@author.io/metadoc-md

metadoc-md

This metadoc post-processor will convert markdown, mermaid, or MathJax snippets within a metadoc's description attributes into HTML.

Metadoc output before metadoc-md:

Metadoc output after metadoc-md:

Usage

This post-processor can be run standalone or as a part of a metadoc build process.

To run as a standalone CLI application, the utility must be installed globally:

npm install -g @author.io/metadoc-md

It can then be used from the command line:

metadoc-md --source /path/to/metadoc/api.json

Alternatively, it metadoc-md can be a part of a series of metadoc post-processors. In this scenario, the module should be saved as part of the devDependencies:

npm install @author.io/metadoc-md --save-dev

It can then be applied as a piped command to the metadoc generation process:

metadoc --source ./src --output ./docs --warnskippedevents --warnnocode --ignore ./work/in/progress | metadoc-md

Additional Flags

Common Flags:

• --output Specify a custom output file (relative or absolute path).

Boolean Flags:

Each boolean flag (except --output) can receive a true/false value to enable/disable a feature. For example, to disable GFM, use --gfm false. If no value is supplied, it is assumed to be true. This means --gfm is the same as --gfm true.

• --pedantic Conform to the original markdown.pl as much as possible. Don't fix original markdown bugs or behavior. Turns off and overrides gfm.
• --gfm Apply Github Flavored Markdown. Enabled by default
• --tables When using gfm, use GFM Tables extension. Enabled by default.
• --breaks If true, use GFM hard and soft line breaks. Requires gfm be true.
• --smartlists If true, use smarter list behavior than those found in markdown.pl.
• --smartypants If true, use "smart" typographic punctuation for things like quotes and dashes.
• --xhtml If true, emit self-closing HTML tags for void elements (
  , , etc.) with a "/" as required by XHTML.
• --svg Renders mermaid SVG files. See mermaid support secction below.

These features are all implemented by passing configuration values into marked configuration options.

Mermaid Support

Mermaid generates graphical SVG diagrams from text. It follows a markdown-like approach. metadoc-md identifies mermaid text and converts it to an HTML-friendly format.

For example:

Metadoc output before metadoc-md:

```mermaid
graph LR
a-->b;
b-->c;
```

Metadoc output after metadoc-md:

<div id="mermaid1" class="mermaid">
  graph LR
  a-->b;
  b-->c;
</div>

As shown above, metadoc-md identifies mermaid code and generates an HTML container for it with an automatic ID. However; it does not generate the SVG graphic. Mermaid provides a browser library for this, which can parse the HTML and replace it with an SVG graphic. See the usage instructions) for detail.

Recognized Mermaid Types

• sequenceDiagram
• classDiagram
• graph (flowcharts)
• gitGraph
• gantt

MathJAX Support

MathJax will generate equation displays from text. Metadoc-md identifies these equations using a markdown-like approach.

For example:

Before metadoc-md:

```math-tex
x = {-b \pm \sqrt{b^2-4ac} \over 2a}
```

After metadoc-md:

<div id="math1" class="math">
  x = {-b \pm \sqrt{b^2-4ac} \over 2a}
</div>

As shown above, metadoc-md identifies MathJax code and generates the HTML container for it. Notice the language is math-tex, indicating the equation content is LaTeX format. math-inlinetex, math-asciimath, and math-mathml are also supported by MathJax. However; metadoc-md does not generate any graphics. The MathJax Getting Started Guide provides instructions for generating the graphics in the browser.