How to render Markdown on a webpage with md-block

Markdown’s simple syntax makes it a great alternative to HTML. The language has always supported embedding HTML, but now you can go the other way and embed Markdown into HTML.

Using a simple library, you can host Markdown embedded in your web pages and convert it to proper HTML on the fly.


What does md-block do?

Your current process may involve manually creating Markdown files and then converting them to HTML. This is how many modern CMS applications work. Or you can use a framework like Angular to render Markdown in pages.

The md-block library is not strictly an alternative; instead, it fulfills a slightly different use case. It converts online Markdown to its HTML equivalent. You can embed Markdown in your HTML files and render it on the client, when requested.

Here’s what it might look like:

<html>
<head>...</head>

<body>
<md-block>
# Heading
Some *embedded* Markdown which `md-block` can convert for you!
</md-block>
</body>
</html>

It’s a good idea to left-align your embedded Markdown code, without any leading indentation. This is because leading whitespace can be important in Markdown, unlike HTML.

The library introduces its own custom HTML element, md block. Although this element is not part of the HTML standard, it is a valid technique. The Web Components (MDN) standard includes an API called Custom Elements. This API supports dynamic registration of custom elements using JavaScript.

Before loading the md-block library, this page will be displayed in a familiar way:

Of course, you can style the md-block element to look more like a text editor. With preformatted whitespace and a monospaced font, it’s at least a little easier to read:

<style>md-block { white-space: pre; font-family: monospace; }</style>

You might want this type of output if you’re writing a Markdown tutorial. It allows you to explain Markdown syntax while allowing you to easily modify your Markdown example:

But md-block’s trick is to convert this Markdown to final HTML.

Even with the default browser styles, content now renders as your usual HTML, even if you’ve sent it to the browser as Markdown:

How to use md-block

Once you have added the md-block library to your page, you can write your Markdown in md block elements. The library will then automatically format your Markdown and you can continue to integrate Markdown as needed.

There are, however, a few variations of this process.

Source the script remotely or install it yourself

The easiest way to get started is to reference the library from the official md-block website:

<script type="module"  data-src="https://md-block.verou.me/md-block.js"></script>

It might not be the most efficient approach, but it’s definitely the fastest. Just add this code to your head and your page will automatically display everything inside an md-block element in HTML:

You can, of course, download this JavaScript file and host it on your own site. Or you can install it via npm:

npm install md-block

Markdown Blocks vs Markdown Online

The default item, named after the library itself, is md block. But you can also use a md span element for inline Markdown, such as text in the middle of a sentence:

The inline Markdown use case is probably less common, but you can still use it:

<p>An HTML paragraph containing <md-span>*italic*</md-span> text.</p>

How to highlight syntax in Markdown code blocks with Prism

Prism is a syntax highlighter co-created by md-block creator Lea Verou. You can use it to highlight preformatted blocks of code in a web page, including those generated by md-block.

So, with this HTML:

<html>
<body>
<md-block>
```javascript
function square(number) {
return number * number;
}
```
</md-block>
<script data-src="prism.js"></script>
</body>
</html>

You’ll see well-formatted code with syntax highlighting:

Your options for writing online just got bigger

How you use md-block is up to you, but there’s a lot of potential for inventive solutions that use it. You can use it to run a very lightweight CMS for writers who are comfortable using Markdown, but not HTML.

Markdown is a perfect language for a general audience. Its adoption by tools like Slack will likely increase usage even more.

Comments are closed.