Source-level directives
Embed rendering configuration directly inside Mermaid or PlantUML source using native comment syntax. The bd CLI and Obsidian plugin honor these directives and strip them before sending source to the API. Direct API callers see them as plain comments — the diagram still renders, just without the override.
What & why
Directives let diagram authors embed rendering preferences — theme, background transparency, and future options — directly inside the source file, right where the diagram lives. A colleague who opens the .mmd file gets the same visual the author intended without passing extra flags. The key design constraint is graceful degradation: directive lines use each format's native comment syntax (%% for Mermaid, ' for PlantUML), so a tool that does not understand directives — including the Beauty Diagram API itself — simply ignores them as comments. The diagram renders normally, just without the override applied.
Syntax
Directives appear at the very top of the source, one per line. Each line follows the pattern <comment-marker> bd:KEY=VALUE. Blank lines between directive lines are tolerated. The directive block ends at the first non-directive, non-blank line.
Uses %%— Mermaid's native single-line comment marker. The parser never sees these lines.
%% bd:KEY=VALUEUses '— PlantUML's native single-line comment marker. Likewise invisible to the renderer.
' bd:KEY=VALUEbd: is required (exactly one space). Multiple directives stack — later ones for the same key override earlier ones within the same file (though in practice you should only set each key once). Any line that does not match the pattern ends the directive block, even if further directive-looking lines appear later in the source.Supported keys
Two keys are recognized today. Unknown keys are parsed but treated as no-ops — they are silently ignored rather than causing an error.
| Key | Values | Behavior |
|---|---|---|
theme | classic · modern · slate · atlas · obsidian · brutalist · atelier · blueprint · memphis | Sets the theme used to render the diagram. Tier gating applies: the consuming tool must hold a plan that can access the requested theme. If the plan does not cover the theme, the consumer falls back to its own default rather than erroring. Free-tier themes: classic, modern, slate. Pro: atlas, obsidian, brutalist, atelier. Premium: blueprint, memphis. |
bg | transparent(other values: no-op) | Renders the canvas with a transparent background, overriding the default theme background color. Only transparent is a recognized value; any other value is silently ignored (reserved for possible future color overrides). |
Override priority
When multiple sources set the same rendering option, the priority from highest to lowest is:
- Explicit CLI flag or API query parameter — e.g.
bd beautify flow.mmd --theme atlasor?theme=atlason the GET embed endpoint. Always wins. - Source-level directive — the
%% bd:theme=...or' bd:theme=...line at the top of the file. Beats the consumer default when no explicit flag is provided. - Consumer default — the theme configured in the tool (e.g.
bd auth loginsaved config, the Obsidian plugin setting, or the API's own default ofmodern). Used only when neither of the above is set.
| CLI flag / query param | Source directive | Result |
|---|---|---|
--theme atlas | %% bd:theme=classic | atlas (flag wins) |
(none) | %% bd:theme=classic | classic (directive wins) |
(none) | (none) | consumer default (e.g. modern) |
Per-consumer behavior
How each tool in the ecosystem interacts with directives:
| Consumer | Parses directives? | Strips before rendering? | Notes |
|---|---|---|---|
| bd CLI | Yes | Yes | Applies theme/bg overrides before sending source to the API. Directive lines are removed from the payload. |
| Obsidian plugin | Yes | Yes | Same behavior as the CLI — reads directives from fenced blocks, applies overrides, strips lines before render. |
| Direct API (curl / HTTP) | No | No | The API server does not parse directives. Directive lines pass through unchanged. Mermaid's %% and PlantUML's ' are native comment markers, so the renderer ignores them and the diagram renders cleanly — just without the override. |
| GET /v1/beautify.svg | No | No | Same as direct API. Source is decoded and forwarded as-is. Use the bd CLI or Obsidian plugin if you need directives honored on inline embeds. |
Examples
Both formats support multiple directives at the top of the source. A blank line between directives is fine; the block ends at the first non-directive, non-blank line.
%% bd:theme=classic
%% bd:bg=transparent
flowchart LR
A[Start] --> B{Decision}
B -->|yes| C[Done]
B -->|no| D[Retry]The bd CLI will render with the classic theme and a transparent canvas. The two directive lines are stripped before the source reaches the API.
' bd:theme=blueprint
@startuml
Alice -> Bob : Hello
Bob --> Alice : Hi there
@endumlThe directive precedes @startuml. Consumers that parse directives will apply blueprint theme. Direct API calls see the ' line as a native PlantUML comment — it is invisible to the parser.
# Directive says atlas; no flag → atlas is used
bd beautify flow.mmd --out flow.svg
# Explicit --theme flag wins; directive is ignored
bd beautify flow.mmd --theme modern --out flow.svgForward compatibility
Unknown directive keys — anything that is not theme or bg today — are parsed but silently ignored. This means future keys (title, scale, and others under consideration) can be added to the specification without breaking diagrams that are read by older consumers. Authors can safely write future-targeted directives in their sources now; existing tools will skip the unknown keys and render normally, and upgraded tools will start honoring them without any source changes needed.
%% bd:bg=red — only transparent is a valid bg value; red is a no-op).Ready to use directives?
Install the bd CLI or the Obsidian plugin to start embedding configuration in your diagram sources today. The API reference covers all render parameters available via query param or request body.