Render styleable Markdown in your HTML with <md-block>

To render Markdown on web pages, Lea Verou created <md-block>. It’s a zero-dependency Custom Element that, unlike other solutions, renders the content in the light DOM which allows you to style the output easily.

There are many web components these days to render Markdown to HTML. However, all render the resulting Markdown in Shadow DOM, making it painful to style like a regular part of the page, which my use cases required.

I also wanted a few more things existing web components didn’t have.

So I made my own. Feel free to use it. Or don’t. 🤷🏽‍♀️ I primarily wrote it to scratch my own itch anyway! 😊

Projects that grow out of a personal necessity are the best ones 🙂


Load it in via a <script> tag, or import the proper classes.

<script type="module" src=""></script>
import { MarkdownBlock, MarkdownSpan, MarkdownElement } from "";

Both methods self-register the <md-block> Custom Element, which can then be used as follows:

	# Heading

	Text **bold text** *italic text* ~strike~



	* List item 1
	* List item 2


In addition to the simple example above, it also supports rendering externally loaded markdown, allows customisation of the start heading level, has syntax highlighting (powered by Prism), can auto-link the headings, etc. Also comes with a <md-span> Custom Element (which is also registered upon loading).

In order to get to the final result, some heavy “Yak Shaving” was involved though. Now that sounded a wee bit too familiar to be honest … 😅

On Yak Shaving and <md-block>, a new HTML element for Markdown →

Published by Bramus!

Bramus is a frontend web developer from Belgium, working as a Chrome Developer Relations Engineer at Google. From the moment he discovered view-source at the age of 14 (way back in 1997), he fell in love with the web and has been tinkering with it ever since (more …)

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.