npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@author.io/metadoc-md

v0.0.5

Published

Parse markdown code within description attributes of a metadoc output file.

Downloads

11

Readme

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:

  • --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 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

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

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.