Swastika/mint docs/md parse fix by swstica · Pull Request #2221 · dimensionalOS/dimos

swstica · 2026-05-22T14:44:02Z

Problem

Existing markdown files syntax is incompatible with mintlify's MDX parser- HTML comments, raw image syntax, unclosed tags cause parsing errors during build.

Solution

make sure md files doesn't break in GH preview as well as in minltify.
removed  comments.
Added required blank lines around <details>/<summary> blocks

greptile-apps · 2026-05-22T14:47:54Z

Greptile Summary

This PR makes the docs/ markdown files compatible with Mintlify's MDX parser by removing **/*.md from .mintignore and systematically fixing every syntax pattern that MDX rejects. It also wires up a full navigation tree in docs.json.

MDX syntax fixes across 36 files:  HTML comment + bare code-block pairs are replaced with ```results fenced blocks;  comments become JSX {/* */} comments; <details><summary> on a single line is split to two lines; a raw <img width=\"100%\"> in native/index.md is converted to standard Markdown image syntax (losing the width attribute).
docs.json navigation expansion: A full multi-group nav tree (Installation, Usage, Agents, Capabilities, Platforms, Development) is added; all referenced file paths were verified to exist on disk.
Heading level demotions: # h1 headings in ubuntu.md, osx.md, nix.md, and blueprints.md were changed to ## h2, leaving those pages without an h1 — this and the backtick-wrapped hyperlinks in docker.md were flagged in previous review threads.

Confidence Score: 4/5

Safe to merge with awareness that the h1→h2 heading demotions and backtick-wrapped hyperlinks from earlier review threads remain unaddressed in the changed files.

The MDX compatibility fixes are correct and complete across all changed files — no HTML comments remain in any .md file, the details splits are properly done, and all navigation paths in docs.json resolve to existing files. The unresolved items from prior review threads (heading demotions in ubuntu/osx/nix/blueprints and broken link rendering in docker.md) are still present in this diff.

docs/installation/ubuntu.md, docs/installation/osx.md, docs/installation/nix.md, docs/usage/blueprints.md (h1 demoted to h2), and docs/development/docker.md (backtick-wrapped hyperlinks)

Important Files Changed

Filename	Overview
docs/.mintignore	Replaces the blanket `*/.md` ignore rule with `node_modules/`, exposing all .md files to Mintlify's MDX parser — relies on the other files in this PR being properly fixed.
docs/docs.json	Significantly expands the Mintlify navigation tree; all referenced file paths were verified to exist on disk.
docs/capabilities/navigation/native/index.md	Converts raw `<img src="..." width="100%">` to `![output](...)` for MDX compatibility, but loses the `width="100%"` styling on the navigation GIF.
docs/usage/modules.md	Converts `<!--Result:-->` comments to triple-backtick results blocks and one `<!-- TODO -->` comment to JSX `{/* */}` syntax; whitespace-only blank-line cleanup.
docs/installation/ubuntu.md	All `#` headings demoted to `##`, leaving the page without an h1 (flagged in a previous review comment on this PR).
docs/development/docker.md	Fixes `<details><summary>` splitting and table reformatting; contains backtick-wrapped Markdown links that render as code strings (flagged in a previous review comment).
docs/agents/docs/doclinks.md	Removes `doclinks-ignore` markers and replaces template table entries with concrete resolved file links; markers were only needed when the entries were abstract examples.
docs/usage/blueprints.md	Converts `<!--Result:-->` blocks and fixes a trailing blank line; the `# Blueprints` → `## Blueprints` h1 demotion (flagged in a prior comment) leaves the page without an h1.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[.mintignore: remove **/*.md] --> B[All .md files now parsed by Mintlify MDX]
    B --> C{MDX-incompatible syntax?}
    C -- "HTML comments" --> D["Convert to results blocks / JSX comments"]
    C -- "details+summary on one line" --> F["Split to two lines"]
    C -- "Raw img with attrs" --> G["Convert to Markdown image — loses width attr"]
    C -- "Heading levels h1 to h2" --> H["Pages lose their h1 title anchor"]
    D --> I[MDX-compatible]
    F --> I
    G --> J[MDX-compatible but style regression]
    H --> K[Page title may fall back to filename]
    I --> L[docs.json: add full nav tree]
    J --> L
    K --> L
    L --> M[Mintlify build can proceed]

_{Reviews (12): Last reviewed commit: "fix link and code block title" | Re-trigger Greptile}

greptile-apps · 2026-05-22T14:48:13Z

@@ -1,4 +1,4 @@
-# System Dependencies Install (Ubuntu 22.04 or 24.04)
+## System Dependencies Install (Ubuntu 22.04 or 24.04)


Top-level # heading removed

Demoting # to ## removes the document's only h1 heading. Mintlify (and GitHub preview) derive the page title from the frontmatter or the first h1; without one, the page title will fall back to the filename. The same applies to osx.md and nix.md, which also had their h1 changed to h2 in this PR. If these files are included in Mintlify navigation without frontmatter title fields, they will show generic titles.

greptile-apps · 2026-05-22T14:48:14Z

@@ -1,4 +1,4 @@
-# Blueprints
+## Blueprints


Top-level # heading removed

# Blueprints was changed to ## Blueprints, so the page now has no h1. Mintlify uses the first h1 as the page title when no frontmatter title is present. Without it, the page title will be blank or fall back to the filename.

…cks, link formatting)

greptile-apps · 2026-05-25T12:35:01Z

+# Ignore dependency trees under the docs workspace (would otherwise be scanned as pages).
+node_modules/


Untouched files still contain MDX-incompatible HTML comments

Removing **/*.md from .mintignore exposes all markdown files to Mintlify's MDX parser, but three files in docs/agents/docs/ were not fixed and still contain  comment syntax that the MDX parser will reject: docs/agents/docs/codeblocks.md (11 occurrences), docs/agents/docs/index.md (5 occurrences), and docs/agents/docs/doclinks.md (2 functional  markers). The Mintlify build will fail on these files after this PR lands. They need the same  → ```results treatment applied to the other files in this PR, or the docs/agents/docs/ path should be added to .mintignore.

codecov · 2026-05-25T13:56:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

paul-nechifor · 2026-05-25T23:07:32Z

+          "usage/modules",
+          "usage/blueprints",
+          "usage/configuration",
+          "usage/lcm",


Many of these titles are not rendered correctly. For example this shows up as Lcm instead of LCM. Same for others, like PythonApi instead of Python API.

mintlify takes up the file name as title by default, I've changed the file names in next PR.

paul-nechifor · 2026-05-25T23:09:55Z

+          "usage/lcm",
+          "usage/transforms",
+          "usage/visualization",
+          "usage/cli",


This page has an invalid link.

The above link points to http://localhost:3000/docs/usage/configuration.md but that 404s.

I suggest writing a small script which crawls http://localhost:3000 and checks that every internal link points somewhere that returns a 200.

paul-nechifor · 2026-05-25T23:18:04Z

Should these be links? Quickstart is the only one which links somewhere.

...

paul-nechifor · 2026-05-25T23:22:04Z

+          {
+            "group": "Memory",
+            "pages": [
+              "capabilities/memory/index",


I think we need better titles for things like this.

same with this, mintlify takes up the file name as title by default. didn't want to touch folder structure in this PR to avoid confusion. changed the names and flattened the nested folder in the next PR.

swstica · 2026-05-26T12:47:40Z

Should these be links? Quickstart is the only one which links somewhere.
...

this is on purpose, the links would've been stale since files names will be changed in next PR. i'll add the links to these cards once the file names are changed (so we don't have anything linking to index page)

Swastika added 4 commits May 20, 2026 17:41

fixing md files parsing for mint and gh

dddc12c

formatting headings

f28921f

format content for mintlify

b88367f

format comments

67ac2b7

greptile-apps Bot reviewed May 22, 2026

View reviewed changes

Swastika added 3 commits May 22, 2026 20:31

fix links

9bbea92

fix parsing issues across usage guides (multiline details, result blo…

480642f

…cks, link formatting)

fix parsing issues across capabilities

fbef1d4

greptile-apps Bot reviewed May 25, 2026

View reviewed changes

Swastika added 2 commits May 25, 2026 18:39

removed comment, updated links

ecd6b57

added docs files to mint nav

6095f82

greptile-apps Bot reviewed May 25, 2026

View reviewed changes

Comment thread docs/docs.json

Merge branch 'main' into swastika/mint-docs/md-parse-fix

f5377b7

Swastika added 4 commits May 25, 2026 20:25

reverting links to path

0babf76

remove readme slug

6d0b6f2

fix docs lint

09a621e

Fix pre-commit lint

5240e01

paul-nechifor reviewed May 25, 2026

View reviewed changes

Comment thread docs/capabilities/memory/index.md Outdated

fix link and code block title

345b2d7

paul-nechifor approved these changes May 26, 2026

View reviewed changes

paul-nechifor enabled auto-merge (squash) May 26, 2026 21:36

		@@ -1,4 +1,4 @@
		# System Dependencies Install (Ubuntu 22.04 or 24.04)
		## System Dependencies Install (Ubuntu 22.04 or 24.04)

		# Ignore dependency trees under the docs workspace (would otherwise be scanned as pages).
		node_modules/

Conversation

swstica commented May 22, 2026

Problem

Solution

Uh oh!

greptile-apps Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov Bot commented May 25, 2026

Codecov Report

Uh oh!

paul-nechifor May 25, 2026

Choose a reason for hiding this comment

Uh oh!

swstica May 26, 2026

Choose a reason for hiding this comment

Uh oh!

paul-nechifor May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swstica May 26, 2026

Choose a reason for hiding this comment

Uh oh!

paul-nechifor commented May 25, 2026

Uh oh!

paul-nechifor May 25, 2026

Choose a reason for hiding this comment

Uh oh!

swstica May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

swstica commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented May 22, 2026 •

edited

Loading

paul-nechifor May 25, 2026 •

edited

Loading