docs: switch documentation to Clarify with minimal configuration - #5648
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 也非常友好。 |
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