Wiki.js 文档发布

本仓库使用 GitHub Actions 将 Markdown 文档发布到 Wiki.js。

发布触发

发布不会在 main 每次提交时自动执行。正式触发方式是：

• push 到 docs-publish 分支。
• push v* tag，例如 v0.2-code-design 或 v0.3.0。
• 在 GitHub Actions 页面手动运行 Publish docs to Wiki.js。

发布链路

GitHub Markdown
  -> GitHub Actions
  -> Wiki.js GraphQL API
  -> Wiki.js 访问控制
  -> 后续 RAGFlow 索引

Notion 不再作为工程文档发布目标。

Wiki.js 页面路径

发布脚本会把仓库文档映射为 Wiki.js 页面：

README.md                             -> /README
docs/overview.md                      -> /docs/overview
docs/features/README.md               -> /docs/features/README
docs/code-design/phase1-code-blueprint.md -> /docs/code-design/phase1-code-blueprint

目录也会生成索引页，例如：

docs/         -> /docs
docs/features -> /docs/features

GitHub 配置

在 GitHub 仓库中配置 Secrets：

• WIKIJS_BASE_URL：Wiki.js 站点地址，例如 https://wiki.jingyu.club
• WIKIJS_TOKEN：Wiki.js API token

可选 Repository Variable：

• WIKIJS_LOCALE：Wiki.js locale，默认 zh

Wiki.js 权限

建议创建一个专用 API token，例如 kgent-docs-publisher，并授予：

• 读取页面
• 创建页面
• 更新页面
• 访问 /README、/docs、/docs/*

访问控制应由 Wiki.js 的用户、组和 Page Rules 管理，不使用 Nginx Basic Auth。

校验机制

发布脚本不是只调用写入接口。每个页面创建或更新后，脚本会立即通过 Wiki.js GraphQL 反查页面内容，并与源 Markdown 对比。

如果页面不存在或内容不一致，GitHub Actions 会失败。这是判断链路是否真正打通的主要依据。

本地验证

Dry-run 只检查扫描、路径和链接转换，不访问 Wiki.js：

WIKIJS_BASE_URL=https://wiki.jingyu.club npm run docs:publish-wikijs:dry-run

真实发布会访问 Wiki.js 并做写后校验：

WIKIJS_BASE_URL=https://wiki.jingyu.club \
WIKIJS_TOKEN=... \
WIKIJS_LOCALE=zh \
npm run docs:publish-wikijs