Digital Developer Conference: Cloud Security 2021 – Build the skills to secure your cloud and data Register free

Go from Markdown to HTML5 with marked-it

Markdown is quickly becoming one of the preferred markup languages for authoring technical content. Markdown’s simple authoring, widespread use in the developer community, and support for collaboration between authors and SMEs makes it appealing to content creators.

As its popularity grows, so does the demand to enable some enhanced authoring. However, there’s a fine line between extending Markdown for enhanced authoring capabilities and ruining the simple nature of Markdown that authors and collaborators enjoy.

We also know that most modern doc applications need HTML5 output to meet design requirements for creating the best user experience. With marked-it, IBM built a generator to parse Markdown to HTML5 and process extensions the team created to provide some of those advanced authoring capabilities but without complicating the Markdown markup too much.

Trying to preserve the simplicity of Markdown, the extensions are a way to hook into well-defined points in the HTML generation process. This way, you can define ways to add classes to elements, new Markdown markup, or even how to organize a group of topics. In this article, I introduce you to some key elements in marked-it that make it a useful tool for displaying HTML5-generated content from Markdown source on a website.


The key extension in marked-it has to do with the ability to use metadata attributes in Markdown. An attribute is a name or a name-value mapping that can be bound to a Markdown element. Then, attributes are passed through to the resulting generated HTML5 elements and output as classes. They are often used to ensure correct CSS styling of the generated HTML5 output. After your attributes are defined, you can apply these values to any Markdown element, like headers, paragraphs, and codeblocks.

Or, you might need to define copyright and other metadata to prepend or append uniformly across the generated HTML5 output. In this extension, you can use standard header and footer files that are called during transformation. You might also need to add HTML opening and closing tags for the file based on your publishing requirements.

To meet accessibility requirements, there is also an extension to add table row headers, table summaries, and figure titles.

Markdown markup

While Markdown can contain HTML, ideally authors are able to fully use Markdown. In cases where the basic Markdown markup isn’t sufficient, the IBM Cloud team defined new markup that marked-it recognizes.

When we define new markup, in general, we search for industry examples where other teams have successfully extended the basic Markdown, and we replicate it. Conrefs are a good example where we were able to discover an existing Markdown implementation that was based off of the popular implementation in DITA markup, and bring it into marked-it.

Another example of new markup in marked-it is for videos. While writers could include the iframe code within the Markdown file, isn’t it so much easier to just tag something as a video and let the generator do all the work? Plus, it ensures that all video tagging is consistent. This video extension enables authors to code a video by using the image Markdown markup. Then, they define it as a video.

For example: ![Video title](<video-ID>){: video output="iframe"}

Organizing topics

In addition to the standard HTML5 output that marked-it produces from each Markdown file, the generator can also produce a Table of Contents file in different formats. Each TOC entry that is produced for a Markdown topic contains a nested set of structured headers, or topicrefs, that match the structure of the headers in the original Markdown source. Each TOC header, or topicref, also contains a link to a corresponding header anchor ID in the HTML5 output file that was generated from the Markdown source.

What that means is that you only have to define the Markdown files in the order you want them to appear in your navigation, and marked-it will create a fully structured table of contents file that has entries for the parent Markdown file and all the headings within it.

Who’s using marked-it?

Some examples of content that is sourced in Markdown in IBM are the IBM Cloud docs and IBM Developer. In both of these implementations, marked-it is part of an automated build pipeline process where content creators can author, commit changes, and a build is automatically triggered to produce the HTML5 output that gets consumed into the respective application.

Want to learn more about marked-it? Check out our specification. The marked-it generator is an open-source tool, and we’re always looking for contributions!