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:
- Simple for the common particular person 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 modification provides just a few 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 positive 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 regular 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 help of navigation titles (navtitles). When you’ve got a prolonged matter 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 listing is a collection of phrases adopted by a definition of the time period. For particulars about methods 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 an inventory. That is particularly useful, for instance, when you must present lists of values to finish a step in a activity.
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 embrace concise lists of choices.
New extension for embedding audio recordsdata
We’ve added a brand new audio extension to embed audio recordsdata, comparable to .mp3, .wav, and extra inside your docs. For details about methods to use the brand new extension, see Audio.
Assist for conrefs and keyrefs
You might need widespread content material that’s wanted in a number of matters inside your doc set. You should use a content material reference (conref) to put in writing this content material as soon as and pull it into many Markdown matters in your identical doc set.
In IBM Cloud, we leverage conrefs for widespread 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 can be easy key-value pairs. In IBM Cloud, keyrefs are leveraged principally for simply product names. Permitted 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.
To view the total marked-it documentation, go to https://ibm.github.io/marked-it.