Markdown fences

puml natively understands fenced code blocks in Markdown. This means you can keep prose and diagrams in the same source file and lint or render them in one pass.

Supported fence languages

Inline preview

On this site, supported diagram fences get a small preview control that renders locally in your browser with the same WASM renderer as the studio editor.

@startuml
actor Writer
participant Docs
Writer -> Docs: open Markdown page
Docs --> Writer: inline SVG preview
@enduml

Example

# Sign-in flow

```puml
@startuml
User -> AuthService: POST /login
AuthService --> User: 200 OK + token
@enduml
```

Render the document:

puml --from-markdown notes.md          # renders each fenced block
puml --from-markdown --check notes.md  # lint only, exit code on validation failure

--from-markdown is automatically enabled for .md, .markdown, and .mdown files.

Output naming

When rendering markdown with --multi, output paths are deterministic:

• File input: <markdown-stem>_snippet_<n>.svg (or _snippet_<n>-<page>.svg for multi-page fences).
• Stdin input: snippet-<n>.svg (or snippet-<n>-<page>.svg for multi-page fences).

Deep dive

See the Markdown fence renderer spec for the full extraction protocol, edge cases, and CI integration patterns.