plantuml-simple-validator

Validate PlantUML diagram syntax in Markdown files and .plantuml files — no local Java needed.

Uses a PlantUML server (e.g. the official plantuml/plantuml-server Docker image) to parse and validate diagrams via HTTP.

Prerequisites

A running PlantUML server. Start one with Docker:

docker run -d -p 9274:8080 plantuml/plantuml-server:jetty

Or point PLANTUML_SERVER to any existing instance.

Install

npm install plantuml-simple-validator

Usage

npx plantuml-simple-validate [-L] <path>

• <path> — a .md file, a .plantuml file, or a directory (scanned recursively)
• -L — follow symbolic links when scanning a directory

Supported files

| Extension | Behaviour | |------------|-----------| | .md | Extracts ```plantuml … ``` fenced blocks; line ranges in the output exclude the fences | | .plantuml | Validates the entire file content as a single diagram |

Server configuration

| Variable | Default | Description | |--------------------|------------------------------|------------------------| | PLANTUML_SERVER | http://localhost:9274 | PlantUML server URL |

Examples

Validate a single file:

npx plantuml-simple-validate diagrams.md

Scan a directory recursively (symlinks are skipped by default):

npx plantuml-simple-validate docs/

Scan a directory and follow symlinks:

npx plantuml-simple-validate -L docs/

Use a custom server:

PLANTUML_SERVER=https://plantuml.example.com npx plantuml-simple-validate .

Output

Given diagrams.md:

## Sequence diagram

```plantuml
Alice -> Bob: Hello
Bob --> Alice: Hi
```

## Broken diagram

```plantuml
Alice - Bob: Invalid
```

npx plantuml-simple-validate diagrams.md

Output:

diagrams.md:6:1-7.999: Error line 8: Syntax Error?
   ...

1 error(s) found.

Exit code is 1 when any block fails validation, 0 otherwise.

How it works

1. Scans a file or directory for .md and .plantuml files
2. For .md files — extracts ```plantuml fenced code blocks and records their line range (excluding fences)
3. For .plantuml files — treats the entire file content as a single diagram
4. Normalizes the diagram (strips and re-adds @startuml/@enduml tags)
5. POSTs each diagram to ${PLANTUML_SERVER}/svg/
6. If the server returns HTTP 200 the diagram is valid; otherwise the error response is reported
7. Error line numbers are mapped back to the original source lines

License

MIT