Diagrams & Rich Blocks

Documents can carry much more than text. Every block on this page is authored in plain Markdown — portable, diffable, and versioned like everything else — and renders in the app, in the editor’s Preview, and on the public site. In the editor’s Markdown tab, the row of block buttons in the toolbar drops a ready-made template at your cursor.

Callouts

:::tip[Pro tip]
Your advice here — full **markdown** works inside.
:::

Five kinds: note, info, tip, warning, danger. The [Title] is optional — each kind has a sensible default.

Tabs

::::tabs
:::tab[Windows]
Windows-specific steps.
:::
:::tab[macOS]
macOS-specific steps.
:::
::::

Perfect for per-platform instructions. Note the four colons on the outer block and three on each tab.

Accordions

:::details[Rollout history]
Hidden until the reader expands it.
:::

Mermaid diagrams

```mermaid
flowchart LR
  A[Start] --> B{Working?}
  B -- Yes --> C[Ship it]
  B -- No --> D[Fix it]
```

Flowcharts, sequence diagrams, Gantt charts, state machines, pie charts — everything Mermaid supports. Diagrams render right in the reader’s browser (nothing leaves your workspace) and follow the app’s light/dark theme.

PlantUML diagrams

```plantuml
Alice -> Bob: Request
Bob --> Alice: Response
```

The @startuml/@enduml wrapper is optional. Rendering uses a PlantUML server — plantuml.com by default, which means diagram text is sent there. For private networks, run the official plantuml/plantuml-server Docker image and set COMPASSDOCS_PLANTUML_SERVER to its URL (or set it to off to disable PlantUML entirely). Rendered diagrams are cached.

Decision trees

```decision
start: Is the server responding?
- Yes -> logs
- No -> Escalate to the network team.
logs: Any errors in the application log?
- Yes -> Follow the runbook for that error code.
- No -> Capture a HAR file and open a ticket.
```

Each id: question line defines a step; each - Answer -> target line is a button. If the target matches another step’s id, choosing it moves there; otherwise the text is shown as the final recommendation. Readers walk the tree one question at a time, with a breadcrumb of their answers and back/start-over controls — ideal for triage guides and support flows.

Interactive checklists

- [ ] Provision the account
- [ ] Grant repository access
- [ ] Book the onboarding session

Standard task lists are now clickable for every reader. Progress is saved per document on the reader’s own device — ticking a box never changes the document, and two readers each get their own progress. (Progress is per-browser: it doesn’t follow users between devices.)

Videos

::video[Optional caption]{src="https://www.youtube.com/watch?v=VIDEO_ID"}

Supports YouTube (played through the privacy-enhanced no-cookie player), Vimeo, Loom, SharePoint / Microsoft Stream, Google Drive, Wistia, Dailymotion, direct video files (.mp4, .webm, …), and video files uploaded as attachments.

You rarely need to write the directive by hand: the rich editor’s Video toolbar button opens an insert dialog (paste a URL with live provider detection, or upload a video file right there), and pasting a supported video link on its own line converts to a video block automatically.

• Uploaded videos stream with full seeking support and get their own size limit (Settings → Attachments, default 200 MB — separate from the document-attachment cap). An optional poster="…" attribute sets the pre-play thumbnail.
• Every video has a theater mode button (hover the player) that expands it to fill the screen; Esc closes.

Website embeds

::embed{src="https://status.example.com" height="500"}

Shows a live page inside the document — dashboards, status pages, forms. The frame is sandboxed and lazy-loaded, with an “open in new tab” link. height is optional (defaults to 420, capped at 1200).

Tables with filtering

Nothing to author — every Markdown table with four or more rows automatically gets a filter box and click-to-sort headers (numeric columns sort numerically). Smaller tables stay plain.

Editing in rich-text mode

Blocks are fully editable in the Rich text editor too — no directive syntax needed:

• Callouts are live colored boxes: pick the kind from a dropdown, type the title inline, and write formatted content inside.
• Accordions and tab panels have inline title fields; tab groups are edited as stacked panels and rendered as real tabs for readers.
• Mermaid, PlantUML, and decision blocks show a live preview under the code while you type.
• Checklists are native click-to-tick task lists.
• Videos and website embeds appear as preview cards with change-URL and remove controls.
• One-click block buttons in the toolbar insert any of them.

Both editors write the exact same Markdown, so you can switch modes freely.

Notes

• Unknown or misspelled block types render as their literal text — nothing breaks.
• Diagrams and embeds print reasonably: rendered SVGs print as images, and interactive blocks (tabs, decision trees) print their visible state.