--- title: Add callouts and diagrams description: Set off a note or a warning with a callout, and draw a diagram from a mermaid block once you run npm install mermaid in the folder where you run tzdocs. slug: /guides/callouts-and-diagrams order: 3 visibility: public redirects_from: [] --- # Add callouts and diagrams Prompt: > Put a warning above the step that deletes the output folder, and draw the build flow as a diagram. Also works: "The `[!NOTE]` on the setup page shows as plain text." "Our diagrams render as code." ## What your tool does - Turns a note or a warning into a block quote that opens with a marker, such as `[!WARNING]`, on a line of its own. - Writes a diagram as a fenced block marked `mermaid`, in Mermaid's text syntax. - Runs `npm install mermaid` in the folder where it runs tzdocs, so the build draws the diagrams. - Runs `tzdocs check --source docs`, corrects what it reports, and builds. - Asks before it installs Mermaid where the project keeps its dependencies under review. ## What you need - Which notes are tips, which are warnings, and so on. - Whether the site should draw diagrams, or show them as code. ## Before your AI starts This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself. - A corpus that passes the check and builds ([Getting started](/getting-started/)). ## Steps ### 1. Add a callout Start a block quote with a marker on a line of its own. Callouts use GitHub's syntax, so a page reads the same in its repository. ```markdown > [!WARNING] > The build replaces the whole output folder. ``` The five markers are `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`, in any letter case. The build renders the quote as a callout titled Note, Tip, Important, Warning, or Caution, with a colored bar at its left. > [!TIP] > A callout holds anything a block quote holds: paragraphs, lists, and code blocks. The marker must be the whole first line, so `> [!NOTE] Read this` stays an ordinary block quote. Each type's color is a custom property, such as `--docs-callout-note`, which [Style the site](/guides/style-the-site/) shows how to change. ### 2. Write a diagram A fenced block marked `mermaid` holds a diagram in Mermaid's text syntax. ````markdown ```mermaid graph TD Source[A folder of Markdown] --> Build[tzdocs build] Build --> Site[A static site] ``` ```` A diagram block takes no title and no line set, because a drawn diagram has no caption and no lines to emphasize. The block below is a diagram where this manual was built with Mermaid, and code otherwise. ```mermaid graph LR Write[Write a page] --> Check[tzdocs check] --> Build[tzdocs build] ``` ### 3. Install Mermaid The build draws diagrams only where Mermaid is installed. Run this in the folder where you run tzdocs. ```text npm install mermaid ``` A Mermaid installed in a folder above that one serves as well, as Node.js finds any package. The build copies Mermaid's browser file into the site as `mermaid.min.js`, and each page with a diagram loads it. The site serves its own copy, so diagrams need no other site. The reader's browser draws each diagram, in dark colors where the reader's system prefers a dark scheme. Without Mermaid, each diagram block shows as code, and the build prints one notice that names `npm install mermaid`. The build still succeeds. ### 4. Or show diagrams as code To keep every `mermaid` block as code even where Mermaid is installed, pass `--diagrams-as-code` to the build. The pages then load no Mermaid file, and the build prints no notice. ```text tzdocs build --source docs --out site --diagrams-as-code ``` ### 5. Check and build Run `tzdocs check --source docs`. It reports a bracketed word that is not one of the five markers, such as `[!WARN]`, which stays a block quote. It also reports a title or a line set on a `mermaid` fence. Correct each line it reports, then build. ## Expected result Each callout shows its title in its type's color, above the rest of the quote. With Mermaid installed, each diagram page draws its diagrams once it loads, and the tree holds `mermaid.min.js` at its root. Without Mermaid, or with `--diagrams-as-code`, each diagram shows as a code block. ## Refusals None of these stops the build. [Refusals and findings](/reference/refusals/#callouts) gives the exact text. | Message | Exit code | Cause | Remedy | | --- | --- | --- | --- | | `unknown callout type in — [!] stays a block quote; the types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION` | 1 from the check | A block quote opens with a bracketed word that is not one of the five markers. | Use one of the five markers. | | `a mermaid diagram takes no title or line set` | 1 from the check | A `mermaid` fence carries `title="..."` or a line set in braces. | Remove them from the fence line. | | `notice: pages hold mermaid diagrams, shown as code — run "npm install mermaid" in this folder to draw them.` | 0 | Mermaid is not installed where the build runs. | Run `npm install mermaid` there, or pass `--diagrams-as-code`. | ## Related - [Highlight a code block](/guides/code-blocks/) covers every other fenced block. - [Page source](/reference/page-source/#callouts) gives the exact rules for callouts and diagrams. - [Output](/reference/output/#diagrams) describes the markup and the files the build writes for them.