@author.io/metadoc-md
v0.0.5
Parse markdown code within description attributes of a metadoc output file.
0/weekUpdated 3 years agoMITUnpacked: 11.0 KB
Published by Corey Butler
npm install @author.io/metadoc-mdmetadoc-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:
``sh`
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:
`sh`
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 (--svg
, , etc.) with a "/" as required by XHTML.
- 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:_
`html`
graph LR
a-->b;
b-->c;
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.
$3
- 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:_
`html`
x = {-b \pm \sqrt{b^2-4ac} \over 2a}
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.