https://github.com/kazumatu981/markdown-it-kroki

markdown-it kroki plugin.
https://github.com/kazumatu981/markdown-it-kroki

Last synced: 1 day ago
JSON representation

markdown-it kroki plugin.

• Host: GitHub
• URL: https://github.com/kazumatu981/markdown-it-kroki
• Owner: kazumatu981
• License: mit
• Created: 2022-10-16T01:02:43.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-06-22T00:11:48.000Z (5 months ago)
• Last Synced: 2024-09-26T21:36:31.099Z (about 1 month ago)
• Language: JavaScript
• Size: 183 KB
• Stars: 5
• Watchers: 1
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-marp - @kazumatu981/markdown-it-kroki - markdown-it plugin (mainly designed for Marp), to support [Kroki](https://kroki.io/) powered embeding diagrams. (Plugins / Compatible markdown-it plugins)

README

        
# markdown-it-kroki

> This library was designed to embed [Kroki.io](https://kroki.io/) diagram into [Marp](https://marp.app/) slide decks!!

This library is a plugin for markdown-it to embed figure created by textual syntax.

To use this package, you can embed **Software Diagram** (like UML) written by **code** in Marp slide decks.

See marp sample code.

## Sample

    ---

    marp: true

    ---

    ## plantuml

    ```plantuml[platuml image]

    @startuml

    left to right direction

    actor Guest as g

    package Professional {

    actor Chef as c

    actor "Food Critic" as fc

    }

    package Restaurant {

    usecase "Eat Food" as UC1

    usecase "Pay for Food" as UC2

    usecase "Drink" as UC3

    usecase "Review" as UC4

    }

    fc --> UC4

    g --> UC1

    g --> UC2

    g --> UC3

    @enduml

    ```

![plantuml-sample](img/plantuml-sample.png)

If you want to write diagrams, you can use various syntaxes (such as [PlantUML](https://plantuml.com/) or [Mermaid](https://mermaid-js.github.io/mermaid/#/)) within fenced code blocks.

## How to install

You can install `npm install` command like below.

```bash

npm install -D @kazumatu981/markdown-it-kroki

```

## How to use

Here is the how to use `markdow-it-kroki`.

This section introduces how to create Marp slides deck project,

and introduces how to create Marp slides deck server.

You can find detail [here](https://marp.app/),

and you can learn about marp plugin ecosystem [here](https://marpit.marp.app/usage?id=extend-marpit-by-plugins).

### **[1st step]** Create slides deck project

First, to create a slides deck, you have to create a **Marp Project** directory and initialize a npm project.

```bash

mkdir myslides

cd myslides

npm init -y

```

Then, build a Marp environment.

Install [@marp-team/marp-cli](https://github.com/marp-team/marp-cli).

```bash

npm install -D @marp-team/marp-cli

```

> Off-course you can install as **global package** (like `npm install -g @marp-team/marp-cli`), or **run at-once** (like `npx`).

### **[2nd step]** Download this project and install

```bash

git clone https://github.com/kazumatu981/markdown-it-kroki.git

cd myslides

npm install -D path/to/markdown-it-kroki

```

### **[3rd step]** Create `marp.config.js`.

Here is the configuration file for **Marp**.

```javascript

module.exports = {

    inputDir: './slides',

    engine: ({ marp }) => marp.use(require('@kazumatu981/markdown-it-kroki'), {

        entrypoint: "https://kroki.io",

    })

}

```

### **[4th step]** Create your slides

On `slies` directory. you create slides-deck. like this.

    ---

    marp: true

    ---

    ## mermaid

    ```mermaid[mermaid image]

    flowchart TD

        Start --> Stop

    ```

### **[5th step]** run server

Run marp server.

```bash

marp -s -c marp.config.js

```

## Detail

### Syntax of Markdown

#### Diagram Language

You have to write diagram language by [fenced code block](https://spec.commonmark.org/0.30/#fenced-code-blocks) syntax, start with **triple back quot** and after that the language.

    ```plantuml

> [!NOTE]  

> This package depends on [Kroki.io](https://kroki.io).   

> If you want to know which **diagram languages are supported**,

> please check the official website at [https://kroki.io/](https://kroki.io/).

#### Alt Text

You can write Alt-text attribute to IMG tag in HTML.

Write in `square blacket` after **Diagram Language**.

    ```mermaid [check your network config..]

### Options of `constructor`

| property-name    | type     | mean                                                   | defaul value              |

| ---------------- | -------- | ------------------------------------------------------ | ------------------------- |

| `entrypoint`     | `string` | The entry point for Kroki server.                      | `'https://kroki.io'`      |

| `containerClass` | `string` | class name of container (`DIV`-tag `class` attribute). | `'kroki-image-container'` |

| `imageFormat`    | `string` | image format of diagram. see [here](https://kroki.io/) | `'svg'`                   |

| `useImg` | `boolean` | use `` tag for embed diagram. ( *for compatibility for past version* ) | `false` |

| `render` | `function` | if you render `html` yourself use this option. see [How To Write `render()` call back](memo/howToWriteRender.md) | `undefined` |