# Add Images and Diagrams

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:

``` markdown
![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:

``` markdown
![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:

``` markdown
::: {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 New in 0.2

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

```` markdown
```{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](https://mermaid.js.org/intro/) 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:

``` markdown
::: {.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.


# Images in README.md

When your README.md contains images, Great Docs automatically copies those files to the build directory so they display correctly on your site's homepage.

For example, if your project root looks like this:

    my-package/
    ├── README.md
    ├── images/
    │   └── screenshot.png
    └── assets/
        └── logo.svg

And your README.md includes:

``` markdown
![Screenshot](images/screenshot.png)
<img src="assets/logo.svg" alt="Logo" />
```

Both images will be available in the built site:

- Images in `assets/` are copied via the standard asset mechanism
- Images anywhere else (like `images/`) are detected from the README and copied automatically

This works for both Markdown image syntax (`![alt](path)`) and HTML `<img>` tags. External URLs (starting with `http://`, `https://`, or `//`) are left unchanged.

> **Note: Note**
>
> For the most portable setup, place all images in the `assets/` directory at your project root. This ensures they work in both your GitHub README and your Great Docs site without any special handling.


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