markdown "sync" framework

An open-source publishing framework built for AI agents and developers to ship websites, docs, or blogs. Write markdown, sync from the terminal. Your content is instantly available to browsers, LLMs, and AI agents. Built on Convex.

Write markdown locally, run npm run sync (dev) or npm run sync:prod (production), and content appears instantly across all connected browsers. Built with React, Convex, and Vite. Optimized for AEO, GEO, and LLM discovery.

How publishing works: Write posts in markdown, run npm run sync for development or npm run sync:prod for production, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so all connected browsers update automatically.

Sync commands:

Sync command scripts are located in scripts/ (sync-posts.ts, sync-discovery-files.ts).

Development:

• npm run sync - Sync markdown content
• npm run sync:discovery - Update discovery files (AGENTS.md, llms.txt)
• npm run sync:all - Sync content + discovery files together

Production:

• npm run sync:prod - Sync markdown content
• npm run sync:discovery:prod - Update discovery files
• npm run sync:all:prod - Sync content + discovery files together

Export dashboard content:

• npm run export:db - Export dashboard posts/pages to content folders (development)
• npm run export:db:prod - Export dashboard posts/pages (production)

How versioning works: Markdown files live in content/blog/ and content/pages/. These are regular files in your git repo. Commit changes, review diffs, roll back like any codebase. The sync command pushes content to Convex.

# Edit, commit, sync
git add content/blog/my-post.md
git commit -m "Update post"
npm run sync        # dev
npm run sync:prod   # production

Documentation

Full documentation is available at markdown.fast/docs

Guides

• Setup Guide - Complete fork and deployment guide
• Fork Configuration Guide - Automated or manual fork setup
• Dashboard Guide - Content management and site configuration
• MCP Server - AI tool integration for Cursor and Claude Desktop
• AgentMail Setup - Newsletter and contact form integration
• WorkOS Setup - Legacy authentication mode (use auth.mode: "workos" in siteConfig)

AI Development Tools

The project includes documentation optimized for AI coding assistants:

• CLAUDE.md - Project instructions for Claude Code CLI with workflows, commands, and conventions
• AGENTS.md - General AI agent instructions for understanding the codebase structure
• llms.txt - AI agent discovery file at /llms.txt
• .cursor/skills/ - Focused skill documentation:
  • frontmatter.md - Complete frontmatter syntax and all field options
  • convex.md - Convex patterns specific to this app
  • sync.md - How sync commands work and content flow
  • robel-auth/SKILL.md - @robelest/convex-auth integration patterns
  • convex-self-hosting/SKILL.md - Convex static self hosting setup

These files are automatically updated during npm run sync:discovery with current site statistics.

Features

See the full feature list on the About page.

Key features include real-time sync, four theme options, full-text search, analytics dashboard, MCP server for AI tools, newsletter integration, and SEO optimization with RSS feeds, sitemaps, and structured data.

Fork Configuration

After forking, run the automated configuration:

cp fork-config.json.example fork-config.json
# Edit fork-config.json with your site info
npm run configure

The fork-config.json.example includes all configurable options:

• Site settings: name, title, description, URL, domain
• Auth mode: convex-auth (default), workos (legacy), or none (local dev)
• Hosting mode: convex-self-hosted (default) or netlify (legacy)
• Media provider: convex (default), convexfs, or r2
• Creator info: name, social links, bio
• Feature toggles: newsletter, dashboard, stats page, AI chat, etc.

See the Fork Configuration Guide for detailed instructions and FORK_CONFIG.md for the complete reference.

One click setup paths

Use either path to get your own clone + Convex backend quickly:

1. GitHub template flow:
   • Click Use this template
   • Clone your new repo
   • Run npm install, npx convex dev --once, npm run sync, npm run deploy
2. CLI flow:
   • Run npx create-markdown-sync my-site
   • Follow prompts and open your site when setup finishes
3. Website setup guide:
   • Follow markdown.fast/fork-configuration-guide

Getting Started

Prerequisites

• Node.js 18 or higher
• A Convex account

Setup

1. Install dependencies:

npm install

