markdown-it-textual-uml
v0.17.1
Published
Markdown-it markdown parser plugin to create uml diagrams from text, based on plantuml, mermaid, etc.
Downloads
17,588
Maintainers
Readme
markdown-it-textual-uml
Overview
[More project metadata badges here. More CI/CD badges here.]
This is a markdown-it
markdown parser plugin to create uml diagrams from text, based on plantuml, mermaid, etc.
At this point the following textual uml offerings are supported:
| UML Offering | Markdown fence identifier |
| ----------------------------------------------------------- | ------------------------- |
| PlantUML | plantuml
|
| DOT | dot
|
| ditaa | ditaa
|
| mermaid | mermaid
|
UML examples
PlantUML
```plantuml
Bob -> Alice : hello
```
DOT
```dot
digraph example1 {
1 -> 2 -> { 4, 5 };
1 -> 3 -> { 6, 7 };
}
```
ditaa
```ditaa
+--------+ +-------+ +-------+
| +---+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
```
mermaid
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
Installation
node.js, browser:
npm install markdown-it-textual-uml --save
Usage
const md = require('markdown-it')()
.use(require('markdown-it-textual-uml'));
Or,
import markdownItTextualUml from 'markdown-it-textual-uml'
const md = require('markdown-it')()
.use(markdownItTextualUml);
Additional steps for mermaid
For mermaid, you have to include the mermaid js
file in your application and initialize it after the window has loaded. Just using this plugin is not enough to ensure that the diagram is rendered correctly.
Note: mermaid js has a dependency on the browser window being loaded before it can initialize. Related GitHub issue.
So you should have the following in your html page in order for the mermaid text definitions to be translated into svg.
<script src="mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
Details here.
When using some sort of framework, be aware that mermaid.initialize
would have to be called after the page has loaded. For example, with vue.js or nuxt.js, this could look like:
<script setup>
import mermaid from 'mermaid'
mermaid.initialize({ startOnLoad: false });
await mermaid.run()
}
</script>
Development
It is highly recommended to use VS Code.
I have an open issue to make development, testing and deployments easier but for now following steps have to be followed:
- Make changes in this project.
- Update version in package.json.
npm run build
npm run pack
- In a separate test project that includes this npm package:
- Change the entry in its package.json to:
"markdown-it-textual-uml": "file:./markdown-it-textual-uml-0.1.3.tgz"
. Change version (last released version) to version from step 2. - Run
npm cache clean --force
. - Delete its package-lock.json.
- Delete folder for
markdown-it-textual-uml
from within the node_modules folder. - Run
npm install
.
- Change the entry in its package.json to:
Once we have the changes tested out, revert back all changes in the test project.
Now, in this project:
- Run
npm run publish
. - Merge
develop
tomain
using Github PR. - Create a GitHub release with the semantically versioned tag against
main
. - Pull repo to local (optional) if you have
main
branch locally.
References
Here are some alternative npm packages:
- GitHub - gmunguia/markdown-it-plantuml: plantuml diagrams in your markdown
- GitHub - tylingsoft/markdown-it-mermaid: Mermaid plugin for markdown-it
- GitHub - liradb2000/markdown-it-mermaid: Mermaid plugin for markdown-it
- GitHub - https://github.com/DatatracCorporation/markdown-it-mermaid