Add Images and Diagrams

Include screenshots, figures, and Mermaid diagrams in your user guide and recipes.

Documentation often benefits from visual aids: screenshots of output, architecture diagrams, or flowcharts. Great Docs (via Quarto) supports standard Markdown images, Quarto figure syntax with captions and layout control, and Mermaid diagrams rendered directly from code blocks.

Place Images in an Asset Directory

Keep images organized by placing them in the assets/ subdirectory within your user guide or recipe directory. Great Docs copies the entire directory tree during the build, so relative paths are preserved:

user_guide/
β”œβ”€β”€ 01-installation.qmd
β”œβ”€β”€ 02-quickstart.qmd
└── assets/
    β”œβ”€β”€ screenshot-light.png
    └── screenshot-dark.png

Reference images using a relative path from the .qmd file:

![Screenshot of the rendered site](assets/screenshot-light.png)

Quarto Figures with Captions

For more control, use Quarto’s figure syntax. This adds a caption, alt text, and allows you to control the image width:

![The landing page with hero section and metadata sidebar.](assets/landing-page.png){#fig-landing width="80%" fig-alt="Screenshot showing the landing page layout"}

The #fig-landing identifier allows you to cross-reference the figure from elsewhere in the document with @fig-landing. The fig-alt attribute provides alt text for accessibility.

Side-by-Side Images

Quarto’s layout syntax lets you place images next to each other. This is useful for comparing light and dark mode, or showing before-and-after screenshots:

::: {layout-ncol=2}
![Light mode](assets/screenshot-light.png)

![Dark mode](assets/screenshot-dark.png)
:::

The layout-ncol=2 attribute creates a two-column grid. You can use layout-ncol=3 for three columns, and so on.

Mermaid Diagrams

Quarto renders Mermaid diagrams directly from fenced code blocks. This is useful for architecture diagrams, flowcharts, and sequence diagrams without needing external image files:

```{mermaid}
graph LR
    A[great-docs init] --> B[great-docs.yml]
    B --> C[great-docs build]
    C --> D[great-docs/_site/]
    D --> E[great-docs preview]
```

Mermaid diagrams are rendered as SVG during the Quarto build, so they scale cleanly at any size and work in both light and dark mode.

Some common Mermaid diagram types that work well in documentation:

  • graph LR or graph TD for flowcharts (left-to-right or top-down)
  • sequenceDiagram for showing interactions between components
  • classDiagram for object relationships
  • stateDiagram-v2 for state machines

See the Mermaid documentation for the full syntax reference.

Callout Blocks for Visual Notes

When you need to draw attention to something without using an image, Quarto callout blocks provide styled containers:

::: {.callout-tip}
## Pro Tip
Run `great-docs preview` after adding images to verify they render correctly
before committing.
:::

The available callout types are note, tip, warning, caution, and important. Each has a distinct color and icon.

Tips

Keep image file sizes reasonable. PNG works well for screenshots, and SVG is ideal for diagrams and logos. For large screenshots, consider compressing them or reducing the resolution.

Always provide alt text for images so that screen readers can describe the content. In standard Markdown images, the alt text is the text between the square brackets. In Quarto figures, use the fig-alt attribute.