@spruceid/mergemaid

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
  • Options
• Operations
  • Diagram Header Keys
  • Diagram Imports
  • Linking Diagrams
  • Diagram Functions
• Using CLI

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