Craft

How to Render Markdown on a Web Page With md-block

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

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


What Does md-block Do?

Your current process may involve creating Markdown files by hand, then converting them into HTML. This is how many modern CMS applications work. Or you may use a framework like Angular to render Markdown into pages.

The md-block library isn’t strictly an alternative; instead, it fulfills a slightly different use case. It converts inline Markdown into its equivalent HTML. You can embed Markdown in your HTML files and render it on the client, at request time.

Here’s what that 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 significant in Markdown, unlike HTML.

The library introduces its own custom HTML element, md-block. Although this element isn’t part of the HTML standard, this is a valid technique. The Web Components standard (MDN) 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 render in a familiar way:

Of course, you can style the md-block element so it looks more like it would in a text editor. With preformatted whitespace and a monospace font, it’s at least a bit easier to read:

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

You might want this kind of output if you’re writing a tutorial on Markdown. It allows you to explain Markdown syntax while letting you easily edit your sample Markdown:

But md-block’s party trick is to convert that Markdown into final HTML.

Even with default browser styles, the content is now displayed just like your regular HTML, even though you sent it to the browser as Markdown:

How to Use md-block

Once you’ve added the md-block library to your page, you can write your Markdown in md-block elements. The library will then format your Markdown automatically, and you can carry on embedding Markdown as you require.

There are, however, a few variations on 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" src="https://md-block.verou.me/md-block.js"></script>

This might not be the most efficient approach, but it’s definitely the quickest. Just add this code to your head and your page will automatically render anything in an md-block element to HTML:

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

npm install md-block

Markdown Blocks vs. Inline Markdown

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

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

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

How to Syntax Highlight Markdown Code Blocks With Prism

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

So, with this HTML:

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

You’ll see nicely formatted code with syntactically aware highlighting:

Your Options For Writing Online Just Increased

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

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

Read the full article here

Leave a Reply

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

Back to top button