Skip to content
Mementropy Labs

Setting Up PlantUML for Obsidian and Hugo

Setting Up PlantUML for Obsidian and Hugo

Section titled “Setting Up PlantUML for Obsidian and Hugo”

Create beautiful, maintainable diagrams that render perfectly in both your Obsidian vault and your Hugo static site. This guide shows you how to configure PlantUML so your diagrams work everywhere.

Table of Contents

Section titled “Table of Contents”
  1. What You’ll Build
  2. What is PlantUML?
  3. Prerequisites
  4. Part 1: Obsidian Setup
  5. Part 2: Hugo Setup
  6. Testing Your Setup
  7. Creating Your First Diagram
  8. Common Diagram Types
  9. Troubleshooting
  10. Next Steps

What You’ll Build

Section titled “What You’ll Build”

A unified PlantUML workflow that:

  • Renders diagrams in Obsidian preview mode
  • Exports cleanly to Hugo without modifications
  • Uses the same syntax in both environments
  • No local PlantUML installation required
  • Automatic server-side rendering

The workflow:

PlantUML Diagram

Why use PlantUML?

  • Text-based diagrams (version controllable)
  • No external diagram tools needed
  • Consistent rendering across platforms
  • Easy to update and maintain
  • Professional-looking results

Time to complete: 15-20 minutes

What is PlantUML?

Section titled “What is PlantUML?”

PlantUML is a tool that lets you create diagrams from plain text descriptions.

Example

Section titled “Example”

Instead of drawing a flowchart in a GUI tool, you write:

PlantUML Diagram

And PlantUML renders it as a sequence diagram.

How It Works

Section titled “How It Works”
  1. You write: PlantUML syntax in a markdown code block
  2. PlantUML server: Converts text to diagram image (SVG/PNG)
  3. You see: Beautiful diagram in your preview/website

Supported Diagram Types

Section titled “Supported Diagram Types”
  • Sequence diagrams - Show interactions between components
  • Flowcharts/Activity diagrams - Show workflows and processes
  • Class diagrams - Show object relationships
  • State diagrams - Show state transitions
  • Component diagrams - Show architecture
  • Deployment diagrams - Show infrastructure
  • Timing diagrams - Show time-based interactions
  • And many more!

Prerequisites

Section titled “Prerequisites”

Before starting, verify you have:

Required

Section titled “Required”
  • Obsidian installed and working
    • Check: You can open your vault
  • Hugo site set up and working
    • Check: hugo version shows v0.120.0 or higher
    • Your site should build successfully with hugo
Section titled “Recommended”
  • Basic markdown knowledge
  • Familiarity with your Hugo theme
  • Text editor for editing Hugo layout files

No Installation Required

Section titled “No Installation Required”

You do NOT need:

  • Java installed
  • PlantUML JAR file
  • Local PlantUML installation
  • Graphviz

We use the PlantUML.com rendering service which handles all processing server-side.

Part 1: Obsidian Setup

Section titled “Part 1: Obsidian Setup”

Configure Obsidian to render PlantUML diagrams in preview mode.

Step 1: Install PlantUML Community Plugin

Section titled “Step 1: Install PlantUML Community Plugin”
  1. Open Obsidian Settings (Cmd+, or Ctrl+,)
  2. Navigate to Community plugins
  3. If disabled, click “Turn on community plugins”
  4. Click “Browse” button
  5. Search for: “PlantUML”
  6. Find “PlantUML” by joethei
  7. Click “Install”
  8. Click “Enable”

What you should see: PlantUML now appears in your installed plugins list with a checkmark.

Step 2: Configure PlantUML Plugin

Section titled “Step 2: Configure PlantUML Plugin”

The default settings work great, but let’s verify them:

  1. Obsidian Settings → Community plugins

  2. Under PlantUML, click the gear icon

  3. Verify these settings:

    Renderer: PlantUML Server

    • This uses plantuml.com for rendering (no local installation)

    Server URL: https://www.plantuml.com/plantuml

    • Official PlantUML rendering service

    Output format: svg

    • SVG gives best quality at any zoom level

  4. Save and close settings

Security note: Diagrams are sent to plantuml.com for rendering. Don’t include sensitive information in diagrams if this is a concern. For private diagrams, you can self-host a PlantUML server (advanced, not covered here).

Step 3: Test in Obsidian

