如何Fork并配置markdown-site?fork-config.json 全字段详解,一条命令完成个性化设置

原创2026-11-14 18:53:491,119 阅读
文章标签:前端后端CMSAI 应用

如何Fork并配置markdown-site?fork-config.json 全字段详解,一条命令完成个性化设置

markdown-site 是一个面向 AI 代理和开发者的开源 Markdown 发布框架:写 Markdown,从终端同步,内容即刻可被浏览器、LLM 和 AI agents 访问。Fork 之后,你只需要编辑一个 fork-config.json 文件,再运行一条命令,14 个配置文件就会全部自动更新——无需手动逐文件修改。本文将带你完整走通 Fork 流程,并逐字段详解 fork-config.json 的每一项设置。

markdown-site Fork 配置管理后台界面

一、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 的用户。步骤只有三步。

markdown-site fork-config.json 配置文件主题图

第 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)。

markdown-site 手动配置与部署指南主题图

三、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_INBOX
  • contactForm:联系表单总开关与文案,通过 frontmatter contactForm: true 按页启用
  • newsletterAdmin:/newsletter-admin 订阅者管理后台开关
  • newsletterNotifications:新订阅提醒、每周统计邮件
  • weeklyDigest:每周自动摘要邮件(dayOfWeek 0=周日)

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。

登录后查看全文
markdown-site