docs: migrate documentation from MkDocs to Docusaurus#2299
Draft
docs: migrate documentation from MkDocs to Docusaurus#2299
Conversation
Replace MkDocs (Material theme) with Docusaurus v3 for the project documentation site. This modernizes the docs framework with a React-based setup and cleaner navigation. Key changes: - Initialize Docusaurus v3 with classic preset in docs/ - Convert all MkDocs-specific syntax (admonitions, collapsibles, content tabs, image width attrs) to Docusaurus equivalents - Restructure navigation into 4 tabs: Get Started, Tools, Core Abilities, FAQ - Move Data Privacy under FAQ section - Merge Installation + Usage Guide into "Get Started" with categories - Add custom CSS with brand colors and dark mode support - Configure Google Tag Manager analytics plugin - Add local search plugin - Rewrite GitHub Actions workflow for Node.js/Docusaurus deployment - Preserve custom domain (qodo-merge-docs.qodo.ai) via CNAME
Contributor
Review Summary by QodoMigrate documentation from MkDocs to Docusaurus v3 with restructured navigation
WalkthroughsDescription• Migrate documentation framework from **MkDocs (Material theme)** to **Docusaurus v3** with classic
preset
• Restructure navigation into **4 clean tabs**: Get Started, Tools, Core Abilities, FAQ (previously
5 tabs)
• Convert all **37 markdown files** from MkDocs syntax to Docusaurus-compatible format:
- 22 admonitions (!!! → :::)
- 18 collapsible blocks (??? → <details>)
- 4 content tabs (=== → <Tabs>/<TabItem> MDX components)
- 50 image width attributes ({width=N} → <img> HTML tags)
- 3 figure tags (removed markdown="1" attribute)
• Create Docusaurus configuration files: docusaurus.config.js, sidebars.js, package.json
• Implement custom CSS with brand colors supporting light/dark mode
• Configure plugins: Google Tag Manager and local search via @easyops-cn/docusaurus-search-local
• Update CI/CD workflow from Python/MkDocs to Node.js 20/Docusaurus build
• Preserve all content, branding, analytics, search functionality, and custom domain (CNAME)
• Remove legacy MkDocs configuration files and overrides directory
Diagramflowchart LR
A["MkDocs<br/>Material Theme"] -- "Convert 37 files<br/>97 syntax instances" --> B["Docusaurus v3<br/>Classic Preset"]
C["5 Navigation Tabs<br/>Overview, Installation,<br/>Usage Guide, Tools,<br/>Core Abilities"] -- "Restructure to<br/>4 Tabs" --> D["4 Navigation Tabs<br/>Get Started, Tools,<br/>Core Abilities, FAQ"]
E["MkDocs Syntax<br/>Admonitions, Collapsibles,<br/>Tabs, Images"] -- "Convert to<br/>Docusaurus Format" --> F["Docusaurus Components<br/>MDX, HTML, CSS"]
G["Python/MkDocs<br/>CI/CD"] -- "Update to<br/>Node.js 20" --> H["Node.js/Docusaurus<br/>CI/CD"]
B --> I["Custom CSS<br/>Light/Dark Mode"]
B --> J["Plugins<br/>GTM, Search"]
File Changes1. docs/docs/tools/improve.mdx
|
Contributor
Code Review by Qodo
1. YAML front matter in docs/
|
There was a problem hiding this comment.
Pull request overview
This PR migrates the documentation site from MkDocs (Material) to Docusaurus v3, including a navigation restructure, updated build/deploy workflow, and conversion of Markdown/MkDocs-specific syntax to Docusaurus/MDX-compatible patterns.
Changes:
- Add Docusaurus v3 config (navbar, sidebars, theme, local search, GTM) and docs build tooling under
docs/. - Convert docs content to Docusaurus frontmatter/MDX and replace MkDocs-only constructs (admonitions, tabs, collapsibles, image sizing).
- Update GitHub Pages deployment workflow to Node 20 +
docusaurus build.
Reviewed changes
Copilot reviewed 50 out of 70 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/static/img/logo.svg | Adds a new logo SVG asset (currently embeds a raster image). |
| docs/static/img/logo_.png | Adds raster logo PNG. |
| docs/static/img/favicon.svg | Adds SVG favicon. |
| docs/static/img/favicon.ico | Adds ICO favicon. |
| docs/static/CNAME | Adds custom domain CNAME for Pages output. |
| docs/src/css/custom.css | Adds Docusaurus theme overrides (colors, images, details styling). |
| docs/sidebars.js | Defines the new 4-tab sidebar structure (Get Started / Tools / Core Abilities / FAQ). |
| docs/README.md | Removes legacy docs portal link content. |
| docs/package.json | Adds Node/Docusaurus dependencies and scripts for docs build. |
| docs/overrides/partials/integrations/analytics/custom.html | Removes MkDocs override for GTM script injection. |
| docs/overrides/partials/footer.html | Removes custom MkDocs footer override. |
| docs/overrides/main.html | Removes MkDocs main template override (announce + noscript GTM). |
| docs/mkdocs.yml | Removes MkDocs site configuration. |
| docs/docusaurus.config.js | Adds Docusaurus config (navbar, footer, GTM plugin, local search, prism). |
| docs/docs/usage-guide/mail_notifications.md | Adds Docusaurus frontmatter; converts MkDocs image sizing to <img>. |
| docs/docs/usage-guide/introduction.md | Adds frontmatter; adjusts links for Docusaurus compatibility. |
| docs/docs/usage-guide/index.md | Adds frontmatter; updates internal links. |
| docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md | Adds frontmatter. |
| docs/docs/usage-guide/configuration_options.md | Adds frontmatter; converts MkDocs admonitions; updates links. |
| docs/docs/usage-guide/changing_a_model.md | Adds frontmatter; converts MkDocs admonitions. |
| docs/docs/usage-guide/automations_and_usage.md | Adds frontmatter; converts MkDocs admonitions. |
| docs/docs/usage-guide/additional_configurations.md | Adds frontmatter; converts MkDocs link target syntax; converts images/admonitions. |
| docs/docs/tools/update_changelog.md | Adds frontmatter; converts images to <img>. |
| docs/docs/tools/similar_issues.md | Adds frontmatter; converts images to <img>. |
| docs/docs/tools/review.md | Adds frontmatter; converts MkDocs collapsibles/admonitions to <details>/:::tip. |
| docs/docs/tools/index.md | Adds frontmatter; updates Improve link to .mdx. |
| docs/docs/tools/improve.mdx | Converts Improve doc to MDX; adds Tabs/TabItem; converts MkDocs constructs. |
| docs/docs/tools/help.md | Adds frontmatter; converts images to <img>. |
| docs/docs/tools/help_docs.md | Adds frontmatter; updates anchor link; converts images to <img>. |
| docs/docs/tools/generate_labels.md | Adds frontmatter; converts images to <img>. |
| docs/docs/tools/describe.md | Adds frontmatter; converts MkDocs collapsibles/admonitions to <details>/:::tip. |
| docs/docs/tools/ask.md | Adds frontmatter; converts images to <img>. |
| docs/docs/tools/add_docs.md | Adds frontmatter; converts images to <img>. |
| docs/docs/summary.md | Removes GitBook/MkDocs summary table of contents page. |
| docs/docs/overview/data_privacy.md | Adds frontmatter. |
| docs/docs/installation/pr_agent.md | Adds frontmatter. |
| docs/docs/installation/locally.md | Adds frontmatter; updates links/anchors for Docusaurus. |
| docs/docs/installation/index.md | Adds frontmatter. |
| docs/docs/installation/gitlab.md | Adds frontmatter. |
| docs/docs/installation/github.md | Adds frontmatter; converts MkDocs admonitions to :::tip. |
| docs/docs/installation/gitea.md | Adds frontmatter. |
| docs/docs/installation/bitbucket.md | Adds frontmatter. |
| docs/docs/installation/azure.md | Adds frontmatter; converts image to <img>. |
| docs/docs/index.md | Adds frontmatter; updates internal links to .mdx where needed; converts figures/images. |
| docs/docs/faq/index.md | Adds frontmatter; converts MkDocs Q/A blocks to <details>. |
| docs/docs/css/custom.css | Removes legacy MkDocs custom CSS. |
| docs/docs/core-abilities/self_reflection.md | Adds frontmatter; converts admonitions/images. |
| docs/docs/core-abilities/metadata.md | Adds frontmatter; updates Improve link to .mdx. |
| docs/docs/core-abilities/interactivity.md | Adds frontmatter; updates Improve link to .mdx. |
| docs/docs/core-abilities/index.md | Adds frontmatter; updates Fetching Ticket Context link to .mdx. |
| docs/docs/core-abilities/fetching_ticket_context.mdx | Converts to MDX; adds Tabs; converts admonitions/collapsibles/images. |
| docs/docs/core-abilities/dynamic_context.md | Adds frontmatter. |
| docs/docs/core-abilities/compression_strategy.md | Adds frontmatter; converts image to <img>. |
| docs/docs/.gitbook.yaml | Removes GitBook configuration. |
| .gitignore | Ignores Docusaurus build artifacts and Node modules under docs/. |
| .github/workflows/docs-ci.yaml | Rewrites docs CI to Node 20 + Docusaurus build + deploy via gh-pages action. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
6
to
7
| # Overview | ||
|
|
There was a problem hiding this comment.
This page now has a frontmatter title, but it also keeps a top-level # Overview heading. In Docusaurus docs, this typically renders two H1s (the doc title + the Markdown H1). Consider removing the # Overview heading (or removing title from frontmatter and letting the H1 drive the title) to avoid duplicate titles and improve accessibility/SEO.
Suggested change
| # Overview |
Comment on lines
+1
to
7
| --- | ||
| title: "Tools" | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Tools | ||
|
|
There was a problem hiding this comment.
Frontmatter defines title: "Tools" but the content still starts with # Tools, which will usually render as a second H1 in Docusaurus. Remove the Markdown H1 (or drop the frontmatter title) to avoid duplicate titles on the page.
Comment on lines
+1
to
7
| --- | ||
| title: "Installation" | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Installation | ||
|
|
There was a problem hiding this comment.
This doc has both a frontmatter title and a top-level # Installation heading. Docusaurus typically renders the title as an H1 already, so this can produce duplicate H1s. Suggest removing the Markdown H1 (or removing title from frontmatter) for a single page title.
Comment on lines
+1
to
7
| --- | ||
| title: "Usage Guide" | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Usage guide | ||
|
|
There was a problem hiding this comment.
This doc sets a frontmatter title and also begins with # Usage guide, which commonly results in two H1s in Docusaurus (title + content H1). Consider removing the Markdown H1 (or removing the frontmatter title) so the page has a single H1.
Comment on lines
+88
to
+90
| <details open> | ||
| <summary>Enable\\disable specific sub-sections</summary> | ||
|
|
There was a problem hiding this comment.
The <summary> text contains Enable\\disable, which will render with literal backslashes. It looks like this was intended to be “Enable/disable”. Update the summary text to use a slash (or plain words) instead of escaping backslashes.
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Comment on lines
+1
to
+4
| --- | ||
| title: "Overview" | ||
| sidebar_position: 1 | ||
| --- |
Contributor
There was a problem hiding this comment.
1. Yaml front matter in docs/ 📘 Rule violation ≡ Correctness
Multiple documentation pages under docs/ introduce YAML front matter blocks (--- ... ---). This violates the requirement to keep MkDocs-style markdown in docs/ without YAML front matter, risking broken rendering/navigation under the documented convention.
Agent Prompt
## Issue description
Docs under `docs/` now contain YAML front matter (`--- ... ---`), which violates the repo's MkDocs markdown convention rule (no YAML front matter under `docs/`).
## Issue Context
Docusaurus supports titles/order via `sidebars.js` and/or H1 headings; the metadata currently expressed as `title`/`sidebar_position` in front matter can be moved to the sidebar configuration (or inferred from headings) to avoid YAML blocks in markdown.
## Fix Focus Areas
- docs/docs/index.md[1-4]
- docs/docs/core-abilities/index.md[1-4]
- docs/docs/tools/describe.md[1-5]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What changed
Framework
docusaurus.config.js,sidebars.js,package.jsonindocs/mkdocs.yml,overrides/, legacy.gitbook.yamlNavigation restructure
Markdown conversion (97 syntax instances)
!!!→:::)???→<details>)===→<Tabs>/<TabItem>MDX){width=N}→<img>)markdown="1")Infrastructure
.github/workflows/docs-ci.yamlfor Node.js 20 + Docusaurus build@docusaurus/plugin-google-tag-manager@easyops-cn/docusaurus-search-localqodo-merge-docs.qodo.aiScreenshots
Get Started (Light)
Tools - Improve (with Tabs component)
Tools - Review (with collapsible sections)
FAQ (with Data Privacy in sidebar)
Core Abilities - Fetching Ticket Context
Dark Mode
Test plan
npm run buildcompletes with zero errors