Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/manastalukdar/markdown-it-textual-uml
Markdown-it plugin to create uml diagrams from text, based on plantuml, mermaid, etc.
https://github.com/manastalukdar/markdown-it-textual-uml
markdown-it mermaidjs plantuml textual-uml uml uml-diagram uml-parser
Last synced: 2 days ago
JSON representation
Markdown-it plugin to create uml diagrams from text, based on plantuml, mermaid, etc.
- Host: GitHub
- URL: https://github.com/manastalukdar/markdown-it-textual-uml
- Owner: manastalukdar
- License: mit
- Created: 2019-08-30T22:55:27.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2024-12-01T06:36:30.000Z (about 1 month ago)
- Last Synced: 2024-12-29T09:32:56.495Z (10 days ago)
- Topics: markdown-it, mermaidjs, plantuml, textual-uml, uml, uml-diagram, uml-parser
- Language: JavaScript
- Homepage:
- Size: 1.43 MB
- Stars: 23
- Watchers: 3
- Forks: 2
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-marp-template - `markdown-it-textual-uml`
- awesome-marp-template - `markdown-it-textual-uml`
README
# markdown-it-textual-uml
1. [Overview](#overview)
2. [UML examples](#uml-examples)
1. [PlantUML](#plantuml)
2. [DOT](#dot)
3. [ditaa](#ditaa)
4. [mermaid](#mermaid)
3. [Installation](#installation)
4. [Usage](#usage)
1. [Additional steps for mermaid](#additional-steps-for-mermaid)
5. [Development](#development)
6. [References](#references)
7. [License](#license)
## Overview
[](https://www.npmjs.com/package/markdown-it-textual-uml)
[](https://github.com/marketplace/actions/super-linter)
[More project metadata badges [here](./documentation/project/metadata.md). More CI/CD badges [here](./documentation/development/ci-cd.md#current-status).]
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](http://plantuml.com/) | `plantuml` |
| [DOT](https://graphviz.gitlab.io/_pages/doc/info/lang.html) | `dot` |
| [ditaa](http://ditaa.sourceforge.net/) | `ditaa` |
| [mermaid](https://github.com/knsv/mermaid) | `mermaid` |
## UML examples
### PlantUML
````markdown
```plantuml
Bob -> Alice : hello
```
````
### DOT
````markdown
```dot
digraph example1 {
1 -> 2 -> { 4, 5 };
1 -> 3 -> { 6, 7 };
}
```
````
### ditaa
````markdown
```ditaa
+--------+ +-------+ +-------+
| +---+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
```
````
### mermaid
````markdown
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
````
## Installation
node.js, browser:
```text
npm install markdown-it-textual-uml --save
```
## Usage
```javascript
const md = require('markdown-it')()
.use(require('markdown-it-textual-uml'));
```
Or,
```javascript
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](https://github.com/knsv/mermaid/issues/485).
So you should have the following in your html page in order for the mermaid text definitions to be translated into svg.
```html
mermaid.initialize({startOnLoad:true});
```
Details [here](https://mermaid.js.org/config/usage.html).
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:
```javascript
import mermaid from 'mermaid'
mermaid.initialize({ startOnLoad: false });
await mermaid.run()
}
```
## Development
It is highly recommended to use [VS Code](https://code.visualstudio.com/).
I have an open issue to make development, testing and deployments easier but for now following steps have to be followed:
1. Make changes in this project.
2. Update version in package.json.
3. `npm run build`
4. `npm run pack`
5. In a separate test project that includes this npm package:
1. 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.
2. Run `npm cache clean --force`.
3. Delete its package-lock.json.
4. Delete folder for `markdown-it-textual-uml` from within the node_modules folder.
5. Run `npm install`.
Once we have the changes tested out, revert back all changes in the test project.
Now, in this project:
1. Run `npm run publish`.
1.
2. Merge `develop` to `main` using Github PR.
3. Create a GitHub release with the semantically versioned tag against `main`.
4. 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](https://github.com/gmunguia/markdown-it-plantuml)
- [GitHub - tylingsoft/markdown-it-mermaid: Mermaid plugin for markdown-it](https://github.com/tylingsoft/markdown-it-mermaid)
- [GitHub - liradb2000/markdown-it-mermaid: Mermaid plugin for markdown-it](https://github.com/liradb2000/markdown-it-mermaid)
- [GitHub - https://github.com/DatatracCorporation/markdown-it-mermaid](https://github.com/DatatracCorporation/markdown-it-mermaid)
## License
[MIT](https://github.com/manastalukdar/markdown-it-textual-uml/blob/main/LICENSE)