2. Initialize Convex:

npx convex dev

This will create your Convex project and generate the .env.local file.

3. Start the development server:

npm run dev

4. Open http://localhost:5173

Validation scripts

Verify your environment and deployment:

npm run validate:env       # Check local env readiness
npm run validate:env:prod  # Check production env
npm run verify:deploy      # Verify deployed endpoints
npm run verify:deploy:prod # Verify production endpoints

Deployment

Default deployment (Convex self hosted)

npx @convex-dev/self-hosting setup
npx convex dev --once
npm run deploy

npm run deploy runs the full one-shot flow through @convex-dev/self-hosting and builds for the target Convex deployment automatically.

Custom domain setup

• Set your Convex custom domain to markdown.fast in the Convex dashboard.
• Point DNS from Cloudflare to Convex using the records Convex provides.
• Set VITE_CONVEX_SITE_URL (or VITE_SITE_URL) for frontend HTTP route overrides.
• Keep VITE_CONVEX_URL for the Convex client URL.

Legacy deployment (Netlify)

1. Deploy Convex functions to production:

npx convex deploy

2. Connect your repository to Netlify
3. Configure build settings:
   • Build command: npm ci --include=dev && npx convex deploy --cmd 'npm run build'
   • Publish directory: dist
4. Add environment variables in Netlify dashboard:
   • CONVEX_DEPLOY_KEY - Generate from Convex Dashboard > Project Settings > Deploy Key
   • VITE_CONVEX_URL - Your production Convex URL

For detailed setup, see the Convex Netlify Deployment Guide and netlify-deploy-fix.md for troubleshooting.

Auth modes

Default mode:

• auth.mode: "convex-auth" - GitHub OAuth via @robelest/convex-auth
• hosting.mode: "convex-self-hosted" - Static assets via @convex-dev/self-hosting
• media.provider: "convex" - Direct Convex storage

Legacy mode:

• auth.mode: "workos" for WorkOS AuthKit compatibility
• hosting.mode: "netlify" for Netlify deployment
• media.provider: "convexfs" or media.provider: "r2" for optional media backends

Local fallback mode:

• auth.mode: "none" for local development only

Dashboard admin access

Dashboard access is server enforced when dashboard.requireAuth: true.

Setting up GitHub OAuth (required for fork users)

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set Homepage URL to your frontend URL (e.g., http://localhost:5173)
4. Set Authorization callback URL to: https://<your-deployment>.convex.site/api/auth/callback/github
5. Copy Client ID and Client Secret

Set environment variables

npx convex env set AUTH_GITHUB_ID "your-github-client-id"
npx convex env set AUTH_GITHUB_SECRET "your-github-client-secret"
npx convex env set DASHBOARD_ADMIN_BOOTSTRAP_KEY "choose-a-long-random-secret"

Bootstrap your admin

npx convex run authAdmin:bootstrapDashboardAdmin \
  '{"bootstrapKey":"choose-a-long-random-secret","email":"your-email@example.com"}'

Grant additional admins

npx convex run authAdmin:grantDashboardAdmin '{"email":"colleague@example.com"}'

Optional strict email gate

npx convex env set DASHBOARD_PRIMARY_ADMIN_EMAIL "your-email@example.com"

See FORK_CONFIG.md for complete admin setup instructions.

Tech Stack

React 18, TypeScript, Vite, Convex (self hosted), @robelest/convex-auth, @convex-dev/self-hosting. Legacy mode: Netlify + WorkOS.

Recent Updates (v2.21.0)

• Convex self hosting as default deployment via @convex-dev/self-hosting
• @robelest/convex-auth as default authentication with GitHub OAuth
• Server-side dashboard admin authorization with dashboardAdmins table
• Multi-mode architecture supporting convex-auth, workos, and none auth modes
• Lightweight rich text editor replacing Quill (zero vulnerabilities)
• Validation scripts for environment and deployment verification
• One-click deploy improvements with updated fork configuration

See the Changelog for the full version history.

Source

Fork this project: github.com/waynesutton/markdown-site

License

This project is licensed under the MIT License.