docs: switch documentation to Clarify with minimal configuration - #5648
docs: switch documentation to Clarify with minimal configuration#5648yinxulai wants to merge 3 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 |
📝 WalkthroughWalkthroughAdds Clarify tooling and configuration for Apollo’s documentation site, including development/build scripts, bilingual navigation and localization, footer links, theme layout settings, and ignored generated documentation files. ChangesDocumentation configuration
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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
1 participant
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.