Rendering Documentation Pages using Markdown

HTML is the only supported format for documentation pages in the Mashery CMS. However, Markdown has gained popularity in recent years as an alternative format for API and component documentation. It is used as the standard documentation format by Github, Atlassian Confluence, and Google Docs, to name a few. The purpose of this document is to demonstrate how to allow customers to author their API documentation in Markdown, and correctly render the content as HTML in the portal.

Step-by-step guide

1. Create a new documentation page in the CMS. Be sure to uncheck the Use TinyMCE option at the top of the page

2. Type/paste your markdown into the Body field and save your changes

3. Click the Advanced Options button

4. Add the following code in the Inline JavaScript section

    if (!window.jQuery) {   loadJS('//code.jquery.com/jquery-1.8.2.js', function() {     var converter = new showdown.Converter();     var text = $(".section-body").text();     console.log(text);       var html = converter.makeHtml(text);     console.log(html);     $(".section-body").html(html);   }); }

    

5. Add the following URL in the Custom Javascript file field

    https://cdnjs.cloudflare.com/ajax/libs/showdown/1.7.3/showdown.min.js

That's it!