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

> Learn how to render diagrams from code blocks using Kroki integration with PlantUML support in Astro Big Doc. Convert plantuml code into SVG diagrams automatically.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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:

```astro
---
// 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`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/components/markdown/code/kroki.yaml). This YAML file enumerates every format that Kroki can render, including **plantuml**:

```yaml

# 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:

````markdown

```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:

```astro
---
// 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:

````markdown

```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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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:

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

```

The configuration logic in [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) (lines 12-13) checks for this environment variable:

```js
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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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):

```js
// 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):

```js
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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/libs/assets.js), enabling downstream components to display titles, captions, or alternative text alongside the rendered SVG.