文档 / 知识库站

文档站首选 VitePress：Markdown 即页面，自带侧边栏、全文搜索、深色模式，构建产物是纯静态文件，丢哪都能托管。

npm init -y && npm i -D vitepress
npx vitepress init        # 问答式初始化，一路回车
npm run docs:dev          # 本地预览 http://localhost:5173

初始化后你会得到：

• docs/.vitepress/config.mjs：站点配置（标题、导航、侧边栏、搜索）
• docs/index.md：首页
• docs/ 下的其他 .md：就是文档正文

目录建议：一个主题一个文件夹（guide/、api/、faq/），文件名用小写英文 + 连字符，中文文件名在链接里要转码，不利于分享和收录。

先跑通空站再写内容，别一边配一边写，配置文件改错很容易卡半小时。

文档站的可用性 80% 取决于侧边栏怎么排。原则：按读者从上到下的阅读顺序排，不是按你写的时候的顺序。

// docs/.vitepress/config.mjs
export default {
  title: '我的文档',
  themeConfig: {
    nav: [{ text: '指南', link: '/guide/' }, { text: 'API', link: '/api/' }],
    sidebar: {
      '/guide/': [{ text: '开始', items: [
        { text: '介绍', link: '/guide/' },
        { text: '快速上手', link: '/guide/quickstart' }
      ]}]
    },
    search: { provider: 'local' }   // 本地全文搜索，无需服务
  }
}

三条经验：

• 侧边栏分组标题用「开始 / 进阶 / 参考」这种读者视角的词，别用「01-basic」
• 开启本地搜索（provider: 'local'），中文可用，零成本
• 每页顶部加一句「这页讲什么」，读者扫一眼就知道点不点

别做的：把所有页面平铺在侧边栏，超过 15 条就开始难找。

文档不是文章，一页只解决一个问题，否则读者搜到了也要自己翻。

一页的标准结构：

1. 一句话说清这页解决什么问题
2. 最短可用示例（能复制就复制）
3. 参数 / 选项说明（表格）
4. 常见错误与排查（最容易被忽略、也最提升口碑的一段）

写作细节：

• 命令、配置、代码全部用代码块，写清适用环境
• 「注意 / 警告」用引用块单独标出，别混在正文里
• 版本号、日期写具体，别写「最新版」——三个月后就是错的
• 每页底部写最后更新日期，读者据此判断可信度

内容从哪来：把你在暗吐槽站被问过三次以上的问题，各写一页。被问过 = 有人搜。

别追求一次写完：先有 10 页能用的，比规划 50 页大纲强。

文档站构建产物是纯静态文件，托管随便挑：

方式一：Vercel（最省事）
连 GitHub 仓库 → 框架选 VitePress → 每次 push 自动构建上线，自带 HTTPS 和 CDN。

方式二：GitHub Pages
仓库 Settings → Pages → 选 GitHub Actions；用官方 workflow 模板，push 即发布。免费但国内访问偏慢。

方式三：自有服务器（国内访问最快）

npm run docs:build               # 产物在 docs/.vitepress/dist
rsync -av docs/.vitepress/dist/ root@服务器:/www/wwwroot/docs.你的域名/

然后宝塔建站 + 申请 SSL。

注意 base 配置：部署在子路径（如 /docs/）时，config 里要写 base: '/docs/'，否则资源路径全 404。

自定义域名：Vercel / Pages 都支持绑域名 + 自动证书；自有服务器用宝塔 Let's Encrypt。

文档站是长期流量资产，前提是每页都能被单独收录。

必做：

• 每页 frontmatter 写 title + description，生成独立 meta
• 开启 sitemap（sitemap: { hostname: 'https://你的域名' }），自动产出 sitemap.xml
• 提交 sitemap 到百度 / Google
• 站内互链：新页从相关页链过去，别让任何一页成为孤岛

收录观测（照抄本站做法）：
把文档页 URL 写进 data/index-observation.json，跑 bash scripts/index-observation.sh 定期核对：HTTP 状态、canonical、robots 是否允许、lastmod 是否更新。收录状态人工在搜索平台核对后回填 indexed 字段。

迭代依据（两个来源）：

1. 搜索平台的「查询词」报表——有人搜但你没覆盖的词，直接补一页
2. 页面停留与退出率——停留极短又跳出的页，多半标题党或答非所问

别一次改全部：每月挑 3 页重写，比一年改一次全部有效。