如何Fork并配置markdown-site?fork-config.json 全字段详解,一条命令完成个性化设置
如何Fork并配置markdown-site?fork-config.json 全字段详解,一条命令完成个性化设置
markdown-site 是一个面向 AI 代理和开发者的开源 Markdown 发布框架:写 Markdown,从终端同步,内容即刻可被浏览器、LLM 和 AI agents 访问。Fork 之后,你只需要编辑一个 fork-config.json 文件,再运行一条命令,14 个配置文件就会全部自动更新——无需手动逐文件修改。本文将带你完整走通 Fork 流程,并逐字段详解 fork-config.json 的每一项设置。
一、Fork markdown-site 并快速跑起来
前置要求:Node.js 18+,一个 Convex 账号。
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/mar/markdown-site my-site
cd my-site
npm install
npx convex dev --once # 初始化 Convex 后端(会打开浏览器登录)
npm run sync # 同步内容到开发环境
npm run dev # 启动开发服务器,访问 localhost:5173
此时站点已可运行,但站名、URL、RSS、社交分享卡片、AI 发现文件(AGENTS.md、CLAUDE.md、public/llms.txt)还是别人的信息。下一步才是重点:个性化配置。
二、三种 Fork 配置方式,如何选择?
| 方式 | 命令 | 适用场景 |
|---|---|---|
| ⚡ CLI 向导(推荐) | npx create-markdown-sync my-site |
从零开始创建新项目 |
| 🔧 JSON 自动配置 | npm run configure |
已有 Fork,想批量改配置 |
| ✍️ 手动配置 | 按 FORK_CONFIG.md 逐步修改 | 想完全控制每个文件 |
方式一:一条命令的交互式向导
create-markdown-sync 是仓库内置的脚手架 CLI(源码见 packages/create-markdown-sync/),一条命令完成克隆、问答式配置、安装依赖、Convex 初始化和内容同步:
npx create-markdown-sync my-site
交互式向导(wizard.ts)会分 11 个部分逐项询问:站点身份、作者信息、外观主题、首页与精选、博客与文章展示、功能开关(Logo 画廊 / GitHub 贡献图 / 访客地图)、页脚社交、订阅与联系表单、认证与托管模式等。还支持参数:
--force:目标目录已存在时强制覆盖--skip-convex:跳过 Convex 初始化--skip-open:完成后不自动打开浏览器
向导最终写入的就是 fork-config.json 结构,所以下面的字段详解同样适用于它。
方式二:编辑 JSON + npm run configure(本文重点)
适合已有 Fork 的用户。步骤只有三步。
第 1 步:复制模板文件
cp fork-config.json.example fork-config.json
fork-config.json 已被 gitignore,你的配置只保存在本地;.example 模板(fork-config.json.example)保留在仓库中供参考。
第 2 步:编辑 JSON——先填必填项即可:
{
"siteName": "我的站点",
"siteTitle": "我的标语",
"siteDescription": "一句话描述你的站点",
"siteUrl": "https://yoursite.example.com",
"siteDomain": "yoursite.example.com",
"githubUsername": "yourusername",
"githubRepo": "your-repo-name",
"contactEmail": "you@example.com",
"creator": { "name": "你的名字", "twitter": "...", "linkedin": "...", "github": "..." },
"bio": "关于我的一段简介",
"theme": "tan"
}
其余字段全部可选,省略时脚本使用合理默认值。
第 3 步:运行配置脚本
npm run configure
脚本 scripts/configure-fork.ts 读取 JSON,自动更新 14 个配置文件,包括 src/config/siteConfig.ts、src/pages/Home.tsx、src/pages/Post.tsx、convex/rss.ts、index.html、public/llms.txt、public/robots.txt、public/openapi.yaml 等。
方式三:手动配置
偏好手动控制的话,FORK_CONFIG.md 提供了完整参考:每个文件要改什么、代码片段、精确位置,甚至附有一段可直接粘贴给 AI 编程助手的配置提示词(AI Agent Prompt)。
三、fork-config.json 全字段详解
以下字段按功能分组(完整模板见 fork-config.json.example)。
3.1 站点身份字段(必填)
| 字段 | 说明 |
|---|---|
siteName |
站点名称,用于导航、RSS、JSON-LD 等 |
siteTitle |
站点标语(页面 <title> 来源之一) |
siteDescription |
一句话描述,用于 meta、RSS、社交分享 |
siteUrl / siteDomain |
完整 URL 与裸域名,用于 canonical、sitemap、Open Graph |
githubUsername / githubRepo |
你的 GitHub 用户名与仓库名,用于首页 "Fork it" 链接 |
contactEmail |
联系邮箱,写入 AI 插件元数据 |
creator |
创作者信息:name、twitter、linkedin、github 社交链接 |
bio |
作者简介,显示在首页 |
3.2 运行模式字段(决定基础设施组合)
| 字段 | 可选值 | 说明 |
|---|---|---|
auth.mode |
convex-auth(默认)/ workos / none |
登录方式:GitHub OAuth、WorkOS 兼容模式或纯本地开发 |
hosting.mode |
convex-self-hosted(默认)/ netlify |
静态托管后端 |
compat.legacyDocs |
true / false |
兼容旧版文档路由 |
media.provider |
convex(默认)/ convexfs / r2 |
图片媒体存储后端 |
3.3 AI 服务链接字段
gitHubRepoConfig(owner、repo、branch、contentPath)供 ChatGPT、Claude、Perplexity 的 "Open in AI" 按钮定位你的原始 Markdown 文件,contentPath 默认指向 public/raw。
3.4 外观与布局字段
| 字段 | 说明 |
|---|---|
theme |
默认主题:dark / light / tan / cloud |
fontFamily |
正文字体:serif / sans / monospace |
featuredViewMode / showViewToggle |
首页精选区卡片/列表视图及切换按钮 |
homepage |
首页设置:type 可为 default / page / post,可把任意页面或文章设为首页;originalHomeRoute 保留原首页入口(默认 /home) |
rightSidebar |
宽屏右侧栏开关及最小视口宽度(默认 1135px) |
3.5 内容模块字段
blogPage:博客页开关、导航展示、标题、排序postsDisplay:首页/博客页文章列表、首页文章数量上限(homePostsLimit)与 "Read more" 链接logoGallery:底部 Logo 墙(enabled、title、scrolling滚动、maxItems)gitHubContributions:GitHub 贡献热力图(用户名、年份导航、跳转 Profile)visitorMap:/stats 页的实时访客地图statsPage:实时统计页开关与导航入口imageLightbox:图片点击放大灯箱footer:页脚 Markdown 内容与各页面显示开关socialFooter:社交图标(支持 github/twitter/linkedin 等平台)、页头显示开关、版权年份
3.6 AI 功能字段
| 字段 | 说明 |
|---|---|
aiChat |
写作页 / 内容页的 AI 聊天开关 |
aiDashboard |
Dashboard AI Agent:多模型文本对话(Claude/GPT/Gemini)+ AI 图片生成 |
askAI |
页头 "Ask AI" 按钮,基于 RAG 对站点内容问答 |
semanticSearch |
语义搜索(需 OPENAI_API_KEY),关闭则仅关键词搜索 |
mcpServer |
HTTP MCP 服务器:endpoint(默认 /mcp)、公开/认证限流、是否强制 API Key,供 Cursor、Claude Desktop 等接入 |
3.7 订阅与邮件字段
newsletter:邮件订阅总开关 + AgentMail 收件箱 + 首页/博客页/文章三个位置的订阅表单(位置、标题、描述);需在 Convex 设置AGENTMAIL_API_KEY与AGENTMAIL_INBOXcontactForm:联系表单总开关与文案,通过 frontmattercontactForm: true按页启用newsletterAdmin:/newsletter-admin 订阅者管理后台开关newsletterNotifications:新订阅提醒、每周统计邮件weeklyDigest:每周自动摘要邮件(dayOfWeek0=周日)
3.8 其他字段
dashboard(管理后台开关与登录要求,建议生产环境 requireAuth: true)、twitter(OG 元数据中的 @handle)。
四、配置后的下一步
git diff # 检查 14 个文件的改动
npx convex dev # 启动 Convex(如未运行)
npm run sync # 同步内容
npm run dev # 本地验证站名、页脚、元数据
npm run deploy # Convex 自托管一键部署
⚠️ 重要提示:保留你的
fork-config.json。npm run sync:discovery/npm run sync:all会读取它来持续更新发现文件(AGENTS.md、CLAUDE.md、public/llms.txt);文件丢失时,这些文件会回退到占位值。
配置脚本只改站点级设置,不会动 content/blog/ 与 content/pages/ 里的 Markdown 内容——想清空示例文章,直接删掉对应文件再同步即可。
五、常见问题速答
Q:改完配置后页面还是旧站名? 先确认已运行 npm run configure,再 npm run dev 查看本地,最后重新部署。
Q:fork-config.json 会被提交到仓库吗? 不会,它已被 gitignore,.example 文件才是进仓库的模板。
Q:Dashboard 权限如何设置? 部署后需完成 GitHub OAuth 并执行管理员引导(详见 FORK_CONFIG.md 的 "Setting up your admin email" 一节),非管理员只能浏览公开内容。
总结
Fork 配置只需记住两条主线:从零起步用 npx create-markdown-sync,已有 Fork 用 npm run configure。字段按需填、默认值兜底,一条命令完成全部个性化。Fork it, configure it, ship it 🚀
更多细节可参考 Fork Configuration Guide 与博客文章 content/blog/fork-configuration-guide.md。