Section titled “Step 3: Test in Obsidian”

Create a test note to verify the plugin works:

  1. Create a new note in your vault: plantuml-test.md

  2. Paste this content:

    # PlantUML Test
    

    This is a simple sequence diagram:
    

    ```plantuml
    @startuml
    Alice -> Bob: Hello
    Bob -> Alice: Hi!
    @enduml
    ```

  3. Switch to Preview mode (Cmd+E or Ctrl+E)

Expected result: You should see a rendered sequence diagram showing Alice and Bob exchanging messages.

If you see a rendered diagram: Success! Obsidian is working. Move to Part 2.

If you see raw code: Check troubleshooting section below.

Part 2: Hugo Setup

Section titled “Part 2: Hugo Setup”

Configure Hugo to render PlantUML code blocks automatically.

Step 1: Create Render Hook Directory

Section titled “Step 1: Create Render Hook Directory”

Hugo uses “render hooks” to customize how markdown elements are rendered.

Terminal window
# Create directory for markdown render hooks
mkdir -p ~/Developer/mementropy/layouts/_default/_markup

What this does: Creates the directory where Hugo looks for custom markdown renderers.

Step 2: Create PlantUML Render Hook

Section titled “Step 2: Create PlantUML Render Hook”

Create a file that tells Hugo how to render plantuml code blocks:

Terminal window
# Create the render hook file
touch ~/Developer/mementropy/layouts/_default/_markup/render-codeblock-plantuml.html

Now edit this file with the following content:

File: layouts/_default/_markup/render-codeblock-plantuml.html

{{- $uml := .Inner | replaceRE "^\n" "" | replaceRE "\n$" "" -}}
{{- $encoded := $uml | base64Encode -}}
{{- $encodedURL := $encoded | replaceRE "\\+" "-" | replaceRE "/" "_" | replaceRE "=" "" -}}
<div class="plantuml">
  <img src="https://www.plantuml.com/plantuml/svg/{{ $encodedURL }}" alt="PlantUML Diagram" loading="lazy" />
</div>

What this does:

  1. Takes the PlantUML code from the code block (.Inner)
  2. Base64 encodes it
  3. Makes it URL-safe (replace +, /, remove =)
  4. Generates an image URL pointing to plantuml.com
  5. Renders as an <img> tag with lazy loading

Step 3: Configure Hugo Markup Settings

Section titled “Step 3: Configure Hugo Markup Settings”

Hugo needs permission to render raw HTML (for the render hook):

Edit: hugo.toml (or config.toml)

Add or verify this section:

