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 HTML embedding, but now you can go the other way and embed Markdown in HTML.
With 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 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 into pages.
The md-block library isn’t necessarily an alternative; Instead, it fulfills a slightly different use case. It converts inline markdown to its equivalent HTML. You can embed Markdown in your HTML files and render it on the client on demand.
It could look like this:
<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 a leading indent. This is because, unlike HTML, leading spaces can be meaningful in Markdown.
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 Standard (MDN) includes an API called Custom Elements. This API supports dynamic registration of custom items using JavaScript.
Before loading the md-block library, this page is rendered in the familiar way:
Of course, you can style the md-block element to look more like a text editor. With spaces preformatted and a monospace font, it’s at least a little 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 easily editing your example markdown:
But md-block’s party trick is to turn that markdown into final HTML.
Even with default browser styles, the content is now rendered 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 it md block Elements. The library will then automatically format your markdown, and you can embed markdown as needed.
However, there are some variations on this process.
Obtain the script remotely or install it yourself
The easiest way to get started is to refer to 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 fastest. Just add this code to yours head and your page automatically renders everything in an md-block element in HTML:
You can of course download this JavaScript file and host it on your own website. Or you can install it via npm:
npm install md-blockMarkdown Blocks vs. Inline Markdown
The default member, named after the library itself, is md block. But you can also use one md-span Element for inline markdown, e.g. B. Text in the middle of a sentence:
The use case for inline markdown is probably less common, but you can still use it:
<p>An HTML paragraph containing <md-span>*italic*</md-span> text.</p>How to syntactically markup blocks of Markdown code with Prism
Prism is a syntax highlighter co-developed by Lea Verou, creator of md-block. You can use it to highlight preformatted blocks of code on 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 see nicely formatted code with syntactically aware highlighting:
Your online writing options just increased
How you use md-block is entirely up to you, but there’s a lot of potential for inventive solutions using it. You could use it to run a very lightweight CMS for authors who are familiar with Markdown but not HTML.
Markdown is a perfect language for a general audience. Adoption by tools like Slack will most likely increase usage even further.