Support for inline and block HTML content

The commonMark spec describes how HTML blocks and Raw HTML should be treated:

4.6 HTML blocks

An HTML block is a group of lines that is treated as raw HTML (and will not be escaped in HTML output).

6.6 Raw HTML

Text between < and > that looks like an HTML tag is parsed as a raw HTML tag and will be rendered in HTML without escaping. Tag and attribute names are not limited to current HTML tags, so custom tags (and even, say, DocBook tags) may be used.

Example:

# Test <em>Emphasis</em>

<a href="http://github.com/markdoc/markdoc">GitHub</a>

Are there plans to support this aspect of the spec?

If so, it’s worth noting that other markdown implementations I’ve seen tend to follow the spec literally and do not parse HTML content in any way. In other words, raw HTML content is just treated as a string in the AST. The downside to this approach is that it prevents you from introspecting raw HTML content.

For example, if you wish to write a validator that ensures the integrity of links on a page you don’t really care whether the links are authored natively in markdown or as raw <a> tags. Likewise, when generating a table of contents, you want to generate IDs for and include all header tags.

Cheers, and congrats on the first release!

[rpaul-stripe]

Experimental implementation here: https://github.com/markdoc/markdoc/compare/html-support

[AlexVipond]

A few more use cases where it’s super useful to render unescaped HTML:

Custom syntax highlighting

Best-in-class highlighters like Shiki Twoslash render code (i.e. Markdoc fence content) to a string of HTML with highlighter classes and/or styles already applied.

Returning these raw HTML strings is a big DX improvement, instead of having to write additional code to parse, walk, and transform the HTML back into Markdoc nodes.

Live demo showing how to use Vite + Markdoc + Shiki Twoslash, returning a simple string of syntax highlighted HTML: ~https://stackblitz.com/edit/vitejs-vite-su1ym2?file=vite.config.ts~

Edit: updated that demo with a hacky workaround to support unescaped HTML for this case:

1. Render the code fence to syntax-highlighted HTML with Shiki Twoslash
2. Generate a unique ID, and cache it along with the HTML string
3. Return the ID from transform
4. After rendering Markdoc to an HTML, replace the unique ID with the cached HTML string

https://stackblitz.com/edit/vite-vue-3-markdoc-shiki-twoslash?file=vite.config.ts

Vue template generation

Since Vue templates are so similar to plain HTML, tools like Vitepress pass rendered Markdown (i.e. HTML strings) directly to the Vue template compiler. The rendered Markdown can include Vue components that are either written in the source .md file, or written with custom Markdown syntax and inserted automatically by the Markdown renderer.

See this project for an example of using a Markdown-It plugin to parse custom syntax and replace with Vue components.

Live demo showing how we could write Vue components in Markdown files if Markdoc supported unescaped HTML: https://stackblitz.com/edit/vite-vue-3-markdoc-shiki-twoslash?file=src%2Fhello-world.md