How to Render Diagrams from Code Blocks Using Kroki Integration with PlantUML Support in Astro Big Doc

Astro Big Doc automatically converts fenced code blocks tagged with plantuml (or other supported languages) into rendered SVG diagrams by sending the source to a Kroki server and caching the result.

The astro-big-doc repository provides a built-in integration that transforms textual diagram definitions into scalable vector graphics at build time. By leveraging the Kroki diagram-as-a-service platform, the project supports multiple diagram languages—including PlantUML—without requiring local Java or Graphviz installations.

How the Kroki Integration Works

The rendering pipeline follows a strict path from Markdown parsing to cached SVG injection. When the Astro content processor encounters a fenced code block, it delegates to specialized components that determine whether the block represents executable code or a diagram definition.

The Decision Flow in Code.astro

The entry point for all fenced blocks is src/components/markdown/code/Code.astro. This component checks whether the block's language appears in the Kroki configuration:

---
// src/components/markdown/code/Code.astro (lines 29-31)
const is_diagram = kroki.languages.includes(language);
---
{(is_diagram) && <Kroki language={language} code={code} params={params} meta={meta}/>}

If is_diagram evaluates to true, the component renders the Kroki component instead of the standard syntax highlighter.

Supported Diagram Languages

The list of valid diagram languages resides in src/components/markdown/code/kroki.yaml. This YAML file enumerates every format that Kroki can render, including plantuml:

# src/components/markdown/code/kroki.yaml

languages:
  - graphviz
  - nwdiag
  - plantuml
  - mermaid
  - blockdiag

Any language listed here triggers the diagram rendering pipeline when used as the info string in a fenced code block.

Rendering PlantUML Diagrams from Markdown

To generate a diagram, authors write standard PlantUML syntax inside a fenced block tagged with the plantuml language identifier.

Basic PlantUML Syntax

Place the following in any Markdown file within the content folder:

```plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another request
Alice <-- Bob: Another response
@enduml

```

During the build process, src/components/markdown/code/Kroki.astro constructs a POST request to the configured Kroki server:

---
// src/components/markdown/code/Kroki.astro (lines 15-18)
const server = config.kroki_server; // defaults to https://kroki.io
const url = `${server}/${language}/svg/`;
---

The component sends the raw PlantUML source to this endpoint (lines 24-25) and receives an SVG string in response.

Using Meta Data for Diagram Captions

Astro Big Doc supports optional metadata after the language identifier. Adding a single token enables downstream components to fetch additional data for captions or alt text:

```plantuml architecture-overview
@startuml
[Client] --> [Load Balancer]
[Load Balancer] --> [Server]
@enduml

```

In Code.astro, the meta string is parsed into params (line 21) and passed to the getMetaData function from src/libs/assets.js (line 184) when parameters are present (line 36). This allows custom wrapper components to display titles or descriptions alongside the rendered SVG.

Configuring the Kroki Server Endpoint

By default, the integration uses the public Kroki instance at https://kroki.io. Organizations running private Kroki servers can override this via environment variables.

Set the KROKI_SERVER variable in a .env file at the repository root:

KROKI_SERVER=https://my-private-kroki.example.com

The configuration logic in config.js (lines 12-13) checks for this environment variable:

const kroki_server = (process.env.KROKI_SERVER == null) ?
    "https://kroki.io" : process.env.KROKI_SERVER;

If the variable is undefined, the system falls back to the public endpoint.

Caching and Performance Optimization

To avoid redundant network requests during rebuilds, the integration implements a filesystem cache managed by src/components/markdown/code/diagram.js.

The Caching Mechanism

When a diagram is requested, the system computes an MD5 hash of the source code (lines 5-7):

// src/components/markdown/code/diagram.js
import { createHash } from 'node:crypto';
const hash = createHash('md5').update(code).digest('hex').slice(0, 16);

The cache directory is determined by config.code_path (line 7). If diagram.svg exists at <code_path>/<hash>/, the cached version is returned immediately. Otherwise, the generator function (provided by Kroki.astro) fetches the SVG from the server, and the result is written to disk (lines 15-18):

await fs.mkdir(cacheDir, { recursive: true });
await fs.writeFile(path.join(cacheDir, 'diagram.svg'), svg);
await fs.writeFile(path.join(cacheDir, 'code.txt'), code);

This ensures that subsequent builds—even across different sessions—reuse previously generated diagrams, significantly reducing build times and eliminating external dependencies for cached content.

Summary

• Astro Big Doc automatically renders diagrams from fenced code blocks using the Kroki integration when the language matches entries in src/components/markdown/code/kroki.yaml.
• PlantUML is supported natively; simply use ```plantuml blocks in Markdown.
• The Code.astro component routes diagram requests to Kroki.astro, which POSTs source code to a configurable Kroki server and receives SVG output.
• Filesystem caching via diagram.js stores generated SVGs using MD5 hashes, avoiding redundant network requests during rebuilds.
• Override the default https://kroki.io endpoint by setting the KROKI_SERVER environment variable in config.js.

Frequently Asked Questions

How do I add support for additional diagram languages beyond PlantUML?

Edit src/components/markdown/code/kroki.yaml and append the new language identifier to the languages array. Kroki supports over 20 formats including Mermaid, Graphviz, and BlockDiag. Once added, fenced code blocks using that language identifier will automatically trigger the diagram rendering pipeline.

Can I use a self-hosted Kroki server instead of the public instance?

Yes. Set the KROKI_SERVER environment variable to your private endpoint URL (e.g., https://kroki.internal.company.com). The configuration logic in config.js prioritizes this variable over the default https://kroki.io public server, directing all diagram generation requests to your infrastructure.

Where are the generated diagram files stored?

Cached diagrams reside in the directory specified by config.code_path (typically dist/codes/ or similar), organized in subdirectories named by the first 16 characters of the MD5 hash of the source code. Each cache entry contains diagram.svg (the rendered output) and code.txt (the original source for reference).

How do I attach captions or metadata to my PlantUML diagrams?

Add a space-separated token after the language identifier in the fenced code block (e.g., ```plantuml system-architecture). This token becomes available as params[0] in the component pipeline and is processed by getMetaData from src/libs/assets.js, enabling downstream components to display titles, captions, or alternative text alongside the rendered SVG.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}