feat(site): migrate documentation site from Docusaurus to VitePress - #2721
Conversation
E2E tests did not runE2E tests run automatically for org/repo members and collaborators on pull requests. For other contributors, a maintainer must add the See E2E testing guide for details. |
PR Summary by QodoMigrate docs site from Docusaurus to VitePress Description
Diagram
High-Level Assessment
Files changed (8)
|
ca03958 to
a722f0e
Compare
c17cf18 to
fe2e0e2
Compare
Code Review by Qodo
1. Indented fences corrupted
|
| function escapeVueSyntax(src: string): string { | ||
| const lines = src.split('\n') | ||
| let fenceLen = 0 | ||
| return lines.map(line => { | ||
| const fenceMatch = line.match(/^(`{3,})/) | ||
| if (fenceMatch) { | ||
| if (fenceLen === 0) { | ||
| fenceLen = fenceMatch[1].length | ||
| return line | ||
| } | ||
| if (fenceMatch[1].length >= fenceLen && line.trim() === fenceMatch[0]) { | ||
| fenceLen = 0 | ||
| return line | ||
| } | ||
| return line | ||
| } | ||
| if (fenceLen > 0) return line | ||
| return escapeLine(line) | ||
| }).join('\n') |
There was a problem hiding this comment.
1. Indented fences corrupted 🐞 Bug ≡ Correctness
escapeVueSyntax() only detects fenced code blocks when the fence starts at column 0, so indented
fences (common inside lists) are treated as normal text and get {} escaped. This corrupts code
blocks (e.g., JSON snippets) by rendering { literally in <code> output instead of {.
Agent Prompt
### Issue description
`escapeVueSyntax()` fails to detect indented fenced code blocks (e.g. list-item code fences like ` ```json`). As a result, code-block contents are passed through `escapeLine()`, which replaces `{`/`}` with HTML entities. Inside fenced code blocks, markdown-it typically escapes `&` to `&`, so the docs render the entity text (e.g. `{`) instead of braces.
### Issue Context
- Many docs contain indented fences and JSON bodies.
- Fix should follow CommonMark: fenced blocks may be indented up to 3 spaces.
### Fix Focus Areas
- website/.vitepress/config.ts[29-47]
### Suggested fix approach
- Update fence detection to allow up to 3 leading spaces: e.g. `line.match(/^\s{0,3}(`{3,})/)`.
- When closing a fence, allow leading/trailing whitespace and allow fence length >= opening fence length.
- Consider also supporting `~~~` fences if they might exist in future (optional).
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
There was a problem hiding this comment.
Good catch, fixed. Updated the regex to /^ {0,3}({3,}|~{3,})/` so it handles indented fences (up to 3 spaces per CommonMark) and tilde fences. Also tracks the fence character type so a backtick fence can only be closed by backticks, not tildes.
71c738f to
c04335e
Compare
|
/fs-review |
|
🤖 Finished Review · ❌ Failure · Started 6:07 PM UTC · Completed 6:08 PM UTC |
c04335e to
a6d0a34
Compare
|
/fs-review |
949fa06 to
bcc1648
Compare
Site previewPreview: https://7d28eabc-site.fullsend-ai.workers.dev Commit: |
bcc1648 to
33c8453
Compare
33c8453 to
ce5b80a
Compare
Replace Docusaurus with VitePress for the docs site at /docs/.
- VitePress config with full sidebar matching the original structure
- Dynamic sidebar generation for ADRs, specs, plans, and experiments
- Custom theme preserving all visual styling (brand colors, gradient
headings, frosted navbar, animated links, code block rounding,
reading progress bar)
- ReadingProgress component migrated from React to Vue
- Markdown preprocessor to escape Vue-incompatible syntax ({}, {{}},
<PLACEHOLDER> tags) in docs without modifying content files
- Inline code v-pre fix per VitePress maintainer recommendation
- README.md to index.md rewrites for clean URLs
- CI workflow updated: website/build to website/dist
- Static assets moved to docs/public/img/
- Updated site-deployment.md references
No documentation content was modified.
Signed-off-by: Juntao Wang <juntwang@redhat.com>
ce5b80a to
7f59e9c
Compare
|
🤖 Finished Retro · ✅ Success · Started 7:05 PM UTC · Completed 7:12 PM UTC |
Retro: PR #2721 — Docusaurus to VitePress migrationTimeline: Human-authored PR by DaoDaoNoCode migrating the docs site from Docusaurus to VitePress (~576 lines changed + lockfile). qodo-code-review[bot] reviewed at 17:59Z and caught two real bugs (indented fence detection, nested README sidebar). waynesun09 invoked What went well:
Proposals: 1 filed (see below). Several other potential improvements were already covered by existing issues:
Proposals filed
|
Summary
/docs/, reducing dependencies from 10 packages (React, MDX, Prism) to 2 (VitePress, Vue)website/build/→website/dist/) for seamless deployment on existing Cloudflare Workers infraWhat changed
Removed (Docusaurus):
website/docusaurus.config.ts,website/sidebars.tswebsite/src/(React components, CSS, theme overrides)website/static/(moved todocs/public/)Added (VitePress):
website/.vitepress/config.ts— site config, sidebar, markdown preprocessingwebsite/.vitepress/theme/— custom theme (CSS, ReadingProgress Vue component)docs/index.md— redirect to Getting Started (replaces Docusaurusslug: /)docs/public/img/— favicon and logoModified:
website/package.json— Docusaurus deps → VitePress + Vuewebsite/tsconfig.json— removed@docusaurus/tsconfigextend.github/workflows/site-build.yml—website/build/→website/dist/Notable decisions
{{ }},{x|y}, and<PLACEHOLDER>syntax in docs break Vue's template compiler. ApreConfighook escapes these before markdown-it processes them (same pattern Docusaurus used). Inline code getsv-preper VitePress maintainer recommendation.fullsend.shalready has its own footer./) and docs (/docs/) remain separate — no changes to the homepage.Test plan
npm run buildproduces 163 HTML pages with no errorsagents/icons/,testing/) not in buildsite-build.ymlcopieswebsite/dist/to_bundle/public/docs/