Interactive Docs with Markdoc
I&#x27;ve recently been using Markdown (to my utter chagrin) in order to update my resume and blog, and I&#x27;m just astounded by how much recreation of solved problems is going on in that space. I prefer JavaScript&#x2F;Node so I&#x27;ve played with UnifiedJS (remark&#x2F;rehype), MarkdownIt, MarkedJS, and others. It&#x27;s honestly just absurd how over-engineered each project is.<p>If all you&#x27;re producing is HTML - which is 99% of what Markdown is used for - having to deal with a raw AST in order to modify a document is like deciding to use Assembly instead of Python. Sure, it could be more efficient if you really want to spend the time, but it&#x27;s generally a step backwards in every way.<p>I&#x27;ve personally decided that the only predictable, reliable and maintainable way to deal with Markdown is to extract the frontmatter, then convert the rest into bog-standard CommonMark HTML and then use JSDOM to do any additional manipulation. So instead of fighting with some wonky AST tree and APIs, I can use the DOM and standard web tools and code.<p>Markdown parsers will let you pass through HTML tags. You can define any tag you want. There is no difference between:<p><pre><code>    {% callout type=&quot;check&quot; %}
    {% &#x2F;callout %}
</code></pre>
and<p><pre><code>    &lt;callout type=&quot;check&quot;&gt;
    &lt;&#x2F;callout&gt;
</code></pre>
And anyone who went through the XSL trend of the early 2000s should know the long-term pain caused by putting logic in your documents.<p><pre><code>    &lt;xsl:if test=&quot;price = 10&quot;&gt;
    &lt;&#x2F;xsl:if&gt;
</code></pre>
Recreating this with {% if equals(1, 2) %} is just ignoring decades of lessons already learned.<p>Honestly, Markdown needs to be killed with prejudice. So much wasted time and effort getting it to do what people need it to do.