PlantUML Support

[joesaby]

What version of starlight are you using?

0.32.2

What is your idea?

Discussion in the Discord channel in thread (https://discord.com/channels/830184174198718474/1345017578497773589) about support for plantuml rendering using rehype within Astro.

Example of astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import rehypePlantuml from './src/scripts/plantuml-png-rehype.ts';

// https://astro.build/config
export default defineConfig({
	markdown: {
		rehypePlugins: [
			rehypePlantuml,
		]
	},
	integrations: [
		starlight({
			title: 'My Docs',
			social: {
				github: 'https://github.com/withastro/starlight',
			},
			customCss: [
				"/src/styles/plantuml.css",
				"/src/custom-width.css",
			  ],
			sidebar: [
				{
					label: 'Guides',
					items: [
						// Each item here is one entry in the navigation menu.
						{ label: 'Example Guide', slug: 'guides/example' },
						{ label: 'Callflow 1', slug: 'callflow1' },
						{ label: 'Callflow 2', slug: 'callflow2' },
					],
				},
				{
					label: 'Reference',
					autogenerate: { directory: 'reference' },
				},
			],
		}),
	],
});

Where

		rehypePlugins: [
			rehypePlantuml,
		]

rehypes any plantuml as code blocks in markdown. Code blocks look like

@startuml
Bob -> Alice : hello
@enduml

Code for ./src/scripts/plantuml-png-rehype.ts

// src/scripts/plantuml-rehype.ts
import type { Root, Element, Parent, RootContent } from 'hast';
import type { Plugin } from 'unified';
import { visit } from 'unist-util-visit';
import axios from 'axios';
import * as zlib from 'zlib';

// Define more specific types for the rehype plugin
type RehypePlugin = Plugin<[], Root>;

/**
 * Determines if a node is a PlantUML code block
 */
function isPlantUMLBlock(node: Element): boolean {
  if (node.tagName !== 'pre') return false;
  
  // Get the code element
  const codeElement = node.children?.[0] as Element | undefined;
  if (!codeElement || codeElement.tagName !== 'code') return false;
  
  // Check for className as an array of strings
  const classNames = codeElement.properties?.className;
  
  if (Array.isArray(classNames)) {
    // Check for the exact 'language-plantuml' class
    return classNames.some(className => {
      if (typeof className !== 'string') return false;
      return className === 'language-plantuml';
    });
  }
  
  return false;
}

/**
 * A rehype plugin that converts PlantUML code blocks to PNG images
 * using a locally hosted PlantUML server.
 */
const rehypePlantuml: RehypePlugin = () => {
  return async (tree: Root) => {
    const codeBlocks: Array<{
      node: Element;
      parent: Parent;
      index: number;
      codeNode: Element;
    }> = [];

    // First pass: collect all PlantUML code blocks
    visit(tree, 'element', (node: Element, index: number | null, parent: Parent | null) => {
      if (isPlantUMLBlock(node) && parent && typeof index === 'number') {
        codeBlocks.push({
          node,
          parent,
          index,
          codeNode: node.children[0] as Element
        });
      }
    });

    console.log(`Found ${codeBlocks.length} PlantUML blocks to process`);

    // Second pass: convert PlantUML code blocks to PNG
    await Promise.all(
      codeBlocks.map(async ({ node, parent, index, codeNode }) => {
        try {
          // Get the PlantUML content
          const content = codeNode.children?.[0]?.value as string | undefined;
          if (!content) {
            console.warn('Empty PlantUML content found');
            return;
          }

          console.log(`Processing PlantUML content: ${content.substring(0, 50)}...`);

          // Encode the PlantUML content using the proper encoder
          const encodedContent = encodePlantUmlForUrl(content.trim());
          
          // Call the local PlantUML server to get the PNG
          const url = `http://localhost:8080/plantuml/png/${encodedContent}`;
          console.log(`Requesting diagram from: ${url}`);
          
          const response = await axios.get(url, { 
            responseType: 'arraybuffer',
            timeout: 10000 // 10 second timeout
          });

          // Convert the binary response to a base64 string for embedding in HTML
          const base64Image = Buffer.from(response.data).toString('base64');
          const imgSrc = `data:image/png;base64,${base64Image}`;

          console.log(`Received PNG response of length: ${response.data.length}`);

          // Create a figure element to contain the PNG image
          const figureNode: Element = {
            type: 'element',
            tagName: 'figure',
            properties: { className: ['plantuml-diagram'] },
            children: [
              {
                type: 'element',
                tagName: 'img',
                properties: { 
                  src: imgSrc,
                  alt: 'PlantUML Diagram',
                  className: ['plantuml-img']
                },
                children: []
              },
            ],
          };

          // Replace the original code block with the PNG image
          parent.children.splice(index, 1, figureNode);
        } catch (error) {
          console.error('Error processing PlantUML diagram:', error);
          
          // Create an error message if the conversion fails
          const errorNode: Element = {
            type: 'element',
            tagName: 'div',
            properties: { className: ['plantuml-error'] },
            children: [
              {
                type: 'element',
                tagName: 'p',
                children: [
                  {
                    type: 'text',
                    value: `Error generating PlantUML diagram: ${(error as Error).message}`,
                  },
                ],
              },
              node, // Keep the original code block
            ],
          };
          
          // Replace the original code block with the error message
          parent.children.splice(index, 1, errorNode);
        }
      })
    );
  };
};

// PlantUML uses a modified base64 encoding
const PLANTUML_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_';

/**
 * Encodes a string into the format expected by PlantUML servers
 */
function encodePlantUmlForUrl(plantUmlText: string): string {
  // Add the @startuml and @enduml if they're not already there
  let text = plantUmlText.trim();
  if (!text.startsWith('@startuml')) {
    text = '@startuml\n' + text;
  }
  if (!text.endsWith('@enduml')) {
    text = text + '\n@enduml';
  }
  
  // Compress with zlib deflate
  const compressed = zlib.deflateSync(text, { level: 9 });
  
  // Encode with PlantUML's custom base64 variant
  return encode64(compressed);
}

/**
 * Encodes a buffer using PlantUML's modified base64 encoding
 */
function encode64(data: Buffer): string {
  let result = '';
  let currentByte = 0;
  let bitsLeft = 0;
  
  for (let i = 0; i < data.length; i++) {
    currentByte = (currentByte << 8) | data[i];
    bitsLeft += 8;
    
    while (bitsLeft >= 6) {
      bitsLeft -= 6;
      const index = (currentByte >> bitsLeft) & 0x3F;
      result += PLANTUML_ALPHABET[index];
    }
  }
  
  // Handle remaining bits
  if (bitsLeft > 0) {
    currentByte = (currentByte << (6 - bitsLeft)) & 0x3F;
    result += PLANTUML_ALPHABET[currentByte];
  }
  
  return result;
}

export default rehypePlantuml;

Why is this feature necessary?

It wouldnt be unusual for engineering teams to use plantUML given mermaid or others arent well suited for complicated sequence flows or state machines

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[joesaby]

As in the code, assumes use of local plantuml server deployed in the same host accessible through localhost:8080. For non sensitive docs, can also use the public URL https://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa700003.

Given our internal engg docs cannot be exposed to public domain, using the locally deployed server. Needs a tomcat installation in the same node container when using docker.

[delucis]

I wonder if you’d be interested in publishing an Astro integration that wraps up this code? I think that would probably be the best approach to make it easier for people to extend their project with this functionality if needed.

Given the relative complexity of needing a server for generating the images, I don’t think it’s something we’d add as a built-in feature, but a community Starlight plugin or Astro integration would make a lot of sense.

[joesaby]

@delucis : Started the leg work to it https://github.com/joesaby/astro-plantuml

[joesaby]

@delucis - this is now done. I have couple of examples done as well

[delucis]

Nice work @joesaby!

One note on your installation guide: npx astro add astro-plantuml should work as a one-command option that will install your plugin and update a user’s astro.config for them if you wanted to mention that.

Please feel free to open a PR adding your package to https://starlight.astro.build/resources/plugins/#community-tools-and-integrations

[joesaby]

updated the readme

[joesaby]

Done #3222