# Markup configuration
[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true  # Allow raw HTML for shortcodes and render hooks

What this does: Allows Hugo’s Goldmark renderer to output raw HTML, which is necessary for the PlantUML image tags.

Save the file.

Step 4: Verify Hugo Configuration

Section titled “Step 4: Verify Hugo Configuration”

Check that your config is valid:

Terminal window
cd ~/Developer/mementropy
hugo config

Look for: markup.goldmark.renderer.unsafe = true in the output.

If you see it: Configuration is correct! Move to testing.

If not: Double-check you added the config to the right section.

Testing Your Setup

Section titled “Testing Your Setup”

Test that PlantUML works in both Obsidian and Hugo.

Test 1: Obsidian Rendering

Section titled “Test 1: Obsidian Rendering”

Goal: Verify diagrams render in Obsidian preview.

Steps

Section titled “Steps”

  1. Open Obsidian

  2. Create or edit a markdown file with PlantUML:

    ```plantuml
    @startuml
    start
    :Write documentation;
    :Add diagrams;
    :Publish!;
    stop
    @enduml
    ```

  3. Switch to Preview mode (Cmd+E)

Expected Result

Section titled “Expected Result”

You should see a flowchart with three steps and start/stop nodes.

Pass: Diagram renders Fail: See troubleshooting below

Test 2: Hugo Local Rendering

Section titled “Test 2: Hugo Local Rendering”

Goal: Verify diagrams render when Hugo builds your site.

Steps

Section titled “Steps”

  1. Create a test post in your Hugo site:

    Terminal window
    # Create a test post
    echo '---
    title: "PlantUML Test"
    date: 2025-01-11
    draft: false
    ---
    

    # Testing PlantUML
    

    ```plantuml
    @startuml
    Alice -> Bob: Can you see this?
    Bob -> Alice: Yes, it works!
    @enduml
    ```' > ~/Developer/mementropy/content/blog/plantuml-test.md

  2. Start Hugo server:

    Terminal window
    cd ~/Developer/mementropy
    hugo server

  3. Open browser to http://localhost:1313

  4. Navigate to your test post (usually /blog/plantuml-test/)

Expected Result

Section titled “Expected Result”

You should see:

  • The heading “Testing PlantUML”
  • A rendered sequence diagram showing Alice and Bob

Pass: Diagram renders correctly Fail: See troubleshooting below

Test 3: Obsidian to Hugo Workflow

Section titled “Test 3: Obsidian to Hugo Workflow”

Goal: Verify diagrams created in Obsidian export to Hugo correctly.

Steps

Section titled “Steps”

  1. In Obsidian, create a note with a diagram:

    ---
    title: "My Workflow"
    date: 2025-01-11
    draft: false
    ---
    

    # My Publishing Workflow
    

    ```plantuml
    @startuml
    skinparam monochrome true
    start
    :Edit in Obsidian;
    :Sync to Hugo;
    :Publish;
    stop
    @enduml
    ```

  2. Verify it renders in Obsidian (Preview mode)

  3. Sync/export to Hugo (using your normal workflow):

    • If using obsidian-export: Run your sync script
    • If manual: Copy the file to Hugo content directory

  4. Check Hugo preview:

    Terminal window
    hugo server

  5. Visit the page in your browser

Expected Result

Section titled “Expected Result”

The diagram should look identical (or very similar) in both Obsidian and Hugo.

Pass: Same diagram in both places Fail: Check file sync and paths

Creating Your First Diagram

Section titled “Creating Your First Diagram”

Now that everything is configured, let’s create a useful diagram.

Example: Simple Flowchart

Section titled “Example: Simple Flowchart”

Create a note with this content:

---
title: "Decision Making Process"
draft: false
---


# Decision Making Process


```plantuml
@startuml
skinparam monochrome true
skinparam shadowing false
skinparam defaultFontName Arial


start


:Receive new idea;


if (Is it feasible?) then (yes)
  :Research thoroughly;
  if (Still good idea?) then (yes)
    :Create plan;
    :Execute;
    stop
  else (no)
    :Document learnings;
    stop
  endif
else (no)
  :Archive for later;
  stop
endif


@enduml
```

What this creates: A decision tree showing how to evaluate new ideas.

Styling explained:

  • skinparam monochrome true - Black and white (cleaner)
  • skinparam shadowing false - No shadows (crisper)
  • skinparam defaultFontName Arial - Readable font

Common Diagram Types

Section titled “Common Diagram Types”

1. Sequence Diagram (Communication)

Section titled “1. Sequence Diagram (Communication)”

Use for: Showing interactions between systems or components

PlantUML Diagram

2. Activity Diagram (Workflow)

Section titled “2. Activity Diagram (Workflow)”

Use for: Showing step-by-step processes

PlantUML Diagram

3. Component Diagram (Architecture)

Section titled “3. Component Diagram (Architecture)”

Use for: Showing system architecture

PlantUML Diagram

4. State Diagram (State Machine)

Section titled “4. State Diagram (State Machine)”

Use for: Showing state transitions

PlantUML Diagram

Troubleshooting

Section titled “Troubleshooting”

Problem: Diagrams Don’t Render in Obsidian

Section titled “Problem: Diagrams Don’t Render in Obsidian”

Symptoms:

  • See raw PlantUML code instead of diagram
  • Preview mode shows code block

Solutions:

  1. Verify plugin is enabled:

    • Settings → Community plugins → PlantUML (should have checkmark)

  2. Check code block syntax:

    • Must be ```plantuml (lowercase)
    • Must have @startuml and @enduml tags

  3. Test with simple diagram:

    PlantUML Diagram

  4. Check plugin settings:

  5. Reload Obsidian:

    • Cmd/Ctrl + R to reload

Problem: Diagrams Don’t Render in Hugo

Section titled “Problem: Diagrams Don’t Render in Hugo”

Symptoms:

  • See raw PlantUML code on website
  • Or see blank/broken image

Solutions:

  1. Verify render hook exists:

    Terminal window
    ls ~/Developer/mementropy/layouts/_default/_markup/render-codeblock-plantuml.html

    Should exist and contain the template code.

  2. Check hugo.toml configuration:

    Terminal window
    grep -A 3 "\[markup\]" ~/Developer/mementropy/hugo.toml

    Should show unsafe = true

  3. Rebuild Hugo:

    Terminal window
    cd ~/Developer/mementropy
    hugo server --disableFastRender

    Force full rebuild

  4. Check browser console (F12):

    • Look for image loading errors
    • PlantUML.com might be blocked by firewall

  5. Test the image URL directly:

    • Right-click broken image → Copy image address
    • Paste in new browser tab
    • Should show diagram

Problem: Diagrams Look Different in Obsidian vs Hugo

Section titled “Problem: Diagrams Look Different in Obsidian vs Hugo”

Symptoms:

  • Diagram renders but looks different in each environment
  • Colors, fonts, or layout differ

Solutions:

  1. Use explicit styling (recommended):

    PlantUML Diagram

  2. Both environments use same server:

    • Obsidian plugin: Uses plantuml.com
    • Hugo render hook: Uses plantuml.com
    • Should be identical if using same skin params

  3. Check PlantUML plugin version:

    • Update to latest version
    • Settings → Community plugins → PlantUML → Update

Problem: Syntax Errors in Diagrams

Section titled “Problem: Syntax Errors in Diagrams”

Symptoms:

  • Error message in rendered output
  • “Syntax error” or similar

Solutions:

  1. Use PlantUML syntax checker:

  2. Common syntax mistakes:

    • Missing @startuml or @enduml
    • Unclosed quotes: "forgot to close
    • Wrong arrow: Use -> not right arrow symbol
    • Missing semicolons (some diagram types)

  3. Reference documentation:

Best Practices

Section titled “Best Practices”

1. Always Use Skin Params

Section titled “1. Always Use Skin Params”

Start every diagram with consistent styling:

PlantUML Diagram

Why: Ensures diagrams look the same everywhere.

2. Keep Diagrams Simple

Section titled “2. Keep Diagrams Simple”
  • One diagram = one concept
  • Break complex diagrams into multiple simpler ones
  • Use notes to explain details

3. Version Control Your Diagrams

Section titled “3. Version Control Your Diagrams”

Since PlantUML is text:

  • Track changes in git
  • See diagram evolution over time
  • Easy to review in PRs

4. Use Comments

Section titled “4. Use Comments”
PlantUML Diagram

5. Test in Both Environments

Section titled “5. Test in Both Environments”

Before publishing:

  1. Renders in Obsidian preview
  2. Renders in Hugo local server
  3. Looks good at different zoom levels (SVG benefit)

Quick Reference

Section titled “Quick Reference”

Basic Syntax

Section titled “Basic Syntax”
ElementSyntax
Start diagram@startuml
End diagram@enduml
Comment' comment text
ArrowA -> B
Notenote right: text
If conditionif (condition) then (yes)
Start/stopstart / stop

Useful Resources

Section titled “Useful Resources”
ResourceURL
Official PlantUML docshttps://plantuml.com/
Live editorhttps://www.plantuml.com/plantuml/uml/
Real-world exampleshttps://real-world-plantuml.com/
Obsidian pluginhttps://github.com/joethei/obsidian-plantuml

File Locations

Section titled “File Locations”
PurposePath
Hugo render hooklayouts/_default/_markup/render-codeblock-plantuml.html
Hugo confighugo.toml (or config.toml)
Obsidian plugins.obsidian/plugins/obsidian-plantuml/

Next Steps

Section titled “Next Steps”

Now that you have PlantUML working, consider:

  1. Add diagrams to existing posts - Visualize complex concepts
  2. Create architecture diagrams - Document your system design
  3. Diagram workflows - Show how processes work
  4. Explore advanced PlantUML - Gantt charts, mind maps, JSON/YAML visualization

Related guides:

Summary

Section titled “Summary”

What you accomplished:

  • Installed Obsidian PlantUML plugin
  • Configured Hugo render hook for PlantUML
  • Created unified syntax that works in both environments
  • Tested with real diagrams
  • Ready to create documentation with diagrams

Key benefits:

  • Text-based diagrams (version controllable)
  • Same syntax everywhere
  • No local installation required
  • Professional results
  • Easy to maintain

Time investment: 15-20 minutes Value: Better documentation forever!

Last updated: 2025-01-11