CouchUml — VS Code Extension

Browse, edit, and live-preview PlantUML diagrams directly inside VS Code.
Supports a local Docker server, plantuml.com, or any self-hosted instance.

Table of contents

1. Quick start
2. Initial setup — Docker (recommended)
3. Initial setup — plantuml.com (no install)
4. Features
5. File naming conventions
6. Settings reference
7. Keyboard shortcuts
8. Git versioning workflow
9. Contributing & publishing
10. Troubleshooting

1. Quick start

1. Install this extension from the VS Code Marketplace
2. Open a folder containing .puml files  (or create one)
3. Open any .puml file
4. Click "▶ Preview" in the CodeLens bar above @startuml

The preview panel opens beside your editor and re-renders every time you save.

2. Initial setup — Docker (recommended)

Running PlantUML locally gives you offline access and no rate limits.

Step 1 — Install Docker

Step 2 — Start the PlantUML container

docker run -d \
  --name plantuml \
  --restart unless-stopped \
  -p 8080:8080 \
  plantuml/plantuml-server:jetty

Verify it's running:

curl http://localhost:8080/png/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000
# → Returns a PNG image (binary output is OK)

Or open http://localhost:8080 in your browser — you should see the PlantUML web UI.

Step 3 — Configure the extension

Open VS Code Settings (Ctrl+,) and search plantuml:

// settings.json
{
  "plantuml.docker.enabled": true,
  "plantuml.docker.port": 8080
}

Or set the server URL manually:

{
  "plantuml.server": "http://localhost:8080/plantuml"
}

Step 4 — Verify connection

Run the command palette (Ctrl+Shift+P) → PlantUML: Check Server Connection.
You should see ✅ in the status bar.

Docker compose (optional — for team projects)

# docker-compose.yml  (commit this to your repo)
version: '3'
services:
  plantuml:
    image: plantuml/plantuml-server:jetty
    ports:
      - "8080:8080"
    restart: unless-stopped

docker compose up -d

3. Initial setup — plantuml.com (no install)

No setup required. The extension uses https://www.plantuml.com/plantuml by default.

⚠️ Limitations: rate-limited, requires internet, diagram source is sent to a third-party server.
For private or sensitive diagrams, use Docker instead.

4. Features

File explorer

Click the CouchUml icon in the Activity Bar (left sidebar) to open the CouchUml panel. Every .puml, .plantuml, and .pu file in your workspace appears as an icon tile — one per file, colour-coded by diagram type. Click a tile to open the file; double-click to open it and immediately launch the preview panel. A small orange dot on a tile means the filename doesn't follow the naming convention (see section 5).

Live preview panel

• Opens beside your editor (Ctrl+Shift+P → PlantUML: Preview)
• Re-renders on save (configurable) or after a typing pause
• Displays rendered image dimensions
• Zoom in/out with + / − buttons or Ctrl+Scroll
• Error overlay with line number when syntax fails
• Server connectivity error with Retry button

CodeLens actions

A ▶ Preview | ⬇ Export PNG | ⬇ Export SVG bar appears above every @startuml.

Export

• PNG / SVG via command palette or CodeLens
• Saved alongside the source file by default (configure plantuml.outputDir)
• Batch export: PlantUML: Render All Diagrams exports every file in the workspace

New diagram wizard

Ctrl+Shift+P → PlantUML: New Diagram
Pick a type → enter a name → file is created with the correct naming convention and a starter template.

5. File naming conventions

The extension enforces (and warns on) a type-suffix convention for clarity and auto-detection:

auth_sequence.puml        ✅ Sequence diagram
domain_class.puml         ✅ Class diagram
order_activity.puml       ✅ Activity diagram
checkout.puml             ⚠️  No suffix — type must be inferred from content

Disable warnings with "plantuml.diagramNamingConvention": false.

Full suffix list:

6. Settings reference

7. Keyboard shortcuts

8. Git versioning workflow

This project uses Semantic Versioning:

MAJOR.MINOR.PATCH
  │     │     └── bug fixes, no API change
  │     └──────── new features, backwards compatible
  └────────────── breaking changes

Day-to-day development

git checkout -b feature/my-feature   # feature branches off main
# … make changes …
git commit -m "feat: add zoom controls to preview panel"
git push origin feature/my-feature
# Open a Pull Request → squash-merge into main

Commit message convention (Conventional Commits)

feat:     new feature
fix:      bug fix
docs:     documentation only
refactor: code change, no feature/fix
test:     adding or updating tests
chore:    tooling, CI, deps

Releasing a new version

# 1. Bump version in package.json
npm version patch    # 0.1.0 → 0.1.1
npm version minor    # 0.1.0 → 0.2.0
npm version major    # 0.1.0 → 1.0.0

# 2. Update CHANGELOG.md — move [Unreleased] items to new version section

# 3. Commit and tag
git add package.json CHANGELOG.md
git commit -m "chore: release v0.2.0"
git tag v0.2.0
git push origin main --tags

# 4. GitHub Actions picks up the tag, builds, creates a GitHub Release,
#    and publishes to the VS Code Marketplace automatically.

Branch strategy

main         ← protected, always releasable
develop      ← integration branch (optional for teams)
feature/*    ← individual features
fix/*        ← bug fixes
chore/*      ← tooling, CI updates

9. Contributing & publishing

First-time marketplace setup

1. Create a publisher at https://marketplace.visualstudio.com/manage
2. Generate a Personal Access Token (PAT) at https://dev.azure.com → User Settings → Personal Access Tokens
   Scope: Marketplace → Manage
3. Add VSCE_PAT as a GitHub Actions secret (repo Settings → Secrets → Actions)
4. Set "publisher": "your-publisher-id" in package.json

Local development

npm install
npm run compile

# Press F5 in VS Code to launch Extension Development Host

Running tests

npm test

Packaging locally

npx vsce package
# Produces couchuml-0.1.0.vsix
# Install with: code --install-extension couchuml-0.1.0.vsix

10. Troubleshooting

"Server unreachable" on startup

1. Run PlantUML: Check Server Connection from the command palette
2. If using Docker: verify the container is running — docker ps | grep plantuml
3. If using plantuml.com: check your internet connection
4. Open Settings (Ctrl+,) → search plantuml.server → verify the URL

Preview shows a blank panel

• Make sure the active editor contains a .puml file
• Check the server URL in settings
• Look for syntax errors in the red error panel at the bottom of the preview

Docker container stops on reboot

Add --restart unless-stopped to your docker run command (already included above).
Or use the docker-compose file, which enables restart by default.

Extension not activating

The extension activates when:

• A .puml, .plantuml, or .pu file is detected in the workspace
• Or a file with plantuml language mode is opened

If neither condition is met, run the command palette → Developer: Show Running Extensions.

Export fails silently

Check plantuml.outputDir — if the directory doesn't exist, export fails.
Either create the directory or leave the setting empty (exports alongside the source file).