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

In marked-it version 2.0, we refactored the code to make it easier for users to code, customize, and contribute their own enhancements to the project.

Why do some teams use Markdown?

Markdown is gaining in popularity, because it is:

• Easy for the average person to use
• Popular with developers, so increases ease of collaboration
• Free! No fancy, expensive editor is required

Why version 2.0?

marked-it turned 6 years old and it was time to do some refactoring of the code to simplify the implementation and make it more extensible. With marked-it 2.0, we changed its core dependency from marked to markdown-it. This change adds a few cool new features, and more importantly makes it quicker and easier for us to introduce more capabilities in the future because of its extensible plug-in architecture. But, we made sure there was the same HTML and JSON output as before — so no updates to consuming apps.

What’s in marked-it 2.0?

In addition to the core dependency change, we added some other features:

New toc.yaml format

To more easily code your table of contents file, we added a new toc.yaml format to marked-it. In addition to easier coding of the file, a standard format also makes it easier to automate checks on the file. The extensionless TOC file from marked-it 1.0 still works, and both TOC formats output to the exact same toc.json schema. For details, see toc.yaml file format.

A new feature that comes with the toc.yaml is support of navigation titles (navtitles). If you have a lengthy topic title, you can now overwrite the label in the navigation by setting a navtitle.

Markdown coding for definition lists

Markdown markup for definitions lists is now supported! A definition list is a series of terms followed by a definition of the term. For details about how to use this feature, see Definition lists.

Markdown coding for tables nested in lists

You can now use Markdown markup to embed a table within a list. This is especially helpful, for example, when you need to provide lists of values to complete a step in a task.

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

Including line breaks, paragraphs, and ordered and unordered lists within Markdown tables is now supported. You might use this feature to break up several sentences in a table cell or include concise lists of options.

New extension for embedding audio files

We’ve added a new audio extension to embed audio files, such as .mp3, .wav, and more within your docs. For information about how to use the new extension, see Audio.

Support for conrefs and keyrefs

You might have common content that is needed in multiple topics within your doc set. You can use a content reference (conref) to write this content once and pull it into many Markdown topics in your same doc set.

In IBM Cloud, we leverage conrefs for common content that is repeated within doc sets. For details, see Content references.

And, we added the ability to use key references (keyrefs) that are simple key-value pairs. In IBM Cloud, keyrefs are leveraged mostly for just product names. Approved product names are stored in a central conkeyref YAML file so that writers across the IBM Cloud platform can refer to these keyword values in the YAML file any time they reference the product name. This allows you to easily change the name in one location, and then after a build, any reference to that product name will magically get updated everywhere the conkeyref was used! This was previously our conrefs implementation in marked-it 1.0. For details, see Key references.

marked-it specification

To view the full marked-it documentation, go to https://ibm.github.io/marked-it.