实施步骤

这篇文章保留当前主题实施中的关键步骤。日常写作规范和发布命令已经沉淀在全局 personal-wiki-publish skill 中，不再作为公开 Wiki 文章维护。

1. 初始化仓库

仓库放在：

/Users/ryanchen/codespace/personal-wiki

基础栈：

Astro + Starlight + Lucode Starlight Theme + Markdown/MDX + Vercel

关键文件：

astro.config.mjs
src/content.config.ts
vercel.json
.github/workflows/vercel-production.yml
scripts/deploy-vercel-git-source.mjs

2. 建立内容目录

当前内容目录保持少而稳定：

src/content/docs/<topic>/   长期知识主题，例如 ai-knowledge-base
src/content/docs/other/     自定义页面入口和其他内容

复杂页面单独放：

src/pages/custom/
src/pages/raw-html/
public/assets/

这个目录设计的目标是降低判断成本。普通内容先判断是否属于某个长期知识主题；不适合时再放到 other，不要为了少量文章过早增加顶层分类。

3. 配置文档站

astro.config.mjs 负责站点骨架：

• site 指向 https://chenzeqing.cn。
• Starlight 管理文档路由、搜索、目录和侧边栏。
• 顶部不放分类菜单，统一使用左侧目录切换。
• sidebar 直接使用长期知识主题作为大分类，例如 AI 自动化个人知识库。
• 不维护自定义 Header 或 Sidebar override，优先使用 Lucode 主题内置组件。

普通文章优先放进正确目录。需要明确展示的主题分类和自定义页面入口，通过 sidebar 保持可发现。

4. 支持复杂页面

默认内容使用 Markdown。表达能力不够时再升级：

• MDX：文章内需要组件。
• Astro 页面：需要完整页面布局或页面级逻辑。
• raw HTML：需要完全独立的 HTML/CSS/JS 展示。

Codex Agent Loop 流程图就是 raw HTML 页面，并通过侧边栏的 其他 分组暴露入口。

5. 接入 GitHub Actions

推送到 main 后，Actions 执行：

Checkout -> Setup Node 24 -> npm ci -> npm run build -> Vercel deploy

构建检查先于部署。这样 frontmatter、MDX、链接和内容 schema 问题会在进入生产前暴露。

6. 接入 Vercel

部署脚本使用 Vercel API 创建生产部署，并传入 GitHub commit 信息。这样线上部署能追溯到具体 commit。

需要的 Secrets：

VERCEL_TOKEN
VERCEL_ORG_ID
VERCEL_PROJECT_ID

vercel.json 保持简单：

{
  "installCommand": "npm install",
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

7. 绑定域名和 HTTPS

生产域名是：

https://chenzeqing.cn

DNS 配置完成后，Vercel 负责证书签发和 HTTPS。上线后用 curl -I https://chenzeqing.cn 验证状态码和 HTTPS 头。

8. 验证路径

本地验证：

npm run build
git diff --check

发布后验证：

gh run list --limit 5
gh run watch <run-id> --exit-status
curl -I https://chenzeqing.cn/ai-knowledge-base/

9. 实施经验

• 标题要短。长标题会进入侧边栏，容易挤压布局。
• 公开 Wiki 不放写作、发布和模板教程；这些规则放到全局 skill。
• 文章按具体知识主题分类沉淀，避免所有文章平铺在一个目录。
• 自定义页面必须有目录入口，否则后续很难找到。
• 发布前必须确认内容可以公开，不能因为仓库是 private 就忽略 Vercel 站点是公开的。