Migrate API docs generation to vitepress#7355
Conversation
There was a problem hiding this comment.
Pull request overview
Migrates the project’s API documentation site generation from the legacy Docbox pipeline to VitePress to reduce dependency risk and modernize the docs UX (theme, dark mode, navigation).
Changes:
- Replace Docbox-based docs build with VitePress build, and add a
docs:devdev server script. - Add VitePress site scaffolding (config, theme CSS, markdown-it endpoint fence plugin) and a new docs home page.
- Tweak existing Markdown for improved rendering/syntax highlighting (e.g.,
curlblocks →bash, escape<...>in tables).
Reviewed changes
Copilot reviewed 9 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/build_api_docs.sh | Switch docs build to npx documentation … + npx vitepress build docs, and stage output under build/docs. |
| package.json | Remove docbox, add vitepress, and add docs:dev script. |
| docs/index.md | New VitePress home page frontmatter + navigation content. |
| docs/http.md | Update code fence language for better highlighting. |
| docs/profiles.md | Escape <…> in markdown table types for correct rendering. |
| docs/.vitepress/config.js | Add VitePress site configuration (nav/sidebar/base/edit links/search). |
| docs/.vitepress/plugins/endpoint.js | Add custom endpoint fence renderer for styled endpoint blocks. |
| docs/.vitepress/theme/index.js | Register custom theme CSS. |
| docs/.vitepress/theme/custom.css | Add styling for endpoint blocks (incl. dark mode tweaks). |
| .gitignore | Ignore VitePress cache directories. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| return `<div class="endpoint"> | ||
| <div class="endpoint-method">${method}</div> | ||
| <div class="endpoint-url">${highlightTokens(url)}</div> | ||
| </div>` |
There was a problem hiding this comment.
The plugin interpolates method and url directly into HTML without escaping. If an endpoint fence contains <, &, quotes, etc., this will generate raw HTML and can lead to XSS in the rendered docs. Use markdown-it’s escaping utilities (e.g. md.utils.escapeHtml) for method/url (and then apply the {param} highlighting) before returning the HTML string.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Issue
Migrate the API docs generation to vitepress and retire docbox, which hasn't seen any updates for many years. As a result, the number of dependencies with known issues and vulnerabilities drops significantly: From 17 vulnerabilities on the main branch (3 critical, 5 high, 7 moderate, 2 low) to 3 moderate severity vulnerabilities.
The following two screenshots show how the dark mode looks, which is also toggle-able.