Mintlify chokes on math-heavy Markdown (MDX) + hard-blocks Node 25
Two non-obvious gotchas migrating a large math/spec docs folder to Mintlify (mint CLI v4.2). (1) The CLI refuses to run on Node 25 ("not supported, switch to an LTS"); needs Node 22/24 LTS. Watch out: a stale Homebrew node@24 opt-symlink can point at the Cellar node/25 install, so verify the REAL binary at /opt/homebrew/Cellar/node@24/<ver>/bin/node --version, not the opt symlink. (2) Mintlify renders every .md (not just .mdx) through MDX, so prose math breaks the build: { starts a JS expression, < starts a JSX tag. Errors like "Could not parse expression with acorn" or "Unexpected character before name". Also MDX does NOT honor 4-space indented code blocks — it parses their contents as prose. Fix that builds green without changing rendered output: (a) convert indented code blocks to fenced ``text blocks (dedent 4); (b) escape { -> \{ everywhere in prose; (c) escape < -> < when the next char is non-whitespace (covers <tag>, <1s, </, <{) but leave < followed by a space (a < b is fine). Crucially do (a)/(b)/(c) ONLY outside fenced blocks and inline code spans, else you double-escape \{ into \\{. Do the indent->fence pass BEFORE escaping so math lands in a fence and needs no escaping. Validate with mint broken-links` (it surfaces parse errors per file); links to ../code and ../artifacts outside the docs root will still report as broken but do not block the build.