draft(docs): switch documentation to Clarify with minimal configuration - #5648
draft(docs): switch documentation to Clarify with minimal configuration#5648yinxulai wants to merge 8 commits into
Conversation
dosubot
Bot
added
the
size:XL
|
CLA Assistant Lite bot: I have read the CLA Document and I hereby sign the CLA You can retrigger this bot by commenting recheck in this Pull Request |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review. 📝 WalkthroughWalkthroughThe update adds Clarify tooling and configuration for the documentation site. It defines bilingual navigation, footer links, locale settings, theme layout, package scripts, and ignore rules for generated documentation files. ChangesDocumentation configuration
Estimated code review effort: 3 (Moderate) | ~20 minutes Merge Risk: ⚪ Minimal · up to This PR replaces the documentation presentation with a minimal Clarify configuration while preserving existing Markdown content. No actionable merge-blocking risk remains beyond normal checks and review. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Linked Issues checkExplanation The PR implements the Clarify migration requested in [ Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
yinxulai
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/en/quick-start.mdx`:
- Around line 1-7: Replace the unfinished placeholder content in
docs/en/quick-start.mdx lines 1-7 with the restored English quick-start
documentation, or remove that page from navigation. Apply the same correction to
docs/zh/quick-start.mdx lines 1-7 using restored Chinese content, or remove it
from navigation; both localized pages must no longer expose placeholders.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e374e3a2-4200-4a1b-9a30-1b10c35614ab
⛔ Files ignored due to path filters (2)
doc/package-lock.jsonis excluded by!**/package-lock.jsondocs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (19)
.gitignoredocs/.nojekylldocs/clarify-env.d.tsdocs/clarify.tsdocs/css/buble.cssdocs/css/dark.cssdocs/css/fonts.cssdocs/css/pure.cssdocs/css/vue.cssdocs/en/deployment/quick-start-docker.mdxdocs/en/deployment/quick-start.mdxdocs/en/quick-start.mdxdocs/index.htmldocs/package.jsondocs/scripts/multiple-language-redirect.jsdocs/zh/README.mdxdocs/zh/deployment/quick-start-docker.mdxdocs/zh/deployment/quick-start.mdxdocs/zh/quick-start.mdx
💤 Files with no reviewable changes (6)
- docs/css/pure.css
- docs/css/vue.css
- docs/css/buble.css
- docs/css/dark.css
- docs/css/fonts.css
- docs/scripts/multiple-language-redirect.js
| # Prepare | ||
|
|
||
| Wait for content... | ||
|
|
||
| ```bash | ||
| content for copy | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Restore or unpublish both placeholder quick-start pages.
Both localized root pages contain unfinished placeholder text rather than documentation.
docs/en/quick-start.mdx#L1-L7: restore the English quick-start content or remove the page from navigation.docs/zh/quick-start.mdx#L1-L7: restore the Chinese quick-start content or remove the page from navigation.
📍 Affects 2 files
docs/en/quick-start.mdx#L1-L7(this comment)docs/zh/quick-start.mdx#L1-L7
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/en/quick-start.mdx` around lines 1 - 7, Replace the unfinished
placeholder content in docs/en/quick-start.mdx lines 1-7 with the restored
English quick-start documentation, or remove that page from navigation. Apply
the same correction to docs/zh/quick-start.mdx lines 1-7 using restored Chinese
content, or remove it from navigation; both localized pages must no longer
expose placeholders.
dosubot
Bot
added
size:L
dosubot
Bot
added
size:XS
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/package.json (1)
8-10: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMake the docs toolchain reproducible.
Please verify that a lockfile is committed for the
docspackage and used by CI; otherwise the caret range on Line 9 can allow later CLI releases to change the build. If no lockfile is intended, pin the CLI version explicitly. npm recommends committing lockfiles for reproducible CI installs, andnpm cirequires one. (docs.npmjs.com)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/package.json` around lines 8 - 10, Make the docs toolchain reproducible by ensuring the docs package has a committed lockfile that CI uses with npm ci; if a lockfile is not intended, replace the caret range for `@clarify-labs/cli` in devDependencies with an exact pinned version.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/package.json`:
- Around line 8-10: Make the docs toolchain reproducible by ensuring the docs
package has a committed lockfile that CI uses with npm ci; if a lockfile is not
intended, replace the caret range for `@clarify-labs/cli` in devDependencies with
an exact pinned version.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f1851b5c-14e5-4dea-85df-fff3f5963744
📒 Files selected for processing (2)
docs/clarify.jsondocs/package.json
|
@nobodyiam 我提供了一个极小的 PR 来完成了初步的尝试，对文档内容零改动，我提供了一份站点配置（甚至也是可选的，我只是为了让目录看起来更友好），对于 |
yinxulai
changed the title
|
感谢提交这个方案。Clarify 在面向 LLM 的文档体验上做了不少有价值的工作，例如提供 Markdown 视图、复制 Markdown、 不过，这些能力同时引入了文档构建和产物部署流程，这也是社区是否采纳时需要重点考虑的因素。Apollo 当前使用 Docsify，Markdown 文件可以直接在浏览器端渲染，仓库中只需维护文档源码，不需要为每次文档更新执行构建。类似这种轻量化模式对社区贡献者和后续维护会更友好一些。部分 LLM 友好能力，例如查看、复制原始 Markdown，也可以在 Docsify 现有模式下通过轻量插件补充。 另外，我目前按照 PR 中提供的步骤在本地执行 build 仍然不成功，因此暂时无法验证迁移后的完整页面效果、静态产物以及后续部署流程。建议先补充可复现的本地构建方式，并进一步说明构建产物如何在 CI 中生成和部署、是否需要提交到代码仓库，再评估完整的迁移成本和收益。 |
|
感谢你非常细致的评审和建议，也感谢你对 Clarify 在 LLM 友好方向上的认可。 先同步最新状态：之前本地遇到的构建报错（navigation 配置校验问题）已经通过升级到最新版本解决，当前构建流程可以正常执行。 关于方案定位，我想补充 Clarify 在这个 PR 中的使用方式和边界：
同时，Clarify 带来的能力不只是页面渲染替换，还包括：
以 Clarify 的官网内容示例：
内容操作菜单： 如果项目有接口文档，那 Clarify 更加适合:
|
|
当前这个 PR 只代表一个最小可用体验（minimal experience），用于验证文档内容零改动前提下能否完成接入与构建，不代表 Clarify 的最佳项目实践形态。 在实际生产使用里，Clarify 官方文档目前采用的是 Cloudflare Pages 自动追踪仓库变更并触发文档更新，这是一种免费、稳定且体验很好的发布方案。 也就是说，Clarify 的接入方式可以根据项目偏好选择，不绑定单一部署方案；无论选择 Cloudflare Pages 还是 GitHub Actions 加 Pages，都可以把仓库重心继续放在 Markdown 内容维护本身。 这一切成立的前提是 Clarify 最终交付的是纯静态 HTML 产物，因此天然适配 CDN 与静态托管链路，同时对搜索引擎抓取和 SEO 也非常友好。 |
nobodyiam
left a comment
nobodyiam
left a comment
There was a problem hiding this comment.
感谢持续更新这个方案，也感谢为 Apollo 社区投入时间做这次尝试。
我重新体验了 Clarify 的官方文档站点。整体阅读体验确实不错，尤其是 Markdown 视图、原始内容输出、llms.txt、MCP/Search 等面向 Agent 的能力，对未来文档被开发者和 AI 工具共同消费很有价值。Clarify 保持源码在 Git 中、生成可自托管静态产物的方向，也与开源社区的协作方式比较契合。
当前遇到的问题更多是 Apollo 已经基于 Docsify 运行多年，积累了现有链接、锚点、静态资源和 GitHub Pages 发布方式，因此从 Docsify 切换到 Clarify 时还需要补充一层迁移适配，并不代表 Clarify 本身不适合。下面这些点希望能一起探讨可行的解决方案。
我基于最新 head 2977e9a29e5df4856006c7fd7adf3e2ba814643d 重新进行了构建和浏览器验证。之前 navigation.links 导致的配置校验问题已经解决，使用 @clarify-labs/cli 0.11.21 也可以完成构建，这是一个明确的进展。
不过，如果当前 PR 的目标是完成 Apollo 线上文档站点的正式切换，还有以下问题需要进一步处理。
- 生成站点还需要与现有 Docsify 入口完成拆分
当前执行 clarify build --content . 时，Clarify 会继续复用已有的 docs/index.html。这个文件包含完整的 Docsify 配置和脚本，并使用 Docsify 的 #app 挂载节点，而 Clarify 需要 #root。
因此，虽然 build 命令能够成功结束，但浏览器运行时仍会出现以下情况：
- Clarify 无法找到
#root挂载节点； multiple-language-redirect.js没有进入生成物，加载时返回 404；- 页面继续被 Docsify 接管；
- 访问
/zh/portal/apollo-user-guide/等 Clarify clean path 时会显示 404； - 仓库中的本地图片没有复制到
docs/output，相关请求会返回 404。
这里可能需要采用 Clarify 推荐的 HTML 入口和 public 静态资源目录，同时将现有 Docsify 专用脚本从 Clarify 构建入口中移除或隔离。
建议后续在 CI 中增加一个简单的浏览器 smoke test，至少验证首页、中英文内容页、页面导航和一张本地图片。这样可以区分“构建命令成功”和“生成站点实际可访问”。
- 需要设计现有文档链接的兼容方案
Apollo 现有文档 URL 使用 Docsify 的 /#/... 路由和 ?id= 章节锚点，而 Clarify 使用 clean path 和标准 #anchor。这两套 URL 格式并不会自动保持兼容。
当前仓库中至少存在：
- 33 处指向
www.apolloconfig.com/#/...的绝对链接，分布在README.md、Issue 模板、Portal 页面和 OpenAPI 脚本等位置； - 文档正文中 109 处 Docsify 风格的
?id=章节链接； - 文档正文中 8 处指向
.md的内部页面链接； - 4 处直接写死的
/#/en/...或/#/zh/...链接。
例如：
https://www.apolloconfig.com/#/zh/portal/apollo-user-guide
在 Clarify 中对应/zh/portal/apollo-user-guide；/#/zh/portal/apollo-user-guide?id=_71-安全相关
需要转换为类似/zh/portal/apollo-user-guide#71-安全相关的格式，并以实际生成的 heading ID 为准；zh/design/apollo-design.md?id=...
如果目标是渲染后的页面，需要改为对应的 clean path 和标准锚点。
仓库内的链接可以逐步更新，但外部网站、搜索结果和用户书签中的旧链接无法一起修改。由于 URL fragment 不会发送到服务器，普通 HTTP 301 也无法直接处理 /#/...。
一种可能的方案是在根页面增加轻量的客户端兼容逻辑，将旧的 /#/path?id=anchor 解析并跳转为新的 /path#anchor。也欢迎结合 Clarify 的插件机制提出更合适的实现方式。
建议同时增加自动化链接检查，覆盖页面路径、章节锚点和静态资源，避免迁移过程中出现难以发现的失效链接。
- 需要确定并落实实际发布方式
Apollo 当前 GitHub Pages 使用 legacy 模式，直接发布 master:/docs。当前 PR 增加了 Clarify 配置和构建脚本，但：
- 没有增加 Clarify 构建和部署 workflow；
docs/output被加入.gitignore；- 现有
docs/index.html没有改变； - 当前 CI 也不会执行 Clarify build。
因此，合并当前改动后线上站点仍然会继续运行 Docsify。
作者之前提到 Cloudflare Pages 和 GitHub Actions + GitHub Pages，这两个方向都可以继续评估。为了便于社区判断后续维护成本，希望本 PR 或后续迁移方案能够明确：
- 最终选择哪种托管方式；
- 依赖安装和构建命令；
- 生成物如何发布；
- GitHub Pages 或托管平台需要调整哪些设置；
CNAME、.nojekyll和本地图片如何保留；- 构建失败时如何避免发布不完整的站点。
如果选择 GitHub Actions + GitHub Pages，建议在 PR 中提供对应 workflow；如果更推荐 Cloudflare Pages，也希望补充 Apollo 仓库侧需要的配置和维护说明，方便社区综合比较。
- Quick Start 占位页需要处理
docs/clarify.json 当前把 quick-start 放入 Getting Started 主导航，但：
docs/en/quick-start.md仍是Wait for content...占位内容；docs/zh/quick-start.md不存在；- 当前 locale fallback 会在中文站点展示英文占位内容。
这里可以恢复完整的中英文内容，也可以先从导航中移除该页面，继续使用已有的 deployment/quick-start 和 deployment/quick-start-docker。
- 建议固定经过验证的 Clarify 版本
docs/package.json 当前使用 "@clarify-labs/cli": "^0.11.21"，但没有提交 lockfile。考虑到不同 Clarify 版本之间可能存在配置 schema 和构建行为变化，为了保证社区贡献者和 CI 得到一致结果，建议：
- 提交
package-lock.json并在 CI 使用npm ci；或者 - 精确锁定当前经过验证的 Clarify CLI 版本。
目前 Java build、code style 和 license 检查已经通过。合并前还需要完成 CLA，并按照仓库要求更新 CHANGES.md。
如果当前 PR 的定位只是验证 Clarify 能否读取 Apollo 现有文档，可以考虑先将其标记为 draft/PoC，记录上述迁移问题和后续实施方案，不必要求一次完成所有生产切换工作。
如果 PR 仍以 “switch documentation to Clarify” 并关闭 #5638 为目标，那么在合并前至少需要完成可工作的构建入口、发布链路和旧链接兼容方案。
总体上我认可继续探索 Clarify 的方向，尤其是其 agent-friendly 能力值得关注。希望我们可以一起把 Apollo 现有文档体系的兼容和发布问题梳理清楚，再逐步推进正式迁移。
yinxulai
changed the title
2 participants
What's the purpose of this PR
Upgrade the Apollo documentation experience from the legacy Docsify presentation to Clarify with a deliberately minimal integration. Existing Markdown content remains unchanged and continues to be the source of truth; Clarify reads it directly from
docs/.A single JSON configuration provides the full site experience: bilingual navigation, grouped sections, search, light/dark themes, responsive layouts, footer links, and localized routes. This keeps future documentation work focused on content instead of site-specific scripts and injected UI configuration.
Which issue(s) this PR fixes
Fixes #5638
Brief changelog
docs/clarify.jsonwith site metadata, English and Chinese locales, navigation, footer links, and layout settings.Local development
Prerequisite: Node.js and npm.
cd docs npm install npm run devOpen the URL printed by the command and visit
/README, for examplehttp://localhost:5173/README. If that port is already in use, Clarify automatically selects another one.The development server watches documentation and configuration files and refreshes the site as they change.
Production build
cd docs npm install npm run buildThe generated static site is written to
docs/output/.Validation
npm run dev.Preview
Checklist
mvn clean test(not required for this documentation-only change).mvn spotless:apply(not applicable to JSON/package metadata only).CHANGES.mdafter the PR URL is available.Summary by CodeRabbit