mirror of
https://github.com/waynesutton/markdown-site.git
synced 2026-01-12 04:09:14 +00:00
update: blog post image for Team Workflows with Git Version Control post
This commit is contained in:
Wayne Sutton
@@ -19,10 +19,10 @@ Your content is instantly available to browsers, LLMs, and AI agents.. Write mar
|
||||
- **Site Name**: markdown
|
||||
- **Site Title**: markdown sync framework
|
||||
- **Site URL**: https://markdown.fast
|
||||
- **Total Posts**: 14
|
||||
- **Total Posts**: 15
|
||||
- **Total Pages**: 5
|
||||
- **Latest Post**: 2025-12-28
|
||||
- **Last Updated**: 2025-12-28T06:58:00.655Z
|
||||
- **Latest Post**: 2025-12-29
|
||||
- **Last Updated**: 2025-12-29T03:04:12.912Z
|
||||
|
||||
## Tech stack
|
||||
|
||||
|
||||
@@ -1040,6 +1040,7 @@ Replace example content in:
|
||||
| ------------------------------ | -------------------------- |
|
||||
| `content/blog/*.md` | Blog posts |
|
||||
| `content/pages/*.md` | Static pages (About, etc.) |
|
||||
| `content/pages/home.md` | Homepage intro content (slug: `home-intro`, uses blog heading styles) |
|
||||
| `public/images/logo.svg` | Site logo |
|
||||
| `public/images/og-default.svg` | Default social share image |
|
||||
| `public/images/logos/*.svg` | Logo gallery images |
|
||||
|
||||
@@ -1078,6 +1078,8 @@ Pages appear automatically in the navigation when published.
|
||||
|
||||
**Hide pages from navigation:** Set `showInNav: false` in page frontmatter to keep a page published and accessible via direct URL, but hidden from the navigation menu. Useful for pages like `/projects` that you want to link directly but not show in the main nav. Pages with `showInNav: false` remain searchable and available via API endpoints.
|
||||
|
||||
**Home intro content:** Create `content/pages/home.md` (slug: `home-intro`) to sync homepage intro text from markdown. Headings (h1-h6) use blog post styling (`blog-h1` through `blog-h6`) with clickable anchor links. Lists, blockquotes, horizontal rules, and links also use blog styling for consistent typography. Set `textAlign: "left"`, `"center"`, or `"right"` to control alignment. Run `npm run sync` to update homepage text instantly without redeploying. Falls back to `siteConfig.bio` if `home-intro` page not found.
|
||||
|
||||
**Sidebar layout:** Add `layout: "sidebar"` to any post or page frontmatter to enable a docs-style layout with a table of contents sidebar. The sidebar extracts headings (H1, H2, H3) automatically and provides smooth scroll navigation. Only appears if headings exist in the content.
|
||||
|
||||
**Right sidebar:** When enabled in `siteConfig.rightSidebar.enabled`, posts and pages can display a right sidebar containing the CopyPageDropdown at 1135px+ viewport width. Add `rightSidebar: true` to frontmatter to enable. Without this field, pages render normally with CopyPageDropdown in the nav bar. When enabled, CopyPageDropdown moves from the navigation bar to the right sidebar on wide screens. The right sidebar is hidden below 1135px, and CopyPageDropdown returns to the nav bar automatically.
|
||||
|
||||
262
content/blog/team-workflows-git-version-control.md
Normal file
262
content/blog/team-workflows-git-version-control.md
Normal file
@@ -0,0 +1,262 @@
|
||||
---
|
||||
title: "Team Workflows with Git Version Control"
|
||||
description: "How teams collaborate on markdown content using git, sync to shared Convex deployments, and automate production syncs with CI/CD."
|
||||
date: "2025-12-29"
|
||||
slug: "team-workflows-git-version-control"
|
||||
published: true
|
||||
tags: ["git", "convex", "ci-cd", "collaboration", "workflow"]
|
||||
readTime: "6 min read"
|
||||
image: /images/team-sync.png
|
||||
featured: false
|
||||
newsletter: true
|
||||
|
||||
layout: "sidebar"
|
||||
excerpt: "Learn how teams use git for markdown version control, sync to Convex deployments, and automate production workflows."
|
||||
---
|
||||
|
||||
# Team Workflows with Git Version Control
|
||||
|
||||
Teams use this markdown framework by treating markdown files as source code. Content lives in git, gets reviewed via pull requests, and syncs to Convex deployments for instant previews and production updates.
|
||||
|
||||
Here's how it works in practice.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
Each team member clones the repo and sets up their own development environment:
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://github.com/your-org/markdown-site.git
|
||||
cd markdown-site
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Initialize Convex (creates .env.local with dev deployment URL)
|
||||
npx convex dev
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Each developer gets their own Convex dev deployment. The `.env.local` file contains a unique development URL and stays gitignored. This means everyone can preview changes locally without affecting others.
|
||||
|
||||
## Git Version Control
|
||||
|
||||
Markdown files are regular files in your git repository. Teams commit, push, and review content changes like any other code.
|
||||
|
||||
```bash
|
||||
# Team member writes a new post
|
||||
# Creates: content/blog/my-new-post.md
|
||||
|
||||
# Commit to git
|
||||
git add content/blog/my-new-post.md
|
||||
git commit -m "Add new blog post"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
The markdown files in `content/blog/` and `content/pages/` are the source of truth. They live in git, get reviewed via pull requests, and can be rolled back like any codebase.
|
||||
|
||||
This approach gives you:
|
||||
|
||||
- Full version history for all content
|
||||
- Pull request reviews before publishing
|
||||
- Easy rollbacks when needed
|
||||
- Branch-based workflows for drafts
|
||||
- Conflict resolution through git merge tools
|
||||
|
||||
## Syncing to Convex
|
||||
|
||||
The sync script reads markdown files from your local filesystem and uploads them to Convex. Development and production use separate deployments.
|
||||
|
||||
**Development (each developer):**
|
||||
|
||||
```bash
|
||||
# After pulling latest changes from git
|
||||
git pull origin main
|
||||
|
||||
# Sync markdown files to YOUR dev Convex
|
||||
npm run sync
|
||||
```
|
||||
|
||||
**Production (shared deployment):**
|
||||
|
||||
```bash
|
||||
# One person (or CI/CD) syncs to production
|
||||
npm run sync:prod
|
||||
```
|
||||
|
||||
The sync script:
|
||||
|
||||
1. Reads all `.md` files from `content/blog/` and `content/pages/`
|
||||
2. Parses frontmatter using `gray-matter`
|
||||
3. Uploads to Convex via `api.posts.syncPostsPublic` mutation
|
||||
4. Generates static files in `public/raw/` for AI access
|
||||
|
||||
Sync is idempotent. Running it multiple times is safe. The mutation updates posts by slug, so the last sync wins.
|
||||
|
||||
## Environment Files
|
||||
|
||||
Two environment files control which Convex deployment receives your content:
|
||||
|
||||
| File | Purpose | Git Status | Who Has It |
|
||||
| ----------------------- | --------------- | ---------- | ------------------------------- |
|
||||
| `.env.local` | Dev Convex URL | Gitignored | Each developer (different URLs) |
|
||||
| `.env.production.local` | Prod Convex URL | Gitignored | Team shares same URL |
|
||||
|
||||
**Team setup:**
|
||||
|
||||
1. Create production Convex deployment: `npx convex deploy`
|
||||
2. Share the production URL with team
|
||||
3. Each developer creates `.env.production.local`:
|
||||
```
|
||||
VITE_CONVEX_URL=https://your-prod-deployment.convex.cloud
|
||||
```
|
||||
|
||||
Each developer maintains their own dev environment while sharing the production deployment URL.
|
||||
|
||||
## Netlify Deployment
|
||||
|
||||
Netlify connects to your GitHub repo and auto-deploys on every push.
|
||||
|
||||
**Netlify Build Settings:**
|
||||
|
||||
- Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
|
||||
- Publish directory: `dist`
|
||||
|
||||
**Netlify Environment Variables:**
|
||||
|
||||
- `CONVEX_DEPLOY_KEY` - Deploys Convex functions at build time
|
||||
- `VITE_CONVEX_URL` - Production Convex URL (same as `.env.production.local`)
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Team pushes markdown to GitHub
|
||||
2. Netlify auto-builds and deploys
|
||||
3. Site updates automatically (Convex functions deploy, frontend rebuilds)
|
||||
4. Content sync happens separately via `npm run sync:prod`
|
||||
|
||||
Netlify handles frontend deployment. Content sync is a separate step that updates the Convex database.
|
||||
|
||||
## Complete Team Workflow
|
||||
|
||||
Here's what happens when a team member adds a new blog post:
|
||||
|
||||
```bash
|
||||
# 1. Create markdown file locally
|
||||
# content/blog/team-update.md
|
||||
|
||||
# 2. Commit to git
|
||||
git add content/blog/team-update.md
|
||||
git commit -m "Add team update post"
|
||||
git push origin main
|
||||
|
||||
# 3. Sync to dev Convex (for local preview)
|
||||
npm run sync
|
||||
|
||||
# 4. Netlify auto-deploys from GitHub (frontend rebuilds)
|
||||
|
||||
# 5. Sync to production Convex (one person or CI/CD)
|
||||
npm run sync:prod
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
- Markdown file is in git (version controlled)
|
||||
- Dev Convex has the post (local preview)
|
||||
- Production Convex has the post (live site)
|
||||
- Netlify site is rebuilt (frontend code)
|
||||
|
||||
## CI/CD Automation
|
||||
|
||||
You can automate production sync with GitHub Actions. This ensures content updates happen automatically when markdown files change.
|
||||
|
||||
Create `.github/workflows/sync-production.yml`:
|
||||
|
||||
```yaml
|
||||
name: Sync to Production
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "content/**"
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: "18"
|
||||
- run: npm install
|
||||
- run: npm run sync:prod
|
||||
env:
|
||||
VITE_CONVEX_URL: ${{ secrets.PROD_CONVEX_URL }}
|
||||
```
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Add `PROD_CONVEX_URL` to GitHub Secrets (Settings > Secrets and variables > Actions)
|
||||
2. Push the workflow file to your repo
|
||||
3. Every push to `main` that changes files in `content/` triggers a production sync
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- No manual sync step required
|
||||
- Content updates automatically after git push
|
||||
- Consistent production state
|
||||
- Works for all team members
|
||||
|
||||
**Optional: Sync discovery files too**
|
||||
|
||||
If you want to update discovery files (`AGENTS.md`, `llms.txt`) automatically:
|
||||
|
||||
```yaml
|
||||
- run: npm run sync:all:prod
|
||||
env:
|
||||
VITE_CONVEX_URL: ${{ secrets.PROD_CONVEX_URL }}
|
||||
```
|
||||
|
||||
This syncs both content and discovery files in one step.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The system separates concerns across four layers:
|
||||
|
||||
**Git:** Source of truth for markdown files (version controlled)
|
||||
|
||||
**Convex Dev:** Each developer's local preview database
|
||||
|
||||
**Convex Prod:** Shared production database
|
||||
|
||||
**Netlify:** Frontend hosting (auto-deploys from git)
|
||||
|
||||
**Why this works:**
|
||||
|
||||
- Markdown files are plain text (great for git diffs)
|
||||
- Convex sync is instant (no rebuild needed for content changes)
|
||||
- Netlify handles frontend deployment (code changes trigger rebuilds)
|
||||
- Each developer can preview locally without affecting others
|
||||
|
||||
## Team Collaboration Best Practices
|
||||
|
||||
**Content changes:** Edit markdown → commit → push → sync to prod
|
||||
|
||||
**Code changes:** Edit React/TypeScript → commit → push → Netlify auto-deploys
|
||||
|
||||
**Config changes:** Edit `siteConfig.ts` → commit → push → Netlify rebuilds
|
||||
|
||||
**Convex schema changes:** Edit `convex/schema.ts` → commit → `npx convex deploy`
|
||||
|
||||
**Conflict resolution:**
|
||||
|
||||
- Git handles markdown file conflicts (merge/rebase)
|
||||
- Convex sync is idempotent (safe to run multiple times)
|
||||
- Last sync wins for content (Convex mutations update by slug)
|
||||
|
||||
## Summary
|
||||
|
||||
Teams collaborate on markdown content through git version control. Each developer maintains a local dev environment for previews, while production syncs happen automatically via CI/CD or manual commands. Netlify handles frontend deployment separately from content updates.
|
||||
|
||||
The workflow gives you version control, pull request reviews, and instant previews without sacrificing the real-time sync that makes content updates immediate.
|
||||
@@ -167,11 +167,49 @@ Content here...
|
||||
| `newsletter` | No | Override newsletter signup display (`true` to show, `false` to hide) |
|
||||
| `contactForm` | No | Enable contact form on this page |
|
||||
| `showImageAtTop` | No | Set `true` to display the `image` field at the top of the page above the header (default: `false`) |
|
||||
| `textAlign` | No | Text alignment: "left" (default), "center", or "right". Used by `home.md` for home intro alignment |
|
||||
|
||||
**Hide pages from navigation:** Set `showInNav: false` to keep a page published and accessible via direct URL, but hidden from the navigation menu. Pages with `showInNav: false` remain searchable and available via API endpoints. Useful for pages you want to link directly but not show in the main nav.
|
||||
|
||||
**Show image at top:** Add `showImageAtTop: true` to display the `image` field at the top of the post/page above the header. Default behavior: if `showImageAtTop` is not set or `false`, image only used for Open Graph previews and featured card thumbnails.
|
||||
|
||||
**Text alignment:** Use `textAlign` field to control text alignment for page content. Options: `"left"` (default), `"center"`, or `"right"`. Used by `home.md` to control home intro alignment.
|
||||
|
||||
### Home intro content
|
||||
|
||||
The homepage intro text can be synced from markdown via `content/pages/home.md` (slug: `home-intro`). This allows you to update homepage text without redeploying.
|
||||
|
||||
**Create home intro:**
|
||||
|
||||
1. Create `content/pages/home.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Home Intro"
|
||||
slug: "home-intro"
|
||||
published: true
|
||||
showInNav: false
|
||||
order: -1
|
||||
textAlign: "left"
|
||||
---
|
||||
|
||||
Your homepage intro text here.
|
||||
|
||||
## Features
|
||||
|
||||
**Feature one** — Description here.
|
||||
|
||||
**Feature two** — Description here.
|
||||
```
|
||||
|
||||
2. Run `npm run sync` to sync to Convex
|
||||
|
||||
3. Content appears on homepage instantly (no rebuild needed)
|
||||
|
||||
**Blog heading styles:** Headings (h1-h6) in home intro content use the same styling as blog posts (`blog-h1` through `blog-h6` classes). Each heading gets an automatic ID and a clickable anchor link (#) that appears on hover. Lists, blockquotes, horizontal rules, and links also use blog styling classes for consistent typography.
|
||||
|
||||
**Fallback:** If `home-intro` page is not found, the homepage falls back to `siteConfig.bio` text.
|
||||
|
||||
### Sidebar layout
|
||||
|
||||
Posts and pages can use a docs-style layout with a table of contents sidebar. Add `layout: "sidebar"` to the frontmatter:
|
||||
|
||||
2
files.md
2
files.md
@@ -169,7 +169,7 @@ Markdown files with frontmatter for blog posts. Each file becomes a blog post.
|
||||
Markdown files for static pages like About, Projects, Contact, Changelog.
|
||||
|
||||
**Special pages:**
|
||||
- `home.md` (slug: `home-intro`): Homepage intro/bio content. Set `showInNav: false` to hide from navigation. Content syncs with `npm run sync` and displays on the homepage without redeploy.
|
||||
- `home.md` (slug: `home-intro`): Homepage intro/bio content. Set `showInNav: false` to hide from navigation. Content syncs with `npm run sync` and displays on the homepage without redeploy. Headings (h1-h6) use blog post styling (`blog-h1` through `blog-h6`) with clickable anchor links. Lists, blockquotes, horizontal rules, and links also use blog styling classes for consistent typography.
|
||||
|
||||
| Field | Description |
|
||||
| --------------- | ----------------------------------------------------------------------- |
|
||||
|
||||
BIN
public/images/team-sync.png
Normal file
BIN
public/images/team-sync.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 422 KiB |
@@ -1,6 +1,6 @@
|
||||
# llms.txt - Information for AI assistants and LLMs
|
||||
# Learn more: https://llmstxt.org/
|
||||
# Last updated: 2025-12-28T06:58:00.656Z
|
||||
# Last updated: 2025-12-29T03:04:12.913Z
|
||||
|
||||
> Your content is instantly available to browsers, LLMs, and AI agents.
|
||||
|
||||
@@ -9,8 +9,8 @@
|
||||
- URL: https://markdown.fast
|
||||
- Description: Your content is instantly available to browsers, LLMs, and AI agents. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex and Netlify.
|
||||
- Topics: Markdown, Convex, React, TypeScript, Netlify, Open Source, AI, LLM, AEO, GEO
|
||||
- Total Posts: 14
|
||||
- Latest Post: 2025-12-28
|
||||
- Total Posts: 15
|
||||
- Latest Post: 2025-12-29
|
||||
- GitHub: https://github.com/waynesutton/markdown-site
|
||||
|
||||
# API Endpoints
|
||||
|
||||
@@ -8,6 +8,21 @@ Date: 2025-12-29
|
||||
All notable changes to this project.
|
||||
|
||||
|
||||
## v1.41.0
|
||||
|
||||
Released December 28, 2025
|
||||
|
||||
**Blog heading styles for home intro content**
|
||||
|
||||
- Headings (h1-h6) in `content/pages/home.md` now use same styling as blog posts
|
||||
- Classes: `blog-h1`, `blog-h2`, `blog-h3`, `blog-h4`, `blog-h5`, `blog-h6`
|
||||
- Clickable anchor links (#) appear on hover for each heading
|
||||
- Automatic ID generation from heading text for anchor navigation
|
||||
- Additional blog styling for lists, blockquotes, horizontal rules, and links
|
||||
- Home intro headings now match blog post typography and spacing
|
||||
|
||||
Updated files: `src/pages/Home.tsx`
|
||||
|
||||
## v1.39.0
|
||||
|
||||
Released December 28, 2025
|
||||
|
||||
@@ -163,11 +163,49 @@ Content here...
|
||||
| `newsletter` | No | Override newsletter signup display (`true` to show, `false` to hide) |
|
||||
| `contactForm` | No | Enable contact form on this page |
|
||||
| `showImageAtTop` | No | Set `true` to display the `image` field at the top of the page above the header (default: `false`) |
|
||||
| `textAlign` | No | Text alignment: "left" (default), "center", or "right". Used by `home.md` for home intro alignment |
|
||||
|
||||
**Hide pages from navigation:** Set `showInNav: false` to keep a page published and accessible via direct URL, but hidden from the navigation menu. Pages with `showInNav: false` remain searchable and available via API endpoints. Useful for pages you want to link directly but not show in the main nav.
|
||||
|
||||
**Show image at top:** Add `showImageAtTop: true` to display the `image` field at the top of the post/page above the header. Default behavior: if `showImageAtTop` is not set or `false`, image only used for Open Graph previews and featured card thumbnails.
|
||||
|
||||
**Text alignment:** Use `textAlign` field to control text alignment for page content. Options: `"left"` (default), `"center"`, or `"right"`. Used by `home.md` to control home intro alignment.
|
||||
|
||||
### Home intro content
|
||||
|
||||
The homepage intro text can be synced from markdown via `content/pages/home.md` (slug: `home-intro`). This allows you to update homepage text without redeploying.
|
||||
|
||||
**Create home intro:**
|
||||
|
||||
1. Create `content/pages/home.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Home Intro"
|
||||
slug: "home-intro"
|
||||
published: true
|
||||
showInNav: false
|
||||
order: -1
|
||||
textAlign: "left"
|
||||
---
|
||||
|
||||
Your homepage intro text here.
|
||||
|
||||
## Features
|
||||
|
||||
**Feature one** — Description here.
|
||||
|
||||
**Feature two** — Description here.
|
||||
```
|
||||
|
||||
2. Run `npm run sync` to sync to Convex
|
||||
|
||||
3. Content appears on homepage instantly (no rebuild needed)
|
||||
|
||||
**Blog heading styles:** Headings (h1-h6) in home intro content use the same styling as blog posts (`blog-h1` through `blog-h6` classes). Each heading gets an automatic ID and a clickable anchor link (#) that appears on hover. Lists, blockquotes, horizontal rules, and links also use blog styling classes for consistent typography.
|
||||
|
||||
**Fallback:** If `home-intro` page is not found, the homepage falls back to `siteConfig.bio` text.
|
||||
|
||||
### Sidebar layout
|
||||
|
||||
Posts and pages can use a docs-style layout with a table of contents sidebar. Add `layout: "sidebar"` to the frontmatter:
|
||||
|
||||
@@ -2,8 +2,10 @@
|
||||
|
||||
This is the homepage index of all published content.
|
||||
|
||||
## Blog Posts (14)
|
||||
## Blog Posts (15)
|
||||
|
||||
- **[Team Workflows with Git Version Control](/raw/team-workflows-git-version-control.md)** - How teams collaborate on markdown content using git, sync to shared Convex deployments, and automate production syncs with CI/CD.
|
||||
- Date: 2025-12-29 | Reading time: 6 min read | Tags: git, convex, ci-cd, collaboration, workflow
|
||||
- **[How to Use the MCP Server with MarkDown Sync](/raw/how-to-use-mcp-server.md)** - Guide to using the HTTP-based Model Context Protocol(MCP) server at www.markdown.fast/mcp with Cursor and other AI tools
|
||||
- Date: 2025-12-28 | Reading time: 5 min read | Tags: mcp, cursor, ai, tutorial, netlify
|
||||
- **[How to use AgentMail with Markdown Sync](/raw/how-to-use-agentmail.md)** - Complete guide to setting up AgentMail for newsletters and contact forms in your markdown blog
|
||||
@@ -45,6 +47,6 @@ This is the homepage index of all published content.
|
||||
|
||||
---
|
||||
|
||||
**Total Content:** 14 posts, 7 pages
|
||||
**Total Content:** 15 posts, 7 pages
|
||||
|
||||
All content is available as raw markdown files at `/raw/{slug}.md`
|
||||
|
||||
@@ -1071,6 +1071,8 @@ Pages appear automatically in the navigation when published.
|
||||
|
||||
**Hide pages from navigation:** Set `showInNav: false` in page frontmatter to keep a page published and accessible via direct URL, but hidden from the navigation menu. Useful for pages like `/projects` that you want to link directly but not show in the main nav. Pages with `showInNav: false` remain searchable and available via API endpoints.
|
||||
|
||||
**Home intro content:** Create `content/pages/home.md` (slug: `home-intro`) to sync homepage intro text from markdown. Headings (h1-h6) use blog post styling (`blog-h1` through `blog-h6`) with clickable anchor links. Lists, blockquotes, horizontal rules, and links also use blog styling for consistent typography. Set `textAlign: "left"`, `"center"`, or `"right"` to control alignment. Run `npm run sync` to update homepage text instantly without redeploying. Falls back to `siteConfig.bio` if `home-intro` page not found.
|
||||
|
||||
**Sidebar layout:** Add `layout: "sidebar"` to any post or page frontmatter to enable a docs-style layout with a table of contents sidebar. The sidebar extracts headings (H1, H2, H3) automatically and provides smooth scroll navigation. Only appears if headings exist in the content.
|
||||
|
||||
**Right sidebar:** When enabled in `siteConfig.rightSidebar.enabled`, posts and pages can display a right sidebar containing the CopyPageDropdown at 1135px+ viewport width. Add `rightSidebar: true` to frontmatter to enable. Without this field, pages render normally with CopyPageDropdown in the nav bar. When enabled, CopyPageDropdown moves from the navigation bar to the right sidebar on wide screens. The right sidebar is hidden below 1135px, and CopyPageDropdown returns to the nav bar automatically.
|
||||
|
||||
257
public/raw/team-workflows-git-version-control.md
Normal file
257
public/raw/team-workflows-git-version-control.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# Team Workflows with Git Version Control
|
||||
|
||||
> How teams collaborate on markdown content using git, sync to shared Convex deployments, and automate production syncs with CI/CD.
|
||||
|
||||
---
|
||||
Type: post
|
||||
Date: 2025-12-29
|
||||
Reading time: 6 min read
|
||||
Tags: git, convex, ci-cd, collaboration, workflow
|
||||
---
|
||||
|
||||
# Team Workflows with Git Version Control
|
||||
|
||||
Teams use this markdown framework by treating markdown files as source code. Content lives in git, gets reviewed via pull requests, and syncs to Convex deployments for instant previews and production updates.
|
||||
|
||||
Here's how it works in practice.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
Each team member clones the repo and sets up their own development environment:
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://github.com/your-org/markdown-site.git
|
||||
cd markdown-site
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Initialize Convex (creates .env.local with dev deployment URL)
|
||||
npx convex dev
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Each developer gets their own Convex dev deployment. The `.env.local` file contains a unique development URL and stays gitignored. This means everyone can preview changes locally without affecting others.
|
||||
|
||||
## Git Version Control
|
||||
|
||||
Markdown files are regular files in your git repository. Teams commit, push, and review content changes like any other code.
|
||||
|
||||
```bash
|
||||
# Team member writes a new post
|
||||
# Creates: content/blog/my-new-post.md
|
||||
|
||||
# Commit to git
|
||||
git add content/blog/my-new-post.md
|
||||
git commit -m "Add new blog post"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
The markdown files in `content/blog/` and `content/pages/` are the source of truth. They live in git, get reviewed via pull requests, and can be rolled back like any codebase.
|
||||
|
||||
This approach gives you:
|
||||
|
||||
- Full version history for all content
|
||||
- Pull request reviews before publishing
|
||||
- Easy rollbacks when needed
|
||||
- Branch-based workflows for drafts
|
||||
- Conflict resolution through git merge tools
|
||||
|
||||
## Syncing to Convex
|
||||
|
||||
The sync script reads markdown files from your local filesystem and uploads them to Convex. Development and production use separate deployments.
|
||||
|
||||
**Development (each developer):**
|
||||
|
||||
```bash
|
||||
# After pulling latest changes from git
|
||||
git pull origin main
|
||||
|
||||
# Sync markdown files to YOUR dev Convex
|
||||
npm run sync
|
||||
```
|
||||
|
||||
**Production (shared deployment):**
|
||||
|
||||
```bash
|
||||
# One person (or CI/CD) syncs to production
|
||||
npm run sync:prod
|
||||
```
|
||||
|
||||
The sync script:
|
||||
|
||||
1. Reads all `.md` files from `content/blog/` and `content/pages/`
|
||||
2. Parses frontmatter using `gray-matter`
|
||||
3. Uploads to Convex via `api.posts.syncPostsPublic` mutation
|
||||
4. Generates static files in `public/raw/` for AI access
|
||||
|
||||
Sync is idempotent. Running it multiple times is safe. The mutation updates posts by slug, so the last sync wins.
|
||||
|
||||
## Environment Files
|
||||
|
||||
Two environment files control which Convex deployment receives your content:
|
||||
|
||||
| File | Purpose | Git Status | Who Has It |
|
||||
| ----------------------- | --------------- | ---------- | ------------------------------- |
|
||||
| `.env.local` | Dev Convex URL | Gitignored | Each developer (different URLs) |
|
||||
| `.env.production.local` | Prod Convex URL | Gitignored | Team shares same URL |
|
||||
|
||||
**Team setup:**
|
||||
|
||||
1. Create production Convex deployment: `npx convex deploy`
|
||||
2. Share the production URL with team
|
||||
3. Each developer creates `.env.production.local`:
|
||||
```
|
||||
VITE_CONVEX_URL=https://your-prod-deployment.convex.cloud
|
||||
```
|
||||
|
||||
Each developer maintains their own dev environment while sharing the production deployment URL.
|
||||
|
||||
## Netlify Deployment
|
||||
|
||||
Netlify connects to your GitHub repo and auto-deploys on every push.
|
||||
|
||||
**Netlify Build Settings:**
|
||||
|
||||
- Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
|
||||
- Publish directory: `dist`
|
||||
|
||||
**Netlify Environment Variables:**
|
||||
|
||||
- `CONVEX_DEPLOY_KEY` - Deploys Convex functions at build time
|
||||
- `VITE_CONVEX_URL` - Production Convex URL (same as `.env.production.local`)
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Team pushes markdown to GitHub
|
||||
2. Netlify auto-builds and deploys
|
||||
3. Site updates automatically (Convex functions deploy, frontend rebuilds)
|
||||
4. Content sync happens separately via `npm run sync:prod`
|
||||
|
||||
Netlify handles frontend deployment. Content sync is a separate step that updates the Convex database.
|
||||
|
||||
## Complete Team Workflow
|
||||
|
||||
Here's what happens when a team member adds a new blog post:
|
||||
|
||||
```bash
|
||||
# 1. Create markdown file locally
|
||||
# content/blog/team-update.md
|
||||
|
||||
# 2. Commit to git
|
||||
git add content/blog/team-update.md
|
||||
git commit -m "Add team update post"
|
||||
git push origin main
|
||||
|
||||
# 3. Sync to dev Convex (for local preview)
|
||||
npm run sync
|
||||
|
||||
# 4. Netlify auto-deploys from GitHub (frontend rebuilds)
|
||||
|
||||
# 5. Sync to production Convex (one person or CI/CD)
|
||||
npm run sync:prod
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
- Markdown file is in git (version controlled)
|
||||
- Dev Convex has the post (local preview)
|
||||
- Production Convex has the post (live site)
|
||||
- Netlify site is rebuilt (frontend code)
|
||||
|
||||
## CI/CD Automation
|
||||
|
||||
You can automate production sync with GitHub Actions. This ensures content updates happen automatically when markdown files change.
|
||||
|
||||
Create `.github/workflows/sync-production.yml`:
|
||||
|
||||
```yaml
|
||||
name: Sync to Production
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- "content/**"
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: "18"
|
||||
- run: npm install
|
||||
- run: npm run sync:prod
|
||||
env:
|
||||
VITE_CONVEX_URL: ${{ secrets.PROD_CONVEX_URL }}
|
||||
```
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Add `PROD_CONVEX_URL` to GitHub Secrets (Settings > Secrets and variables > Actions)
|
||||
2. Push the workflow file to your repo
|
||||
3. Every push to `main` that changes files in `content/` triggers a production sync
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- No manual sync step required
|
||||
- Content updates automatically after git push
|
||||
- Consistent production state
|
||||
- Works for all team members
|
||||
|
||||
**Optional: Sync discovery files too**
|
||||
|
||||
If you want to update discovery files (`AGENTS.md`, `llms.txt`) automatically:
|
||||
|
||||
```yaml
|
||||
- run: npm run sync:all:prod
|
||||
env:
|
||||
VITE_CONVEX_URL: ${{ secrets.PROD_CONVEX_URL }}
|
||||
```
|
||||
|
||||
This syncs both content and discovery files in one step.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The system separates concerns across four layers:
|
||||
|
||||
**Git:** Source of truth for markdown files (version controlled)
|
||||
|
||||
**Convex Dev:** Each developer's local preview database
|
||||
|
||||
**Convex Prod:** Shared production database
|
||||
|
||||
**Netlify:** Frontend hosting (auto-deploys from git)
|
||||
|
||||
**Why this works:**
|
||||
|
||||
- Markdown files are plain text (great for git diffs)
|
||||
- Convex sync is instant (no rebuild needed for content changes)
|
||||
- Netlify handles frontend deployment (code changes trigger rebuilds)
|
||||
- Each developer can preview locally without affecting others
|
||||
|
||||
## Team Collaboration Best Practices
|
||||
|
||||
**Content changes:** Edit markdown → commit → push → sync to prod
|
||||
|
||||
**Code changes:** Edit React/TypeScript → commit → push → Netlify auto-deploys
|
||||
|
||||
**Config changes:** Edit `siteConfig.ts` → commit → push → Netlify rebuilds
|
||||
|
||||
**Convex schema changes:** Edit `convex/schema.ts` → commit → `npx convex deploy`
|
||||
|
||||
**Conflict resolution:**
|
||||
|
||||
- Git handles markdown file conflicts (merge/rebase)
|
||||
- Convex sync is idempotent (safe to run multiple times)
|
||||
- Last sync wins for content (Convex mutations update by slug)
|
||||
|
||||
## Summary
|
||||
|
||||
Teams collaborate on markdown content through git version control. Each developer maintains a local dev environment for previews, while production syncs happen automatically via CI/CD or manual commands. Netlify handles frontend deployment separately from content updates.
|
||||
|
||||
The workflow gives you version control, pull request reviews, and instant previews without sacrificing the real-time sync that makes content updates immediate.
|
||||
Reference in New Issue
Block a user