Swastika/mint docs/mdx fixes#2075
Conversation
Greptile SummaryThis PR fixes Mintlify MDX parsing incompatibilities across 55 documentation files and introduces a new
Confidence Score: 3/5Not ready to merge — the new docs.json navigation config references 14 pages that don't exist, and the doclinks tool's ignore markers are broken. The bulk of the changes (MDX comment conversions, details/summary reformatting, H1 removal) are mechanical and correct. However, the newly introduced docs.json has 14 navigation entries pointing to file paths with no matching file on disk, meaning the Mintlify site will display broken nav items or fail to build for those sections. Additionally, converting the doclinks-ignore HTML comment markers to JSX comments breaks the doclinks.py tool. The dead link to /troubleshooting/replay in quickstart.mdx is a lesser but additional gap. docs/docs.json (navigation path mismatches) and docs/agents/docs/doclinks.md (broken tool markers) need attention before merge. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["docs.json\n(Mintlify config)"] -->|references| B["✅ Existing pages\n(introduction, quickstart,\ninstallation/*, usage/*, etc.)"]
A -->|broken refs| C["❌ Missing pages\n(usage/concepts, capabilities/agents,\nplatforms/quadruped-go2,\nnavigation/overview, etc. ×14)"]
D["quickstart.mdx"] -->|dead link| E["❌ /troubleshooting/replay\n(no file)"]
D -->|broken card links| C
F["doclinks.md"] -->|old HTML markers| G["<!-- doclinks-ignore-start -->\n<!-- doclinks-ignore-end -->"]
F -->|new JSX markers| H["{/* doclinks-ignore-start */}\n{/* doclinks-ignore-end */}"]
H -->|not matched by| I["doclinks.py regex\n(expects HTML comment syntax)"]
G -.->|was recognized by| I
Reviews (1): Last reviewed commit: "Remove duplicate headings from all the p..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| "usage/concepts", | ||
| "usage/blueprints", | ||
| "usage/modules", | ||
| "usage/native_modules", | ||
| "usage/configuration", | ||
| "usage/cli", | ||
| "usage/python-api", | ||
| "usage/lcm", | ||
| "usage/transforms", | ||
| "usage/tool_streams", | ||
| "usage/visualization", | ||
| { | ||
| "group": "Data Streams", | ||
| "pages": [ | ||
| "usage/data_streams/overview", | ||
| "usage/data_streams/reactivex", | ||
| "usage/data_streams/advanced_streams", | ||
| "usage/data_streams/quality_filter", | ||
| "usage/data_streams/temporal_alignment", | ||
| "usage/data_streams/storage_replay" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Sensor Streams", | ||
| "pages": [ | ||
| "usage/sensor_streams/overview", | ||
| "usage/sensor_streams/reactivex", | ||
| "usage/sensor_streams/advanced_streams", | ||
| "usage/sensor_streams/quality_filter", | ||
| "usage/sensor_streams/temporal_alignment", | ||
| "usage/sensor_streams/storage_replay" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Transports", | ||
| "pages": [ | ||
| "usage/transports/overview", | ||
| "usage/transports/dds" | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Capabilities", | ||
| "pages": [ | ||
| "capabilities/agents", | ||
| { | ||
| "group": "Navigation", | ||
| "pages": [ | ||
| "capabilities/navigation/overview", | ||
| "capabilities/navigation/native-go2" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Manipulation", | ||
| "pages": [ | ||
| "capabilities/manipulation/overview", | ||
| "capabilities/manipulation/adding_a_custom_arm", | ||
| "capabilities/manipulation/openarm_integration" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Memory", | ||
| "pages": [ | ||
| "capabilities/memory/overview", | ||
| "capabilities/memory/plot", | ||
| "capabilities/memory/algo_comparison" | ||
| ] | ||
| }, | ||
| "capabilities/perception" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Platforms", | ||
| "pages": [ | ||
| "platforms/quadruped-go2", | ||
| "platforms/humanoid-g1" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "Development", | ||
| "pages": [ | ||
| "development/docker", | ||
| "development/testing", | ||
| "development/grid_testing", | ||
| "development/large_file_management", | ||
| "development/profiling_dimos", | ||
| "development/writing_docs" | ||
| ] | ||
| }, | ||
| { | ||
| "group": "For Agents", | ||
| "pages": [ | ||
| "agents/overview", | ||
| "agents/style", | ||
| "agents/testing", | ||
| { | ||
| "group": "Writing Docs", | ||
| "pages": [ | ||
| "agents/docs/overview", | ||
| "agents/docs/codeblocks", | ||
| "agents/docs/doclinks" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] |
There was a problem hiding this comment.
docs.json is introduced in this PR with 14 page paths that have no matching file on disk, so every one of these nav items will either throw a Mintlify build error or render as a broken page. The mismatches are:
usage/concepts— actual file isusage/README.mdusage/data_streams/overview— actual file isusage/data_streams/README.mdusage/sensor_streams/overview— actual file isusage/sensor_streams/README.mdusage/transports/overview— actual file isusage/transports/index.mdcapabilities/agents— actual file iscapabilities/agents/readme.mdcapabilities/navigation/overview— actual file iscapabilities/navigation/readme.mdcapabilities/navigation/native-go2— actual file iscapabilities/navigation/native/index.mdcapabilities/manipulation/overview— actual file iscapabilities/manipulation/readme.mdcapabilities/memory/overview— actual file iscapabilities/memory/index.mdcapabilities/perception— actual file iscapabilities/perception/readme.mdplatforms/quadruped-go2— actual file isplatforms/quadruped/go2/index.mdplatforms/humanoid-g1— actual file isplatforms/humanoid/g1/index.mdagents/overview— actual file isagents/index.mdagents/docs/overview— actual file isagents/docs/index.md
Either the nav entries need to be updated to match the existing file paths, or the files need to be renamed/relocated to match the nav entries before this is merged.
| {/* doclinks-ignore-start */} | ||
| | Pattern | Example | | ||
| |-------------|-----------------------------------------------------| | ||
| | Code file | `[`service/spec.py`]()` → resolves path | | ||
| | With symbol | `Configurable` in `[`spec.py`]()` → adds `#L<line>` | | ||
| | Doc link | `[Configuration](.md)` → resolves to doc | | ||
| <!-- doclinks-ignore-end --> | ||
| {/* doclinks-ignore-end */} |
There was a problem hiding this comment.
doclinks-ignore markers changed to JSX syntax, breaking the doclinks tool
dimos/utils/docs/doclinks.py uses re.compile(r"<!--\s*doclinks-ignore-start\s*-->") to identify regions to skip. Changing these markers from <!-- doclinks-ignore-start/end --> to {/* doclinks-ignore-start/end */} means the regex will no longer match, so the doclinks tool will attempt to resolve the example patterns inside the table as real file references and likely fail or produce incorrect output when run against this file.
| First replay failing? Most issues are network or LFS related. See [Replay troubleshooting](/troubleshooting/replay). | ||
| </Note> |
There was a problem hiding this comment.
/troubleshooting/replay is referenced here but there is no troubleshooting/ directory or replay.md file anywhere in the docs/ tree, so this link will 404. Either the page needs to be created or the note should point to an existing help resource.
| "platforms/quadruped-go2", | ||
| "platforms/humanoid-g1" |
There was a problem hiding this comment.
"platforms/quadruped-go2" is not indented to match the surrounding entries.
| "platforms/quadruped-go2", | |
| "platforms/humanoid-g1" | |
| "platforms/quadruped-go2", | |
| "platforms/humanoid-g1" |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
1 participant
Merge order: 2/3- Merge after #2071
Problem
Existing markdown files syntax is incompatible with Mintlify's MDX parser- HTML comments, raw image syntax, unclosed tags, and duplicate H1 headings cause parsing errors during build.
Solution
<!-- -->) to MDX comments ({/* */})) with JSX<img />tags<details>/<summary>blocks<img>→<img />)<10ms→<10ms)How to Test
Contributor License Agreement