Add callouts and diagrams #

View this page as Markdown

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).

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.

> [!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.

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 shows how to change.

2. Write a diagram #

A fenced block marked mermaid holds a diagram in Mermaid's text syntax.

```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.

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.

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.

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 gives the exact text.

Related #

• Highlight a code block covers every other fenced block.
• Page source gives the exact rules for callouts and diagrams.
• Output describes the markup and the files the build writes for them.