[WIP] docs: migrate documentation to Docusaurus#5382
[WIP] docs: migrate documentation to Docusaurus#5382Jont828 wants to merge 1 commit intoai-dynamo:mainfrom
Conversation
|
👋 Hi Jont828! Thank you for contributing to ai-dynamo/dynamo. Just a reminder: The 🚀 |
github-actions
bot
added
the
external-contribution
WalkthroughThis pull request migrates the NVIDIA Dynamo documentation from Sphinx to Docusaurus 3.9.2, replacing RST-based configurations with Markdown and modern tooling. The migration includes updating navigation structure, adding YAML front matter to documentation files, converting asset paths, and updating hyperlinks throughout the documentation. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 16
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (11)
docs/docs/multimodal/index.md (1)
32-35: Empty section: Add content or remove the heading.The "Backend Documentation" heading has no content beneath it. Since the toctree navigation was moved to the Docusaurus sidebar, this section should either:
- Include introductory text about the backend-specific pages
- List the backends with links (vLLM, TRT-LLM, SGLang)
- Be removed if it serves no purpose
Empty sections reduce documentation quality and can confuse readers.
docs/docs/agents/tool-calling.md (1)
21-21: Fix mismatched quote in bash command.The command has a closing quote without an opening quote.
✏️ Proposed fix
-python -m dynamo.<backend> --help" +python -m dynamo.<backend> --helpdocs/docs/backends/trtllm/llama4_plus_eagle.md (2)
35-35: Fix extra parenthesis in configuration note.The note has an extra opening parenthesis that makes the formatting unclear.
✏️ Proposed fix
-* Make sure the (`eagle3_one_model: true`) is set in the LLM API config inside the `examples/backends/trtllm/engine_configs/llama4/eagle` folder. +* Make sure `eagle3_one_model: true` is set in the LLM API config inside the `examples/backends/trtllm/engine_configs/llama4/eagle` folder.
41-41: Complete the incomplete sentence.The comment text appears incomplete.
✏️ Proposed fix
-following environment variables based: +following environment variables:Or if there was meant to be additional context:
-following environment variables based: +following environment variables based on your setup:docs/docs/backends/trtllm/gpt-oss.md (1)
217-219: Typo: "ususally" should be "usually".📝 Suggested fix
-is that the application has a set of tools to aid the assistant provide accurate answer, and it is ususally +is that the application has a set of tools to aid the assistant provide accurate answer, and it is usuallydocs/docs/backends/sglang/gpt-oss.md (1)
13-13: Fix typo in documentation text.Line 13 contains "ues" which should be "use".
📝 Proposed fix
-please ues the vLLM guide as a reference with the different deployment steps as highlighted below: +please use the vLLM guide as a reference with the different deployment steps as highlighted below:docs/docs/backends/vllm/prompt-embeddings.md (1)
257-258: Use consistent README.md link format with other vLLM backend files.Lines 257–258 use bare relative paths (
README.md), but other files in the same directory use more explicit formats:./README.md(lines 31, 124 in speculative_decoding.md) or absolute paths like/docs/backends/vllm/README.md(gpt-oss.md line 23). Update these links to use./README.mdor the absolute path format for consistency.docs/docs/backends/vllm/multi-node.md (2)
86-90: Fix missing line continuation backslash.Line 87 is missing the backslash (
\) at the end, which will cause the multi-line command to fail when executed. The command will terminate after the--modelargument, and subsequent lines will be treated as separate commands.🐛 Proposed fix
# Start prefill worker python -m dynamo.vllm \ - --model meta-llama/Llama-3.3-70B-Instruct + --model meta-llama/Llama-3.3-70B-Instruct \ --tensor-parallel-size 8 \ --enforce-eager
94-100: Fix missing line continuation backslash.Line 96 is missing the backslash (
\) at the end, causing the same issue as the previous command block.🐛 Proposed fix
# Start decode worker python -m dynamo.vllm \ - --model meta-llama/Llama-3.3-70B-Instruct + --model meta-llama/Llama-3.3-70B-Instruct \ --tensor-parallel-size 8 \ --enforce-eager \ --is-prefill-workerdocs/README.md (1)
164-199: Remove Sphinx-specific troubleshooting content.This section still contains Sphinx-specific troubleshooting guidance that's no longer relevant after migrating to Docusaurus:
- Lines 164-171: References
dependency-groupsand Sphinx packages- Lines 173-182: Mentions Sphinx-specific build warnings (toctree entries, headers)
- Lines 185-189: References
uvand.venv-docs(Sphinx tooling)- Lines 192-199: Uses old Sphinx build output paths (
docs/build/html)🧹 Recommended replacement
Replace with Docusaurus-specific troubleshooting:
## Troubleshooting ### Build Errors Common issues when building the documentation: - **Broken links**: Run `npm run build` to check for broken internal links - **Missing dependencies**: Run `npm install` to ensure all packages are installed - **Cache issues**: Run `npm run clear` to clear the Docusaurus cache ### Port Already in Use If `npm run start` fails because port 3000 is in use: ```bash # Kill the process using port 3000 lsof -ti:3000 | xargs kill -9 # Or use a different port npm run start -- --port 3001Viewing Built Documentation
After building with
npm run build, serve the production build:npm run serve # Opens http://localhost:3000</details> </blockquote></details> <details> <summary>docs/docs/kvbm/kvbm_integrations.md (1)</summary><blockquote> `32-47`: **Fix trailing space in alt text on line 32.** The image files are correctly placed at `docs/static/img/` and the absolute paths (`/img/`) are properly configured for Docusaurus. However, line 32 has a trailing space in the alt text: `` should be ``. <details> <summary>Fix trailing space</summary> ```diff - +
🤖 Fix all issues with AI agents
In @.github/workflows/lint-docs.yaml:
- Line 27: The workflow references a missing config filename (config-file:
.markdownlinkcheck.json); either add a .markdownlinkcheck.json file at the
repository root with the markdown-link-check configuration expected by the
lint-docs workflow, or update the workflow step that uses config-file to point
to an existing config or remove the config-file key; ensure you update the
workflow entry that contains "config-file: .markdownlinkcheck.json" so the
action can find valid settings at runtime.
In @docs/docs/benchmarks/benchmarking.md:
- Around line 1-3: The frontmatter 'title' field is incorrect (it currently
contains the license identifier); update the YAML frontmatter by replacing the
title value with the actual document title (e.g., "Benchmarking") or remove the
erroneous title line so the page uses the correct heading, keeping the SPDX
license only in the existing HTML comment block; ensure the 'title' key is no
longer set to "SPDX-License-Identifier: Apache-2.0".
- Line 112: Replace HTML-escaped angle brackets in the markdown code blocks with
literal angle brackets so copy-paste works: find occurrences of "<" and
">" in the command strings (e.g., the kubectl command shown as "kubectl
port-forward -n <namespace> svc/<frontend-service-name> 8000:8000 >
/dev/null 2>&1 &") and change them to "<namespace>" and
"<frontend-service-name>" (and do the same for the other occurrences noted)
ensuring the content remains inside triple-backtick code blocks.
- Line 104: In docs/docs/benchmarks/benchmarking.md replace the absolute GitHub
URL that points to the installation guide with a relative Docusaurus link so
versioned and local builds resolve correctly; specifically, change the current
absolute link for the installation guide back to [installation
guide](/docs/kubernetes/installation_guide.md) (keep the existing external
GitHub URL for deploy/utils/README as that file is outside the docs and should
remain an absolute link).
In @docs/docs/benchmarks/kv-router-ab-testing.md:
- Line 353: Replace HTML entities `<` and `>` inside inline code and code
blocks with literal angle brackets so placeholders are copy-pastable; e.g.,
change occurrences like `<namespace>` and `<pod-name>` to
`<namespace>` and `<pod-name>` (and any other `<...>` placeholders)
throughout the document (including the other reported occurrences), ensuring
Markdown/Docusaurus rendering uses the literal `<` and `>` in code contexts.
In @docs/docs/design_docs/distributed_runtime.md:
- Around line 48-50: The admonition uses Docusaurus syntax but closes with
Sphinx-style backticks; change the closing delimiter from ``` to ::: so the
block opens with :::caution and closes with ::: to restore correct Docusaurus
admonition rendering.
- Line 69: Replace the hardcoded GitHub URL to push_router.rs in
docs/docs/design_docs/distributed_runtime.md with a relative repository link
(e.g., ../../../../lib/runtime/src/pipeline/network/egress/push_router.rs) or
configure/use Docusaurus link resolution (e.g., @site alias or repo resolver in
docusaurus.config.js) and update the link target text "push_router.rs"
accordingly so the documentation uses a relative/path-resolved reference instead
of the absolute GitHub main-branch URL.
In @docs/docs/kubernetes/webhooks.md:
- Line 239: The file contains HTML-escaped angle-bracket placeholders (e.g.,
"<release>", "<namespace>") that break copy/paste; find and replace
all occurrences of "<" and ">" in docs/kubernetes/webhooks.md with literal
"<" and ">" so placeholders render as "<release>", "<namespace>", etc.; apply
this change to every instance (including the many occurrences listed in the
review such as the lines around 239, 242, 333, 336, 354, 361, 426, 465, 474,
479, 498, 504, 513, 518, 535, 541, 546, 549, 554, 569, 575, 578, 584, 594-595,
598, 613, 635, 642, 645, 652, 657, 700) and ensure all code blocks and inline
code use literal angle brackets so MDX renders correctly.
In @docs/docs/kvbm/kvbm_intro.md:
- Around line 40-48: Remove the RST toctree HTML block (the <div class="toctree"
hidden=""> ... </div> section) from docs/docs/kvbm/kvbm_intro.md because
Docusaurus does not process reStructuredText directives and the site navigation
is already managed by sidebars.ts; simply delete that entire block so the page
content renders correctly and avoids hidden/raw RST text.
In @docs/docs/observability/README.md:
- Line 58: The Markdown link text "do../kubernetes/observability/metrics.md" is
malformed; update that link in the README to
"../kubernetes/observability/metrics.md" so the path points correctly to the
Kubernetes observability metrics doc, ensuring the link uses the correct
relative path string "../kubernetes/observability/metrics.md".
In @docs/docs/planner/planner_intro.md:
- Around line 24-25: Remove the unnecessary backslashes escaping the square
brackets in the markdown link so the link renders correctly: change the text
containing "\[SLA Planner Quick Start
Guide\](/docs/planner/sla_planner_quickstart.md)" to use regular brackets " [SLA
Planner Quick Start Guide](/docs/planner/sla_planner_quickstart.md)" (i.e.,
remove the backslashes around "SLA Planner Quick Start Guide").
- Around line 34-46: The file contains 13 leftover conversion artifact lines
that consist solely of "||" markers; remove those lines from planner_intro.md
and ensure no stray empty lines remain or broken markdown/table placeholders;
after deletion, preview the rendered doc to confirm spacing and any intended
table or content around the former artifact is intact and adjust adjacent
markdown (headers, lists, or tables) if necessary.
- Around line 20-32: Replace the raw HTML Sphinx-style block (<div
class="admonition seealso"> ... </div>) with a Docusaurus native admonition
block using the triple-colon syntax (e.g., :::note or :::info) and include the
“Quick Start” title and the same inner content; locate the HTML div with
class="admonition seealso" in planner_intro.md and convert it to an appropriate
Docusaurus admonition (choose :::tip/:::info/:::note as fits the semantics)
ensuring the inner markdown (links and bold text) remains unchanged and close
the block with the matching triple-colon.
In @docs/DOCUSAURUS_MIGRATION_PLAN.md:
- Around line 421-438: The REPLACEMENTS entry that uses the generic pattern
r'```' will replace every triple-backtick (breaking normal code blocks); update
the REPLACEMENTS logic so only MyST admonition markers are targeted (e.g.,
convert the specific patterns like r'```{note}', r'```{warning}', r'```{tip}',
r'```{caution}', r'```{danger}' while removing or escaping the generic r'```'
rule), and implement handling for admonition closers either by (A) matching
entire admonition blocks at once (a single regex that captures ```{type} ... ```
and replaces with the corresponding :::type ... :::) or (B) adding a simple
stateful parser around REPLACEMENTS that tracks when you're inside an admonition
and only converts the closing triple-backticks for those blocks; ensure changes
are made where REPLACEMENTS is defined and referenced so regular code fences
remain untouched.
In @docs/MIGRATION_COMPLETE.md:
- Around line 48-62: Update the incorrect directory path in the Docusaurus
commands: replace the "cd docs/docusaurus" invocation with "cd docs" in the code
block (the shell commands for starting, building, serving, and clearing the
site) so the development commands point to the relocated Docusaurus project
referenced in Phase 4.
🟡 Minor comments (14)
docs/docs/guides/request_plane.md-189-189 (1)
189-189: Use relative paths instead of hardcoded GitHub URLs.The absolute GitHub URL has several issues:
- Branch mismatch: Points to
mainbranch, but this PR is ondocusaurus-migration— the link won't resolve correctly until merged.- Portability: Hardcoded GitHub URLs break in local development, alternative hosting, or if the repository is forked.
- Inconsistency: Line 196 references the same file using a relative path, while line 189 uses an absolute URL.
Docusaurus supports relative links that work across different deployment scenarios.
📝 Suggested fix using relative path
-See [`examples/backends/vllm/launch/agg_request_planes.sh`](https://github.com/ai-dynamo/dynamo/tree/main/examples/backends/vllm/launch/agg_request_planes.sh) for a complete working example that demonstrates launching Dynamo with TCP, HTTP, or NATS request planes. +See [`examples/backends/vllm/launch/agg_request_planes.sh`](../../../examples/backends/vllm/launch/agg_request_planes.sh) for a complete working example that demonstrates launching Dynamo with TCP, HTTP, or NATS request planes.Alternatively, if the examples are outside the docs directory and won't be published with the docs, you could link to the repository root or use a Docusaurus config-based URL prefix.
docs/docs/backends/vllm/speculative_decoding.md-1-3 (1)
1-3: Remove Markdown formatting from the front matter title.In Docusaurus 3.9.2, the front-matter title field is treated as plain text and does not process Markdown syntax. The
**Meta-Llama-3.1-8B-Instruct**will appear as literal asterisks in sidebar navigation, browser tabs, and metadata.📝 Suggested fix
--- -title: "Running **Meta-Llama-3.1-8B-Instruct** with Speculative Decoding (Eagle3)" +title: "Running Meta-Llama-3.1-8B-Instruct with Speculative Decoding (Eagle3)" ---docs/docs/frontends/kserve.md-94-95 (1)
94-95: Fix hyphenation: "client side" should be "client-side".When used as an adjective before a noun, compound modifiers should be hyphenated for clarity.
📝 Proposed fix
-* [triton_model_config](https://github.com/ai-dynamo/dynamo/tree/main/lib/llm/src/protocols/tensor.rs): For users that already have Triton model config and require the full config to be returned for client side logic, they can set the config in `TensorModelConfig::triton_model_config` which will supersedes other fields in `TensorModelConfig` and be used for endpoint responses. `triton_model_config` is expected to be the serialized string of the `ModelConfig` protobuf message, see [echo_tensor_worker.py](https://github.com/ai-dynamo/dynamo/tree/main/tests/frontend/grpc/echo_tensor_worker.py) for example. +* [triton_model_config](https://github.com/ai-dynamo/dynamo/tree/main/lib/llm/src/protocols/tensor.rs): For users that already have Triton model config and require the full config to be returned for client-side logic, they can set the config in `TensorModelConfig::triton_model_config` which will supersedes other fields in `TensorModelConfig` and be used for endpoint responses. `triton_model_config` is expected to be the serialized string of the `ModelConfig` protobuf message, see [echo_tensor_worker.py](https://github.com/ai-dynamo/dynamo/tree/main/tests/frontend/grpc/echo_tensor_worker.py) for example.lib/runtime/README.md-40-42 (1)
40-42: Add language specification to the code block.The fenced code block should specify a language identifier for proper syntax highlighting.
📝 Proposed fix
-``` +```bash cargo build cargo test</details> </blockquote></details> <details> <summary>docs/MIGRATION_COMPLETE.md-16-40 (1)</summary><blockquote> `16-40`: **Add language specification to the directory structure code block.** The fenced code block should specify a language identifier (e.g., "plaintext") for consistency. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```plaintext docs/ ├── docusaurus.config.ts # Main Docusaurus configuration ...lib/runtime/README.md-86-96 (1)
86-96: Add language specification to code blocks.Both code blocks should specify a language identifier for proper syntax highlighting.
📝 Proposed fix
-``` +```bash cd examples/hello_world cargo run --bin serverIn the second terminal, execute:
-
+bash
cd examples/hello_world
cargo run --bin clientlib/runtime/README.md-51-56 (1)
51-56: Add language specification to code block.The code block is missing a language identifier for proper syntax highlighting.
📝 Proposed fix
-``` +```bash # At the root of the repository: docker compose -f deploy/docker-compose.yml up -d</details> </blockquote></details> <details> <summary>docs/docs/backends/trtllm/README.md-218-227 (1)</summary><blockquote> `218-227`: **Duplicate content: Client and Benchmarking sections repeated.** Lines 218-227 duplicate the content from lines 175-184. The "Client" and "Benchmarking" sections appear twice in the document. <details> <summary>🧹 Proposed fix to remove duplicate sections</summary> ```diff -## Client - -See [client](../../backends/sglang/README.md#testing-the-deployment) section to learn how to send request to the deployment. - -NOTE: To send a request to a multi-node deployment, target the node which is running `python3 -m dynamo.frontend <args>`. - -## Benchmarking - -To benchmark your deployment with AIPerf, see this utility script, configuring the -`model` name and `host` based on your deployment: [perf.sh](https://github.com/ai-dynamo/dynamo/tree/main/benchmarks/llm/perf.sh) - ## Multimodal supportbenchmarks/profiler/README.md-154-161 (1)
154-161: Update TensorRT-LLM version list to match official AIConfigurator support.The version 1.0.0rc6 is listed but not documented in the official AIConfigurator support list, which only confirms 0.20.0 and 1.0.0rc3. Consider verifying the supported versions with the AI Configurator documentation to ensure accuracy, as the listed versions may not reflect the current officially supported backend versions.
docs/docs/api/nixl_connect/README.md-185-185 (1)
185-185: Fix list indentation.The list item has incorrect indentation according to Markdown linting rules (expected 0 spaces, actual 2 spaces).
Based on coding guidelines, markdownlint rule MD007 should be addressed.
📝 Proposed fix
- - [Dynamo Multimodal Example](https://github.com/ai-dynamo/dynamo/tree/main/examples/multimodal) +- [Dynamo Multimodal Example](https://github.com/ai-dynamo/dynamo/tree/main/examples/multimodal)docs/docs/kvbm/kvbm_design_deepdive.md-1-3 (1)
1-3: Change title to match filename and content.The file
kvbm_design_deepdive.mdhas front matter title"KVBM components", which conflicts with the existingkvbm_components.md(titled "Understanding KVBM components") and misaligns with the filename. The actual content discusses KvBlockManager architecture and memory mapping—a design deep dive, not a components overview. Update the title to"KVBM Design Deep Dive"or another title that accurately reflects the filename and content focus.docs/docs/kvbm/kvbm_intro.md-30-38 (1)
30-38: Remove empty table row artifacts.These lines appear to be conversion artifacts or placeholders that render as broken/empty table cells. They should be removed as they have no semantic meaning.
🧹 Proposed fix
-|| -|| -|| -|| -|| -|| -|| -|| -||docs/docusaurus.config.ts-29-36 (1)
29-36: Address deprecatedonBrokenMarkdownLinksoption inmarkdown.hooks.The
onBrokenMarkdownLinksoption undermarkdown.hooksis valid in Docusaurus 3.x, but was deprecated in v3.9 and will be removed in v4. Consider verifying your Docusaurus version and planning to remove or replace this option before upgrading to v4.docs/src/components/HomepageFeatures/index.tsx-12-43 (1)
12-43: Remove unused HomepageFeatures component or implement it properly before use.This component is not imported or used anywhere in the codebase. The FeatureList contains default Docusaurus boilerplate (with references to Docusaurus rather than NVIDIA Dynamo), and the three SVG files it requires do not exist in
docs/static/img/(only PNG/JPG files are present).Either delete this unused component or, if intended for future use, customize the feature titles, descriptions, and SVG assets to reflect Dynamo's capabilities before enabling it.
🧹 Nitpick comments (25)
docs/docs/benchmarks/kv-router-ab-testing.md (1)
578-578: Optional: Simplify HTML entities in prose.HTML entity escaping (
<) is unnecessary for comparison operators in regular Markdown prose. Docusaurus handles literal<symbols correctly in text content.✨ Proposed simplification
-- **Short prompts** (<1000 tokens) where routing overhead exceeds benefit +- **Short prompts** (<1000 tokens) where routing overhead exceeds benefit-- **Low prefix overlap**: <5% improvement (may not be worth enabling) +- **Low prefix overlap**: <5% improvement (may not be worth enabling)-- KV router shows <10% improvement +- KV router shows <10% improvementAlso applies to: 585-585, 593-593
docs/docs/backends/trtllm/gemma3_sliding_window_attention.md (1)
1-3: LGTM! Front matter correctly formatted for Docusaurus.The YAML front matter follows Docusaurus conventions with proper delimiters and a clear title field. The title matches the H1 heading on line 22, which creates consistency.
Optional: Consider removing duplicate title.
Since Docusaurus typically renders the front matter title as the page heading, the H1 on line 22 may be redundant. However, if this duplicate-title pattern is intentional across the migration (as suggested by the PR's systematic approach), it's acceptable for markdown readability.
docs/docs/agents/tool-calling.md (1)
32-33: Add blank line before table for better Markdown compatibility.While many Markdown parsers handle this, adding a blank line between the heading and table is a best practice that ensures consistent rendering across all parsers.
📝 Proposed improvement
Parser to Model Mapping + | Parser Name | Supported Models |docs/docs/backends/trtllm/kv-cache-transfer.md (1)
33-33: TODO: Complete NIXL backend configuration instructions.This section needs instructions for specifying different backends for NIXL.
Would you like me to help draft the documentation for NIXL backend configuration, or open an issue to track this task?
docs/docs/backends/sglang/profiling.md (1)
43-43: Use a relative link instead of the absolute GitHub URL for better maintainability.The file exists, so the link target is valid. However, the absolute GitHub URL pointing to the
mainbranch is less maintainable than a relative link. Since the documentation already uses a relative path on line 46 (python examples/backends/sglang/test_sglang_profile.py), consider using a consistent relative link format:[`examples/backends/sglang/test_sglang_profile.py`](../../../examples/backends/sglang/test_sglang_profile.py)This approach avoids hardcoding branch names and ensures the link remains valid if the repository is renamed or reorganized.
.github/workflows/lint-docs.yaml (1)
1-11: Consider adding workflow trigger for the config file.If
.markdownlinkcheck.jsonis modified, the workflow won't run since it only triggers on.mdfile changes. Consider adding the config file to the paths filter.Proposed enhancement
on: push: paths: - "**.md" + - ".markdownlinkcheck.json" branches: - main pull_request: - paths: "**.md" + paths: + - "**.md" + - ".markdownlinkcheck.json"docs/docs/backends/sglang/README.md (1)
31-33: Minor heading case inconsistency.The TOC entry "Disaggregated Serving" (line 32) uses title case, but the actual heading on line 221 uses "Disaggregated serving" (sentence case). While anchor links are typically case-insensitive, consider aligning the casing for consistency.
docs/package.json (2)
17-28: Inconsistent version pinning for Docusaurus packages.Some Docusaurus packages use exact versions (
3.9.2) while others use caret ranges (^3.9.2). For reproducible builds and to avoid potential compatibility issues, consider using consistent pinning.Proposed fix for consistent pinning
"dependencies": { "@docusaurus/core": "3.9.2", - "@docusaurus/plugin-client-redirects": "^3.9.2", + "@docusaurus/plugin-client-redirects": "3.9.2", "@docusaurus/preset-classic": "3.9.2", - "@docusaurus/theme-mermaid": "^3.9.2", + "@docusaurus/theme-mermaid": "3.9.2",
1-50: Add a lockfile for reproducible builds.Commit a
package-lock.json(for npm),yarn.lock(for yarn), orpnpm-lock.yaml(for pnpm) alongsidepackage.jsonto ensure consistent dependency versions in CI/CD pipelines.docs/docs/observability/prometheus-grafana.md (1)
86-86: Consider linking to a stable version tag instead of the main branch.The GitHub URL is accessible and the file exists, but hardcoding
maincreates a moving target. Documentation should ideally link to specific release versions or tags (e.g.,v1.0.0) to ensure the referenced configuration remains consistent with the deployed version being documented.docs/docs/backends/trtllm/README.md (2)
177-177: Consider creating shared client documentation instead of cross-referencing backend-specific README sections.The TensorRT-LLM documentation references the SGLang backend's README (line 177 and elsewhere) for client testing instructions via
../../backends/sglang/README.md#testing-the-deployment. While this reference currently works, it creates architectural coupling where the TensorRT-LLM docs depend on SGLang's documentation structure. If client interactions are similar across backends, consider:
- Creating a shared
docs/docs/client.mdpage with general client instructions- Duplicating essential client instructions in each backend's documentation
- Maintaining a common "Getting Started" or "Usage" guide
This would improve long-term maintainability and reduce the risk of broken references if backend documentation is reorganized.
58-63: Consider removing.mdextensions from internal documentation links for Docusaurus consistency.The referenced documentation files all exist, but these links use
.mdextensions. While this works, Docusaurus 2.x convention is to omit the extension for better compatibility. The repository itself uses mixed patterns—some links include.mdwhile others omit it. Removing the extension would align with Docusaurus best practices:-| [**Disaggregated Serving**](../../design_docs/disagg_serving.md) | ✅ | | +| [**Disaggregated Serving**](../../design_docs/disagg_serving) | ✅ | | -| [**Conditional Disaggregation**](../../design_docs/disagg_serving.md#conditional-disaggregation) | 🚧 | Not supported yet | +| [**Conditional Disaggregation**](../../design_docs/disagg_serving#conditional-disaggregation) | 🚧 | Not supported yet |Apply the same change to lines 60–63.
docs/DOCUSAURUS_MIGRATION_PLAN.md (3)
198-199: Consider stricter link checking for production.The configuration sets
onBrokenLinks: 'warn'which allows builds with broken links. For production documentation, consider using'throw'to catch broken links during CI/CD builds.🔗 Suggested configuration for stricter link validation
- onBrokenLinks: 'warn', - onBrokenMarkdownLinks: 'warn', + onBrokenLinks: 'throw', // Fail builds on broken links in CI + onBrokenMarkdownLinks: 'throw',Alternatively, you could use environment-based configuration:
onBrokenLinks: process.env.NODE_ENV === 'production' ? 'throw' : 'warn',
87-113: Add language identifier to code block for better syntax highlighting.The directory structure code block lacks a language identifier, which prevents proper syntax highlighting and triggers linting warnings.
📝 Suggested improvement
-**New Structure:** -``` +**New Structure:** +```text docs/ ├── docusaurus/ # New Docusaurus project
768-768: Convert emphasized text to proper metadata format.The closing line uses emphasis instead of a proper heading or metadata format, which triggers a linting warning.
📝 Suggested alternatives
Option 1 - Remove emphasis:
--- -*Document updated: January 2026* +Document updated: January 2026Option 2 - Move to front matter:
--- +last_updated: January 2026 -*Document updated: January 2026*docs/docs/benchmarks/benchmarking.md (1)
81-81: Explicit anchor may be redundant.Docusaurus automatically generates heading anchors from the heading text. The explicit anchor
{#client-side-benchmarking-local}matches what Docusaurus would auto-generate, making it redundant.You can simplify to:
## Client-Side Benchmarking (Local)Only use explicit anchors when you need a different ID than the auto-generated one (e.g., for backward compatibility with old links).
docs/README.md (1)
1-3: Remove Sphinx-specific front matter.The
orphan: truedirective is Sphinx-specific and has no effect in Docusaurus. While it won't cause errors, it should be removed as part of the migration cleanup.🧹 Suggested cleanup
Either remove the front matter entirely if no Docusaurus-specific metadata is needed:
---- -orphan: true ---- - # NVIDIA Dynamo DocumentationOr replace with Docusaurus-appropriate metadata:
--- -orphan: true +sidebar_position: 0 +title: Documentation Guide ---benchmarks/profiler/README.md (2)
100-107: Apply hyphenation for compound adjectives.Several compound adjectives need hyphens for proper grammar:
- Line 103: "per GPU throughput" → "per-GPU throughput"
- Line 107: "computation bound MLP kernel" → "computation-bound MLP kernel"
Additionally, consider using "resolve" instead of "fix" in line 101 for more formal technical documentation.
✏️ Suggested style improvements
- - However, for MoE models, this is not guaranteed because the kv cache in different attention DP ranks is different. We are working on framework-side change to fix this issue. For example, the below plot shows the decode parallelization mapping sweep results for H100 for deepseek-ai/DeepSeek-R1-Distill-Llama-8B. + - However, for MoE models, this is not guaranteed because the kv cache in different attention DP ranks is different. We are working on framework-side change to resolve this issue. For example, the below plot shows the decode parallelization mapping sweep results for H100 for deepseek-ai/DeepSeek-R1-Distill-Llama-8B.  -4. **Recommendation**: Selects optimal parallelization mapping for prefill and decode that achieves the highest per GPU throughput while adhering the SLA on TTFT and ITL. Specifically, the profiler will choose the point (or a point on the curve for decode) that is left to the vertical red dashed line that represents the SLAs while has the highest y coordinate (throughput per GPU). +4. **Recommendation**: Selects optimal parallelization mapping for prefill and decode that achieves the highest per-GPU throughput while adhering the SLA on TTFT and ITL. Specifically, the profiler will choose the point (or a point on the curve for decode) that is left to the vertical red dashed line that represents the SLAs while has the highest y coordinate (throughput per GPU). 5. **In-Depth Profiling on the Recommended P/D Engine**: After finding the best TP size for prefill and decode, the script will then interpolate the TTFT with ISL and ITL with active KV cache and decode context length. This is to provide a more accurate estimation of the performance when ISL and OSL changes and will be used in the sla-planner.  - **Prefill**: Measures TTFT and throughput per GPU across different input lengths with batch size=1. - - **Decode**: Measures ITL and throughput per GPU under various KV cache loads and decode context lengths. The active kv usage determines the complexity of the memory-bounded attention kernel while the active kv usage divided the average context length determines the complexity of the computation bound MLP kernel. For example, the below figure shows the ITL of DS-Distilled Llama 8b model on H100 TP4. The ITL grows near-linearly with active kv usage under a fixed context length. And the slope increases as the context length decreases. + - **Decode**: Measures ITL and throughput per GPU under various KV cache loads and decode context lengths. The active kv usage determines the complexity of the memory-bounded attention kernel while the active kv usage divided the average context length determines the complexity of the computation-bound MLP kernel. For example, the below figure shows the ITL of DS-Distilled Llama 8b model on H100 TP4. The ITL grows near-linearly with active kv usage under a fixed context length. And the slope increases as the context length decreases.
560-560: Use literal<character instead of HTML entity.Line 560 uses
<where a literal<character would be clearer and is safe in this Markdown context.✏️ Simplify HTML entity
-- Most models **<1B parameters**: May hit this constraint +- Most models **<1B parameters**: May hit this constraintdocs/docs/planner/sla_planner.md (1)
28-28: Prefer relative links over hardcoded GitHub URLs for internal repository files.The absolute GitHub URL pointing to the
mainbranch creates version-sync issues: readers viewing versioned documentation will always see the latest main branch code, which may not match their documentation version. Additionally, the link won't work in offline documentation or forked repositories.♻️ Suggested fix: Use a relative path
-The adjustment interval can be defined in the planner manifest as an argument. The default interval value can be found in this [file](https://github.com/ai-dynamo/dynamo/tree/main/components/src/dynamo/planner/defaults.py). +The adjustment interval can be defined in the planner manifest as an argument. The default interval value can be found in this [file](../../components/src/dynamo/planner/defaults.py).Note: Adjust the relative path (
../../components/...) based on the actual location of thecomponentsdirectory relative todocs/docs/planner/. If the components directory is outside the docs structure, consider using a Docusaurus alias or keeping a reference to the file path without making it a clickable link.docs/docs/reference/glossary.md (1)
36-36: Minor: Missing trailing period for consistency.Other glossary definitions end with periods, but this one doesn't.
Suggested fix
-**Instance** - A running process with a unique `instance_id`. Multiple instances can serve the same namespace, component, and endpoint for load balancing +**Instance** - A running process with a unique `instance_id`. Multiple instances can serve the same namespace, component, and endpoint for load balancing.docs/docs/intro.md (1)
12-12: Consider simplifying redundant phrase.The phrase "a specific point in time" can be simplified to "a specific point" or "a specific time" for more concise writing.
✍️ Proposed simplification
-This guide is a snapshot of a specific point in time. For the latest information, examples, and Release Assets, see the [Dynamo GitHub repository](https://github.com/ai-dynamo/dynamo/releases/latest). +This guide is a snapshot of a specific point. For the latest information, examples, and Release Assets, see the [Dynamo GitHub repository](https://github.com/ai-dynamo/dynamo/releases/latest).Based on learnings from static analysis hints.
docs/docs/backends/vllm/README.md (1)
65-65: Consider using relative paths instead of absolute GitHub URLs.These links point to absolute GitHub URLs on the
mainbranch:
- Line 65:
https://github.com/ai-dynamo/dynamo/tree/main/deploy/docker-compose.yml- Line 150:
https://github.com/ai-dynamo/dynamo/tree/main/examples/backends/vllm/deploy/README.mdIf these files are also part of the docs site or get moved, these links could become stale. If they must remain external, consider whether versioned links would be more appropriate for release branches.
Also applies to: 150-150
docs/docusaurus.config.ts (1)
74-75: Mixing CommonJSrequire.resolvewith ES module imports.The config uses ES module imports at the top but
require.resolvefor the search plugin. While this works in Docusaurus's TypeScript config, for consistency you could use a string path or verify this pattern is intentional.Alternative using string identifier
- require.resolve('@easyops-cn/docusaurus-search-local'), + '@easyops-cn/docusaurus-search-local',docs/src/components/HomepageFeatures/index.tsx (1)
45-57: Consider adding accessible label for SVGs.The
role="img"attribute is good, but screen readers won't have meaningful content to announce. Consider adding anaria-labelattribute based on the feature title.♿ Optional accessibility enhancement
function Feature({title, Svg, description}: FeatureItem) { return ( <div className={clsx('col col--4')}> <div className="text--center"> - <Svg className={styles.featureSvg} role="img" /> + <Svg className={styles.featureSvg} role="img" aria-label={title} /> </div> <div className="text--center padding-horiz--md"> <Heading as="h3">{title}</Heading> <p>{description}</p> </div> </div> ); }
| - uses: tcort/github-action-markdown-link-check@e7c7a18363c842693fadde5d41a3bd3573a7a225 # v1.1.2 | ||
| with: | ||
| use-quiet-mode: 'yes' | ||
| config-file: .markdownlinkcheck.json |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the markdownlinkcheck config file exists
fd -t f "markdownlinkcheck.json" --max-depth 2Repository: ai-dynamo/dynamo
Length of output: 42
🏁 Script executed:
#!/bin/bash
# Broader search for the markdownlinkcheck config file
find . -name "*markdownlinkcheck*" -o -name ".markdownlinkcheck*" 2>/dev/nullRepository: ai-dynamo/dynamo
Length of output: 42
Add the .markdownlinkcheck.json config file to the repository root.
The workflow references .markdownlinkcheck.json at line 27, but this file does not exist in the repository. The workflow will fail without this configuration file. Either add the missing config file or update the workflow to reference an existing configuration.
🤖 Prompt for AI Agents
In @.github/workflows/lint-docs.yaml at line 27, The workflow references a
missing config filename (config-file: .markdownlinkcheck.json); either add a
.markdownlinkcheck.json file at the repository root with the markdown-link-check
configuration expected by the lint-docs workflow, or update the workflow step
that uses config-file to point to an existing config or remove the config-file
key; ensure you update the workflow entry that contains "config-file:
.markdownlinkcheck.json" so the action can find valid settings at runtime.
| --- | ||
| title: "SPDX-License-Identifier: Apache-2.0" | ||
| --- |
There was a problem hiding this comment.
Fix incorrect title in frontmatter.
The title field contains the license identifier instead of the actual document title. This will cause Docusaurus to display "SPDX-License-Identifier: Apache-2.0" as the page title in the browser tab and navigation.
📝 Proposed fix
---
-title: "SPDX-License-Identifier: Apache-2.0"
+title: "Benchmarking Guide"
---The license information is already present in the HTML comment block (lines 5-18) and doesn't need to be in the title field.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: "SPDX-License-Identifier: Apache-2.0" | |
| --- | |
| --- | |
| title: "Benchmarking Guide" | |
| --- |
🤖 Prompt for AI Agents
In @docs/docs/benchmarks/benchmarking.md around lines 1 - 3, The frontmatter
'title' field is incorrect (it currently contains the license identifier);
update the YAML frontmatter by replacing the title value with the actual
document title (e.g., "Benchmarking") or remove the erroneous title line so the
page uses the correct heading, keeping the SPDX license only in the existing
HTML comment block; ensure the 'title' key is no longer set to
"SPDX-License-Identifier: Apache-2.0".
|
|
||
| ### Step 1: Establish Kubernetes Cluster and Install Dynamo | ||
| Set up your Kubernetes cluster with NVIDIA GPUs and install the Dynamo Kubernetes Platform. First follow the [installation guide](/docs/kubernetes/installation_guide.md) to install Dynamo Kubernetes Platform, then use [deploy/utils/README](../../deploy/utils/README.md) to set up benchmarking resources. | ||
| Set up your Kubernetes cluster with NVIDIA GPUs and install the Dynamo Kubernetes Platform. First follow the [installation guide](/docs/kubernetes/installation_guide.md) to install Dynamo Kubernetes Platform, then use [deploy/utils/README](https://github.com/ai-dynamo/dynamo/tree/main/deploy/utils/README.md) to set up benchmarking resources. |
There was a problem hiding this comment.
Reconsider using absolute GitHub URLs for internal documentation.
The link to /docs/kubernetes/installation_guide.md has been changed to an absolute GitHub URL. For internal documentation that's part of the same repository, relative links are preferred in Docusaurus because they:
- Work with versioning (link to the same version of the doc)
- Work offline and in local builds
- Are validated at build time for broken links
🔗 Recommended approach
For documentation files that are part of the docs:
-First follow the [installation guide](/docs/kubernetes/installation_guide.md) to install Dynamo Kubernetes Platform, then use [deploy/utils/README](https://github.com/ai-dynamo/dynamo/tree/main/deploy/utils/README.md) to set up benchmarking resources.
+First follow the [installation guide](/kubernetes/installation_guide.md) to install Dynamo Kubernetes Platform, then use the [deploy/utils README](https://github.com/ai-dynamo/dynamo/tree/main/deploy/utils/README.md) to set up benchmarking resources.For files outside the docs directory (like deploy/utils/README.md), GitHub URLs are appropriate since those aren't versioned documentation.
🤖 Prompt for AI Agents
In @docs/docs/benchmarks/benchmarking.md at line 104, In
docs/docs/benchmarks/benchmarking.md replace the absolute GitHub URL that points
to the installation guide with a relative Docusaurus link so versioned and local
builds resolve correctly; specifically, change the current absolute link for the
installation guide back to [installation
guide](/docs/kubernetes/installation_guide.md) (keep the existing external
GitHub URL for deploy/utils/README as that file is outside the docs and should
remain an absolute link).
| ```bash | ||
| # Port-forward the frontend service for deployment A | ||
| kubectl port-forward -n <namespace> svc/<frontend-service-name> 8000:8000 > /dev/null 2>&1 & | ||
| kubectl port-forward -n <namespace> svc/<frontend-service-name> 8000:8000 > /dev/null 2>&1 & |
There was a problem hiding this comment.
Remove HTML entity escaping from code blocks.
The use of <namespace> instead of <namespace> in code blocks breaks copy-paste functionality. Users copying this command will get the HTML entities instead of angle brackets, causing the command to fail.
In Markdown code blocks (triple backticks), angle brackets don't need escaping and should be literal:
🐛 Proposed fix
-kubectl port-forward -n <namespace> svc/<frontend-service-name> 8000:8000 > /dev/null 2>&1 &
+kubectl port-forward -n <namespace> svc/<frontend-service-name> 8000:8000 > /dev/null 2>&1 &The same issue appears on lines 129, 164, 403, 428, and 491. All should use literal angle brackets.
🤖 Prompt for AI Agents
In @docs/docs/benchmarks/benchmarking.md at line 112, Replace HTML-escaped angle
brackets in the markdown code blocks with literal angle brackets so copy-paste
works: find occurrences of "<" and ">" in the command strings (e.g., the
kubectl command shown as "kubectl port-forward -n <namespace>
svc/<frontend-service-name> 8000:8000 > /dev/null 2>&1 &") and change them
to "<namespace>" and "<frontend-service-name>" (and do the same for the other
occurrences noted) ensuring the content remains inside triple-backtick code
blocks.
|
|
||
| **Both must show 8/8 workers in Ready state (1/1 Running).** If workers are not ready: | ||
| - Check logs: `kubectl logs -n <namespace> <pod-name>` | ||
| - Check logs: `kubectl logs -n <namespace> <pod-name>` |
There was a problem hiding this comment.
Critical: HTML entities in code blocks break copy-paste functionality.
HTML entities (< and >) render literally inside code blocks and inline code, preventing users from copying working commands. Markdown/Docusaurus automatically handles angle brackets in code contexts, so literal < and > should be used for placeholders.
Impact: Users copying these commands will get <namespace> instead of <namespace>, requiring manual correction.
🔧 Proposed fix: Use literal angle brackets in code
-- Check logs: `kubectl logs -n <namespace> <pod-name>`
+- Check logs: `kubectl logs -n <namespace> <pod-name>`-kubectl edit dynamographdeployment -n <namespace>
+kubectl edit dynamographdeployment -n <namespace>-- Check operator logs: `kubectl logs -n <namespace> deployment/dynamo-platform-dynamo-operator-controller-manager`
+- Check operator logs: `kubectl logs -n <namespace> deployment/dynamo-platform-dynamo-operator-controller-manager`-kubectl logs -n <namespace> <worker-pod-name>
+kubectl logs -n <namespace> <worker-pod-name>-kubectl patch dynamographdeployment <deployment-name> -n <namespace> --type='json' \
+kubectl patch dynamographdeployment <deployment-name> -n <namespace> --type='json' \-kubectl get pods -n <namespace> -l nvidia.com/dynamo-component-type=worker
+kubectl get pods -n <namespace> -l nvidia.com/dynamo-component-type=worker-kubectl describe pod <pod-name> -n <namespace>
+kubectl describe pod <pod-name> -n <namespace>Also applies to: 651-651, 673-673, 682-682, 704-704, 732-732, 735-735
🤖 Prompt for AI Agents
In @docs/docs/benchmarks/kv-router-ab-testing.md at line 353, Replace HTML
entities `<` and `>` inside inline code and code blocks with literal angle
brackets so placeholders are copy-pastable; e.g., change occurrences like
`<namespace>` and `<pod-name>` to `<namespace>` and `<pod-name>`
(and any other `<...>` placeholders) throughout the document (including
the other reported occurrences), ensuring Markdown/Docusaurus rendering uses the
literal `<` and `>` in code contexts.
| <div class="admonition seealso"> | ||
|
|
||
| 🚀 Quick Start | ||
|
|
||
| **New to SLA Planner?** Start with the \[SLA Planner Quick Start | ||
| Guide\](/docs/planner/sla_planner_quickstart.md) for a complete, | ||
| step-by-step workflow. | ||
|
|
||
| **Prerequisites**: SLA-based planner requires pre-deployment profiling | ||
| (2-4 hours on real silicon or a few minutes using simulator) before | ||
| deployment. The Quick Start guide includes everything you need. | ||
|
|
||
| </div> |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Use Docusaurus-native admonition syntax.
The HTML <div class="admonition seealso"> is Sphinx-style markup. Docusaurus provides native admonition syntax that renders properly and supports theming.
♻️ Proposed refactor to Docusaurus syntax
-<div class="admonition seealso">
-
-🚀 Quick Start
-
-**New to SLA Planner?** Start with the \[SLA Planner Quick Start
-Guide\](/docs/planner/sla_planner_quickstart.md) for a complete,
-step-by-step workflow.
-
-**Prerequisites**: SLA-based planner requires pre-deployment profiling
-(2-4 hours on real silicon or a few minutes using simulator) before
-deployment. The Quick Start guide includes everything you need.
-
-</div>
+:::tip 🚀 Quick Start
+
+**New to SLA Planner?** Start with the [SLA Planner Quick Start Guide](/docs/planner/sla_planner_quickstart.md) for a complete, step-by-step workflow.
+
+**Prerequisites**: SLA-based planner requires pre-deployment profiling (2-4 hours on real silicon or a few minutes using simulator) before deployment. The Quick Start guide includes everything you need.
+
+:::🤖 Prompt for AI Agents
In @docs/docs/planner/planner_intro.md around lines 20 - 32, Replace the raw
HTML Sphinx-style block (<div class="admonition seealso"> ... </div>) with a
Docusaurus native admonition block using the triple-colon syntax (e.g., :::note
or :::info) and include the “Quick Start” title and the same inner content;
locate the HTML div with class="admonition seealso" in planner_intro.md and
convert it to an appropriate Docusaurus admonition (choose
:::tip/:::info/:::note as fits the semantics) ensuring the inner markdown (links
and bold text) remains unchanged and close the block with the matching
triple-colon.
| **New to SLA Planner?** Start with the \[SLA Planner Quick Start | ||
| Guide\](/docs/planner/sla_planner_quickstart.md) for a complete, |
There was a problem hiding this comment.
Fix escaped brackets in markdown link.
The backslashes escaping the square brackets break the markdown link syntax. The link won't render correctly.
Note: This is also addressed in the admonition refactor above (lines 20-32), but calling it out separately as it's a critical syntax error.
🤖 Prompt for AI Agents
In @docs/docs/planner/planner_intro.md around lines 24 - 25, Remove the
unnecessary backslashes escaping the square brackets in the markdown link so the
link renders correctly: change the text containing "\[SLA Planner Quick Start
Guide\](/docs/planner/sla_planner_quickstart.md)" to use regular brackets " [SLA
Planner Quick Start Guide](/docs/planner/sla_planner_quickstart.md)" (i.e.,
remove the backslashes around "SLA Planner Quick Start Guide").
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
| || | ||
|
|
There was a problem hiding this comment.
Remove conversion artifacts.
These 13 lines containing only || markers appear to be leftover artifacts from the Sphinx-to-Docusaurus migration, likely remnants of an RST table or placeholder content.
🧹 Proposed fix
-||
-||
-||
-||
-||
-||
-||
-||
-||
-||
-||
-||
-||🤖 Prompt for AI Agents
In @docs/docs/planner/planner_intro.md around lines 34 - 46, The file contains
13 leftover conversion artifact lines that consist solely of "||" markers;
remove those lines from planner_intro.md and ensure no stray empty lines remain
or broken markdown/table placeholders; after deletion, preview the rendered doc
to confirm spacing and any intended table or content around the former artifact
is intact and adjust adjacent markdown (headers, lists, or tables) if necessary.
| REPLACEMENTS = [ | ||
| # Admonitions: MyST -> Docusaurus | ||
| (r'```{note}', ':::note'), | ||
| (r'```{warning}', ':::warning'), | ||
| (r'```{tip}', ':::tip'), | ||
| (r'```{caution}', ':::caution'), | ||
| (r'```{danger}', ':::danger'), | ||
| (r'```', ':::'), # Close admonitions | ||
|
|
||
| # References | ||
| (r':ref:`([^`]+)`', r'[\1](\1.md)'), | ||
|
|
||
| # Code blocks with sphinx-specific options | ||
| (r'```{code-block} (\w+)', r'```\1'), | ||
|
|
||
| # Remove toctree directives (handled by sidebars.ts) | ||
| (r'```{toctree}[\s\S]*?```', ''), | ||
| ] |
There was a problem hiding this comment.
Fix regex pattern that will break code blocks.
The regex pattern r'```' on line 428 will match and replace ALL triple backticks in the document, not just MyST admonition closers. This will corrupt regular code blocks.
🐛 Proposed fix for the admonition closing pattern
The admonition conversion needs a more sophisticated approach since MyST admonitions and code blocks both use triple backticks:
REPLACEMENTS = [
# Admonitions: MyST -> Docusaurus
- (r'```{note}', ':::note'),
- (r'```{warning}', ':::warning'),
- (r'```{tip}', ':::tip'),
- (r'```{caution}', ':::caution'),
- (r'```{danger}', ':::danger'),
- (r'```', ':::'), # Close admonitions
+ (r'```\{note\}', ':::note'),
+ (r'```\{warning\}', ':::warning'),
+ (r'```\{tip\}', ':::tip'),
+ (r'```\{caution\}', ':::caution'),
+ (r'```\{danger\}', ':::danger'),
+ # Don't convert closing ``` - handle admonition closing separately
# References
(r':ref:`([^`]+)`', r'[\1](\1.md)'),Better approach: Use a stateful parser to track when inside an admonition block, or use a more complex regex that matches the entire admonition block at once.
🤖 Prompt for AI Agents
In @docs/DOCUSAURUS_MIGRATION_PLAN.md around lines 421 - 438, The REPLACEMENTS
entry that uses the generic pattern r'```' will replace every triple-backtick
(breaking normal code blocks); update the REPLACEMENTS logic so only MyST
admonition markers are targeted (e.g., convert the specific patterns like
r'```{note}', r'```{warning}', r'```{tip}', r'```{caution}', r'```{danger}'
while removing or escaping the generic r'```' rule), and implement handling for
admonition closers either by (A) matching entire admonition blocks at once (a
single regex that captures ```{type} ... ``` and replaces with the corresponding
:::type ... :::) or (B) adding a simple stateful parser around REPLACEMENTS that
tracks when you're inside an admonition and only converts the closing
triple-backticks for those blocks; ensure changes are made where REPLACEMENTS is
defined and referenced so regular code fences remain untouched.
| ```bash | ||
| cd docs/docusaurus | ||
|
|
||
| # Start development server (hot reload) | ||
| npm run start | ||
|
|
||
| # Build production site | ||
| npm run build | ||
|
|
||
| # Serve production build locally | ||
| npm run serve | ||
|
|
||
| # Clear cache | ||
| npm run clear | ||
| ``` |
There was a problem hiding this comment.
Fix incorrect directory path in development commands.
Line 49 references "cd docs/docusaurus" but according to the Phase 4 restructuring section (lines 110-118), the Docusaurus project was moved directly to "docs/". This instruction would fail.
🐛 Proposed fix
```bash
-cd docs/docusaurus
+cd docs
# Start development server (hot reload)
npm run start🤖 Prompt for AI Agents
In @docs/MIGRATION_COMPLETE.md around lines 48 - 62, Update the incorrect
directory path in the Docusaurus commands: replace the "cd docs/docusaurus"
invocation with "cd docs" in the code block (the shell commands for starting,
building, serving, and clearing the site) so the development commands point to
the relocated Docusaurus project referenced in Phase 4.
Jont828
force-pushed
the
docusaurus-migration
branch
from
bf404eb to
1243d94
Compare
Jont828
force-pushed
the
docusaurus-migration
branch
from
1243d94 to
12149cc
Compare
|
Closing in favor of #5445 |
1 participant
Overview:
I'd like to migrate the docs to Docusaurus as it can easily generate docs, provide versioned docs (which currently does not work on the site), and fixes the issues with relative/absolute link paths. This allows us to easily translate the MD docs into a website and removes the need for maintaining dedicated doc generation script with regex for replacing links and a complicated CI flow for deploying the docs as well.
This is an example of the resulting docs page.
Details:
Where should the reviewer start?
Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.