MrDocs ships html and adoc. Consumers publishing with MkDocs, Hugo or Docusaurus need Markdown, and examples/generators/data-driven/md is a demonstration rather than a basis. Four things in it produce broken output:
mrdocs-generator.yml maps '_': '\_' with no context, so an identifier inside <code> renders as quantity\_specpartials/markup/a.md.hbs emits {{{href}}} raw, so links come out absolute (/mp_units/quantity-01.md) rather than relativizedlayouts/wrapper.md.hbs hardcodes # Reference as every page's titlepartials/markup/table.md.hbs builds a GFM pipe table while the escape map has no | entry, so a signature containing one — operator|, operator|= — puts a raw pipe in a cell
We wrote our own, and the shape that works is worth sharing: Markdown for block structure, so headings feed the host's table of contents, anchors and search index, and inline HTML for code and links, so a link can sit inside a <code> span and a pipe cannot break a table. Escaping is then HTML entities rather than Markdown backslashes. 15 partials and a helper over extends: html.
A supported generator along those lines would save every static-site consumer from rediscovering it, and would make the md example honest about being a starting point.
Happy to contribute ours if that is useful.
MrDocs ships
htmlandadoc. Consumers publishing with MkDocs, Hugo or Docusaurus need Markdown, andexamples/generators/data-driven/mdis a demonstration rather than a basis. Four things in it produce broken output:mrdocs-generator.ymlmaps'_': '\_'with no context, so an identifier inside<code>renders asquantity\_specpartials/markup/a.md.hbsemits{{{href}}}raw, so links come out absolute (/mp_units/quantity-01.md) rather than relativizedlayouts/wrapper.md.hbshardcodes# Referenceas every page's titlepartials/markup/table.md.hbsbuilds a GFM pipe table while the escape map has no|entry, so a signature containing one —operator|,operator|=— puts a raw pipe in a cellWe wrote our own, and the shape that works is worth sharing: Markdown for block structure, so headings feed the host's table of contents, anchors and search index, and inline HTML for code and links, so a link can sit inside a
<code>span and a pipe cannot break a table. Escaping is then HTML entities rather than Markdown backslashes. 15 partials and a helper overextends: html.A supported generator along those lines would save every static-site consumer from rediscovering it, and would make the
mdexample honest about being a starting point.Happy to contribute ours if that is useful.