Remodel your Markdown supply into HTML5 output – IBM Developer


marked-it is an open supply generator that transforms Markdown supply into HTML5 output. Created by IBM, marked-it provides to the fundamental Markdown markup with extensions that make your content material web-ready.

In marked-it model 2.0, we refactored the code to make it simpler for customers to code, customise, and contribute their very own enhancements to the undertaking.

Why do some groups use Markdown?

Markdown is gaining in reputation, as a result of it’s:

  • Straightforward for the common individual to make use of
  • Well-liked with builders, so will increase ease of collaboration
  • Free! No fancy, costly editor is required

Why model 2.0?

marked-it turned 6 years previous and it was time to do some refactoring of the code to simplify the implementation and make it extra extensible. With marked-it 2.0, we modified its core dependency from marked to markdown-it. This transformation provides a couple of cool new options, and extra importantly makes it faster and simpler for us to introduce extra capabilities sooner or later due to its extensible plug-in structure. However, we made certain there was the identical HTML and JSON output as earlier than — so no updates to consuming apps.

What’s in marked-it 2.0?

Along with the core dependency change, we added another options:

New toc.yaml format

To extra simply code your desk of contents file, we added a brand new toc.yaml format to marked-it. Along with simpler coding of the file, a typical format additionally makes it simpler to automate checks on the file. The extensionless TOC file from marked-it 1.0 nonetheless works, and each TOC codecs output to the very same toc.json schema. For particulars, see toc.yaml file format.

A brand new function that comes with the toc.yaml is assist of navigation titles (navtitles). You probably have a prolonged subject title, now you can overwrite the label within the navigation by setting a navtitle.

Markdown coding for definition lists

Markdown markup for definitions lists is now supported! A definition record is a collection of phrases adopted by a definition of the time period. For particulars about find out how to use this function, see Definition lists.

Markdown coding for tables nested in lists

Now you can use Markdown markup to embed a desk inside a listing. That is particularly useful, for instance, when you should present lists of values to finish a step in a job.

Markdown coding for line breaks, paragraphs, and lists in tables

Together with line breaks, paragraphs, and ordered and unordered lists inside Markdown tables is now supported. You would possibly use this function to interrupt up a number of sentences in a desk cell or embody concise lists of choices.

New extension for embedding audio information

We’ve added a brand new audio extension to embed audio information, similar to .mp3, .wav, and extra inside your docs. For details about find out how to use the brand new extension, see Audio.

Help for conrefs and keyrefs

You may need frequent content material that’s wanted in a number of matters inside your doc set. You need to use a content material reference (conref) to jot down this content material as soon as and pull it into many Markdown matters in your similar doc set.

In IBM Cloud, we leverage conrefs for frequent content material that’s repeated inside doc units. For particulars, see Content material references.

And, we added the flexibility to make use of key references (keyrefs) which are easy key-value pairs. In IBM Cloud, keyrefs are leveraged largely for simply product names. Accepted product names are saved in a central conkeyref YAML file in order that writers throughout the IBM Cloud platform can refer to those key phrase values within the YAML file any time they reference the product title. This lets you simply change the title in a single location, after which after a construct, any reference to that product title will magically get up to date in all places the conkeyref was used! This was beforehand our conrefs implementation in marked-it 1.0. For particulars, see Key references.

marked-it specification

To view the complete marked-it documentation, go to


Please enter your comment!
Please enter your name here