markdown“同步”框架

一个开源的发布框架，专为AI智能体和开发者打造，用于快速部署网站、文档或博客。只需编写Markdown文件，通过终端即可完成同步。您的内容会立即对浏览器、大型语言模型（LLM）以及AI智能体开放访问。基于Convex构建。

您可以在本地编写Markdown文件，运行npm run sync（开发环境）或npm run sync:prod（生产环境），内容便会即时出现在所有已连接的浏览器中。该框架使用React、Convex和Vite构建，针对AEO、GEO以及LLM发现进行了优化。

发布流程： 您只需以Markdown格式撰写文章，然后在开发环境中运行npm run sync，或在生产环境中运行npm run sync:prod，文章就会立即显示在您的线上站点上。无需重新构建或重新部署。Convex负责实时数据同步，因此所有已连接的浏览器都会自动更新。

同步命令：

同步命令脚本位于scripts/目录下（sync-posts.ts、sync-discovery-files.ts）。

开发环境：

• npm run sync - 同步Markdown内容
• npm run sync:discovery - 更新发现文件（AGENTS.md、llms.txt）
• npm run sync:all - 同步内容与发现文件

生产环境：

• npm run sync:prod - 同步Markdown内容
• npm run sync:discovery:prod - 更新发现文件
• npm run sync:all:prod - 同步内容与发现文件

导出仪表盘内容：

• npm run export:db - 将仪表盘中的帖子/页面导出到内容文件夹（开发环境）
• npm run export:db:prod - 导出仪表盘中的帖子/页面（生产环境）

版本控制机制： Markdown文件存储在content/blog/和content/pages/目录中。这些文件是Git仓库中的普通文件。您可以提交更改、查看差异，并像管理任何代码库一样进行回滚。同步命令会将内容推送到Convex数据库。

# 编辑、提交、同步
git add content/blog/my-post.md
git commit -m "更新文章"
npm run sync        # 开发环境
npm run sync:prod   # 生产环境

文档

完整的文档可在**markdown.fast/docs**查阅。

指南

• 设置指南 - 完整的fork与部署指南
• Fork配置指南 - 自动化或手动的fork配置方法
• 仪表盘指南 - 内容管理和站点配置
• MCP服务器 - 用于Cursor和Claude Desktop的AI工具集成
• AgentMail设置 - 邮件列表与联系表单集成
• WorkOS设置 - 旧版认证模式（在siteConfig中使用auth.mode: "workos"）

AI开发工具

该项目包含专为AI编码助手优化的文档：

• CLAUDE.md - Claude Code CLI的工作流、命令及规范说明
• AGENTS.md - 通用AI智能体指南，帮助理解代码库结构
• llms.txt - 存放于/llms.txt的AI智能体发现文件
• .cursor/skills/ - 专注于技能的文档：
  • frontmatter.md - 完整的Frontmatter语法及所有字段选项
  • convex.md - 本应用特有的Convex模式
  • sync.md - 同步命令的工作原理及内容流转
  • robel-auth/SKILL.md - @robelest/convex-auth集成模式
  • convex-self-hosting/SKILL.md - Convex静态自托管设置

这些文件会在运行npm run sync:discovery时，根据当前站点统计数据自动更新。

特性

完整特性列表请参见关于页面。

主要特性包括实时同步、四种主题选择、全文搜索、分析仪表盘、用于AI工具的MCP服务器、邮件列表集成，以及通过RSS订阅、站点地图和结构化数据实现的SEO优化。

Fork配置

Fork后，请运行自动化配置：

cp fork-config.json.example fork-config.json
# 编辑fork-config.json以填写您的站点信息
npm run configure

fork-config.json.example包含了所有可配置选项：

• 站点设置：名称、标题、描述、URL、域名
• 认证模式：convex-auth（默认）、workos（旧版）或none（本地开发）
• 托管模式：convex-self-hosted（默认）或netlify（旧版）
• 媒体提供商：convex（默认）、convexfs或r2
• 创作者信息：姓名、社交链接、简介
• 功能开关：邮件列表、仪表盘、统计页面、AI聊天等

