Mergemaid
Tool for merging sequence diagrams in .md
and .mmd
file formats into one master diagram based on the official mermaid.js syntax.
Index
Quick Start
To include Mergemaid in your workflow simply import the module and run it like this:
const Mergemaid = require('mergemaid');
const mergemaid = new Mergemaid({ root: __dirname });
mergemaid.merge('./path/to/directory/with/diagrams', './path/to/generated/diagrams');
The merge
function offers an input and output directory for specifying multiple merge operations in one workflow. The input directory will be used in the absence of an output directory.
In this case, all .md
and .mmd
files found in the ./path/to/directory/with/diagrams
directory that contain imports, links and functions will be processed outputted into ./path/to/generated/diagrams
directory.
Options
Mergemaid offers a number of configuration options that can be passed into the constructor:
Option | Type | Optional | Description |
---|---|---|---|
root | String | No | For defining the root path of the project. All subsequent directories will be relative to that path (__dirname for most applications). |
comments | Boolean | Yes | When enabled, header and import comments will be included in the master file for easy segment reference. Set to false by default. |
prefix | String | Yes | When set, master- file prefix will be changed to the passed value. |
fileWarningComment | Boolean | Yes | When disabled, it will omit the warning in the header of the generated document. Set to true by default. |
outputExtension |
md , mmd or txt
|
Yes | The extension of the generated file(s). Set to md by default. |
Operations
Diagram Header Keys
A diagram header key is a way of specifying a reference to a diagram block in a .md
and .mmd
file. This allows other import and linking operations to reference these blocks:
<!-- diagram: my-diagram-name -->
```mermaid
sequenceDiagram
A->>B: My referenced diagram
```
these annotations can be defined in any comment style supported by markdown that include:
<!-- diagram: my-diagram-name -->
# diagram: my-diagram-name
%% diagram: my-diagram-name %%
Diagram Imports
A common way of merging multiple diagram pieces into one master diagram is by using an import statements. This can be achieved by either importing the entire file or an individual block from a file.
To import a complete file, simply specify a relative path to your .md
or .mmd
file like so:
TODO: Modification (always include paths on import - when the path is omitted it is assumed that the block is contained in the same file as the import statement):
<!-- import: ./relative/path/to/a/file#name-of-diagram -->
```mermaid
sequenceDiagram
%% import: ./relative/path/to/a/file#name-of-diagram
```
```mermaid
sequenceDiagram
A->>B: Regular sequence diagram
%% import: ./path/to/my/diagram.mmd %%
```
Alternatively, a diagram key can be used to import an individual diagram from a file:
```mermaid
sequenceDiagram
A->>B: Regular sequence diagram
%% import: my-diagram %%
%% import: another-diagram %%
```
where my-diagram
and another-diagram
refer to diagram header keys found in other files.
Linking Diagrams
Diagram linking is an alternative way of viewing multiple smaller pieces of a diagram in one large file that include additional viewing options, where pieces of a diagram can be turned off.
Note: This feature requires an enhanced VS Code Extension.
Similarly to import statements, links can be defined by referencing either paths to a complete file or individual pieces referenced by a diagram key:
```mermaid
sequenceDiagram
A->>B: Regular sequence diagram
# link: my-diagram
With unsupported extensions the link will be invisible as the link imports the block in a comment for backwards compatibility (preventing the entire diagram from being broken).
Diagram Functions
Function statements, as the name might suggest, allow for script execution from withing the diagram extension viewer.
Note: This feature requires an enhanced VS Code Extension.
Function statements only reference code blocks that contain function header keys:
```javascript
const myFunction = (params) => {
alert(`my ${params}.`);
}
```
that can be used like this:
```mermaid
sequenceDiagram
A->>B: Regular sequence diagram # function: my-function(params)
This will include the function in a comment block for backwards compatibility, preventing the diagram from breaking with unsupported extensions.
Using CLI
Another way of using Mergemaid is from the CLI, by first installing it globally with:
npm install -g mergemaid
then running it with:
mergemaid diagram.md -output /path/to/output/directory