{"slug": "get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion", "title": "Get-md now preserves Mermaid diagrams through document-to-Markdown conversion", "summary": "Get-md v1.7.0, developed by the Nano Collective, now preserves Mermaid diagrams during document-to-Markdown conversion, recovering source from rendered SVGs, optionally reconstructing diagrams from PDFs via a vision model, and validating Mermaid syntax. The update also fixes a validation bug and ensures syntax-highlighted code blocks retain their language classes.", "body_md": "get-md v1.7.0 is out. Where 1.6.0 taught the library to read PDF, DOCX, and Markdown, this release is about not throwing away the one thing a Markdown converter usually destroys: **Mermaid diagrams**. v1.7.0 preserves Mermaid fences it finds, recovers the source from diagrams a browser has already rendered to `<svg>`\n\n, optionally reconstructs diagrams drawn into a PDF using a vision model, and optionally checks that whatever comes out actually parses. It also fixes a handful of real bugs surfaced along the way, including a validation path that was almost always wrong.\n\nBuilt by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.\n\n## What changed\n\nFour diagram behaviours, on by default where they can be, opt-in where they need optional dependencies:\n\n**Preserved.** A```` mermaid`\n\nfence in your HTML or Markdown comes out the other side unchanged, fence and language tag intact. Same treatment for`dot`\n\n,`graphviz`\n\n, and`plantuml`\n\n, all newly registered as recognised language identifiers.**Recovered.** When a docs site has already rendered a diagram to`<svg>`\n\n(the GitHub, MkDocs, and Docusaurus case), get-md pulls the original source back out of the DOM before Readability and the HTML cleaner can strip it.**Reconstructed.** Diagrams drawn into a PDF can be rebuilt by a remote vision model. Opt-in, capped at the first 10 pages, and remote providers only.**Validated.**`validateMermaid: true`\n\nparses every Mermaid block in the finished Markdown and annotates the ones that fail, keeping the original so you can repair it rather than losing it.\n\nThese cover the same problem from four angles, and each one is independently switchable. The default install footprint is unchanged. New capabilities that need rendering or parsing install their own optional peer dependencies.\n\n## Preserved: Mermaid fences survive conversion\n\n`mermaid`\n\nis now a recognised language identifier, alongside `dot`\n\n, `graphviz`\n\n, and `plantuml`\n\n. Previously a Mermaid block survived only by accident, through a loose lowercase-word fallback with no test coverage behind it.\n\nA ```` mermaid`\n\nblock in HTML (`<pre><code class=\"language-mermaid\">`\n\n) or in a Markdown file comes out the other side unchanged, fence and language tag intact. The behaviour applies from both the library and the CLI, across HTML, URL, and `.md`\n\ninput.\n\nThe release also fixes a general case that affects every syntax-highlighted page, not just Mermaid: the Mermaid recovery work sets `keepClasses: true`\n\n, so `<pre><code class=\"language-x\">`\n\nkeeps its class through extraction. Fenced output is now tagged, ```` python`\n\n, ```` go`\n\n, ```` rust`\n\n, where it previously came out bare. This is the most visible change in the release for anyone converting documentation sites. Two consequences worth knowing: unrecognised class names can now surface as tags via the lowercase-word fallback, and because element classes survive into the cleanup pass, class-based noise rules match more often (a `cookie-notice`\n\nblock is correctly dropped, but so is genuine prose carrying an `advertisement`\n\nor `popup`\n\nclass).\n\n## Recovered: Mermaid source from rendered SVG\n\nGitHub, MkDocs, and Docusaurus run mermaid.js client-side, so the HTML you fetch holds the rendered `<svg>`\n\n, not the diagram. The source is usually still in the DOM somewhere, and get-md now goes looking for it before Readability and the HTML cleaner can strip it.\n\nThe recovery looks for these container shapes:\n\n`.mermaid`\n\n,`pre.mermaid`\n\n,`[data-processed=\"true\"]`\n\n,`svg[id^=\"mermaid-\"]`\n\n, and`svg.mermaid`\n\n.\n\nFor each container it tries the first source it can find, in this order:\n\n- A\n`<script type=\"text/mermaid\">`\n\ninside or next to the container. - A\n`data-code`\n\n,`data-mermaid`\n\n,`data-src`\n\n,`data-original`\n\n, or`data-source`\n\nattribute. - The container's own text when it is a\n`<pre>`\n\nholding no`<svg>`\n\n. - A hidden\n`pre[hidden]`\n\n,`<template>`\n\n, or`textarea[hidden]`\n\n. - The SVG's\n`<desc>`\n\n,`<title>`\n\n, or`aria-label`\n\n.\n\nThat last fallback is deliberately strict. mermaid.js writes accessibility strings such as `Created with Mermaid`\n\ninto those nodes, and emitting one as a diagram would be worse than dropping it. Text qualifies only if it is multi-line, contains `;`\n\n, or opens with a diagram keyword and carries an arrow, a colon, or real length.\n\nRecovered diagrams are re-emitted as ```` mermaid`\n\nfences. Where no source is recoverable, behaviour is unchanged: the SVG's text labels fall through as loose text.\n\n## Reconstructed: diagrams in PDFs by a vision model (opt-in)\n\nA diagram in a PDF is vector drawing or raster image. There is no text to recover, so this is a vision problem. With `useLLM`\n\nand a remote vision-capable model, get-md renders PDF pages to images and asks the model to emit Mermaid inline where the diagram appeared.\n\nA few constraints worth stating up front:\n\n**Remote providers only.** The local ReaderLM-v2 path is text-only, and so is`useLLM`\n\nwith no`llm`\n\nconfig, since that defaults to local-llama. Neither renders pages nor calls a vision model.**New optional peer dependencies.**`pdfjs-dist`\n\n(^5) and`@napi-rs/canvas`\n\n(^0.1), installed only if you want this. Standard fonts resolve dynamically from the installed`pdfjs-dist`\n\n.**Capped at the first 10 pages**, to keep long PDFs from overflowing the model's context. Longer documents log a warning naming the cap; text extraction still covers the whole file.**Fails soft in both directions.** Missing render dependencies or a render error warns and continues text-only, and a failed vision request retries the same conversion without images.**Accuracy varies with the model and the diagram.** This is a best-effort assist, not guaranteed fidelity.\n\nOne limitation carried over from 1.6.0 and now worth stating explicitly: a PDF with no extractable text, a pure scan or a page that is nothing but a diagram, still returns an empty result before page rendering is attempted, so vision reconstruction never runs on exactly the PDFs that would benefit most.\n\n## Validated: parse every Mermaid block (opt-in)\n\n`validateMermaid: true`\n\nruns every ```` mermaid`\n\nfence in the finished Markdown through mermaid's own parser and annotates the ones that fail, so a model that emits plausible-but-broken Mermaid does not do so silently.\n\n- Invalid blocks are\n**kept**, with a GitHub-style`> [!WARNING]`\n\ncallout inserted above them. You repair the diagram rather than losing it. - Applies to all Mermaid in the output: preserved, recovered, and model-generated alike, and runs last, after conversion and image localization.\n- Available as the\n`validateMermaid`\n\nlibrary option, the`--validate-mermaid`\n\nCLI flag, and a`validateMermaid`\n\nconfig-file key, across every conversion path: HTML, URL, Markdown, PDF, DOCX, batch, and sitemap. - Requires the\n**optional**`mermaid`\n\npeer dependency (^11). Without it, get-md logs a warning and returns the Markdown untouched, so enabling the option can never break a conversion. - Only non-indented triple-backtick fences are matched; indented fences may pass through unvalidated.\n\n``` js\nimport { convertToMarkdown } from \"@nanocollective/get-md\";\n\nconst result = await convertToMarkdown(source, {\n  inputType: \"markdown\",\n  validateMermaid: true,\n});\n```\n\n## Bug fixes from the launch review\n\nThree real bugs were caught while building this release, and a behavioural change worth its own callout.\n\n**Mermaid validation no longer rejects valid diagrams.**`mermaid.parse`\n\nsanitizes label text through DOMPurify, which needs a DOM. Under plain Node there wasn't one, so any diagram carrying node labels, things like`A[Start]`\n\n,`B{Choice}`\n\n,`-->|yes|`\n\n, and every class, state, ER, gantt, and mindmap diagram, threw`DOMPurify.addHook is not a function`\n\n, and the validator treated any throw as a syntax error. In practice almost every real diagram was annotated as invalid, including correct output from the PDF vision path this option exists to check. Validation now installs a headless DOM before importing mermaid (the point DOMPurify binds to the global scope) and restores the global scope afterwards, including`process`\n\n, which constructing a happy-dom`Window`\n\nreplaces. Only a genuine parse complaint now annotates the document; anything environmental logs one diagnostic and leaves the diagram alone. Two diagram types (`pie`\n\n,`gitGraph`\n\n) still take that path, failing inside a lazily loaded mermaid parser chunk, and are skipped by the validator.The flag was accepted, and`--config <path>`\n\nis no longer ignored.`--show-config`\n\neven printed the path, but every conversion still loaded configuration through cwd/home auto-discovery. An explicitly named config file had no effect on output and its validation errors never surfaced, so a typo'd config failed silently. All five conversion paths and`--show-config`\n\nnow resolve config through one helper that honors the flag.**Duplicate validation warnings prevented.** Re-running validation over already-annotated Markdown no longer stacks a second warning onto the same block. The fence-matching regex was also tightened for stability.**PDF rendering is loaded dynamically**, so the optional`pdfjs-dist`\n\nand`@napi-rs/canvas`\n\ndependencies are never touched unless vision reconstruction is actually in play.\n\n## Behaviour change: code-block language tags survive\n\nAlready covered above, but worth its own callout because it affects every docs conversion, not just Mermaid. The recovery work sets `keepClasses: true`\n\n, so `<pre><code class=\"language-x\">`\n\nkeeps its class through Readability extraction. Fenced output is now tagged where it previously came out bare. The two tradeoffs above (unrecognised class names surfacing as tags, class-based noise rules matching more often) are real, and worth noting if your pages lean heavily on either.\n\n## Installation\n\n```\nnpm install -g @nanocollective/get-md\n\n# Install this specific version\nnpm install -g @nanocollective/[email protected]\n```\n\nFor the optional paths:\n\n```\n# PDF diagram reconstruction (vision)\nnpm install pdfjs-dist @napi-rs/canvas\n\n# Mermaid validation\nnpm install mermaid\n```\n\n## Usage\n\n```\ngetmd\n```\n\nOr from a script:\n\n``` js\nimport { convertToMarkdown } from \"@nanocollective/get-md\";\n\n// From HTML string\nconst result = await convertToMarkdown(\"<h1>Hello</h1><p>World</p>\");\nconsole.log(result.markdown);\n\n// From a Markdown file with validation\nconst validated = await convertToMarkdown(markdownSource, {\n  inputType: \"markdown\",\n  validateMermaid: true,\n});\n```\n\n## Documentation\n\nThe new [Diagrams & Mermaid guide](https://docs.nanocollective.org/get-md/docs/guides/mermaid) covers the support matrix of what is preserved, recovered, reconstructed, and validated per input type, the recovery precedence order, setup and limits for the opt-in PDF path, and a troubleshooting table. The README gains a Mermaid section, and the runnable [ examples/mermaid-diagrams.ts](https://github.com/Nano-Collective/get-md/blob/main/examples/mermaid-diagrams.ts) covers preservation, recovery, and validation entirely offline, with the PDF vision path as a commented snippet.\n\n## Tests\n\n634 passing (up from 592 at 1.6.0). New coverage for Mermaid fence preservation from HTML and Markdown, and the other diagram languages; source recovery across every container shape and source strategy, including the accessibility-text guard; PDF page rendering and the 10-page cap; vision prompting, multimodal message assembly, and text-only fallback; validation across nine diagram shapes that were previously false-positived, plus global-scope and `process`\n\nrestoration; and the `--validate-mermaid`\n\nflag and `--config`\n\nresolution end-to-end through the CLI.\n\n## Upgrading\n\n```\nnpm install @nanocollective/[email protected]\n```\n\nOr:\n\n```\npnpm add @nanocollective/[email protected]\n```\n\nNode.js 22 or later is required. No peer dependencies are required for the standard HTML/PDF/DOCX/Markdown paths. The new Mermaid and PDF-vision paths install their own optional dependencies when you opt in.\n\nIf you hit any issues or want to dig into the diagram recovery work, open an issue or find us on [Discord](https://discord.gg/ktPDV6rekE).", "url": "https://wpnews.pro/news/get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion", "canonical_source": "https://nanocollective.org/blog/get-md-v170-mermaid-diagrams-survive-the-conversion-end-to-end-80", "published_at": "2026-07-31 13:41:24+00:00", "updated_at": "2026-07-31 13:52:11.305563+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["Nano Collective", "get-md"], "alternates": {"html": "https://wpnews.pro/news/get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion", "markdown": "https://wpnews.pro/news/get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion.md", "text": "https://wpnews.pro/news/get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion.txt", "jsonld": "https://wpnews.pro/news/get-md-now-preserves-mermaid-diagrams-through-document-to-markdown-conversion.jsonld"}}