详细说明请参阅Fork配置指南，完整参考请见FORK_CONFIG.md。

一键搭建路径

您可以通过以下任一方式快速获得自己的克隆项目及Convex后端：

1. GitHub模板流程：
   • 点击使用此模板
   • 克隆新仓库
   • 运行npm install、npx convex dev --once、npm run sync、npm run deploy
2. CLI流程：
   • 运行npx create-markdown-sync my-site
   • 按照提示操作，设置完成后即可打开您的站点
3. 网站搭建指南：
   • 参阅markdown.fast/fork-configuration-guide

快速入门

前提条件

• Node.js 18或更高版本
• 一个Convex账户

设置步骤

1. 安装依赖：

npm install

2. 初始化Convex：

npx convex dev

这将创建您的Convex项目并生成.env.local文件。

如果您使用WSL 2且浏览器认证无法自动打开，请执行以下命令：

npx convex login --no-open --login-flow paste
npx convex dev --once

随后启动正常监听模式：

npx convex dev

3. 启动开发服务器：

npm run dev

4. 打开http://localhost:5173

验证脚本

验证您的环境与部署情况：

npm run validate:env       # 检查本地环境是否就绪
npm run validate:env:prod  # 检查生产环境
npm run verify:deploy      # 验证已部署的端点
npm run verify:deploy:prod # 验证生产环境的端点

部署

默认部署（Convex自托管）

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

npm run deploy会通过@convex-dev/self-hosting执行一次性流程，并自动为目标Convex部署构建。

自定义域名设置

• 在Convex仪表盘中将您的自定义域名设置为markdown.fast。
• 使用Convex提供的记录，将Cloudflare的DNS指向Convex。
• 设置VITE_CONVEX_SITE_URL（或VITE_SITE_URL）以覆盖前端HTTP路由。
• 保持VITE_CONVEX_URL作为Convex客户端的URL。

遗留部署（Netlify）

1. 将 Convex 函数部署到生产环境：

npx convex deploy

2. 将您的仓库连接到 Netlify。
3. 配置构建设置：
   • 构建命令：npm ci --include=dev && npx convex deploy --cmd 'npm run build'
   • 发布目录：dist
4. 在 Netlify 控制台中添加环境变量：
   • CONVEX_DEPLOY_KEY — 从 Convex 控制台 > 项目设置 > 部署密钥生成。
   • VITE_CONVEX_URL — 您的生产 Convex URL。

有关详细设置，请参阅 Convex Netlify 部署指南 和 netlify-deploy-fix.md 以进行故障排除。

认证模式

默认模式：

• auth.mode: "convex-auth" — 通过 @robelest/convex-auth 使用 GitHub OAuth。
• hosting.mode: "convex-self-hosted" — 通过 @convex-dev/self-hosting 提供静态资源。
• media.provider: "convex" — 直接使用 Convex 存储。

遗留模式：

• auth.mode: "workos" 用于 WorkOS AuthKit 兼容性。
• hosting.mode: "netlify" 用于 Netlify 部署。
• media.provider: "convexfs" 或 media.provider: "r2" 作为可选的媒体后端。

本地回退模式：

• auth.mode: "none" 仅用于本地开发。

仪表板管理员访问权限

当 dashboard.requireAuth: true 时，仪表板访问权限由服务器强制执行。

设置 GitHub OAuth（对分叉用户必需）

1. 前往 GitHub 开发者设置。
2. 创建一个新的 OAuth 应用程序。
3. 将主页 URL 设置为您前端的 URL（例如 http://localhost:5173）。
4. 将授权回调 URL 设置为：https://<your-deployment>.convex.site/api/auth/callback/github。
5. 复制客户端 ID 和客户端密钥。

设置环境变量

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"

启动您的管理员账户

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

授予其他管理员权限

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

可选的严格邮箱准入

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

