https://github.com/raghur/mermaid-filter

Pandoc filter for creating diagrams in mermaid syntax blocks in markdown docs
https://github.com/raghur/mermaid-filter

mermaid pandoc pandoc-filter

Last synced: about 2 months ago
JSON representation

Pandoc filter for creating diagrams in mermaid syntax blocks in markdown docs

• Host: GitHub
• URL: https://github.com/raghur/mermaid-filter
• Owner: raghur
• Created: 2015-10-25T08:58:57.000Z (almost 9 years ago)
• Default Branch: master
• Last Pushed: 2024-04-09T03:28:11.000Z (6 months ago)
• Last Synced: 2024-07-20T10:46:51.694Z (2 months ago)
• Topics: mermaid, pandoc, pandoc-filter
• Language: JavaScript
• Size: 461 KB
• Stars: 406
• Watchers: 9
• Forks: 75
• Open Issues: 35
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
Sequence and Graph diagrams in your markdown files!

=========================

`mermaid-filter` is a pandoc filter that adds support for [mermaid](https://github.com/mermaid-js/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](https://github.com/jgm/pandoc/issues/3458).

You have to edit the globally installed `mermaid-filter.cmd` located in `c:\users\\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.

Attributes

--------------------

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

Note that to specify options in attribtues, 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.

    // saves generated diagram in the img subfolder of the current working dir

    ```{.mermaid loc=img}

    // Your diagram code here

    ```

| Option Name | default value | env var | Notes|

|-------------|---------------|---------|------|

|   `caption` |             | `MERMAID_FILTER_CAPTION`| Sets `alt=` attribute on the image|

| `format`    | png         | `MERMAID_FILTER_FORMAT` | Allowed - `svg`|

| `width`     | 800           | `MERMAID_FILTER_WIDTH`  ||

| `theme`     | default       | `MERMAID_FILTER_THEME`  |Corresponds to `--theme`  flag of mermaid.cli|

|`background` | `white`       | `MERMAID_FILTER_BACKGROUND` |Correponds to `--backgroundColor` flag of mermaid.cli|

| `filename`  | NA            | `MERMAID_FILTER_FILENAME`| Takes precedence |

| `loc`| `inline` | `MERMAID_FILTER_LOC`| inline - generates a data url; `imgur` - uploads to imgur; `loc=anythingelse` saves images to folder `anythingelse`

| `scale` | 1|`MERMAILD_FILTER_SCALE`| |

| `imageclass` ||`MERMAID_FILTER_IMAGECLASS`| |

You can also specify an ID to be applied to the rendered image. This may be useful to use [`pandoc-crossref`](https://github.com/lierdakil/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.

The `title` attribute is set to `fig:` by if the id specified starts with `fig:`

(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