Fork from https://github.com/vuesence/vitepress-plugin-diagrams

VitePress Plugin Kroki

English | Español | 中文 | Українська | Русский

A VitePress plugin that adds support for various diagram types using the Kroki service. The plugin automatically converts diagram code blocks into SVG images, caches them locally, and provides a clean, customizable display with optional captions.

Using an external service requires an internet connection during build, but it offers significant advantages over creating an image on the client (huge bundle and performance drop) and over creating an image on the server (complexity - mermaid requires puppeteer for this, for example).

Features

• Supports multiple diagram types (Mermaid, PlantUML, GraphViz, and more)
• Automatic SVG generation and caching (once generated it's cached locally until the diagram code changes)
• Optional diagram captions
• Customizable output directory and public path
• Clean, semantic HTML output
• Use can use any editor to create diagrams (for example VS Code with Mermaid extension)

Installation

pnpm add -D vitepress-plugin-diagrams

yarn add -D vitepress-plugin-diagrams

npm install --save-dev vitepress-plugin-diagrams

Quick Start

1. Add to VitePress config (.vitepress/config.ts):

import { defineConfig } from "vitepress";
import { markdownItGenerateDiagramsPlugin, viteGenerateDiagramsPlugin } from "vitepress-plugin-kroki";

export default defineConfig({
    markdown: {
        config: async (md) => {
            markdownItGenerateDiagramsPlugin(md, {
                diagramsDir: "docs/public/diagrams",
                diagramsDistDir: "diagrams",
                publicPath: '/public/diagrams',
            });
        }
    },
    vite: {
        plugins: [viteGenerateDiagramsPlugin()]
    },
});

2. Create diagrams in markdown:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[Cancel]
```
<!-- diagram id="1" caption: "System Design Flow" -->

You can also create diagram in markdown using a file if you set the type followed by ":file":

```excalidraw:file
/example.excalidraw
```

note: it will use the plugin option "diagramsDir" as base for the path.

Diagram Metadata

The diagram metadata feature provides additional context and identification. You can add metadata to your diagrams using special HTML comments.

<!-- diagram id="1" caption: "System Design Flow" -->

• Assign a unique ID to each diagram to prevent cache bloating (optional, if you do not modify and regenerate diagrams)
• Add descriptive captions under the diagram (optional)

Supported Diagrams

Mermaid, PlantUML, GraphViz, BlockDiag, BPMN, Bytefield, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, Nomnoml, Pikchr, Structurizr, Svgbob, Symbolator, TikZ, UMlet, Vega, Vega-Lite, WaveDrom, WireViz

View full list of supported diagrams →

Configuration

| Option | Type | Default | Description | |--------|------------|--------------------------|-------------| | diagramsDir | string | "docs/public/diagrams" | Directory where SVG files will be stored | | publicPath | string | "/diagrams" | Public path for accessing the SVG files | | krokiBaseUrl | string | https://kroki.io | BaseUrl for kroki, useful when using self-hosted instances | | customFetch | function | default fetch function | Custom fetch to set proxy or specific network configuration |

Output

Output Structure

<figure class="vpd-diagram vpd-diagram--[diagramType]">
  <img 
    src="[publicPath]/[diagramType]-[diagramId]-[hash].svg" 
    alt="[diagramType] Diagram" 
    class="vpd-diagram-image"
  />
  <figcaption class="vpd-diagram-caption">
    [caption]
  </figcaption>
</figure>

You can customize the CSS classes to match your theme.

Note

When updating a diagram, you may see a placeholder image on the browser page. This is normal, because the svg file is loaded asynchronously and may not be displayed immediately. Just refresh the page.

License

MIT

Contributing

Contributions are welcome! Before submitting a Pull Request, please open an issue first to discuss proposed changes.

Credits

This plugin uses the Kroki service for diagram generation.