完整管理员设置说明请参阅 FORK_CONFIG.md。

技术栈

React 18、TypeScript、Vite、Convex（自托管）、@robelest/convex-auth、@convex-dev/self-hosting。遗留模式：Netlify + WorkOS。

最新更新（v2.21.0）

• 默认部署方式改为 Convex 自托管，通过 @convex-dev/self-hosting 实现。
• 默认认证方式为 @robelest/convex-auth，支持 GitHub OAuth。
• 引入了基于 dashboardAdmins 表的 服务器端仪表板管理员 权限控制。
• 支持多模式架构，涵盖 convex-auth、workos 和 none 认证模式。
• 替换 Quill 的 轻量级富文本编辑器，无任何已知漏洞。
• 添加了用于验证环境和部署的 验证脚本。
• 更新了分叉配置，改进了 一键部署功能。

完整版本历史请参阅 Changelog。

源代码

您可以分叉该项目：github.com/waynesutton/markdown-site

许可证

本项目采用 MIT 许可证。

markdown-site 快速上手指南

markdown-site 是一个专为 AI 代理和开发者设计的开源发布框架。它允许你本地编写 Markdown 文件，通过终端命令同步内容，无需重新构建或部署即可实时更新网站、文档或博客。该框架基于 React、Convex 和 Vite 构建，针对 AEO（答案引擎优化）、GEO 和 LLM 发现进行了优化。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 版本 18 或更高。
• Convex 账户: 需要注册一个 Convex 账户用于后端数据同步和托管。
• 包管理器: 推荐使用 npm。

国内开发者提示：如果安装依赖速度较慢，可临时使用淘宝镜像源： npm config set registry https://registry.npmmirror.com

安装步骤

1. 获取项目代码

你可以选择以下两种方式之一初始化项目：

方式 A：使用 CLI 工具（推荐）

npx create-markdown-sync my-site
cd my-site

跟随提示完成配置，设置完成后会自动打开浏览器。

方式 B：手动 Fork 与克隆

1. 点击 GitHub 仓库页面的 "Use this template" 创建你的仓库。
2. 克隆新仓库到本地：

   git clone <你的仓库地址>
   cd <项目目录>
   

3. 复制并编辑配置文件：

   cp fork-config.json.example fork-config.json
   # 使用编辑器修改 fork-config.json，填入你的站点名称、域名等信息
   npm run configure
   

2. 安装依赖

npm install

3. 初始化 Convex 后端

运行以下命令将创建你的 Convex 项目并生成 .env.local 文件：

npx convex dev

注意：如果在 WSL 2 环境中浏览器认证窗口未自动弹出，请运行：

npx convex login --no-open --login-flow paste
npx convex dev --once

随后再运行 npx convex dev 进入正常监听模式。

基本使用

1. 启动开发服务器

在终端运行：

npm run dev

访问 http://localhost:5173 查看你的网站。

2. 发布内容（核心工作流）

markdown-site 的核心在于“写即所得”。你只需在本地编辑 Markdown 文件，然后运行同步命令。

步骤：

1. 在 content/blog/ 或 content/pages/ 目录下创建或编辑 .md 文件。

2. 提交更改（可选，但推荐纳入版本控制）：

   git add content/blog/my-post.md
   git commit -m "Update post"
   

3. 同步内容到 Convex 后端：

   开发环境同步：

   npm run sync
   

   生产环境同步：

   npm run sync:prod
   

执行同步后，所有连接的浏览器将立即更新显示新内容，无需重启服务器或重新部署。

3. 同步 AI 发现文件

为了优化 AI 代理（如 Cursor, Claude）对内容的抓取，可以同步生成 AGENTS.md 和 llms.txt 等文件：

npm run sync:discovery

或者一次性同步内容和发现文件：

npm run sync:all

4. 部署上线

默认使用 Convex 自托管模式部署：

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

---

更多详细配置（如 GitHub OAuth 认证设置、自定义域名绑定等），请参考官方文档：markdown.fast/docs