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

mermaid-filter

v1.4.7

Published

Pandoc filter for mermaid

Downloads

3,096

Readme

Sequence and Graph diagrams in your markdown files!

mermaid-filter is a pandoc filter that adds support for mermaid syntax diagrams in markdown.

Write your diagrams in fenced code blocks as usual like this:

~~~mermaid
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
~~~

and get this in rendered doc

Installation and usage

  1. npm install --global mermaid-filter
  2. To convert your markdown file something.md into something.html, use pandoc -t html -F mermaid-filter -o something.html something.md

WINDOWS - you need mermaid-filter.cmd in the line above

Windows 8.1 - On windows 8.1, mermaid-filter.cmd fails - apparently due to change in how the CMD.exe works for subprocesses? - see this issue thread. You have to edit the globally installed mermaid-filter.cmd located in c:\users\<username>\AppData\Roaming\npm to use ~dp$PATH:0. Unfortunately, you will need to do this each time you install/update mermaid-filter since it overwrites the cmd file.

Options

You have a couple of formatting options via attributes of the fenced code block to control the rendering

  • Pandoc caption, the filename is this value cleaned up - Use {.mermaid caption="Caption Text Here"}
  • Image Format - Use {.mermaid format=svg} Default is png
  • Width - Use {.mermaid width=400} default width is 800
  • Theme - Use {.mermaid theme=forest} default is 'default'. Corresponds to --theme flag of mermaid.cli
  • Background - Use {.mermaid background=transparent} default is 'white'. Correponds to --backgroundColor flag of mermaid.cli
  • Filename - Use {.mermaid filename="file with space"} to set the filename. This has priority over the caption
  • Save path - Use {.mermaid loc=img} default loc=inline which will encode the image in a data uri scheme.
    • Possible values for loc
      • loc=inline - default; encode image to data uri on img tag.
        • For widest compatibility, use png (default)
        • SVG has trouble on IE11
      • loc=imgur - upload png to imgur and link to it.
      • loc=<anythingelse> -treat as folder name to place images into

Note that to specify options, you need to use the curly braces syntax and have the .mermaid class attached. Admittedly, this is uglier than the earlier syntax on top - but that's how Pandoc wants it.

It's also possible to override global defaults by using environment variables. The name for these environment variables are the same as the attributes prefixed with a MERMAID_FILTER_ so that width would be MERMAID_FILTER_WIDTH.

You can also specify an ID to be applied to the rendered image. This may be useful to use pandoc-crossref or similar packages to reference your diagrams, for example:

```{.mermaid #fig:example}
// Your diagram code here
```

This text has a reference @fig:example which is automatically inserted.

(Note that pandoc-crossref will automatically find and use the caption= option. Also note that the order of applying the filters matters - you must apply mermaid-filter before pandoc-crossref so that pandoc-crossref can find the images.)

JSON and CSS configuration

Mermaid cli allows you to specify additional options in a json configuration file and a css file. mermaid-filter will look in the current working directory for .mermaid-config.json and .mermaid.css and if found, pass them in to mermaid cli.

Puppeteer Configuration - mermaid-filter will look in the current working directory for a .puppeteer.json and pass it on to mermaid cli (-p option of mmdc)if found