Home

Awesome

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:

Input

Metadoc output after metadoc-md:

Output

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:

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.

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

Mermaid Support

Mermaid Graph

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

MathJAX Support

MathJax

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.