npm package: @spruceid/mergemaid
Description: Tool for merging mermaid sequence diagrams
Author: Spruce Systems Inc.
Latest version: 0.0.4

# Mergemaid
Tool for merging sequence diagrams in `.md` and `.mmd` file formats into one master diagram based on the official [mermaid.js syntax](https://mermaid-js.github.io/mermaid/#/n00b-syntaxReference?id=syntax-structure).

## Index
- [Quick Start](#quick-start)
  + [Options](#options)
- [Operations](#operations)
  + [Diagram Header Keys](#diagram-header-keys)
  + [Diagram Imports](#diagram-imports)
  + [Linking Diagrams](#linking-diagrams)
  + [Diagram Functions](#diagram-functions)
- [Using CLI](#using-cli)

<br>

# Quick Start
To include Mergemaid in your workflow simply import the module and run it like this:

```JavaScript
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.

<br>

## 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.

<br>

# 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](#diagram-header-keys) 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](#diagram-header-keys) found in other files.

<br>

## 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](link-to-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](#diagram-header-keys):

~~~
```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). 

<br>

## 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](link-to-extension).

Function statements only reference code blocks that contain [function header keys](#diagram-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:

```bash
npm install -g mergemaid
```

then running it with:

```bash
mergemaid diagram.md -output /path/to/output/directory
```