----------------------------------------------------------------------
This is the API documentation for the great_docs library.
----------------------------------------------------------------------


## The GreatDocs Class

The central class that orchestrates site initialization, building, and deployment for your Python package documentation.


GreatDocs(project_path: str | None = None)

GreatDocs class for creating beautiful API documentation sites.

This class provides methods to install assets and configure Quarto projects with the great-docs
styling and functionality. It handles package discovery, API reference generation, Quarto
configuration, and site building with a consistent, polished look.

Parameters
----------
project_path
    Path to the project root directory. If `None` (the default), the current working directory
    is used.

Attributes
----------
project_root
    Absolute path to the project root directory.
docs_dir
    Relative path to the documentation build directory (`great-docs`).
project_path
    Full absolute path to the documentation build directory (`project_root / docs_dir`).

Examples
--------
Create a documentation site for a Python package:

```python
from great_docs import GreatDocs

gd = GreatDocs()

# One-time setup: generates great-docs.yml and discovers exports
gd.install()

# Build the documentation site
gd.build()

# Preview locally in a browser
gd.preview()
```

Build from a different directory:

```python
gd = GreatDocs(project_path="/path/to/my-package")
gd.build()
```

Notes
-----
The typical workflow is: `install()` once to scaffold configuration, then `build()` (and
optionally `preview()`) as you iterate. The `build()` method re-discovers package exports by
default, so new functions and classes are picked up automatically.


## GreatDocs Methods

Methods for installing dependencies, building the documentation site, launching a live preview, and validating links across all pages.


install(self, force: bool = False) -> None

Initialize great-docs in your project.

This method creates a great-docs.yml configuration file in the project root
with discovered exports and sensible defaults. The docs directory and assets
will be created later during the build process.

::: {.callout-note}
In practice, you would normally use the `great-docs init` CLI command rather
than calling this method directly. See the
[CLI reference](cli/init.qmd) for details.
:::

Parameters
----------
force
    If `True`, overwrite existing great-docs.yml without prompting. Default is `False`.

Examples
--------
Initialize great-docs in the current directory:

```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.install()
```

Initialize in a specific project directory, overwriting existing config:

```python
docs = GreatDocs("/path/to/my/project")
docs.install(force=True)
```

uninstall(self) -> None

Remove Great Docs configuration and generated build directories

Delete `great-docs.yml` and the current `great-docs/` build directory.
Also delete each historical `great-docs-<tag>/` directory that is not a
symlink and contains the complete generated-file header. Preserve
symlinks and historical directories without this header.

::: {.callout-note}
In practice, you would normally use the `great-docs uninstall` CLI command
rather than calling this method directly. See the
[CLI reference](cli/uninstall.qmd) for details.
:::

Examples
--------
Uninstall great-docs from the current directory:

```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.uninstall()
```

Uninstall from a specific project directory:

```python
docs = GreatDocs("/path/to/my/project")
docs.uninstall()
```

build(self, watch: bool = False, refresh: bool = True, version_tags: list[str] | None = None, latest_only: bool = False) -> None

Build the documentation site.

Generates API reference pages followed by `quarto render`. By default, re-discovers package
exports and updates the API reference configuration before building.

::: {.callout-note}
In practice, you would normally use the `great-docs build` CLI command rather
than calling this method directly. See the
[CLI reference](cli/build.qmd) for details.
:::

Parameters
----------
watch
    If `True`, watch for changes and rebuild automatically.
refresh
    If `True` (default), re-discover package exports and update API reference config before
    building. Set to False for faster rebuilds when your package API hasn't changed.
version_tags
    If provided, only build these specific version tags (for multi-version sites). Ignored
    when no `versions:` config is present.
latest_only
    If `True`, build only the latest version (skip historical versions). Ignored when no
    `versions:` config is present.

Examples
--------
Build the documentation (with API refresh):

```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.build()
```

Build with watch mode:

```python
docs.build(watch=True)
```

Quick rebuild without API refresh:

```python
docs.build(refresh=False)
```

preview(self, port: int = 3000) -> None

Preview the documentation site locally.

Starts a local HTTP server and opens the built site in the default browser. If the site
hasn't been built yet, it will be built first. Use `great-docs build` to rebuild the site if
you've made changes.

::: {.callout-note}
In practice, you would normally use the `great-docs preview` CLI command rather than calling
this method directly. See the [CLI reference](cli/preview.qmd) for details.
:::

Parameters
----------
port
    The port number for the local HTTP server (default `3000`).

Examples
--------
Preview the documentation:

```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.preview()
```

check_links(self, include_source: bool = True, include_docs: bool = True, timeout: float = 10.0, ignore_patterns: list[str] | None = None, verbose: bool = False) -> dict

Check all links in source code and documentation for broken links.

::: {.callout-note}
In practice, you would normally use the `great-docs check-links` CLI command rather than
calling this method directly. See the [CLI reference](cli/check_links.qmd) for details.
:::

This method scans Python source files and documentation files (`.qmd`, `.md`) for URLs and
checks their HTTP status. It reports broken links (404s) and warns about redirects.

The following content is automatically excluded from link checking:

- **Python comments**: URLs in lines starting with `#`
- **Code blocks**: URLs inside fenced code blocks (````` ... `````)
- **Inline code**: URLs inside backticks (`` `...` ``)
- **Marked URLs**: URLs followed by `{.gd-no-link}` in `.qmd`/`.md` files

For documentation, the checker scans the source `user_guide/` directory rather than the
generated `docs/` directory to avoid checking transient files.

In `.qmd` files, you can exclude specific URLs from checking by adding `{.gd-no-link}`
immediately after the URL:

    Visit http://example.com{.gd-no-link} for an example.
    Also works with inline code: `http://example.com`{.gd-no-link}

Parameters
----------
include_source
    If `True`, scan Python source files in the package directory for URLs. Default is
    `True`.
include_docs
    If `True`, scan documentation files (`.qmd`, `.md`) for URLs. Default is `True`.
timeout
    Timeout in seconds for each HTTP request. Default is `10.0`.
ignore_patterns
    List of URL patterns (strings or regex) to ignore. URLs matching any pattern will be
    skipped. Default is `None`.
verbose
    If `True`, print detailed progress information. Default is `False`.

Returns
-------
dict
    A dictionary containing:

    - `total`: total number of unique links checked
    - `ok`: list of links that returned 2xx status
    - `redirects`: list of dicts with `url`, `status`, `location` for 3xx responses
    - `broken`: list of dicts with `url`, `status`, `error` for 4xx/5xx or errors
    - `skipped`: list of URLs that were skipped (matched ignore patterns)
    - `by_file`: dict mapping file paths to lists of links found in each file

Examples
--------
Check all links in a project:

```python
from great_docs import GreatDocs

docs = GreatDocs()
results = docs.check_links()

print(f"Checked {results['total']} links")
print(f"Broken: {len(results['broken'])}")
print(f"Redirects: {len(results['redirects'])}")
```

Check only documentation files with custom timeout:

```python
results = docs.check_links(
    include_source=False,
    timeout=5.0,
    ignore_patterns=["localhost", "127.0.0.1", "example.com"]
)
```


## Table Preview/Explorer

Generate styled HTML table previews from any tabular data source with `tbl_preview()`, and explore tables interactively with `tbl_explorer()`.


tbl_preview(data: 'Any', columns: 'list[str] | None' = None, n_head: 'int' = 5, n_tail: 'int' = 5, limit: 'int' = 50, show_all: 'bool' = False, show_row_numbers: 'bool' = True, show_dtypes: 'bool' = True, show_dimensions: 'bool' = True, max_col_width: 'int' = 250, min_tbl_width: 'int' = 500, caption: 'str | None' = None, highlight_missing: 'bool' = True, row_index_offset: 'int' = 0, id: 'str | None' = None) -> 'TblPreview'

Generate a self-contained HTML table preview from almost any tabular data source.

The `tbl_preview()` function gives you a quick, polished look at a dataset without pulling in
heavy rendering dependencies. Pass it a Polars DataFrame, a Pandas DataFrame, a PyArrow Table,
a file path to a CSV / TSV / JSONL / Parquet / Feather file, a column-oriented dictionary, or a
list of row dictionaries—and get back a styled HTML table that renders identically in notebooks,
Quarto documents, and static HTML pages.

The preview shows a configurable number of rows from the top and bottom of the table, separated
by a blue divider line when the full dataset exceeds the requested row count. Each column header
displays the column name and, beneath it, a compact dtype label (e.g., `i64`, `str`, `f64`). A
header banner shows a colored badge identifying the data source type (Polars, Pandas, CSV,
Parquet, etc.) alongside row and column counts. Missing values (`None`, `NaN`, `NA`) are
highlighted in red so they stand out immediately.

The output is a :class:`TblPreview` object with `_repr_html_()` support, so it displays
automatically in Jupyter notebooks and Quarto code cells. All CSS is scoped to a unique id,
and the table includes full dark-mode support. No JavaScript is required.

Parameters
----------
data
    The table to preview. This can be a Polars DataFrame, a Pandas DataFrame, a PyArrow Table, a
    file path (as a string or `pathlib.Path` object), a column-oriented dictionary, or a list of
    row dictionaries. When providing a file path, the extension determines the loader: `.csv`,
    `.tsv`, `.jsonl` (or `.ndjson`), `.parquet`, `.feather`, and `.arrow` (Arrow IPC) are all
    supported. Read the *Supported Input Data Types* section for details on each accepted
    format.
columns
    The columns to display in the preview, by default `None` (all columns are shown). This
    can be a list of column name strings. If any name does not match a column in the table, a
    `KeyError` is raised. This is useful for focusing on a subset of a wide dataset.
n_head
    The number of rows to show from the start of the table. Set to `5` by default. When the
    table has fewer rows than `n_head + n_tail`, the full table is displayed without a
    divider.
n_tail
    The number of rows to show from the end of the table. Set to `5` by default.
limit
    The limit value for the sum of `n_head=` and `n_tail=` (the total number of rows shown).
    If the sum of `n_head=` and `n_tail=` exceeds the limit, a `ValueError` is raised. The
    default value is `50`. Increase this when you need to display more rows.
show_all
    Should the entire table be displayed? If `True`, all rows are shown regardless of the
    `n_head=` and `n_tail=` settings. By default, this is `False`.
show_row_numbers
    Should row numbers be shown? The numbers appear in a narrow gutter column on the left side
    of the table, separated from the data columns by a subtle blue vertical line. By default,
    this is set to `True`.
show_dtypes
    Should data type labels be displayed beneath each column name? The labels use short
    abbreviations (e.g., `i64` for 64-bit integer, `str` for string, `f64` for 64-bit float). By
    default, this is set to `True`.
show_dimensions
    Should the header banner be shown? The banner displays a colored badge identifying the data
    source type alongside row and column counts in labeled pill badges. By default, this is set
    to `True`.
max_col_width
    The maximum width of any single column in pixels. Column widths are computed automatically
    to fit their content up to this ceiling, beyond which cell text is truncated with an
    ellipsis. The default value is `250` pixels.
min_tbl_width
    The minimum total width of the table in pixels. If the sum of the computed column widths is
    less than this value, columns are proportionally widened to fill the available space. The
    default value is `500` pixels.
caption
    An optional caption string displayed below the header banner and above the column headers.
    Useful for labeling a preview with a dataset name or description. By default, no caption is
    shown.
highlight_missing
    Should missing values (`None`, `NaN`, `NA`) be highlighted? When `True` (the default),
    missing cells are displayed in red text on a light red background so they stand out at a
    glance.
row_index_offset
    The starting number for row indices. Defaults to `0`, matching the zero-based indexing
    convention of Python, Polars, and Pandas. Set to `1` for one-based numbering (e.g., for
    presentation to audiences unfamiliar with zero-based indexing).
id
    An HTML `id` attribute for the outer `<div>` container. If `None` (the default), a unique ID
    is auto-generated using `secrets.token_hex(4)`. Providing your own ID is useful when you
    need to target the table with custom CSS or JavaScript.

Returns
-------
TblPreview
    A rendered table preview object. The object has `_repr_html_()` for automatic notebook
    display.

Supported Input Data Types
--------------------------
The `data` parameter accepts any of the following:

- **Polars DataFrame** — displays a blue *Polars* badge
- **Pandas DataFrame** — displays a dark purple *Pandas* badge
- **PyArrow Table** — displays an indigo *Arrow* badge
- **CSV file** (`.csv`) — loaded automatically; displays a cream *CSV* badge
- **TSV file** (`.tsv`) — loaded automatically; displays a green *TSV* badge
- **JSONL file** (`.jsonl` or `.ndjson`) — loaded line-by-line; displays a blue *JSONL*
  badge
- **Parquet file** (`.parquet`) — requires `polars`, `pandas`, or `pyarrow`; displays
  a purple *Parquet* badge
- **Feather / Arrow IPC file** (`.feather` or `.arrow`) — requires `polars`, `pandas`,
  or `pyarrow`; displays an orange *Feather* badge
- **Dictionary** (column-oriented, `dict[str, list]`) — displays a gray *Table* badge
- **List of dictionaries** (row-oriented, `list[dict]`) — displays a gray *Table* badge

For file-based inputs, pass a string or `pathlib.Path` object. The file extension is used to
determine the format. Polars is preferred for loading when available; Pandas and PyArrow are
used as fallbacks.

Examples
--------
The simplest way to preview a table is to pass a Python dictionary:

```{python}
from great_docs import tbl_preview

tbl_preview({"city": ["Tokyo", "Paris", "New York"], "population": [13960000, 2161000, 8336000]})
```

The result is a styled HTML table with a header banner showing the row and column count, dtype
labels beneath each column name, and row numbers on the left.

You can also pass a Polars DataFrame:

```{python}
import polars as pl

df = pl.DataFrame({
    "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
    "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
    "price": [29.99, 49.50, 12.00, 8.75, 199.99],
    "in_stock": [True, False, True, True, False],
})

tbl_preview(df)
```

For large tables, only the first `n_head=` and last `n_tail=` rows are shown, separated by a
blue divider line. Adjust the counts to show more or fewer rows:

```{python}
tbl_preview(df, n_head=2, n_tail=1)
```

Use `columns=` to focus on specific columns in a wide dataset:

```{python}
tbl_preview(df, columns=["product", "price"])
```

File paths work directly—no need to load the data yourself:

```{python}
#| echo: false
#| output: false
import pathlib, json
_d = pathlib.Path("assets/tbl-preview-data")
_d.mkdir(parents=True, exist_ok=True)
(_d / "students.csv").write_text(
    "name,subject,score,grade,passed\n"
    "Alice,Math,95.5,A,true\n"
    "Bob,Science,82.0,B,true\n"
    "Charlie,English,71.3,C,true\n"
    "Diana,History,60.0,D,true\n"
    "Eve,Art,55.8,F,false\n"
    "Frank,Math,88.2,B+,true\n"
    "Grace,Science,79.9,C+,true\n"
    "Hank,English,91.0,A-,true\n"
    "Iris,History,66.4,D+,true\n"
    "Jack,Art,73.7,C,true\n"
)
```

```{python}
tbl_preview("assets/tbl-preview-data/students.csv")
```

Add a caption to label the preview:

```{python}
tbl_preview(df, caption="Product Catalog for Q1 2026")
```

For a minimal look, turn off the header banner, dtype labels, and row numbers:

```{python}
tbl_preview(df, show_dimensions=False, show_dtypes=False, show_row_numbers=False)
```

See Also
--------
tbl_explorer: Launch an interactive table explorer for deeper data investigation.

enable_tbl_preview(**kwargs: 'Any') -> 'None'

Register `tbl_preview()` as the default DataFrame display formatter.

After calling this, any Polars or Pandas DataFrame that is the last expression in a cell (or
passed to `display()`) will be rendered as a `tbl_preview()` table instead of the library's
default HTML.

Parameters
----------
**kwargs
    Keyword arguments forwarded to `tbl_preview()` (e.g., `n_head=10`, `show_all=True`,
    `show_dimensions=False`).

Returns
-------
None
    The formatter is registered as a side effect. IPython suppresses `None` output, so
    nothing is printed in the cell.

Examples
--------
```{python}
import pandas as pd
import great_docs as gd

df = pd.DataFrame({"name": ["Alice", "Bob", "Carol"], "score": [92, 87, 95]})
```

Before enabling, the DataFrame renders with default Pandas HTML:

```{python}
df
```

After enabling, the same DataFrame renders as a `tbl_preview()` table:

```{python}
gd.enable_tbl_preview(n_head=3)
df
```

From this point on, all DataFrames (Pandas, Polars, or otherwise) will render using
`tbl_preview()` until `disable_tbl_preview()` is called.

See Also
--------
disable_tbl_preview : Remove the formatter and restore default display.
tbl_preview : Generate a preview table for a single DataFrame.

disable_tbl_preview() -> 'None'

Remove the `tbl_preview()` display formatter and restore defaults.

After calling this, any Polars or Pandas DataFrame will revert to using the library's default
HTML representation instead of `tbl_preview()`. This undoes the effect of
`enable_tbl_preview()`.

Returns
-------
None
    The formatter is removed as a side effect. IPython suppresses `None` output, so
    nothing is printed in the cell.

Examples
--------
```{python}
import pandas as pd
import great_docs as gd

df = pd.DataFrame({"name": ["Alice", "Bob", "Carol"], "score": [92, 87, 95]})
gd.enable_tbl_preview(n_head=3)
```

With the preview formatter active, the DataFrame renders as a `tbl_preview()` table:

```{python}
df
```

After disabling, the DataFrame reverts to the default Pandas HTML:

```{python}
gd.disable_tbl_preview()
df
```

From this point on, all DataFrames (Pandas, Polars, or otherwise) will render using their
native styling until `enable_tbl_preview()` is called again.

See Also
--------
enable_tbl_preview : Register `tbl_preview()` as the default DataFrame display formatter.
tbl_preview : Generate a preview table for a single DataFrame.

tbl_explorer(data: 'Any', columns: 'list[str] | None' = None, show_row_numbers: 'bool' = True, show_dtypes: 'bool' = True, show_dimensions: 'bool' = True, max_col_width: 'int' = 250, min_tbl_width: 'int' = 500, caption: 'str | None' = None, highlight_missing: 'bool' = True, page_size: 'int' = 10, sortable: 'bool' = True, filterable: 'bool' = True, column_toggle: 'bool' = True, copyable: 'bool' = True, downloadable: 'bool' = True, resizable: 'bool' = False, sticky_header: 'bool' = True, search_highlight: 'bool' = True, id: 'str | None' = None) -> 'TblExplorer'

Generate an interactive table explorer from almost any tabular data source.

The `tbl_explorer()` function creates a self-contained, interactive HTML table widget from
tabular data. Pass it a Polars DataFrame, a Pandas DataFrame, a PyArrow Table, a file path to a
CSV / TSV / JSONL / Parquet / Feather file, a column-oriented dictionary, or a list of row
dictionaries—and get back an interactive table with sorting, token-based filtering, pagination,
column toggling, copy-to-clipboard, and CSV download.

The output uses **progressive enhancement**: the initial HTML contains a fully rendered static
table (the first page of data) that is readable without JavaScript. When JavaScript is available,
the static table is enhanced with interactive controls. All row data is embedded as inline JSON
within the HTML, so the widget is completely self-contained with no external dependencies.

The interactive toolbar includes a token-based filter bar (with type-aware operators for string,
numeric, and boolean columns), a column visibility dropdown, copy and download buttons, and a
reset control. Column headers are clickable for single-column sorting, and shift-click enables
multi-column sorting. Pagination is enabled by default at 20 rows per page.

The output is a :class:`TblExplorer` object with `_repr_html_()` support, so it displays
automatically in Jupyter notebooks and Quarto code cells. All CSS is scoped to a unique id, and
the table includes full dark-mode support.

Parameters
----------
data
    The table to explore. This can be a Polars DataFrame, a Pandas DataFrame, a PyArrow Table,
    a file path (as a string or `pathlib.Path` object), a column-oriented dictionary, or a list
    of row dictionaries. When providing a file path, the extension determines the loader:
    `.csv`, `.tsv`, `.jsonl` (or `.ndjson`), `.parquet`, `.feather`, and `.arrow` (Arrow IPC)
    are all supported. Read the *Supported Input Data Types* section for details on each
    accepted format.
columns
    The columns to display in the explorer, by default `None` (all columns are shown). This
    can be a list of column name strings. If any name does not match a column in the table, a
    `KeyError` is raised. This is useful for focusing on a subset of a wide dataset.
show_row_numbers
    Should row numbers be shown? The numbers appear in a narrow gutter column on the left side
    of the table, separated from the data columns by a subtle blue vertical line. By default,
    this is set to `True`.
show_dtypes
    Should data type labels be displayed beneath each column name? The labels use short
    abbreviations (e.g., `i64` for 64-bit integer, `str` for string, `f64` for 64-bit float).
    By default, this is set to `True`.
show_dimensions
    Should the header banner be shown? The banner displays a colored badge identifying the data
    source type alongside row and column counts in labeled pill badges. By default, this is set
    to `True`.
max_col_width
    The maximum width of any single column in pixels. Column widths are computed automatically
    to fit their content up to this ceiling, beyond which cell text is truncated with an
    ellipsis. The default value is `250` pixels.
min_tbl_width
    The minimum total width of the table in pixels. If the sum of the computed column widths is
    less than this value, columns are proportionally widened to fill the available space. The
    default value is `500` pixels.
caption
    An optional caption string displayed below the header banner and above the column headers.
    Useful for labeling an explorer with a dataset name or description. By default, no caption
    is shown.
highlight_missing
    Should missing values (`None`, `NaN`, `NA`) be highlighted? When `True` (the default),
    missing cells are displayed in red text on a light red background so they stand out at a
    glance.
page_size
    The number of rows to display per page. The default value is `20`. Set to `0` to disable
    pagination entirely and display all rows at once. The pagination bar shows the current range
    (e.g., "Showing 1–20 of 150 rows") and page navigation buttons.
sortable
    Should column sorting be enabled? When `True` (the default), clicking a column header
    cycles through ascending → descending → unsorted. Hold **Shift** and click to add
    multi-column sorting. Sort indicators appear as SVG arrows next to column names.
filterable
    Should the token-based filter bar be shown? When `True` (the default), a filter bar appears
    in the toolbar with a **+** button to add structured filters. Each filter is a token with a
    column, operator, and optional value. Available operators depend on the column type:
    string columns offer contains, starts with, ends with, etc.; numeric columns offer
    comparison operators including between; boolean columns offer is true/is false. Filters
    support case-sensitive matching via an **Aa** toggle.
column_toggle
    Should the column visibility dropdown be shown? When `True` (the default), a **Columns**
    button appears in the toolbar. Clicking it opens a dropdown with checkboxes for each
    column. At least one column must remain visible.
copyable
    Should the copy-to-clipboard button be shown? When `True` (the default), a clipboard icon
    appears in the toolbar. Clicking it copies the currently visible page of data as
    tab-separated values. On success, the icon briefly changes to a green checkmark.
downloadable
    Should the CSV download button be shown? When `True` (the default), a download icon appears
    in the toolbar. Clicking it downloads the full filtered dataset (all pages) as a CSV file.
resizable
    Should column drag-resize be enabled? Reserved for future use. Currently has no effect.
    The default value is `False`.
sticky_header
    Should column headers remain visible when scrolling vertically? When `True` (the default),
    the header row sticks to the top of the table container as the user scrolls through rows.
search_highlight
    Should matching cell text be highlighted when a "contains" filter is active? When `True`
    (the default), text matching the filter value is highlighted with a colored background. Set
    to `False` to disable highlighting.
id
    An HTML `id` attribute for the outer `<div>` container. If `None` (the default), a unique
    ID is auto-generated using `secrets.token_hex(4)`. Providing your own ID is useful when you
    need to target the table with custom CSS or JavaScript.

Returns
-------
TblExplorer
    A rendered interactive table object. The object has `_repr_html_()` for automatic notebook
    display.

Supported Input Data Types
--------------------------
The `data` parameter accepts any of the following:

- **Polars DataFrame** — displays a blue *Polars* badge
- **Pandas DataFrame** — displays a dark purple *Pandas* badge
- **PyArrow Table** — displays an indigo *Arrow* badge
- **CSV file** (`.csv`) — loaded automatically; displays a cream *CSV* badge
- **TSV file** (`.tsv`) — loaded automatically; displays a green *TSV* badge
- **JSONL file** (`.jsonl` or `.ndjson`) — loaded line-by-line; displays a blue *JSONL*
  badge
- **Parquet file** (`.parquet`) — requires `polars`, `pandas`, or `pyarrow`; displays
  a purple *Parquet* badge
- **Feather / Arrow IPC file** (`.feather` or `.arrow`) — requires `polars`, `pandas`,
  or `pyarrow`; displays an orange *Feather* badge
- **Dictionary** (column-oriented, `dict[str, list]`) — displays a gray *Table* badge
- **List of dictionaries** (row-oriented, `list[dict]`) — displays a gray *Table* badge

For file-based inputs, pass a string or `pathlib.Path` object. The file extension is used to
determine the format. Polars is preferred for loading when available; Pandas and PyArrow are
used as fallbacks.

Examples
--------
The simplest way to explore a table is to pass a Python dictionary:

```{python}
from great_docs import tbl_explorer

tbl_explorer({
    "city": ["Tokyo", "Paris", "New York", "London", "Sydney"],
    "population": [13960000, 2161000, 8336000, 8982000, 5312000],
    "country": ["Japan", "France", "USA", "UK", "Australia"],
})
```

You can also pass a Polars DataFrame:

```{python}
import polars as pl

df = pl.DataFrame({
    "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
    "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
    "price": [29.99, 49.50, 12.00, 8.75, 199.99],
    "in_stock": [True, False, True, True, False],
})

tbl_explorer(df)
```

Load a CSV file and show only specific columns:

```python
tbl_explorer("data/sales.csv", columns=["product", "revenue", "units"])
```

Disable pagination to show all rows at once:

```python
tbl_explorer(df, page_size=0)
```

Create a minimal, sort-only table with no toolbar controls:

```python
tbl_explorer(
    df,
    sortable=True,
    filterable=False,
    column_toggle=False,
    copyable=False,
    downloadable=False,
    page_size=0,
)
```

See Also
--------
tbl_preview: A simpler table preview widget for quick looks at datasets without interactive controls or pagination.


## Skills

Install, check, and list Agent Skills from the Python API.


install_skill(*, package: 'str | None' = None, url: 'str | None' = None, skill_content: 'str | None' = None, agent: 'AgentFormat | None' = None, global_: 'bool' = False, path: 'str | None' = None, root: 'Path | None' = None, detect: 'bool' = False, skill_name: 'str | None' = None, extra_files: 'dict[str, str] | None' = None, quiet: 'bool' = False) -> 'list[Path]'

Install a SKILL.md file for AI coding agents.

Resolves skill content from one of three sources (in priority order):

1. `skill_content`: raw SKILL.md text provided directly
2. `url`: fetch from a documentation site's well-known endpoint
3. `package`: find bundled skills inside an installed Python package

The skill is installed to the appropriate agent directory based on auto-detection or explicit
`agent` parameter.

Parameters
----------
package
    Python package name (e.g., `"great-tables"`). Skills are looked up inside the installed
    package's `skills/` directory.
url
    Documentation site URL to fetch skills from via the `.well-known` discovery protocol.
skill_content
    Raw SKILL.md content to install directly.
agent
    Target agent format. If not set, auto-detected from the project root or prompted
    interactively.
global_
    Install to the global (home directory) location instead of the repo.
path
    Explicit target path. Overrides agent-based path resolution.
root
    Project root directory. Defaults to the current working directory.
detect
    Auto-detect existing installations and update them in place.
skill_name
    Override the skill name (derived from frontmatter by default).
extra_files
    Additional files to install alongside SKILL.md, as `{relative_path: content}` pairs.
quiet
    Suppress output messages.

Returns
-------
list[Path]
    Paths to installed SKILL.md files (one per agent if multiple detected).

check_skill(*, package: 'str | None' = None, global_: 'bool' = False, local: 'bool' = True, root: 'Path | None' = None, update: 'bool' = False, quiet: 'bool' = False) -> 'list[dict]'

Check if installed skills are up to date.

Scans for installed SKILL.md files and compares their version with the version bundled in the
installed Python package.

Parameters
----------
package
    Python package name to check. If None, checks all detected skills.
global_
    Only check global (home directory) installations.
local
    Only check local (repository) installations.
root
    Project root directory. Defaults to the current working directory.
update
    Automatically update any outdated skills found.
quiet
    Suppress output messages.

Returns
-------
list[dict]
    Status entries: `{"path": Path, "name": str, "installed_version": str,
    "package_version": str, "status": "current"|"outdated"|"unknown"}`.

list_skills(*, package: 'str | None' = None, url: 'str | None' = None, quiet: 'bool' = False) -> 'list[dict]'

List available skills from a package or URL.

Parameters
----------
package
    Python package name to list skills from.
url
    Documentation site URL to query for skills.
quiet
    Suppress output messages.

Returns
-------
list[dict]
    Skill entries: `{"name": str, "description": str, "path": Path|None,
    "version": str|None}`.


----------------------------------------------------------------------
This is the CLI documentation for the package.
----------------------------------------------------------------------

## CLI: great-docs

```
Usage: great-docs [OPTIONS] COMMAND [ARGS]...

  Great Docs: Beautiful documentation for Python packages.

  Great Docs generates professional documentation sites with auto-generated
  API references, CLI documentation, smart navigation, and modern styling.

  Get started with 'great-docs init' to set up your docs, then use 'great-docs
  build' to generate your site.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  init                Initialize great-docs in your project (one-time...
  build               Build your documentation site.
  preview             Preview your documentation locally.
  uninstall           Remove great-docs from your project.
  config              Generate a great-docs.yml configuration file.
  ci                  Helpers meant to run inside CI (GitHub Actions).
  scan                Discover package exports and preview what can be...
  freeze              Execute specific pages and persist their freeze cache.
  timings             Show page-level build timings from the last build.
  setup-github-pages  Set up automatic deployment to GitHub Pages.
  check-links         Check for broken links in source code and...
  changelog           Generate a Changelog page from GitHub Releases.
  proofread           Check spelling and grammar in documentation files...
  seo                 Audit SEO health of your documentation site.
  lint                Lint documentation quality for your package.
  api-diff            Compare the public API between two versions.
  versions            List configured documentation versions.
  api-snapshot        Capture a JSON snapshot of a package's public API.
  skill               Manage AI coding agent skills.
  termshow            Terminal recording and playback for CLI/TUI...
```

### great-docs init

```
Usage: great-docs init [OPTIONS]

  Initialize great-docs in your project (one-time bootstrap).

  Creates a fresh 'great-docs.yml' configuration file with discovered package
  exports and sensible defaults. Refuses to run if 'great-docs.yml' already
  exists (use '--force' to reset).

  • Creates 'great-docs.yml' with discovered API exports
  • Auto-detects your package name and public API
  • Updates .gitignore to exclude the build directory
  • Detects docstring style (numpy, google, sphinx)

  After init, customize 'great-docs.yml' then use 'great-docs build' for all
  subsequent builds. You should never need to run 'great-docs init' again
  unless you want to completely reset your configuration.

  Examples:
    great-docs init                       # Initialize in current directory
    great-docs init --force               # Reset config to defaults
    great-docs init --project-path ../pkg # Initialize in another project

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --force                   Delete existing great-docs.yml and generate a
                            fresh default config
  --help                    Show this message and exit.
```

### great-docs build

```
Usage: great-docs build [OPTIONS]

  Build your documentation site.

  Requires 'great-docs.yml' to exist (run 'great-docs init' first). This is
  the only command you need day-to-day and in CI.

  Creates the 'great-docs/' build directory, copies all assets, and builds the
  documentation site. The build directory is ephemeral and should not be
  committed to version control.

  Use '--project-path' to point to a project in a different directory. Use '--
  watch' to automatically rebuild when source files change.

  Use '--no-refresh' to skip API discovery for faster rebuilds when your
  package's public API hasn't changed.

  When multi-version documentation is configured, use '--versions' to build
  only specific versions, or '--latest-only' to skip historical versions.

  Use '--from-repo' to build documentation from a remote Git repository. This
  clones the repo into a temporary directory, creates an isolated virtual
  environment, installs the package and great-docs, builds the site, and
  copies the output to '--output-dir' (or './great-docs/_site').

  Add '--preview' to automatically start a local server after a '--from-repo'
  build completes, opening the site in your browser.

  Examples:
    great-docs build                      # Full build with API refresh
    great-docs build --no-refresh         # Fast rebuild (skip API discovery)
    great-docs build --watch              # Rebuild on file changes
    great-docs build --versions 0.3,dev   # Build specific versions only
    great-docs build --latest-only        # Build only the latest version
    great-docs build --project-path ../pkg
    great-docs build --from-repo https://github.com/owner/pkg.git
    great-docs build --from-repo git@github.com:owner/pkg.git --branch v1.0
    great-docs build --from-repo https://github.com/owner/pkg.git --output-dir ./site
    great-docs build --from-repo https://github.com/owner/pkg.git --shallow
    great-docs build --from-repo https://github.com/owner/pkg.git --preview

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --watch                   Watch for changes and rebuild automatically
  --no-refresh              Skip re-discovering package exports (faster
                            rebuild when API unchanged)
  --versions TEXT           Build only specific versions (comma-separated
                            tags, e.g. '0.3,dev')
  --latest-only             Build only the latest version (skip historical
                            versions)
  --from-repo TEXT          Clone a remote Git repository and build its docs
                            (HTTPS or SSH URL)
  --branch TEXT             Branch or tag to check out when using --from-repo
                            (default: repo default)
  --output-dir DIRECTORY    Where to copy the built site when using --from-
                            repo (default: ./great-docs/_site)
  --shallow                 Force shallow clone with --from-repo (fastest, but
                            no versioned docs or page dates)
  --preview                 Start a preview server after building with --from-
                            repo
  --help                    Show this message and exit.
```

### great-docs preview

```
Usage: great-docs preview [OPTIONS]

  Preview your documentation locally.

  Starts a local HTTP server and opens the built documentation site in your
  default browser. If the site hasn't been built yet, it will build it first.

  The site is served from 'great-docs/_site/'. Use 'great-docs build' to
  rebuild if you've made changes.

  Use '--site-dir' to preview a site from any directory (e.g. output from a '
  --from-repo' build).

  Use '--pr', '--run', or '--branch' to fetch and preview a site that CI
  already built (no hosting setup required). Downloading CI artifacts needs a
  GitHub token with 'Actions: read' (via GITHUB_TOKEN, a .env, or 'gh auth
  login' + '--use-gh'). For fork PRs you'll be viewing contributor-authored
  HTML locally.

  Examples:
    great-docs preview                    # Preview on port 3000
    great-docs preview --port 8080        # Preview on port 8080
    great-docs preview --site-dir /tmp/weathervault-site
    great-docs preview --pr 302           # Newest CI build for PR #302
    great-docs preview --run 18273645521  # A specific workflow run
    great-docs preview --pr 302 --path reference/mcp/gd_config.html

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --port INTEGER            Port for the local preview server  [default: 3000]
  --site-dir DIRECTORY      Path to a pre-built site directory to serve
                            (bypasses project detection)
  --pr INTEGER              Preview the CI docs build for this PR number.
  --run INTEGER             Preview a specific workflow run id.
  --branch TEXT             Preview the newest CI docs build for a branch.
  --repo TEXT               GitHub repo as 'owner/repo' (default: detect from
                            git remote / config).
  --artifact TEXT           Name of the CI artifact to fetch.  [default: docs-
                            html]
  --path TEXT               Open the browser at this page within the site
                            (e.g. reference/index.html).
  --no-open                 Serve without launching a browser.
  --refresh                 Ignore the local cache and re-download.
  --clear-cache             Delete the downloaded PR-preview cache and exit.
  --use-gh                  Fetch via the 'gh' CLI (uses your existing gh
                            auth) instead of a token.
  --env-file FILE           Load a .env for GITHUB_TOKEN/GH_TOKEN (default:
                            auto-detect .env).
  --help                    Show this message and exit.
```

### great-docs uninstall

```
Usage: great-docs uninstall [OPTIONS]

  Remove great-docs from your project.

  This command removes the great-docs configuration and build directory:

  • Deletes the 'great-docs.yml' configuration file
  • Removes the 'great-docs/' build directory

  Your source files ('user_guide/', 'README.md', etc.) are preserved.

  Examples:
    great-docs uninstall                  # Remove from current project

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --help                    Show this message and exit.
```

### great-docs config

```
Usage: great-docs config [OPTIONS]

  Generate a great-docs.yml configuration file.

  Creates a 'great-docs.yml' file with all available options documented. The
  generated file contains commented examples for each setting.

  Examples:
    great-docs config                     # Generate in current directory
    great-docs config --force             # Overwrite existing file
    great-docs config --project-path ../pkg

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --force                   Overwrite existing great-docs.yml without
                            prompting
  --help                    Show this message and exit.
```

### great-docs ci

```
Usage: great-docs ci [OPTIONS] COMMAND [ARGS]...

  Helpers meant to run inside CI (GitHub Actions).

  These emit the "preview this build locally" hints that let reviewers open a
  pull request's docs without a preview host: a workflow log notice and a
  sticky PR comment, both pointing at 'great-docs preview'.

  Examples:
    great-docs ci notice --run "$GITHUB_RUN_ID" --pr 302
    great-docs ci pr-comment --run "$GITHUB_RUN_ID" --pr 302

Options:
  --help  Show this message and exit.

Commands:
  pr-comment  Post or refresh a sticky PR comment with the local-preview...
  notice      Print a workflow log notice with the local-preview command.
```

### great-docs ci pr-comment

```
Usage: great-docs ci pr-comment [OPTIONS]

  Post or refresh a sticky PR comment with the local-preview command.

  Reads the token from GITHUB_TOKEN / GH_TOKEN and needs 'pull-requests:
  write'.

Options:
  --run INTEGER  Workflow run id that built the site.  [required]
  --pr INTEGER   Pull request number to comment on.  [required]
  --repo TEXT    GitHub repo as 'owner/repo' (default: $GITHUB_REPOSITORY,
                 then git remote).
  --help         Show this message and exit.
```

### great-docs ci notice

```
Usage: great-docs ci notice [OPTIONS]

  Print a workflow log notice with the local-preview command.

Options:
  --run INTEGER  Workflow run id that built the site.  [required]
  --pr INTEGER   Pull request number (adds the --pr hint).
  --help         Show this message and exit.
```

### great-docs scan

```
Usage: great-docs scan [OPTIONS]

  Discover package exports and preview what can be documented.

  This command analyzes your package to find public classes, functions, and
  other exports. Use this to see what's available before writing your
  reference config.

  Examples:
    great-docs scan                       # Show discovered exports
    great-docs scan --verbose             # Include method names for classes
    great-docs scan -v                    # Short form of --verbose

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --docs-dir TEXT           Path to documentation directory relative to
                            project root
  -v, --verbose             Show method names for each class
  --help                    Show this message and exit.
```

### great-docs freeze

```
Usage: great-docs freeze [OPTIONS] [PAGES]...

  Execute specific pages and persist their freeze cache.

  Renders one or more QMD pages (always executing their code), then copies the
  resulting '_freeze/' entries back to a persistent location so they survive
  future builds.

  PAGES are paths to .qmd files relative to your project root (e.g.,
  'user_guide/benchmarks.qmd'). Quarto always executes code when rendering
  individual files, even with freeze enabled (this is how you update frozen
  outputs).

  Use '--clean' to wipe the entire '_freeze/' cache before re-executing. This
  forces a full refresh of all specified pages from scratch.

  Use '--info' to see the freeze status of all pages without rendering.

  After running, the updated '_freeze/' entries are ready to commit to version
  control.

  Examples:
    great-docs freeze user_guide/benchmarks.qmd
    great-docs freeze user_guide/benchmarks.qmd user_guide/mcmc-demo.qmd
    great-docs freeze user_guide/benchmarks.qmd --freeze-dir docs/_freeze
    great-docs freeze user_guide/benchmarks.qmd --clean
    great-docs freeze --info

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --freeze-dir TEXT         Where to persist _freeze/ (default: project root
                            '_freeze/')
  --clean                   Delete existing _freeze/ before re-executing
                            (forces full refresh).
  --info                    Show freeze status for all pages (which are
                            frozen, cached, stale).
  --help                    Show this message and exit.
```

### great-docs timings

```
Usage: great-docs timings [OPTIONS]

  Show page-level build timings from the last build.

  Reads the build-timings.json artifact generated during 'great-docs build'
  and displays per-page render durations as a sorted table. Pages are listed
  slowest-first to help identify bottlenecks.

  Run 'great-docs build' first to generate the timing data.

  Examples:
    great-docs timings
    great-docs timings --top 10
    great-docs timings --version 0.10
    great-docs timings --output-dir ./public
    great-docs timings --json

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --top INTEGER             Show only the N slowest pages.
  --version TEXT            Show timings for a specific version only (multi-
                            version builds).
  --json                    Output raw JSON instead of a table.
  --output-dir DIRECTORY    Path to the build output directory (if different
                            from default _site).
  --help                    Show this message and exit.
```

### great-docs setup-github-pages

```
Usage: great-docs setup-github-pages [OPTIONS]

  Set up automatic deployment to GitHub Pages.

  This command creates a GitHub Actions workflow that automatically builds and
  deploys your documentation when you push to the main branch.

  The workflow will:
  • Build docs on every push and pull request
  • Deploy to GitHub Pages on main branch pushes
  • Use Quarto's official GitHub Action for reliable builds
  • Install dev dependencies (auto-detected from your package manager)

  The Python version is automatically detected from your pyproject.toml's
  `requires-python` field. Use '--python-version' to override.

  The package manager is auto-detected by checking for lock files: • uv.lock
  -> uses uv (installs dev dependencies automatically) • poetry.lock -> uses
  poetry (installs with dev dependencies) • Otherwise -> uses pip with
  optional extras like [dev,docs]

  After running this command, commit the workflow file and enable GitHub Pages
  in your repository settings (Settings -> Pages -> Source: GitHub Actions).

  Examples:
    great-docs setup-github-pages                     # Auto-detect everything
    great-docs setup-github-pages --main-branch dev   # Deploy from 'dev' branch
    great-docs setup-github-pages --python-version 3.12
    great-docs setup-github-pages --package-manager uv
    great-docs setup-github-pages --force             # Overwrite existing workflow
    great-docs setup-github-pages --install-from-main # Use GitHub main branch

Options:
  --project-path DIRECTORY        Path to your project root directory
                                  (default: current directory)
  --main-branch TEXT              Main branch name for deployment (default:
                                  main)
  --python-version TEXT           Python version for CI (default: auto-detect
                                  from pyproject.toml, or 3.11)
  --package-manager [auto|pip|uv|poetry]
                                  Package manager for installing dependencies
                                  (default: auto-detect)
  --force                         Overwrite existing workflow file without
                                  prompting
  --install-from-main             Install Great Docs from GitHub main branch
                                  instead of PyPI release
  --help                          Show this message and exit.
```

### great-docs check-links

```
Usage: great-docs check-links [OPTIONS]

  Check for broken links in source code and documentation.

  This command scans Python source files and documentation ('.qmd', '.md') for
  URLs and checks their HTTP status. It reports broken links (404s) and warns
  about redirects.

  Default ignore patterns include:
  • localhost and 127.0.0.1 URLs
  • example.com, example.org, yoursite.com URLs
  • Placeholder URLs with brackets like [username]

  Examples:
    great-docs check-links                        # Check all links
    great-docs check-links --verbose              # Show progress for each URL
    great-docs check-links --docs-only            # Only check documentation
    great-docs check-links --source-only          # Only check source code
    great-docs check-links -i "github.com/.*#"    # Ignore GitHub anchor links
    great-docs check-links --timeout 5            # Use 5 second timeout
    great-docs check-links --json-output          # Output as JSON

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --source-only             Only check links in Python source files
  --docs-only               Only check links in documentation files
  --timeout FLOAT           Timeout in seconds for each HTTP request (default:
                            10)
  -i, --ignore TEXT         URL pattern to ignore (can be used multiple times)
  -v, --verbose             Show detailed progress for each URL checked
  --json-output             Output results as JSON
  --help                    Show this message and exit.
```

### great-docs changelog

```
Usage: great-docs changelog [OPTIONS]

  Generate a Changelog page from GitHub Releases.

  Fetches published releases from the GitHub API and renders them as a
  'changelog.qmd' page in the build directory. The page is also linked in the
  navbar automatically.

  Requires the project to have a GitHub repository URL in 'pyproject.toml'.
  Set 'GITHUB_TOKEN' or 'GH_TOKEN' to avoid API rate limits.

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --max-releases INTEGER    Maximum number of releases to include (default:
                            from config or 50)
  --help                    Show this message and exit.
```

### great-docs proofread

```
Usage: great-docs proofread [OPTIONS] [FILES]...

  Check spelling and grammar in documentation files using Harper.

  Harper is a fast, privacy-first grammar checker that runs locally. It checks
  spelling, grammar, punctuation, and style in a single pass.

  By default, checks all documentation files (.qmd, .md) in the project.
  Uses smart defaults to reduce noise in technical documentation:
    - Ignores formatting rules that conflict with code/YAML (unless '--strict')
    - Includes a built-in dictionary of technical terms (unless '--no-builtin-dictionary')

  Examples:
    great-docs proofread                         # Check all docs (smart defaults)
    great-docs proofread --strict                # Check everything (no smart defaults)
    great-docs proofread --spelling-only         # Just spelling
    great-docs proofread --dialect=uk            # UK English
    great-docs proofread -d griffe -d quartodoc  # Add custom words
    great-docs proofread --json-output           # JSON output for CI
    great-docs proofread --ignore=SpellCheck     # Skip specific rules
    great-docs proofread README.md user_guide/*.qmd  # Specific files

  Requires harper-cli to be installed:
    brew install harper      # macOS
    cargo install harper-cli # any platform

Options:
  --project-path DIRECTORY    Path to your project root directory (default:
                              current directory)
  --docs-dir TEXT             Path to documentation directory relative to
                              project root
  --include-docstrings        Also check Python docstrings
  --spelling-only             Only check spelling (SpellCheck rule)
  --grammar-only              Exclude spelling, check grammar/style only
  --only TEXT                 Only run these rules (comma-separated)
  --ignore TEXT               Skip these rules (comma-separated)
  -d, --dictionary TEXT       Additional word(s) to consider correct (can be
                              used multiple times)
  --dictionary-file PATH      Path to file with custom words (one per line)
  --dialect [us|uk|au|in|ca]  English dialect (default: us)
  -v, --verbose               Show detailed progress for each file checked
  --json-output               Output results as JSON for CI
  --compact                   One line per issue (GCC-style output)
  --max-issues INTEGER        Exit with error if more than N issues found
  --strict                    Disable smart defaults (check everything, no
                              builtin dictionary)
  --no-builtin-dictionary     Don't add built-in technical terms to dictionary
  --help                      Show this message and exit.
```

### great-docs seo

```
Usage: great-docs seo [OPTIONS]

  Audit SEO health of your documentation site.

  Checks for common SEO issues and provides recommendations for improvement.
  Run this after building your site with 'great-docs build'.

  Checks performed:
    • sitemap.xml presence and validity
    • robots.txt presence and configuration
    • Canonical URLs on all pages
    • Meta descriptions on pages
    • JSON-LD structured data
    • Page titles with site name
    • Missing alt text on images
    • Broken internal links (basic check)

  Examples:
    great-docs seo                        # Audit SEO health
    great-docs seo --fix                  # Fix issues where possible
    great-docs seo --json                 # JSON output for CI

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --fix                     Attempt to fix some issues automatically (e.g.,
                            generate missing files)
  --json                    Output results as JSON for CI integration
  --help                    Show this message and exit.
```

### great-docs lint

```
Usage: great-docs lint [OPTIONS]

  Lint documentation quality for your package.

  Analyzes your package's public API for documentation issues including
  missing docstrings, broken cross-references, inconsistent formatting,
  malformed directives, and stale version annotations.

  Checks performed:
    • missing-docstring    Public exports or methods without docstrings
    • broken-xref          '%seealso' references to unknown symbols
    • ambiguous-xref       References to a short name two objects claim
    • unread-source        A linked source's inventory could not be read
    • style-mismatch       Docstrings not matching configured style (numpy/google/sphinx)
    • unknown-directive    Unrecognized '%directive' names
    • stale-badge          Version badges far behind latest release
    • stale-callout        Version callouts that are very old
    • stale-upcoming       'upcoming:' frontmatter for already-released versions

  Examples:
    great-docs lint                                # Run all checks
    great-docs lint --check stale-versions         # Only check for stale annotations
    great-docs lint --check docstrings             # Only check for missing docstrings
    great-docs lint --check cross-refs --check style
    great-docs lint --json                         # JSON output for CI
    great-docs lint --json | jq '.issues[] | select(.severity == "error")'

Options:
  --project-path DIRECTORY        Path to your project root directory
                                  (default: current directory)
  --check [docstrings|cross-refs|style|directives|stale-versions]
                                  Run only specific checks (can be repeated).
                                  Default: all checks.
  --json                          Output results as JSON for CI integration
  --help                          Show this message and exit.
```

### great-docs api-diff

```
Usage: great-docs api-diff [OPTIONS] OLD_VERSION NEW_VERSION

  Compare the public API between two versions.

  Analyzes how the API surface changed between 'OLD_VERSION' and 'NEW_VERSION'
  (git tags). Detects added, removed, and changed symbols, tracks parameter
  changes, and flags breaking changes with migration hints.

  Use 'HEAD' as 'NEW_VERSION' to compare against the working tree.

  Examples:
    great-docs api-diff v0.1.0 v0.2.0
    great-docs api-diff v1.0.0 HEAD
    great-docs api-diff v0.9.0 v1.0.0 --json
    great-docs api-diff v0.1.0 v0.2.0 --graph
    great-docs api-diff v0.1.0 HEAD --timeline
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --changes-only
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table
    great-docs api-diff v0.1.0 v0.5.0 --symbol GreatDocs --table --html

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --package TEXT            Python package name (auto-detected from
                            pyproject.toml if omitted)
  --json                    Output results as JSON
  --graph                   Show dependency graph as Mermaid diagram for the
                            NEW version
  --timeline                Show API surface growth timeline across all
                            version tags
  --symbol TEXT             Track a single symbol across versions (shows
                            signature history)
  --changes-only            With --symbol, show only versions where the symbol
                            changed
  --table                   With --symbol, show parameter evolution as a table
  --html                    With --symbol --table, output HTML (with
                            disclosure wrapper)
  --help                    Show this message and exit.
```

### great-docs versions

```
Usage: great-docs versions [OPTIONS]

  List configured documentation versions.

  Shows the multi-version documentation configuration from 'great-docs.yml',
  including version tags, labels, and status indicators.

  Examples:
    great-docs versions              # List all configured versions
    great-docs versions --check      # Validate configuration

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --check                   Validate version configuration and exit with non-
                            zero on errors
  --help                    Show this message and exit.
```

### great-docs api-snapshot

```
Usage: great-docs api-snapshot [OPTIONS] [VERSION_TAG]

  Capture a JSON snapshot of a package's public API.

  Snapshots record every public symbol, its parameters, type annotations, and
  other metadata. They are used to build versioned API reference pages and
  compute diff annotations without needing access to old source code.

  With no arguments, snapshot the *current* working-tree API:
    'great-docs api-snapshot'

  Snapshot a specific git tag:
    'great-docs api-snapshot v1.0.0'

  Snapshot all version tags at once:
    'great-docs api-snapshot --all-tags'

  Snapshots are saved to '.great-docs/snapshots/<version>.json' by default.

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --package TEXT            Python package name (auto-detected from
                            'pyproject.toml' if omitted)
  -o, --output FILE         Output file path (default: '.great-
                            docs/snapshots/<version>.json')
  --all-tags                Snapshot all version tags in the repository
  --force                   Overwrite existing snapshot files
  --help                    Show this message and exit.
```

### great-docs skill

```
Usage: great-docs skill [OPTIONS] COMMAND [ARGS]...

  Manage AI coding agent skills.

  Install, check, and list SKILL.md files so AI coding agents can learn to use
  your Python package.

  Quick start:
    great-docs skill install great-docs      # install Great Docs' own skill
    great-docs skill install great-tables    # install from PyPI package
    great-docs skill install pointblank      # works with any GD-powered package
    great-docs skill check                   # verify freshness
    great-docs skill check --update          # auto-update outdated skills
    great-docs skill list great-tables       # see what's bundled

Options:
  --help  Show this message and exit.

Commands:
  install  Install skills for AI coding agents.
  check    Check if installed skills are up to date.
  list     List available skills from a package or URL.
```

### great-docs skill install

```
Usage: great-docs skill install [OPTIONS] [SOURCE]

  Install skills for AI coding agents.

  SOURCE can be a Python package name or a documentation site URL. If omitted,
  looks for skills in the current package.

  Examples:
    great-docs skill install                    # current package (pyproject.toml)
    great-docs skill install great-tables       # any installed package
    great-docs skill install polars pointblank  # multiple packages at once
    great-docs skill install https://posit-dev.github.io/great-tables/
    great-docs skill install great-tables --agent claude           # Claude Code
    great-docs skill install great-tables --agent copilot          # GitHub Copilot
    great-docs skill install great-tables --global                 # install to ~/
    great-docs skill install great-tables --path .claude/skills/gt # custom path
    great-docs skill install --detect           # find and refresh all skills

Options:
  -g, --global                    Install the skill globally (~/) instead of
                                  in the current repository.
  -p, --path TEXT                 Custom path where to install the skill.
  -d, --detect                    Automatically detect and update existing
                                  installations.
  --agent [claude|copilot|cursor|windsurf|opencode|codex]
                                  Target agent format (auto-detected if not
                                  specified).
  --name TEXT                     Override the skill name.
  --help                          Show this message and exit.
```

### great-docs skill check

```
Usage: great-docs skill check [OPTIONS] [PACKAGE]

  Check if installed skills are up to date.

  Scans for installed SKILL.md files and compares their content hash with the
  currently installed package to detect changes.

  Examples:
    great-docs skill check                # check all installed skills
    great-docs skill check great-tables   # check a specific package
    great-docs skill check --global       # check global installations only
    great-docs skill check --update       # reinstall any that have changed

Options:
  -g, --global  Only check global installations (in home directory).
  -l, --local   Only check local installations (in current repository).
  -u, --update  Automatically update any outdated skills found.
  --help        Show this message and exit.
```

### great-docs skill list

```
Usage: great-docs skill list [OPTIONS] [SOURCE]

  List available skills from a package or URL.

  Shows all SKILL.md files bundled in a package or discoverable at a URL,
  including their names and file paths.

  Examples:
    great-docs skill list                   # current package (pyproject.toml)
    great-docs skill list great-tables      # any installed package
    great-docs skill list https://posit-dev.github.io/great-tables/

Options:
  --url TEXT  Documentation site URL to query for available skills.
  --help      Show this message and exit.
```

### great-docs termshow

```
Usage: great-docs termshow [OPTIONS] COMMAND [ARGS]...

  Terminal recording and playback for CLI/TUI documentation.

  Record terminal sessions, edit them with YAML scripts, and render them as
  SVG frame sequences for the termshow player.

Options:
  --help  Show this message and exit.

Commands:
  edit         Open the Termshow Editor for a .termshow recording.
  import-cast  Import an asciicast (.cast) file to .termshow format.
  record       Record a terminal session to a .termshow file.
  render       Render a .termshow recording into SVG frames.
```

### great-docs termshow record

```
Usage: great-docs termshow record [OPTIONS] OUTPUT

  Record a terminal session to a .termshow file.

  Spawns an interactive shell and captures all output with timing. Press
  Ctrl+D or type 'exit' to stop recording.

Options:
  --cols INTEGER   Terminal width in columns
  --rows INTEGER   Terminal height in rows
  --shell TEXT     Shell to spawn (default: $SHELL)
  --capture-input  Also capture keyboard input events
  --help           Show this message and exit.
```

### great-docs termshow render

```
Usage: great-docs termshow render [OPTIONS] SOURCE

  Render a .termshow recording into SVG frames.

  Processes the recording through the virtual terminal emulator and produces
  SVG keyframes + a manifest.json for the player.

Options:
  -o, --output-dir PATH  Output directory for frames
  --interval FLOAT       Keyframe interval in seconds
  --script PATH          Path to .termshow.yml script
  --help                 Show this message and exit.
```

### great-docs termshow import-cast

```
Usage: great-docs termshow import-cast [OPTIONS] SOURCE OUTPUT

  Import an asciicast (.cast) file to .termshow format.

Options:
  --help  Show this message and exit.
```

### great-docs termshow edit

```
Usage: great-docs termshow edit [OPTIONS] SOURCE

  Open the Termshow Editor for a .termshow recording.

  Launches a browser-based timeline editor for adding chapters, annotations,
  and cuts. Changes are saved back to the .termshow.yml script file.

  Examples:   great-docs termshow edit demos/my-demo.termshow   great-docs
  termshow edit demos/install.termshow --port 9000

Options:
  --port INTEGER  Local server port
  --no-browser    Don't auto-open browser
  --help          Show this message and exit.
```


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------


## Getting Started

# Welcome to Great Docs

Great Docs is a documentation site generator for Python packages. Run one command, get a complete documentation site. Customize as much or as little as you want.

## Get Up and Running Fast

Point Great Docs at your Python package and it does the rest. `great-docs init` scans your codebase, discovers your public API, detects your docstring format, and writes all the configuration for you. Then `great-docs build` produces a full documentation site (landing page, API reference, navigation) ready to preview and deploy.

No templates to author. No content pages to write by hand. No build system to learn.

## Your Site Looks Great From the Start

The default site isn't a starting point you'll need to overhaul. It's a polished, modern documentation site right away: dark mode, responsive layout, GitHub integration, structured parameter tables, and source links. Whether your package exposes a handful of functions or a deep class hierarchy, Great Docs figures out how to present it well.

## Explore a World of Possibilities

When you're ready for more, there's a lot here:

- Narrative user guides and tutorials alongside your API reference
- Blogs, recipe sections, custom pages, and additional content sections
- Diagrams, videos, color swatches, and interactive table previews
- Gradient themes, announcement banners, and custom branding
- Internationalization across twenty-three languages

Every feature is opt-in. Your site stays clean until you decide to expand it.

## Go as Deep as You Need

As your project grows, Great Docs keeps up. Publish multiple versions with a version selector. Track API changes across releases. Run the built-in link checker, linter, and proofreader. Generate `llms.txt` for AI tools. Deploy to GitHub Pages in one step.

We keep on building the tools you'll need, and they'll be here when the time is right for you.

## What You'll Learn

This User Guide covers everything you need to know to build and maintain great documentation sites. Here's what to expect:

**Getting started**: Installing Great Docs, creating your first site, authoring `.qmd` files, writing effective docstrings, and understanding the project structure.

**Configuration and theming**: Tuning site behavior through `great-docs.yml`, customizing appearance, setting up cross-references, internationalization, and responsive scaling.

**Site content**: Auto-generated API and CLI references, narrative user guides, custom sections and static pages, blogs, diagrams, videos, tables, color swatches, and more.

**Building and deployment**: Previewing locally, publishing to GitHub Pages, SEO optimization, social cards, and multi-version documentation.

**Quality and maintenance**: Link checking, proofreading, linting, changelogs, community files, page status badges, and tracking API evolution.

## Next Steps

This User Guide covers everything from first install to production deployment. Start at the beginning or jump to whatever topic you need.

- [Installation](installation.qmd) gets Great Docs and Quarto set up on your machine
- [Quick Start](quickstart.qmd) walks you through creating your first documentation site
- [Authoring QMD Files](authoring-qmd-files.qmd) teaches the Markdown, frontmatter, and Quarto features you'll use everywhere


# Installation

This guide covers how to install Great Docs and its prerequisites.

## Prerequisites

Before installing Great Docs, ensure you have:

- **Python 3.11 or later**
- **Quarto** – The publishing system that renders your documentation

### Installing Quarto

Great Docs uses Quarto to render documentation. Install it from
[quarto.org](https://quarto.org/docs/get-started/):

::: {.panel-tabset}

## macOS

```{.bash filename="Terminal"}
# Using Homebrew
brew install quarto

# Or download the installer from quarto.org
```

::: {.details summary="SVG generation is not working"}
Please confirm the successful import via

```{.python filename="Python"}
import cairosvg
```

If `cairosvg` is installed but the required libraries still cannot be found, add the brew dynamic
library to your terminal environment by running:

```{.bash filename="Terminal"}
echo 'export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_FALLBACK_LIBRARY_PATH"' >> ~/.zshrc
```

:::

## Linux

```{.bash filename="Terminal"}
# Download and install the .deb package (Ubuntu/Debian)
# Get the latest release URL from https://quarto.org/docs/get-started/
wget <quarto-release-url>.deb
sudo dpkg -i <quarto-release-filename>.deb

# Or use your package manager
```

## Windows

Download and run the installer from [quarto.org](https://quarto.org/docs/get-started/).

:::

Verify the installation:

```{.bash filename="Terminal"}
quarto --version
```

## Installing Great Docs

### From PyPI

The simplest way to install Great Docs:

```{.bash filename="Terminal"}
pip install great-docs
```

### From GitHub

Install the latest development version directly from GitHub:

```{.bash filename="Terminal"}
pip install git+https://github.com/posit-dev/great-docs.git
```

Or install a specific version:

```{.bash filename="Terminal"}
# Install from a specific branch
pip install git+https://github.com/posit-dev/great-docs.git@main

# Install from a specific tag
pip install git+https://github.com/posit-dev/great-docs.git@v0.1.0
```

### Development Installation

For contributing to Great Docs or testing the latest features:

```{.bash filename="Terminal"}
# Clone the repository
git clone https://github.com/posit-dev/great-docs.git
cd great-docs

# Install in editable mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"
```

## Verify Installation

After installation, verify everything is working:

```{.bash filename="Terminal"}
# Check Great Docs version
great-docs --help

# Check Quarto version
quarto --version
```

You should see the Great Docs help message and the Quarto version number.

## Upgrading Great Docs

When a new version of Great Docs is released, upgrade using the same tool you used to install it:

::: {.panel-tabset}

## pip

```{.bash filename="Terminal"}
pip install --upgrade great-docs
```

## uv

```{.bash filename="Terminal"}
uv pip install --upgrade great-docs
```

If Great Docs is declared in your `pyproject.toml` dependencies, update the version constraint there
and run `uv sync` instead.

## pipx

```{.bash filename="Terminal"}
pipx upgrade great-docs
```

:::

### After upgrading

1. **Verify the new version**

   ```{.bash filename="Terminal"}
   great-docs --version
   ```

2. **Review the changelog** — Check the
   [release notes](https://github.com/posit-dev/great-docs/releases) for breaking changes,
   new configuration options, or deprecated features that may affect your site.

3. **Rebuild your site** — Run `great-docs build` to pick up any changes in the build pipeline,
   templates, or default configuration.

::: {.callout-tip}
You do **not** need to re-execute user guide notebooks after upgrading. A plain `great-docs build`
is sufficient as it regenerates reference pages and templates without re-running notebook code
(which can be time-consuming).
:::

## Next Steps

With Great Docs and Quarto installed, you're ready to generate your first documentation site.

- [Quick Start](quickstart.qmd) walks you through `great-docs init` and `great-docs build`
- [Configuration](configuration.qmd) covers customizing behavior through `great-docs.yml`


# Quick Start

This guide walks you through creating your first documentation site with Great Docs in just a few
minutes.

## Initialize Your Documentation

Make sure you've [installed Great Docs](installation.qmd) first, then navigate to your Python
project's root directory and run:

```{.bash filename="Terminal"}
great-docs init
```

You only need to run this **once**. It creates `great-docs.yml` with sensible defaults. After that,
`great-docs build` is the only command you need.

Great Docs will automatically:

1. **Find your package**: Auto-detects your package name from `pyproject.toml`, `setup.cfg`,
`setup.py`, or directory structure
2. **Discover your API**: Finds all public classes, functions, and methods
3. **Create configuration**: Generates `great-docs.yml` with your API structure
4. **Update .gitignore**: Optionally adds `great-docs/` to exclude build artifacts

You'll see output like this:

```{.default filename="Terminal output"}
Initializing great-docs...
Detecting docstring style...
Detected numpy docstring style
Found package __init__.py at: my_package/__init__.py
Using __all__ with 15 exports
Auto-excluding 3 item(s): cli, main, version
Categorizing API objects...
MyClass: class with 8 public methods
Testing dynamic introspection mode...
Dynamic introspection mode works for this package
Generated 2 section(s) from reference config
Created /path/to/project/great-docs.yml

The great-docs/ directory is ephemeral and should not be committed to git.
Add 'great-docs/' to .gitignore? [Y/n]: Y
✅ Updated .gitignore to exclude great-docs/ directory

✅ Great Docs initialization complete!

Next steps:
1. Review great-docs.yml to customize your API reference structure
   (Reorder items, add sections, set 'members: false' to exclude methods)
2. Run `great-docs build` to generate and build your documentation site
3. Run `great-docs preview` to view the site locally

Other helpful commands:
  great-docs scan           # Preview API organization
  great-docs build --watch  # Watch for changes and rebuild
```

::: {.callout-note}
## Configuration File

The `great-docs.yml` file contains your API structure and is **committed to git**. The `great-docs/`
build directory is **ephemeral** and should be gitignored.
:::

## Customize Your Configuration

Open `great-docs.yml` and tailor it to your project. Organize API sections, add authors or funding
info, set a `display_name`, add a `user_guide` directory, etc. See
[Configuration](configuration.qmd) for all available options.

## Build Your Documentation

Build (and rebuild) your docs with:

```{.bash filename="Terminal"}
great-docs build
```

This is the only command you need day-to-day and in CI. It prepares the build directory,
configures the API reference, generates supporting files (LLM indexes, source links, changelogs),
processes your user guide and custom pages, generates API reference pages, and runs Quarto to render
the final HTML site. The output shows each step with its status and timing:

```{.default filename="Build output (abbreviated)"}
━━ Step  1/19 ─ Prepare build directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] great-docs/ ready                                                <0.1s

━━ Step  2/19 ─ Configure API reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] 2 section(s), 15 item(s)                                           1.2s
   ...

━━ Step 17/19 ─ Build site with Quarto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] quarto render                                                     28.4s

━━ Step 18/19 ─ Post-render processing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] Version assembly complete                                        <0.1s

━━ Step 19/19 ─ Generate SEO files ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      Generated sitemap.xml with 120 URLs
      Generated robots.txt
   [OK] sitemap.xml + robots.txt                                          <0.1s

==============================================================================
|  [OK] Build complete — 19/19 steps                                         |
|  Total time: 35.6s                                                         |
|                                                                            |
|  🎉 Site ready →                                                           |
|     /path/to/project/great-docs/_site/index.html                           |
==============================================================================
```

The built site is in `great-docs/_site/`.

::: {.callout-tip}
## Images in README.md

If your README contains images with relative paths (like `![](images/screenshot.png)`), they will be
copied to the build directory automatically. For the most portable setup (working in both GitHub and
your docs site) place images in the `assets/` directory at your project root.
:::

::: {.callout-tip}
## Ephemeral Build Directory

The `great-docs/` directory is created fresh on each build. You can safely delete it between builds
(it will be recreated from `great-docs.yml` and your source files).
:::

## Preview Locally

To preview your documentation with live reload:

```{.bash filename="Terminal"}
great-docs preview
```

This starts a local server and opens your browser. Changes to your documentation files trigger
automatic rebuilds.

## Project Structure

After initialization and your first build, your project will have:

```{.default filename="Project structure"}
your-project/
├── great-docs.yml           # Configuration (committed to git)
├── great-docs/              # Build directory (gitignored, ephemeral)
│   ├── _quarto.yml          # Generated Quarto config
│   ├── index.qmd            # Landing page (from README.md)
│   ├── great-docs.scss      # Styling
│   ├── github-widget.js     # GitHub stars widget
│   ├── sidebar-filter.js    # API search filter
│   ├── llms.txt             # LLM-friendly docs index
│   ├── llms-full.txt        # Full API docs for LLMs
│   ├── _source_links.json   # Source code links
│   ├── reference/           # API reference pages (generated)
│   │   ├── index.qmd
│   │   ├── MyClass.qmd
│   │   └── ...
│   ├── user-guide/          # Copied from user_guide/
│   ├── scripts/
│   │   └── post-render.py   # HTML post-processing
│   └── _site/               # Built HTML site
│       ├── index.html
│       └── ...
├── user_guide/              # Your narrative docs (optional)
│   ├── 01-installation.qmd
│   └── ...
├── pyproject.toml
├── README.md
└── your_package/
    └── ...
```

::: {.callout-important}
## What to Commit

- ✅ `great-docs.yml` – Your configuration
- ✅ `user_guide/` – Your narrative documentation
- ✅ `README.md` – Your project readme
- ❌ `great-docs/` – Ephemeral build directory (gitignored)
:::

## Scan Your API

Before (or after) running `init`, you can use `great-docs scan` to preview what Great Docs
discovered in your package. It shows every public class, function, constant, and enum, along with
whether each item appears in your `great-docs.yml` reference config:

```{.bash filename="Terminal"}
great-docs scan            # Show discovered exports
great-docs scan --verbose  # Include method names for each class
```

This is useful for auditing your configuration: items marked `[x]` are included in your docs,
while `[ ]` items are not. You can then add or remove entries in `great-docs.yml` accordingly.

## Command Options

### Initialize Options

```{.bash filename="Terminal"}
# Initialize a different project
great-docs init --project-path /path/to/project

# Reset config to fresh defaults (deletes existing great-docs.yml)
great-docs init --force
```

::: {.callout-warning}
## --force Starts From Scratch

`great-docs init --force` **deletes** your existing `great-docs.yml`
and generates a brand-new default config. Any customizations you made
(authors, sections, display_name, etc.) will be lost. Only use this if
you genuinely want to reset.
:::

### Build Options

```{.bash filename="Terminal"}
# Skip API re-discovery for faster rebuilds
great-docs build --no-refresh

# Watch for file changes and rebuild automatically
great-docs build --watch

# Build only specific versions (multi-version sites)
great-docs build --versions 0.3,dev

# Build only the latest version (skip historical)
great-docs build --latest-only
```

### Preview Options

```{.bash filename="Terminal"}
# Preview on the default port (3000)
great-docs preview

# Use a different port
great-docs preview --port 8080
```

## Using the Python API

You can also use Great Docs programmatically:

```{.python filename="Python"}
from great_docs import GreatDocs

# Initialize for current directory
docs = GreatDocs()
docs.install()

# Build documentation
docs.build()

# Preview documentation
docs.preview()

# Or initialize for a specific project
docs = GreatDocs(project_path="/path/to/project")
docs.install()
docs.build()
```

## Next Steps

Your documentation site is ready! If you're new to writing `.qmd` files, head to the
[Authoring QMD Files](authoring-qmd-files.qmd) guide for a thorough introduction to Markdown,
frontmatter, callouts, tabsets, and all the other building blocks available to you.

- [Authoring QMD Files](authoring-qmd-files.qmd) covers Markdown, frontmatter, callouts, and other building blocks
- [Configuration](configuration.qmd) covers customizing Great Docs behavior
- [API Documentation](api-documentation.qmd) explains how API discovery works
- [CLI Documentation](cli-documentation.qmd) covers Click CLI documentation
- [User Guides](user-guides.qmd) explains how to add narrative documentation
- [Deployment](deployment.qmd) covers publishing to GitHub Pages


# Authoring QMD Files

Great Docs sites are built from **`.qmd` files** (Quarto Markdown). If you've written Markdown
before, you're already most of the way there. The `.qmd` format extends standard Markdown with YAML
frontmatter, executable code blocks, cross-references, callouts, and more. This page teaches you
everything you need to write rich documentation pages.

## What Is a `.qmd` File?

A `.qmd` file is a plain-text file with three parts:

1. **YAML frontmatter**: metadata at the top of the file, enclosed in `---` fences
2. **Markdown body**: the content of the page, written in Markdown
3. **Optional executable code**: code blocks that Quarto can run and embed output from

Here's the simplest possible `.qmd` file:

```{.yaml filename="my-page.qmd"}
---
title: "My Page"
---

This is a documentation page.
```

When Great Docs builds the site, Quarto converts each `.qmd` file into a styled HTML page with
navigation, search, and theming applied automatically.

Understanding this three-part structure is all you need to start writing pages. The rest of this
guide explores each part in detail so you can take full advantage of `.qmd` capabilities.

## Where You'll Use This

As you build out your documentation site, you'll author `.qmd` files in several contexts:

- **User Guide pages**: narrative documentation such as tutorials, installation instructions, and
  conceptual explanations (see [User Guides](user-guides.qmd))
- **Custom sections**: additional page groups like examples, tutorials, FAQs, or cookbooks that you
  define in `great-docs.yml` (see [Custom Sections](custom-sections.qmd))
- **Blog posts**: time-stamped articles for announcements, release notes, or technical deep dives
  (see [Blog](blog.qmd))

All of these use the same Markdown syntax, frontmatter, callouts, tabsets, and other features
covered on this page. Once you learn the authoring basics here, they transfer directly to every
part of your site.

::: {.callout-tip}
## Docstrings Are Markdown Too
Much of what you learn here also applies to writing Python docstrings. Great Docs renders
docstrings through Quarto, so formatting like **bold**, `inline code`, lists, tables, and even
callouts works inside your docstrings as well. You can even embed executable code cells in
docstrings, which means your API examples can display rich outputs (tables, plots, and more) right
on the reference page. See [Writing Docstrings](writing-docstrings.qmd) for the full guide on
structuring docstrings for Great Docs.
:::

## YAML Frontmatter

Every `.qmd` file starts with a YAML block delimited by `---` lines. This block sets metadata that
controls how the page is rendered and where it appears in navigation. Think of it as the control
panel for the page: it never appears in the body text, but it shapes everything about how the page
looks and behaves.

### Required Fields

At minimum, a page needs a `title`:

```yaml
---
title: "Installation Guide"
---
```

For User Guide pages, you'll also want `guide-section` to control sidebar grouping:

```yaml
---
title: "Installation Guide"
guide-section: "Getting Started"
---
```

The `title` becomes both the page heading and the label readers see in sidebar navigation, so make
it concise and descriptive.

### Common Frontmatter Fields

| Field | Purpose | Example |
|-------|---------|---------|
| `title` | Page heading and sidebar label | `"Quick Start"` |
| `guide-section` | Sidebar section grouping | `"Getting Started"` |
| `tags` | Page tags for filtering and discovery | `[Setup, Configuration]` |
| `toc` | Show table of contents | `true` (default) |
| `toc-depth` | Max heading depth in the TOC | `3` |

The **Table of Contents** (TOC) is the "On this page" sidebar that appears on the right side of
every page. It lists the headings on the current page as clickable links, letting readers jump
directly to the section they need. By default the TOC is enabled and shows headings down to level 3
(i.e., `##` and `###`). Setting `toc-depth: 2` would limit it to only `##` headings, making the
sidebar shorter for pages with many subsections. Setting `toc: false` hides it entirely, which can
be useful for very short pages that don't benefit from a navigation outline.

These fields give you fine-grained control over each page's behavior without changing its content.

### YAML Syntax Essentials

YAML is whitespace-sensitive. Here are the patterns you'll use most:

```yaml
---
# Strings (quotes optional unless the value contains special characters)
title: "My Title"
guide-section: Getting Started

# Booleans
toc: true

# Lists (two equivalent forms)
tags: [Setup, Config]
tags:
  - Setup
  - Config
---
```

::: {.callout-warning}
## Indentation Matters
YAML uses spaces, never tabs. Inconsistent indentation will cause a build error. Use 2 spaces per
indent level.
:::

You won't need deep YAML knowledge for most pages. The patterns above cover the vast majority of
frontmatter you'll write. When in doubt, copy the frontmatter from an existing page and adjust the
values.

## Markdown Fundamentals

The body of a `.qmd` file is written in Markdown, a lightweight markup language designed to be readable
as plain text while converting cleanly to HTML. If you've never used Markdown, this section covers
everything you need to start writing documentation.

### Headings

Use `#` characters to create headings. The number of `#` symbols determines the level:

```markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
```

In a `.qmd` file, the `title` in frontmatter is the page's top-level heading, so your body content
typically starts at `##`:

```{.markdown filename="my-page.qmd"}
---
title: "Configuration"
---

## Basic Settings

Content here...

### Database Options

More content...
```

Headings automatically appear in the Table of Contents sidebar and serve as anchor targets for
linking. Choose heading levels to reflect the logical structure of your content. Don't skip levels
(e.g., jumping from `##` to `####`) as this breaks the outline hierarchy.

### Paragraphs and Line Breaks

Paragraphs are separated by blank lines. For example, the following Markdown source:

```markdown
This is the first paragraph. It can span
multiple lines in the source file and will
be rendered as a single flowing paragraph.

This is a second paragraph.
```

...renders as two paragraphs, with the line breaks within the first paragraph collapsed into spaces.

### Emphasis and Formatting

Markdown provides several ways to emphasize text. Here's the syntax alongside what it produces:

| Syntax | Result | Use For |
|--------|--------|---------|
| `*italic*` or `_italic_` | *italic* | Introducing terms, emphasis |
| `**bold**` or `__bold__` | **bold** | Strong emphasis, important terms |
| `***bold italic***` | ***bold italic*** | Rare, combined emphasis |
| `` `code` `` | `code` | Function names, variables, file paths |
| `~~strikethrough~~` | ~~strikethrough~~ | Deprecated or removed content |

Here's a live example: writing `**Great Docs** makes it *easy* to document your ~~old~~ package`
produces the following: **Great Docs** makes it *easy* to document your ~~old~~ package.

Use emphasis purposefully. Bold works well for key terms on first introduction, italic for slight
emphasis, and inline code for anything a programmer would type. Overusing emphasis dilutes its
effect and makes prose harder to scan.

### Lists

**Unordered lists** use `-`, `*`, or `+`. The syntax:

```markdown
- First item
- Second item
  - Nested item (indent 2 spaces)
  - Another nested item
- Third item
```

Renders as:

- First item
- Second item
  - Nested item (indent 2 spaces)
  - Another nested item
- Third item

**Ordered lists** use numbers followed by a period:

```markdown
1. First step
2. Second step
3. Third step
```

Which produces:

1. First step
2. Second step
3. Third step

The actual numbers don't matter because Markdown renumbers them automatically. Writing `1.` for
every item is a common shorthand that keeps diffs clean when you reorder items.

**Definition lists** pair a term with its definition:

```markdown
Term
: Definition of the term.

Another term
: Its definition.
```

This renders as:

Term
: Definition of the term.

Another term
: Its definition.

Lists are one of the most effective tools for organizing information. Use unordered lists for
collections where order doesn't matter, ordered lists for sequences and procedures, and definition
lists for glossaries or option descriptions.

### Links

Most common are inline links, where you would put the URL right next to the text:

```markdown
Visit [Quarto's website](https://quarto.org) for more.
```

This renders as: Visit [Quarto's website](https://quarto.org) for more.

For links to other pages in your documentation, use relative paths:

```markdown
See the [Configuration](configuration.qmd) page.
```

This renders as: See the [Configuration](configuration.qmd) page.

Liberal cross-linking between pages helps readers navigate your documentation. Reference-style links
are especially handy when the same URL appears multiple times or when long URLs would clutter your
prose.

### Images

The basic syntax is:

```markdown
![Alt text describing the image](images/screenshot.png)
```

For more control over sizing and layout, use Quarto's figure syntax:

```markdown
![A descriptive caption](images/diagram.png){width=80% fig-align="center"}
```

The attributes in curly braces let you set width, height, alignment, and more. Always include
meaningful alt text for accessibility. Screen readers rely on it, and it also displays as a
placeholder if the image fails to load.

Images and diagrams break up walls of text and can communicate complex ideas far more efficiently
than prose. Store images in a subdirectory (e.g., `images/`) to keep your project organized.

### Blockquotes

Prefix lines with `>` to create blockquotes:

```markdown
> Documentation is a love letter that you write to your future self.
>
> — Damian Conway
```

This renders as:

> Documentation is a love letter that you write to your future self.
>
> — Damian Conway

Blockquotes work well for attributing quotes, reproducing terminal output in narrative context, or
visually setting apart a passage that you're commenting on.

### Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line create a visual divider:

```markdown
***
```

Which renders as a horizontal line:

***

::: {.callout-note}
Because `---` is also used for YAML frontmatter fences, it's safest to use `***` or `___` for
horizontal rules in the body of your document to avoid any ambiguity.
:::

Horizontal rules are useful for separating thematically distinct sections within a page when a
heading would be too heavy-handed.

### Tables

Use pipes and hyphens to create tables:

```markdown
| Feature    | Status      |
|------------|-------------|
| Dark mode  | Supported   |
| Search     | Built-in    |
| Mobile     | Responsive  |
```

This renders as:

| Feature    | Status      |
|------------|-------------|
| Dark mode  | Supported   |
| Search     | Built-in    |
| Mobile     | Responsive  |

Control column alignment with colons in the separator row:

```markdown
| Left       | Center      | Right       |
|:-----------|:-----------:|------------:|
| aligned    | aligned     | aligned     |
```

Which produces:

| Left       | Center      | Right       |
|:-----------|:-----------:|------------:|
| aligned    | aligned     | aligned     |

For tables with long content, the pipes don't need to line up perfectly. Markdown is forgiving about
column widths in the source.

Tables are the best way to present structured comparisons, option listings, and reference data.
They're much easier to scan than the equivalent information written as prose.

Taken together, the Markdown fundamentals covered in this section are enough to write clear,
well-structured documentation pages. The remaining sections introduce Quarto-specific features that
take your pages further.

## Code Blocks

Code blocks are essential for technical documentation. Quarto offers several forms, each suited to
different purposes: from showing syntax-highlighted snippets to running live code and embedding its
output.

### Fenced Code Blocks

Wrap code in triple backticks. Specify the language after the opening fence for syntax highlighting:

````markdown
```python
import great_docs

docs = great_docs.GreatDocs()
docs.build()
```
````

This renders with full syntax highlighting:

```python
import great_docs

docs = great_docs.GreatDocs()
docs.build()
```

Quarto supports syntax highlighting for many languages: `python`, `javascript`, `typescript`, `r`,
`bash`, `yaml`, `toml`, `json`, `html`, `css`, `sql`, `rust`, `go`, `java`, `cpp`, and more.

Syntax highlighting makes code dramatically easier to read by visually distinguishing keywords,
strings, comments, and other language elements. Always specify the language tag. There's no reason
to show unhighlighted code.

### Code Block Options

Add a filename label to give readers context about where the code belongs:

````markdown
```{.python filename="build.py"}
from great_docs import GreatDocs

docs = GreatDocs()
docs.build()
```
````

This renders as:

```{.python filename="build.py"}
from great_docs import GreatDocs

docs = GreatDocs()
docs.build()
```

The `.python` syntax (with the dot prefix) is Quarto's way of specifying syntax highlighting for
non-executable blocks. It's equivalent to plain `python` but allows you to add attributes like
`filename`.

Filename labels are a small touch that adds important context. They tell readers *where* a piece of
code lives, which is especially valuable in tutorials that span multiple files.

### Executable Code Blocks

Use curly braces around the language name to make a code block executable. Quarto will run the code
and embed the output directly in the page:

````markdown
```{{python}}
import pandas as pd

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
df
```
````

Here's that same block running live:

```{python}
import pandas as pd

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
df
```

Control execution with hash-pipe (`#|`) options. For example, the following block hides its source
code and produces only the figure output with a caption:

````markdown
```{{python}}
#| echo: false
#| fig-cap: "A simple plotnine chart"

from plotnine import ggplot, aes, geom_col, theme_minimal, labs
import pandas as pd

df = pd.DataFrame({"category": ["A", "B", "C", "D"], "value": [4, 7, 3, 8]})

(
    ggplot(df, aes(x="category", y="value"))
    + geom_col(fill="#4682B4")
    + theme_minimal()
    + labs(x="Category", y="Value")
)
```
````

And here it is rendered (notice only the plot appears because `echo: false` hides the code):

```{python}
#| echo: false
#| fig-cap: "A simple plotnine chart"

from plotnine import ggplot, aes, geom_col, theme_minimal, labs
import pandas as pd

df = pd.DataFrame({"category": ["A", "B", "C", "D"], "value": [4, 7, 3, 8]})

(
    ggplot(df, aes(x="category", y="value"))
    + geom_col(fill="#4682B4")
    + theme_minimal()
    + labs(x="Category", y="Value")
)
```

Common hash-pipe options:

| Option | Effect |
|--------|--------|
| `#| echo: false` | Hide the source code, show only output |
| `#| eval: false` | Show the code but don't run it |
| `#| output: false` | Run the code but hide the output |
| `#| warning: false` | Suppress warning messages |
| `#| fig-cap: "..."` | Add a caption to figure output |
| `#| label: fig-name` | Create a referenceable label for the figure |
| `#| output-title: "..."` | Wrap the output in a labelled container |
| `#| output-frame: true` | Wrap the output in a bordered container (no title) |
| `#| source-code: mock` | Display one code block but execute another (see below) |

Executable code blocks are what make `.qmd` files more powerful than plain Markdown. They ensure
that your documentation's code examples are always tested: if the code breaks, the build fails, so
your docs stay in sync with your actual API.

### Output Titles and Frames

Cell output can be wrapped in a styled container using `#| output-title` and `#| output-frame`.
These options work on any executable code cell and compose with `source-code: mock`.

**Adding a title.** Use `#| output-title` to wrap output in a bordered container with a label
displayed above it. This is useful for marking chat responses, returned values, or any output that
benefits from a heading:

````markdown
```{{python}}
#| output-title: "Response"
chat.chat("Tell me a joke.")
```
````

**Adding a frame without a title.** Use `#| output-frame: true` to wrap output in a bordered
container *without* a title label. This gives text-based output visual containment that it doesn't
normally have:

````markdown
```{{python}}
#| output-frame: true
from mypackage import greet
greet("World")
```
````

**Rich HTML outputs.** When the output is a rich HTML object (such as a GT table or a styled
DataFrame), the frame is automatically removed to avoid a double-border (these objects already
carry their own visual structure). With `output-title`, the title appears as a floating label above
the output; with `output-frame`, the container is effectively invisible since the object supplies
its own styling.

**Composing with mock cells.** Both `output-title` and `output-frame` work naturally with
`source-code: mock`. The title or frame applies to the eval cell's output:

````markdown
```{{python}}
#| source-code: mock
#| output-title: "Response"
chat.chat("I need your help.")
# ---
chat.chat("I need your help.", debug=True, header=False)
```
````

### Mocked Code Cells

Sometimes you need the code the reader *sees* to differ from the code that actually *runs*. Common
reasons include:

- an output requires a debug parameter that shouldn't be shown
- the displayed code uses simplified imports
- you want to hide boilerplate setup

Normally this requires two separate code cells: one for display (`eval: false`) and one for
execution (`echo: false`). The `source-code: mock` option collapses these into a single cell.

Place `#| source-code: mock` at the top and separate the display code from the eval code with a
`# ---` delimiter:

````markdown
```{{python}}
#| source-code: mock
import chatlas as ctl

chat = ctl.ChatOpenAI()
chat.chat("I need your help.")
# ---
import chatlas as ctl
chat = ctl.ChatOpenAI(debug=True)
chat.chat("I need your help.", header=False)
```
````

The reader sees only the clean code above `# ---`, while the code below `# ---` runs and produces
the output. Other hash-pipe options (`output-title`, `output-frame`, `warning`, etc.) compose
naturally (see [Output Titles and Frames] above for examples).

**Edge cases:**

- **No delimiter**: the entire cell is display-only (equivalent to `eval: false`)
- **Multiple `# ---`**: only the first one splits; subsequent ones are part of the eval code
- **Empty eval section**: display-only cell (no output produced)

### Inline Code

Use single backticks for inline code. For example, writing `` The `build()` method generates the
HTML output `` renders as: The `build()` method generates the HTML output.

Inline code is the workhorse of technical writing. Use it every time you mention a function name,
variable, command, file path, or any other literal value. It tells readers "this is something you'd
type, not just a word in a sentence".

Code blocks, whether static or executable, are the backbone of any technical documentation page.
They let you show readers exactly what to type and exactly what to expect.

## Callouts

Callouts are colored boxes that draw attention to important information. They stand out from the
surrounding prose, making them impossible to miss. Quarto provides five built-in types, each with a
distinct color and icon:

```markdown
::: {.callout-note}
Supplementary information that adds context.
:::
```

Here are all five types rendered live:

::: {.callout-note}
Supplementary information that adds context. Use notes for background details, clarifications, or
"good to know" asides.
:::

::: {.callout-tip}
A helpful suggestion or best practice. Use tips for workflow shortcuts, performance advice, or
recommended approaches.
:::

::: {.callout-warning}
Something the reader should be careful about. Use warnings for common mistakes, breaking changes, or
compatibility issues.
:::

::: {.callout-important}
Critical information the reader must not miss. Use important callouts for security considerations,
data integrity, or required prerequisites.
:::

::: {.callout-caution}
Potential for data loss or irreversible actions. Use caution callouts for destructive operations,
production deployments, or anything that can't be undone.
:::

### Callouts with Titles

Add a heading inside the callout to give it a custom title:

```markdown
::: {.callout-tip}
## Pro Tip
You can chain `great-docs init` and `great-docs build` in CI.
:::
```

This renders as:

::: {.callout-tip}
## Pro Tip
You can chain `great-docs init` and `great-docs build` in CI.
:::

Custom titles let you summarize the callout's message at a glance, which is especially helpful when
a page has several callouts.

### Collapsible Callouts

Add `collapse="true"` to make a callout collapsible (readers click to expand):

```markdown
::: {.callout-note collapse="true"}
## Click to expand
This content is hidden by default.
:::
```

This renders as:

::: {.callout-note collapse="true"}
## Click to expand
This content is hidden by default. Collapsible callouts are perfect for supplementary details that
most readers can skip, like lengthy configuration examples or edge-case explanations.
:::

Collapsible callouts keep pages scannable by hiding secondary detail behind a click. They're ideal
for verbose examples, troubleshooting steps, or background context that would otherwise interrupt
the flow.

Callouts are one of the most effective tools for guiding readers through your documentation. Use
them to flag what matters, but use them sparingly. If everything is highlighted, nothing stands out.

## Tabsets

Tabsets present alternative content in switchable tabs. They're perfect for showing
platform-specific instructions or code in multiple languages without cluttering the page with
content most readers will skip:

````markdown
::: {.panel-tabset}

## pip

```bash
pip install great-docs
```

## conda

```bash
conda install great-docs
```

## pipx

```bash
pipx install great-docs
```

:::
````

This renders as a set of clickable tabs:

::: {.panel-tabset}

## pip

```bash
pip install great-docs
```

## conda

```bash
conda install great-docs
```

## pipx

```bash
pipx install great-docs
```

:::

Each `##` heading inside the `::: {.panel-tabset}` block becomes a tab label. Readers click tabs to
switch content (no page reload needed).

Tabsets solve a common documentation problem: when you need to present the same information in
multiple variants (different operating systems, package managers, programming languages, or
framework versions), tabs keep all variants accessible without forcing readers to scroll past the
ones they don't need.

## Divs and Spans

Quarto uses a fenced div syntax (borrowed from Pandoc) to apply classes and attributes to blocks of
content. The `:::` fences you've already seen in callouts and tabsets are examples of divs. This
section covers the general mechanism so you can use it for layout and styling beyond those built-in
features.

### Fenced Divs

Wrap content in `:::` with a class name:

```markdown
::: {.border}
This content has a border around it.
:::
```

This renders as:

::: {.border}
This content has a border around it.
:::

Nest divs by using more colons on the outer fence:

```markdown
:::: {.columns}

::: {.column width="50%"}
Left column content.
:::

::: {.column width="50%"}
Right column content.
:::

::::
```

This renders as:

:::: {.columns}

::: {.column width="50%"}
**Left column**: content placed here appears on the left half of the page.
:::

::: {.column width="50%"}
**Right column**: content placed here appears on the right half of the page.
:::

::::

Fenced divs give you a structural building block for any layout that Markdown alone can't express.
Because they're plain text, they stay readable in source and don't require writing raw HTML.

### Spans

Apply classes to inline content with square brackets and curly braces:

```markdown
This is [important text]{.text-danger} in a sentence.
```

This renders as: This is [important text]{.text-danger} in a sentence.

Spans are the inline counterpart to divs. Use them when you need to style or annotate a word or
phrase without affecting the surrounding block.

Divs and spans together give you a complete system for applying structure and styling at any
granularity, from full-page layouts down to individual words, all without leaving Markdown.

## Cross-References

Cross-references let you link to specific figures, tables, sections, and other elements by label.
Unlike plain links that break when content moves, cross-references resolve by label during the
build, so they stay valid as your documentation evolves.

### Linking to Sections

Any heading can be referenced by its auto-generated ID (lowercase, hyphens for spaces):

```markdown
See [YAML Frontmatter](#yaml-frontmatter) above.
```

This renders as: See [YAML Frontmatter](#yaml-frontmatter) above.

Section links are the simplest form of cross-reference. They help readers jump to related content
within the same page without scrolling.

### Linking to Figures

Label a figure with `#fig-` prefix and reference it:

````markdown
```{{python}}
#| label: fig-revenue
#| fig-cap: "Quarterly revenue"

import matplotlib.pyplot as plt
plt.plot([1, 2, 3, 4], [10, 15, 13, 17])
plt.show()
```

As shown in @fig-revenue, revenue grew steadily.
````

The `@fig-revenue` syntax creates a numbered link like "Figure 1" that stays correct even if you add
more figures. This means you never have to manually update figure numbers; Quarto handles the
bookkeeping.

### Linking to Other Pages

Use relative paths for links within your documentation:

```markdown
See the [Configuration](configuration.qmd) guide for all options.

For API details, see the [GreatDocs](../reference/GreatDocs.qmd) class.
```

These links are validated during the build, so broken references are caught before your site goes
live.

Cross-references are essential for any documentation longer than a single page. They weave your
pages into a connected whole, letting readers follow their own path through the material.

## Layout and Columns

Quarto supports multi-column layouts for side-by-side content. This is useful for comparisons,
before/after examples, or pairing explanatory text with a visual:

```markdown
:::: {.columns}

::: {.column width="40%"}
### Input
Raw Markdown text goes here.
:::

::: {.column width="60%"}
### Output
The rendered result appears here.
:::

::::
```

This renders as:

:::: {.columns}

::: {.column width="40%"}
**Input**: the left column holds source text or code.
:::

::: {.column width="60%"}
**Output**: the right column holds the rendered result or a larger visual.
:::

::::

You can also use the `layout` attribute on figures for grid arrangements:

````markdown
::: {layout-ncol=2}
![First image](images/one.png)

![Second image](images/two.png)
:::
````

Multi-column layouts let you use horizontal space effectively. They're particularly valuable for
tutorials where readers benefit from seeing input and output side by side, or for image galleries
that would waste space displayed one-per-row.

## Includes

Break large pages into smaller, reusable pieces with the `include` shortcode:

````markdown
{{{< include _shared-setup.qmd >}}}
````

This inserts the contents of `_shared-setup.qmd` directly into the page at build time. By
convention, included files start with `_` to indicate they aren't standalone pages.

Includes are useful for:

- Shared preambles or setup instructions across multiple pages
- Reusable admonitions or disclaimers
- Content that appears in both the User Guide and README

Includes promote the "write once, use everywhere" principle. When a paragraph or setup block appears
in multiple pages, extracting it into an include file means you only need to update it in one place.

### Code Includes

When the `include` shortcode references a code file (anything other than `.qmd` or `.md`), Great
Docs automatically wraps the file contents in a syntax-highlighted code block:

```markdown{shortcodes=false}
{{{< include src/mypackage/examples/demo.py >}}}
```

The language is auto-detected from the file extension. A `.py` file becomes a `python` code block,
a `.js` file becomes `javascript`, and so on. This is the same `include` shortcode used for content
includes above. Great Docs handles code files automatically while passing `.qmd` and `.md` includes
through to Quarto as usual.

Code includes are ideal for keeping documentation in sync with real code. Instead of copying code
snippets into your pages (where they can drift out of date), reference the source files directly.

::: {.callout-note}
Generally, include shortcodes should not be enclosed in code blocks, as the formatting is applied automatically.
:::

#### Including existing source files

If your library already has runnable examples, tests, or configuration files that you want to
showcase in the documentation, point `include` at them directly:

```markdown{shortcodes=false}
{{{< include src/mypackage/examples/usage.py >}}}
{{{< include tests/test_core.py lines="12-30" >}}}
{{{< include pyproject.toml >}}}
```

Because paths are resolved relative to the project root, any file in your repository is reachable.
This is the primary use case: your code examples are real, tested code that stays in sync
automatically. When the source file changes, the documentation updates on the next build with no
manual copying required.

#### Writing new snippets for the docs

When you need purpose-written examples that don't belong in your library's source tree, place them
in an underscore-prefixed subdirectory of your user guide directory (for example,
`user_guide/_includes/` or `user_guide/_snippets/`):

```text
user_guide/
├── _includes/
│   ├── quickstart.py
│   ├── config-example.yaml
│   └── shortcode-demo.qmd
├── 01-introduction.qmd
└── 02-tutorial.qmd
```

Then reference them with a path relative to the user guide directory:

```markdown
{{{< include _includes/quickstart.py >}}}
{{{< include _includes/shortcode-demo.qmd lang="markdown" >}}}
```

This keeps documentation-only snippets close to the pages that use them, separate from the real
source code. You can include `.qmd` files as code too, just add the `lang` or `lines` keyword to
tell Great Docs to wrap the contents in a fenced code block instead of passing it through to Quarto
for rendering.

::: {.callout-important}
## Use underscore-prefixed directories for snippet files

Directories inside `user_guide/` that contain `.qmd` files are normally treated as content
subdirectories. Their `.qmd` files are discovered as user guide pages. A leading underscore
(e.g., `_includes/`, `_snippets/`) tells Great Docs to treat the directory as an **asset
directory** instead: the files are copied to the build output but are not discovered as standalone
pages.

This means you can safely store `.qmd` snippets in `_includes/` without them appearing as pages in
your site navigation. Without the underscore prefix, any `.qmd` files in the directory would either
be picked up as user guide pages or prevent the directory from being copied as an asset directory.

For non-`.qmd` snippet files (`.py`, `.js`, `.yaml`, etc.), the underscore prefix is not strictly
required but using it consistently keeps all your snippet files in one predictable place.
:::

#### Options

**Line ranges**: include only specific lines with the `lines` keyword:

```markdown
{{{< include src/mypackage/core.py lines="10-25" >}}}
```

Line numbers are 1-based and inclusive. This is useful for highlighting a specific function or block
without showing the entire file.

**Language override**: override the auto-detected language with the `lang` keyword:

```markdown
{{{< include config/settings.conf lang="toml" >}}}
```

**Combining options**: both keywords can be used together:

```markdown
{{{< include src/mypackage/core.py lines="5-15" lang="python" >}}}
```

#### Path resolution

File paths are resolved relative to the directory containing the `.qmd` file first, then relative to
the project root. This two-step lookup means you can use whichever style is most natural:

- `_includes/example.py`: relative to the user guide directory (documentation-only snippets)
- `src/mypackage/utils.py`: relative to the project root (existing source files)
- `tests/test_core.py`: any file in the project tree

If the referenced file is not found, a warning comment is inserted in the output so you can catch
broken references during review.

## Math Equations

For technical documentation that involves math, Quarto renders LaTeX equations natively.

**Inline math** uses single dollar signs. For example, `$E = mc^2$` renders as $E = mc^2$.

**Display math** uses double dollar signs for centered, standalone equations:

```markdown
$$
L = \frac{1}{n}\sum_{i=1}^{n}(y_i - \hat{y}_i)^2
$$
```

This renders as:

$$
L = \frac{1}{n}\sum_{i=1}^{n}(y_i - \hat{y}_i)^2
$$

Math rendering uses KaTeX, so most LaTeX math commands are supported, from simple expressions like
$\alpha + \beta$ to complex formulas with fractions, summations, and matrices.

Math support is indispensable for packages that deal with statistics, machine learning, physics, or
any domain where precise notation matters. Equations embedded directly in your docs are more
readable and maintainable than screenshot images of formulas.

## Raw HTML

When Markdown doesn't offer enough control, you can embed raw HTML directly:

```markdown
<details>
<summary>Click to expand</summary>

This content is hidden by default but still written in Markdown.

- List item one
- List item two

</details>
```

This renders as:

<details>
<summary>Click to expand</summary>

This content is hidden by default but still written in Markdown.

- List item one
- List item two

</details>

::: {.callout-note}
Use raw HTML sparingly. Markdown content is portable and easier to maintain. Reserve HTML for cases
where Markdown and Quarto's built-in features can't achieve the layout you need.
:::

Raw HTML is an escape hatch for the rare cases where Markdown's abstractions aren't sufficient. The
`<details>` element shown above is a good example: it creates a native browser disclosure widget
that's simpler than a collapsible callout for short asides.

## Comments

Add comments that don't appear in the rendered output:

```markdown
<!-- This is an HTML comment. It won't be visible on the page. -->

Content visible to readers.

<!-- TODO: Add a diagram here -->
```

Comments are invisible to readers but visible to anyone editing the source file. Use them to leave
notes for yourself or other authors: TODO reminders, explanations of why content is structured a
certain way, or placeholders for sections you plan to fill in later. They're a lightweight
coordination tool that costs nothing in the rendered output.

## Putting It All Together

Here's a realistic User Guide page that combines many of these features:

````{.yaml filename="user_guide/04-getting-started.qmd"}
---
title: "Getting Started"
guide-section: "Tutorials"
tags: [Setup, Tutorial]
---

## Prerequisites

Before you begin, make sure you have:

- Python 3.9 or later
- A Python package with a `pyproject.toml`

::: {.callout-tip}
## Virtual Environments
We recommend using a virtual environment to keep your dependencies isolated.
:::

## Installation

::: {.panel-tabset}

## pip

```bash
pip install great-docs
```

## pipx

```bash
pipx install great-docs
```

:::

## Your First Build

Run these two commands from your project root:

```{.bash filename="Terminal"}
great-docs init
great-docs build
```

The generated site is in `great-docs/_site/`. Open `index.html` to preview it.

## What's Next?

| Topic | Page |
|-------|------|
| Customize settings | [Configuration](configuration.qmd) |
| Add narrative docs | [User Guides](user-guides.qmd) |
| Deploy your site | [Deployment](deployment.qmd) |
````

This example uses frontmatter, a list, a callout, a tabset, a code block with a filename label, and
a table (all features covered on this page). As you write your own pages, mix and match these
building blocks to create documentation that's clear, scannable, and engaging.

## Quick Reference

A compact cheat sheet for the most common `.qmd` authoring patterns:

| Element | Syntax |
|---------|--------|
| Heading | `## My Heading` |
| Bold | `**bold text**` |
| Italic | `*italic text*` |
| Inline code | `` `my_function()` `` |
| Link | `[text](url)` |
| Image | `![alt](path.png)` |
| Unordered list | `- item` |
| Ordered list | `1. item` |
| Code block | ```` ```python ... ``` ```` |
| Executable block | ```` ```{python} ... ``` ```` |
| Callout | `::: {.callout-note} ... :::` |
| Tabset | `::: {.panel-tabset} ... :::` |
| Cross-ref to section | `[Section Name](#section-name)` |
| Cross-ref to figure | `@fig-label` |
| Inline math | `$E = mc^2$` |
| Display math | `$$ ... $$` |
| Include | `{{{< include file.qmd >}}}` |

Keep this table close at hand as you write your first few pages. After a short while, the syntax
becomes second nature.

## Next Steps

The syntax covered here (frontmatter, Markdown, callouts, tabsets, executable code, cross-references) applies everywhere in Great Docs: user guide pages, docstrings, recipes, and custom sections. Once it's second nature, you're well-prepared to dive into any of these topics:

- [Writing Docstrings](writing-docstrings.qmd): structure docstrings with sections, executable examples, and Great Docs directives
- [Configuration](configuration.qmd): customize your site's structure and behavior
- [API Documentation](api-documentation.qmd): how Great Docs discovers and renders your package's API
- [User Guides](user-guides.qmd): organize pages into a multi-page guide with sidebar navigation
- [Cross-Referencing](cross-referencing.qmd): Great Docs' advanced linking system for API symbols


# Writing Docstrings

Your docstrings are the single biggest input to your API reference. Great Docs renders them through
Quarto, which means everything you can do in a `.qmd` file (Markdown formatting, callouts, tables,
executable code cells) also works inside a docstring. A well-written docstring becomes a polished
reference page with almost no extra effort; a thin or poorly structured one leaves your users
guessing.

This page covers how to structure docstrings so that Great Docs can extract the most value from
them: which format to choose, what sections are available, how to embed live examples, and how to
use Great Docs directives to control what gets documented.

## Choosing a Docstring Format

Great Docs supports two widely used docstring conventions: **NumPy style** and **Google style**.
Both produce the same rendered output. The difference is purely syntactic, so pick whichever your
team already uses. If you're starting from scratch, either works well.

When you run `great-docs init`, Great Docs analyzes your existing docstrings and auto-detects the
style. You can override this in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
parser: numpy   # or "google"
```

### NumPy Style

NumPy-style docstrings use underlined section headers. Parameters are listed one per line with the
type on the same line as the name, separated by a colon:

```python
def connect(host: str, port: int = 5432) -> Connection:
    """Open a connection to the database server.

    Establishes a TCP connection to the specified host and port. The connection
    is returned in an idle state, ready for queries. Call `close()` when you're
    finished to release the underlying socket.

    Parameters
    ----------
    host
        The server hostname or IP address.
    port
        The TCP port number. Defaults to the standard PostgreSQL port.

    Returns
    -------
    Connection
        An open connection object.

    Raises
    ------
    ConnectionError
        If the server is unreachable or refuses the connection.

    Examples
    --------
    ```{{python}}
    conn = connect("localhost", port=5432)
    ```
    """
    ...
```

### Google Style

Google-style docstrings use indented section headers followed by a colon. Parameters are indented
under the section header:

```python
def connect(host: str, port: int = 5432) -> Connection:
    """Open a connection to the database server.

    Establishes a TCP connection to the specified host and port. The connection
    is returned in an idle state, ready for queries. Call `close()` when you're
    finished to release the underlying socket.

    Args:
        host: The server hostname or IP address.
        port: The TCP port number. Defaults to the standard PostgreSQL port.

    Returns:
        An open connection object.

    Raises:
        ConnectionError: If the server is unreachable or refuses the connection.

    Examples:
        ```{{python}}
        conn = connect("localhost", port=5432)
        ```
    """
    ...
```

Leave a blank line before each Google-style section header, as shown above. Without the
blank line, the header and its contents are treated as one.

Both formats render identically in the final documentation. Great Docs parses them using
[griffe](https://mkdocstrings.github.io/griffe/) and produces structured HTML with proper headings,
parameter tables, and type annotations.

## Docstring Sections

A docstring can contain several recognized sections. You don't need all of them for every function
or class. Use only what's relevant. The standard sections are:

| Section | Purpose |
|---------|---------|
| **Summary line** | A one-line description. Always present. Shows up in API index tables. |
| **Extended description** | Extra paragraphs after the summary. Markdown formatting applies. |
| **Parameters** | Describes each parameter (name, type, meaning, default). |
| **Returns** | What the function returns, including the type. |
| **Raises** | Exceptions the function may raise and when. |
| **Notes** | Implementation details, algorithms, or caveats. |
| **Examples** | Code demonstrating usage. Can be executable (see below). |
| **See Also** | Related functions or classes. See [Cross-Referencing](cross-referencing.qmd). |
| **Warnings** | Important cautions about usage. |
| **References** | Citations or links to external resources. |

Not every section needs to appear, and sections with no content are simply omitted from the
rendered page. At minimum, include a summary line and a Parameters section for any function that
accepts arguments. Returns and Raises sections are also high value: they tell users what to expect
without reading source code.

### Custom Sections

Both NumPy and Google docstring formats allow you to define your own named sections beyond the
standard ones. This is useful when a function has domain-specific concepts that deserve their own
heading. For example, the Pointblank library uses custom sections like "Supported DataFrame Types",
"Preprocessing", "Segmentation", and "Thresholds" to document recurring concepts that cut across
many validation methods:

```python
def col_vals_gt(
    self,
    columns: str | list[str],
    value: float | int,
    na_pass: bool = False,
    pre: Callable | None = None,
    thresholds: Thresholds | None = None,
) -> Validate:
    """Are column data greater than a fixed value or data in another column?

    The `col_vals_gt()` validation method checks whether column values
    in a table are *greater than* a specified `value=`.

    Parameters
    ----------
    columns
        A single column or a list of columns to validate.
    value
        The value to compare against. This can be a single value or a
        column name given in `col()`.
    na_pass
        Should any encountered None, NA, or Null values be considered
        as passing test units? By default, this is `False`.
    pre
        An optional preprocessing function or lambda to apply to the
        data table during interrogation.
    thresholds
        Failure-condition levels for reporting and reacting to
        exceedences.

    Returns
    -------
    Validate
        The `Validate` object with the added validation step.

    What Can Be Used in `value=`?
    -----------------------------
    The `value=` argument allows for a variety of input types:

    - a single numeric value
    - a single date or datetime value
    - a `col()` object that represents a column name

    Preprocessing
    -------------
    The `pre=` argument allows for a preprocessing function or lambda
    to be applied to the data table during interrogation. The
    transformed table only exists during the validation step and is
    not stored.

    Thresholds
    ----------
    The `thresholds=` parameter sets the failure-condition levels.
    There are three levels: 'warning', 'error', and 'critical'.

    Examples
    --------
    ...
    """
    ...
```

Each custom section becomes its own heading on the rendered reference page, giving readers a
structured way to learn about concepts without cramming everything into the extended description.

## Executable Examples in Docstrings

One of the most powerful features of Great Docs is that executable code cells work inside
docstrings. Instead of showing static code snippets, you can write live examples that Quarto runs
during the build. The output (tables, plots, printed values) appears directly on the reference page.

Use the same ```` ```{python} ```` syntax you'd use in a `.qmd` file:

```python
def preview(data, limit: int = 5):
    """Display a preview of the first rows of a table.

    Parameters
    ----------
    data
        The table to preview.
    limit
        Maximum number of rows to show.

    Examples
    --------
    Load a dataset and preview it:

    ```{{python}}
    import pointblank as pb

    tbl = pb.load_dataset(dataset="small_table", tbl_type="polars")

    pb.preview(tbl)
    ```

    The preview shows column names, types, and the first few rows. This
    is useful for quickly inspecting data before writing validation steps.
    """
    ...
```

When Great Docs builds the site, Quarto executes the code block and embeds the resulting HTML
table directly on the reference page. Readers see both the code and its output, so they know
exactly what to expect when they call the function.

### Tips for Executable Examples

Executable examples are powerful, but they add build time and can break if APIs change. These
guidelines help you get the most from them while keeping your builds fast and reliable:

- **Set up shared state with hidden cells.** If every example needs the same imports or
  configuration, use a hidden code cell at the top of the Examples section. Mark it with
  `#| echo: false` and `#| output: false` so readers see only the meaningful examples:

    ````python
    """
    Examples
    --------
    ```{{python}}
    #| echo: false
    #| output: false
    import mypackage as mp
    mp.config(report_header=False)
    ```

    Now the visible example is clean:

    ```{{python}}
    result = mp.transform(data)
    result
    ```
    """
    ````

- **Add prose between code cells.** Docstring examples don't have to be just code. Intersperse
  explanatory paragraphs that guide readers through what each example demonstrates and what the
  output means.

- **Keep examples self-contained.** Each example should run on its own. Don't rely on variables
  defined in earlier examples unless you've set them up in a hidden cell.

Following these patterns keeps your reference pages informative without turning the build into a
fragile integration test.

## Great Docs Directives

Great Docs recognizes special `%`-prefixed directives that you can place anywhere in a docstring.
These directives are stripped from the rendered output and used to control documentation behavior.

### `%seealso`: Cross-Reference Related Items

The `%seealso` directive adds a "See Also" section to the rendered reference page with clickable
links to related symbols. Place it on its own line anywhere in the docstring:

```python
def encode(data: bytes, encoding: str = "utf-8") -> str:
    """Encode bytes to a string.

    %seealso decode, transcode
    """
    ...
```

You can add descriptions after each name, separated by a colon:

```python
def load(path: str) -> dict:
    """Load data from a file.

    %seealso save : Write data back to a file, validate : Check integrity
    """
    ...
```

You can also use multiple `%seealso` lines. Great Docs merges them into a single "See Also"
section:

```python
def transform(data: dict) -> dict:
    """Transform data before processing.

    %seealso load : Read raw data from a file
    %seealso save : Write transformed data back
    %seealso validate : Check data integrity after transform
    """
    ...
```

For full details on cross-referencing (including inline interlinks and code autolinks), see
[Cross-Referencing](cross-referencing.qmd).

### `%nodoc`: Exclude an Item from Documentation

Sometimes a function or class is public (no leading underscore) but you don't want it in the API
reference. Perhaps it's a legacy function kept for backward compatibility, or an implementation
detail that happens to be exported. The `%nodoc` directive tells Great Docs to skip it entirely:

```python
def _real_implementation():
    ...

def legacy_wrapper():
    """Old entry point, kept for backward compatibility.

    %nodoc
    """
    return _real_implementation()
```

When Great Docs discovers `legacy_wrapper` during static analysis, it reads the docstring, finds
the `%nodoc` directive, and excludes the item from the generated reference. The function still
exists in your package and still works; it simply won't appear in the documentation.

This is different from the `exclude` list in `great-docs.yml`. The `exclude` config is for items
you always want hidden (CLI entry points, internal modules). The `%nodoc` directive is for
per-item decisions that live alongside the code, where the author of the function is best positioned
to decide whether it belongs in the docs.

You can verify which items are excluded by running `great-docs scan`. Items marked with `%nodoc`
won't appear in the output.

## Markdown in Docstrings

Since Great Docs renders docstrings through Quarto, all standard Markdown formatting works:

- **Bold** and *italic* text
- `Inline code` with backticks
- [Links](https://example.com) to external resources
- Bulleted and numbered lists
- Tables
- Callout blocks (tip, note, warning, caution)
- Block quotes
- Images

Here's an example showing callouts and tables inside a docstring:

```python
class DataStore:
    """A persistent key-value store backed by SQLite.

    ::: {.callout-warning}
    The store is not thread-safe. If you need concurrent access, use
    `ThreadSafeStore` instead.
    :::

    The following storage backends are supported:

    | Backend  | Persistence | Speed  |
    |----------|-------------|--------|
    | memory   | None        | Fast   |
    | sqlite   | Disk        | Medium |
    | redis    | Network     | Varies |

    %seealso ThreadSafeStore, connect
    """
    ...
```

All of this renders exactly as it would in a `.qmd` page: the callout becomes a styled warning
box, the table gets proper formatting, and the `%seealso` directive produces a "See Also" section
with links.

## Linking to Other API Items

Inside docstrings, you can create clickable links to other documented symbols using interlinks
syntax. This is useful for guiding readers to related classes or functions:

```python
class Validator:
    """Run validation checks on a data table.

    After creating a `Validator`, add steps with methods like
    [](`~mypackage.col_vals_gt`) and [](`~mypackage.col_vals_lt`),
    then call [](`~mypackage.Validator.interrogate`) to run them.
    """
    ...
```

The `~` prefix strips the package path so readers see just `col_vals_gt` instead of the full
qualified name. Great Docs also auto-links inline code: if you write `` `col_vals_gt` `` in a
docstring and that name is a documented symbol, it automatically becomes a clickable link. See
[Cross-Referencing](cross-referencing.qmd) for the full details.

## Beyond Functions and Classes

Most docstring guidance focuses on functions, methods, and classes. But Python has other objects
that appear in your public API and benefit just as much from documentation: constants, module-level
variables, type aliases, `TypeVar` declarations, properties, and modules themselves. These objects
often go undocumented simply because developers don't think of them as "documentable", yet they show
up in your API reference and can leave readers guessing if they lack context.

Great Docs can render docstrings for all of these. The pattern is the same everywhere: a summary
line, an optional extended description, and whichever sections make sense. Here's some guidance on
what to write for each.

### Constants

A constant (typically uppercase, optionally annotated with `Final`) should explain what the value
controls and why it has the value it does. If the constant is part of a set of related constants,
mention the others:

```python
from typing import Final

MAX_CONNECTIONS: Final[int] = 128
"""Upper bound on simultaneous database connections.

Exceeding this limit raises `ConnectionPoolExhausted`. The default
of 128 matches the PostgreSQL `max_connections` default so that a
single application instance can saturate one server without
over-provisioning.

Notes
-----
Deployments behind a connection pooler (PgBouncer, Odyssey) can
safely raise this to 500 or more, since the pooler manages the
actual backend connection count.

%seealso MIN_CONNECTIONS, ConnectionPoolExhausted
"""
```

### Module-Level Variables

A mutable module-level variable is documented the same way as a constant, but its docstring should
emphasize valid values, defaults, and what happens when a user changes it:

```python
timeout: int = 30
"""Seconds to wait before abandoning a request.

Set this before calling any request functions. Values below 1 are
treated as "no timeout" (the request blocks indefinitely). The
default of 30 seconds suits most interactive use. Batch pipelines
may want 120 or more.

Examples
--------
```{python}
#| eval: false
import mypackage

mypackage.timeout = 60  # generous timeout for batch jobs
"""
```

### Type Aliases

Type aliases name complex types so that signatures stay readable. The docstring should explain the
*intent* behind the alias (i.e., what it represents in the domain) not just restate the underlying
type:

```python
type Key[K: (str, bytes)] = dict[K, ContractId]
"""A lookup keyed by either `str` or `bytes`, but not a mix of the two.

`Key` appears in every registry function that needs to look up a
contract. The constraint to `str | bytes` reflects the fact that
contract identifiers arrive as strings from the API and as raw bytes
from the binary ledger format. Callers pick one and stick with it.

%seealso ContractId, Ledger
"""
```

For the pre-PEP 695 `TypeAlias` spelling, the same guidance applies:

```python
from typing import TypeAlias

Signature: TypeAlias = Literal["ed25519", "rsa"]
"""Which signing scheme produced a signature.

Only `ed25519` and `rsa` are currently supported. The literal type
ensures invalid schemes are caught by type checkers before runtime.
"""
```

### TypeVar, ParamSpec, and TypeVarTuple

These declarations constrain generic signatures. Their docstrings should explain *why* the
constraint exists and what it means for callers:

```python
from typing import TypeVar

Sortable = TypeVar("Sortable", bound="SupportsLessThan")
"""A type that can be compared with `<`.

Any type passed where `Sortable` is expected must implement
`__lt__`. This is the minimum needed for `sorted()` and
`heapq` to work, and it's deliberately narrower than
`SupportsRichComparison` to avoid requiring `__eq__`.
"""
```

### Properties

A property looks like an attribute to the caller but may involve computation, caching, or
validation. The docstring should make this behavior visible:

```python
class Connection:
    @property
    def is_idle(self) -> bool:
        """Whether the connection has no in-flight queries.

        Computed from the internal transaction counter, so this is
        always consistent even if queries are being submitted from
        another thread. An idle connection can be safely returned
        to the pool or closed.

        %seealso close, release
        """
        return self._in_flight == 0
```

### Modules

The module docstring (the first string literal in a `.py` file) sets context for everything the
module contains. It should orient readers who land on the module's page in the API reference:

```python
"""Connection pooling and lifecycle management.

This module owns the connection pool, the health-check loop, and the
retry logic that wraps individual queries. Most users interact with it
through `get_connection()` and the `Connection` context manager; the
pool configuration constants are exposed for tuning.

%seealso config, query
"""
```

### General Tips

A few guidelines apply across all of these:

- **Lead with intent, not structure.** "A lookup keyed by either `str` or `bytes`" tells the reader
more than "`dict[K, ContractId]` where `K` is constrained to `str` or `bytes`."
- **Use `%seealso` liberally.** Constants, type aliases, and TypeVars rarely stand alone. Link to
the functions and classes that use them.
- **Keep the summary line short.** Even for a complex type alias, the first line should fit
comfortably in an API index table.
- **Don't repeat the type annotation.** The rendered page already shows the type, so the docstring
should add what the type alone can't express.

## Docstrings and Sphinx Compatibility

Great Docs supports `%` directives for callouts and API-reference behaviour under every
docstring parser. For example, `%versionadded 2.0` adds a version annotation, and
`%warning` adds a warning callout.

Numbered citations also work with every parser. Define one in a References section with
`.. [1]`; Great Docs renders it as an ordered-list item. Refer to it from prose in the
same docstring with `[1]_`. The reference links to the citation, and the citation links
back to every reference. Nonnumeric labels such as `.. [CIT2002]` render as literal text.

Set `parser: sphinx` to use other RST forms: cross-reference roles such as
`` :py:exc:`ValueError` ``, `math`, `seealso`, and `todo` directives, the inline
`:math:` role, literal blocks, and simple or grid tables. Under `parser: numpy` or
`parser: google`, these forms render as literal text.

To cite from a project bibliography with any parser, use `[@citekey]` and set the
project-level `bibliography:` key.

A bold pseudo-heading such as `**Examples**::` renders as plain text under every parser,
including Sphinx. Use a valid section heading instead.

See [API Documentation: Docstring Directives](api-documentation.qmd#docstring-directives) for the
supported directives and syntax.

## Next Steps

Well-structured docstrings are the foundation of a useful API reference. By choosing a consistent
format, using the right sections, and embedding executable examples, you give Great Docs the raw
material it needs to produce polished reference pages with minimal extra effort.

- [API Documentation](api-documentation.qmd) explains how Great Docs discovers exports, classifies
them, and organizes the reference
- [Cross-Referencing](cross-referencing.qmd) covers `%seealso`, inline interlinks, and code
autolinks in depth
- [Linting](linting.qmd) checks for missing docstrings, malformed directives, and other issues
- [Configuration](configuration.qmd) covers the `parser` setting and other `great-docs.yml` options



## Config & Theming

# Configuration

Great Docs is designed to work with zero configuration, but you can customize its behavior through a
`great-docs.yml` file. This page covers the functional settings: API discovery, docstring parsing,
GitHub integration, sidebar behavior, content features, and more. For visual customization (logos,
gradients, banners, hero sections, dark mode), see [Theming & Appearance](theming.qmd).

::: {.version-only versions=">=0.6"}
For HTML-based landing pages and demo surfaces, see [Custom Static Pages](custom-pages.qmd). That
feature is configured with `custom_pages` and still falls back to `custom/` when omitted.
:::

## Configuration Location

All Great Docs settings go in a `great-docs.yml` file in your project root directory. This dedicated
configuration file keeps your documentation settings separate and easy to manage:

```{.yaml filename="great-docs.yml"}
# Your settings here
```

To generate a starter configuration file with all options documented:

```bash
great-docs config
```

## Display Name

By default, Great Docs uses your package name exactly as-is for the site title and navbar. For
packages with technical names like `my_package` or `my-package`, you might want a more polished
presentation name.

### Setting a Display Name

Use the `display_name` field to specify how your package name appears in the site:

```{.yaml filename="great-docs.yml"}
display_name: My Package
```

This will display `My Package` in the navbar instead of the actual package name.

### When to Use It

Common use cases for `display_name`:

- **Branding**: Convert technical names to marketing names
  - `weathervault` -> `WeatherVault`
  - `great_docs` -> `Great Docs`

- **Readability**: Add spaces and capitalization
  - `my_awesome_lib` -> `My Awesome Lib`
  - `data-processor` -> `Data Processor`

- **Product names**: Use your product's official name
  - `ml_toolkit` -> `ML Toolkit Pro`

### Default Behavior

If you don't specify `display_name`:

- the site title will be your actual package name
- no automatic title-casing or transformation is applied
- `great_docs` stays as `great_docs`, not `Great Docs`
- `my-package` stays as `my-package`, not `My Package`

This ensures predictable behavior and respects your package's actual naming.

## Project Type

By default, Great Docs assumes a Python project. Set `project_type` to tell Great Docs about the
primary language of your project:

```{.yaml filename="great-docs.yml"}
project_type: rust
```

Valid values:

| Value | Effect |
|-------|--------|
| `python` | (default) Enables Python API reference, PyPI link, and Click CLI support |
| `go` | Enables Go CLI support; disables Python-specific features (PyPI link, package info page) |
| `rust` | Enables Rust CLI support; disables Python-specific features (PyPI link, package info page) |

For projects that combine languages (e.g., a Rust binary with Python bindings), use a list:

```{.yaml filename="great-docs.yml"}
project_type: [python, rust]
```

When `python` is included in the list, Python-specific features remain active alongside the other
language's CLI documentation.

## API Discovery Settings

### Excluding Items

To exclude specific items from documentation during `init` and `scan`:

```{.yaml filename="great-docs.yml"}
exclude:
  - InternalClass
  - helper_function
```

Note: The `exclude` setting affects what appears when running `great-docs init` (which
auto-generates your `reference` config) and `great-docs scan` (which shows discovered exports). Once
you have a `reference` config, you control exactly what's documented by listing items there.

### Auto-Excluded Names

Great Docs automatically excludes these common internal names during discovery:

| Category | Names |
|----------|-------|
| CLI/Entry points | `main`, `cli` |
| Version/Metadata | `version`, `VERSION`, `VERSION_INFO` |
| Module re-exports | `core`, `utils`, `helpers`, `constants`, `config`, `settings` |
| Standard library | `PackageNotFoundError`, `typing`, `annotations`, `TYPE_CHECKING` |
| Logging | `logger`, `log`, `logging` |

### Force-Including Auto-Excluded Names

Some packages intentionally export names that match the auto-exclude list (e.g., a `config` or
`logging` module that is part of the public API). Use `auto_include` to force specific names back
into discovery:

```{.yaml filename="great-docs.yml"}
auto_include:
  - config
  - logging
```

Names listed in `auto_include` are removed from the auto-exclude filter while all other
auto-excluded names remain filtered as usual.

### Disabling Auto-Exclude Entirely

If the auto-exclude list doesn't suit your package at all, you can bypass it completely:

```{.yaml filename="great-docs.yml"}
no_auto_exclude: true
```

With this setting, no names are automatically excluded. You can still use `exclude` to manually
remove specific items.

## Docstring Parser

Different projects use different docstring conventions, so Great Docs automatically detects your
docstring style during initialization. For a full guide on structuring docstrings (sections,
executable examples, directives), see [Writing Docstrings](writing-docstrings.qmd).

### Supported Styles

| Style | Description | Example |
|-------|-------------|--------|
| `numpy` | NumPy-style with section underlines | `Parameters\n----------` |
| `google` | Google-style with indented sections | `Args:\n    x: The value` |
| `sphinx` | Sphinx-style with field markers | `:param x: The value` |

### Automatic Detection

When you run `great-docs init`, Great Docs analyzes your package's docstrings to detect the style:

- **NumPy style** is identifiable by section headers with `---` underlines (e.g., `Parameters\n----------`)
- **Google style** is identifiable by section headers with colons (e.g., `Args:`, `Returns:`)
- **Sphinx style** is identifiable by field markers (e.g., `:param:`, `:returns:`, `:rtype:`)

The detected style is saved to `great-docs.yml` and forwarded to the API reference renderer during
builds.

### Manual Configuration

If auto-detection doesn't work for your project, or you want to override it:

```{.yaml filename="great-docs.yml"}
parser: google  # Options: numpy (default), google, sphinx
```

### When to Change the Parser

You might need to manually set the parser if:

- your package has few or no docstrings (detection defaults to `numpy`)
- you use a mix of styles and want to standardize on one
- auto-detection chose the wrong style

### Example Docstrings

::: {.panel-tabset}

#### NumPy Style

```python
def my_function(x, y):
    """
    Add two numbers together.

    Parameters
    ----------
    x
      The first number.
    y
      The second number.

    Returns
    -------
    int
      The sum of x and y.
    """
    return x + y
```

#### Google Style

```python
def my_function(x, y):
    """Add two numbers together.

    Args:
      x: The first number.
      y: The second number.

    Returns:
      The sum of x and y.
    """
    return x + y
```

#### Sphinx Style

```python
def my_function(x, y):
    """Add two numbers together.

    :param x: The first number.
    :type x: int
    :param y: The second number.
    :type y: int
    :returns: The sum of x and y.
    :rtype: int
    """
    return x + y
```

:::

## Interlinks

Your prose can link to another project's documentation the same way it links to your own.
Name each project you want to reach, and the URL its documentation is served from:

```yaml
interlinks:
  sources:
    numpy:
      url: https://numpy.org/doc/stable/
      aliases: [np]
    pandas:
      url: https://pandas.pydata.org/pandas-docs/stable/
```

With that in place, `` [](`numpy.ndarray`) `` resolves to numpy's page for `ndarray`, exactly
as a reference to one of your own objects resolves to yours.

Each source takes two fields:

- `url` is where the project's documentation lives. Its inventory is read from
  `<url>/objects.inv`, where every project publishes one, and every link into the project is
  written against `<url>`.
- `aliases` lists the module names your prose uses for the project. With `aliases: [np]`, a
  reference to `` [](`np.ndarray`) `` resolves as `numpy.ndarray`.

A `url` may name a directory on disk rather than a served site. Great Docs reads the
inventory from that directory and writes links against the same path, so this reaches a
project you build alongside this one only when its path on disk is also its path on the
site. Where the two differ, point `url` at the published site and let the build fetch the
inventory over the network.

Give a `url` that means the same thing from every page. One prefix is written into the
index and used from pages at every depth, so a relative `url` such as `../sibling` resolves
from wherever the reading page sits and cannot suit them all. Great Docs reports a relative
`url` in the build log and writes the links as configured. A source with no `url` at all is
skipped, and the build log says that too.

Add Python's standard library as a source in the same way:

```yaml
interlinks:
  sources:
    python:
      url: https://docs.python.org/3/
```

Do not add `aliases` here. The standard library has no single root. An alias rewrites a prefix
to a project's root module, which works when a project puts every name under one package, as
numpy and pandas do.

Inventories are downloaded during the build and cached, so repeated builds do no network work,
and a build that cannot reach a project falls back to the copy it already has. A project it has
never reached is reported and skipped, leaving those references unlinked rather than failing
the build.

Your own site publishes `objects.inv` at its root, so other projects can point a source at
your documentation in the same way.

### Parentheses on Function Links

A function or method link displays a trailing `()`, so `[](`decode`)` renders as `decode()`. Class
links never display parentheses. Set `add_function_parentheses: false` to display the bare name:

```yaml
interlinks:
  add_function_parentheses: false
```

This setting applies to links whose targets you write, including links generated by `%seealso`. It
does not affect inline-code autolinks. Their display text remains exactly as written: `decode()`
keeps its parentheses, while `decode` never gains them.

## Dynamic Introspection

Great Docs uses its built-in renderer to generate API reference pages. By default, it uses
**dynamic introspection** (importing your package at runtime), which produces the most accurate
documentation for complex packages with re-exports and aliases.

```{.yaml filename="great-docs.yml"}
dynamic: true   # Default: true
```

Some packages have internal attributes that cause errors during dynamic introspection. If this
happens, Great Docs will **automatically retry the build with static analysis** (`dynamic: false`).
You'll see a message like:

```
⚠️  API reference build failed with dynamic introspection.
   Retrying with static analysis (dynamic: false)...
```

To skip the retry and always use static analysis, set it explicitly:

```{.yaml filename="great-docs.yml"}
dynamic: false
```

### When to Set `dynamic: false`

- your package has cyclic aliases or complex re-export patterns
- the build fails with `AttributeError` during introspection
- you're documenting a compiled extension (PyO3/Rust/Cython)

## GitHub Integration

Several Great Docs features require knowing your GitHub repository URL:

- **GitHub widget/icon** in the navbar (with star count)
- **Source links** on API reference pages
- **Version badge** next to the package name (from GitHub Releases)
- **Changelog** page (from GitHub Releases)

### Repository URL Detection

Great Docs looks for your GitHub repository in this order:

1. **`repo:` in great-docs.yml**: explicit override, takes precedence
2. **`[project.urls]` in pyproject.toml**: looks for `Repository`, `Source`, `GitHub`, or `Homepage`
keys containing a GitHub URL

```{.yaml filename="great-docs.yml"}
repo: https://github.com/your-org/your-package
```

Or via pyproject.toml:

```{.toml filename="pyproject.toml"}
[project.urls]
Repository = "https://github.com/your-org/your-package"
```

::: {.callout-note}
## Build Messages

During `great-docs build`, you may see messages about GitHub integration:

- **"No GitHub repository info available"**: no repository URL was found. Check that `repo:` is set
in great-docs.yml or `[project.urls]` is configured in pyproject.toml.
- **"No GitHub releases found"**: the repository was detected, but has no published GitHub Releases.
The version badge feature requires at least one published release.
:::

### GitHub Link Style

Choose how the GitHub link appears in the navbar:

```{.yaml filename="great-docs.yml"}
# Shows stars count (default)
github_style: widget

# Or use a simple GitHub icon
github_style: icon
```

### Version Badge

When your repository has published GitHub Releases, Great Docs automatically displays a version
badge next to your package name in the navbar. The badge shows the latest release version and
updates automatically on each build.

This feature requires:

1. a detected GitHub repository URL (see above)
2. at least one published [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)

No configuration is needed (the badge appears automatically when these conditions are met).

### Source Links

Great Docs automatically creates "source" links to GitHub. Configure the branch:

```{.yaml filename="great-docs.yml"}
source:
  branch: main  # Default: auto-detected from git
```

To disable source links entirely:

```{.yaml filename="great-docs.yml"}
source:
  enabled: false
```

Full source link configuration:

```{.yaml filename="great-docs.yml"}
source:
  enabled: true        # Enable/disable source links (default: true)
  branch: main         # Git branch/tag to link to (default: auto-detect)
  path: src/package    # Custom source path for monorepos (default: auto-detect)
  placement: usage     # Where to place the link: "usage" (default) or "title"
```

## PyPI Link

The homepage metadata sidebar includes a "View on PyPI" link, auto-detected from your package name
in `pyproject.toml`. You can disable it or point it to a custom package index:

```{.yaml filename="great-docs.yml"}
# Disable the PyPI link entirely
pypi: false
```

```{.yaml filename="great-docs.yml"}
# Use a custom package index URL (e.g., a private registry)
pypi: "https://packages.example.com/simple/my-package"
```

By default (`pypi: null`) the link is generated for Python projects and omitted for everything
else, so a Go-only project gets no PyPI link without your having to say so. Setting `pypi: true`
forces the link on regardless of `project_type`; it is auto-generated as
`https://pypi.org/project/{package_name}/`.

## Site URL

Set `site_url` to the canonical URL where your documentation site is (or will be) hosted.
This value is used in several places:

- **Skills page** install instructions (e.g., `npx skills add <url>`)
- **`.well-known/` discovery** endpoints for agent skills
- **Quarto's `website.site-url`** (canonical links, sitemaps)
- **Subdirectory deployments** where the site lives at a path other than `/`
  (e.g., `https://internal.example.com/docs/mypackage/`)

Without it, the Skills page renders literal `<site-url>` placeholders instead of working
install commands, and subdirectory-hosted sites will have broken asset paths.

```{.yaml filename="great-docs.yml"}
# Site URL: the canonical address of the deployed documentation site.
# Used for skills page install commands, .well-known/ discovery, and sitemaps.
site_url: "https://your-org.github.io/your-package/"
```

Alternatively, you can set a `Documentation` entry in `pyproject.toml`:

```{.toml filename="pyproject.toml"}
[project.urls]
Documentation = "https://your-org.github.io/your-package/"
```

Great Docs checks these sources in order:

1. `site_url` in `great-docs.yml`
2. `Documentation` URL in `[project.urls]` (pyproject.toml)
3. `website.site-url` already present in `_quarto.yml`

If none are found, the build emits a warning:

```
⚠ No site URL found — skills page will show <site-url> placeholders.
  Set site_url in great-docs.yml or add a Documentation URL to
  [project.urls] in pyproject.toml.
```

::: {.callout-tip}
Set `site_url` even before your site is deployed. Once the site goes live at that address, all
generated install commands will already be correct.
:::

## Sidebar Filter

The API reference sidebar includes a search filter for large APIs. Configure it:

```{.yaml filename="great-docs.yml"}
sidebar_filter:
  enabled: true   # Enable/disable filter (default: true)
  min_items: 20   # Minimum items before showing filter (default: 20)
```

## Method Page Splitting

Control whether class methods get their own pages or stay inline on the class page:

```{.yaml filename="great-docs.yml"}
inline_methods: 5      # Split above 5 methods (default)
inline_methods: 10     # Split above 10 methods
inline_methods: true   # Always inline (never split)
inline_methods: false  # Always split to separate pages
```

See [API Documentation: Smart Method Handling](06-api-documentation.qmd#smart-method-handling) for
detailed examples.

## Markdown Pages

Every HTML page gets a companion `.md` file generated automatically. A small widget appears in the
top-right corner of each page allowing visitors to **copy** the page content as Markdown or **view**
the raw `.md` file. This is enabled by default:

```{.yaml filename="great-docs.yml"}
markdown_pages: true   # Enable/disable (default: true)
```

To disable both the `.md` generation and the copy/view widget:

```{.yaml filename="great-docs.yml"}
markdown_pages: false
```

To generate `.md` pages but hide the widget:

```{.yaml filename="great-docs.yml"}
markdown_pages:
  widget: false
```

## Theming & Visual Options

Great Docs offers extensive visual customization: announcement banners, animated gradient presets
for the navbar and content area, solid navbar colors, custom head injections, logos with light/dark
variants, automatic favicon generation, and hero sections on the landing page. These options are
covered in their own dedicated page.

See [Theming & Appearance](theming.qmd) for full details on all visual customization options.

## HTML Math Renderer

Great Docs forwards `site.html-math-method` to Quarto's HTML configuration. It defaults to
KaTeX, which renders mathematical notation without a browser-side MathJax dependency:

```{.yaml filename="great-docs.yml"}
site:
  html-math-method: katex
```

To use MathJax instead, set the method explicitly:

```{.yaml filename="great-docs.yml"}
site:
  html-math-method: mathjax
```

Other Quarto-supported HTML math methods can also be selected with this setting. Configure it in
`great-docs.yml`; Great Docs writes the corresponding value into its generated `_quarto.yml`.

## User Guide Directory

By default, Great Docs looks for a `user_guide/` directory in your project root. To use a different
location:

```{.yaml filename="great-docs.yml"}
user_guide: docs/guides
```

The path is relative to the project root. If both the config option and a `user_guide/` directory
exist, the config option takes precedence.

See [User Guides](user-guides.qmd) for details on writing and organizing User Guide content.

## Homepage Mode

By default, Great Docs generates a separate homepage from your project's README (or
`index.qmd`/`index.md`), with a "User Guide" link in the top navbar. Many Python documentation sites
use a different layout where the first User Guide page _is_ the landing page.

The `homepage` setting controls which layout to use:

```{.yaml filename="great-docs.yml"}
homepage: user_guide
```

### Available Modes

| Value | Behaviour |
|-------|-----------|
| `index` (default) | Separate homepage from README / `index.qmd`. "User Guide" appears as a navbar link. |
| `user_guide` | First User Guide page becomes the landing page. Left sidebar shows the UG table of contents. Right sidebar shows project metadata. No separate "User Guide" navbar link. |

### How `user_guide` Mode Works

When `homepage: user_guide` is set:

1. **Landing page**: the first User Guide page (determined by filename sort order or explicit
config) becomes `index.qmd` at the site root. Its content is preserved verbatim, with the project
metadata sidebar (links, license, authors, etc.) appended in the right margin.

2. **Left sidebar**: the User Guide table of contents appears in the left sidebar on every UG page,
including the homepage. The first entry links to the site root.

3. **Navbar**: the "User Guide" link is omitted from the top navbar since clicking the site title
already takes you to the User Guide landing page. All other navbar items (Reference, custom
sections, etc.) are unchanged.

4. **README**: your `README.md` is not used for the homepage. It still serves its purpose on PyPI
and GitHub.

### Example

A project with this structure:

```
my_package/
├── user_guide/
│   ├── 00-getting-started.qmd   # ← becomes the homepage
│   ├── 01-installation.qmd
│   └── 02-configuration.qmd
├── great-docs.yml
└── pyproject.toml
```

And this config:

```{.yaml filename="great-docs.yml"}
homepage: user_guide
```

Will produce a site where:

- the homepage shows the "Getting Started" content with a project metadata sidebar
- the left sidebar lists all three User Guide pages
- the navbar has no "User Guide" link (the site title links home)

### Fallback Behavior

If `homepage: user_guide` is set but no User Guide pages exist, Great Docs will warn and fall back
to the default `index` mode (generating a homepage from your README).

## CLI Documentation

Great Docs can generate CLI reference pages for Python, Go, and Rust projects. Each ecosystem has
its own configuration key.

### Python CLI (Click)

Enable automatic CLI documentation for Click-based CLIs:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
```

With optional explicit configuration:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: my_package.cli   # Module containing Click commands
  name: cli                # Name of the Click command object
```

### Go CLI (Cobra)

For Go projects using Cobra, urfave/cli, or similar frameworks. Requires `go` on your `PATH`:

```{.yaml filename="great-docs.yml"}
project_type: go
go_cli:
  enabled: true
```

### Rust CLI (clap)

For Rust projects using clap, structopt, argh, or similar frameworks. Requires `cargo` on your
`PATH`:

```{.yaml filename="great-docs.yml"}
project_type: rust
rust_cli:
  enabled: true
```

See [CLI Documentation](cli-documentation.qmd) for full details on each ecosystem, including project
detection, help-text formatting tips, and troubleshooting.

## Changelog

Great Docs auto-generates a Changelog page from your GitHub Releases. It's enabled by default so if
your `pyproject.toml` has a GitHub repository URL, a changelog page will appear automatically.

To customize:

```{.yaml filename="great-docs.yml"}
changelog:
  enabled: true        # Enable/disable changelog (default: true)
  max_releases: 50     # Max releases to include (default: 50)
```

To disable it entirely:

```{.yaml filename="great-docs.yml"}
changelog:
  enabled: false
```

See [Changelog](changelog.qmd) for full details on authentication, CLI usage, and edge cases.

## Custom Sections

Add custom page groups (examples, tutorials, blog, etc.) to your site. Each section gets a navbar
link and an auto-generated index page:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples          # Navbar link text
    dir: examples            # Source directory
    navbar_after: User Guide  # Position in navbar (optional)
  - title: Tutorials
    dir: tutorials
  - title: Blog              # Blog with Quarto's listing directive
    dir: blog
    type: blog               # "blog" for listing page; omit for card grid
```

Default sections get a card-grid index and sidebar navigation. Blog-type sections use Quarto's
native `listing:` directive. Posts are sorted by date and displayed with author, categories, and
descriptions.

See [Custom Sections](custom-sections.qmd) and [Blog](blog.qmd) for full details.

## Navbar Order

By default, navbar items appear in the order they are added during the build (Reference, Changelog,
User Guide, custom sections). Use `navbar_order` to set an explicit ordering:

```{.yaml filename="great-docs.yml"}
navbar_order:
  - User Guide
  - Reference
  - Demos
  - Changelog
```

Items are matched by their display text. Any navbar items not listed are appended at the end in
their original order. This is useful when you want a specific item (like the User Guide) to appear
first.

## Reference Section Order

When your site includes multiple reference sections (Python API, CLI, MCP Server), the default
ordering of sections is: Python API, CLI, MCP Server. You may prefer a different order and we can
use `ref_section_order` to change this. For example, a CLI-first tool might want this particular
ordering of reference pages:

```{.yaml filename="great-docs.yml"}
ref_section_order:
  - cli
  - api
  - mcp
```

Valid values are `api`, `cli`, and `mcp`. Sections listed here that don't exist in your project are
silently ignored, so it's safe to include `mcp` even if your package has no MCP server. Sections not
listed are appended at the end in the default order. The navbar "Reference" link will point to
whichever section is first.

## Author Information

Customize author display in the landing page sidebar:

```{.yaml filename="great-docs.yml"}
authors:
  - name: Your Name
    email: you@example.com
    role: Lead Developer
    affiliation: Organization
    github: yourusername
    homepage: https://yoursite.com
    orcid: 0000-0002-1234-5678
```

Multiple authors are supported:

```{.yaml filename="great-docs.yml"}
authors:
  - name: First Author
    role: Lead Developer
    github: firstauthor

  - name: Second Author
    role: Contributor
    github: secondauthor
```

### Supported Author Fields

| Field | Description |
|-------|-------------|
| `name` | **Required.** Author's full name |
| `email` | Email address (clickable icon) |
| `role` | Role in the project (e.g., "Lead Developer") |
| `affiliation` | Organization or institution |
| `github` | GitHub username (clickable icon) |
| `homepage` | Personal website URL (clickable icon) |
| `orcid` | ORCID identifier (clickable icon) |

## API Reference Structure

Control how your API documentation is organized with the `reference` config:

```{.yaml filename="great-docs.yml"}
reference:
  - title: Core Classes
    desc: Main classes for working with the package
    contents:
      - name: MyClass
        members: false       # Don't document methods here
      - SimpleClass          # Methods documented inline (default)

  - title: Utility Functions
    desc: Helper functions for common tasks
    contents:
      - helper_func
      - another_func
```

If no `reference` config is provided, Great Docs auto-generates sections from discovered exports.

### Page Title and Description

You can set a custom heading and introductory paragraph for the API reference index page:

```{.yaml filename="great-docs.yml"}
reference:
  title: "API Docs"
  desc: >-
    Complete reference for all public classes and functions
    available in this package.
```

The `title` replaces the default "Reference" text in both the page heading and the navbar. The
`desc` appears as a paragraph below the heading, before the section listings. If omitted, the
heading defaults to "Reference" with no introductory text.

These keys can be combined with explicit `sections` for full control over both the page heading and
the section structure:

```{.yaml filename="great-docs.yml"}
reference:
  title: "API Docs"
  desc: "All public symbols documented below."
  sections:
    - title: Core
      contents:
        - MyClass
```

## Agent Skills (skill.md)

Great Docs supports the [Agent Skills](https://agentskills.io/) open standard, which gives AI
coding agents structured context about your package so they can write better code when using it.

During the build, a `SKILL.md` is generated (or copied from your hand-written version) and served
at `.well-known/agent-skills/<name>/SKILL.md` for discovery. Users can then install it with
`npx skills add` or `great-docs skill install`.

```{.yaml filename="great-docs.yml"}
skill:
  enabled: true          # Set to false to disable skill.md entirely
  file: null             # Path to a SKILL.md (overrides curated and generated)
  well_known: true       # Serve at /.well-known/ discovery endpoints
  gotchas: []            # Gotcha strings (for auto-generated skill only)
  best_practices: []     # Best-practice strings (for auto-generated skill only)
  decision_table: []     # Rows: [{need: "...", use: "..."}]
  extra_body: null       # Path to extra Markdown to append (auto-generated only)
  skills: []             # Multi-skill mode: [{name: "...", file: "..."}]
```

For the full guide — including how to write a skill, the resolution order, multi-skill mode,
the `great-docs skill` CLI, freshness checking, and the Python API — see
[Agent Skills](38-agent-skills.qmd).

## Page Metadata [version-badge new 0.2]

Display page creation and modification dates at the bottom of documentation pages, giving readers a
sense of content freshness.

### Enabling Page Metadata

```{.yaml filename="great-docs.yml"}
site:
  show_dates: true
```

When enabled, pages display timestamps in a compact horizontal format:

```
✏️ 4 months ago   📄 2 years ago
```

- **✏️ (pencil icon)**: Last modification date
- **📄 (file icon)**: Creation date

Hovering over a timestamp shows the full date (e.g., "March 24, 2026").

### How Dates Are Determined

Great Docs determines dates from Git history when available:

| Date Type | Source |
|-----------|--------|
| **Created** | Date of the first Git commit that added the file |
| **Modified** | Date of the most recent Git commit that changed the file |

If Git history is unavailable (e.g., shallow clones in CI), the file system timestamps are used as a
fallback.

### Overriding Dates in Frontmatter

You can override Git-derived dates using frontmatter, which is useful when:

- you want to set a specific "last updated" date
- git history is unavailable or incorrect (shallow clones, file renames)
- you're migrating content from another system

```{.yaml filename="guide.qmd"}
---
title: "Getting Started"
last_update:
  date: "2026-01-15"
  author: "Jane Developer"
date_created: "2024-06-01"
---
```

The `last_update` field follows this format:

- `date`: ISO date string (with or without time/timezone)
- `author`: optional author name override

Frontmatter values take precedence over Git history. If only `last_update.date` is provided, the
creation date still comes from Git.

### CI/CD Considerations

In CI environments like GitHub Actions, the default checkout only fetches the latest commit (shallow
clone). This means all pages would show identical timestamps.

The `great-docs setup-github-pages` command generates a workflow with full Git history enabled:

```yaml
- uses: actions/checkout@v6
  with:
    fetch-depth: 0  # Full history for accurate timestamps
```

For large repositories, you can use sparse checkout to speed up builds while still getting full
history for documentation files:

```yaml
- uses: actions/checkout@v6
  with:
    fetch-depth: 0
    sparse-checkout: |
      user_guide
      recipes
```

### Auto-Generated Pages

Pages that Great Docs generates automatically (API reference, changelog, CLI reference) show a
"Refreshed" timestamp instead:

```
🔄 Refreshed 2 hours ago
```

This indicates when the page content was last regenerated during a build, not when source code was
edited.

### Which Pages Show Metadata

| Page Type | Shows Metadata |
|-----------|----------------|
| User Guide pages | ✓ Yes |
| Recipes | ✓ Yes |
| Roadmap, Contributing, etc. | ✓ Yes |
| API Reference pages | ✓ Yes (as "Refreshed") |
| Changelog | ✓ Yes (as "Refreshed") |
| Homepage | ✗ No |

### Configuration Options

```{.yaml filename="great-docs.yml"}
site:
  show_dates: true       # Enable/disable page metadata (default: false)
  show_author: true      # Show author attribution when enabled (default: true)
  show_security: true    # Show security policy page from SECURITY.md (default: true)
```

### Author Attribution

When `show_author` is enabled and a page has author information in its frontmatter, author avatars
appear alongside the timestamps:

```
✏️ 4 months ago   📄 2 years ago   —   ○ ○
```

To add author information to a page, include it in the YAML frontmatter:

```{.yaml filename="guide.qmd"}
---
title: "Getting Started"
author:
  name: "Jane Developer"
  image: "https://github.com/janedev.png"
  url: "https://github.com/janedev"
---
```

Great Docs automatically looks up author details from the `authors` list in `great-docs.yml`, so you
can often just specify the name:

```{.yaml filename="guide.qmd"}
---
title: "Getting Started"
author: "Jane Developer"
---
```

If the author is listed in `great-docs.yml` with a `github` field, their GitHub avatar is used
automatically.

## Complete Example

Here's a comprehensive configuration demonstrating all available options:

```{.yaml filename="great-docs.yml"}
# Display Name
display_name: My Package  # Custom display name for navbar/title

# Docstring Parser
parser: numpy  # Auto-detected: numpy, google, or sphinx

# API Discovery
exclude:
  - _InternalClass

# GitHub Integration
repo: https://github.com/your-org/your-package  # Override auto-detect
github_style: widget

# Site URL — canonical address of the deployed documentation site.
# Used for skills page install commands, .well-known/ discovery, and sitemaps.
# site_url: "https://your-org.github.io/your-package/"

# Source Links
source:
  enabled: true
  branch: main
  placement: usage

# PyPI Link
pypi: null  # null (default) links for Python projects; true forces, false disables, or a URL string

# Sidebar
sidebar_filter:
  enabled: true
  min_items: 15

# Site Settings
site:
  show_dates: true       # Show page timestamps
  show_author: true      # Show author avatars

# Markdown Pages
markdown_pages: true

# User Guide Directory
# user_guide: docs/guides

# Homepage Mode
# homepage: user_guide  # First UG page becomes the landing page

# CLI Documentation
cli:
  enabled: true

# Changelog (GitHub Releases)
changelog:
  enabled: true
  max_releases: 50

# Custom Sections
sections:
  - title: Examples
    dir: examples
  - title: Tutorials
    dir: tutorials
    navbar_after: Examples
  - title: Blog
    dir: blog
    type: blog

# Navbar Order
navbar_order:
  - User Guide
  - Reference
  - Examples
  - Tutorials
  - Changelog

# Reference Section Order (within the Reference area)
ref_section_order:
  - cli
  - api
  - mcp

# API Reference Structure
reference:
  title: "API Reference"
  desc: "Complete reference for the library's public API."
  sections:
    - title: Core Classes
      desc: Main classes for the library
      contents:
        - name: MainClass
          members: false
        - HelperClass

    - title: MainClass Methods
      desc: Methods for the MainClass
      contents:
        - MainClass.process
        - MainClass.validate

    - title: Utility Functions
      desc: Helper functions
      contents:
        - utility_func
        - helper_func

# Authors
authors:
  - name: Jane Developer
    email: jane@example.com
    role: Lead Developer
    github: janedev
    orcid: 0000-0001-2345-6789

  - name: John Contributor
    role: Contributor
    github: johncontrib

# Agent Skills (skill.md)
skill:
  gotchas:
    - "Always call init() before using other functions"
  best_practices:
    - "Use context managers for resource cleanup"
  decision_table:
    - need: "Create a widget"
      use: "Widget()"
    - need: "Process data"
      use: "MainClass.process()"
```

You don't need all of these settings. Start with just the options you need and add more as your
project grows. The defaults work well for most packages, so you may find that a minimal
configuration (or none at all) is sufficient.

## Generating a Configuration File

To create a starter `great-docs.yml` with all options documented:

```bash
great-docs config
```

This creates a file with all available options as comments, making it easy to enable the features
you need.

## Quarto Configuration

Great Docs generates and maintains a `_quarto.yml` file in the `great-docs/` output directory. This
is an internal file that controls how Quarto renders your site, including navigation, theming, and
the API reference configuration. It is regenerated on every `great-docs build`.

**Should you edit it?** No. Any manual edits will be overwritten on the next build. All
customization should go through `great-docs.yml`, which is the single source of truth for your
documentation configuration.

**Should you commit it?** No. The entire `great-docs/` output directory is ephemeral and should
be gitignored (which `great-docs init` offers to set up for you).

## Next Steps

With `great-docs.yml` you control everything from API discovery and docstring parsing to sidebar
layout and GitHub integration. Most projects only need a handful of settings, but the full range is
here when you need it.

- [Theming & Appearance](theming.qmd) covers logos, gradients, banners, dark mode, hero sections,
and other visual options
- [API Documentation](api-documentation.qmd) explains how API discovery and organization works
- [CLI Documentation](cli-documentation.qmd) covers Click CLI documentation
- [Cross-Referencing](cross-referencing.qmd) covers the Great Docs Linking System (GDLS)



## Site Content

# API Documentation

Most Python packages need an API reference, but writing one by hand is tedious and keeping it in
sync with code changes is even harder. Great Docs takes care of both: it automatically discovers
your package's public API through static analysis, classifies every export by type, and generates a
complete, styled reference section. You can ship a polished API reference without writing a single
docstring page yourself, and as your code evolves the documentation stays up to date.

This page explains how discovery works, what gets documented, and how to customize the result.

## How Discovery Works

When you run `great-docs init` or `great-docs build`, Great Docs:

1. **Finds your package**: looks in standard locations (`src/`, `python/`, project root)
2. **Uses static analysis**: analyzes your code with `griffe` without importing it
3. **Discovers public names**: finds all non-private names (not starting with `_`)
4. **Introspects submodules**: drills into exported modules to discover their classes, functions,
and constants
5. **Categorizes items**: classifies every export into one of 13 object types
6. **Generates configuration**: creates API reference sections in `_quarto.yml`

The entire pipeline runs in seconds and produces a fully structured reference. You don't need to
maintain a manifest of your public symbols; Great Docs figures it out from your code.

To preview what Great Docs will find without generating any files, run `great-docs scan` in your
project directory. This lists every discovered export grouped by type, and marks which items are
already included in your `reference` config. Add `--verbose` to see individual methods on each
class.

### Static Analysis Benefits

Great Docs uses static analysis rather than importing your package. This means:

- **No side effects**: your code isn't executed during discovery
- **No import errors**: missing dependencies won't break documentation
- **Faster discovery**: no need to set up a complete environment
- **Safer**: works even if your package has complex initialization

Because discovery never executes your code, you can generate documentation in CI environments,
containers, or any machine where your package's runtime dependencies aren't installed.

## What Gets Documented

By default, Great Docs documents everything it discovers in your package's public API. These
discovered items are the package's *documentable objects*: any public class, function, constant, or
type alias that Great Docs can identify through static analysis. Each documentable object is
classified into one of the following 13 object types:

**Class-like types**

- **Classes**: regular public classes with their methods
- **Dataclasses**: classes decorated with `@dataclass`
- **Abstract Classes**: classes inheriting from `ABC` or using `ABCMeta`
- **Protocols**: structural typing protocols (`typing.Protocol` subclasses)
- **Enumerations**: `Enum` subclasses
- **Exceptions**: `Exception` and `BaseException` subclasses
- **Named Tuples**: `NamedTuple` definitions
- **Typed Dicts**: `TypedDict` definitions

**Function-like types**

- **Functions**: synchronous public functions
- **Async Functions**: functions defined with `async def`

**Data types**

- **Constants**: module-level constants and data
- **Type Aliases**: type alias definitions (including `TypeVar`)

**Other**

- **Other**: anything that doesn't fit the above categories

Each type is placed into its own section in the generated reference and receives a distinct visual
badge (see [Type Labels](#type-labels) below).

### Exclusion Rules

Not everything in your package's namespace belongs in the API reference. Internal wiring like CLI
entry points, logging setup, and utility modules are implementation details that would clutter the
documentation without helping users. Great Docs automatically excludes a set of common names that
almost never represent public API:

```python
# These are auto-excluded:
main        # CLI entry points
cli
version     # Version metadata
VERSION
core        # Internal modules
utils
helpers
logger      # Logging
log
```

To exclude additional names from `init` and `scan`, add them to the `exclude` list in
`great-docs.yml`:

```{.yaml filename="great-docs.yml"}
exclude:
  - InternalHelper
  - deprecated_function
```

Once you have a `reference` config in `great-docs.yml`, you control exactly what gets documented by
listing items there. The `exclude` setting only affects what `great-docs init` discovers when
generating your initial config. Between the built-in exclusions and the explicit list, you can keep
the reference focused on the symbols your users actually need.

## Smart Method Handling

Large classes with many methods can create overwhelming documentation. Great Docs handles this
intelligently by separating methods into their own pages when a class exceeds a threshold.

### Default Behavior

By default, classes with **more than 5 methods** are split: the class itself gets one page, and each
method gets its own page in a companion "Methods" section. Classes with 5 or fewer methods keep
their methods inline on the class page.

### Configuring the Threshold

You can control this behavior with the `inline_methods` setting in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
# Keep the default (split above 5 methods)
inline_methods: 5

# Custom threshold: split above 10 methods
inline_methods: 10

# Always inline: never split methods to separate pages
inline_methods: true

# Always split: every class gets separate method pages
inline_methods: false
```

| Value | Behavior |
| --- | --- |
| `true` | Methods always stay inline on the class page, regardless of count |
| `false` | Methods always get their own pages (even for classes with 1–2 methods) |
| Integer `N` | Methods stay inline for classes with ≤N methods; classes with >N get split (default: `5`) |

The examples below show what Great Docs generates in `_quarto.yml`. This file is regenerated on
every build, so don't edit it by hand. Use `inline_methods` in `great-docs.yml` to control the
behavior and let the build produce the right output.

### Small Classes (≤ threshold)

When a class has fewer methods than the threshold, all of its methods appear directly on the class
page. Readers see everything in one place without navigating between pages. In the generated
`_quarto.yml`, the class is listed as a simple entry:

```{.yaml filename="_quarto.yml"}
sections:
  - title: Classes
    contents:
      - MySmallClass  # Methods shown inline
```

This keeps the sidebar compact and works well for classes where the full method list fits
comfortably on a single page.

### Large Classes (> threshold)

When a class exceeds the threshold, Great Docs automatically splits it in the generated
`_quarto.yml`. The methods are pulled out into a dedicated "Methods" section with individual pages,
and the class entry suppresses inline method documentation so readers aren't overwhelmed:

```{.yaml filename="_quarto.yml"}
sections:
  - title: Classes
    contents:
      - name: MyLargeClass
        members: []  # Suppresses inline methods

  - title: MyLargeClass Methods
    desc: Methods for the MyLargeClass class
    contents:
      - MyLargeClass.method_one
      - MyLargeClass.method_two
      # ... all methods listed individually
```

Each method gets its own sidebar entry and its own page, making it easier to link to specific
methods and to find them through search.

### When to Adjust

The right setting depends on how users interact with your API documentation:

- set `inline_methods: true` if your classes have many methods but users typically need to see them
all at once (e.g., configuration objects, builder patterns).
- set `inline_methods: false` if every method deserves its own discoverable page (e.g., a large
framework API where methods are searched individually).
- set a higher number (e.g., `10` or `15`) if your classes tend to have moderate method counts and the
default of `5` splits too aggressively.

When in doubt, start with the default and adjust once you see how your rendered documentation feels
to navigate.

## Callable Signatures

The `callable_signatures` block in `great-docs.yml` controls how a callable's signature is
written to the page. It applies to functions, methods, and classes; attributes and type aliases
render the same way whatever it says.

```{.yaml filename="great-docs.yml"}
callable_signatures:
  style: highlighted   # a highlighted code block (default)
  wrap: per_parameter  # one parameter per line (default)
```

| Setting | Value | Behaviour |
| --- | --- | --- |
| `style` | `highlighted` | The signature is a fenced Python code block, highlighted by Quarto (default) |
| `style` | `plain` | The signature is inline markup carrying the callable's name and its parameters |
| `wrap` | `per_parameter` | Every parameter takes its own line whenever there is more than one (default) |
| `wrap` | `width` | The signature stays on one line until it exceeds 78 characters |

## API Organization

The auto-generated reference is organized into sections by object type. This works well out of the
box, but as your package grows you may want to group exports by domain rather than by type. Great
Docs gives you full control over the section structure through the `reference` config in
`great-docs.yml`, from simple title changes to completely custom groupings.

### Default Sections

Great Docs creates sections automatically based on what it discovers. Only non-empty sections
appear, so if your package has no enumerations or protocols, those sections are simply omitted. Here
is the full set of possible sections:

| Section | Description |
| --- | --- |
| **Classes** | Regular public classes |
| **Dataclasses** | Data-holding classes |
| **Abstract Classes** | Abstract base classes |
| **Protocols** | Structural typing protocols |
| **Enumerations** | Enum types |
| **Exceptions** | Exception classes |
| **Named Tuples** | NamedTuple types |
| **Typed Dicts** | TypedDict types |
| **Functions** | Synchronous functions |
| **Async Functions** | Asynchronous functions (`async def`) |
| **Constants** | Module-level constants and data |
| **Type Aliases** | Type alias definitions |
| **Other** | Additional exports |
| **[ClassName] Methods** | Created for classes exceeding the `inline_methods` threshold |

A typical package might only produce a few of these (e.g., Classes, Functions, and Constants). The
section structure is automatically tailored to your package's contents.

You're encouraged to customize the organization using the `reference` config in `great-docs.yml` to
create sections that better reflect your package's domain.

### Custom Organization with `reference` Config

The default sections group exports by type, but your users probably think about your API in terms of
what it does, not what kind of Python object each export is. A data validation library might group
things into "Schema Definition", "Validators", and "Error Handling" rather than "Classes",
"Functions", and "Exceptions". Custom organization lets you tell a story with your API reference,
guiding readers to the right part of the documentation based on what they are trying to accomplish.

You can explicitly control the structure in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
reference:
  - title: User Management
    desc: Functions for managing users
    contents:
      - create_user
      - delete_user
      - update_user

  - title: Authentication
    desc: Functions for authentication
    contents:
      - login
      - logout
```

Items appear in the order listed within each section. This explicit configuration gives you complete
control over how your API documentation is organized.

One thing to watch out for: the names in `contents` must match your package's actual public API
exactly. A misspelled name, a name that was renamed or removed, or a name that appears in the
`exclude` list will silently produce a missing or empty reference page. If a page doesn't render as
expected after a build, check that the name in your `reference` config matches what your package
exports.

### Custom Title and Description

You can customize the heading and introductory text of the API reference page using the `title` and
`desc` keys:

```{.yaml filename="great-docs.yml"}
reference:
  title: "API Docs"
  desc: >
    Welcome to the API documentation. This reference covers all public
    classes and functions available in the package.
```

When set, the `title` replaces the default "Reference" heading on the API index page and in the
navigation bar. The `desc` text appears as a paragraph immediately below the heading, providing
context before the section listings.

Without explicit `sections`, sections are auto-generated from your package's public API. You can
also combine `title`/`desc` with explicit section ordering using a `sections` key:

```{.yaml filename="great-docs.yml"}
reference:
  title: "API Reference"
  desc: "Complete reference for all public symbols."
  sections:
    - title: Core
      desc: Primary classes
      contents:
        - MyClass
        - Config
    - title: Utilities
      desc: Helper functions
      contents:
        - format_output
        - parse_input
```

If neither `title` nor `desc` is set, the page heading defaults to "Reference" with no introductory
text.

### Controlling Method Documentation

By default, class methods are documented inline on the class page. To exclude methods from
documentation (for example, if you want to document them separately elsewhere), use
`members: false`:

```{.yaml filename="great-docs.yml"}
reference:
  - title: Core Classes
    desc: Main classes for the package
    contents:
      - name: MyClass
        members: false       # Don't document methods here
      - SimpleClass          # Methods documented inline (default)

  - title: MyClass Methods
    desc: Methods for the MyClass class
    contents:
      - MyClass.method1
      - MyClass.method2
```

When `members: false` is set, only the class itself is documented. You can then place individual
methods wherever you want in your reference structure.

### Documenting Inherited Methods

By default, only methods defined directly on a class are documented. Inherited methods are excluded
unless you opt in. This keeps reference pages focused and avoids duplicating parent class methods on
every child page (especially important in deep class hierarchies where it would add significant
clutter).

If your class hierarchy uses inheritance and you want child classes to show inherited methods, there
are two approaches.

**Explicit member list.** List the methods you want documented (including inherited ones) in the
`members` key:

```{.yaml filename="great-docs.yml"}
reference:
  - title: API
    contents:
      - BaseProcessor
      - name: AdvancedProcessor
        members:
          - process        # own method
          - validate       # inherited from BaseProcessor
          - reset          # inherited from BaseProcessor
```

This gives you full control over which inherited methods appear and in what order.

**Auto-include inherited methods.** Use `include_inherited: true` to automatically document all
inherited methods without listing them explicitly:

```{.yaml filename="great-docs.yml"}
reference:
  - title: Shapes
    contents:
      - Shape
      - name: Circle
        include_inherited: true  # includes area(), perimeter(), describe() from Shape
```

With this flag, the child class page will show its own methods plus all public methods inherited
from parent classes.

::: {.callout-tip}
You can combine both approaches. Use `include_inherited: true` for convenience, or provide an
explicit `members` list when you want to cherry-pick specific inherited methods or control ordering.
:::

### Excluding Items with `exclude`

To exclude items from documentation, add them to the `exclude` list in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
exclude:
  - internal_helper
  - deprecated_function
```

Items in the exclude list won't appear when running `great-docs init` or `great-docs scan`, and
won't be documented even if discovered.

## Source Code Links

Great Docs automatically adds "source" links to each documented item, pointing to the exact line
numbers on GitHub.

### How It Works

1. Great Docs detects your GitHub repository from `pyproject.toml` or `.git`
2. For each documented item, it finds the source file and line numbers
3. Links are generated pointing to `github.com/owner/repo/blob/branch/file#L1-L10`

Source links let readers jump straight from the documentation to the implementation, which is
especially valuable during code reviews and debugging.

### Configuration

```{.yaml filename="great-docs.yml"}
source:
  # Use a specific branch (default: auto-detected)
  branch: main

  # Disable source links
  enabled: false
```

## Submodule Introspection

When your package exports submodules (e.g., `dateutil.parser`, `dateutil.tz`), Great Docs
automatically drills into each module to discover its public classes, functions, and constants. This
means you can list a module name in your `reference` config and Great Docs will expand it into all
of its individual members.

For example, if your package exports a `parser` submodule containing a `parse()` function, a
`parser` class, and a `ParserError` exception, writing:

```{.yaml filename="great-docs.yml"}
reference:
  - title: Parser
    desc: Date string parsing
    contents:
      - parser
```

will automatically expand to document `parser.parse`, `parser.parser`, `parser.ParserError`, and all
other public members of the `parser` module. Each member is classified into the correct object type
and receives appropriate visual treatment.

This is particularly useful for packages like `dateutil` that organize their API into topical
submodules rather than exporting everything from the top-level `__init__.py`.

## Cross-Referencing

Great Docs includes a linking system (GDLS) that automatically creates clickable navigation between
your API reference pages. It supports `%seealso` directives in docstrings, inline interlinks using
Markdown syntax, and automatic code-to-link conversion for inline code that matches documented
symbols.

See [Cross-Referencing](cross-referencing.qmd) for the full guide to all linking features.

## Docstring Directives

Great Docs directives add document structure and control API-reference behavior. Write directives
as `%<directive>` in NumPy-, Google-, or Sphinx-style docstrings.

Great Docs supports two kinds of directives:

- `%nodoc` excludes an object, and `%seealso` adds cross-references.
- Callout directives add version annotations and admonitions.

### Callout Directives

Short callouts can put their content on the directive line:

```python
%warning This operation modifies the input.
%versionadded 2.0
%deprecated 3.0 Use `new_function` instead.
```

For longer content, indent the body below the directive:

```python
%versionchanged 2.1
    Now returns a copy.

%warning
    This operation modifies the input.

    Make a copy first if mutation is undesirable.
```

An inline body may also continue on indented lines. Great Docs preserves Markdown and paragraph
breaks within the body. Version directives use the first argument as the version and the remaining
content as the optional description.

| Directive | Appearance |
| --- | --- |
| `%versionadded 2.0` | Quarto `note` callout titled "Added in version 2.0" |
| `%versionchanged 3.1` | Quarto `note` callout titled "Changed in version 3.1" |
| `%deprecated 2.6` | Quarto `warning` callout titled "Deprecated since version 2.6" |
| `%note ...` | Quarto `note` callout |
| `%warning ...` | Quarto `warning` callout |
| `%caution ...` | Quarto `caution` callout |
| `%danger ...` | Quarto `important` callout |
| `%important ...` | Quarto `important` callout |
| `%tip ...` | Quarto `tip` callout |
| `%hint ...` | Quarto `tip` callout |

### Sphinx Compatibility

With `parser: sphinx`, Great Docs also recognises these equivalent reStructuredText
directives:

```rst
.. versionadded:: 2.0

.. versionchanged:: 2.1

    Now returns a copy.

.. warning:: This operation modifies the input.
```

Both forms produce the same callouts. Use `parser: sphinx` when docstrings must build
with both Great Docs and Sphinx. Otherwise, use Great Docs `%` directives.

### Sphinx Cross-Reference Roles

With `parser: sphinx`, Great Docs renders Sphinx roles such as `:py:class:`, `:func:`, and
`:exc:` as inline code. For example, `` :py:exc:`ValueError` `` renders as `ValueError`,
and `` :py:class:`datetime.datetime` `` renders as `datetime.datetime`. Function and
method roles gain trailing parentheses: `` :func:`my_function` `` renders as
`my_function()`, and `` :meth:`MyClass.run` `` renders as `MyClass.run()`.

With `parser: numpy` or `parser: google`, these roles render as literal text. To link to
another symbol with any parser, use `%seealso` or an inline interlink. See
[Cross-Referencing](cross-referencing.qmd).

## Visual Enhancements

Great Docs applies consistent styling to your API documentation, making it easier to scan and
understand at a glance.

### Type Labels {#type-labels}

Each documented item displays a colored badge indicating its object type:

| Type | Color | Used For |
| --- | --- | --- |
| **class** | Indigo | Classes, dataclasses, protocols, ABCs, named tuples, typed dicts |
| **exception** | Red | Exception classes |
| **enum** | Indigo | Enum types |
| **function** | Violet | Functions (shown with trailing `()`) |
| **method** | Cyan | Class methods (shown as `Class.method()`) |
| **constant** | Amber | Module-level constants |
| **type alias** | Green | Type alias definitions |
| **other** | Gray | Uncategorized exports |

Great Docs uses a metadata file (`_object_types.json`) generated during the build to determine the
correct badge for each item. This ensures accurate classification even for edge cases like constants
that start with an uppercase letter or functions named after classes.

### Code Styling

The documentation applies careful typography to code elements throughout. Function signatures use
monospace fonts for clarity, and type annotations are formatted to be easily readable. Parameter
lists have improved spacing that makes long signatures scannable. Code blocks benefit from enhanced
syntax highlighting that matches the overall site theme. Together, these refinements make technical
content more approachable.

### Responsive Design

API documentation needs to work on devices of all sizes, from large desktop monitors to phones.
Great Docs optimizes the layout for each screen size with mobile-friendly navigation that adapts to
touch interactions. The sidebar becomes collapsible on smaller screens, and typography scales
appropriately to remain readable. Whether you're at your desk or reviewing docs on your phone during
a commute, the experience remains consistent.

## Sidebar Filter

For packages with many exports, navigating the sidebar can become cumbersome. Great Docs addresses
this with a built-in search filter that appears automatically when your API has 20 or more items.

The filter provides instant results as you type, narrowing down the sidebar to show only matching
items. A count indicator shows how many items match your search out of the total. The section
structure is preserved during filtering, so you maintain context about where items live in your API
hierarchy.

You can customize when the filter appears in your `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sidebar_filter:
  enabled: true
  min_items: 15   # Show filter with 15+ items
```

Set `enabled: false` to disable it entirely, or adjust `min_items` to change the threshold.

## Refreshing API Documentation

When your package's API changes, rebuild with:

```{.bash filename="Terminal"}
great-docs build
```

This automatically re-discovers exports and updates the configuration.

For faster builds when only documentation content changed (not API):

```{.bash filename="Terminal"}
great-docs build --no-refresh
```

Either way, the rendered output reflects the current state of your package. You never need to
manually edit generated reference pages.

## Migrating from quartodoc

If you have an existing site built with [quartodoc](https://machow.github.io/quartodoc/), switching
to Great Docs is straightforward. The two tools share similar ideas (sections, contents lists,
Quarto rendering) but differ in where configuration lives and how much you need to specify by hand.

### Key Differences

| | **quartodoc** | **Great Docs** |
| --- | --- | --- |
| Config file | `_quarto.yml` (under a `quartodoc:` key) | `great-docs.yml` |
| API discovery | Manual: you list every object | Automatic: discovers your public API from source |
| Build command | `quartodoc build` then `quarto render` | `great-docs build` (handles both steps) |
| Preview command | `quarto preview` | `great-docs preview` |
| Generated output | `reference/` directory with `.qmd` files and `_sidebar.yml` | `great-docs/` directory (ephemeral, gitignored) |
| Sidebar | You include a generated `_sidebar.yml` via `metadata-files` | Managed automatically |

### Step-by-Step Migration

1. **Install Great Docs** and run `great-docs init` in your project root. This auto-discovers your
   package and creates `great-docs.yml`.

2. **Translate your reference layout.** The `sections` structure maps almost directly. A quartodoc
   config like this:

   ```{.yaml filename="_quarto.yml (quartodoc)"}
   quartodoc:
     package: my_package
     sections:
       - title: Core
         desc: Primary interface
         contents:
           - MyClass
           - helper_function
       - title: Utilities
         desc: Utility helpers
         contents:
           - format_output
   ```

   becomes this in Great Docs:

   ```{.yaml filename="great-docs.yml"}
   reference:
     sections:
       - title: Core
         desc: Primary interface
         contents:
           - MyClass
           - helper_function
       - title: Utilities
         desc: Utility helpers
         contents:
           - format_output
   ```

   The section structure (`title`, `desc`, `contents`) is the same and you just move it from
   `quartodoc.sections` in `_quarto.yml` to `reference.sections` in `great-docs.yml`.

   One syntax difference: quartodoc uses `members: []` (an empty list) to suppress inline method
   documentation on a class, while Great Docs uses `members: false`. So a quartodoc entry like:

   ```yaml
   - name: MyClass
     members: []
   ```

   becomes:

   ```yaml
   - name: MyClass
     members: false
   ```

3. **Move your user guide pages.** If you have narrative `.qmd` files (tutorials, guides, etc.),
   move them into a top-level `user_guide/` directory. Great Docs expects user guide content there
   rather than scattered alongside `_quarto.yml`. See [User Guides](user-guides.qmd) for naming
   conventions and sidebar ordering.

4. **Clean up quartodoc artifacts.** Great Docs generates its own `_quarto.yml` inside the
   ephemeral `great-docs/` build directory on every build, so you don't need to edit or keep your
   old `_quarto.yml`. The main thing to do is delete the `reference/` directory that quartodoc
   generated (but check it first for any hand-written `.qmd` content you want to migrate into
   your `user_guide/` directory or `great-docs.yml` reference config).

5. **Build and preview.** Run `great-docs build` followed by `great-docs preview`. Your reference
   pages should render with the same content, now with Great Docs' enhanced styling and features.

## Next Steps

Great Docs handles the tedious parts of API documentation (discovery, classification, layout,
linking) so you can focus on writing clear docstrings. Whether your package exports a handful of
functions or hundreds of classes, the reference section stays organized and up to date.

- [Writing Docstrings](writing-docstrings.qmd) covers docstring format, sections, executable
examples, and `%nodoc`
- [Cross-Referencing](cross-referencing.qmd) covers the full linking system (GDLS) for connecting
API pages
- [CLI Documentation](cli-documentation.qmd) covers Click CLI documentation
- [User Guides](user-guides.qmd) explains how to add narrative documentation
- [Configuration](configuration.qmd) covers all `great-docs.yml` options


# CLI Documentation

Great Docs can generate reference pages for command-line interfaces automatically. Each command and
subcommand gets its own structured page showing the usage signature, description, typed options, and
examples, all using the same layout as API reference pages.

Three CLI ecosystems are supported:

- **Python** (Click): introspects Click commands at import time
- **Go** (Cobra, urfave/cli): compiles the Go binary and extracts `--help` output
- **Rust** (clap, structopt, argh): compiles via `cargo build` and extracts `--help` output

The Go and Rust pipelines work the same way: build the binary, run it with `--help` recursively on
every subcommand, parse the output, and generate the same structured pages as the Python pipeline.
This means your CLI documentation stays perfectly in sync with your code regardless of language.

This page covers each ecosystem in turn: how to enable it, how discovery works, and how to write
help text that produces clear reference pages.

## Python CLI (Click) {#python-cli}

### Enabling Python CLI Documentation

Add the following to your `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
```

With this single setting, Great Docs handles the rest: it finds your Click commands, captures their
help output, and generates reference pages during every build. No additional configuration is needed
for standard project layouts.

### How It Works

When CLI documentation is enabled, Great Docs runs a pipeline that mirrors how it handles API
documentation: discover, extract, generate, and integrate. Here's what happens during each build:

1. **Finds your CLI**: looks for Click commands in common locations
2. **Discovers entry point**: reads `[project.scripts]` from `pyproject.toml`
3. **Extracts metadata**: introspects each command for its description, options, arguments,
   subcommands, and examples
4. **Generates structured pages**: creates `.qmd` files in `reference/cli/` with the same layout
   as API reference pages
5. **Updates navigation**: adds a CLI section to the sidebar

The pipeline runs as part of `great-docs build`, so CLI pages are always regenerated from the
current state of your code. You never need to update them manually.

### Auto-Discovery

Most Click-based packages follow a handful of common patterns for where the CLI entry point lives.
Great Docs checks these locations automatically, so you rarely need to tell it where to look:

1. `your_package.cli`: the most common location
2. `your_package.__main__`: for `python -m your_package` support
3. `your_package.main`: alternative location
4. entry point module from `[project.scripts]`

Great Docs tries each location in order and uses the first one that contains a Click command.

If you have a `[project.scripts]` section:

```{.toml filename="pyproject.toml"}
[project.scripts]
my-cli = "my_package.cli:main"
```

Great Docs uses `my-cli` as the command name in documentation.

### Explicit Configuration

If your CLI lives in a non-standard location, or if auto-discovery picks up the wrong command
object, you can specify the module and command name explicitly in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: my_package.commands   # Module containing Click commands
  name: app                      # Name of the Click command object
```

The `module` value should be the dotted import path to the Python module containing your Click group
or command. The `name` value is the variable name of the Click command object within that module.
With explicit configuration, Great Docs skips auto-discovery entirely and goes straight to the
specified location.

### Writing Good Click Help

The quality of your CLI documentation depends on the help text you write in your Click decorators
and docstrings. Great Docs parses your docstrings into structured sections, so following a few
conventions produces the best results.

Every Click command should have a docstring that explains what it does. The first paragraph becomes
the **subject** (displayed prominently at the top of the page), and remaining paragraphs form the
**extended description**:

```{.python filename="cli.py"}
@click.command()
@click.argument("path")
@click.option("--output", "-o", help="Output directory for generated files")
@click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
def build(path, output, verbose):
    """Build the project at PATH.

    This command compiles all source files and generates output
    in the specified directory. Use --verbose to see detailed
    progress information.
    """
    ...
```

The first paragraph is especially important because it also appears as the short description in
the parent group's **Commands** list and in search results.

**Document all options.** Every `@click.option()` should include a `help=` string. Options without
help text appear in the reference page but give readers no indication of what they do. Use single
quotes around file names or values to have them rendered as inline code:

```{.python filename="cli.py"}
@click.option(
    "--format",
    type=click.Choice(["json", "yaml", "toml"]),
    default="json",
    help="Output format (default: json)"
)
@click.option(
    "--config",
    help="Path to config file (default: 'pyproject.toml')"
)
```

In the generated page, `'pyproject.toml'` in the second option's help text becomes inline code
automatically, so the rendered description reads "Path to config file (default: `pyproject.toml`)".

**Use Click groups for subcommands.** If your CLI has multiple commands, use a `@click.group()` to
organize them. Great Docs generates a separate page for each subcommand and links them together in
the sidebar:

```{.python filename="cli.py"}
@click.group()
def cli():
    """My CLI application for managing projects."""
    pass

@cli.command()
def init():
    """Initialize a new project."""
    ...

@cli.command()
def build():
    """Build the project."""
    ...
```

Well-structured Click groups produce the clearest documentation. Each subcommand becomes its own
page, and the group's docstring serves as the overview for the CLI section.

**Include examples.** If your docstring contains a paragraph starting with `Examples:`, Great Docs
extracts it into a dedicated **Examples** section rendered as a `bash` code block. Use Click's `\b`
marker to prevent paragraph rewrapping:

```{.python filename="cli.py"}
@click.command()
def deploy():
    """Deploy the built site.

    Uploads the contents of _site/ to your configured host.

    \b
    Examples:
      my-cli deploy                  # Deploy to production
      my-cli deploy --dry-run        # Preview what would happen
      my-cli deploy --target staging # Deploy to staging
    """
    ...
```

Without the `\b` marker, Click joins continuation lines into a single paragraph, which would
collapse the example lines together. Always place `\b` on its own line before `Examples:` to
preserve the formatting.

### Example: Great Docs CLI

Great Docs uses this feature to document its own CLI. Here's what the generated page for
`great-docs build` looks like (simplified):

**Subject and usage:**

> Build your documentation site.

```bash
great-docs build [OPTIONS]
```

**Extended description (formatted as prose):**

> Requires `great-docs.yml` to exist (run `great-docs init` first). This is the only command you
> need day-to-day and in CI.

**Collapsible `--help` output:**

The full raw terminal output is available inside a disclosure widget labeled "Full --help output".
Readers can expand it when they want the complete reference, but it doesn't dominate the page.

**Options (structured definition list):**

| Option | Type | Description |
|--------|------|-------------|
| `--watch` | flag | Watch for changes and rebuild automatically |
| `--no-refresh` | flag | Skip re-discovering package exports |
| `--versions` | TEXT | Build only specific versions (comma-separated) |
| `--from-repo` | TEXT | Clone a remote Git repository and build its docs |

**Examples (bash code block):**

```bash
great-docs build                      # Full build with API refresh
great-docs build --no-refresh         # Fast rebuild (skip API discovery)
great-docs build --watch              # Rebuild on file changes
```

The main group page (`great-docs`) additionally includes a **Commands** section that links to each
subcommand's dedicated page. You can see these pages live in the Great Docs reference section.
All of these sections are generated from the same Click decorators and docstrings shown earlier
in this guide.

## Go CLI (Cobra) {#go-cli}

Great Docs can document Go CLI projects that use [Cobra](https://github.com/spf13/cobra),
[urfave/cli](https://github.com/urfave/cli), or any framework whose `--help` output follows the
standard Cobra convention. The process is fully automatic: Great Docs compiles the Go binary, runs
it with `--help`, and parses the output into structured reference pages.

### Enabling Go CLI Documentation

Set `project_type` to `go` (or include `go` in a list for mixed projects) and enable `go_cli`:

```{.yaml filename="great-docs.yml"}
project_type: go
go_cli:
  enabled: true
```

This requires `go` to be on your `PATH`. Great Docs compiles the binary to a temporary directory
during each build, so the project tree is never modified.

### Project Detection

Great Docs recognizes a Go CLI project when it finds:

1. A `go.mod` file at the project root
2. At least one main package in a standard layout:
   - `cmd/<name>/main.go` (multi-binary layout, most common)
   - `cmd/main.go` (single binary under `cmd/`)
   - `main.go` (flat layout)

The binary name is inferred from the directory name (for `cmd/<name>/`) or from the module path
(for flat layouts).

### How It Works

During each build:

1. **Detects the project**: reads `go.mod` for the module path, locates the main package
2. **Compiles the binary**: runs `go build` to a temporary directory
3. **Extracts the command tree**: runs `<binary> --help` and parses subcommands recursively
4. **Generates pages**: creates the same structured `.qmd` pages as the Python CLI pipeline
5. **Updates navigation**: adds a CLI section to the sidebar

Cobra's help format uses `Available Commands:` and `Flags:` sections. Great Docs parses these
automatically, including custom command groups defined with `AddGroup()`.

## Rust CLI (clap) {#rust-cli}

Great Docs can document Rust CLI projects that use [clap](https://docs.rs/clap/),
[structopt](https://docs.rs/structopt/), [argh](https://docs.rs/argh/), or any framework whose
`--help` output follows standard conventions. Like the Go pipeline, the process is fully automatic:
Great Docs compiles the Rust binary via `cargo build`, runs it with `--help`, and parses the output
into structured reference pages.

### Enabling Rust CLI Documentation

Set `project_type` to `rust` and enable `rust_cli`:

```{.yaml filename="great-docs.yml"}
project_type: rust
rust_cli:
  enabled: true
```

This requires `cargo` to be on your `PATH`. Great Docs compiles a release binary to a temporary
directory during each build, so the project tree is never modified.

### Project Detection

Great Docs recognizes a Rust CLI project when it finds:

1. A `Cargo.toml` at the project root with a `[package]` section
2. At least one binary target:
   - Explicit `[[bin]]` sections in `Cargo.toml`
   - `src/main.rs` (Cargo's default binary target, named after the package)

For projects that produce multiple binaries (like separate `ir` and `rx` binaries), Great Docs
documents the first binary listed.

### How It Works

During each build:

1. **Detects the project**: reads `Cargo.toml` for the package name and binary targets
2. **Compiles the binary**: runs `cargo build --release` with a temporary `--target-dir`
3. **Extracts the command tree**: runs `<binary> --help` and parses subcommands recursively
4. **Generates pages**: creates the same structured `.qmd` pages as the Python and Go pipelines
5. **Updates navigation**: adds a CLI section to the sidebar

clap's help format uses `Commands:` and `Options:` sections. Great Docs parses these automatically,
including nested subcommand groups (e.g., `yamark git-filter clean`), positional arguments, default
values in `[default: ...]` brackets, and flags with no description text.

### Writing Good `--help` Text

The quality of generated documentation depends directly on your `--help` output. For clap-based
projects using the derive API:

- **Add `about` or `long_about`** to every command and subcommand via the `#[command(...)]`
attribute or doc comments. The description text becomes the page's subject and extended description.
- **Add `help` to every argument and option** via `#[arg(help = "...")]` or doc comments. Options
without help text still appear on the page but give readers no context.
- **Use `after_help`** for examples. clap renders this after the options list, and Great Docs
captures it in the full `--help` output shown in the collapsible disclosure widget.

```{.rust filename="src/cli.rs"}
/// Format YAML and Markdown files.
///
/// Reads files from the given paths and writes formatted output.
/// When no paths are given, reads from standard input.
#[derive(Parser)]
struct Cli {
    /// Enable check mode (exit 1 if files would change)
    #[arg(long)]
    check: bool,

    /// Output width for prose wrapping
    #[arg(long, default_value_t = 72)]
    wrap: usize,

    /// Files to format
    paths: Vec<PathBuf>,
}
```

### Mixed Projects

For projects that include both a Rust CLI and a Python package (e.g., a Rust binary with Python
bindings), use a list for `project_type`:

```{.yaml filename="great-docs.yml"}
project_type: [python, rust]
rust_cli:
  enabled: true
```

This enables both the Python API reference and the Rust CLI reference. The generated site shows
both sections in the Reference sidebar.

## Generated Output

Regardless of which ecosystem your CLI uses, Great Docs generates the same structured pages.

### Sidebar Structure

CLI commands appear in the Reference sidebar:

```
Reference
├── API
│   └── (your classes and functions)
└── CLI
    ├── my-cli (main command)
    ├── my-cli build
    ├── my-cli deploy
    └── my-cli config
```

### Page Format

Each CLI page uses the same structured layout as API reference pages, making the site feel cohesive.
A generated page contains these sections in order:

1. **Title** with a colored label badge (`cli` or `cli-group`)
2. **Subject**: the first paragraph of the description (the short description)
3. **Usage signature**: a `bash` code block showing the invocation pattern
4. **Extended description**: remaining paragraphs, formatted as prose
5. **Collapsible `--help` output**: the full raw `--help` text, tucked inside a disclosure widget
6. **Arguments**: if the command takes positional arguments
7. **Options**: a definition list with name, type, default, and help text
8. **Subcommands**: for groups, each subcommand links to its own page
9. **Examples**: if the help text includes an `Examples:` section

This structured layout gives readers quick access to what they need (usage, options, examples) while
preserving the full `--help` output for those who want the raw reference.

### Text Enhancements

Within the description and option help text, Great Docs automatically applies two enhancements:

- **Single-quoted text -> code**: `'great-docs build'` in your help text renders as
`great-docs build` in inline code
- **Option names -> code**: references to options like `--watch` or `--from-repo` are rendered as
inline code automatically

These enhancements are applied automatically during page generation. You don't need to use backticks
or any special markup in your help strings.

## Styling

CLI reference pages share the same visual system as API reference pages:

- **Colored label badges**: `cli` (blue) and `cli-group` (teal) distinguish commands from groups
- **Structured definition lists**: options are displayed with the same parameter styling used for
  function signatures in API docs
- **Consistent layout**: subject, signature, description, and parameters mirror the API page
  structure
- **Responsive design**: pages adapt to mobile and desktop viewports
- **Collapsible details**: the raw `--help` output is available but doesn't clutter the page

This shared design language means readers moving between API docs and CLI docs see the same
patterns: a short subject at the top, a signature block, extended prose, and a structured parameter
list.

## Troubleshooting

### Python CLI Not Detected

If your Click CLI isn't found:

1. verify Click is installed
2. check the module path is correct
3. ensure the Click command is importable
4. use explicit configuration:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: your_package.cli
  name: cli   # The Click command object name
```

### Go or Rust CLI Not Detected

If your Go or Rust CLI isn't found:

1. verify the compiler is on `PATH` (`go` or `cargo`)
2. check that `go.mod` or `Cargo.toml` exists at the project root
3. ensure there is a binary entry point (`main.go` or `src/main.rs`)
4. check the build log for compilation errors

### Help Text Missing

If commands show minimal help:

- **Python**: add docstrings to Click functions and `help=` to all options
- **Go**: add descriptions to Cobra commands via `Short` and `Long` fields
- **Rust**: add doc comments or `#[arg(help = "...")]` to clap structs

The generated page will still show the command's usage signature and options, but the description
sections will be empty without help text.

## Next Steps

CLI documentation works best when your commands have good help text. Great Docs takes what you've
written and turns it into browsable, searchable reference pages that stay in sync with your code.

- [User Guides](08-user-guides.qmd) explains how to add narrative documentation
- [Deployment](14-deployment.qmd) covers publishing to GitHub Pages


# User Guides

API reference pages are valuable, but they only describe individual functions and classes in
isolation. For users to truly understand your project, they need narrative documentation:
tutorials that walk them through real tasks, guides that explain concepts in context, and
explanations that connect the pieces together. Without this kind of content, users are left to
figure out the bigger picture on their own.

Great Docs treats user guides as first-class content. When you add a `user_guide/` directory to
your project, Great Docs automatically generates sidebar navigation, adds a navbar link, applies
narrative-optimized styling, and keeps everything in sync across builds. You write Quarto Markdown
files and Great Docs handles the rest.

## Creating a User Guide

Getting started takes just three steps:

1. create a `user_guide/` directory in your project root
2. add `.qmd` files for each page
3. run `great-docs build`

Great Docs automatically:

- copies files to `great-docs/user-guide/`
- generates sidebar navigation
- adds a "User Guide" link to the navbar
- organizes pages into sections

No additional configuration is required. As soon as Great Docs finds `.qmd` files in the
`user_guide/` directory, the User Guide section appears in your site.

## Directory Structure

A typical project with a User Guide looks like this:

```{.default filename="Project structure"}
your-project/
├── great-docs/              # Build directory (ephemeral, gitignored)
│   ├── user-guide/          # Copied from user_guide/
│   └── ...
├── user_guide/              # Your source files (committed to git)
│   ├── 00-introduction.qmd
│   ├── 01-installation.qmd
│   ├── 02-quickstart.qmd
│   ├── 03-configuration.qmd
│   └── images/              # Asset directories are copied too
│       └── screenshot.png
├── great-docs.yml
├── pyproject.toml
└── your_package/
```

The `user_guide/` directory is the default location. You can use a
[custom directory](#custom-user-guide-directory) by setting `user_guide` in `great-docs.yml`.

## Page Ordering

The order of pages in the sidebar matters for guiding readers through your content in a logical
sequence. Files are sorted alphabetically by filename, so numeric prefixes give you full control
over the ordering:

```{.default filename="user_guide/"}
user_guide/
├── 00-introduction.qmd    # First
├── 01-installation.qmd    # Second
├── 02-getting-started.qmd # Third
└── 03-advanced.qmd        # Fourth
```

The prefix is stripped from the title, so `01-installation.qmd` becomes "Installation" in the
navigation. This means you can reorder pages at any time by renaming files without affecting how
titles appear in the sidebar.

## Organizing into Sections

As your user guide grows, flat lists of pages become hard to navigate. Sections let you group
related pages together so readers can find what they need and understand how topics relate to each
other.

The simplest approach is the `guide-section` frontmatter key:

```{.yaml filename="01-installation.qmd"}
---
title: "Installation"
guide-section: "Getting Started"
---
```

Pages with the same `guide-section` value are grouped together in the sidebar:

```{.default filename="Sidebar navigation"}
User Guide
├── Getting Started
│   ├── Introduction
│   └── Installation
├── Core Concepts
│   ├── Configuration
│   └── API Documentation
└── Advanced
    └── Customization
```

This grouping is purely visual in the sidebar. The pages themselves remain as flat files in the
`user_guide/` directory.

### Section Order

Sections appear in the order they're first encountered (based on file sort order). To control
section order, ensure the first file in each section has the appropriate prefix:

```{.default filename="user_guide/"}
user_guide/
├── 00-introduction.qmd      # guide-section: "Getting Started"
├── 01-installation.qmd      # guide-section: "Getting Started"
├── 10-configuration.qmd     # guide-section: "Core Concepts"
├── 11-api-docs.qmd          # guide-section: "Core Concepts"
├── 20-customization.qmd     # guide-section: "Advanced"
```

### Subdirectory-Based Sections

For larger user guides, you may prefer organizing pages into actual subdirectories rather than using
frontmatter. Each
subdirectory becomes a section in the sidebar, with the section title derived from the
subdirectory's `index.qmd` title (or the directory name if there is no `index.qmd`):

```{.default filename="user_guide/"}
user_guide/
├── index.qmd                        # Root page (appears first in sidebar)
├── getting-started/
│   ├── index.qmd                    # Section title: "Getting Started"
│   ├── installation.qmd
│   └── quickstart.qmd
└── advanced/
    ├── index.qmd                    # Section title: "Advanced Usage"
    ├── configuration.qmd
    └── deployment.qmd
```

This produces a sidebar like:

```{.default filename="Sidebar navigation"}
User Guide
├── User Guide           # Root index.qmd
├── Getting Started
│   ├── Installation
│   └── Quickstart
└── Advanced Usage
    ├── Configuration
    └── Deployment
```

A root-level `index.qmd` is recommended so the "User Guide" navbar link has a landing page.
Subdirectory `index.qmd` files provide section titles but don't appear as separate pages in the
sidebar. Rather, their title is used as the collapsible section heading.

Subdirectories are sorted alphabetically by directory name. To control the order of sections and
pages within them, use numeric prefixes. They are stripped from both directory names and filenames
in URLs and navigation:

```{.default filename="user_guide/"}
user_guide/
├── index.qmd
├── 01-getting-started/
│   ├── index.qmd                    # Section title: "Getting Started"
│   ├── 01-installation.qmd
│   └── 02-quickstart.qmd
├── 02-guides/
│   ├── index.qmd                    # Section title: "Guides"
│   ├── 01-configuration.qmd
│   └── 02-troubleshooting.qmd
└── 03-advanced/
    ├── index.qmd                    # Section title: "Advanced"
    └── 01-deployment.qmd
```

The prefixes control ordering but don't appear in the output:

- `01-getting-started/` → `getting-started/` in URLs
- `01-installation.qmd` → `installation.html` in rendered pages
- Numbering restarts at `01-` in each subdirectory

This pattern gives you full control over section and page order while keeping URLs clean.

The subdirectory approach works well for larger user guides where the directory structure itself
communicates the organization, while `guide-section` frontmatter is better suited for flat file
layouts.

### Mixing Root Files and Subdirectories

You can mix root-level files with subdirectory sections in the same user guide. Numeric prefixes
sort them together so the nav order follows the prefix regardless of whether an item is a file or a
directory:

```{.default filename="user_guide/"}
user_guide/
├── 01-overview.qmd              # Page: Overview
├── 02-concepts/
│   ├── index.qmd                # Section title: "Concepts"
│   └── details.qmd
└── 03-quickstart.qmd            # Page: Quickstart
```

This produces a sidebar that interleaves files and sections in prefix order:

```{.default filename="Sidebar navigation"}
User Guide
├── Overview
├── Concepts
│   └── Details
└── Quickstart
```

A root-level `index.qmd` always appears first regardless of its prefix.

::: {.callout-warning}
Avoid giving a root file and a subdirectory the same base name (e.g., `02-concepts.qmd` alongside
`02-concepts/`). After numeric prefixes are stripped from URLs, both would map to the same
`concepts` path, which causes duplicate entries in the sidebar.
:::

## Writing Pages

User Guide pages are standard Quarto Markdown files, which means you have access to all of Quarto's
powerful features for creating rich, interactive documentation. Here are some of the most useful
features for writing guides.

### Basic Frontmatter

Every User Guide page needs frontmatter at the top to define its title and section. The `title`
appears in the sidebar navigation and as the page heading, while `guide-section` determines which
group the page belongs to:

```{.yaml filename="your-page.qmd"}
---
title: "Your Page Title"
guide-section: "Section Name"
---
```

### Code Blocks

Code blocks with syntax highlighting are essential for technical documentation. Specify the language
after the opening backticks to enable highlighting:

````markdown
```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.build()
```
````

Quarto supports syntax highlighting for dozens of languages including Python, JavaScript,
TypeScript, R, Bash, YAML, TOML, and many more.

For Python code that you want to actually execute and show the output, use `{python}` instead of
just `python`. You can control execution behavior with hash-pipe options at the top of the code
block. Some useful hash-pipe options include:

- `#| echo: false`: hide the code, show only output
- `#| eval: false`: show the code but don't run it
- `#| output: false`: run the code but hide output
- `#| warning: false`: suppress warning messages
- `#| fig-cap: "Caption"`: add a caption to figure output

### Tabsets

Tabsets let you present alternative content (like code in multiple languages or instructions for
different platforms) without cluttering the page. Readers can click to switch between tabs:

````markdown
::: {.panel-tabset}

## Python

```python
print("Hello")
```

## JavaScript

```javascript
console.log("Hello");
```

:::
````

This is particularly useful for showing installation commands for different operating systems or
demonstrating concepts in multiple programming languages.

### Callouts

Callouts draw attention to important information. Use them sparingly to highlight notes, warnings,
or tips that readers shouldn't miss:

```markdown
::: {.callout-note}
This is a note.
:::

::: {.callout-warning}
This is a warning.
:::

::: {.callout-tip}
This is a tip.
:::
```

Each callout type has distinct styling. Notes are informational, warnings alert readers to potential
issues, and tips offer helpful suggestions.

### Images

Visual content like screenshots, diagrams, and architecture charts can greatly improve
documentation. Store images in a subdirectory to keep your User Guide organized:

```{.default filename="user_guide/"}
user_guide/
├── 01-getting-started.qmd
└── images/
    └── screenshot.png
```

Reference them in your content using standard Markdown image syntax. The alt text in brackets
improves accessibility:

```markdown
![Screenshot](images/screenshot.png)
```

### Cross-References

Link freely between pages to help readers navigate related content. For other User Guide pages, use
relative paths:

```markdown
See the [Installation](installation.qmd) guide for details.
```

To link to API reference pages, use a relative path that goes up one directory level first:

```markdown
See the [GreatDocs](../reference/GreatDocs.qmd) class for the full API.
```

These links are validated during the build, so you'll catch broken references early.

## Asset Directories

User guide pages often need supporting files like images, diagrams, or sample data. Any
subdirectory that doesn't contain `.qmd` files is treated as an asset directory and copied as-is:

```{.default filename="user_guide/"}
user_guide/
├── 01-guide.qmd
├── images/          # Copied to great-docs/user-guide/images/
│   ├── logo.png
│   └── diagram.svg
└── data/            # Copied to great-docs/user-guide/data/
    └── example.json
```

This means you can reference images and other files using simple relative paths (e.g.,
`images/screenshot.png`) in your `.qmd` files, and Great Docs will make sure those files are
available in the built site.

## User Guide Styling

Because user guides serve a different purpose than API references, Great Docs applies different
styling to match. The sidebar filter that helps navigate large API listings is hidden since user
guides are typically smaller and have a clear hierarchical structure. Breadcrumb navigation is also
removed to provide a cleaner reading experience. The sidebar itself uses section-based navigation
that mirrors your `guide-section` organization, making it easy for readers to see where they are
in the guide.

These styling differences are applied automatically. You don't need to configure anything to get
the narrative-optimized layout.

## Example: This User Guide

The User Guide you're reading right now is built with Great Docs, using the same features described
on this page. Here's a representative sample of its structure:

```{.default filename="user_guide/"}
user_guide/
├── 00-introduction.qmd           # Getting Started
├── 01-installation.qmd           # Getting Started
├── 02-quickstart.qmd             # Getting Started
├── 03-authoring-qmd-files.qmd    # Getting Started
├── 04-writing-docstrings.qmd     # Getting Started
├── 05-configuration.qmd          # Config & Theming
├── 06-api-documentation.qmd      # Site Content
├── 07-cli-documentation.qmd      # Site Content
├── 08-user-guides.qmd            # Site Content (this page)
├── ...                           # 26 more pages
└── 35-keyboard-keys.qmd          # Site Content
```

The guide spans 36 pages organized across five sections: Getting Started, Config & Theming, Site
Content, Build & Deploy, and Quality & Maintenance. Numeric prefixes control page order, and
`guide-section` frontmatter handles the grouping.

## Custom User Guide Directory

By default, Great Docs looks for a `user_guide/` directory in your project root. If you need your
User Guide source files in a different location (e.g., inside a `docs/` folder or a monorepo
subdirectory), you can specify a custom path in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
user_guide: docs/guides
```

The path is relative to the project root. Any directory structure works, including nested paths:

```{.yaml filename="great-docs.yml"}
user_guide: content/user-docs
```

### Precedence Rules

If both a `user_guide` config option **and** a conventional `user_guide/` directory exist, the
config option takes precedence and the `user_guide/` directory is ignored. Great Docs will print a
warning to let you know:

```
⚠️  Both 'user_guide' config option ('docs/guides') and 'user_guide/' directory exist; using
configured path
```

### Warnings

Great Docs warns you if the resolved directory:

- **Doesn't exist**: the path specified in `user_guide` couldn't be found
- **Is empty**: the directory exists but contains no files at all
- **Has no `.qmd` files**: the directory exists but doesn't contain any Quarto Markdown files

In all three cases, the User Guide is skipped and processing continues normally.

## Tips

These tips cover common patterns and best practices for maintaining user guides as they grow.

### Keep Source Separate from Output

Whether you use the default `user_guide/` directory or a custom path, Great Docs copies files to
`great-docs/user-guide/` during each build, keeping your source separate from generated output.

### Use Descriptive Titles

The `title` in frontmatter appears in navigation. Make it clear and concise:

```yaml
---
title: "Configuration Options"  # Good
guide-section: "Reference"
---
```

### Organize Logically

Group related content into sections that make sense for your users. A common pattern starts with
"Getting Started" content that covers installation and quick start guides. This is everything new
users need to get up and running. "Core Concepts" sections explain the main features and typical
usage patterns. "Advanced" sections dive into complex topics and customization options for power
users. Finally, a "Reference" section can house configuration options and troubleshooting guides.
Adapt this structure to fit your project's needs.

## Next Steps

User guides bring the narrative depth that API references alone can't provide. With numbered files,
frontmatter sections, and automatic sidebar generation, you can build a structured guide that
grows alongside your project.

- [Custom Sections](custom-sections.qmd) explains how to add entirely new sidebar sections beyond
the User Guide and API reference
- [Cross-Referencing](cross-referencing.qmd) covers linking between User Guide pages and API
reference pages
- [Theming](theming.qmd) lets you customize the look and feel of your entire site, including User
Guide pages
- [Deployment](deployment.qmd) covers publishing your finished documentation to GitHub Pages


# Custom Sections

Great Docs lets you add any number of custom page groups to your documentation site (examples, tutorials, demos, or anything else). Each section gets its own navbar link and sidebar navigation. By default, the navbar links directly to the first page in the section. Set `index: true` to generate a card-based index page instead. For blog-style content, there's a dedicated `type: blog` mode that uses Quarto's native listing directive.

::: {.version-only versions=">=0.6"}
If you need a single hand-written HTML page rather than a section of `.qmd` files, see [Custom Static Pages](custom-pages.qmd). Custom sections and custom static pages are complementary features.
:::

## Quick Start

1. Create a directory in your project root with `.qmd` files:

```
my-package/
├── examples/
│   ├── 01-basic-usage.qmd
│   ├── 02-advanced.qmd
│   └── 03-real-world.qmd
├── great-docs.yml
└── ...
```

2. Add the section to `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples
    dir: examples
```

3. Run `great-docs build`: the Examples link appears in the navbar and the pages are rendered with a sidebar.

## Configuration

Each section is defined as an entry in the `sections` array:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples          # Navbar link text (required)
    dir: examples            # Source directory (required)
    index: true              # Generate card-based index page (optional)
    navbar_after: User Guide  # Insert after this navbar item (optional)
    type: default            # Section type: "default" or "blog" (optional)
```

### Required Fields

| Field   | Description |
|---------|-------------|
| `title` | The text shown in the navbar link and sidebar heading |
| `dir`   | Path to the source directory (relative to project root) |

### Optional Fields

| Field            | Default            | Description |
|------------------|--------------------|-------------|
| `index`          | `false`            | When `true`, auto-generates a card-based index page; when `false`, navbar links to the first page |
| `navbar_after`   | Before "Reference" | Name of an existing navbar item to place this section after |
| `type`           | `default`          | `"default"` for card-grid index with sidebar; `"blog"` for Quarto listing page |

::: {.version-only versions=">=0.7"}
| `index_columns`  | `2`                | Number of columns for image cards on the index page (1 or 2). Only applies when `index: true` [version-badge new 0.7] |
:::

::: {.version-only versions="dev"}
| `dir_titles`     | `{}`               | Mapping of subdirectory names to custom sidebar section titles (see [Subdirectories](#subdirectories)) [version-badge new dev] |
:::

## Multiple Sections

Add as many sections as you need:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples
    dir: examples
  - title: Tutorials
    dir: tutorials
    navbar_after: Examples
  - title: Blog
    dir: blog
    type: blog
    navbar_after: Reference
```

This produces a navbar like:

```
Home | User Guide | Examples | Tutorials | Reference | Blog
```

::: {.callout-tip}
## Blog sections
The `type: blog` option uses Quarto's native listing directive for date-sorted, searchable blog posts. See [Blog](blog.qmd) for the full guide.
:::

## Navbar Positioning

By default, custom sections are inserted **before "Reference"** in the navbar. Use `navbar_after` to control placement:

| `navbar_after` value | Result |
|---------------------|--------|
| *(not set)*         | Before "Reference" |
| `Home`              | After "Home" |
| `User Guide`        | After "User Guide" |
| `Reference`         | After "Reference" |
| `Changelog`         | After "Changelog" |

Sections appear in the order they're listed in the config.

## Page Files

Place `.qmd` or `.md` files in the section directory. Great Docs will:

- **Strip numeric prefixes** from filenames for clean URLs (`01-basic.qmd` → `basic.qmd`)
- **Add `bread-crumbs: false`** to frontmatter automatically
- **Copy all files** to the build directory

### Frontmatter

Each page's YAML frontmatter is used to populate the auto-generated index and the sidebar:

```{.yaml filename="examples/01-basic-usage.qmd"}
---
title: "Basic Usage"
description: "A simple example showing core functionality"
image: "img/basic.png"
---
```

| Field         | Used for |
|---------------|----------|
| `title`       | Sidebar link text, index page heading |
| `description` | Index page summary text |
| `image`       | Index page thumbnail (optional) |

## Index Page

### No Index (Default)

By default, sections do **not** get an index page. The navbar links directly to the first page in the section, and all pages are accessible via the sidebar. This is the simplest setup and works well when pages are self-explanatory.

### Auto-Generated Index

Set `index: true` to generate a gallery-style index page with cards for each page, using each file's `title`, `description`, and `image` from frontmatter:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples
    dir: examples
    index: true
```

The generated index page renders entries in two zones:

1. **Image cards** — pages with an `image` field in frontmatter appear first as clickable cards in a responsive grid. Each card shows the hero image, title, and description.
2. **Plain links** — pages without an `image` field appear below as a single-column list of title + description links.

When both zones are present, a horizontal rule separates them. This design mirrors the pattern used by the [pointblank demos page](https://posit-dev.github.io/pointblank/demos/), where featured items with screenshots sit above a simpler list of additional entries.

::: {.version-only versions=">=0.7"}

#### Controlling Columns

By default, image cards use a **2-column** responsive grid. Set `index_columns: 1` for a single-column layout (useful for wide screenshots or fewer items):

```{.yaml filename="great-docs.yml"}
sections:
  - title: Gallery
    dir: gallery
    index: true
    index_columns: 1
```

::: {.callout-tip}
## Mixed layouts
You can combine both approaches in the same site: a 2-column demos section with featured screenshots alongside a 1-column gallery with full-width images, plus plain text links for supplementary pages that don't need a visual.
:::

:::

#### Example: Featured Demos with Plain Links

Given this directory:

```
demos/
├── 01-starter.qmd       ← Has image: "img/starter.png"
├── 02-advanced.qmd      ← Has image: "img/advanced.png"
├── 03-tips.qmd          ← No image
├── 04-faq.qmd           ← No image
└── img/
    ├── starter.png
    └── advanced.png
```

With this config:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Demos
    dir: demos
    index: true
```

The generated index page shows:

- Two image cards side by side (Starter and Advanced) at the top
- A horizontal rule
- Two plain link entries (Tips and FAQ) in a single-column list below

### Custom Index

If you provide your own `index.qmd` in the directory, Great Docs uses it as-is (regardless of the `index` setting). This gives you full control over the landing page layout as you can write custom HTML, use Quarto grid layouts, or embed interactive content.

```
examples/
├── index.qmd          ← Your custom gallery page
├── 01-basic.qmd
├── 02-advanced.qmd
└── img/
    ├── basic.png
    └── advanced.png
```

## Subdirectories

Sections support nested subdirectories. Files in subdirectories are copied with their relative paths preserved, and each subdirectory becomes a **sidebar section** with its own heading.

```
tutorials/
├── getting-started/
│   ├── installation.qmd
│   └── first-steps.qmd
└── advanced/
    └── custom-config.qmd
```

### Numeric Prefix Stripping

Just like individual files, subdirectory names have numeric prefixes stripped automatically. This lets you control the sort order of sidebar sections while keeping clean display titles:

```
examples/
├── 01-getting-started/
│   ├── installation.qmd
│   └── first-steps.qmd
├── 02-results-and-reporting/
│   ├── basic-report.qmd
│   └── custom-output.qmd
└── 03-advanced-topics/
    └── custom-config.qmd
```

The sidebar displays these as **"Getting Started"**, **"Results And Reporting"**, and **"Advanced Topics"** (not "01 Getting Started", etc.).

::: {.version-only versions="dev"}

### Custom Subdirectory Titles {#custom-subdirectory-titles}

The auto-generated title converts hyphens and underscores to spaces and applies title case. If you need different capitalization or phrasing, use `dir_titles` to override specific subdirectory headings:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Demos
    dir: examples
    index: true
    dir_titles:
      getting-started: "Getting Started"
      results-and-reporting: "Results/Reporting"
      advanced-topics: "Advanced Topics"
```

The keys in `dir_titles` are the subdirectory names **after** numeric prefix stripping (e.g., use `getting-started`, not `01-getting-started`). Any subdirectory not listed in the mapping falls back to the auto-generated title.

::: {.callout-tip}
## When to use `dir_titles`
This is useful when the auto-generated title doesn't match your preferred style — for example, turning "Results And Reporting" into "Results/Reporting", or "Actions And Thresholds" into "Actions & Thresholds".
:::

:::

## Example: Visual Gallery

To create a visual gallery with a hand-crafted index page:

1. Create the directory structure:

```
demos/
├── index.qmd
├── 01-starter/
│   └── index.qmd
├── 02-advanced/
│   └── index.qmd
└── img/
    ├── starter.png
    └── advanced.png
```

2. Write your custom `index.qmd` with a visual grid:

```{.markdown filename="demos/index.qmd"}
---
title: "Examples"
toc: false
---

:::::: {.column-page}
::::: {.grid}

:::{.g-col-lg-6 .g-col-12}
### [Starter](01-starter/index.qmd)
![](img/starter.png){width="100%"}
A validation with the basics.
:::

:::{.g-col-lg-6 .g-col-12}
### [Advanced](02-advanced/index.qmd)
![](img/advanced.png){width="100%"}
A comprehensive example.
:::

:::::
::::::
```

3. Add to config:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples
    dir: demos
```

## Next Steps

Custom sections let you go beyond the standard User Guide and API Reference to organize content in whatever way makes sense for your project. Whether it's a tutorials section, a cookbook, or a gallery of examples, each section gets its own navbar link, sidebar navigation, and optional index page.

- [Blog](blog.qmd) covers setting up a blog with Quarto's listing directive
- [Configuration](configuration.qmd) covers all available `great-docs.yml` options
- [User Guides](user-guides.qmd) covers the User Guide section setup


# Blog

Great Docs supports adding a blog to your documentation site using Quarto's native [listing](https://quarto.org/docs/websites/website-listings.html) feature. Blog posts are automatically sorted by date, display author and category metadata, and include built-in search.

## Quick Start

1. Create a `blog/` directory with each post in its own subdirectory:

```
my-package/
├── blog/
│   ├── welcome-post/
│   │   └── index.qmd
│   └── v0.2-release/
│       └── index.qmd
├── great-docs.yml
└── ...
```

2. Add the blog section to `great-docs.yml` with `type: blog`:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Blog
    dir: blog
    type: blog
```

3. Run `great-docs build`: a **Blog** link appears in the navbar, and the listing page is generated automatically.

## Post Structure

Each blog post lives in its own subdirectory under `blog/`, with an `index.qmd` file containing the post content. This is the same convention used by Quarto's blog projects.

```
blog/
├── welcome-post/
│   ├── index.qmd
│   └── images/
│       └── hero.png       # Post-specific images
├── v0.2-release/
│   └── index.qmd
└── tips-and-tricks/
    └── index.qmd
```

### Post Frontmatter

Each post's `index.qmd` should include frontmatter with metadata that Quarto uses for the listing page:

```{.yaml filename="blog/welcome-post/index.qmd"}
---
title: "Welcome to Our Blog"
author: Vivian Smith
date: 2024-01-15
categories: [announcements, getting-started]
description: "An introduction to us and what we're building."
---
```

| Field          | Required | Description |
|----------------|----------|-------------|
| `title`        | Yes      | Post title, shown in listing and as the page heading |
| `date`         | Yes      | Publication date (`YYYY-MM-DD`); controls sort order |
| `author`       | No       | Author name, displayed in the listing |
| `categories`   | No       | List of tags for filtering posts |
| `description`  | No       | Summary text shown in the listing |
| `image`        | No       | Thumbnail image for the listing card |

## Listing Page

When no `index.qmd` exists at the root of the blog directory, Great Docs auto-generates one using Quarto's `listing:` directive:

```{.yaml}
---
title: "Blog"
listing:
  type: default
  sort: "date desc"
  contents:
    - "**.qmd"
---
```

This produces a listing page that:

- sorts posts by date (newest first)
- shows title, author, date, description, and categories
- includes client-side search across all posts
- links each entry to the full post

### Custom Listing Page

To customize the listing layout, provide your own `blog/index.qmd`. For example, to use a table layout:

```{.yaml filename="blog/index.qmd"}
---
title: "Blog"
listing:
  type: table
  sort: "date desc"
  feed: true
  contents:
    - "**.qmd"
---
```

Quarto supports three listing types:

| Type      | Description |
|-----------|-------------|
| `default` | Card-style listing with thumbnails |
| `grid`    | Grid of equal-sized cards |
| `table`   | Compact table with sortable columns |

See [Quarto Listings](https://quarto.org/docs/websites/website-listings.html) for all options, including custom templates and feeds.

## How It Differs from Default Sections

Blog sections (`type: blog`) differ from default sections in several ways:

| Feature | Default Sections | Blog Sections |
|---------|-----------------|---------------|
| Index page | Card grid (auto-generated) | Quarto listing (auto-generated) |
| Sidebar | Yes (with page links) | No |
| Sort order | Alphabetical | By date (newest first) |
| Post metadata | `title`, `description` | `title`, `date`, `author`, `categories`, `description` |
| Frontmatter modification | Adds `bread-crumbs: false` | No modification |
| File structure | Flat `.qmd` files | Subdirectories with `index.qmd` |

## Configuration

The blog section is configured as part of the `sections` array in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Blog              # Navbar link text
    dir: blog                # Source directory
    type: blog               # Use Quarto's listing directive
    navbar_after: Reference  # Position in navbar (optional)
```

## Example: Full Blog Setup

Here's a complete example with three posts:

### Directory Structure

```
my-package/
├── blog/
│   ├── introducing-the-project/
│   │   └── index.qmd
│   ├── february-update/
│   │   └── index.qmd
│   └── v0.2-release/
│       └── index.qmd
├── my_package/
│   └── __init__.py
├── great-docs.yml
└── pyproject.toml
```

### Configuration

```{.yaml filename="great-docs.yml"}
sections:
  - title: Blog
    dir: blog
    type: blog
```

### Blog Post

```{.markdown filename="blog/v0.2-release/index.qmd"}
---
title: "Version 0.2 Release Notes"
author: Vivian Smith
date: 2024-03-10
categories: [releases]
description: "New features and improvements in v0.2."
---

We're happy to announce the v0.2 release!

## New Features

- blog support via Quarto's listing directive
- improved dark mode styling
- better section card colors

## Breaking Changes

None in this release.
```

## Next Steps

A blog gives your project a voice beyond reference documentation. Use it for release announcements, tutorials, design rationale, or anything else that benefits from a chronological format. Great Docs handles the listing page, categories, and date sorting so you can focus on writing.

- [Custom Sections](custom-sections.qmd) covers adding non-blog sections (examples, tutorials, etc.)
- [Configuration](configuration.qmd) covers all available `great-docs.yml` options



## Config & Theming

# Theming & Appearance

The default Great Docs site looks polished out of the box, but most projects want their
documentation to reflect their own identity. Great Docs gives you control over every visual layer of
the site: the color scheme, navbar styling, dark mode, logos, hero section, icons, and more. All of
these options live in `great-docs.yml`, so you can adjust the look without writing any CSS or
JavaScript.

This page covers the visual customization options. For functional settings (API discovery, parsers,
GitHub integration, etc.), see [Configuration](configuration.qmd).

## Dark Mode Toggle

Great Docs includes a light/dark mode toggle in the navbar. It respects the visitor's system
preference on first visit and remembers their choice in local storage for subsequent visits. The
toggle is enabled by default.

To disable the toggle, set `dark_mode_toggle` to `false` in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
dark_mode_toggle: true   # Enabled by default
```

```{.yaml filename="great-docs.yml"}
dark_mode_toggle: false  # Disable the toggle
```

When enabled, the toggle provides instant switching without a page reload. Visitors who prefer
reduced motion in their operating system settings will still see the theme change, but without the
transition animation.

## GitHub Link Style

Great Docs automatically adds a GitHub link to the navbar when it detects your repository URL. The
`github_style` option controls how that link is displayed:

```{.yaml filename="great-docs.yml"}
github_style: widget   # Default: interactive widget with stats dropdown
```

```{.yaml filename="great-docs.yml"}
github_style: icon     # Simple GitHub icon linking to the repo
```

The `widget` style shows a GitHub icon that, on hover, reveals a dropdown with live star, fork,
issue, and pull request counts. The `icon` style renders a plain GitHub icon that links directly to
the repository.

## Sidebar Filter

API reference sidebars can grow large as your package adds more exports. The sidebar filter adds a
search input at the top of the sidebar so visitors can quickly find the function or class they're
looking for. It is enabled by default and appears automatically when the sidebar has enough items.

To configure the filter in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sidebar_filter:
  enabled: true     # Default: true
  min_items: 20     # Default: show filter when sidebar has 20+ items
```

The `min_items` threshold prevents the filter from appearing on small APIs where it would not be
useful. Set `enabled: false` to hide the filter entirely.

## Display Name

By default, Great Docs uses your package name (from `pyproject.toml`) in the navbar and page titles.
If your package name uses underscores or hyphens (e.g., `great_docs` or `great-docs`), you can set a
friendlier display name:

```{.yaml filename="great-docs.yml"}
display_name: "Great Docs"
```

This name appears in the navbar title, the hero section (if enabled), the page `<title>` tag, and
anywhere else the package name is shown to visitors.

## GitHub Link Style

A floating button appears in the bottom-right corner of the page after the visitor scrolls down,
providing a one-click way to return to the top. The button uses smooth scrolling and automatically
shifts upward when it would overlap with the prev/next page navigation links. It is enabled by
default.

```{.yaml filename="great-docs.yml"}
back_to_top: true    # Enabled by default
```

```{.yaml filename="great-docs.yml"}
back_to_top: false   # Disable the button
```

The button respects the visitor's `prefers-reduced-motion` setting: when reduced motion is
preferred, scrolling is instant rather than animated.

When `back_to_top` is enabled, a companion **On this page** button also appears on mobile
viewports (below 768 px). This round floating button sits directly above the back-to-top button
and opens a compact table-of-contents panel. Tapping a heading scrolls to that section and
dismisses the panel whereas tapping outside the panel dismisses it without navigating. The button is
hidden on tablet and desktop widths where the sidebar TOC is already visible.

## Keyboard Navigation [version-badge new 0.5]

Great Docs includes built-in keyboard shortcuts that let visitors navigate the site and access
common actions without reaching for the mouse. A small keyboard icon appears in the navbar; clicking
it (or pressing `h` / `?`) opens an overlay listing every shortcut.

### Available Shortcuts

The shortcuts are organized into three groups:

#### Navigation

Move between pages and jump to common destinations without leaving the keyboard.

| Key | Action |
|-----|--------|
| `s` or `/` | Focus the search input |
| `[` | Go to the previous page |
| `]` | Go to the next page |
| `q` | Go to the homepage |
| `u` | Go to the User Guide |
| `r` | Go to the API Reference |
| `m` or `n` | Show/hide the floating menu overlay |

The floating menu shows the sidebar navigation on documentation pages and the navbar links on the
homepage, giving quick access to any section without scrolling.

#### Display

Control how the page looks and capture its content.

| Key | Action |
|-----|--------|
| `d` | Toggle dark mode |
| `c` | Copy the current page as Markdown (when available) |

#### General

Access help and dismiss any open overlay.

| Key | Action |
|-----|--------|
| `h` or `?` | Show/hide the keyboard shortcuts help overlay |
| `Escape` | Close the active overlay or unfocus the current element |

### Configuration

Keyboard navigation is enabled by default. To disable it:

```{.yaml filename="great-docs.yml"}
keyboard_nav: false
```

### Accessibility

Keyboard shortcuts are automatically skipped when the visitor is typing in an input field, textarea,
or content-editable element, so they never interfere with form entry or search. The help overlay
uses ARIA attributes for screen reader compatibility, and animations respect the visitor's
`prefers-reduced-motion` system setting.

## Announcement Banner

A site-wide banner can be displayed above the navbar to highlight important news, releases, or
alerts. The banner appears on every page and can optionally be dismissed by the visitor.

### Simple Form

The simplest way to add a banner is with a string value. This creates a blue, info-styled banner
that visitors can dismiss:

```{.yaml filename="great-docs.yml"}
announcement: "Version 2.0 is now available!"
```

### Full Configuration

For more control over the banner's appearance and behavior, use a dictionary with `content`, `type`,
`dismissable`, and `url` keys:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "We've moved to a new domain. Please update your bookmarks!"
  type: warning        # info (default), warning, success, or danger
  dismissable: true    # Allow visitors to close the banner (default: true)
  url: https://example.com/blog/migration  # Optional: makes the text a link
```

The available banner types and their colors:

| Type | Light Mode | Dark Mode |
|------|-----------|-----------|
| `info` | Blue | Dark blue |
| `warning` | Yellow (dark text) | Dark yellow |
| `success` | Green | Dark green |
| `danger` | Red | Dark red |

### Dismiss Behavior

When `dismissable: true` (the default), visitors can click the close button to hide the banner. The
dismissal is stored in `sessionStorage`, so the banner stays hidden for the rest of the browsing
session but reappears after the browser is closed. If you change the announcement text, the new
message will appear even for visitors who dismissed the previous one.

### Disabling the Banner

To remove a previously configured banner, either set the key to `false` or remove it from the file
entirely:

```{.yaml filename="great-docs.yml"}
announcement: false
```

## Animated Gradient Presets

The announcement banner, navbar, and content area all support gradient backgrounds. The banner and
navbar use animated gradients that shift slowly across the element, creating a subtle, eye-catching
effect. The content area uses a soft radial glow at the top of each page. Each preset includes
paired light-mode and dark-mode color palettes.

### Available Presets

Great Docs ships with eight gradient presets. Each bar below shows the light-mode gradient on the
left and the dark-mode gradient on the right:

```{=html}
<style>
@media (max-width: 576px) {
  .gd-preset-desc { font-size: 0.6em; }
  .gd-preset-bar { height: 34px; font-size: 0.6em; }
}
</style>
<div style="display: flex; flex-direction: column; gap: 6px; margin: 1em 0;">
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #d0ecf9, #e0f4ff, #c5e8f7, #b8e0f5); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">sky</code><span class="gd-preset-desc">&ensp;Soft sky blues</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #023e8a, #0077b6, #005f73, #0096c7); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">sky</code><span class="gd-preset-desc">&ensp;Soft sky blues</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ffddc1, #ffe4cc, #fdd0d8, #fbc4d4); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">peach</code><span class="gd-preset-desc">&ensp;Peach and blush</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #cc4a1a, #c7760f, #b84a5f, #a33560); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">peach</code><span class="gd-preset-desc">&ensp;Peach and blush</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #c4f0e0, #d0e8f5, #e4d4f4, #d8cef0); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">prism</code><span class="gd-preset-desc">&ensp;Mint, sky, and lavender</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #048a65, #0c6a8a, #52077d, #2a0978); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">prism</code><span class="gd-preset-desc">&ensp;Mint, sky, and lavender</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #e8d0f0, #f5d0e0, #f0d4f8, #eac8ee); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">lilac</code><span class="gd-preset-desc">&ensp;Lilac and pink</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #561e64, #8b1140, #a02db3, #6e1a7d); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">lilac</code><span class="gd-preset-desc">&ensp;Lilac and pink</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #e0e4e8, #eceff1, #dde2e6, #d5dadf); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">slate</code><span class="gd-preset-desc">&ensp;Cool grays</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #37474f, #455a64, #3e525e, #263238); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">slate</code><span class="gd-preset-desc">&ensp;Cool grays</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ffe0c2, #ffedcc, #ffe5b4, #ffd6a8); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">honey</code><span class="gd-preset-desc">&ensp;Warm cream and apricot</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #bf360c, #e65100, #ef6c00, #b71c1c); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">honey</code><span class="gd-preset-desc">&ensp;Warm cream and apricot</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #d8daf0, #dddff5, #d4d0ee, #dad4f2); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">dusk</code><span class="gd-preset-desc">&ensp;Soft lavender-blue</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #0d1244, #141b55, #1a0f52, #261560); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">dusk</code><span class="gd-preset-desc">&ensp;Soft lavender-blue</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ccece8, #d5f0ec, #c4e8e4, #d0f2ee); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">mint</code><span class="gd-preset-desc">&ensp;Pale aqua</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #00695c, #00796b, #004d40, #00897b); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">mint</code><span class="gd-preset-desc">&ensp;Pale aqua</span></div>
  </div>
  <div style="display: flex; gap: 0; font-size: 0.75em; color: #888; margin-top: 2px;">
    <div style="flex: 1; text-align: center;">Light mode</div>
    <div style="flex: 1; text-align: center;">Dark mode</div>
  </div>
</div>
```

### Gradient on the Announcement Banner

Add a `style` key to the announcement config to apply a gradient background instead of the solid
color:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "Version 2.0 is now available!"
  style: sky
```

When `style` is set, it overrides the solid-color `type` background with the animated gradient. The
`type` key is still used for semantic class names but has no visual effect on the background when a
gradient is active.

### Gradient on the Navbar

Use the top-level `navbar_style` key to apply the animated gradient to the site's top navigation
bar:

```{.yaml filename="great-docs.yml"}
navbar_style: peach
```

In dark mode, text and icons are automatically adjusted to white for readability.

### Gradient on the Content Area

Use the top-level `content_style` key to add a subtle radial glow at the top of the main content
area:

```{.yaml filename="great-docs.yml"}
content_style: lilac
```

The glow fades out smoothly and does not interfere with text or interactive elements. It uses the
same preset names as the banner and navbar gradients.

By default the glow appears on all pages. To restrict it to the homepage only, use the dictionary
form with a `pages` key:

```{.yaml filename="great-docs.yml"}
content_style:
  preset: lilac
  pages: homepage    # "all" (default) or "homepage"
```

### Combining All Three

You can use the same preset or different presets for the banner, navbar, and content area. Here is
an example that mixes two presets:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "New release!"
  style: sky

navbar_style: sky
content_style:
  preset: lilac
  pages: homepage
```

## Accent Color

The accent color is a site-wide tint used by shortcodes (like the `{{< hr >}}` horizontal rule),
gradient presets, and other accent-colored elements. It sets the `--gd-accent` CSS custom property,
which you can also reference in custom stylesheets.

A single string applies the same color in both light and dark mode:

```{.yaml filename="great-docs.yml"}
accent_color: "#6366f1"
```

For per-mode colors, use a dictionary:

```{.yaml filename="great-docs.yml"}
accent_color:
  light: "#6366f1"
  dark: "#818cf8"
```

If you don't set an accent color, Great Docs uses its built-in defaults.

## Navbar Color

If you prefer a solid color over an animated gradient, the `navbar_color` option sets a flat
background on the navbar with automatic contrast-aware text. Great Docs uses the
[APCA (Accessible Perceptual Contrast Algorithm)](https://github.com/Myndex/SAPC-APCA) to determine
whether white or black text provides maximum readability against your chosen background.

### Single Color for Both Modes

A plain string applies the same navbar color in both light and dark mode. Any CSS named color (e.g.,
`navy`, `tomato`, `teal`) or hex value works:

```{.yaml filename="great-docs.yml"}
navbar_color: steelblue
```

### Per-Mode Colors

Use a dictionary with `light` and `dark` keys to set different navbar colors for each mode. You can
also set only one mode, and the other keeps the default navbar styling:

```{.yaml filename="great-docs.yml"}
navbar_color:
  light: "#2c3e50"
  dark: "#1a237e"
```

### How Text Color is Chosen

You do not need to specify a text color. Great Docs automatically picks white or black text (and
adjusts icons, search button, toggle, and hover states) based on the APCA contrast algorithm. Dark
backgrounds get white text; light backgrounds get black text.

### Precedence with `navbar_style`

If both `navbar_style` (animated gradient) and `navbar_color` are set, the gradient takes precedence
and `navbar_color` is ignored. To use a solid color, remove or comment out `navbar_style`:

```{.yaml filename="great-docs.yml"}
# navbar_style: peach      # commented out, so navbar_color takes effect
navbar_color: "#2c3e50"
```

## Custom Head Content {#include-in-header}

Use `include_in_header` to inject custom HTML into the `<head>` of every page. This is useful for
adding analytics scripts, custom meta tags, external stylesheets, or any other head content that
needs to load before the page renders.

A single string is treated as inline HTML:

```{.yaml filename="great-docs.yml"}
include_in_header: '<link rel="stylesheet" href="https://example.com/custom.css">'
```

For multiple entries, use a list. Each item can be a string (inline HTML) or a dictionary with a
`text` or `file` key:

```{.yaml filename="great-docs.yml"}
include_in_header:
  - text: |
      <script>
        console.log("hello from great-docs");
      </script>
  - text: '<meta name="custom" content="value">'
  - file: custom-head.html
```

Your entries are merged with Great Docs' own head injections (Font Awesome, theme scripts, etc.) so
everything cooperates automatically.

## Logo

Great Docs can display a logo in the navbar instead of the plain-text package name. Logos are
automatically detected from conventional file locations, or you can configure them explicitly.

### Auto-Detection

If you place logo files in your project using common naming conventions, Great Docs will find and
use them automatically with no configuration needed:

```
my-package/
├── logo.svg              # Primary logo
├── assets/
│   ├── logo.svg          # Also auto-detected
│   └── logo-dark.svg     # Dark-mode variant
```

Auto-detection checks these paths in priority order:

1. `logo.svg` / `logo.png` (project root)
2. `assets/logo.svg` / `assets/logo.png`
3. `docs/assets/logo.svg` / `docs/assets/logo.png`
4. `{package_name}_logo.svg` / `{package_name}_logo.png`

If a file named `logo-dark.svg` (or `{stem}-dark.{ext}`) exists alongside the primary logo, it is
automatically used for dark mode.

### Explicit Configuration

For full control, configure the logo in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
```

You can also set additional options:

```{.yaml filename="great-docs.yml"}
logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
  alt: My Package         # Alt text (defaults to display_name)
  href: https://example.com  # Logo link target (defaults to site root)

logo_show_title: true      # Show text title alongside logo (default: false)
```

### What Happens When a Logo Is Set

When a logo is configured (or auto-detected):

- the logo image replaces the text title in the navbar.
- a dark-mode variant is used automatically when the user switches themes.
- the text title is hidden by default (set `logo_show_title: true` to show both).
- favicons are generated automatically from the logo (see below).

## Favicon

Great Docs automatically generates a complete set of favicons for your site. If a logo is
configured, favicons are derived from it with no extra setup needed. You can also specify a
dedicated favicon image.

### Automatic Generation from Logo

When a logo is set, Great Docs generates all standard favicon formats automatically:

| File | Purpose |
|------|---------|
| `favicon.ico` | Classic favicon (16, 32, and 48px embedded) |
| `favicon.svg` | Modern browsers (SVG, infinite scaling) |
| `favicon-16x16.png` | Small icon contexts |
| `favicon-32x32.png` | Standard tab icon |
| `apple-touch-icon.png` | iOS home screen (180x180) |

These files are created in the build directory and proper `<link>` tags are injected into every
page's `<head>`.

### Dedicated Favicon

If you want a different image for your favicon (for example, a simplified icon rather than the full
logo), set the `favicon` option:

```{.yaml filename="great-docs.yml"}
favicon: assets/favicon.svg
```

This generates the same set of raster variants as the logo-based approach, but uses your dedicated
favicon source image instead. Both SVG and PNG source files are supported.

### Non-Square Source Images

Source images do not need to be perfectly square. Non-square images are automatically centered on a
transparent canvas, preserving the original aspect ratio. This means wide logos will not be
distorted; they will be padded with transparency above and below.

## Hero Section

The hero section is a prominent banner displayed at the top of the landing page, showcasing the
package logo, name, tagline, and badges. It is generated automatically when a logo is present and
gives your documentation a polished, professional look.

### Auto-Enable Behavior

The hero section auto-enables when a logo is configured (or auto-detected). No explicit
configuration is needed: if you have a logo, you get a hero. The hero displays:

- the package logo (with dark-mode support)
- the package display name
- the package description from `pyproject.toml`
- badges auto-extracted from the README (shields.io badges, etc.)

### Disabling the Hero

To disable the hero entirely (for example, if you prefer your `index.qmd` or `README.md` rendered
as-is):

```{.yaml filename="great-docs.yml"}
hero: false
```

### Customizing the Hero

Each hero component can be overridden or suppressed individually. These examples add
`enabled: true` since they have no logo configured — if you already have a logo (and
therefore an auto-enabled hero), you can omit it:

```{.yaml filename="great-docs.yml"}
hero:
  enabled: true                         # Needed here since no logo is configured
  name: "My Package"                    # Override the auto-detected name
  tagline: "A better way to build things"  # Override the description
  logo_height: 120px                    # Default: 200px
  badges: false                         # Suppress badge display
```

Set any component to `false` to suppress it:

```{.yaml filename="great-docs.yml"}
hero:
  enabled: true
  name: false              # Hide the name (logo and tagline only)
  badges: false            # No badges
```

### Hero Logo vs. Navbar Logo

By default, the hero uses the same logo as the navbar. But you may want a different image for the
hero, for example a detailed wordmark instead of a compact lettermark.

Set a separate hero logo with light/dark variants:

```{.yaml filename="great-docs.yml"}
# Navbar: compact lettermark
logo:
  light: assets/logo-lettermark.svg
  dark: assets/logo-lettermark-dark.svg

# Hero: expanded wordmark
hero:
  logo:
    light: assets/logo-wordmark.svg
    dark: assets/logo-wordmark-dark.svg
  logo_height: 150px
```

Or use a simple string for a single hero logo image:

```{.yaml filename="great-docs.yml"}
hero:
  logo: assets/hero-logo.svg
```

### Hero Logo Auto-Detection

Great Docs can also auto-detect hero-specific logo files from conventional file locations, with no
configuration needed. Place files using these naming conventions:

```
my-package/
├── assets/
│   ├── logo-hero.svg          # Hero logo (single image)
│   ├── logo-hero-light.svg    # Hero logo (light variant)
│   └── logo-hero-dark.svg     # Hero logo (dark variant)
```

Auto-detection checks these paths in priority order:

1. `logo-hero.svg` / `logo-hero.png` (project root)
2. `assets/logo-hero.svg` / `assets/logo-hero.png`
3. `logo-hero-light.svg` / `logo-hero-light.png` (project root)
4. `assets/logo-hero-light.svg` / `assets/logo-hero-light.png`

If a file named `logo-hero-dark.svg` (or `logo-hero-dark.png`) exists alongside the primary hero
logo, it is automatically used for dark mode.

When hero logo files are detected, the hero section auto-enables even if no `logo` or `hero` config
is set in `great-docs.yml`.

The full logo fallback chain for the hero is:

1. explicit `hero.logo` in `great-docs.yml`
2. auto-detected hero logo files (`logo-hero.*`)
3. explicit top-level `logo` in `great-docs.yml`
4. auto-detected navbar logo files (`logo.*`)

### Explicit Badge List

By default, badges are auto-extracted from the README. You can provide an explicit list instead:

```{.yaml filename="great-docs.yml"}
hero:
  badges:
    - alt: PyPI version
      img: https://img.shields.io/pypi/v/my-package
      url: https://pypi.org/project/my-package/
    - alt: License
      img: https://img.shields.io/badge/license-MIT-green
      url: https://opensource.org/licenses/MIT
```

### Hero Section Summary

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `hero` | `bool` / `dict` | auto | `false` to disable; `true` to force-enable; dict to customize (auto-enables with a logo) |
| `hero.name` | `str` / `false` | display name | Package name shown in hero |
| `hero.tagline` | `str` / `false` | description | Tagline shown below the name |
| `hero.logo` | `str` / `dict` / `false` | auto-detect | Hero-specific logo (can have `light`/`dark` keys); auto-detects `logo-hero.*` files |
| `hero.logo_height` | `str` | `200px` | CSS max-height for the hero logo |
| `hero.badges` | `list` / `false` | `auto` | Explicit badge list or `false` to suppress |

## Navigation Icons [version-badge new 0.5]

Add [Lucide](https://lucide.dev/) icons to navbar and sidebar entries for quick visual
identification. Great Docs ships with the complete Lucide icon set (1,900+ icons) and resolves them
to lightweight inline SVGs at build time.

### Basic Setup

Map navigation labels to Lucide icon names under `nav_icons`. Use `navbar` for the top navigation
bar and `sidebar` for left-sidebar items:

```{.yaml filename="great-docs.yml"}
nav_icons:
  navbar:
    User Guide: book-open
    Reference: code-2
  sidebar:
    Getting Started: rocket
    Configuration: settings
```

Each key is the **exact text** of the navigation label as it appears in the rendered site. The value
is any [Lucide icon name](https://lucide.dev/icons/) (lowercase, hyphenated).

### Navbar Icons

Icons in the navbar appear next to the top-level links (User Guide, Reference, Recipes, etc.):

```{.yaml filename="great-docs.yml"}
nav_icons:
  navbar:
    User Guide: book-open
    Recipes: chef-hat
    Reference: code-2
```

### Sidebar Icons

Sidebar icons appear next to items and section headers in the left navigation panel. These work for
User Guide pages, custom sections, and Reference section headings:

```{.yaml filename="great-docs.yml"}
nav_icons:
  sidebar:
    # User Guide pages
    Getting Started: rocket
    Configuration: settings
    Advanced Topics: graduation-cap
    # Reference sections
    Functions: zap
    Classes: layers
    # Custom section headers
    Tutorials: lightbulb
```

You don't need to assign an icon to every item, entries without a mapping simply display as normal
text.

### Finding Icon Names

Browse the full icon set at [lucide.dev/icons](https://lucide.dev/icons/). Use the search bar to
find icons by concept: search "chart" for data visualization icons, "file" for document icons,
"settings" for configuration icons, etc.

To list all available icon names programmatically:

```python
from great_docs._icons import list_icons

print(list_icons())  # sorted list of 1,900+ names
```

::: {.callout-tip}
### Icon Naming Tips

Lucide names are lowercase and hyphen-separated. Common patterns:

- **Actions**: `download`, `upload`, `copy`, `trash-2`
- **Objects**: `file`, `folder`, `database`, `cloud`
- **Concepts**: `settings`, `search`, `bell`, `heart`
- **Numbered variants**: `code-2`, `trash-2` (alternate designs of the same concept)
:::

### Dark Mode

Icons automatically adapt to dark mode. They use `stroke="currentColor"`, so they inherit the text
color of their navigation context (no additional configuration is needed).

## Inline Icons [version-badge new 0.6]

Beyond navbar and sidebar icons, you can place Lucide icons anywhere in your `.qmd` content using
the `icon` shortcode. Icons scale with the surrounding text, sit on the baseline, and inherit the
text color.

### Basic Usage

```{shortcodes="false"}
{{< icon heart >}}
```

This renders inline: {{< icon heart >}} (sized to match the surrounding text).

A few more examples: {{< icon rocket >}} `rocket`, {{< icon star >}} `star`, {{< icon check >}} `check`, {{< icon book-open >}} `book-open`. Icon names follow the same Lucide naming convention described above.

### Size

By default icons are `1em` tall (matching the current font size). Use `size` to specify a different
size in pixels (the value is converted to `em` units so the icon still scales with its context):

```{shortcodes="false"}
{{< icon star size="12" >}}  small
{{< icon star >}}            default (16px = 1em)
{{< icon star size="24" >}}  large
{{< icon star size="32" >}}  very large
```

Result: {{< icon star size="12" >}} small · {{< icon star >}} default · {{< icon star size="24" >}} large · {{< icon star size="32" >}} very large

### Accessibility

By default icons are decorative (`aria-hidden="true"`). When an icon conveys meaning on its own,
add a `label`:

```{shortcodes="false"}
{{< icon alert-triangle label="Warning" >}}
```

This replaces `aria-hidden` with `aria-label="Warning" role="img"`, so screen readers announce the
icon's purpose.

### In Context

Icons work in headings, callouts, lists, tables, and blockquotes:

- {{< icon file-text >}} Documentation pages
- {{< icon code-2 >}} Source code references
- {{< icon test-tube >}} Testing guides

| Status | Icon | Description |
|--------|------|-------------|
| Complete | {{< icon check-circle >}} | Feature is stable |
| In progress | {{< icon loader >}} | Under active development |
| Planned | {{< icon calendar >}} | Scheduled for a future release |

::: {.callout-tip}
## {{< icon lightbulb >}} Pro Tip
Use icons sparingly to draw attention to key information without cluttering the page.
:::

## Footer Attribution

By default, Great Docs adds a small "Site created with Great Docs" attribution line in the page
footer. To hide it:

```{.yaml filename="great-docs.yml"}
attribution: false
```

## Next Steps

Great Docs gives you control over every visual aspect of your site, from broad choices like gradient
themes and dark mode down to fine details like accent colors, icon placement, and footer
attribution. Start with the defaults and customize as your project's identity evolves.

- [Configuration](configuration.qmd) covers functional settings like API discovery, parsers, and
GitHub integration
- [Internationalization](internationalization.qmd) shows how translated labels interact with your
site's visual design
- [Custom Pages](custom-pages.qmd) explains how to add standalone HTML pages that inherit your theme
- [Horizontal Rules](horizontal-rules.qmd) demonstrates the `hr` shortcode, which uses the accent
color


# Cross-Referencing

Documentation becomes much more useful when readers can follow connections between related items.
Without links, someone reading the `encode()` page has no easy way to discover that `decode()`
exists, or that a higher-level `Pipeline` class ties everything together. Cross-references turn
isolated pages into a connected web. This page covers that internal linking, and ends with
citations: linking your prose outward to the papers, specifications, and books your work builds
on.

Great Docs provides a linking system called GDLS (Great Docs Linking System) that automatically
creates clickable navigation between your API reference pages. GDLS operates at three levels, each
adding a different kind of connectivity to your documentation.

The first level is the `%seealso` directive, which adds structured "See Also" sections that link
related items together. The second level is inline interlinks, which let you create Markdown-style
links to API symbols anywhere in your prose. The third level is code autolinks, which automatically
turn inline code references like `` `MyClass` `` into clickable links when they match a documented
symbol.

All three mechanisms resolve against the same inventory that Great Docs generates during the
build, and they resolve while the page is being rendered. To preview which symbols are available
for linking before you build, run:

```bash
great-docs scan
```

This is useful for confirming the exact names you can reference in your docstrings.

Your site publishes that inventory as `objects.inv` at its root, the format Sphinx and Quarto
projects both read, so other projects can link into your documentation the same way you link
into theirs.

## Linking to Another Project

Configure the projects you want to reach under `interlinks.sources`, naming each one and the URL
its documentation is served from:

```yaml
interlinks:
  sources:
    numpy:
      url: https://numpy.org/doc/stable/
      aliases: [np]
```

An external reference is then written exactly like an internal one:

```markdown
See [](`numpy.ndarray`) for the array type, or [](`np.ndarray`) using the alias.
```

Code autolinks stay inside your own project. A bare `` `array` `` in your prose is left alone
rather than linked into another project's documentation.

See [Configuration](05-configuration.qmd) for the full set of fields a source accepts.

## When a Short Name Is Ambiguous

You can reference an object by a short name, writing `` [](`Cache`) `` rather than
`` [](`mypkg.store.Cache`) ``. If two documented objects would answer to the same short name,
neither claims it: the reference renders unlinked rather than pointing at whichever object came
first. Qualify the reference to fix it.

The build reports each ambiguous name it drops, and `great-docs lint` reports each reference
that hits one, so you do not have to find them by reading the built pages.

Only your own objects compete for a short name. If a linked project publishes the same
spelling, an unambiguous local name still wins and the external object remains reachable
by its full name. An ambiguous local name stays unlinked even when an external object has
that spelling. Qualify the source to link to the external object.

A version built from an API snapshot or a git tag resolves references against that version's
own API, so a name added since then stays unlinked in the older version's pages rather than
pointing at a page it does not have.

## The `%seealso` Directive

The most common cross-referencing need is connecting items that serve complementary roles: an
encoder and a decoder, a reader and a writer, or a class and its factory function. The `%seealso`
directive handles this by adding a "See Also" section at the bottom of a reference page. Place it
anywhere in a docstring with a comma-separated list of related names:

```python
def encode(data: bytes, encoding: str = "utf-8") -> str:
    """Encode bytes to a string.

    %seealso decode, transcode
    """
    ...
```

Great Docs strips the directive from the rendered output and generates a "See Also" section with
clickable links at the bottom of the page.

Names can reference any exported symbol, including class methods using dotted notation:

```python
class Validator:
    def check(self, data):
        """Run all validation checks.

        %seealso Validator.reset, Report
        """
        ...
```

### Adding Descriptions

You can add a short description after each name, separated by a colon. When descriptions are
present, the See Also section renders as a list with each link followed by its description. Without
descriptions, the links appear as a compact comma-separated line.

```python
def load(path: str) -> dict:
    """Load data from a file.

    %seealso save : Write data back to a file, validate : Check data integrity
    """
    ...
```

You can mix entries with and without descriptions freely:

```python
def transform(data: dict) -> dict:
    """Transform data before processing.

    %seealso validate : Check data integrity first, load, save
    """
    ...
```

### NumPy-style See Also Sections

If your docstrings use the NumPy docstring format, you can write a standard See Also section instead
of (or in addition to) the `%seealso` directive. Great Docs recognizes this format, preserves the
descriptions, and merges it with any `%seealso` entries on the same page. Duplicate references are
deduplicated automatically.

```python
def connect(host: str, port: int = 5432):
    """Open a connection to the server.

    Parameters
    ----------
    host
        The server hostname.
    port
        The port number.

    See Also
    --------
    disconnect : Close an open connection.
    send : Transmit data over the connection.
    """
    ...
```

Both formats produce the same rendered output. If a page has both a `%seealso` directive and a NumPy
See Also section, the entries are merged and any duplicates are removed.

## Inline Interlinks

Sometimes you need to mention another API item in the middle of a prose explanation rather than in a
structured "See Also" section. Inline interlinks let you create Markdown-style links to API symbols
anywhere in your docstring text. This is especially useful in class hierarchies and overview
docstrings where you want to point readers to related pages. There are several forms:

- write `` [](`~mypackage.MyClass`) `` to display just `MyClass`. The `~` prefix strips the package
path and shows only the short name
- write `` [](`mypackage.MyClass`) `` to display the full path `mypackage.MyClass`
- write `` [see this class](`mypackage.MyClass`) `` to display `see this class` as the link text
- write `` [see this class](`~mypackage.MyClass`) `` to also display `see this class`; when you
supply custom link text in the brackets, it is always used as-is regardless of the `~` prefix

Here is an example showing interlinks in practice:

```python
class BaseStore:
    """Base class for all stores.

    Available implementations:

    - [](`~mypackage.DuckDBStore`): local storage with embedded search.
    - [](`~mypackage.ChromaDBStore`): vector storage using ChromaDB.

    See [](`mypackage.BaseStore`) for the full API, or
    [the DuckDB guide](`~mypackage.DuckDBStore`) for a walkthrough.
    """
    ...
```

Interlinks work in any part of a docstring: the summary line, extended description, parameter
descriptions, notes, or any other section. If a reference cannot be resolved (for example, a typo in
the symbol name), the link text still renders but without a clickable link.

## Code Autolinks

The first two levels (`%seealso` and interlinks) require you to opt in by writing specific syntax.
Code autolinks take a different approach: they work automatically with no markup at all. When Great
Docs encounters inline code in a docstring that matches a documented API symbol, it turns that code
into a clickable link:

```python
class Engine:
    """Core processing engine.

    Use `Pipeline` to chain multiple engines together.
    Call `run_pipeline()` to execute a full pipeline.
    """
    ...
```

In the rendered output, `` `Pipeline` `` and `` `run_pipeline()` `` become clickable links to their
respective reference pages.

### Shortening Prefixes

For qualified names, you can control the display text with `~~` prefixes. The double tilde strips
everything before the last component of the dotted path:

| What you write | What renders | What it links to |
|---|---|---|
| `` `mypackage.MyClass` `` | `mypackage.MyClass` | MyClass page |
| `` `mypackage.my_func()` `` | `mypackage.my_func()` | my_func page |
| `` `~~mypackage.MyClass` `` | `MyClass` | MyClass page |
| `` `~~mypackage.my_func()` `` | `my_func()` | my_func page |
| `` `~~.mypackage.MyClass` `` | `.MyClass` | MyClass page |

If the name does not match any documented symbol (e.g., `` `~~unknown_func()` ``), it renders as
plain code with no link.

### What Gets Autolinked

Any inline code that looks like an identifier or dotted path is a candidate for autolinking.
Parentheses at the end are allowed. Code that contains arguments, spaces, or operators is not
linked.

Examples that will be linked (if the name exists in the API):

- `` `MyClass` ``
- `` `my_func()` ``
- `` `mypackage.MyClass` ``

Examples that will not be linked:

- `` `my_func(x=1)` `` (contains arguments)
- `` `a + b` `` (contains operators)
- `` `-MyClass` `` (starts with an operator)

When in doubt, write the name as you normally would in a docstring. If it resolves, it becomes a
link; if not, it renders as plain code.

## Parentheses in Cross-References

The three cross-referencing levels handle parentheses differently, so it helps to know the rules:

**`%seealso`**: Write bare names without parentheses. Great Docs automatically appends `()` to
functions and methods in the rendered "See Also" section based on each symbol's type. Writing
`%seealso decode, MyClass` produces `decode()` and `MyClass` in the output, with the parentheses
added only where appropriate. Set `interlinks.add_function_parentheses` to `false` if you would
rather link the bare name.

**Inline interlinks**: The target inside backticks should be the qualified name without parentheses.
Write `` [](`~mypackage.my_func`) ``, not `` [](`~mypackage.my_func()`) ``.

**Code autolinks**: Trailing `()` are optional and purely cosmetic. Both `` `my_func` `` and
`` `my_func()` `` resolve to the same page. The parentheses are preserved in the display text but
stripped during lookup. Use `()` when you want to signal to readers that something is callable:

```python
class Pipeline:
    """Chain multiple engines together.

    Call `run()` to execute the pipeline, or inspect `config` for current settings.
    """
    ...
```

In the rendered output, `run()` links to the `run` method page (with parentheses displayed) and
`config` links to the `config` attribute page (without parentheses).

### Disabling Autolinks

To prevent a specific piece of inline code from being autolinked, add the `{.gd-no-link}` class
after the backtick span:

```markdown
The `Config`{.gd-no-link} parameter is a plain dictionary, not the Config class.
```

This is useful when a word happens to match a documented symbol but you are referring to something
else in context. You only need this occasionally; most autolinks are helpful and should be left in
place.

## Best Practices for Linking

Cross-references make documentation much more navigable, but a few guidelines help keep them useful
rather than distracting.

Use `%seealso` to connect items that serve complementary roles. If `encode()` and `decode()` are a
natural pair, linking them together helps readers discover both. For larger groupings, a brief
description after each name (using the colon syntax) gives context about why the link is relevant.

Use inline interlinks when you mention another symbol in the middle of a prose explanation. This
keeps reading flow natural while still giving readers a path to the referenced page. The shortened
form (with `~`) is usually the best choice because fully qualified paths can be long and interrupt
the sentence visually.

Code autolinks require no effort on your part, since they happen automatically. But be aware that
common words like `Config` or `Data` might match a symbol unexpectedly. If you notice unwanted links
in the rendered output, add `{.gd-no-link}` to the specific code span.

## Citations & Bibliography

Cross-references connect the pages *within* your documentation; citations connect your prose to the
work it builds on (e.g., a paper, a specification, a book, etc.). Great Docs supports academic
citations and a generated **References** section, driven by a single project-level bibliography.

Point `bibliography:` at a `.bib` file (path relative to the project root):

```{.yaml filename="great-docs.yml"}
bibliography: docs/references.bib
```

Then cite by key anywhere (no per-page frontmatter required):

```markdown
Literate programming was introduced by Knuth [@knuth1984].
```

That renders as "…by Knuth (Knuth 1984)", linked to a References section. At build time Great Docs
copies the `.bib` into the build directory and wires it into the generated `_quarto.yml`, so the
bibliography is available to *every* page: User Guide pages, custom sections, the homepage, and even
the docstrings that become your API reference.

### Writing citations

Citations use standard [Pandoc citation
syntax](https://quarto.org/docs/authoring/citations.html#sec-citations). The citation key is the
identifier from your `.bib` entry (`knuth1984` above), prefixed with `@`.

| You write | Renders as |
|-----------|------------|
| `[@knuth1984]` | (Knuth 1984) |
| `@knuth1984` | Knuth (1984) |
| `[@knuth1984; @lamport1994]` | (Knuth 1984; Lamport 1994) |
| `[see @knuth1984, pp. 33-35]` | (see Knuth 1984, 33–35) |
| `[-@knuth1984]` | (1984) |

Wrap a key in square brackets for a parenthetical citation, drop them for an in-text citation where
the author becomes part of the sentence, separate multiple keys with semicolons, and add a prefix,
locator, or leading `-` to suppress the author.

### The references section

When a page contains at least one citation, Great Docs renders a **References** section listing
every work cited. By default it appears at the end of the page. To place it somewhere specific, add
an empty `#refs` div where you want it:

```markdown
## References

::: {#refs}
:::
```

Quarto fills that div with the reference list instead of appending one at the end, and uses your
heading as-is (it won't add a second one).

### Multiple bibliography files

Pass a list to combine several `.bib` files; all entries become citable from any page:

```{.yaml filename="great-docs.yml"}
bibliography:
  - docs/references.bib
  - docs/software.bib
```

### Citation style

By default citations follow the Chicago author-date style. To use a different
[CSL](https://citationstyles.org) style, point `csl:` at a `.csl` file (relative to the project
root); Great Docs copies it into the build alongside the bibliography. Find styles in the
[Zotero Style Repository](https://www.zotero.org/styles).

```{.yaml filename="great-docs.yml"}
bibliography: docs/references.bib
csl: docs/nature.csl
```

### Localized headings

If your site sets a [language](internationalization.qmd), the auto-generated references heading is
localized automatically. So a French site (`site.language: fr`) renders **Les références**, with the
entries themselves formatted for that language too.

::: {.callout-note}
If citations render as literal `[@key]` text with no References section, the key doesn't match a
`.bib` entry or the bibliography wasn't found. So check the key spelling and that `bibliography:`
resolves from the project root. A missing file warns (`"Bibliography file not found"`) and the build
continues without it.
:::

## Next Steps

Cross-references turn a collection of standalone reference pages into a connected web of
documentation. Use `%seealso` for structured navigation, interlinks for inline mentions, code
autolinks for the rest, and a project-level `bibliography:` to cite external work.

- [Writing Docstrings](writing-docstrings.qmd) covers how to write effective docstrings that work
well with cross-referencing
- [API Documentation](api-documentation.qmd) covers how API discovery and page organization work
- [User Guides](user-guides.qmd) explains how to link from User Guide pages to API reference pages
- [Internationalization](internationalization.qmd) localizes the References heading and the rest of
the UI
- [Linting](linting.qmd) can catch broken cross-references during the build



## Build & Deploy

# Building & Previewing

The `great-docs build` command is the main way you interact with Great Docs on a day-to-day basis.
It reads your `great-docs.yml` configuration, discovers your package's API, generates Quarto source
files, and renders everything into a static HTML site. This page explains what happens during a
build, how to preview your site locally, and how to troubleshoot common issues.

## The Build Pipeline

When you run `great-docs build`, the following steps execute in order:

1. The `great-docs/` output directory is created (or refreshed) with all required assets:
stylesheets, JavaScript files for dark mode toggling, sidebar filtering, the GitHub stars widget,
and other interactive features.

2. Your `great-docs.yml` is read. A `_quarto.yml` file is generated (or updated) in the output
directory with the Quarto project configuration, including navbar links, sidebar structure, and
theme settings.

3. A landing page (`index.qmd`) is generated from your project's `README.md`. If you have a logo
configured, a hero section with the logo, package name, tagline, and badges is added automatically.

4. If a user guide directory exists (by default `user_guide/`), all `.qmd` files are copied into
the output directory with numeric prefixes stripped from filenames. The sidebar is organized by
`guide-section` frontmatter metadata.

5. If Click CLI documentation is enabled, Great Docs discovers your CLI commands and generates a
reference page for each one.

6. Custom sections defined in `great-docs.yml` (examples, tutorials, blog posts, etc.) are processed
and copied to the output directory.

::: {.version-only versions=">=0.6"}
7. If `custom_pages` is configured, or if the fallback `custom/` directory exists, custom HTML pages
are discovered. Passthrough pages are converted into generated `.qmd` files and raw pages are copied
through unchanged.
:::

8. If the changelog is enabled and a GitHub repository URL exists in `pyproject.toml`, GitHub
Releases are fetched and a `changelog.qmd` file is generated.

9. The Agent Skills file (`skill.md`) is generated or copied. If you have a curated `SKILL.md` in
`skills/<package-name>/`, it is used directly. Otherwise, a skill file is auto-generated from your
package metadata. See [Agent Skills](38-agent-skills.qmd) for details.

10. `llms.txt` and `llms-full.txt` files are generated. These provide AI-friendly summaries of your
package documentation. See [llms.txt](39-llms-txt.qmd) for details.

11. Source link metadata (`_source_links.json`) is generated, mapping each documented symbol to its
file and line numbers on GitHub.

12. Quarto renders all the source files into HTML. A post-render script runs to apply final
transformations: injecting source links, processing cross-references (GDLS), cleaning up Sphinx/RST
artifacts, and generating companion Markdown (`.md`) files for each page.

After all steps complete, the finished site is in `great-docs/_site/`.

## Preview Mode

To view your site locally with live reload:

```{.bash filename="Terminal"}
great-docs preview
```

This starts a local development server and opens your default browser. When you edit source files
(user guide pages, docstrings, configuration), the site rebuilds automatically and the browser
refreshes to show your changes.

Preview mode is ideal during the writing process because it lets you see how content will look in
the final rendered site without committing or deploying anything.

## Build Options

The `great-docs build` command accepts several options that control its behavior.

### Watch Mode

Watch mode keeps the build process running and automatically rebuilds when files change. This is
similar to preview mode but without starting a local server:

```{.bash filename="Terminal"}
great-docs build --watch
```

This is useful when you want to rebuild continuously but view the output in a different way (for
example, opening the HTML files directly or using a separate static file server).

### Clean Build

If you suspect stale files in the output directory are causing issues, you can force a completely
fresh build. Delete the `great-docs/` directory and rebuild:

```{.bash filename="Terminal"}
rm -rf great-docs/ && great-docs build
```

Since the `great-docs/` directory is ephemeral and fully generated from `great-docs.yml` plus your
source files, deleting it is always safe.

## Build Output Structure

After a successful build, the output directory has this layout:

```{.default filename="great-docs/"}
great-docs/
├── _quarto.yml          # Generated Quarto config
├── index.qmd            # Landing page
├── great-docs.scss      # Theme stylesheet
├── *.js                 # Interactive features (dark mode, sidebar, etc.)
├── llms.txt             # LLM-friendly summary
├── llms-full.txt        # Full API docs for LLMs
├── skill.md             # Agent Skills file
├── _source_links.json   # GitHub source link metadata
├── reference/           # API reference pages
│   ├── index.qmd
│   ├── MyClass.qmd
│   └── ...
├── user-guide/          # User guide pages (from user_guide/)
├── recipes/             # Recipe pages (from recipes/)
├── scripts/
│   └── post-render.py   # HTML post-processing script
└── _site/               # Final rendered HTML
    ├── index.html
    └── ...
```

The `_site/` subdirectory contains the final HTML output. This is the directory you deploy to your
hosting service (GitHub Pages, Netlify, Vercel, etc.).

Everything outside of `_site/` is intermediate Quarto source. You generally do not need to inspect
these files, but they can be useful for debugging rendering issues.

## Building from a Remote Repository [version-badge new 0.11] {#from-repo}

The `--from-repo` flag lets you build documentation for any Git-hosted package without cloning it
yourself. Great Docs handles the entire workflow: cloning the repository, creating an isolated
virtual environment, installing the package and its dependencies, running the full build pipeline,
and copying the finished site to a local directory.

```{.bash filename="Terminal"}
great-docs build --from-repo https://github.com/owner/package.git
```

The built site is copied to `./great-docs/_site/` by default. Use `--output-dir` to put it somewhere
else:

```{.bash filename="Terminal"}
great-docs build --from-repo https://github.com/owner/package.git --output-dir /tmp/my-site
```

### Branch or Tag

By default the repository's default branch is cloned. Use `--branch` to check out a specific branch
or tag:

```{.bash filename="Terminal"}
great-docs build --from-repo https://github.com/owner/package.git --branch v2.0.0
```

### Clone Depth

Great Docs inspects the target project's `great-docs.yml` to decide how much Git history to fetch.
If the project uses multi-version docs or page dates, a full clone is performed automatically.
Otherwise a lightweight tag-only clone is used.

Use `--shallow` to force a minimal `--depth 1` clone. This is the fastest option but disables
versioned documentation and page dates:

```{.bash filename="Terminal"}
great-docs build --from-repo https://github.com/owner/package.git --shallow
```

### Previewing After Build

Add `--preview` to start a local server and open the site in your browser as soon as the build
finishes:

```{.bash filename="Terminal"}
great-docs build --from-repo https://github.com/owner/package.git --preview
```

### Previewing a Previously Built Site

If you have already built a site with `--from-repo` (or received a site directory from someone
else), use `great-docs preview --site-dir` to serve it without any project context:

```{.bash filename="Terminal"}
great-docs preview --site-dir /tmp/my-site
```

This starts the same local HTTP server and opens your browser, just like the regular
`great-docs preview` command.

## Previewing a PR or CI Build [version-badge new 0.16] {#pr-preview}

When someone opens a pull request, reviewing the rendered docs usually means checking out the
branch and rebuilding locally, or setting up a preview host (Netlify, Cloudflare Pages,
per-PR GitHub Pages). But if your CI already builds and uploads the site as an artifact
(as the [recommended workflow](14-deployment.qmd) does) you can fetch that exact build and
view it locally (with no hosting setup):

```{.bash filename="Terminal"}
great-docs preview --pr 302             # newest CI docs build for PR #302
great-docs preview --run 18273645521    # a specific workflow run
great-docs preview --branch fix-mcp     # newest build for a branch
```

Great Docs resolves the pull request to its most recent successful docs run, downloads the
`docs-html` artifact, caches it locally, and serves it with the usual preview server.

### Authentication

Downloading a workflow artifact requires a GitHub token with **Actions: read** (this is
true even for public repositories). Great Docs looks for credentials in this order, so pick
whichever is convenient:

- `GITHUB_TOKEN` or `GH_TOKEN` in your environment
- a `.env` file with `GITHUB_TOKEN=...` (auto-detected, or point at one with `--env-file`)
- the [`gh`](https://cli.github.com/) CLI: run `gh auth login`, then add `--use-gh` to let
  `gh` perform the download end-to-end

```{.bash filename="Terminal"}
gh auth login
great-docs preview --pr 302 --use-gh
```

::: {.callout-note}
Great Docs never accepts a token as a command-line argument (it would leak into your shell
history). Use an environment variable, a `.env` file, or `gh` instead.
:::

### Jumping to a specific page

Use `--path` to open the browser directly at a page within the site instead of the home
page, useful when a review comment is about one specific reference or guide:

```{.bash filename="Terminal"}
great-docs preview --pr 302 --path reference/index.html
```

### Other options

| Option | Purpose |
| --- | --- |
| `--repo owner/repo` | Target a repo explicitly (default: detected from `git remote origin`). |
| `--artifact <name>` | Fetch a differently-named artifact (default: `docs-html`). |
| `--no-open` | Serve without launching a browser. |
| `--refresh` | Ignore the local cache and re-download. |
| `--port <n>` | Serve on a specific port. |

::: {.callout-warning}
## Fork pull requests

A site built from a fork contains contributor-authored HTML and JavaScript, which your
browser will execute when you preview it locally (the same trust level as reviewing their
diff). Great Docs warns you when a build comes from a fork.
:::

::: {.callout-tip}
## Advertise it in CI

If you scaffolded your CI with [`great-docs setup-github-pages`](14-deployment.qmd), this is
already wired up: on every pull request the workflow prints a log notice **and** posts a
sticky PR comment with the exact `great-docs preview` command, pinned to that run.

To add it to a hand-maintained workflow, use the `great-docs ci` helpers. `ci notice` prints
a log annotation; `ci pr-comment` posts (and keeps updated) a sticky comment on the pull
request. Both pin the command to the run that produced the build with `--run`, so a reviewer
reproduces exactly the build they're looking at:

```{.yaml filename=".github/workflows/docs.yml"}
      # In the build job (great-docs is already installed):
      - name: How to preview this build locally
        if: github.event_name == 'pull_request'
        run: great-docs ci notice --run ${{ github.run_id }} --pr ${{ github.event.number }}

      # In a separate job with 'permissions: pull-requests: write':
      - name: Post preview instructions to the PR
        run: pipx run great-docs ci pr-comment --run ${{ github.run_id }} --pr ${{ github.event.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
:::

## Using the Python API

In addition to the CLI, you can drive the build programmatically:

```{.python filename="Python"}
from great_docs import GreatDocs

docs = GreatDocs()
docs.install()   # Initialize the output directory
docs.build()     # Run the full build pipeline
docs.preview()   # Start the preview server
```

The `GreatDocs` class accepts a `project_path` argument if your working directory is not the project
root:

```{.python filename="Python"}
docs = GreatDocs(project_path="/path/to/my-project")
docs.install()
docs.build()
```

## Troubleshooting

### Quarto Errors

If the build fails during the Quarto rendering step, the error output will include Quarto's own
messages. Common causes include:

- A `.qmd` file with invalid YAML frontmatter. Check that all frontmatter blocks are enclosed
between `---` markers and that the YAML is well-formed.
- A reference to a file that does not exist. If you renamed or deleted a user guide page, make
sure the `guide-section` frontmatter in other files does not depend on it.
- A Quarto version incompatibility. Great Docs is tested with Quarto 1.4 and later. Run
`quarto --version` to check your installed version.

### Missing API Reference Pages

If some symbols are missing from the rendered API reference, run `great-docs scan` to see what Great
Docs discovers. Items that appear in the scan output but not in the reference may be excluded by the
`exclude` list in `great-docs.yml` or may not be listed in the `reference` config sections.

### Dynamic Introspection Failures

If Great Docs reports an error during dynamic introspection, it will automatically retry with static
analysis. If you see this retry message frequently, you can set `dynamic: false` in `great-docs.yml`
to skip the dynamic pass entirely. See [Configuration](configuration.qmd) for details.

### Stale Output

If your site looks correct in some places but outdated in others, the most reliable fix is a clean
rebuild: delete the `great-docs/` directory and run `great-docs build` again. The output directory
is fully regenerated each time, so there is no risk in deleting it.

## Build Timings [version-badge new 0.12] {#build-timings}

Every time `great-docs build` runs, it records how long each page takes to render and writes the
results to `great-docs/_site/build-timings.json`. This helps you identify slow pages that are
bottlenecks in your build.

### Viewing Timings

Use the `great-docs timings` command to display a sorted table (slowest pages first):

```{.bash filename="Terminal"}
great-docs timings
```

```{.default}
  Build time: 2026-05-06 14:32:01
  Total: 47.2s across 38 pages

  Page                              Time
  ─────────────────────────────────────────────────
  reference/GT.qmd                  12.4s  ████████████
  reference/GT.tab_style.qmd         6.1s  ██████
  user-guide/theming.qmd             4.8s  █████
  reference/GT.fmt_number.qmd        3.9s  ████
  ...
```

Pages served from the [Quarto freeze cache](freeze.qmd) are marked with a ❄ indicator. This view
makes it easy to spot which pages are worth optimizing or splitting up.

### Filtering Results

Show only the top N slowest pages:

```{.bash filename="Terminal"}
great-docs timings --top 5
```

For multi-version builds, filter by version:

```{.bash filename="Terminal"}
great-docs timings --version 0.10
```

These filters are useful when you only care about a specific slice of the build.

### Custom Output Directories

If you built with a custom `--output-dir`, pass the same path:

```{.bash filename="Terminal"}
great-docs timings --output-dir ./public
```

This ensures the command can locate `build-timings.json` regardless of where the site was rendered.

### JSON Output

For scripting or CI integration, use `--json` to get the raw data:

```{.bash filename="Terminal"}
great-docs timings --json
```

The JSON format is convenient for piping into other tools like `jq` or for building custom
dashboards.

### CI Integration

The `great-docs setup-github-pages` workflow automatically uploads `build-timings.json` as a
separate artifact named **build-timings** in each CI run. You can download it from the workflow
run's Artifacts section on GitHub to compare build performance over time. This makes it easier to
track regressions and monitor improvements across commits.

## Next Steps

The build pipeline is designed to be fast and predictable. For most projects, `great-docs build` is
really all you need. When something goes wrong, the troubleshooting tips above probably cover the
most common causes.

- [Deployment](deployment.qmd) covers publishing your built site to GitHub Pages
- [Configuration](configuration.qmd) covers all `great-docs.yml` options
- [Link Checker](link-checker.qmd) explains how to validate links across your site


# Deployment

Great Docs makes it easy to publish your documentation to GitHub Pages with automatic builds on every push.

## Quick Setup

Deploy to GitHub Pages with a single command:

```{.bash filename="Terminal"}
great-docs setup-github-pages
```

This creates a complete GitHub Actions workflow at `.github/workflows/docs.yml`.

## What the Workflow Does

The generated workflow includes three jobs:

### 1. Build Documentation

- Checks out your repository
- Sets up Python and Quarto
- Installs dependencies (with caching)
- Runs `great-docs build`
- Uploads the built site as an artifact

### 2. Publish to GitHub Pages

- Downloads the built artifact
- Deploys to GitHub Pages
- Only runs on pushes to your main branch

### 3. Preview for Pull Requests

- Creates preview deployments for PRs
- Lets reviewers see documentation changes before merging

## Enabling GitHub Pages

After generating the workflow:

1. **Commit and push** the workflow file:

   ```{.bash filename="Terminal"}
   git add .github/workflows/docs.yml
   git commit -m "Add documentation workflow"
   git push
   ```

2. **Enable GitHub Pages** in your repository:
   - Go to **Settings → Pages**
   - Set **Source** to `GitHub Actions`

3. **Trigger a build** by pushing to your main branch

Your documentation will be published at:

```
https://[username].github.io/[repository]/
```

## Customization Options

### Different Main Branch

```{.bash filename="Terminal"}
great-docs setup-github-pages --main-branch develop
```

### Different Python Version

```{.bash filename="Terminal"}
great-docs setup-github-pages --python-version 3.12
```

### Combined Options

```{.bash filename="Terminal"}
great-docs setup-github-pages \
  --main-branch develop \
  --python-version 3.12
```

### Force Overwrite

```{.bash filename="Terminal"}
great-docs setup-github-pages --force
```

## Generated Workflow

Here's what the generated workflow looks like:

```{.yaml filename=".github/workflows/docs.yml"}
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install dependencies
        run: |
          pip install great-docs
          pip install -e .

      - name: Build documentation
        run: great-docs build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: great-docs/_site
          include-hidden-files: true

  publish-docs:
    needs: build-docs
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5
```

## Manual Deployment

If you prefer to deploy manually or use a different hosting service:

### Build Locally

```{.bash filename="Terminal"}
great-docs build
```

### Upload the Built Site

The built site is in `great-docs/_site/`. Upload this directory to your hosting service:

- **Netlify**: Drag and drop `great-docs/_site/` folder
- **Vercel**: Point to `great-docs/_site` as output directory
- **AWS S3**: Sync the `great-docs/_site/` folder to your bucket
- **Any static host**: Copy contents of `great-docs/_site/`

## Subdirectory Deployments

If your site is hosted at a subpath rather than a domain root (for example,
`https://internal.example.com/docs/mypackage/`), you need to tell Quarto the base URL so it
generates correct root-relative paths for CSS, JS, and navigation links.

Set `site_url` in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
site_url: "https://internal.example.com/docs/mypackage/"
```

This writes `website.site-url` into the generated `_quarto.yml` during every
build, so you never have to patch the config manually.

### What it fixes

Without `site_url`, Quarto generates root-relative asset paths like `/site_libs/...` and
`/reference/...`. When the site lives at a subpath, those paths resolve to the wrong location and
the site appears broken (missing styles, broken navigation, 404s on the reference section, etc.).

### Versioned sites

For multi-version builds, Great Docs automatically appends the version prefix to `site-url` for
non-latest versions. If your `site_url` is:

```
https://internal.example.com/docs/mypackage/
```

then version `0.2` (served at `/v/0.2/`) will use:

```
https://internal.example.com/docs/mypackage/v/0.2/
```

No extra configuration is needed.

### When you don't need it

If you deploy to a domain root (e.g., `https://yourpackage.github.io/` or a custom domain), you do
not need to set `site_url`. Quarto's defaults work correctly in that case.

## Custom Domain

To use a custom domain with GitHub Pages:

1. Add a `CNAME` file to your project root (it will be copied during build):

   ```{.default filename="CNAME"}
   docs.example.com
   ```

2. Configure DNS with your domain registrar:
   - Add a CNAME record pointing to `[username].github.io`

3. In GitHub repository settings:
   - Go to **Settings → Pages**
   - Enter your custom domain
   - Enable "Enforce HTTPS"

## Troubleshooting

### Build Fails

Check the GitHub Actions logs for errors. Common issues:

- **Missing dependencies**: Ensure your `pyproject.toml` lists all dependencies
- **Quarto version**: The workflow uses the latest Quarto; ensure compatibility
- **Python version**: Make sure your code works with the specified Python version

### Pages Not Updating

If your documentation seems stuck on an old version, there are several things to check. First, verify the workflow completed successfully in the Actions tab. Then confirm that your GitHub Pages source is set to "GitHub Actions" in repository settings. Sometimes it's simply browser caching. Try clearing your cache or viewing in incognito mode.

### Preview Not Working

Pull request previews need a few things to be in place. The workflow must complete successfully, your repository needs appropriate permissions configured, and the `actions/deploy-pages` action must be allowed in your organization settings. Check each of these if previews aren't appearing on your PRs.

## Best Practices

### Keep Documentation in Sync

Run `great-docs build` locally before pushing to catch errors early:

```bash
great-docs build && open great-docs/_site/index.html
```

### Use Pull Request Previews

Review documentation changes in PRs before merging. This catches:

- Broken links
- Formatting issues
- Missing content

### Version Your Documentation

For versioned documentation, consider:

- Separate branches for major versions
- Using tools like `mike` for version switching
- Tagging releases with corresponding docs

## Next Steps

With Great Docs and GitHub Pages, you get automatic builds on every push, preview deployments for pull requests, zero-maintenance hosting, custom domain support, and HTTPS out of the box. Your documentation stays in sync with your code automatically.

- [Building & Previewing](building.qmd) covers the full build pipeline and local preview
- [Configuration](configuration.qmd) covers all `great-docs.yml` options
- [SEO Optimization](seo.qmd) explains how to improve your site's search visibility



## Quality & Maintenance

# Link Checker

Great Docs includes a built-in link checker that scans your documentation and source code for broken links. This helps maintain the quality of your documentation by catching dead links before they frustrate your users.

## Quick Start

Check all links in your project:

```{.bash filename="Terminal"}
great-docs check-links
```

The command scans both your documentation files (`.qmd`, `.md`) and Python source code for URLs, then checks each one for validity.

## What Gets Checked

The link checker extracts URLs from:

- **Documentation files**: All `.qmd` and `.md` files in your docs directory
- **Source code**: Python files in your package directory (docstrings, comments, string literals)
- **README**: Your project's `README.md` file

Each URL is checked with an HTTP HEAD request (falling back to GET if needed) to verify it returns a successful status code.

## Understanding the Output

The link checker categorizes URLs into four groups:

### ✅ OK (2xx responses)

Links that return successful HTTP status codes (200-299). These are working correctly.

### ⚠️ Redirects (3xx responses)

Links that redirect to another URL. While these still work, you may want to update them to point directly to the final destination:

```
⚠️  301 https://old-url.com → https://new-url.com
```

### ❌ Broken (4xx/5xx responses)

Links that return error status codes. These need to be fixed:

```
❌ 404 https://example.com/deleted-page (Not Found)
❌ 500 https://example.com/broken (Server Error)
```

### ⏭️ Skipped

Links that match ignore patterns and weren't checked.

## Command Options

### Check Only Documentation

Skip source code and only check documentation files:

```{.bash filename="Terminal"}
great-docs check-links --docs-only
```

### Check Only Source Code

Skip documentation and only check Python source files:

```{.bash filename="Terminal"}
great-docs check-links --source-only
```

### Verbose Output

See progress for every URL being checked:

```{.bash filename="Terminal"}
great-docs check-links --verbose
```

### Custom Timeout

Adjust the timeout for slow servers (default is 10 seconds):

```{.bash filename="Terminal"}
great-docs check-links --timeout 5
```

### JSON Output

Get results in JSON format for CI/CD integration:

```{.bash filename="Terminal"}
great-docs check-links --json-output
```

### Ignore Patterns

Skip URLs matching specific patterns:

```{.bash filename="Terminal"}
great-docs check-links -i "internal.company.com" -i "localhost"
```

Patterns can be literal strings or regular expressions:

```{.bash filename="Terminal"}
# Ignore all GitHub anchor links
great-docs check-links -i "github.com/.*#"

# Ignore version-specific URLs
great-docs check-links -i "docs\.example\.com/v\d+"
```

## Default Ignore Patterns

The link checker automatically skips certain URLs that are commonly used as examples or placeholders:

| Pattern | Description |
|---------|-------------|
| `localhost` | Local development servers |
| `127.0.0.1` | Local IP addresses |
| `example.com` | RFC 2606 reserved domain |
| `example.org` | RFC 2606 reserved domain |
| `yoursite.com` | Common placeholder |
| `YOUR-USERNAME` | GitHub template placeholder |
| `[...]` | Bracket placeholders like `[username]` |
| `.git@` or `.git$` | Git repository URLs with branches |

## Excluding URLs in Documentation

In `.qmd` files, you can mark specific URLs for exclusion by adding `{.gd-no-link}` immediately after the URL.

```markdown
Visit http://fake-example.com{.gd-no-link} for a placeholder example.

See https://yoursite.com/api/endpoint{.gd-no-link} for the API format.
```

This is useful for:

- **Example URLs** that are intentionally fake
- **Template URLs** showing a pattern users should customize
- **Placeholder URLs** in code examples

The `{.gd-no-link}` directive uses Quarto's attribute syntax but doesn't render any visible styling (it simply tells the link checker to skip that URL).

::: {.callout-note}
The `{.gd-no-link}` directive only works in `.qmd` files. For `.md` files or source code, use the `--ignore` command-line option instead.
:::

## Python API

You can also use the link checker programmatically:

```python
from great_docs import GreatDocs

docs = GreatDocs()
results = docs.check_links(
    include_source=True,
    include_docs=True,
    timeout=10.0,
    ignore_patterns=["localhost", "example.com"],
    verbose=False,
)

print(f"Total links: {results['total']}")
print(f"OK: {len(results['ok'])}")
print(f"Redirects: {len(results['redirects'])}")
print(f"Broken: {len(results['broken'])}")
print(f"Skipped: {len(results['skipped'])}")

# Handle broken links
for item in results['broken']:
    print(f"Broken: {item['url']} - {item['error']}")

# Handle redirects
for item in results['redirects']:
    print(f"Redirect: {item['url']} → {item['location']}")
```

### Return Value

The `check_links()` method returns a dictionary with:

| Key | Type | Description |
|-----|------|-------------|
| `total` | `int` | Total unique URLs found |
| `ok` | `list[str]` | URLs returning 2xx status |
| `redirects` | `list[dict]` | URLs returning 3xx status (with `url`, `status`, `location`) |
| `broken` | `list[dict]` | URLs returning 4xx/5xx or errors (with `url`, `status`, `error`) |
| `skipped` | `list[str]` | URLs matching ignore patterns |
| `by_file` | `dict[str, list[str]]` | Mapping of file paths to URLs found in each |

## CI/CD Integration

### Exit Codes

The `check-links` command returns:

- **Exit code 0**: All links are valid (or only redirects/skipped)
- **Exit code 1**: One or more broken links found

This makes it easy to fail CI builds when broken links are detected.

### GitHub Actions Example

Add link checking to your documentation workflow:

```yaml
name: Check Documentation Links

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Run weekly to catch external link rot
    - cron: '0 0 * * 0'

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install great-docs

      - name: Check links
        run: |
          great-docs check-links --docs-only --timeout 15
```

### Scheduled Checks

External links can break over time ("link rot"). Consider running the link checker on a schedule to catch these issues:

```yaml
on:
  schedule:
    # Every Sunday at midnight
    - cron: '0 0 * * 0'
```

## Tips and Best Practices

### Start with Documentation Only

If your source code has many URLs (e.g., in comments or docstrings), start by checking just documentation:

```{.bash filename="Terminal"}
great-docs check-links --docs-only
```

### Use Verbose Mode for Debugging

When troubleshooting, verbose mode shows you exactly what's being checked:

```{.bash filename="Terminal"}
great-docs check-links --verbose
```

### Handle Rate Limiting

Some websites rate-limit requests. If you're getting false positives, try:

1. Increasing the timeout: `--timeout 30`
2. Running the check less frequently in CI
3. Ignoring specific domains: `-i "api.example.com"`

### Fix Redirects Proactively

While redirects still work, they:

- Add latency for users clicking links
- May eventually break if the redirect is removed
- Indicate outdated references

Update redirected links to point to their final destinations when practical.

### Document Intentional Placeholder URLs

When using fake URLs in examples, mark them with `{.gd-no-link}` to make your intent clear and prevent false positives:

```markdown
Replace `https://your-api.com/endpoint`{.gd-no-link} with your actual API URL.
```

## Next Steps

The link checker catches broken references before your readers do. Run it locally during development and in CI before every deploy to keep your documentation reliable.

- [Proofreading](proofreading.qmd) checks spelling, grammar, and style across your documentation
- [Docs Linting](linting.qmd) validates docstring directives, cross-references, and structural issues
- [Building & Previewing](building.qmd) covers the full build pipeline


### Proofreading

Good documentation requires accurate spelling and grammar. Great Docs includes a proofreading command that checks your documentation for spelling mistakes, grammar issues, and common writing problems using [Harper](https://github.com/Automattic/harper), a fast, privacy-focused grammar checker that runs entirely on your machine.

## Installing Harper

The proofreader requires Harper to be installed separately. It's a single binary with no dependencies:

::: {.panel-tabset}

### macOS (Homebrew)

```bash
brew install harper
```

### Any Platform (Cargo)

```bash
cargo install harper-cli
```

### Manual Download

Download pre-built binaries from the [Harper releases page](https://github.com/Automattic/harper/releases).

:::

Verify the installation:

```bash
harper-cli --version
```

## What Gets Checked

The proofreader scans all `.qmd` and `.md` files in your documentation site directory. It automatically skips:

- **Fenced code blocks** - Content between ` ``` ` markers
- **YAML frontmatter** - Content between `---` markers at the start of files

Inline code (backticked text) is checked for typos.

## Basic Usage

Run the proofreader from your project directory:

```bash
great-docs proofread
```

This checks all documentation files and reports any issues found. By default, rules that tend to produce false positives in technical documentation are disabled.

## Filtering by File

Check specific files or patterns:

```bash
# Check one file
great-docs proofread user-guide/getting-started.qmd

# Check all files in a directory
great-docs proofread recipes/
```

## Custom Dictionary

### Adding Words on the Command Line

For project-specific terminology, add custom words using `-d`:

```bash
great-docs proofread -d "griffe" -d "pkgdown" -d "navbar"
```

### Built-in Technical Dictionary

Great Docs includes a built-in dictionary of common technical terms (API, CLI, PyPI, navbar, docstring, etc.) that are automatically accepted. To disable this:

```bash
great-docs proofread --no-builtin-dictionary
```

## Strict Mode

The default settings skip rules that often produce false positives in technical writing. To enable all Harper rules:

```bash
great-docs proofread --strict
```

This is useful for final polishing or when writing prose-heavy content like blog posts.

## Spelling-Only or Grammar-Only

Focus on just one type of check:

```bash
# Only spelling errors
great-docs proofread --spelling-only

# Only grammar issues
great-docs proofread --grammar-only
```

## English Dialect

Harper supports different English dialects. The default is American English:

```bash
great-docs proofread --dialect British
```

Available dialects: `American` (default), `British`, `Australian`, `Canadian`.

## Output Formats

### Default Output

The default output groups issues by file with context:

```
user-guide/getting-started.qmd:
  Line 12: "recieve" - Did you mean "receive"?
  Line 45: Consider using "use" instead of "utilize"
```

### Compact Output

For a condensed one-line-per-issue format:

```bash
great-docs proofread --compact
```

### JSON Output

For programmatic processing or CI integration:

```bash
great-docs proofread --json-output
```

## CI/CD Integration

### GitHub Actions

Add proofreading to your CI workflow:

```{.yaml filename=".github/workflows/docs.yml"}
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  proofread:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install Harper
        run: cargo install harper-cli

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install great-docs

      - name: Proofread documentation
        run: great-docs proofread
```

### Pre-commit Hook

Add proofreading as a pre-commit hook:

```{.yaml filename=".pre-commit-config.yaml"}
repos:
  - repo: local
    hooks:
      - id: proofread
        name: Proofread Documentation
        entry: great-docs proofread
        language: system
        types: [markdown]
        pass_filenames: false
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | No issues found |
| 1 | Issues found or error occurred |

## Default Ignored Rules

By default, these Harper rules are disabled because they frequently trigger on valid technical documentation patterns:

- **Spacing rules** - Technical docs often have unconventional spacing around operators and in code
- **Capitalization rules** - Many technical terms have specific capitalization (macOS, iOS)
- **Compound word rules** - Technical terms like navbar, frontend, codebase are flagged as compounds
- **Punctuation rules** - Quote marks and dashes in code examples differ from prose conventions

Use `--strict` to enable all rules.

## Best Practices

1. **Install Harper in CI** - Use `cargo install harper-cli` in your workflow
2. **Run proofread in CI** to catch issues before they reach production
3. **Use `--strict` sparingly** - Default settings are tuned for technical docs
4. **Add project-specific terms** with `-d` for domain-specific vocabulary
5. **Combine with link checking** for comprehensive documentation QA:

```bash
great-docs check-links && great-docs proofread
```

## Programmatic Usage

You can also use the proofreader programmatically:

```python
from great_docs import GreatDocs

docs = GreatDocs()

# Basic proofread
results = docs.proofread()
for file_result in results:
    if file_result.issues:
        print(f"{file_result.file}: {len(file_result.issues)} issues")

# With custom dictionary
results = docs.proofread(
    custom_words=["griffe", "pkgdown"],
)

# Strict mode (all rules enabled)
results = docs.proofread(strict=True)

# Process results
for file_result in results:
    for issue in file_result.issues:
        print(f"Line {issue.line}: {issue.message}")
        if issue.suggestions:
            print(f"  Suggestions: {issue.suggestions[:3]}")
```

## Next Steps

Proofreading catches the small errors that accumulate over time: misspellings, repeated words, and style inconsistencies. Run it alongside the link checker and linter to keep your documentation polished.

- [Link Checker](link-checker.qmd) validates that all links in your documentation resolve correctly
- [Docs Linting](linting.qmd) checks docstring directives, cross-references, and structural issues
- [Configuration](configuration.qmd) covers custom dictionaries and proofreading settings in `great-docs.yml`


# Changelog

Users want to know what changed between versions, whether that's new features, bug fixes, or breaking changes. A well-maintained changelog builds trust and helps people decide when to upgrade. But keeping a separate changelog file in sync with your actual releases is tedious and error-prone.

Great Docs solves this by automatically generating a Changelog page from your GitHub Releases. Each published release becomes a section on the page, with its title, date, body content, and a link back to the release on GitHub. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.

## How It Works

When changelog generation is enabled (the default), `great-docs build` will:

1. **Detect your GitHub repository**: reads the `Repository` URL from `[project.urls]` in `pyproject.toml`
2. **Fetch releases**: calls the GitHub Releases API to retrieve published releases
3. **Generate the page**: writes a `changelog.qmd` file in the build directory with one section per release
4. **Add a navbar link**: adds a "Changelog" item to the site's top navigation bar

The result is a fully rendered Changelog page that stays in sync with your GitHub Releases. No manual maintenance is needed, and the page is regenerated on every build.

## Prerequisites

For changelog generation to work, Great Docs needs to know where your repository lives. Your `pyproject.toml` must include a `Repository` URL pointing to GitHub:

```{.toml filename="pyproject.toml"}
[project.urls]
Repository = "https://github.com/your-org/your-package"
```

If no GitHub URL is found, the changelog step is silently skipped and the build continues normally.

## Configuration

The changelog works out of the box with sensible defaults. You only need to add a `changelog` section to `great-docs.yml` if you want to change the behavior:

```{.yaml filename="great-docs.yml"}
changelog:
  enabled: true        # Enable/disable changelog (default: true)
  max_releases: 50     # Maximum releases to include (default: 50)
```

### Disabling the Changelog

If you don't want a changelog page at all:

```{.yaml filename="great-docs.yml"}
changelog:
  enabled: false
```

### Limiting Releases

For projects with many releases, you can cap how many appear:

```{.yaml filename="great-docs.yml"}
changelog:
  max_releases: 20
```

Releases are shown in reverse chronological order (newest first), so older releases are the ones omitted.

## Authentication

The GitHub API allows unauthenticated requests but with a low rate limit (60 requests/hour). For most projects this is sufficient because the changelog is only fetched once per build. If you hit rate limits (particularly in CI environments with many concurrent builds), set a GitHub token:

```{.bash filename="Terminal"}
export GITHUB_TOKEN=ghp_your_token_here
```

Great Docs checks for `GITHUB_TOKEN` or `GH_TOKEN` environment variables and uses whichever is set. A token raises the rate limit to 5,000 requests/hour.

::: {.callout-tip}
## GitHub Actions

In GitHub Actions workflows, `GITHUB_TOKEN` is already available automatically. No extra setup is needed.
:::

## Standalone CLI Command

You can generate the changelog independently of a full build. This is useful for testing your release notes formatting or regenerating just the changelog without rebuilding the entire site:

```{.bash filename="Terminal"}
great-docs changelog
```

You can also override the max releases:

```{.bash filename="Terminal"}
great-docs changelog --max-releases 10
```

The output is written to the build directory, just as it would be during a full `great-docs build`.

## What Gets Included

Not all GitHub Releases appear on the changelog page. Here is how each release type is handled:

- **Published releases**: shown with their title, date, and body
- **Pre-releases**: included but marked with a "(Pre-release)" badge
- **Draft releases**: excluded (they aren't public yet)

The release body is rendered as Markdown, so any formatting, lists, headings, or code blocks in your GitHub Release notes carry through to the documentation site. This means the changelog page looks just as rich as your release notes on GitHub.

## Generated Output

The generated `changelog.qmd` page includes:

- A title ("Changelog") and table of contents
- An introductory line linking to the full GitHub Releases page
- One `##` section per release, containing:
  - The release name as the heading
  - A metadata line with the publication date and a "View on GitHub" link
  - The full release body as Markdown

Here's an example of what a section looks like:

```markdown
## Version 2.0.0

*2026-01-15* · [View on GitHub](https://github.com/org/pkg/releases/tag/v2.0.0)

### What's New

- Added feature X
- Improved performance of Y

### Breaking Changes

- Removed deprecated `old_function()`
```

The page is self-contained: readers can browse all release notes in one place without leaving your documentation site.

## Edge Cases

Great Docs is designed to handle common failure scenarios gracefully. The changelog is never a hard failure; the build always completes successfully.

| Scenario | Behavior |
|---|---|
| No GitHub URL in `pyproject.toml` | Changelog step is skipped silently |
| Repository exists but has no releases | No `changelog.qmd` is created; build continues normally |
| GitHub API rate limit reached | Warning printed; partial results used if any were already fetched |
| GitHub API returns 404 | Warning printed; changelog skipped |
| Network error | Warning printed; changelog skipped |

## Next Steps

The changelog is fully automatic: Great Docs fetches your GitHub Releases, formats them into a navigable page, and regenerates it on every build. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.

- [Community Files](community-files.qmd) covers other auto-detected files like `CONTRIBUTING.md` and `ROADMAP.md`
- [Deployment](deployment.qmd) covers publishing your docs (including the changelog) to GitHub Pages
- [Link Checker](link-checker.qmd) validates that changelog links to GitHub are not broken
- [Configuration](configuration.qmd) covers all available `great-docs.yml` options


# Community Files

Open-source projects rely on more than just code. Files like `CONTRIBUTING.md`,
`CODE_OF_CONDUCT.md`, and `SECURITY.md` set expectations for how people participate in and interact
with a project. Most projects already have these files, but they often sit in the repository root
where casual users never see them.

Great Docs automatically detects these standard community files and turns them into styled pages on
your documentation site. Each detected file gets its own page and a link in the **Community**
section of the homepage's right sidebar. No configuration is needed. If the file exists, it becomes
part of your site.

## Supported Files

Great Docs recognizes the following community files:

| File | Generated Page | Sidebar Link |
|------|---------------|--------------|
| `CONTRIBUTING.md` | `contributing.qmd` | "Contributor guidelines" |
| `CODE_OF_CONDUCT.md` | `code-of-conduct.qmd` | "Code of conduct" |
| `ROADMAP.md` [version-badge new 0.2] | `roadmap.qmd` | "Project roadmap" |
| `SECURITY.md` [version-badge new 0.3] | `security.qmd` | "Security policy" |
| `CITATION.cff` | `citation.qmd` | "Citing *package*" |

These files follow the common conventions used by most open-source projects, so if you already have
them, they'll work automatically.

## How It Works

During `great-docs build`, each community file goes through a simple pipeline:

1. **Detects the file** in your project root (and `.github/` as a fallback)
2. **Strips the title** by removing the first `# ` heading line (since Great Docs adds its own title
via frontmatter)
3. **Generates a `.qmd` file** in the build directory with appropriate frontmatter
4. **Adds a sidebar link** in the Community section of the homepage's right margin

::: {.callout-tip}
## Community file locations

GitHub accepts `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` in your project root,
`docs/`, or `.github/`. Great Docs searches only the project root and `.github/`, in that order.
Both locations work without configuration.

Great Docs generates `contributing.qmd`, `code-of-conduct.qmd`, and `security.qmd` from the files
it finds, then links them from the homepage. Link to these generated pages instead of embedding
the source files in another page. An include such as
`{{{< include "../../../.github/CONTRIBUTING.md" >}}}` depends on the build directory's depth.
:::

The original Markdown content is preserved, so any formatting, images, or links in your community
files carry through to the documentation site. The generated `.qmd` files are recreated on every
build, so changes to the source files are always picked up.

## Example

To see how everything comes together, consider a project with these files:

```
my-package/
├── .github/
│   └── SECURITY.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── ROADMAP.md
├── great-docs.yml
└── pyproject.toml
```

Will produce a homepage sidebar like:

```
Community
├── Contributor guidelines
├── Code of conduct
├── Project roadmap
├── Security policy
```

Clicking any link navigates to the corresponding page. If any of these files are missing, the
corresponding link is simply omitted.

## ROADMAP.md [version-badge new 0.2]

A `ROADMAP.md` file communicates your project's future direction to users and contributors. This
helps potential contributors understand where they can have the most impact and gives users
confidence that the project is actively maintained. Common sections include:

- **In Progress**: features currently being developed
- **Near Term**: planned for the next release cycle
- **Medium Term**: targeted for upcoming major versions
- **Long Term**: aspirational features on the horizon

### Example Structure

```markdown
# Roadmap

A summary of planned features and improvements.

## In Progress

### Feature Name
Brief description...

## Near Term

### Feature Name
Brief description...

## Long Term

### Feature Name
Brief description...
```

::: {.callout-tip}
## Keep it forward-looking
Focus on unshipped features. Shipped features are better documented in your Changelog
(auto-generated from GitHub Releases) or release notes.
:::

## CONTRIBUTING.md

A clear `CONTRIBUTING.md` lowers the barrier for new contributors. Without one, people who want to
help may not know where to start or what process to follow. Common sections include:

- development setup instructions
- how to run tests
- code style guidelines
- pull request process
- issue reporting guidelines

### Example Structure

```markdown
# Contributing

We welcome contributions! Here's how to get started.

## Development Setup

1. Clone the repo
2. Install dependencies: `pip install -e ".[dev]"`
3. Run tests: `pytest`

## Pull Request Process

1. Fork the repo and create a branch
2. Make your changes with tests
3. Submit a PR describing your changes
```

## SECURITY.md [version-badge new 0.3]

A `SECURITY.md` file tells users how to responsibly report security vulnerabilities. Without one,
people who discover a vulnerability may open a public issue, exposing the problem before a fix is
available. GitHub also recognizes this file and displays it under the **Security** tab of your
repository.

Great Docs looks for `SECURITY.md` in two locations (in order):

1. project root (`SECURITY.md`)
2. `.github/` directory (`.github/SECURITY.md`)

### Example Structure

```markdown
# Security Policy

## Reporting a Vulnerability

Please do not open a public issue. Instead, use the
Report a vulnerability function on the Security tab.

Your report should include:

- a clear description of the vulnerability
- steps to reproduce the issue
- any relevant code snippets or proof-of-concept

## Coordinated Disclosure

Once confirmed, we will notify you before public disclosure
and credit you in the release notes.
```

### Disabling the Security Page

To detect `SECURITY.md` but not generate a page for it, set `show_security: false` in
`great-docs.yml`:

```yaml
site:
  show_security: false
```

## CODE_OF_CONDUCT.md

A code of conduct sets expectations for community behavior and signals that your project takes a
welcoming environment seriously. Most projects adopt a standard like the
[Contributor Covenant](https://www.contributor-covenant.org/) rather than writing one from scratch.

### Using the Contributor Covenant

Download version 2.1 from the official site:

```bash
curl -o CODE_OF_CONDUCT.md https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md
```

Then customize the contact email at the bottom of the file.

## CITATION.cff

If your project has a `CITATION.cff` file, Great Docs generates a dedicated citation page
(`citation.qmd`) and adds a "Citing *package*" link to the Community sidebar. The generated page
includes a formatted author list, a text citation, and a BibTeX entry, all derived from the
structured data in the CFF file.

The `CITATION.cff` file is only used for the citation page. Author information displayed elsewhere
on the site (such as the Developers section of the homepage sidebar) comes from `great-docs.yml`
first, with `pyproject.toml` as a fallback.

### Example Structure

```{.yaml filename="CITATION.cff"}
cff-version: 1.2.0
title: "My Package"
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: Smith
    given-names: Jane
    orcid: "https://orcid.org/0000-0002-1234-5678"
version: 1.0.0
date-released: "2025-06-15"
license: MIT
repository-code: "https://github.com/example/my-package"
```

If a `repository-code` or `url` field is present, the citation page links back to the `CITATION.cff`
file on GitHub.

## `.github/` Directory Fallback

For `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`, Great Docs checks the `.github/`
directory if the file isn't found in the project root. This matches GitHub's own convention for
repository-level community health files, so projects that follow the GitHub standard layout work
without changes.

## Fallback Behavior

If a community file doesn't exist, the build continues without error. The corresponding link simply
won't appear in the sidebar. You can add community files at any time and they'll be automatically
detected on the next build. This means you can introduce community files gradually as your project
matures.

## Package Info

In addition to community files, Great Docs automatically generates a **Package Info** page that
displays your package's declared dependencies. This page surfaces important metadata about what your
package requires to run and what optional components are available.

### What It Shows

The Package Info page includes:

- runtime Dependencies: packages required to use your library (from `dependencies` in
`pyproject.toml`)
- optional Dependencies: extra packages grouped by feature (from `optional-dependencies`)
- version Constraints: specifier ranges for each package (e.g., `>=1.24`, `>=2.0,<3.0`)
- environment Markers: platform or Python version constraints (e.g., `python_version<'3.12'`)
- last Published: the latest release date of each dependency on PyPI
- PyPI Link: direct links to the PyPI page for each package

Dependencies are presented in tables with one group per optional dependency set (e.g., `dev`,
`docs`, `test`).

### Configuration

The Package Info page is enabled by default. To disable it, add to `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
package_info_page: false
```

### Accessing the Page

The Package Info page is accessible via a "Package Info" link in the **Meta** section of the
homepage sidebar (next to "Requires", "Provides-Extra", and "Site Tags"). The page is located at
`package-info.html` and is also included in your site's navigation and search index.

### When To Use It

This feature is useful for:

- users evaluating your package's compatibility with their environment
- CI/CD pipelines checking dependency requirements
- developers understanding what optional features are available
- dependency scanners and compliance tools

## Next Steps

Community files give your project a professional, welcoming presence without any configuration.
Adding a `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md` to your repository is all it takes to get a
styled page in your documentation site.

- [Changelog](changelog.qmd) covers auto-generating a changelog from GitHub Releases
- [Linting](linting.qmd) helps you catch broken links and other issues in community file pages
- [SEO & Metadata](seo.qmd) explains how community pages are included in site metadata
- [Configuration](configuration.qmd) covers all `great-docs.yml` options



## Site Content

# Diagrams

Some concepts are hard to explain with words alone. Architecture diagrams, workflow charts, and
sequence diagrams communicate structure and flow far more effectively than prose. But maintaining
diagrams as image files is fragile: they go out of date, they're hard to diff in version control,
and they require external tools to edit.

Great Docs supports two text-based diagram languages, both authored directly in fenced code blocks
so your diagrams live alongside your prose in version control and update just as easily:

- **[D2](https://d2lang.com)**: a modern diagramming language with a clean syntax and polished
  output. Great Docs renders D2 diagrams at build time into crisp SVGs, with separate light and dark
  versions that match your site's theme.
- **[Mermaid](https://mermaid.js.org/)**: a widely used diagram language rendered in the browser,
  supporting flowcharts, sequence, class, state, Gantt, and pie charts.

Both work seamlessly in light and dark mode, automatically adapting their colors for readability.

## D2 Diagrams

[D2](https://d2lang.com) ("Declarative Diagramming") turns a concise text description into a
polished diagram. Great Docs renders D2 blocks **at build time** using the `d2` command-line tool,
producing a self-contained SVG for each diagram.

### Prerequisites

D2 rendering requires the `d2` binary on your `PATH`. Install it once:

```bash
# macOS (Homebrew)
brew install d2

# or the official install script (macOS / Linux)
curl -fsSL https://d2lang.com/install.sh | sh -s --
```

See the [D2 install guide](https://d2lang.com/tour/install) for other platforms. If `d2` is not
installed, Great Docs leaves the code block untouched and prints a warning, so builds never fail
because of a missing binary (they simply skip diagram rendering until `d2` is available).

### Basic Usage

To add a D2 diagram, use a fenced code block with `{d2}` as the language identifier:

````markdown
```{d2}
Start -> Decision
Decision -> Action: Yes
Decision -> End: No
```
````

This renders as:

```{d2}
Start -> Decision
Decision -> Action: Yes
Decision -> End: No
```

Connections use `->` (or `<->`, `<-`, `--`), and text after a colon labels the connection. Declaring
a shape is as simple as naming it.

### Shapes and Containers

D2 supports a rich set of shapes and lets you nest related nodes inside containers using dot
notation. Containers are ideal for grouping the pieces of a subsystem:

```{d2}
build: Build Pipeline {
  parse -> generate
  generate -> render
}

deploy: Deploy {
  upload -> verify
}

build.render -> deploy.upload: publish
```

You can change any node's shape with the `shape` keyword:

```{d2}
config: great-docs.yml {
  shape: document
}
db: Cache {
  shape: cylinder
}
config -> build -> db
```

### Sequence Diagrams

D2 renders sequence diagrams from the same syntax by setting `shape: sequence_diagram`. They're
ideal for documenting API call flows or request/response cycles where order matters:

```{d2}
shape: sequence_diagram
User -> CLI: great-docs build
CLI -> Core: GreatDocs.build()
Core -> Core: Parse docstrings
Core -> Quarto: quarto render
Quarto -> Core: HTML output
Core -> CLI: Build complete
CLI -> User: Site ready
```

### Options

Fine-tune a diagram with `#|` option lines at the top of the block. These are stripped before the
diagram is rendered:

| Option       | Description                                              | Default |
|--------------|----------------------------------------------------------|---------|
| `theme`      | D2 theme id used for the light rendering                 | `0`     |
| `dark-theme` | D2 theme id used for the dark rendering                  | `200`   |
| `layout`     | Layout engine (`dagre`, `elk`, or `tala` if installed)   | `dagre` |
| `sketch`     | `true` for a hand-drawn look                             | `false` |
| `pad`        | Padding in pixels around the diagram                     | `20`    |
| `scale`      | Scale factor for the rendered output                     | auto    |

For example, a hand-drawn diagram with the ELK layout engine:

```{d2}
#| sketch: true
#| layout: elk
Idea -> Draft -> Review -> Publish
```

Run `d2 themes` to see the full catalog of light and dark theme ids.

### Dark Mode Support

Readers who switch between light and dark mode should not have to squint at a bright diagram on a
dark background. Because Great Docs renders a dedicated dark-theme SVG for every D2 diagram, dark
mode gets a genuinely dark diagram. The switch happens instantly when the reader toggles the theme,
with no additional configuration required.

## Mermaid Diagrams

[Mermaid](https://mermaid.js.org/) is rendered in the reader's browser and supports a broad set of
diagram types. Great Docs pins Mermaid to its light theme and, in dark mode, presents each diagram
inside a light background container so text and shapes stay clearly readable.

### Basic Usage

To add a Mermaid diagram, use a fenced code block with `{mermaid}` as the language identifier:

````markdown
```{mermaid}
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```
````

This renders as:

```{mermaid}
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

### Flowcharts

Flowcharts are the most common diagram type in technical documentation. They're useful for
documenting workflows, decision trees, or multi-step processes. Use `graph LR` for left-to-right
flow or `graph TD` for top-down:

```{mermaid}
graph TD
    A[great-docs init] --> B[Configure great-docs.yml]
    B --> C[Write docstrings]
    C --> D[great-docs build]
    D --> E{Preview OK?}
    E -->|Yes| F[Deploy to GitHub Pages]
    E -->|No| C
```

#### Flowchart Node Shapes

Mermaid supports various node shapes:

```{mermaid}
graph LR
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C --> D([Stadium])
    D --> E[[Subroutine]]
    E --> F[(Database)]
```

### Sequence Diagrams

Sequence diagrams show how components interact over time. They're ideal for documenting API call
flows, request/response cycles, or system interactions where the order of operations matters:

```{mermaid}
sequenceDiagram
    participant User
    participant CLI
    participant Core
    participant Quarto

    User->>CLI: great-docs build
    CLI->>Core: GreatDocs.build()
    Core->>Core: Parse docstrings
    Core->>Core: Generate .qmd files
    Core->>Quarto: quarto render
    Quarto-->>Core: HTML output
    Core-->>CLI: Build complete
    CLI-->>User: Site ready in great-docs/_site/
```

The `participant` declarations control the column order. Solid arrows (`->>`) represent calls, and
dashed arrows (`-->>`) represent returns.

### Class Diagrams

Class diagrams are perfect for documenting object-oriented code structures:

```{mermaid}
classDiagram
    class GreatDocs {
        +project_root: Path
        +config: Config
        +install()
        +build()
        +preview()
    }

    class Config {
        +package_name: str
        +exclude: list
        +logo: dict
        +load()
        +save()
    }

    GreatDocs --> Config : uses
```

Class diagrams support visibility modifiers (`+` public, `-` private, `#` protected) and
relationship types (inheritance, composition, association).

### State Diagrams

State diagrams help document state machines, lifecycle stages, or any system where items transition
between well-defined states:

```{mermaid}
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Accept
    Review --> Draft: Request changes
    Approved --> Published: Deploy
    Published --> [*]
```

The `[*]` node represents the start and end states.

### Gantt Charts

Gantt charts are useful for documenting project timelines, release schedules, or migration plans:

```{mermaid}
gantt
    title Documentation Release Schedule
    dateFormat YYYY-MM-DD
    section Phase 1
        API Documentation    :done, api, 2024-01-01, 2024-01-15
        User Guide          :done, guide, 2024-01-10, 2024-01-25
    section Phase 2
        CLI Reference       :active, cli, 2024-01-20, 2024-02-05
        Deployment Guide    :deploy, 2024-02-01, 2024-02-10
```

Tasks can be marked as `done`, `active`, or left unmarked for upcoming work.

### Pie Charts

Pie charts provide a quick visual summary of proportions:

```{mermaid}
pie title Documentation Coverage
    "API Reference" : 45
    "User Guide" : 30
    "Recipes" : 15
    "CLI Docs" : 10
```

Values are automatically converted to percentages.

### Dark Mode Support

Great Docs automatically adjusts Mermaid diagrams for dark mode by displaying them in a light
background container, ensuring text and shapes remain clearly readable. No additional configuration
is required.

## Tips for Better Diagrams

Text-based diagrams are easy to create, but a few practices help keep them clear and maintainable
(whether you use D2 or Mermaid).

### Keep Diagrams Focused

Each diagram should illustrate one concept. If a diagram becomes too complex, consider breaking it
into multiple smaller diagrams.

### Use Descriptive Labels

Node labels should be self-explanatory. Use action verbs for process steps and clear nouns for
entities:

```{d2}
Parse Config -> Discover Exports -> Generate Pages -> Render HTML
```

### Choose a Direction that Matches the Flow

Both languages let you set a direction. In D2, add `direction: right` (or `up`, `down`, `left`); in
Mermaid, use `graph LR`, `graph TD`, and so on. Pick the direction that best matches the process
you're documenting (left-to-right for pipelines, top-down for hierarchies and decision trees).

### Group Related Nodes

Group related nodes with D2 containers (`name { ... }`) or Mermaid subgraphs:

```{mermaid}
graph TD
    subgraph Build Process
        A[Parse] --> B[Generate]
        B --> C[Render]
    end
    subgraph Deploy
        D[Upload] --> E[Verify]
    end
    C --> D
```

For complete syntax references, see the [D2 documentation](https://d2lang.com/tour/intro) and the
[Mermaid documentation](https://mermaid.js.org/intro/). Quarto also provides additional options for
diagram sizing and placement in the
[Quarto Diagrams guide](https://quarto.org/docs/authoring/diagrams.html).

## Next Steps

Text-based diagrams let you visualize architecture, workflows, and relationships directly in your
documentation. Because they're defined in text, they stay in version control, diff cleanly, and
update alongside your prose.

- [Authoring QMD Files](authoring-qmd-files.qmd) covers other content building blocks like callouts,
  tabsets, and code blocks
- [Videos](videos.qmd) covers embedding YouTube, Vimeo, and Loom content
- [Cross-Referencing](cross-referencing.qmd) explains how to link diagram pages to API reference
items
- [Theming & Appearance](theming.qmd) explains how diagrams inherit your site's color scheme



## Build & Deploy

# SEO Optimization

Documentation is only useful if people can find it. When someone searches for how to install your
package or call a specific function, your docs should appear near the top of the results. Good SEO
ensures that search engines can crawl, index, and accurately represent your pages.

Great Docs includes comprehensive SEO features that are enabled by default and work automatically
when you build your site. Sitemaps, canonical URLs, meta descriptions, structured data, and robots
directives are all generated without any configuration.

## What's Included

Great Docs generates and injects SEO-related files and metadata automatically:

- **`sitemap.xml`**: helps search engines discover all your pages
- **`robots.txt`**: guides crawler behavior and references your sitemap
- **Canonical URLs**: prevents duplicate content issues
- **Meta descriptions**: provides search result snippets
- **JSON-LD structured data**: enables rich search results
- **Page title templates**: consistent `Page Title | Site Name` format

All of these are generated at build time. You can customize any of them or disable features you
don't need.

## Auditing SEO Health

After building your site, you can audit the generated output to verify that all SEO features are in
place. Run the SEO audit command to check for issues:

```{.bash filename="Terminal"}
great-docs seo
```

This produces a report like this:

```
════════════════════════════════════════════════════════════
📊 SEO Audit Results
════════════════════════════════════════════════════════════

✅ sitemap.xml: 65 URLs indexed
✅ robots.txt: includes sitemap reference
✅ robots.txt: has user-agent rules
✅ Analyzed 65 HTML pages
✅ All pages have canonical URLs
✅ All pages have meta descriptions
✅ 10 pages have JSON-LD structured data
✅ All images have alt text

────────────────────────────────────────────────────────────
✅ All SEO checks passed!
```

The audit checks every HTML page in the built site and reports missing or malformed SEO elements.

### Fixing Issues

Use `--fix` to automatically generate missing SEO files:

```{.bash filename="Terminal"}
great-docs seo --fix
```

This creates `sitemap.xml` and `robots.txt` if they're missing and patches any fixable issues in the
built output.

### CI Integration

For continuous integration, use `--json` for machine-readable output:

```{.bash filename="Terminal"}
great-docs seo --json
```

```json
{
  "status": "pass",
  "pages_checked": 65,
  "issues": [],
  "warnings": [],
  "info": ["✅ sitemap.xml: 65 URLs indexed", "..."]
}
```

The command exits with code `1` if critical issues are found, making it easy to fail CI builds on
SEO problems. Pair this with `great-docs lint` and `great-docs links` for a comprehensive
pre-deployment check.

## Configuration

All SEO settings live under the `seo` key in `great-docs.yml`. Here's the full configuration with
defaults:

```{.yaml filename="great-docs.yml"}
seo:
  enabled: true  # Master switch for all SEO features

  sitemap:
    enabled: true
    changefreq:
      homepage: weekly
      reference: monthly
      user_guide: monthly
      changelog: weekly
      default: monthly
    priority:
      homepage: 1.0
      reference: 0.8
      user_guide: 0.9
      changelog: 0.6
      default: 0.5

  robots:
    enabled: true
    allow_all: true
    disallow: []
    crawl_delay: null
    extra_rules: []

  canonical:
    enabled: true
    base_url: null  # Auto-detected from GitHub Pages

  title_template: "{page_title} | {site_name}"

  structured_data:
    enabled: true
    type: SoftwareSourceCode

  default_description: null  # Falls back to package description
```

Most users won't need to change these defaults. They are optimized for typical Python documentation
sites, and every feature can be toggled independently.

## Sitemap Configuration

The sitemap tells search engines about all your pages and how often they change. Great Docs
generates different priorities and change frequencies based on page type, so your most important
content gets crawled first.

### Page Types

Pages are automatically categorized based on their path in the built site:

| Type | Example Paths | Default Priority | Default Changefreq |
|------|---------------|------------------|-------------------|
| `homepage` | `index.html` | 1.0 | weekly |
| `user_guide` | `user-guide/*.html`, `recipes/*.html` | 0.9 | monthly |
| `reference` | `reference/*.html` | 0.8 | monthly |
| `changelog` | `changelog.html` | 0.6 | weekly |
| `default` | Everything else | 0.5 | monthly |

These defaults work well for most projects. The subsections below show how to override them if your
site has different needs.

### Customizing Priorities

Adjust priorities based on what's most important for your site:

```{.yaml filename="great-docs.yml"}
seo:
  sitemap:
    priority:
      homepage: 1.0
      user_guide: 0.9  # Your tutorials are most valuable
      reference: 0.7   # API docs are secondary
```

### Customizing Change Frequencies

If your reference documentation changes frequently:

```{.yaml filename="great-docs.yml"}
seo:
  sitemap:
    changefreq:
      reference: weekly  # API changes often
      changelog: daily   # Frequent releases
```

## Robots.txt Configuration

The `robots.txt` file tells search engine crawlers which pages to index and where to find your
sitemap. Great Docs generates one automatically, but you can customize it for more control over
crawler behavior.

### Default Behavior

By default, Great Docs generates a permissive `robots.txt`:

```{.txt filename="robots.txt"}
# Robots.txt generated by Great Docs

User-agent: *
Allow: /

Sitemap: https://username.github.io/repo/sitemap.xml
```

### Blocking Paths

To prevent indexing of specific paths (e.g., draft pages):

```{.yaml filename="great-docs.yml"}
seo:
  robots:
    disallow:
      - /drafts/
      - /_internal/
```

### Blocking AI Crawlers

Some projects prefer to block AI training crawlers:

```{.yaml filename="great-docs.yml"}
seo:
  robots:
    extra_rules:
      - "User-agent: GPTBot"
      - "Disallow: /"
      - "User-agent: CCBot"
      - "Disallow: /"
```

### Setting Crawl Delay

For sites with limited bandwidth:

```{.yaml filename="great-docs.yml"}
seo:
  robots:
    crawl_delay: 10  # Seconds between requests
```

## Canonical URLs

Canonical URLs tell search engines which version of a page is the "official" one. This prevents
duplicate content issues when your site is accessible via multiple URLs (for example, with and
without a trailing slash, or through both a custom domain and `github.io`).

### Auto-Detection

Great Docs automatically generates canonical URLs based on your GitHub repository. If your repo is
`github.com/username/repo`, the canonical base URL will be:

```
https://username.github.io/repo/
```

### Manual Configuration

For custom domains or non-GitHub hosting, set the base URL explicitly:

```{.yaml filename="great-docs.yml"}
seo:
  canonical:
    base_url: https://docs.myproject.com/
```

The trailing slash is important (Great Docs will add it if missing). Every page in the built site
receives a `<link rel="canonical">` tag pointing to its full URL.

## Page Titles

Great Docs applies a consistent title template to all pages, improving brand recognition in search
results.

### Default Template

The default template is `{page_title} | {site_name}`, which produces titles like:

- `Installation | My Package`
- `GreatDocs.build | My Package`
- `Configuration | My Package`

### Custom Templates

Change the separator or format:

```{.yaml filename="great-docs.yml"}
seo:
  title_template: "{page_title} - {site_name}"
```

Or remove the site name entirely:

```{.yaml filename="great-docs.yml"}
seo:
  title_template: "{page_title}"
```

## Structured Data (JSON-LD)

Structured data helps search engines understand what your site is about beyond plain text. Great
Docs injects [JSON-LD](https://json-ld.org/) structured data into your pages, enabling rich search
results with additional context about your software.

### What Gets Injected

On the homepage and reference pages, Great Docs adds a schema block like this:

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareSourceCode",
  "name": "My Package",
  "description": "A Python package for...",
  "codeRepository": "https://github.com/username/repo",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "Python"
  }
}
```

### Customizing the Schema Type

For different types of documentation:

```{.yaml filename="great-docs.yml"}
seo:
  structured_data:
    type: WebSite  # Or: SoftwareApplication, APIReference, etc.
```

### Disabling Structured Data

If you prefer not to include JSON-LD:

```{.yaml filename="great-docs.yml"}
seo:
  structured_data:
    enabled: false
```

## Meta Descriptions

Meta descriptions are the short summaries that appear below page titles in search results. A good
description improves click-through rates because it tells searchers exactly what they'll find on the
page. Great Docs generates these automatically from your content.

### Auto-Generation

For each page, Great Docs extracts a description from:

1. the first meaningful paragraph in the page content
2. falls back to the default description if no suitable content is found

### Setting a Default Description

Configure a fallback description for pages without extractable content:

```{.yaml filename="great-docs.yml"}
seo:
  default_description: "Documentation for My Package, a Python library for..."
```

If not set, the package description from `pyproject.toml` is used as a fallback.

### Page-Level Descriptions

For individual pages, add a `description` field in the YAML frontmatter:

```{.yaml filename="user_guide/01-installation.qmd"}
---
title: "Installation"
description: "How to install My Package using pip, conda, or from source."
---
```

## Noindex for Internal Pages

Not every page belongs in search results. Internal pages, drafts, or experimental features can
clutter search results and confuse users. Great Docs automatically adds `noindex` directives to
internal pages like the Skills page.

### Manual Noindex

To prevent a specific page from being indexed, add to its frontmatter:

```{.yaml filename="drafts/experimental-feature.qmd"}
---
title: "Experimental Feature"
robots: "noindex, nofollow"
---
```

## Disabling SEO Features

If you handle SEO through other means (for example, a hosting platform that generates sitemaps for
you), you can disable individual features or all of them at once.

To completely disable SEO generation:

```{.yaml filename="great-docs.yml"}
seo:
  enabled: false
```

Or disable specific features:

```{.yaml filename="great-docs.yml"}
seo:
  sitemap:
    enabled: false
  robots:
    enabled: false
  canonical:
    enabled: false
  structured_data:
    enabled: false
```

## Best Practices

The automatic features cover the technical foundations. These recommendations help you get the most
out of them.

### For Maximum SEO Effectiveness

1. set a base URL either through a GitHub repo or explicit configuration
2. write good descriptions: add `description:` to key pages' frontmatter
3. use descriptive titles that are clear (as concise page titles improve click-through rates)
4. add alt text to images: Great Docs audits this and will fix any missing alt text
5. run `great-docs seo` to audit before deployment and catch issues early

### For GitHub Pages

If you're deploying to GitHub Pages, SEO works out of the box:

1. your canonical base URL is auto-detected from the repository
2. the sitemap is automatically referenced in `robots.txt`
3. all pages get proper canonical links

### For Custom Domains

When using a custom domain, this configuration is useful:

```{.yaml filename="great-docs.yml"}
seo:
  canonical:
    base_url: https://docs.myproject.com/
```

And ensure your DNS is configured correctly (see
[Adding a Custom Domain](../recipes/add-custom-domain.qmd)).

## Next Steps

Good SEO makes your documentation discoverable. Great Docs handles the technical foundations
(sitemaps, canonical URLs, meta tags, structured data) automatically, so you can focus on writing
clear titles and descriptions that represent your content well.

- [Social Cards](social-cards.qmd) controls how links appear when shared on social platforms
- [Deployment](deployment.qmd) covers publishing to GitHub Pages with SEO settings applied
- [Linting](linting.qmd) catches documentation quality issues that can also affect search relevance
- [Configuration](configuration.qmd) covers all `great-docs.yml` options including SEO settings



## Quality & Maintenance

# Docs Linting

Documentation problems tend to be invisible until someone encounters them: a function with no
docstring, a cross-reference pointing to a symbol that was renamed, or a directive that's
misspelled. These issues don't produce build errors, so they can persist across many releases.

Great Docs includes a built-in linter that analyzes your package's public API for documentation
quality issues. It catches missing docstrings, broken cross-references, inconsistent formatting, and
malformed directives before your users ever see them.

## Basic Usage

Run the linter from your project directory:

```{.bash filename="Terminal"}
great-docs lint
```

This produces a report like:

```
════════════════════════════════════════════════════════════
📋 Documentation Lint Results
════════════════════════════════════════════════════════════

Package: my_package
Exports checked: 42

✅ All documentation checks passed!
```

When issues are found, they are grouped by check type with clear indicators:

```
────────────────────────────────────────────────────────────
  missing-docstring  [2 error(s), 3 warning(s)]
────────────────────────────────────────────────────────────
  ❌  calculate_total: Public export 'calculate_total'
                       has no docstring.
  ❌  DataProcessor: Public export 'DataProcessor' has
                     no docstring.
  ⚠️   Widget.render: Public method 'Widget.render'
                       has no docstring.
  ⚠️   Widget.update: Public method 'Widget.update'
                       has no docstring.
  ⚠️   Widget.__repr__: Public method 'Widget.__repr__'
                         has no docstring.

────────────────────────────────────────────────────────────
  style-mismatch  [1 warning(s)]
────────────────────────────────────────────────────────────
  ⚠️   parse_config: Docstring appears to use 'google'
                      style but project is configured
                      for 'numpy'.

────────────────────────────────────────────────────────────
❌ 2 error(s), 4 warning(s)
```

Errors represent problems that will produce gaps or broken content on the rendered site. Warnings
flag inconsistencies that are worth investigating but won't break anything.

## Checks Performed

The linter runs four categories of checks, each targeting a different class of documentation
problem. All four run by default, and each can be run individually using `--check` (described
below).

### Missing Docstrings

Finds public exports and class methods that lack docstrings.

| Finding | Severity | Description |
|---------|----------|-------------|
| `missing-docstring` | Error | A public export in `__all__` has no docstring |
| `missing-docstring` | Warning | A public method on a documented class has no docstring |

Private methods (names starting with `_`) and constructor dunders (`__init__`, `__new__`) are
skipped automatically. The linter only flags symbols that would appear (or be expected to appear) in
the rendered documentation.

### Broken Cross-References

Cross-references to undocumented symbols produce dead links on the rendered site. The linter
checks that each `%seealso` target names an object this project documents or a linked project
publishes. The linter checks only docstrings that render in the reference. A `%seealso` in a
hidden member, such as one from a class configured `members: false`, has no rendered page and
produces no finding.

| Finding | Severity | Description |
|---------|----------|-------------|
| `broken-xref` | Error | A reference names no object documented by this project or a linked source |
| `ambiguous-xref` | Error | A reference names a short form claimed by two documented objects |
| `unread-source` | Info | A linked source inventory could not be read, so `%seealso` was not checked |

For example, this would flag an error:

```python
def process(data):
    """
    Process the input data.

    %seealso validate_input, transform_data
    """
    ...
```

If `validate_input` is documented but `transform_data` is not, the linter reports
`transform_data` as a broken cross-reference. This is especially useful after renaming or removing
functions.

A reference can also be ambiguous. If both `StoreCache` and `NetCache` document a `flush`
method, neither claims the short name `flush`, so a reference to it renders unlinked:

```
'flush' is claimed by demo.NetCache.flush and demo.StoreCache.flush, so the reference stays
unlinked. Qualify it.
```

Writing `` [](`StoreCache.flush`) `` resolves it. The linter judges `%seealso` entries and inline
references identically because the build resolves both through one index. It scans docstrings and
documentation pages.

References to linked projects use the same index. `%seealso numpy.ndarray` passes whenever
the built page resolves it, by full name or source alias. Great Docs uses a fresh cached
inventory or downloads one when needed. If it cannot read a source, its names are unavailable,
so the linter reports `unread-source` and does not classify `%seealso` references as broken
for that run.

### Style Consistency

Detects docstrings that don't match your project's configured parser style. The `parser` setting in
`great-docs.yml` determines which style is expected:

```{.yaml filename="great-docs.yml"}
parser: numpy    # or "google" or "sphinx"
```

| Finding | Severity | Description |
|---------|----------|-------------|
| `style-mismatch` | Warning | Docstring uses a different style than configured |

The linter detects style by looking for characteristic patterns:

- **NumPy**: Section headers with dashed underlines (`Parameters\n----------`)
- **Google**: Section headers with colons (`Args:`, `Returns:`)
- **Sphinx**: Field markers (`:param x:`, `:returns:`)

Short docstrings without structured sections are not flagged, since they don't contain enough signal
to determine a style.

### Directive Consistency

Great Docs uses `%`-prefixed directives in docstrings for features like cross-references and
documentation exclusion. This check catches misspelled or unrecognized directives that would
otherwise be silently ignored.

| Finding | Severity | Description |
|---------|----------|-------------|
| `unknown-directive` | Warning | A `%`-prefixed directive is not recognized |

Great Docs recognizes these parser-independent directives:

- Cross-reference and exclusion: `%seealso` (see
  [Cross-Referencing](cross-referencing.qmd)) and `%nodoc` (see
  [Writing Docstrings](writing-docstrings.qmd#nodoc-exclude-an-item-from-documentation))
- Callouts: `%note`, `%warning`, `%caution`, `%danger`, `%important`, `%tip`, and `%hint`
- Version notices: `%versionadded`, `%versionchanged`, and `%deprecated`

Numbered `.. [1]` citation markers work with every parser. Use `parser: sphinx` for
reStructuredText directives and inline cross-reference roles such as
`` :py:exc:`ValueError` ``.

Any other `%`-prefixed token, such as `%internal`, is flagged as unknown. If you see a false
positive, check for typos in the directive name.

## Running Specific Checks

When diagnosing a particular class of issue, you can run a subset of checks instead of the full
suite. Use `--check` to select only the checks you need (this option can be repeated):

```{.bash filename="Terminal"}
# Only check for missing docstrings
great-docs lint --check docstrings

# Check cross-references and style together
great-docs lint --check cross-refs --check style

# Only check directive usage
great-docs lint --check directives
```

Available check names:

| Name | What it checks |
|------|----------------|
| `docstrings` | Missing docstrings on public exports and methods |
| `cross-refs` | Broken `%seealso` references and ambiguous interlinks |
| `style` | Docstring style consistency with configured parser |
| `directives` | Unknown or malformed `%` directives |

When no `--check` flags are given, all four categories run.

## JSON Output

For CI/CD integration or programmatic analysis, use `--json` to get machine-readable output:

```{.bash filename="Terminal"}
great-docs lint --json
```

This produces structured JSON:

```json
{
  "status": "fail",
  "package": "my_package",
  "exports_checked": 42,
  "summary": {
    "errors": 2,
    "warnings": 4,
    "info": 0
  },
  "issues": [
    {
      "check": "missing-docstring",
      "severity": "error",
      "symbol": "calculate_total",
      "message": "Public export 'calculate_total' has no docstring."
    },
    {
      "check": "style-mismatch",
      "severity": "warning",
      "symbol": "parse_config",
      "message": "Docstring appears to use 'google' style but project is configured for 'numpy'."
    }
  ]
}
```

The `status` field is one of:

| Status | Meaning |
|--------|---------|
| `pass` | No errors or warnings |
| `warn` | Warnings only (exit code 0) |
| `fail` | At least one error (exit code 1) |

You can filter the JSON output with `jq`:

```{.bash filename="Terminal"}
# Show only errors
great-docs lint --json | jq '.issues[] | select(.severity == "error")'

# Count issues by check type
great-docs lint --json | jq '.issues | group_by(.check) | map({check: .[0].check, count: length})'
```

The JSON format is stable across releases, so you can build tooling around it.

## Exit Codes

The linter uses exit codes to indicate whether action is needed:

| Code | Meaning |
|------|---------|
| `0` | No errors (warnings are allowed) |
| `1` | At least one error was found |

This means you can use `great-docs lint` directly in CI pipelines and it will fail the build only
when there are errors. Warnings appear in the output but do not block the pipeline.

## CI/CD Integration

Running the linter in CI ensures that documentation quality is enforced on every pull request, not
just when someone remembers to check.

### GitHub Actions

Add documentation linting to your CI workflow:

```{.yaml filename=".github/workflows/docs.yml"}
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          pip install -e .
          pip install great-docs

      - name: Lint documentation
        run: great-docs lint
```

### Pre-commit Hook

Add linting as a pre-commit hook:

```{.yaml filename=".pre-commit-config.yaml"}
repos:
  - repo: local
    hooks:
      - id: lint-docs
        name: Lint Documentation
        entry: great-docs lint
        language: system
        pass_filenames: false
        always_run: true
```

### Combining with Other Quality Checks

Run linting alongside other Great Docs quality tools in CI:

```{.yaml filename=".github/workflows/docs.yml"}
      - name: Lint documentation
        run: great-docs lint

      - name: Check links
        run: great-docs check-links

      - name: Proofread
        run: great-docs proofread

      - name: Audit SEO
        run: great-docs seo
```

Running all four together gives you a comprehensive pre-deployment quality gate.

## Next Steps

The linter catches structural problems early: missing docstrings, malformed directives, broken
cross-references, and style inconsistencies that would otherwise surface as confusing gaps in the
rendered site. Run it in CI to enforce documentation quality alongside code quality.

- [Link Checker](link-checker.qmd) validates that all links in the built site resolve correctly
- [Proofreading](proofreading.qmd) checks spelling, grammar, and style in your prose
- [Writing Docstrings](writing-docstrings.qmd) covers the docstring format and directives that the
linter validates
- [SEO Optimization](seo.qmd) audits generated metadata that complements documentation quality



## Site Content

# Videos

Videos can make tutorials, demos, and explainers far more effective than screenshots alone. Great
Docs supports YouTube, Vimeo, and local video files with responsive layouts, lazy loading, and
accessibility features built in.

## YouTube

Use the following syntax to embed a YouTube video. You can use the regular watch URL, the short URL,
or the embed URL (all three work):

```{shortcodes="false"}
{{< video https://www.youtube.com/watch?v=wo9vZccmqwc >}}

{{< video https://youtu.be/wo9vZccmqwc >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}
```

All three produce the same result. The video is responsive by default and it scales to fill the
available width while maintaining a 16:9 aspect ratio.

Here's a live example:

{{< video https://www.youtube.com/watch?v=d8-Jyh-NaMw >}}

::: {.callout-tip}
## YouTube Controls

YouTube embeds use the standard YouTube player, giving visitors full access to native controls
including ad skipping, captions, playback speed, and quality settings.
:::

### Start Time

To start playback at a specific point, use the `start` option (in seconds):

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc start="116" >}}
```

### Title and Accessibility

Add a `title` for the iframe and an `aria-label` for screen readers:

```{shortcodes="false"}
{{< video https://www.youtube.com/embed/wo9vZccmqwc
    title="What is the CERN?"
    aria-label="Video tour of CERN particle physics laboratory"
>}}
```

## Vimeo

Vimeo videos work the same way:

```{shortcodes="false"}
{{< video https://vimeo.com/548291297 >}}
```

Vimeo embeds are lazy-loaded automatically: the iframe content is deferred until the video scrolls
near the viewport.

## Local Video Files

To embed a video file stored alongside your documentation (e.g., a short screen recording), place
the file in your project and reference it directly:

```{shortcodes="false"}
{{< video demo.mp4 >}}
```

Local videos are rendered as HTML5 `<video>` elements. To host them alongside your `.qmd` files,
place them in the `assets/` directory:

```
user_guide/
├── 05-walkthrough.qmd
└── assets/
    └── demo.mp4
```

Then reference from the `.qmd` file:

```{shortcodes="false"}
{{< video assets/demo.mp4 >}}
```

::: {.callout-note}
Keep video files small. Git repositories aren't ideal for large binary files. For longer recordings,
consider uploading to YouTube or Vimeo and embedding from there.
:::

## Aspect Ratio

The default aspect ratio is 16:9. You can change it to one of the standard Bootstrap ratios:

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc aspect-ratio="4x3" >}}
```

Available ratios: `1x1`, `4x3`, `16x9` (default), and `21x9`.

## Fixed Dimensions

To disable responsive sizing and set explicit pixel dimensions:

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc width="400" height="225" >}}
```

## Cross-Referencing Videos

To create a numbered, cross-referenceable video (like a figure), wrap it in a fenced div:

```{shortcodes="false"}
::: {#fig-demo}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

A short tour of the CERN facility.

:::

See @fig-demo for the full walkthrough.
```

This assigns the video a figure number and caption, and `@fig-demo` creates a clickable
cross-reference elsewhere on the page.

## Loom

Loom videos aren't recognized by the video syntax directly. Instead, use the Loom embed URL in a raw
HTML `<iframe>`:

```html
<div class="quarto-video ratio ratio-16x9">
<iframe
  src="https://www.loom.com/embed/YOUR_VIDEO_ID"
  frameborder="0"
  allowfullscreen>
</iframe>
</div>
```

Replace `YOUR_VIDEO_ID` with the ID from your Loom share link (e.g., if the share link is
`https://www.loom.com/share/abc123`, the ID is `abc123`). The `quarto-video ratio ratio-16x9`
classes give it the same responsive container as other videos, and Great Docs will lazy-load the
iframe automatically.

## Tips

- **Ads**: YouTube may show ads on monetized videos, even in embeds. To guarantee an ad-free
experience, upload to a channel you control with monetization disabled.
- **Privacy**: Consider using `youtube-nocookie.com` embed URLs (e.g.,
`https://www.youtube-nocookie.com/embed/VIDEO_ID`) to reduce tracking.
- **Multiple videos**: The thumbnail placeholder optimization means pages with many YouTube embeds
still load quickly (only the thumbnails are fetched initially).

## Next Steps

Embedded videos bring tutorials, demos, and walkthroughs to life without leaving the documentation
site. Great Docs lazy-loads all video embeds for fast page loads, regardless of how many videos
appear on a page.

- [Diagrams](diagrams.qmd) covers Mermaid diagrams for visualizing architecture and workflows
- [Authoring QMD Files](authoring-qmd-files.qmd) covers other rich content like callouts, tabsets,
and code blocks
- [Theming & Appearance](theming.qmd) explains how video containers adapt to your site's styling



## Config & Theming

# Internationalization

If your project has users around the world, presenting documentation in their language makes a real
difference. Even when the actual content is in English, translating navigation labels, button text,
and timestamps removes friction and signals that the project cares about accessibility.

Great Docs can display all of its UI text in multiple languages. When you set a language in
`great-docs.yml`, every button label, tooltip, relative timestamp, navbar link, and accessibility
attribute across the site is automatically translated.

## Setting the Language

Add the `language` key under `site` in your configuration file. The value is a
[BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language code:

```{.yaml filename="great-docs.yml"}
site:
  language: fr
```

If you don't set a language, Great Docs defaults to English (`en`). Only a single language can be
active at a time.

## Supported Languages

Great Docs ships with translations for 23 languages. If yours is in the list, all you need is the
`language` key in `great-docs.yml`:

| Code | Language |
|------|----------|
| `en` | English (default) |
| `fr` | French |
| `de` | German |
| `es` | Spanish |
| `pt` | Portuguese |
| `it` | Italian |
| `nl` | Dutch |
| `sv` | Swedish |
| `da` | Danish |
| `nb` | Norwegian Bokmål |
| `is` | Icelandic |
| `fi` | Finnish |
| `ja` | Japanese |
| `ko` | Korean |
| `zh-Hans` | Chinese (Simplified) |
| `zh-Hant` | Chinese (Traditional) |
| `ru` | Russian |
| `pl` | Polish |
| `cs` | Czech |
| `ro` | Romanian |
| `tr` | Turkish |
| `el` | Greek |
| `hi` | Hindi |

If your language isn't listed here and you'd like to contribute a translation, see the
[How It Works](#how-it-works) section below for details on the translation pipeline.

## What Gets Translated

Setting the language affects every piece of UI text that Great Docs generates. Here's a summary of
what changes:

### Navbar Labels

The top-level navigation links are translated automatically. For example, with `language: de`:

- **User Guide** becomes **Benutzerhandbuch**
- **Recipes** becomes **Rezepte**
- **Reference** becomes **Referenz**
- **Changelog** becomes **Änderungsprotokoll**

### Widget Text

All interactive widgets use the configured language:

- **Back-to-top button**: tooltip text
- **Copy code button**: "Copy to clipboard" / "Copied!" labels
- **Copy page menu**: all menu items and status messages
- **Dark mode toggle**: "Switch to dark mode" / "Switch to light mode" tooltips
- **Sidebar filter**: placeholder text and result counts
- **Reference switcher**: "API Reference" / "CLI Reference" labels
- **GitHub widget**: "Stars", "Forks", "Issues", "Pull Requests" labels
- **Announcement banner**: dismiss button accessibility label
- **Responsive tables**: scrollable table indicator
- **Video embed**: play button and video labels

### Page Metadata

The page metadata widget displays relative timestamps like "3 days ago" or "2 months ago". These
time expressions are fully translated and support correct singular/plural forms for each language.
The tooltip date format also adapts to match the configured locale.

### Table of Contents

The "On this page" heading above the right-hand table of contents is translated to match your
configured language.

All of these translations are applied automatically. You don't need to provide any translation files
or configure anything beyond the `language` key.

## Right-to-Left (RTL) Support

::: {.callout-note}
RTL layout support for languages like Arabic and Hebrew is under active development and not yet
available. The underlying translations exist, but the visual layout needs further work before these
languages can be officially supported.
:::

## Placeholders and Plurals

Translation strings aren't always simple substitutions. Some include dynamic values and need to
handle singular and plural forms correctly. Great Docs handles both cases automatically at runtime:

- **Placeholders** use `{name}` syntax: for example, `"Refreshed {time}"` becomes
`"Actualisé {time}"` in French, where `{time}` is filled in with the relative timestamp.
- **Plurals** use a `singular|plural` pipe format: for example, `"{n} day ago|{n} days ago"` becomes
`"il y a {n} jour|il y a {n} jours"` in French, with the correct form selected based on the count.

## How It Works

Understanding the translation pipeline can be helpful if you're contributing translations or
debugging language issues:

1. you set `language` in `great-docs.yml`
2. during the build, Great Docs looks up all translation strings for that language from its internal
dictionary
3. the full translation bundle is written into `_gd_options.json`
4. after Quarto renders each page, the post-render script injects a `<meta name="gd-i18n">` tag into
the HTML `<head>` containing the JSON-encoded translations
5. each JavaScript widget reads from this meta tag using a shared `_gdT(key, fallback)` helper
function

If a translation is missing for a particular key, the English fallback is used automatically. This
means partial translations are safe to ship: untranslated strings appear in English rather than as
blank text or error messages.

## Next Steps

Internationalization lets you serve documentation in your users' language with a single config
setting. Great Docs translates all UI chrome (navigation, buttons, tooltips, timestamps) while you
focus on translating the content that matters most.

- [Configuration](configuration.qmd) covers the `language` setting and other `great-docs.yml`
options
- [Theming & Appearance](theming.qmd) explains how translated labels integrate with your site's
visual design
- [SEO Optimization](seo.qmd) covers how language settings affect search engine indexing
- [Social Cards](social-cards.qmd) explains Open Graph metadata, which can include language
attributes



## Build & Deploy

# Social Cards

When someone shares a link to your documentation on LinkedIn, Discord, Slack, Bluesky, Mastodon, X (Twitter), or other platforms, social card meta tags control the preview that appears. Great Docs automatically generates Open Graph and Twitter Card meta tags for every page so your links look polished rather than bare URLs.

## What's Generated

For every page in your site, Great Docs injects two sets of `<meta>` tags into `<head>`:

**Open Graph** (used by LinkedIn, Discord, Slack, Bluesky, Mastodon, Facebook, and most other platforms):

```html
<meta property="og:type" content="website">
<meta property="og:title" content="Configuration | My Package">
<meta property="og:description" content="How to configure My Package...">
<meta property="og:url" content="https://user.github.io/pkg/user-guide/config.html">
<meta property="og:site_name" content="My Package">
<meta property="og:image" content="https://user.github.io/pkg/social-card.png">
```

**Twitter/X Card** (used by X for its own preview cards):

```html
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Configuration | My Package">
<meta name="twitter:description" content="How to configure My Package...">
<meta name="twitter:image" content="https://user.github.io/pkg/social-card.png">
<meta name="twitter:site" content="@myhandle">
```

These tags are generated per-page with the correct title, description, and URL for each page.

## Zero-Config Defaults

Social card tags are enabled by default. With no configuration at all, Great Docs will:

- use the page `<title>` for `og:title` and `twitter:title`
- extract a description from the page's meta description or first paragraph
- fall back to the package description from `pyproject.toml` when no page-level description is available
- build the `og:url` from your canonical base URL (auto-detected from GitHub Pages)
- set `twitter:card` to `"summary"` (no image) or `"summary_large_image"` (when an image is configured)

No changes to `great-docs.yml` are needed for basic social card previews.

## Adding a Social Card Image

An image makes a dramatic difference in how your links appear. Without one, most platforms show a plain text card. With a well-designed image, your link gets a large visual preview that stands out in feeds and chat messages.

### Recommended Image Specifications

| Property | Recommendation |
|----------|---------------|
| **Dimensions** | 1200 × 630 pixels (1.91:1 aspect ratio) |
| **Minimum size** | 600 × 315 pixels |
| **Maximum file size** | Under 1 MB (ideally under 300 KB) |
| **Format** | PNG for graphics/text, JPEG for photos |
| **Safe area** | Keep important content within the center 1080 × 565 pixels |

The 1200 × 630 size is the universal sweet spot: it works well as a `summary_large_image` on X, fills the preview area on LinkedIn and Discord, and renders crisply on high-DPI screens.

### Configuring the Default Image

Place your image in the project's `assets/` directory. This is the same directory Great Docs already copies into the build for logos, favicons, and other static files:

```
my-package/
├── assets/
│   ├── social-card.png   ← your social card image
│   ├── logo.svg
│   └── favicon.svg
├── my_package/
├── great-docs.yml
└── pyproject.toml
```

Then reference it in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
social_cards:
  image: assets/social-card.png
```

This single image is used as the default `og:image` and `twitter:image` for **every page** on your site. It's copied to the site root during build and referenced with an absolute URL.

### What to Put in the Image

A good social card image typically includes:

- your package logo or wordmark
- the package name in large, readable text
- a short tagline or description
- a subtle background color or pattern that matches your brand

Avoid putting page-specific information in the image since it's shared across all pages. Focus on making the package itself recognizable.

### Design Tips

- **High contrast text**: white or light text on a dark background (or vice versa) ensures readability at small sizes
- **Large text**: the image is often shown at 300-400 pixels wide in feeds; small text becomes unreadable
- **Simple composition**: one logo, one title, one line of description is enough
- **Test at small sizes**: preview your image at 300 × 157 pixels to see how it looks in a typical feed

## Configuration Reference

The full `social_cards` configuration with all options:

```{.yaml filename="great-docs.yml"}
social_cards:
  enabled: true                          # Master switch (default: true)
  image: assets/social-card.png          # Default og:image path or URL
  twitter_site: "@myhandle"              # Twitter/X site @handle
  twitter_card: summary_large_image      # Card type override
```

### Options

You can enable or disable social card meta tag generation. The default is `true`.

```{.yaml filename="great-docs.yml"}
# Disable social cards entirely
social_cards:
  enabled: false
```

You can also use the shorthand form:

```{.yaml filename="great-docs.yml"}
social_cards: false
```

The `image` key needs a path to a default image file (relative to the project root) or an absolute URL. This image is used as `og:image` and `twitter:image` for all pages.

```{.yaml filename="great-docs.yml"}
# Local file (copied to site root during build)
social_cards:
  image: assets/social-card.png

# External URL (used as-is)
social_cards:
  image: https://cdn.example.com/my-package-card.png
```

When an image is provided, the `twitter:card` type automatically switches from `"summary"` to `"summary_large_image"` for a bigger preview on X.

The `twitter_site` key refers to the Twitter/X `@handle` for the site or organization. This appears in the card footer on X.

```{.yaml filename="great-docs.yml"}
social_cards:
  twitter_site: "@posaboron"
```

The `@` prefix is optional (Great Docs will add it if missing).

Regarding `twitter_card`, this overrides the Twitter card type. By default, Great Docs chooses automatically:

- `"summary"` when no image is configured
- `"summary_large_image"` when an image is configured

Set this to force a specific type regardless of image presence:

```{.yaml filename="great-docs.yml"}
social_cards:
  image: assets/social-card.png
  twitter_card: summary  # Use small card even though an image exists
```

## How Descriptions Are Extracted

Social card descriptions are extracted automatically with this priority:

1. **Existing meta description**: if the page already has a `<meta name="description">` tag (from SEO processing or manual frontmatter), that text is reused
2. **First paragraph**: the first `<p>` in the page's `<main>` content with at least 30 characters of meaningful text
3. **Default description**: the `seo.default_description` value from `great-docs.yml`, or the package description from `pyproject.toml`

For the best previews, add a `description` to important pages' frontmatter:

```{.yaml filename="user_guide/03-configuration.qmd"}
---
title: "Configuration"
description: "Complete guide to configuring Great Docs, including theming, navbar styles, and SEO settings."
---
```

## Testing Your Social Cards

After building your site, you can verify the meta tags are present by inspecting any HTML file:

```{.bash filename="Terminal"}
grep -E 'og:|twitter:' great-docs/_site/index.html
```

To see how your links will actually appear on each platform, use these free preview tools:

- **LinkedIn**: [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/)
- **X (Twitter)**: [Twitter Card Validator](https://cards-dev.twitter.com/validator)
- **Facebook**: [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
- **General**: [Open Graph Debugger](https://opengraph.dev) (this shows previews for multiple platforms at once)

These tools fetch your live URL, so you'll need to deploy your site first (or use a tunnel for local testing).

## Relationship to SEO

Social cards work alongside the [SEO features](seo.qmd) but serve a different purpose:

- **SEO** optimizes how your pages appear in search engine results (Google, Bing)
- **Social cards** control how your links appear when shared on social platforms

Both features can be enabled independently. Social cards use some of the same underlying data (canonical URLs, meta descriptions) but generate separate meta tags (`og:*` and `twitter:*`).

## Disabling Social Cards

To turn off social card meta tags entirely you can use:

```{.yaml filename="great-docs.yml"}
social_cards: false
```

Or equivalently:

```{.yaml filename="great-docs.yml"}
social_cards:
  enabled: false
```

With either of these settings, the Open Graph and Twitter Card meta tags will not be injected into any pages.

## Next Steps

Social cards control how your documentation looks when shared on Twitter, Slack, Discord, and other platforms. Great Docs generates the right meta tags automatically from your page titles and descriptions.

- [SEO Optimization](seo.qmd) covers search engine visibility, sitemaps, and canonical URLs
- [Configuration](configuration.qmd) covers all `great-docs.yml` options including social card settings
- [Deployment](deployment.qmd) explains publishing to GitHub Pages where social cards take effect



## Site Content

# Custom Static Pages

Great Docs can auto-discover hand-written HTML pages and add them to your site with either minimal transformation or no transformation at all. This is useful for product landing pages, interactive demos, playgrounds, embedded widgets, and other content that does not fit naturally into a standard `.qmd` workflow.

## Configuring Source Directories

Custom static pages are configured with `custom_pages` in `great-docs.yml`.

### Zero-config fallback

If you do not set `custom_pages`, Great Docs falls back to a conventional `custom/` directory:

```{.default filename="project layout"}
my-package/
├── custom/
│   ├── py.html
│   ├── playground.html
│   └── assets/
│       └── chart.js
├── great-docs.yml
└── ...
```

That is only the default on-ramp. You can override it.

### One custom page directory

```{.yaml filename="great-docs.yml"}
custom_pages: marketing
```

This reads pages from `marketing/` and publishes them under `marketing/` in the built site.

### One directory with a custom URL prefix

```{.yaml filename="great-docs.yml"}
custom_pages:
  dir: marketing
  output: py
```

This reads files from `marketing/` but publishes them under `py/`, which is useful when your source directory name and URL shape should differ.

### Multiple custom page directories

```{.yaml filename="great-docs.yml"}
custom_pages:
  - dir: marketing
    output: py
  - dir: playgrounds
    output: demos
```

This lets a larger site keep different HTML surfaces in separate source trees while still controlling their deployed paths.

### Disable custom pages entirely

```{.yaml filename="great-docs.yml"}
custom_pages: false
```

This disables the fallback `custom/` directory too.

## Two Layout Modes

Custom HTML pages support two layout modes through YAML frontmatter.

### `layout: passthrough`

Use passthrough mode when you want to keep your HTML body mostly intact but still render it inside the normal Great Docs shell.

```{.html filename="marketing/index.html"}
---
title: Comet Apps for Python
layout: passthrough
navbar: true
---
<section class="hero-banner">
  <h1>Reactive Python apps</h1>
  <p>Build interactive apps with a custom landing page.</p>
</section>
```

In passthrough mode, Great Docs will:

- parse the frontmatter
- generate an intermediate `.qmd` file in the build directory
- keep your HTML body as the page content
- render the page with the normal navbar, footer, search, theme, and scripts

This is the right choice for pages like:

- product landing pages
- marketing-style homepages for a sub-area of your docs
- richly designed pages that should still feel like part of the main documentation site

### `layout: raw`

Use raw mode when the HTML should be served unchanged.

```{.html filename="playgrounds/playground.html"}
---
layout: raw
navbar:
  text: Playground
  after: User Guide
---
<!DOCTYPE html>
<html>
  <head>
    <title>Playground</title>
  </head>
  <body>
    <main id="playground-root">Raw playground content</main>
  </body>
</html>
```

In raw mode, Great Docs will:

- strip the frontmatter
- copy the HTML file through to the final site output unchanged
- exclude that file from Quarto rendering

This is the right choice for pages like:

- standalone widget hosts
- JavaScript demos with their own document structure
- third-party embeds that depend on exact HTML markup

## Navbar Integration

Custom pages do not have to appear in the navbar, but they can opt in using frontmatter.

### Use the page title

```{.yaml filename="frontmatter"}
navbar: true
```

This adds the page to the navbar using its `title`.

### Use custom text

```{.yaml filename="frontmatter"}
navbar: Widget Lab
```

This adds the page to the navbar using the provided text.

### Control placement

```{.yaml filename="frontmatter"}
navbar:
  text: Playground
  after: User Guide
```

This uses explicit link text and inserts the link after an existing navbar item.

If no placement is specified, the link is inserted before `Reference`, which matches the current behavior for custom sections.

## Assets and Relative Paths

Files under each configured custom-page directory that are not HTML are copied as project resources.

For example:

```{.default filename="playgrounds/"}
playgrounds/
├── widget.html
└── assets/
    ├── chart.js
    └── styles.css
```

From `playgrounds/widget.html`, you can reference those files with relative paths:

```{.html filename="playgrounds/widget.html"}
<link rel="stylesheet" href="assets/styles.css">
<script src="assets/chart.js"></script>
```

If `playgrounds/` is configured with `output: demos`, those files are copied into the built site under `demos/assets/`.

## Coexisting with User Guides and Sections

Custom static pages are meant for a different job than User Guide pages or configured sections.

Use **User Guide pages** when:

- the content is standard documentation prose
- you want Quarto-native Markdown authoring
- you want the usual sectioned sidebar behavior

Use **Custom Sections** when:

- you want a group of related pages with shared navigation
- you want a navbar item plus a section sidebar
- the content is still mostly `.qmd` or `.md`

Use **Custom Static Pages** when:

- the page is already HTML
- the layout is highly bespoke
- the page should behave like a landing page or demo surface
- you need raw HTML delivery without Quarto transformation

It is normal for one site to use all three together.

## What Happens During Build

When `great-docs build` runs, Great Docs scans each configured custom-page directory after processing configured sections and before copying top-level `assets/`.

The custom page pipeline:

1. walks each configured custom-page directory recursively
2. copies non-HTML files as resources
3. reads frontmatter from `.html` and `.htm` files
4. converts passthrough pages into generated `.qmd` files
5. copies raw pages through unchanged and excludes them from Quarto rendering
6. injects any opted-in custom pages into the navbar

## Example: Shiny-Style Landing Page

If you want a page similar in spirit to `https://shiny.posit.co/py/`, passthrough mode is usually the better fit.

```{.html filename="marketing/index.html"}
---
title: Comet Apps for Python
layout: passthrough
navbar: true
---
<section class="hero-banner">
  <h1>Reactive data apps in pure Python</h1>
  <p>Elegant, efficient, and ready for production.</p>
</section>

<section class="feature-grid">
  <article>
    <h2>Reactive</h2>
    <p>Automatic execution flow without callback boilerplate.</p>
  </article>
  <article>
    <h2>Efficient</h2>
    <p>Render outputs only when upstream inputs change.</p>
  </article>
  <article>
    <h2>Robust</h2>
    <p>Build on top of the modern Python web stack.</p>
  </article>
</section>
```

That gives you a custom layout while still preserving the site shell around it.

## Current Limitations

This feature is intentionally narrow in its first version.

- custom pages are HTML-based; Great Docs is not currently transforming arbitrary non-HTML page types here
- there is no dedicated custom-page sidebar model yet
- navbar integration is per-page frontmatter, not a separate config block

These constraints keep the feature predictable while it matures.

## Next Steps

Custom pages give you an escape hatch for content that doesn't fit the standard page model. Use them sparingly for landing pages, dashboards, or anything that needs full control over HTML and layout.

- [Custom Sections](custom-sections.qmd) covers multi-page section navigation
- [Configuration](configuration.qmd) covers the broader `great-docs.yml` model
- [Building & Previewing](building.qmd) explains where custom pages fit in the build pipeline


# Page Tags

As a documentation site grows, the sidebar and search bar are not always enough to help readers find
what they need. Tags offer a second axis of navigation, organized by topic rather than page order. A
reader looking for everything related to "Testing" can find it in one place, even if those pages are
spread across the User Guide, Recipes, and custom sections.

Great Docs lets you categorize pages with tags for improved discoverability. Add tags to any user
guide, recipe, or custom section page via frontmatter, and Great Docs will generate a tags index
page, render tag pills above page titles, and support hierarchical tag organization.

<style>
.gd-demo-tag-pill, .gd-demo-tag-index, .gd-demo-tag-page-mock {
  font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
}
.gd-demo-tag-pill {
  display: inline-flex;
  align-items: center;
  gap: 0.2rem;
  padding: 0.15rem 0.55rem;
  font-size: 0.75rem;
  font-weight: 500;
  line-height: 1.4;
  color: #6b7280;
  background-color: #f3f4f6;
  border: 1px solid #d1d5db;
  border-radius: 1rem;
  text-decoration: none;
  white-space: nowrap;
}
.gd-demo-tag-pills {
  display: flex;
  flex-wrap: wrap;
  gap: 0.4rem;
  margin-top: 0.35rem;
  margin-bottom: 0.8rem;
}
.gd-demo-tag-page-mock {
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 1rem 1.25rem;
  margin: 1rem 0;
  background: transparent;
}
body.quarto-dark .gd-demo-tag-page-mock { border-color: #374151; }
body.quarto-dark .gd-demo-tag-pill {
  color: #9ca3af;
  background-color: rgba(107,114,128,0.15);
  border-color: rgba(107,114,128,0.3);
}
.gd-demo-tag-index {
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 1rem 1.25rem;
  margin: 1rem 0;
  background: transparent;
}
body.quarto-dark .gd-demo-tag-index { border-color: #374151; }
.gd-demo-section-badge {
  display: inline-block;
  font-size: 0.7rem;
  font-weight: 500;
  color: #6b7280;
  background-color: #f3f4f6;
  padding: 0.05rem 0.4rem;
  border-radius: 0.25rem;
  margin-left: 0.4rem;
  vertical-align: middle;
}
body.quarto-dark .gd-demo-section-badge { color: #9ca3af; background-color: #1f2937; }
.gd-demo-tag-seg {
  display: inline-flex;
  align-items: center;
  padding: 0;
  border-radius: 1rem;
  overflow: hidden;
  border: 1px solid #d1d5db;
  font-size: 0.75rem;
  font-weight: 500;
  line-height: 1.4;
  color: #6b7280;
  white-space: nowrap;
}
body.quarto-dark .gd-demo-tag-seg { color: #9ca3af; border-color: rgba(107,114,128,0.3); }
.gd-demo-tag-seg-parent {
  display: inline-flex;
  align-items: center;
  padding: 0.15rem 0.55rem;
  background-color: #f3f4f6;
}
body.quarto-dark .gd-demo-tag-seg-parent { background-color: rgba(107,114,128,0.15); }
.gd-demo-tag-seg-child {
  display: inline-flex;
  align-items: center;
  padding: 0.15rem 0.55rem;
  background-color: #f9fafb;
}
body.quarto-dark .gd-demo-tag-seg-child { background-color: rgba(107,114,128,0.08); }
.gd-demo-tag-seg-sep {
  display: inline-block;
  width: 1px;
  align-self: stretch;
  background-color: #9ca3af;
}
body.quarto-dark .gd-demo-tag-seg-sep { background-color: rgba(107,114,128,0.4); }
</style>

Tags are disabled by default. To enable them, add a `tags` section to `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
```

Or use the shorthand:

```{.yaml filename="great-docs.yml"}
tags: true
```

## Adding Tags to Pages

Add tags to any `.qmd` page using the `tags` key in YAML frontmatter:

```{.yaml filename="user_guide/03-configuration.qmd"}
---
title: "Configuration"
tags: [Python, Configuration, Getting Started]
---
```

Tags can be any string. They are case-sensitive, so `Python` and `python` are treated as different
tags.

## Tags Index Page

When tags are enabled, Great Docs automatically generates a `tags/index.qmd` page that lists every
tag and the pages associated with it. A "Tags" link is added to the site's top navigation bar
(positioned before "Reference").

Each tag becomes a heading on the index page, with links to all pages that use that tag. Section
badges (e.g., "User Guide", "Recipes") appear next to each page link so readers can see where the
page lives:

<div class="gd-demo-tag-index">
<div style="font-size:1.1rem; font-weight:600; margin-bottom:0.5rem;"><span class="gd-demo-tag-pill">Configuration</span></div>
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Configuration</a> <span class="gd-demo-section-badge">User Guide</span></div>
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Advanced Configuration</a> <span class="gd-demo-section-badge">Recipes</span></div>
<div style="font-size:1.1rem; font-weight:600; margin-top:1rem; margin-bottom:0.5rem;"><span class="gd-demo-tag-pill">Getting Started</span></div>
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Installation</a> <span class="gd-demo-section-badge">User Guide</span></div>
<div style="padding-left:1.25rem; padding:0.15rem 0 0.15rem 1.25rem;"><a style="color:inherit; text-decoration:underline;">Quickstart</a> <span class="gd-demo-section-badge">User Guide</span></div>
</div>

### Disabling the Index Page

If you want tag pills on pages but don't want a dedicated index page:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  index_page: false
```

## Tag Pills on Pages

By default, tagged pages display small pill-shaped links below the page title. Each pill links to
the corresponding tag's section on the tags index page, helping readers discover related content:

<div class="gd-demo-tag-page-mock">
<div style="font-size:1.5rem; font-weight:700;">Configuration</div>
<div class="gd-demo-tag-pills"><span class="gd-demo-tag-pill">Python</span> <span class="gd-demo-tag-pill">Configuration</span> <span class="gd-demo-tag-pill">Getting Started</span></div>
</div>

To disable the pills while keeping the tags index page:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  show_on_pages: false
```

## Tag Location

By default, tag pills appear at the **top** of the page, just below the title (and subtitle, if
present). You can move them to the **bottom** of the page instead, where they appear after the page
metadata block (dates and author info) or under a horizontal rule if no metadata is present.

Set the default location globally in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  location: bottom
```

Valid values are `top` (default) and `bottom`.

### Per-Page Overrides

Individual pages can override the global setting using `tag-location` in their YAML frontmatter:

```{.yaml filename="user_guide/05-tips.qmd"}
---
title: "Tips and Tricks"
tags: [Python, Setup]
tag-location: top
---
```

This is useful when most pages use bottom placement but a few key pages benefit from prominent top
placement (or vice versa).

::: {.callout-tip}
When tags are placed at the bottom, they are rendered *after* the page metadata
(creation/modification dates and author info). If page metadata is not enabled, tags appear at the
end of the main content under a horizontal rule.
:::

## Hierarchical Tags

Tags support a hierarchy using the `/` separator. For example, `Python/Testing` creates a parent
"Python" group with a "Testing" child. On the tags index page, hierarchical tags are rendered with
nested headings:

```yaml
---
title: "Unit Testing Guide"
tags: [Python/Testing, Python/pytest, Best Practices]
---
```

This produces an index page structure like:

```
## Best Practices
  - Unit Testing Guide

## Python
  ### Testing
    - Unit Testing Guide
  ### pytest
    - Unit Testing Guide
```

On the page itself, hierarchical tag pills display as segmented pills with the parent and leaf
separated by a vertical divider. The full path is shown as a tooltip on hover:

<div class="gd-demo-tag-pills" style="margin:1rem 0;">
<span class="gd-demo-tag-seg"><span class="gd-demo-tag-seg-parent">Python</span><span class="gd-demo-tag-seg-sep">&nbsp;</span><span class="gd-demo-tag-seg-child">Testing</span></span>
<span class="gd-demo-tag-seg"><span class="gd-demo-tag-seg-parent">Python</span><span class="gd-demo-tag-seg-sep">&nbsp;</span><span class="gd-demo-tag-seg-child">pytest</span></span>
<span class="gd-demo-tag-pill">Best Practices</span>
</div>

### Literal Slashes in Tag Names

If a tag name contains a literal `/` that should **not** be treated as a hierarchy separator, escape
it with a backslash: `\/`. For example, `AI\/LLM` displays as "AI/LLM" without creating a hierarchy.

```yaml
---
title: "Working with LLMs"
tags: [AI\/LLM, Getting Started]
---
```

::: {.callout-note}
In YAML, leave the tag unquoted (e.g., `AI\/LLM`) so the backslash is preserved. Double-quoted YAML
strings will consume the backslash as an escape character.
:::

To disable hierarchical tag support entirely and treat all `/` characters as literal:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  hierarchical: false
```

## Shadow Tags

Not all tags are meant for readers. Shadow tags let you use the tagging system for internal
organization without exposing those labels publicly. Pages with shadow tags are still indexed
internally, but the tags themselves are not rendered as pills on pages or shown on the tags index
page.

This is useful for editorial workflows. For example, you can tag pages as `needs-review` or `draft`
without exposing those labels to readers.

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  shadow:
    - needs-review
    - draft
    - internal
```

A page can have both visible and shadow tags:

```yaml
---
title: "Advanced Configuration"
tags: [Configuration, API, needs-review]
---
```

In this example, "Configuration" and "API" appear as pills and on the index page, while
"needs-review" is silently ignored in the public output.

## Tag Icons

You can associate tags with icons from the [Lucide](https://lucide.dev/icons/) icon set (the same
icon set used by `nav_icons`). Icons appear inside the tag pill and next to the tag heading on the
index page.

```{.yaml filename="great-docs.yml"}
tags:
  enabled: true
  icons:
    Python: code
    Tutorial: book-open
    API: file-code
    Testing: flask-conical
```

The icon names are Lucide icon names (lowercase, hyphenated). Browse the full catalogue at
[lucide.dev/icons](https://lucide.dev/icons/).

## Full Configuration Reference

Here is the complete `tags` configuration with all options and their defaults:

```{.yaml filename="great-docs.yml"}
tags:
  enabled: false          # Master switch (default: false)
  index_page: true        # Generate a tags index page (default: true)
  show_on_pages: true     # Show tag pills above page titles (default: true)
  location: top           # Pill placement: "top" or "bottom" (default: "top")
  hierarchical: true      # Support "/" as tag hierarchy separator (default: true)
  icons: {}               # Tag → icon name mapping (default: empty)
  shadow: []              # Tags hidden from public view (default: empty)
  scoped: false           # Scoped tag listings per section (default: false)
```

Individual pages can override `location` via `tag-location` in their YAML frontmatter.

## Which Pages Are Scanned?

Great Docs scans for tags in `.qmd` files found in:

- **User guide** pages (`user-guide/`)
- **Recipes** pages (`recipes/`)
- **Custom sections** (any section defined in `sections:` config)

Index pages (`index.qmd`) in these directories are skipped. API reference pages and the changelog
are not scanned for tags.

## Tips

A few guidelines help keep your tag system useful as your documentation grows.

- **Start simple**: begin with a flat list of 5-10 tags and add hierarchy later as your
documentation grows.
- **Be consistent**: establish a tag naming convention early (e.g., always use title case).
- **Use shadow tags for workflow**: tags like `needs-update` or `v2-migration` help you track
editorial tasks without cluttering the reader experience.
- **Combine with search**: tags improve discoverability today, and will integrate with enhanced
search in a future release.

## Next Steps

Tags give readers a second way to navigate your documentation, organized by topic rather than page
order. Start with a small set of well-chosen tags and expand as your content grows.

- [Page Status Badges](page-status-badges.qmd) adds lifecycle indicators (new, updated, deprecated)
to pages
- [Custom Sections](custom-sections.qmd) covers organizing pages into named groups with sidebar
navigation
- [Internationalization](internationalization.qmd) covers language support for tag-related UI
elements
- [Configuration](configuration.qmd) covers all tag settings in `great-docs.yml`


# Page Status Badges

Documentation pages have a lifecycle. Some pages describe brand-new features, others cover APIs that
are experimental and subject to change, and some document capabilities that are being phased out.
Communicating this status helps readers set expectations before they invest time in a page.

Great Docs lets you mark pages with a lifecycle status such as "New", "Beta", or "Deprecated".
Status badges appear as colored indicators in two places:

1. **Below the page title**: a full badge with icon, label, and description
2. **In sidebar navigation**: a compact icon next to the link, with a tooltip on hover

Status badges are disabled by default. To enable them, add a `page_status` section to
`great-docs.yml`:

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: true
```

Or use the shorthand:

```{.yaml filename="great-docs.yml"}
page_status: true
```

## Adding a Status to a Page

Set the `status` key in the YAML frontmatter of any user guide, recipe, or custom section page:

```{.yaml filename="user_guide/03-migration.qmd"}
---
title: "Migration Guide"
status: deprecated
---
```

The value must match one of the defined status keys (see below). Pages without a `status` key
display no badge.

## Built-in Statuses

Great Docs ships with five built-in statuses, each with a [Lucide](https://lucide.dev/icons/) icon,
color, and description:

| Key            | Label          | Icon                | Color   | Description                         |
|----------------|----------------|---------------------|---------|-------------------------------------|
| `new`          | New            | `sparkles`          | Green   | Recently added                      |
| `updated`      | Updated        | `refresh-cw`        | Blue    | Recently updated                    |
| `beta`         | Beta           | `flask-conical`     | Amber   | Beta feature                        |
| `deprecated`   | Deprecated     | `triangle-alert`    | Red     | May be removed in a future release  |
| `experimental` | Experimental   | `beaker`            | Purple  | API may change without notice       |

Here is how these five statuses look as page-level badges:

<style>
.gd-demo-badge, .gd-demo-sidebar-item, .gd-demo-sidebar-pill, .gd-demo-page-mock {
  font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
}
.gd-demo-badge {
  display: inline-flex;
  align-items: center;
  gap: 0.35rem;
  padding: 0.25rem 0.65rem;
  font-size: 14px;
  font-weight: 500;
  line-height: 1.4;
  border-radius: 0.35rem;
}
.gd-demo-badge .gd-demo-lbl { font-weight: 600; }
.gd-demo-badge .gd-demo-dsc { font-weight: 400; opacity: 0.8; }
.gd-demo-sidebar-item {
  display: flex;
  align-items: center;
  padding: 0.3rem 0.75rem;
  font-size: 0.875rem;
  color: #374151;
}
body.quarto-dark .gd-demo-sidebar-item { color: #d1d5db; }
.gd-demo-sidebar-pill {
  display: inline-flex;
  align-items: center;
  margin-left: 4px;
  padding: 0.05rem 0.35rem;
  font-size: 0.65rem;
  font-weight: 600;
  line-height: 1.3;
  border-radius: 0.75rem;
  white-space: nowrap;
}
.gd-demo-sidebar-list {
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 0.4rem 0;
  max-width: 300px;
  margin: 1rem 0;
  background: transparent;
}
body.quarto-dark .gd-demo-sidebar-list { border-color: #374151; }
.gd-demo-page-mock {
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  padding: 1rem 1.25rem;
  margin: 1rem 0;
  background: transparent;
}
body.quarto-dark .gd-demo-page-mock { border-color: #374151; }
</style>

<div style="display:flex; flex-direction:column; align-items:flex-start; gap:0.35rem; margin:1rem 0;">
<div class="gd-demo-badge" style="color:#10b981; background:rgba(16,185,129,0.08); border:1px solid rgba(16,185,129,0.25);"><span class="gd-demo-lbl">✦ New</span> <span class="gd-demo-dsc">&mdash; Recently added</span></div>
<div class="gd-demo-badge" style="color:#3b82f6; background:rgba(59,130,246,0.08); border:1px solid rgba(59,130,246,0.25);"><span class="gd-demo-lbl">↻ Updated</span> <span class="gd-demo-dsc">&mdash; Recently updated</span></div>
<div class="gd-demo-badge" style="color:#f59e0b; background:rgba(245,158,11,0.08); border:1px solid rgba(245,158,11,0.25);"><span class="gd-demo-lbl">⚗ Beta</span> <span class="gd-demo-dsc">&mdash; Beta feature</span></div>
<div class="gd-demo-badge" style="color:#ef4444; background:rgba(239,68,68,0.08); border:1px solid rgba(239,68,68,0.25);"><span class="gd-demo-lbl">⚠ Deprecated</span> <span class="gd-demo-dsc">&mdash; May be removed in a future release</span></div>
<div class="gd-demo-badge" style="color:#8b5cf6; background:rgba(139,92,246,0.08); border:1px solid rgba(139,92,246,0.25);"><span class="gd-demo-lbl"><svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 3h15"></path><path d="M6 3v16a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V3"></path><path d="M6 14h12"></path></svg> Experimental</span> <span class="gd-demo-dsc">&mdash; API may change without notice</span></div>
</div>

All built-in status labels and descriptions are automatically translated when the site uses a
non-English language (see [Internationalization](internationalization.qmd)).

## Custom Statuses

The five built-in statuses cover common lifecycle stages, but your team may have its own workflow.
You can add your own statuses or override built-in ones via the `statuses` map in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: true
  statuses:
    draft:
      label: "Draft"
      icon: pencil
      color: "#6b7280"
      description: "Work in progress"
    review:
      label: "In Review"
      icon: eye
      color: "#0ea5e9"
      description: "Awaiting technical review"
```

Each custom status definition accepts:

| Key           | Type   | Required | Description                                               |
|---------------|--------|----------|-----------------------------------------------------------|
| `label`       | string | No       | Display text (defaults to the key in title case)           |
| `icon`        | string | No       | Lucide icon name (e.g., `pencil`, `eye`)                   |
| `color`       | string | No       | CSS color for the badge (defaults to `#6b7280`)            |
| `description` | string | No       | Short explanation shown on the page badge and as a tooltip |

Custom statuses use their literal `label` and `description` values in all languages. Only the five
built-in statuses are translated automatically.

Use the custom key in frontmatter just like a built-in status:

```{.yaml filename="user_guide/10-new-api.qmd"}
---
title: "New API Design"
status: draft
---
```

## Overriding Built-in Statuses

To change a built-in status (for example, switching the icon or color for `deprecated`), redefine
it in `statuses`:

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: true
  statuses:
    deprecated:
      label: "Legacy"
      icon: archive
      color: "#9ca3af"
      description: "Superseded by a newer approach"
```

Your definition fully replaces the built-in default for that key. Any fields you omit fall back to
their defaults (gray color, title-cased label, no icon).

## Controlling Where Badges Appear

By default, badges are shown in both locations. You can disable either one independently if you
prefer a subtler approach.

### Sidebar Only

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: true
  show_on_pages: false   # No badge below the title
  show_in_sidebar: true  # Icon in sidebar (default)
```

### Page Title Only

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: true
  show_on_pages: true    # Badge below the title (default)
  show_in_sidebar: false # No icon in sidebar
```

## How It Looks

### On the Page

The page-level badge appears directly below the title (and subtitle, if present). It displays the
status icon, label, and description in the status color:

<div class="gd-demo-page-mock">
<div style="font-size:1.5rem; font-weight:700; margin-bottom:0.15rem;">Getting Started</div>
<div style="font-size:0.95rem; color:#6b7280; margin-bottom:0.5rem;">A quick introduction to the package</div>
<div class="gd-demo-badge" style="color:#10b981; background:rgba(16,185,129,0.08); border:1px solid rgba(16,185,129,0.25);"><span class="gd-demo-lbl">✦ New</span> <span class="gd-demo-dsc">&mdash; Recently added</span></div>
</div>

### In the Sidebar

Sidebar links for pages with a status show a small colored pill after the link text. Hovering over
the pill displays a tooltip with the full label and description:

<div class="gd-demo-sidebar-list">
<div class="gd-demo-sidebar-item">Getting Started <span class="gd-demo-sidebar-pill" style="color:#10b981; background:rgba(16,185,129,0.1);" title="New — Recently added">✦</span></div>
<div class="gd-demo-sidebar-item">Migration Guide <span class="gd-demo-sidebar-pill" style="color:#ef4444; background:rgba(239,68,68,0.1);" title="Deprecated — May be removed in a future release">⚠</span></div>
<div class="gd-demo-sidebar-item" style="opacity:0.7;">Configuration</div>
<div class="gd-demo-sidebar-item">New API Design <span class="gd-demo-sidebar-pill" style="color:#8b5cf6; background:rgba(139,92,246,0.1);" title="Experimental — API may change without notice"><svg xmlns="http://www.w3.org/2000/svg" width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 3h15"></path><path d="M6 3v16a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V3"></path><path d="M6 14h12"></path></svg></span></div>
</div>

Pages without a status display no indicator, keeping the sidebar clean.

## Which Pages Are Scanned?

Great Docs scans for `status` frontmatter in `.qmd` files found in:

- **User guide** pages (`user-guide/`)
- **Recipes** pages (`recipes/`)
- **Custom sections** (any section defined in `sections:` config)

API reference pages, the changelog, and index pages are not scanned. This keeps badges focused on
content pages where lifecycle status is meaningful.

## Full Configuration Reference

Here is the complete `page_status` configuration with all options and their defaults:

```{.yaml filename="great-docs.yml"}
page_status:
  enabled: false           # Master switch (default: false)
  show_in_sidebar: true    # Show icon in sidebar links (default: true)
  show_on_pages: true      # Show badge below page titles (default: true)
  statuses:                # Status definitions (built-ins shown below)
    new:
      label: "New"
      icon: sparkles
      color: "#10b981"
      description: "Recently added"
    updated:
      label: "Updated"
      icon: refresh-cw
      color: "#3b82f6"
      description: "Recently updated"
    beta:
      label: "Beta"
      icon: flask-conical
      color: "#f59e0b"
      description: "Beta feature"
    deprecated:
      label: "Deprecated"
      icon: triangle-alert
      color: "#ef4444"
      description: "May be removed in a future release"
    experimental:
      label: "Experimental"
      icon: beaker
      color: "#8b5cf6"
      description: "API may change without notice"
```

## Tips

A few guidelines help keep status badges effective across your documentation.

- **Use statuses sparingly**: a page should carry a status only when it communicates something
actionable. If every page is "New", the badge loses its value.
- **Remove stale statuses**: revisit `status: new` and `status: updated` periodically and remove
them once the content is no longer recent.
- **Combine with tags**: statuses and tags serve different purposes. Tags categorize content by
topic; statuses communicate lifecycle. A page can have both.
- **Custom statuses for workflows**: define statuses like `draft` or `review` to track editorial
progress while keeping the documentation published.

## Next Steps

Status badges communicate lifecycle information at a glance. They work best when used selectively
for pages that are genuinely new, recently updated, or approaching deprecation.

- [Page Tags](page-tags.qmd) categorizes pages by topic with filterable tag listings
- [API Evolution](api-evolution.qmd) tracks changes across releases at the API level
- [Internationalization](internationalization.qmd) covers how built-in badge labels are translated
- [Configuration](configuration.qmd) covers all status badge settings in `great-docs.yml`



## Quality & Maintenance

# API Evolution

Great Docs can track how your package's public API changes across tagged releases. This is useful for understanding signature drift, detecting breaking changes, and generating visual migration aids for your users.

## Quick Start

Compare two versions from the command line:

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0
```

This produces a summary showing added, removed, and changed symbols, with breaking-change detection and migration hints:

```
════════════════════════════════════════════════════════════
API Diff: v0.1.0 → v1.0.0
Package: my_package
════════════════════════════════════════════════════════════

  Added: 3  │  Removed: 1  │  Changed: 5  │  Breaking: 2

──────────────────────────────────────────────────────────
  ✚ Added (3)
──────────────────────────────────────────────────────────
    + preview
    + scan
    + setup_github_pages

──────────────────────────────────────────────────────────
  ✖ Removed (1)  [BREAKING]
──────────────────────────────────────────────────────────
    - generate_config
      hint: 'generate_config' was removed. Check the changelog for a replacement.

──────────────────────────────────────────────────────────
  ∆ Changed (5)
──────────────────────────────────────────────────────────
    ~ build  ⚠ BREAKING
        ⚠ New parameter: watch
        Return type: (none) → int
```

Use `--json` for machine-readable output, perfect for CI checks:

```{.bash filename="Terminal"}
great-docs api-diff v0.9.0 v1.0.0 --json
```

## Tracking a Single Symbol

Use `--symbol` to follow one function or class across every version:

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0 --symbol build
```

Add `--changes-only` to skip versions where the signature was unchanged:

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0 --symbol build --changes-only
```

## Evolution Table

The `--table` flag renders a positional parameter grid that shows exactly how a signature evolved. Each column is a version (where a change occurred), and each row is a positional parameter slot. Every cell is self-contained (it shows the parameter name, type, and default at that position) so insertions, reorderings, and removals are immediately visible.

```{.bash filename="Terminal"}
# Plain-text table (for terminal)
great-docs api-diff v0.1.0 v1.0.0 --symbol build --table --changes-only

# HTML table with disclosure wrapper (for embedding in docs)
great-docs api-diff v0.1.0 v1.0.0 --symbol build --table --html
```

### Live Demo

Below is a demonstration of how a `build()` function might evolve over four releases. The table is rendered from a JSON data file using the shortcode:

```{shortcodes="false"}
{{< evolution build json="api-evolution-demo.json" >}}
```

{{< evolution build json="api-evolution-demo.json" >}}

Reading this table left-to-right tells the story:

- `v0.1.0`: there are two parameters, `project_path=` (required `str`) and `output_dir=` (with a string default).
- `v0.3.0`: `project_path=` widens to `str | Path`. A new `watch=` parameter is appended. `output_dir=` changes its default to a `Path` object.
- `v0.6.0`: `watch=` moves to position 2 (before `output_dir`), and a new `clean=` parameter is added. The return type changes from `None` to `int`.
- `v1.0.0`: `project_path=` gets a default (`None`), `output_dir=`'s default changes to `"_site"`, and a new `verbose=` parameter is appended.

Notice how this layout makes insertions and reorderings visible. In v0.6.0 you can see that `watch=` moved up and `output_dir=` moved down, which would be invisible in a row-per-parameter-name layout.

### Embedding in Pages

To insert an evolution table directly into a User Guide page or any `.qmd` file, use the shortcode syntax:

```{shortcodes="false"}
{{< evolution build >}}
```

This produces a self-contained HTML table (with embedded CSS) showing how `build()` evolved across all tagged releases. The table is generated at build time so no Python code blocks or manual HTML is required.

#### Options

You can customize the output with named arguments:

```{shortcodes="false"}
{{< evolution symbol="build" old_version="v0.3.0" new_version="v1.0.0" >}}
```

| Option | Default | Description |
|--------|---------|-------------|
| (positional or `symbol`) | *required* | Symbol name to track |
| `old_version` | first tag | Earliest version to include |
| `new_version` | latest tag | Latest version to include |
| `changes_only` | `"true"` | Only show versions where the signature changed |
| `disclosure` | `"false"` | Wrap in a collapsible `<details>` element |
| `summary` | auto | Custom label for the disclosure header |
| `css` | `"true"` | Include the `<style>` block (set `"false"` for the second table on a page) |
| `json` | — | Path to a JSON file; renders from data instead of live git history |

#### Multiple Tables on One Page

When embedding more than one table, set `css="false"` on all but the first to avoid duplicating the stylesheet:

```{shortcodes="false"}
{{< evolution build >}}

{{< evolution preview css="false" >}}

{{< evolution GreatDocs css="false" >}}
```

## JSON Data Format {#json-spec}

The evolution table can be exported as JSON for use in CI pipelines, external tools, or custom rendering:

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0 --symbol build --json > evolution.json
```

The schema of the evolution table JSON (obtained via `evolution_table_to_dict()`) is:

```{.json filename="evolution.json"}
{
  "symbol": "build",
  "package": "my_package",
  "versions": ["v0.1.0", "v0.3.0", "v0.6.0", "v1.0.0"],
  "slots": [
    {
      "position": 0,
      "cells": [
        {"name": "project_path", "type": "str", "default": null},
        {"name": "project_path", "type": "str | Path", "default": null},
        ...
      ]
    }
  ],
  "returns": ["None", "None", "int", "int"]
}
```

| Field | Description |
|-------|-------------|
| `symbol` | Name of the tracked symbol |
| `package` | Python package name |
| `versions` | Ordered list of version labels (column headers) |
| `slots` | Array of positional parameter slots |
| `slots[].position` | Zero-based parameter position |
| `slots[].cells` | Array parallel to `versions` (one entry per column) |
| `slots[].cells[]` | `{"name", "type", "default"}` or `null` if the slot didn't exist |
| `returns` | Array parallel to `versions` with return types (`null` if none); omitted if no version has a return annotation |

A `null` entry in `cells` means the parameter slot did not exist in that version (the function had fewer parameters).

## Other Modes

### Dependency Graph

The `--graph` flag generates a [Mermaid](https://mermaid.js.org/) diagram showing class inheritance relationships within your package at the newer version. Classes are drawn as rectangles, functions as rounded boxes, and arrows point from parent to child.

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0 --graph
```

The output is a Mermaid `graph TD` block that you can paste into a `.qmd` file, a GitHub comment, or any Mermaid-compatible renderer. Add `--json` for a machine-readable representation with `nodes` (name → kind) and `inheritance` edge lists.

### API Surface Timeline

The `--timeline` flag produces a Mermaid bar chart that tracks how the total number of public symbols (classes and functions combined) grows across every tagged release between the two versions.

```{.bash filename="Terminal"}
great-docs api-diff v0.1.0 v1.0.0 --timeline
```

This is useful for spotting rapid API expansion or for confirming that a stabilization release didn't inadvertently expose new symbols. The default output is a `xychart-beta` Mermaid block; use `--json` for an array of `{version, symbols, classes, functions}` objects suitable for custom charting.

## Next Steps

API Evolution gives you visibility into how your package's public surface changes over time. Use the diff reports and shortcodes to keep users informed about additions, removals, and breaking changes across releases.

- [Versioned Docs](multi-version-docs.qmd) covers publishing multiple documentation versions side by side
- [Changelog](changelog.qmd) covers auto-generated changelogs from GitHub Releases
- [Configuration](configuration.qmd) covers all `great-docs.yml` options

If you run into rough edges or have ideas for what would be most useful, please [open an issue](https://github.com/posit-dev/great-docs/issues).



## Config & Theming

# Scale-to-Fit

Wide content like tables created with [Great Tables](https://github.com/posit-dev/great-tables), DataFrames, and custom `_repr_html_` objects often overflow the content area on smaller screens. When a table is just slightly wider than the container, the reader has to scroll horizontally to see a small sliver of remaining content, which is a frustrating experience. Shrinking the element by a few percent makes it fit cleanly and nobody notices the difference. On the other hand, when an element is dramatically wider than the container, scaling it down would make the text unreadably small. In that case, horizontal scrolling is the better option.

Great Docs includes a **scale-to-fit** system that handles both situations. It automatically shrinks targeted elements so they fit within the container width, and falls back to horizontal scrolling when the element would need to shrink beyond a configurable threshold.

## See It in Action

The examples below use `:::{.scale-to-fit}` divs to demonstrate the scaling behavior, but this is just one of three ways to enable scale-to-fit. You can also target elements globally through `great-docs.yml` or per-page through frontmatter (both covered in later sections). Try resizing your browser window to see elements shrink. The third example uses a per-div `data-min-scale` attribute to show the scrolling fallback.

### A Table That Fits Normally

This table is narrow enough to fit the content area without any scaling. It renders at its natural size.

````markdown
:::{.scale-to-fit}
```{=html}
<table style="width: 400px; ...">
  ...
```
:::
````

:::{.scale-to-fit}
```{=html}
<table style="width: 400px; border-collapse: collapse; font-size: 14px;">
  <thead>
    <tr style="background: var(--bs-tertiary-bg, #f0f0f0);">
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Name</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Value</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Status</th>
    </tr>
  </thead>
  <tbody>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Alpha</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">42</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Active</td></tr>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Beta</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">87</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Pending</td></tr>
  </tbody>
</table>
```
:::

At 400px, this table fits comfortably within the content area. No scaling is applied and no scrollbar appears.

### A Wide Table That Scales Down

This table is 1600px wide, wider than most content areas. Scale-to-fit shrinks it proportionally so it fits without overflow.

````markdown
:::{.scale-to-fit}
```{=html}
<table style="width: 1600px; ...">
  ...
```
:::
````

:::{.scale-to-fit}
```{=html}
<table style="width: 1600px; border-collapse: collapse; font-size: 14px;">
  <thead>
    <tr style="background: var(--bs-tertiary-bg, #f0f0f0);">
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">ID</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Name</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Category</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Region</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q1 Revenue</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q2 Revenue</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q3 Revenue</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q4 Revenue</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Total</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Status</th>
    </tr>
  </thead>
  <tbody>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">001</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Acme Corp</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Enterprise</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">North America</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,245,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,389,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,102,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,567,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$5,303,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Active</td></tr>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">002</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Globex Inc</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Mid-Market</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Europe</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$892,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,045,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$978,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,123,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$4,038,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Active</td></tr>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">003</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Initech</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Startup</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Asia Pacific</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$234,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$312,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$289,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$401,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$1,236,000</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Review</td></tr>
  </tbody>
</table>
```
:::

Notice that the text is slightly smaller than in the first table. The system shrank the 1600px table to fit the content area, and the reduction is modest enough that everything stays readable.

### A Very Wide Element (Scrolling Fallback)

This element is 2400px wide. It has `data-min-scale="0.65"` set directly on the div, so when the computed scale factor drops below 0.65 the system falls back to horizontal scrolling instead of shrinking the content to an unreadable size.

````markdown
:::{.scale-to-fit data-min-scale="0.65"}
```{=html}
<table style="width: 2400px; ...">
  ...
```
:::
````

:::{.scale-to-fit data-min-scale="0.65"}
```{=html}
<table style="width: 2400px; border-collapse: collapse; font-size: 14px;">
  <thead>
    <tr style="background: var(--bs-tertiary-bg, #f0f0f0);">
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">ID</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Product</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">SKU</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Category</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Supplier</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Region</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Warehouse</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Stock</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Unit Price</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q1 Sales</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q2 Sales</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q3 Sales</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Q4 Sales</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Annual Total</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">YoY Growth</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Margin</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Rating</th>
      <th style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Status</th>
    </tr>
  </thead>
  <tbody>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">P-001</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Widget Pro Max</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">WPM-2024-A</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Hardware</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">TechSource Ltd</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">North America</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Dallas-TX</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">12,450</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$149.99</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">3,200</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">4,150</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">3,890</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">5,100</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">16,340</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">+18.2%</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">34.5%</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">4.7/5</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Active</td></tr>
    <tr><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">P-002</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Gadget Elite</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">GE-2024-B</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Electronics</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">CircuitWorks</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Europe</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Munich-DE</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">8,320</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">$249.50</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">1,800</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">2,450</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">2,100</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">3,200</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">9,550</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">+12.7%</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">28.3%</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">4.5/5</td><td style="padding: 8px 12px; border: 1px solid var(--bs-border-color, #ddd);">Active</td></tr>
  </tbody>
</table>
```
:::

This table is so wide that scaling it down would make the text unreadable. Because `data-min-scale="0.65"` is set on the div, the system switches to horizontal scrolling instead. Scroll right to see the rest of the columns.

## How It Works

The scale-to-fit system operates as a three-level cascade:

1. **Global config**: target specific CSS selectors across the entire site
2. **Page frontmatter**: override the selectors and threshold on individual pages
3. **Manual div**: wrap any content block in a `:::{.scale-to-fit}` div for one-off scaling

When an element matches a targeted selector, the system:

- Measures the element's natural width against the available container width
- Computes a scale factor (`container width / element width`)
- Applies a CSS `transform: scale()` to shrink the element proportionally
- If the scale factor falls below the minimum threshold, the element is shown at full size with horizontal scrolling instead

The scaling is applied on page load and recalculated on window resize. Together, these three levels give you fine-grained control over which elements scale, how far they can shrink, and when they should scroll instead.

## Global Configuration

To enable scale-to-fit for specific elements across your entire site, add `scale_to_fit` to your `great-docs.yml` with a list of CSS selectors. Any element that matches one of these selectors will be automatically scaled.

```{.yaml filename="great-docs.yml"}
scale_to_fit:
  - "#my_wide_table"
  - ".wide-output"
```

A single selector also works:

```{.yaml filename="great-docs.yml"}
scale_to_fit:
  - "#gt_table_1"
```

### Minimum Scale Threshold

By default there is no minimum scale: elements will shrink as much as needed to fit. You can set a threshold below which the system falls back to horizontal scrolling instead:

```{.yaml filename="great-docs.yml"}
scale_to_fit:
  - "#my_wide_table"
scale_to_fit_min_scale: tablet
```

The threshold can be a **viewport keyword** or a **numeric fraction**.

#### Viewport Keywords

Viewport keywords switch to scrolling when the viewport is at or below the named breakpoint, regardless of the computed scale factor.

| Keyword | Max Width | When It Scrolls |
|---------|-----------|-----------------|
| `mobile` | 576 px | Phones in portrait |
| `tablet` | 768 px | Tablets in portrait |
| `desktop` | 992 px | Small laptops and below |

```{.yaml filename="great-docs.yml"}
scale_to_fit_min_scale: mobile   # Only scroll on phones
```

```{.yaml filename="great-docs.yml"}
scale_to_fit_min_scale: desktop  # Scroll on anything below a large desktop
```

Viewport keywords are the simplest way to set a threshold: pick the device class where scaling should stop and scrolling should begin.

#### Numeric Fraction

A decimal value between 0 and 1 sets a minimum scale factor. If the computed scale drops below this value, the element scrolls instead.

```{.yaml filename="great-docs.yml"}
scale_to_fit_min_scale: 0.5  # Scroll if element would shrink below 50%
```

```{.yaml filename="great-docs.yml"}
scale_to_fit_min_scale: 0.35  # Allow more aggressive shrinking
```

Choose a numeric fraction when you want precise control over the shrink limit, independent of any particular viewport size.

### Disabling

To disable scale-to-fit entirely, remove the `scale_to_fit` key from your config or set it explicitly:

```{.yaml filename="great-docs.yml"}
scale_to_fit: false
```

With `scale_to_fit` and `scale_to_fit_min_scale`, the global configuration covers most sites. Every page inherits the same selectors and threshold, so you only need to set it once. For pages that need different behavior, use page-level overrides.

## Page-Level Overrides

Individual pages can override both the targeted selectors and the minimum scale threshold using frontmatter keys. This is useful when a particular page needs different behavior than the site-wide default.

### Overriding Selectors

Use `scale-to-fit` in the page's YAML frontmatter to target different elements on that page:
```yaml
---
title: My Page
scale-to-fit:
  - "#special_table"
  - "#dashboard_widget"
---
```

The page-level selectors **replace** (not merge with) the global selectors for that page. If you want to keep the global selectors and add more, list them all in the page frontmatter.

### Overriding the Threshold

Use `scale-to-fit-min-scale` in frontmatter to set a different threshold for the page:

```yaml
---
title: My Page
scale-to-fit:
  - "#wide_output"
scale-to-fit-min-scale: mobile
---
```

If a page specifies `scale-to-fit` selectors but omits `scale-to-fit-min-scale`, the global `scale_to_fit_min_scale` value is used as a fallback. This lets you change which elements are targeted on a page without having to repeat the threshold.

### Combined Example

Consider a site that globally targets `#main_table` with a `tablet` threshold:

```{.yaml filename="great-docs.yml"}
scale_to_fit:
  - "#main_table"
scale_to_fit_min_scale: tablet
```

A specific page can override both:

```yaml
---
title: Dashboard
scale-to-fit:
  - "#main_table"
  - "#summary_card"
scale-to-fit-min-scale: 0.4
---
```

On this page, `#main_table` and `#summary_card` are both scaled, and the threshold is a 40 % minimum scale factor instead of the global `tablet` keyword. Page-level overrides give you full flexibility to tailor the scaling behavior for individual pages without changing the site-wide defaults.

## Manual Div Wrapping

For one-off cases where you want to scale a single block of content without adding it to the global config, wrap it in a `:::{.scale-to-fit}` fenced div in your `.qmd` page:

````markdown
:::{.scale-to-fit}
```{{python}}
#| echo: false
my_wide_widget()
```
:::
````

The `.scale-to-fit` class provides the same scaling behavior: content is measured, scaled to fit, and scrolled if it would exceed the minimum threshold. This approach requires no configuration at all; the elements inside the div are always considered for scaling. Use manual wrapping for isolated wide outputs that don't warrant a global selector.

### Per-Div Minimum Scale

You can set a minimum scale threshold directly on an individual div using the `data-min-scale` attribute. This accepts the same values as the global and page-level settings: a viewport keyword (`mobile`, `tablet`, `desktop`) or a numeric fraction between 0 and 1.

````markdown
:::{.scale-to-fit data-min-scale="0.5"}
```{{python}}
#| echo: false
my_extremely_wide_table()
```
:::
````

The per-div threshold takes precedence over any page-level or global threshold. This is useful when a single element on a page needs a different scrolling cutoff than the rest.

## Typical Selectors

The selectors you provide are standard CSS selectors. These examples show common patterns:

| Selector | Matches |
|----------|---------|
| `#my_table` | An element with `id="my_table"` |
| `.gt_table` | Any element with class `gt_table` |
| `table.dataframe` | A `<table>` element with class `dataframe` |

For GT tables, the `id` parameter controls the HTML `id`:

```python
GT(df, id="my_table")
```

For objects with `_repr_html_`, include the `id` attribute in your returned HTML:

```python
class MyWidget:
    def _repr_html_(self):
        return '<div id="my_widget" style="width:1400px;">...</div>'
```

As long as your output element has a stable `id` or class name, it can be targeted by scale-to-fit: the system works with any HTML content, not just tables.

## Configuration Reference

### Global (great-docs.yml)

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `scale_to_fit` | list of strings | `None` | CSS selectors to target for auto-scaling |
| `scale_to_fit_min_scale` | string or float | `None` | Minimum threshold: `"mobile"`, `"tablet"`, `"desktop"`, or a float (0–1) |

### Page Frontmatter

| Key | Type | Description |
|-----|------|-------------|
| `scale-to-fit` | list of strings | Overrides global selectors for this page |
| `scale-to-fit-min-scale` | string or float | Overrides global threshold for this page |

Note the key naming: global config uses **underscores** (`scale_to_fit`) to match Python property names, while page frontmatter uses **hyphens** (`scale-to-fit`) to match Quarto's built-in key style. Between these two tables you have the full set of options available for controlling scale-to-fit behavior at both the site and page level.

## Putting It All Together

For most projects, a single `scale_to_fit` entry in `great-docs.yml` is all you need. Pick the selectors that match your wide outputs, choose a minimum scale threshold that feels right, and every page on your site benefits automatically. When a particular page calls for something different, override the selectors or threshold in that page's frontmatter. And for the occasional one-off table or widget that just needs to fit, wrap it in a `:::{.scale-to-fit}` div and move on. The three levels work together so you can start simple and add precision only where it matters.

## Next Steps

Scale-to-fit keeps wide content readable on any screen size without horizontal scrolling. The three-level cascade (global, page, div) lets you start with a single config line and add precision only where needed.

- [Table Previews](table-previews.qmd) covers the `tbl_preview()` function for rendering data tables
- [Table Explorer](table-explorer.qmd) adds interactive filtering, sorting, and pagination to tables
- [Configuration](configuration.qmd) covers all `great-docs.yml` options including scale-to-fit settings



## Build & Deploy

# Versioned Docs

Libraries evolve, but users on older releases need documentation that matches the version they have installed. Great Docs makes multi-version documentation a first-class authoring experience: declare your versions, annotate your content, and let the build system produce a coherent, version-aware site.

## Quick Start

Getting started with versioned documentation takes just two lines of configuration. Here's the fastest path to a working multi-version site.

Add a `versions` key to your `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
versions:
  - "0.3"
  - "0.2"
  - "0.1"
```

Then build as usual:

```{.bash filename="Terminal"}
great-docs build
```

This builds three independent copies of your site:

- `/`: the latest version (0.3), served at the root for clean URLs
- `/v/0.2/`: version 0.2
- `/v/0.1/`: version 0.1

A version selector dropdown appears in the navbar, letting visitors switch between versions.

That's all you need for basic versioning. The sections below cover the full range of configuration options and authoring tools available.

## Configuration

The `versions` key in `great-docs.yml` controls which versions are built and how they appear in the version selector. You can also configure the selector widget itself and set up floating URL aliases.

### Version List

Versions are declared as an ordered list, newest first. The first non-prerelease entry is treated as "latest" by default.

**Minimal form** with just strings:

```{.yaml filename="great-docs.yml"}
versions:
  - "0.3"
  - "0.2"
  - "0.1"
```

**Full form** with metadata:

```{.yaml filename="great-docs.yml"}
versions:
  - label: "0.4.0 (dev)"
    tag: dev
    version: "0.4"
    prerelease: true
  - label: "0.3.0"
    tag: "0.3"
    latest: true
  - label: "0.2.0"
    tag: "0.2"
    api_snapshot: api-snapshots/0.2.json
  - label: "0.1.0"
    tag: "0.1"
    eol: true
```

### Version Object Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `label` | `str` | Same as `tag` | Display name in the version selector |
| `tag` | `str` | Required | Short identifier for URL paths and fences |
| `latest` | `bool` | Auto-detected | Mark as the canonical latest version |
| `prerelease` | `bool` | `false` | Show a pre-release badge in the selector |
| `eol` | `bool` | `false` | Show an end-of-life warning banner |
| `api_snapshot` | `str` | `None` | Path to a pre-generated API snapshot JSON |
| `git_ref` | `str` | `None` | Git tag for API introspection (tags only) |
| `released` | `str` | `None` | ISO date (e.g. `"2025-03-15"`) when this version was released. Used by the `days` badge expiry mode |
| `version` | `str` | `None` | Semantic version this tag represents (e.g. `"0.8"` for a `dev` tag). Enables version expressions like `>=0.8` to match non-numeric tags |

When strings are used instead of dicts, `tag` and `label` both default to the string value. Most projects only need `tag`, `label`, and occasionally `api_snapshot`. The other fields are useful when you have pre-release or end-of-life versions to distinguish.

### Version Selector Settings

The version selector widget is enabled automatically when `versions` is non-empty. These settings let you fine-tune its behavior and placement:

```{.yaml filename="great-docs.yml"}
version_selector:
  enabled: true
  placement: navbar-right   # "navbar-right" | "navbar-left" | "sidebar-top"
  warning_banner: true      # Show banner on non-latest versions
```

### Floating Aliases

Floating aliases give you stable, version-independent URLs that always resolve to the right version. Great Docs creates these bookmarkable URL aliases:

- `/v/latest/`: redirects to the version marked `latest`
- `/v/stable/`: same as `latest`
- `/v/dev/`: redirects to the version marked `prerelease`

These are useful for sharing stable links that always point to the right version. For example, a README badge linking to `/v/latest/` will always reach the current stable docs without hard-coding a version number.

## Version Fences

Version fences let you show or hide blocks of content per version. They work in any `.qmd` file: user guide pages, recipes, reference pages, and custom sections.

### Show Content for Specific Versions

The most common fence type is `.version-only`, which includes a block only in matching versions:

```{.markdown filename="guide.qmd"}
This content appears in all versions.

::: {.version-only versions=">=0.3"}
This paragraph only appears in version 0.3 and later.
:::

::: {.version-only versions="0.1,0.2"}
This paragraph only appears in versions 0.1 and 0.2.
:::
```

### Hide Content from Specific Versions

Sometimes it's easier to say "show this everywhere except version X". Use `.version-except` for that:

```{.markdown filename="guide.qmd"}
::: {.version-except versions="0.1"}
This content appears in every version except 0.1.
:::
```

### Version Expressions

Both `.version-only` and `.version-except` accept version expressions: flexible patterns that target one or more versions. Here's the full set of supported expressions:

| Expression | Meaning |
|---|---|
| `"0.3"` | Exactly version 0.3 |
| `"0.2,0.3"` | Versions 0.2 or 0.3 |
| `">=0.2"` | Version 0.2 and all newer versions |
| `"<=0.2"` | Version 0.2 and all older versions |
| `">0.1,<0.4"` | Strictly between 0.1 and 0.4 |
| `"*"` | All versions |

When an expression contains only bare tags (no operators), they are evaluated with **OR logic**: the target matches if it equals any listed tag. When operators are present, all constraints are evaluated with **AND logic** so every constraint must be satisfied. This lets you express both "any of these versions" and "within this range" naturally.

### Nesting Fences

Fences can be nested. An inner fence is only evaluated if its outer fence includes the current version:

```{.markdown filename="guide.qmd"}
::: {.version-only versions=">=0.2"}
Available since 0.2.

::: {.version-only versions=">=0.3"}
This extra detail only appears in 0.3 and later.
:::

:::
```

In version 0.2, only the outer content appears. In version 0.3+, both blocks are visible. In version 0.1, neither appears. This is useful for progressive disclosure, adding detail in newer versions without duplicating the surrounding context.

## Page-Level Version Scoping

When an entire page only applies to certain versions (like a migration guide or a feature that didn't exist in older releases), you can scope it at the page level rather than wrapping every paragraph in a fence.

Restrict an entire page to specific versions by adding `versions` to its YAML frontmatter:

```{.yaml filename="migration-guide.qmd"}
---
title: "Migration Guide: 0.2 → 0.3"
versions: ["0.3"]
---
```

```{.yaml filename="legacy-config.qmd"}
---
title: "Legacy Configuration"
versions: ["0.1", "0.2"]
---
```

### Version Expressions in Frontmatter

Instead of listing every matching version explicitly, you can use the same version expression syntax that fences support. This is especially useful for pages that apply to a version "and everything newer" so you don't need to update the frontmatter each time a new version is released:

```{.yaml filename="new-feature.qmd"}
---
title: "Social Cards"
versions: ">=0.5"
---
```

This page will appear in version 0.5, 0.6, 0.7, dev, and any future version, without needing a change when a new release is tagged.

All expression types work:

| Frontmatter | Meaning |
|---|---|
| `versions: ">=0.5"` | Version 0.5 and all newer versions |
| `versions: "<=0.3"` | Version 0.3 and all older versions |
| `versions: ["0.3", "dev"]` | Exactly versions 0.3 and dev |
| `versions: ["0.3"]` | Exactly version 0.3 |

::: {.callout-tip}
## Prefer expressions for forward-looking pages
Use `versions: ">=0.5"` instead of `versions: ["0.5", "0.6", "0.7", "dev"]`. The expression form automatically includes future versions so you never need to update frontmatter when a new version is released.
:::

Pages with no `versions` key appear in **all** versions. Scoped pages are excluded from the sidebar, search index, and build output for non-matching versions. This keeps the navigation clean and users never see links to pages that don't exist in their version.

## Section-Level Version Scoping

For coarser control, you can scope an entire section directory to specific versions. This is useful when a whole group of pages (like migration guides or a new tutorial series) only makes sense for certain releases.

Scope sections in your configuration:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Recipes
    dir: recipes

  - title: Migration Guides
    dir: migrations
    versions: ["0.2", "0.3", "dev"]
```

The `migrations/` section only appears in versions 0.2, 0.3, and dev. It is completely absent from the sidebar and build output for version 0.1. Combined with page-level scoping, this gives you fine-grained control over what each version's readers see.

## Inline Version Badges

Inline badges are small visual markers that indicate when a feature was added, changed, or deprecated. They're ideal for annotating individual headings, parameters, or methods without wrapping content in a fence.

Mark individual features with inline badges:

```{.markdown filename="reference.qmd"}
## Widget [version-badge new]

The widget class.

## render() [version-badge changed 0.2]

The render function was refactored.

## legacy_mode [version-badge deprecated 0.1]

Use `new_mode()` instead.
```

These expand into styled `<span>` badges:

- `[version-badge new]` → **New in 0.3** (uses the current version's label)
- `[version-badge changed 0.2]` → **Changed in 0.2** (uses the explicit version)
- `[version-badge deprecated 0.1]` → **Deprecated in 0.1**

Badges are compact enough to use liberally throughout your API reference and user guide pages. They give readers an at-a-glance sense of what's new without interrupting the flow of the documentation.

### Upcoming Feature Badges

When a version is marked `prerelease: true` in your config, any `[version-badge new]` that references it automatically renders as "Upcoming" instead of "New". This lets you document features before they ship without special syntax:

```{.yaml filename="great-docs.yml"}
versions:
  - label: "0.8.0"
    tag: "0.8"
    prerelease: true
  - label: "0.7.0"
    tag: "0.7"
    latest: true
```

```{.markdown filename="guide.qmd"}
## Widget [version-badge new 0.8]
```

While 0.8 is prerelease, this badge renders differently depending on which version is being built:

- **Building 0.7** (stable): **Upcoming in 0.8** with `gd-badge-upcoming` style
- **Building 0.8** (prerelease): **New in 0.8** with `gd-badge-new` style

When you release 0.8 (remove `prerelease: true` or change it to `false`), it becomes **New in 0.8** on all builds — no source edits needed.

Only `new` badges are affected. `changed` and `deprecated` badges always render with their normal labels regardless of prerelease status.

::: {.callout-tip}
## Use the version number as the tag
If your prerelease tag is the actual version number (e.g. `tag: "0.8"` with `prerelease: true`), the transition from "Upcoming" to "New" is zero-maintenance: just flip the `prerelease` flag at release time. If you use a rolling tag like `dev`, you'll need to rename badge references from `dev` to the release number when you ship.
:::

### Upcoming Pages

When a page documents a feature that hasn't shipped yet, you want it visible in current docs (so readers know it's coming) but clearly marked as "Upcoming". Great Docs supports two mechanisms for this.

#### The `upcoming` frontmatter key

The most explicit approach — add `upcoming:` to a page's frontmatter with the version where the feature will ship:

```{.yaml filename="new-feature.qmd"}
---
title: "Versioned Docs"
upcoming: "0.8"
versions: ">=0.7"
---
```

This page is included starting from version 0.7, but when building 0.7 (or any version older than 0.8), it automatically receives `status: upcoming` — adding an "Upcoming" badge in the sidebar and at the top of the page. When building 0.8 or later, the page renders normally with no badge.

The `upcoming` key works with both the `version` field (e.g. referencing `"0.8"` which maps to a `dev` tag) and direct tags. Once 0.8 ships, the key becomes inert — no cleanup needed.

#### Automatic detection from version scoping

If a page is scoped exclusively to prerelease versions, Great Docs detects this automatically:

```{.yaml filename="prerelease-only.qmd"}
---
title: "New Feature"
versions: ["dev"]
---
```

Because `dev` is the only version listed and it's marked `prerelease: true`, the page automatically gets the "Upcoming" status badge — no `upcoming:` key needed. This also works with expressions like `versions: ">0.7"` when only prerelease entries are newer than 0.7.

::: {.callout-note}
Neither mechanism overrides an existing `status:` in frontmatter. If you've manually set `status: experimental`, that takes precedence over automatic upcoming injection.
:::

### Badge Expiry

As your project matures, "new" badges from several releases ago become noise rather than signal. The `new_is_old` option lets you automatically suppress old `new` badges so they stop rendering after a configurable threshold. Only `new` badges are affected while `changed` and `deprecated` badges always render.

Add `new_is_old` to your `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
new_is_old: 3 releases
```

With this setting, a `[version-badge new 0.3]` badge will render in versions 0.3 through 0.5 (three releases) and then silently disappear from version 0.6 onward. The badge is simply omitted from the output (no placeholder or residual markup is left behind).

#### Expiry Modes

| Value | Meaning |
|---|---|
| `"never"` | Badges never expire (the default) |
| `"3 releases"` | Expire after 3 releases, counting all versions including prerelease |
| `"2 minor releases"` | Expire after 2 releases, counting only non-prerelease versions |
| `"0.6"` | Expire starting at version 0.6 (all `new` badges from before 0.6 are suppressed) |
| `"2026-06-01"` | Expire after an absolute calendar date |
| `"180 days"` | Expire 180 days after the badge's version was released (requires `released` dates in the version config) |

The `releases` and `minor releases` modes measure the distance between the badge's version and the version currently being built. For example, `3 releases` means "show this badge as long as the version being built is fewer than 3 releases newer than the badge's version." The `minor releases` variant is identical except that it skips prerelease entries when counting, so a `dev` prerelease doesn't consume a slot in the window.

::: {.callout-tip}
## Choosing a mode
Most projects should start with `"3 releases"` or `"2 minor releases"`. The release-counting modes are simple, predictable, and don't require any extra configuration. Use `days` only if your releases are irregular and you want time-based expiry.
:::

#### Days Mode and Release Dates

The `days` mode requires `released` dates in your version configuration so that Great Docs can compute elapsed time:

```{.yaml filename="great-docs.yml"}
new_is_old: 180 days

versions:
  - label: "0.7.0"
    tag: "0.7"
    latest: true
    released: "2026-01-15"
  - label: "0.6.0"
    tag: "0.6"
    released: "2025-09-01"
  - label: "0.5.0"
    tag: "0.5"
    released: "2025-03-15"
```

A badge for a version without a `released` date is never expired (fail-open), so you can add dates incrementally.

#### Per-Page Override

You can override the global `new_is_old` setting on individual pages by adding `new-is-old` to the page's YAML frontmatter:

```{.yaml filename="important-feature.qmd"}
---
title: "Core Feature"
new-is-old: never
---
```

This keeps all `new` badges visible on that page regardless of the global setting. The per-page value uses the same syntax as the global option (any expiry mode works).

#### Interaction with Fences

Badge expiry only affects **rendering** (whether the badge `<span>` appears in the HTML output). It does not change version fence behavior. A heading like `## Widget [version-badge new 0.3]` inside a `::: {.version-only versions=">=0.3"}` fence will still be included in matching versions even if the badge itself is suppressed. The fence controls structural inclusion; the badge is purely visual.

## Version Callouts

When a version change needs more explanation than a badge can provide, use a version callout. These render as styled admonition boxes that draw the reader's attention to important changes.

```{.markdown filename="guide.qmd"}
::: {.version-note version="0.3"}
The `format` parameter was renamed from `fmt` in this version.
:::

::: {.version-deprecated version="0.1"}
The `legacy_mode` parameter is deprecated. Use `new_mode()` instead.
:::
```

These render as styled callout boxes:

- `.version-note` → a blue info callout titled "Added in 0.3"
- `.version-deprecated` → an orange warning callout titled "Deprecated since 0.1"

If you omit the `version=` attribute, the current version's label is used automatically.

Use callouts for migration notes, deprecation notices, or any change that benefits from a sentence or two of explanation. For shorter annotations, prefer inline badges instead.

## API Reference Versioning

The API reference is the most complex part of versioned documentation because the public API surface (classes, functions, parameters, and signatures) changes between releases. Great Docs supports three strategies for keeping each version's reference accurate, from the most hands-on to the most automated.

### Strategy A: Pre-Written Snapshots

The recommended approach for most projects. You run a CLI command to capture the current API surface before each release, and the build uses that snapshot to generate accurate reference pages for older versions.

Snapshot the current API before tagging a release:

```{.bash filename="Terminal"}
great-docs api-snapshot --output api-snapshots/v0.3.json
```

Then reference the snapshot in your config:

```{.yaml filename="great-docs.yml"}
versions:
  - label: "0.3.0"
    tag: "0.3"
    latest: true
  - label: "0.2.0"
    tag: "0.2"
    api_snapshot: api-snapshots/0.2.json
```

The latest version uses live introspection. Older versions generate their API reference pages from the snapshot (capturing all classes, functions, signatures, and parameters as they existed at that release).

This is the **recommended approach** for most projects because it's fast, reproducible, and doesn't require checking out old code.

### Strategy B: Git-Tag Introspection

For projects that want fully automatic API versioning without manually managing snapshot files, Great Docs can check out a Git tag and introspect the package at that point in time:

```{.yaml filename="great-docs.yml"}
versions:
  - label: "0.3.0"
    tag: "0.3"
  - label: "0.2.0"
    tag: "0.2"
    git_ref: v0.2.0
```

Only Git **tags** are accepted (not branches or arbitrary SHAs). This is a security restriction: tags are immutable references to reviewed, released code. Results are cached in `.great-docs-cache/snapshots/` so subsequent builds don't repeat the introspection. This strategy is slower on the first build but fully hands-off after that.

### Strategy C: Automatic Snapshots

A hybrid of the other two approaches: Great Docs automatically saves an API snapshot after every successful build. This creates a rolling archive so that by the time you tag a release, the snapshot already exists. You can also use the `--all-tags` flag to generate snapshots for all existing Git tags in one pass:

```{.bash filename="Terminal"}
great-docs api-snapshot --all-tags
```

Whichever strategy you choose, the end result is the same: each version's API reference pages accurately reflect the API surface as it existed at that release.

## CLI Commands

Great Docs adds several CLI commands and flags for working with versioned documentation.

### Building with Versions

The `build` command gains two new flags for controlling which versions are built:

```{.bash filename="Terminal"}
# Build all versions
great-docs build

# Build only specific versions
great-docs build --versions 0.3,0.2

# Build only the latest version (fast iteration)
great-docs build --latest-only
```

### Listing Versions

To see which versions are configured and their current status:

```{.bash filename="Terminal"}
great-docs versions
```

This displays the configured versions with their tags, labels, and status (latest, prerelease, eol).

### Managing API Snapshots

The `api-snapshot` command captures the current API surface for use with Strategy A:

```{.bash filename="Terminal"}
# Snapshot the current API
great-docs api-snapshot --output api-snapshots/v0.3.json

# Snapshot a specific package
great-docs api-snapshot --package my_package --output snapshot.json

# Snapshot all Git tags at once
great-docs api-snapshot --all-tags

# Overwrite existing snapshots
great-docs api-snapshot --all-tags --force
```

All snapshot files are plain JSON, so they can be committed to your repository and reviewed in pull requests.

## URL Structure

Versioned sites follow a predictable URL scheme that keeps the latest version at the root for clean canonical URLs, with older versions nested under `/v/`.

| URL | Content |
|---|---|
| `/` | Latest version homepage (no redirect) |
| `/v/0.2/` | Version 0.2 homepage |
| `/v/0.2/user-guide/` | Version 0.2 user guide |
| `/v/dev/` | Pre-release version homepage |
| `/v/latest/` | Alias → latest stable (redirect) |
| `/v/stable/` | Alias → latest stable (redirect) |

The unversioned root (`/`) serves the latest version directly for clean canonical URLs. Older versions get `<link rel="canonical">` tags pointing to the latest version, so search engines prefer the current docs. The `/v/` prefix is fixed (not configurable) to avoid collisions with pages whose names happen to match version numbers.

## Version Selector Widget

The version selector is the primary way visitors navigate between versions. It appears as a dropdown in the navbar and shows:

- the current version
- any pre-release versions (with a dot indicator)
- any end-of-life versions (with a warning indicator)

The selected version is persisted in `localStorage`, so returning visitors see their last-used version. The widget is also keyboard-accessible (arrow keys, Enter, Escape) and works entirely client-side with no server round-trips.

## Warning Banners

Visitors browsing older or pre-release documentation should know they're not looking at the current stable version. Warning banners handle this automatically. Non-latest versions display a dismissable banner at the top of every page:

- **Older versions**: "You are viewing documentation for version 0.2. The latest version is 0.3."
- **Pre-release versions**: "You are viewing documentation for a pre-release version (0.4.0-dev). It may contain unreleased features."
- **End-of-life versions**: "Version 0.1 is no longer supported. You should upgrade to the latest version."

Each banner includes a link to switch to the latest stable version. Banners can be disabled globally by setting `warning_banner: false` in the `version_selector` configuration.

## Deployment

Versioned sites work on any static hosting platform. Great Docs generates the necessary redirect rules for floating aliases so that URLs like `/v/latest/` resolve correctly regardless of your host.

### Netlify

Great Docs automatically generates a `_redirects` file with rewrite rules for floating aliases (`/v/latest/*`, `/v/stable/*`, `/v/dev/*`).

### Vercel

A `vercel.json` file is generated with equivalent rewrite rules.

### GitHub Pages

Static redirect HTML files are generated for each alias, so aliases work on any static hosting platform without server-side configuration. No matter which platform you deploy to, the core versioned site works out of the box. These redirect mechanisms only affect the floating alias URLs.

## Build Architecture

Understanding the build pipeline is optional for most users, but it helps when debugging or optimizing large versioned sites. The multi-version build runs in three stages:

1. **Preprocess**: For each version, copy the source tree, apply page/section scoping, resolve version fences, expand badges and callouts, and generate API reference pages from snapshots.

2. **Render**: Run `quarto render` for each version in parallel (up to 4 concurrent renders by default).

3. **Assemble**: Merge the per-version `_site/` outputs into the final site: latest version at the root, historical versions under `/v/<tag>/`. Generate the version map, aliases, and redirect files.

The version map (`_version_map.json`) is a JSON manifest listing all versions, their metadata, and which pages exist in each version. The version selector widget reads this at runtime to enable smart navigation and fallback behavior.

Because each version is rendered independently, the build is embarrassingly parallel (there are no cross-version dependencies during rendering). A project with five versions takes only slightly longer than a single-version build on a multi-core machine.

## Build directories

Versioned builds work in these directories:

- **`great-docs/`** stores the temporary Quarto project for the latest version and the assembled site in `great-docs/_site/`. Great Docs recreates the directory at the start of every build.
- **`great-docs-<tag>/`** stores one temporary, self-contained Quarto project for each historical version. Great Docs removes existing marked sibling directories before a versioned build and recreates only those selected for that build.
- **`.great-docs-cache/`** caches one API snapshot for each version that uses Strategy B (`git_ref`). Delete the directory to repeat API introspection during the next build.

Every version's Quarto project therefore sits one level below your project root, whether or not you configure `versions:`. A relative path in page content resolves to the same file either way.

A project configured with a single version, marked `latest: true`, creates no `great-docs-<tag>/` directories at all.

Add these to your `.gitignore`. Great Docs does this automatically when you run `great-docs init`, but if you set up versioning on an existing project you can add them manually:

```{.text filename=".gitignore"}
/great-docs/
/great-docs-*/
.great-docs-build/
.great-docs-cache/
.great-docs/
```

The generated ignore block also retains `.great-docs-build/` for older build layouts.
`.great-docs/` stores snapshots created by `great-docs api-snapshot`.

Great Docs deletes only build directories whose `_quarto.yml` contains its generated marker. It preserves other `great-docs-*/` directories and prints a warning. If an unmarked directory would receive a configured version, the build stops and asks you to move or delete it.

## Next Steps

With versioned documentation configured, your readers can always find docs that match the release they're using. Add a `versions` list to your `great-docs.yml` and run `great-docs build` to get started.

- [Enable Multi-Version Documentation](../recipes/enable-multi-version-docs.qmd) is a hands-on recipe for setting up versioning
- [Use Version Fences and Badges](../recipes/use-version-fences-and-badges.qmd) covers annotating content with version-specific callouts
- [Deployment](deployment.qmd) covers publishing versioned sites to GitHub Pages
- [Configuration](configuration.qmd) covers all `great-docs.yml` options including version settings



## Site Content

# Table Previews

Documentation sites for data-oriented packages often need to show what a dataset looks like.
Screenshots go stale, raw HTML tables lack context, and notebook-style output is tightly coupled to
a specific runtime. The `tbl_preview()` function solves this by generating a self-contained HTML
table preview from almost any data source. It works in Python code cells, Jupyter notebooks, and
(via the `{{{< tbl-preview >}}}` shortcode) directly in Quarto `.qmd` pages without writing any
Python at all.

Each preview includes a colored type badge (Polars, Pandas, CSV, Parquet, etc.), compact dtype
labels beneath every column header, row-number gutters, head/tail splitting for large tables, and
automatic highlighting of missing values. The output renders identically in light mode and dark
mode, requires no JavaScript, and is safe to embed in RSS feeds, emails, or static HTML.

This guide walks through every feature, starting from the simplest Python call and building up to
the Quarto shortcode, file format support, and advanced display options. For interactive tables with
sorting, filtering, and pagination, see the companion [Table Explorer](31-table-explorer.qmd) guide.

## Quick Start

The fastest way to preview a table is to pass a Python dictionary to `tbl_preview()`. No
configuration or file is needed.

```{python}
from great_docs import tbl_preview

tbl_preview({
    "city": ["Tokyo", "Paris", "New York"],
    "country": ["Japan", "France", "USA"],
    "population": [13960000, 2161000, 8336000],
})
```

The result is a styled HTML table with a header banner showing the row and column count, dtype
labels beneath each column name, and row numbers on the left. This single function call is all it
takes to go from raw data to a polished preview.

:::{.callout-tip}
## Hiding the Code Cell

Most of the time you'll want to show just the table itself, not the underlying generation code. Add
`#| echo: false` at the top of the code cell to hide the source and display only the rendered
preview:

````markdown
```{{python}}
#| echo: false
tbl_preview({"city": ["Tokyo", "Paris"], "country": ["Japan", "France"]})
```
````
:::

## Data Sources

`tbl_preview()` accepts many different input types, so you can pass whatever data structure your
project already uses. Each source type gets a distinct colored badge in the header banner, making it
easy to tell at a glance what kind of data is being displayed.

### Dictionaries and Lists

The simplest inputs are column-oriented dictionaries and row-oriented lists of dictionaries. Both
produce a **Table** badge and infer dtypes from the cell values.

A column-oriented dictionary (keys are column names, values are lists):

```{python}
tbl_preview({"name": ["Alice", "Bob"], "score": [95.5, 82.0]})
```

A list of row dictionaries (each dict is one row):

```{python}
tbl_preview([
    {"name": "Alice", "score": 95.5},
    {"name": "Bob", "score": 82.0},
])
```

Both styles produce identical output. Use whichever matches the data you already have.

### Polars DataFrames

If Polars is installed, pass a `pl.DataFrame` directly. The badge shows **Polars** in blue, and
dtype labels are derived from the Polars schema (e.g., `i64`, `f64`, `str`).

```{python}
import polars as pl

df = pl.DataFrame({
    "product": ["Widget", "Gadget", "Gizmo"],
    "price": [29.99, 49.50, 12.00],
    "in_stock": [True, False, True],
})

tbl_preview(df)
```

Polars dtypes are mapped to compact short labels (like `i64` for `Int64`, `f64` for `Float64`, `str`
for `String`) so the column headers stay clean.

### Pandas DataFrames

Pandas DataFrames work the same way. The badge shows **Pandas** in dark purple, and dtypes come from
the Pandas `.dtypes` attribute.

```{python}
import pandas as pd

df = pd.DataFrame({
    "city": ["London", "Sydney", "Toronto"],
    "temp_c": [15.2, 22.8, -3.1],
    "sunny": [False, True, False],
})

tbl_preview(df)
```

Both Polars and Pandas DataFrames are detected automatically (no format flag is needed).

### CSV Files

Pass a file path (as a string or `pathlib.Path`) to any supported format and `tbl_preview()` reads
it directly. CSV files get a warm yellow **CSV** badge:

```{python}
tbl_preview("../assets/data/students.csv")
```

The file is read using Polars if available, falling back to Pandas. Column dtypes are inferred from
the file contents.

### TSV Files

Tab-separated files (`.tsv` or `.tab`) are auto-detected by extension. The badge shows **TSV** in
green:

```{python}
tbl_preview("../assets/data/products.tsv")
```

TSV support uses the same reader as CSV with the delimiter set to tab, so all the same options
(column subsets, head/tail, etc.) apply.

### JSONL Files

Newline-delimited JSON files (`.jsonl` or `.ndjson`) are read line by line. Each line must be a
valid JSON object. The badge shows **JSONL** in light blue:

```{python}
tbl_preview("../assets/data/server_logs.jsonl", show_all=True)
```

JSONL is a common format for log data and streaming pipelines, making `tbl_preview()` a convenient
way to inspect log files in documentation.

### Parquet Files

Apache Parquet files (`.parquet` or `.pq`) are read via Polars or PyArrow. The badge shows
**Parquet** in purple:

```{python}
tbl_preview("../assets/data/products.parquet", show_all=True)
```

Parquet preserves the original column types from the file schema, so dtype labels are precise (e.g.,
`f64` rather than a generic `float`).

### Feather and Arrow IPC Files

Feather files (`.feather`) and Arrow IPC files (`.arrow`, `.ipc`) are both read as Arrow IPC format.
Feather files get a **Feather** badge in orange, while `.arrow`/`.ipc` files get an **Arrow** badge
in indigo:

```{python}
tbl_preview("../assets/data/employees.feather", show_all=True)
```

Arrow IPC is the recommended format for fast local reads when you need to preserve exact column
types.

### PyArrow Tables

If you're working with PyArrow directly, pass a `pyarrow.Table` without writing to disk. The badge
shows **Arrow** in indigo:

```{python}
import pyarrow as pa

table = pa.table({
    "sensor": ["A1", "A2", "B1"],
    "reading": [23.5, 19.8, 31.2],
    "active": [True, True, False],
})

tbl_preview(table)
```

PyArrow's type system is fully supported, including nested types like `list<int64>` and `struct`
which are displayed with their Arrow type names.

### Supported File Extensions

The full mapping of file extensions to format types is:

| Extension | Format | Badge |
|-----------|--------|-------|
| `.csv` | CSV | CSV |
| `.tsv`, `.tab` | TSV | TSV |
| `.jsonl`, `.ndjson` | JSONL | JSONL |
| `.parquet`, `.pq` | Parquet | Parquet |
| `.feather` | Feather | Feather |
| `.arrow`, `.ipc` | Arrow IPC | Arrow |

Any unrecognized extension defaults to CSV parsing.

## Head and Tail Splitting

Large tables are automatically split into a head and tail section, connected by a visual divider
row. This gives readers a sense of both the beginning and end of the data without rendering
thousands of rows.

### Default Split

By default, the first 5 rows and last 5 rows are shown:

```{python}
import polars as pl

df = pl.DataFrame({
    "id": list(range(1, 21)),
    "value": [x * 1.1 for x in range(1, 21)],
    "label": [f"item-{i}" for i in range(1, 21)],
})

tbl_preview(df)
```

The divider row between head and tail is a thin colored line that visually separates the two
sections while keeping the table compact.

### Custom Split

Adjust the `n_head` and `n_tail` parameters to control how many rows appear in each section:

```{python}
tbl_preview(df, n_head=3, n_tail=2)
```

Setting `n_tail=0` shows only the head, which is useful when the start of the data is most relevant:

```{python}
tbl_preview(df, n_head=8, n_tail=0)
```

The `limit` parameter (default 50) caps the maximum sum of `n_head + n_tail`. If you need a larger
split, increase the limit explicitly.

### Show All Rows

For small tables where every row matters, set `show_all=True` to disable the head/tail split
entirely:

```{python}
tbl_preview(
    {"name": ["Alice", "Bob", "Charlie"], "score": [95, 82, 71]},
    show_all=True,
)
```

When `show_all=True` is set, the divider row is omitted and all rows are displayed in sequence. Use
this for tables with fewer than ~50 rows where the full picture is important.

## Column Selection

By default, all columns are shown. The `columns` parameter lets you pick a subset, which is useful
for wide tables where only a few columns are relevant to the discussion.

```{python}
tbl_preview(
    "../assets/data/students.csv",
    columns=["name", "score", "grade"],
    show_all=True,
)
```

Columns appear in the order you specify, so you can also use this to reorder columns. If a column
name doesn't exist in the data, a `ValueError` is raised with a helpful message listing the
available columns.

## Missing Values

Missing values (`None`, `NaN`, `NA`, `Inf`, `-Inf`) are highlighted with a red background and text
by default. This makes it easy to spot gaps in the data at a glance.

```{python}
import math

tbl_preview({
    "sensor": ["A1", "A2", "A3", "B1"],
    "reading": [23.5, None, math.nan, 31.2],
    "status": ["ok", "offline", None, "ok"],
}, show_all=True)
```

The cell text shows a representation of the missing value (`None`, `NaN`, `NA`, `Inf`), and the cell
background turns light red to draw attention.

To disable missing-value highlighting (for example, if your data intentionally contains `None` as a
meaningful value), set `highlight_missing=False`:

```{python}
tbl_preview({
    "sensor": ["A1", "A2", "A3"],
    "reading": [23.5, None, 31.2],
}, show_all=True, highlight_missing=False)
```

With highlighting off, missing values still display their text representation but use the normal
cell styling.

## Display Options

Every visual element of the preview table can be toggled on or off independently. This lets you
create anything from a fully-featured data preview to a minimal, stripped-down table.

### Captions

Add a descriptive caption that appears below the header banner and above the column labels:

```{python}
tbl_preview(
    {"city": ["Tokyo", "Paris", "New York"], "population": [13960000, 2161000, 8336000]},
    show_all=True,
    caption="World cities by population (2024 estimates)",
)
```

Captions are useful when multiple previews appear on the same page, giving each table a distinct
label.

### Row Numbers

Row numbers appear in a left-hand gutter by default, starting from 0 to match Python, Polars, and
Pandas 0-based indexing. They reflect the original row positions, even when head/tail splitting is
active. To hide them:

```{python}
tbl_preview(
    {"x": [1, 2, 3], "y": [4, 5, 6]},
    show_all=True,
    show_row_numbers=False,
)
```

Hiding row numbers is useful for small reference tables where the row position isn't meaningful.

### Row Index Offset

If you prefer 1-based numbering (or any other starting value), set `row_index_offset`:

```{python}
tbl_preview(
    {"x": [1, 2, 3], "y": [4, 5, 6]},
    show_all=True,
    row_index_offset=1,
)
```

The offset applies to all rows, including tail rows in head/tail splits. The default of `0` keeps
row numbers consistent with what you see when inspecting a DataFrame in Python.

### Dtype Labels

Compact dtype labels appear beneath each column name (e.g., `str`, `i64`, `f64`). To hide them:

```{python}
tbl_preview(
    {"name": ["Alice", "Bob"], "score": [95.5, 82.0]},
    show_all=True,
    show_dtypes=False,
)
```

Hiding dtype labels produces a cleaner look when the column types are obvious from context or not
relevant to the reader.

### Dimensions Banner

The header banner shows the table type badge, row count, and column count. To hide it:

```{python}
tbl_preview(
    {"x": [1, 2, 3], "y": [4, 5, 6]},
    show_all=True,
    show_dimensions=False,
)
```

Hiding the dimensions banner is useful when the surrounding text already describes the data size.

### Minimal Chrome

Combine the toggle options to create a stripped-down table with no row numbers, no dtypes, and no
dimensions (just the data):

```{python}
tbl_preview(
    {"name": ["Alice", "Bob", "Charlie"], "score": [95, 82, 71]},
    show_all=True,
    show_row_numbers=False,
    show_dtypes=False,
    show_dimensions=False,
)
```

This minimal style works well for small inline reference tables where the chrome would be
distracting.

### Column Width Control

The `max_col_width` parameter caps the pixel width of any single column. Long cell values are
truncated with an ellipsis. The default is 250px.

```{python}
tbl_preview({
    "description": [
        "This is a very long description that would normally extend the column width quite far",
        "Another lengthy entry with lots of detail about the item in question",
        "Short one",
    ],
    "code": ["ABC-001", "DEF-002", "GHI-003"],
}, show_all=True, max_col_width=150)
```

The `min_tbl_width` parameter sets a floor for the total table width (default 500px), ensuring that
narrow tables don't collapse to an unreadably small size.

Both width parameters accept integer values in pixels.

## Quarto Shortcode

The `{{{< tbl-preview >}}}` shortcode renders a table preview directly in a `.qmd` page without
writing any Python code. Point it at a data file and the shortcode handles everything.

### Basic Usage

The simplest invocation needs only the `file` parameter:

````markdown
{{{< tbl-preview file="assets/data.csv" >}}}
````

The shortcode resolves the file path relative to the Quarto project root, reads the data, and
inserts the preview HTML at render time. No code cell or Python import is needed.

### Adding Options

All the display options available to the Python function are also available as shortcode parameters:

````markdown
{{{< tbl-preview file="assets/data.csv" show_all="true" caption="My Dataset" >}}}
````

````markdown
{{{< tbl-preview file="data.tsv" n_head="3" n_tail="2" show_row_numbers="false" >}}}
````

````markdown
{{{< tbl-preview file="logs.jsonl" show_all="true" max_col_width="120" >}}}
````

Note that shortcode parameters are always strings, so boolean values must be quoted (`"true"` /
`"false"`) and numeric values must be quoted (`"10"`, `"150"`).

### Column Subsets

To show only specific columns, pass a comma-separated list to the `columns` parameter:

````markdown
{{{< tbl-preview file="assets/students.csv" columns="name,score,grade" show_all="true" >}}}
````

Columns appear in the order listed.

### Supported Parameters

The full set of shortcode parameters mirrors the Python function:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file` | string | — | Path to data file (required, relative to project root) |
| `columns` | string | all | Comma-separated column names to display |
| `n_head` | string | `"5"` | Number of rows from the start |
| `n_tail` | string | `"5"` | Number of rows from the end |
| `show_all` | string | `"false"` | Show all rows (ignores head/tail) |
| `show_row_numbers` | string | `"true"` | Show row-number gutter |
| `show_dtypes` | string | `"true"` | Show dtype labels under column names |
| `show_dimensions` | string | `"true"` | Show header banner with row/column counts |
| `max_col_width` | string | `"250"` | Maximum column width in pixels |
| `min_tbl_width` | string | `"500"` | Minimum total table width in pixels |
| `caption` | string | — | Caption text below the header banner |
| `row_index_offset` | string | `"0"` | Starting row number (use `"1"` for 1-based) |

The shortcode supports every file format listed in the
[Supported File Extensions](#supported-file-extensions) table.

## Notebook Integration

In Jupyter notebooks and Quarto `.qmd` documents with Python code cells, you can enable automatic
`tbl_preview()` rendering for all DataFrames using the display hook.

### Enable Auto-Preview

Call `enable_tbl_preview()` once at the top of a notebook, and every Polars or Pandas DataFrame
displayed afterward will render as a preview table instead of the library's default HTML:

```python
import great_docs as gd

gd.enable_tbl_preview(n_head=8, n_tail=3)

# Now any DataFrame as the last expression in a cell
# renders as a tbl_preview() table automatically:
import pandas as pd
pd.read_csv("data.csv")  # → preview table
```

Keyword arguments passed to `enable_tbl_preview()` are forwarded to `tbl_preview()`, so you can set
defaults for the entire notebook in one call.

### Disable Auto-Preview

To restore the default DataFrame display, call `disable_tbl_preview()`:

```python
gd.disable_tbl_preview()
```

This removes the formatter and returns to the library's built-in HTML rendering.

## Parameters Reference

The table below lists every parameter available on the `tbl_preview()` function. All parameters
except `data` are optional.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | various | — | Data source: DataFrame, file path, dict, or list of dicts |
| `columns` | `list[str]` | `None` | Column names to display (all if `None`) |
| `n_head` | `int` | `5` | Rows from the start |
| `n_tail` | `int` | `5` | Rows from the end |
| `limit` | `int` | `50` | Maximum allowed `n_head + n_tail` |
| `show_all` | `bool` | `False` | Show all rows |
| `show_row_numbers` | `bool` | `True` | Show row-number gutter |
| `show_dtypes` | `bool` | `True` | Show dtype labels |
| `show_dimensions` | `bool` | `True` | Show header banner |
| `max_col_width` | `int` | `250` | Maximum column width (px) |
| `min_tbl_width` | `int` | `500` | Minimum table width (px) |
| `caption` | `str` | `None` | Caption text |
| `highlight_missing` | `bool` | `True` | Highlight missing values |
| `row_index_offset` | `int` | `0` | Starting row number (0-based by default) |
| `id` | `str` | auto | Custom HTML `id` for the container |

The return value is a `TblPreview` object with `_repr_html_()` (for notebook display), `as_html()`
(returns the HTML string), and `save(path)` (writes HTML to a file) methods.

## Next Steps

Table previews give readers a quick look at a dataset's structure and content without loading the
full table. Use them in docstring examples, user guides, or anywhere you want to show data at a
glance.

- [Table Explorer](table-explorer.qmd) adds interactive filtering, sorting, and pagination for
larger datasets
- [Scale-to-Fit](scale-to-fit.qmd) keeps wide tables readable on narrow screens
- [Writing Docstrings](writing-docstrings.qmd) covers embedding table previews in executable
docstring examples


# Table Explorer

The `tbl_explorer()` function generates an interactive table widget from tabular data. Where
[`tbl_preview()`](30-table-previews.qmd) produces a static, JavaScript-free snapshot of a dataset,
`tbl_explorer()` embeds all rows as inline JSON and progressively enhances a static fallback table
with interactive controls: sorting, token-based filtering, pagination, column toggling,
copy-to-clipboard, and CSV download.

Like `tbl_preview()`, `tbl_explorer()` accepts any tabular data source—Polars/Pandas DataFrames,
PyArrow Tables, CSV/TSV/JSONL/Parquet/Feather files, column-oriented dicts, or row-oriented lists of
dicts. The output is a self-contained HTML block that works in Python code cells, Jupyter notebooks,
and (via the `{{{< tbl-explorer >}}}` shortcode) directly in Quarto `.qmd` pages.

::: {.callout-note}
For datasets larger than 10,000 rows, `tbl_explorer()` emits a warning because all data is embedded
as JSON, which increases page weight. For very large datasets, consider using `tbl_preview()` with
`n_head`/`n_tail` splitting instead.
:::

```{python}
#| echo: false
#| output: false
from great_docs import tbl_explorer
```

## Basic Usage

Pass any supported data source to `tbl_explorer()` to get a fully interactive table:

```{python}
from great_docs import tbl_explorer

tbl_explorer({
    "city": ["Tokyo", "Paris", "New York", "London", "Sydney"],
    "population": [13960000, 2161000, 8336000, 8982000, 5312000],
    "country": ["Japan", "France", "USA", "UK", "Australia"],
})
```

The result includes a toolbar with a filter bar, column toggle, copy, download, and reset buttons.
Column headers are sortable, and pagination appears at the bottom when the dataset exceeds the page
size.

:::{.callout-tip}
## Hiding the Code Cell

Most of the time you'll want to show just the table itself, not the underlying generation code. Add
`#| echo: false` at the top of the code cell to hide the source and display only the rendered
explorer:

````markdown
```{{python}}
#| echo: false
tbl_explorer("data/students.csv")
```
````
:::

## Sorting

Click any column header to cycle through three states: **ascending → descending → unsorted**. Sort
indicators appear as arrows next to column names.

Multi-column sorting is always active. Clicking additional columns adds them to the sort stack, with
each column sorting within the groups established by prior sort columns. For example, clicking
*department* then *salary* will group by department and sort salaries within each department. To
start over, use the reset button to clear all sort criteria.

## Token-Based Filtering

The filter system uses structured, token-based filters. Each filter is a discrete token displayed as
a blue pill in the filter bar, and all active tokens are ANDed together.

### Adding a Filter

1. Click the **+** button in the filter bar
2. Select a **column** from the dropdown—each column shows its dtype badge
3. Choose an **operator**—the available operators depend on the column's data type:

| Column type | Operators |
|-------------|-----------|
| String | contains, doesn't contain, starts with, ends with, equals, is empty, is not empty |
| Numeric | =, ≠, <, ≤, >, ≥, between |
| Boolean | is true, is false |
| All types | is null, is not null |

4. For operators that require a value, type it in the input field and press **Enter** or click
**Apply**

The *between* operator for numeric columns presents two input fields for the lower and upper bounds
of the range.

### Understanding Filter Tokens

Each token shows the column name, operator, and value. Text values appear in single quotes (e.g.,
`city contains 'york'`). Numeric values are shown unquoted (e.g., `salary > 80000`). Click the
**×** on any token to remove that individual filter.

### Case Sensitivity

Text filters are **case-insensitive** by default. When entering a filter value for a text column, an
**Aa** toggle button appears next to the input field. Click it to enable case-sensitive matching for
that specific filter. Case-sensitive tokens display a small bordered **Aa** badge on the pill.

### Combining Filters

Multiple filters are ANDed together—a row must match *all* active filters to be displayed. You can
add multiple filters on the same column (e.g., `salary > 70000` AND `salary < 100000`) or across
different columns (e.g., `department contains 'Eng'` AND `rating > 4.0`).

### Search Highlighting

When a "contains" filter is active, matching text in cells is highlighted with a colored background.
This makes it easy to spot why each row matched the filter. Disable this with
`search_highlight=False`.

## Pagination

Tables are paginated at **20 rows per page** by default. The pagination bar shows:

- the current range (e.g., "Showing 1–20 of 150 rows")
- **First**, **Previous**, **Next**, and **Last** navigation buttons
- page number buttons with ellipsis for large page counts

The row count updates to reflect any active filters (e.g., "Showing 1–5 of 5 rows (filtered from
24)").

To disable pagination and show all rows at once, set `page_size=0`:

```{python}
tbl_explorer(
    "../assets/data/students.csv",
    page_size=0,
)
```

Or set a custom page size:

```{python}
tbl_explorer(
    "../assets/data/employees.csv",
    page_size=10,
)
```

## Column Toggle

Click the **Columns** button in the toolbar to open a dropdown with checkboxes for each column.
Uncheck columns to hide them from the table; check them again to restore them. At least one column
must remain visible—the last visible column's checkbox is disabled.

This is useful for wide datasets where you want to focus on specific columns without modifying the
underlying data.

## Copy and Download

The toolbar includes two data-export buttons:

- **Copy** (clipboard icon) — copies the currently visible page of data as tab-separated values to
the clipboard. On success, the icon briefly turns into a green checkmark. The copied data includes
column headers and respects the current sort and filter state.
- **Download** (download icon) — downloads the full filtered dataset (all pages, not just the
current page) as a CSV file. The filename is based on the table's `id` attribute.

## Reset

The **Reset** button (↺ icon) restores the table to its initial state in one click, clearing all:

- Sort states
- Filter tokens
- Column visibility changes
- Pagination (returns to page 1)

## From a File

Like `tbl_preview()`, you can pass a file path directly. The file extension determines the loader:

```{python}
tbl_explorer("../assets/data/students.csv", page_size=5)
```

Supported file formats: `.csv`, `.tsv`, `.jsonl` (or `.ndjson`), `.parquet`, `.feather`, `.arrow`.

:::{.callout-tip}
## Where to Put Data Files

We recommend placing data files in an `assets/data/` directory at the root of your project. This
keeps them version-controlled, easy to reference from any `.qmd` page, and separate from images and
other static assets:

```
my-package/
├── assets/
│   └── data/
│       ├── students.csv
│       └── products.tsv
├── reference/
└── user-guide/
```

Both `tbl_explorer()` and `tbl_preview()` resolve file paths relative to the working directory,
which is typically the project root during a Quarto build.
:::

## From a DataFrame

Pass a Polars or Pandas DataFrame directly:

```{python}
import polars as pl

df = pl.DataFrame({
    "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
    "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
    "price": [29.99, 49.50, 12.00, 8.75, 199.99],
    "in_stock": [True, False, True, True, False],
    "rating": [4.5, 3.8, 4.9, 4.2, 2.1],
})

tbl_explorer(df)
```

## Column Subset

Use the `columns=` parameter to show only specific columns:

```{python}
tbl_explorer(
    "../assets/data/employees.csv",
    columns=["name", "department", "salary"],
)
```

## Quarto Shortcode

The `{{{< tbl-explorer >}}}` shortcode brings the interactive explorer to `.qmd` pages without
writing any Python. The `file=` parameter specifies the data file path relative to the `.qmd` file:

```{markdown}
{{< tbl-explorer file="data/example.csv" >}}
```

All parameters can be set as shortcode attributes:

```{markdown}
{{{< tbl-explorer file="data.csv" page_size="25" sortable="true" >}}}
{{{< tbl-explorer file="data.csv" column_toggle="false" downloadable="false" >}}}
{{{< tbl-explorer file="data.csv" columns="name,department,salary" >}}}
```

Boolean parameters accept `"true"` or `"false"` as strings. The `columns=` parameter accepts a
comma-separated list of column names.

## Minimal Chrome

You can selectively disable interactive features for a cleaner, read-only presentation. For example,
to show a sortable-only table with no toolbar controls:

```{python}
tbl_explorer(
    "../assets/data/products.tsv",
    sortable=True,
    filterable=False,
    column_toggle=False,
    copyable=False,
    downloadable=False,
    page_size=0,
)
```

## Progressive Enhancement

Interactive widgets can be fragile: if JavaScript fails to load or the page is consumed outside a
browser (RSS readers, email digests, search engine crawlers), readers see nothing. The table
explorer avoids this problem.

The `tbl_explorer()` output is designed with **progressive enhancement** in mind. The initial HTML
contains a fully rendered static table (the first page of data) that is readable without JavaScript.
When JavaScript is available, the static table is enhanced with interactive controls.

This means:

- **RSS feeds and email**: readers see a usable static table
- **Search engines**: table content is indexable
- **Accessibility**: the base table works with screen readers
- **No-JS environments**: content is still visible

Because the static fallback is a real HTML table (not a placeholder), it carries semantic structure
that assistive technology and search engines can parse directly.

## Choosing Between `tbl_preview()` and `tbl_explorer()`

Great Docs offers two table display functions that serve different purposes. Use this comparison to
decide which one fits your page:

| | `tbl_preview()` | `tbl_explorer()` |
|---|---|---|
| **Interactivity** | None (static HTML) | Sorting, filtering, pagination, column toggle |
| **JavaScript** | Not required | Required for interactivity; static fallback without it |
| **Data embedding** | Head/tail rows only | All rows as inline JSON |
| **Best for** | Quick dataset snapshots, lightweight pages | Exploratory data docs, dashboards, reference tables |
| **Large datasets** | Efficient (shows only head + tail) | All data embedded (watch page weight) |
| **Dark mode** | Full support | Full support |

In general, reach for `tbl_preview()` when you want a quick, lightweight snapshot and
`tbl_explorer()` when readers need to search, sort, or page through the data.

## Parameters Reference

All parameters for `tbl_explorer()` are listed below. Every parameter has a sensible default, so in
most cases you only need to pass the data source itself.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | various | — | Data source: DataFrame, file path, dict, or list of dicts |
| `columns` | `list[str]` | `None` | Column subset to display (all if `None`) |
| `show_row_numbers` | `bool` | `True` | Show row-number gutter column |
| `show_dtypes` | `bool` | `True` | Show dtype labels under column names |
| `show_dimensions` | `bool` | `True` | Show header banner with type badge and counts |
| `max_col_width` | `int` | `250` | Maximum column width in pixels |
| `min_tbl_width` | `int` | `500` | Minimum total table width in pixels |
| `caption` | `str` | `None` | Caption text above column headers |
| `highlight_missing` | `bool` | `True` | Highlight `None`/`NaN`/`NA` in red |
| `page_size` | `int` | `20` | Rows per page (`0` to disable pagination) |
| `sortable` | `bool` | `True` | Enable click-to-sort on column headers |
| `filterable` | `bool` | `True` | Enable the token-based filter bar |
| `column_toggle` | `bool` | `True` | Enable column visibility dropdown |
| `copyable` | `bool` | `True` | Enable copy-to-clipboard button |
| `downloadable` | `bool` | `True` | Enable CSV download button |
| `resizable` | `bool` | `False` | Enable column drag-resize (reserved for future use) |
| `sticky_header` | `bool` | `True` | Make column headers sticky on vertical scroll |
| `search_highlight` | `bool` | `True` | Highlight matching text for "contains" filters |
| `id` | `str` | auto | Custom HTML `id` for the container |

The return value is a `TblExplorer` object with `_repr_html_()` (for notebook display), `as_html()`
(returns the HTML string), and `save(path)` (writes HTML to a file) methods.

## Next Steps

The table explorer turns static data tables into interactive views with filtering, sorting,
pagination, and CSV export. Use it when readers need to search through larger datasets or compare
specific rows.

- [Table Previews](table-previews.qmd) covers a lighter-weight table display for quick data
summaries
- [Scale-to-Fit](scale-to-fit.qmd) keeps wide tables readable on narrow screens
- [Configuration](configuration.qmd) covers all `great-docs.yml` options


# Horizontal Rules

Markdown's `---` gives you a plain horizontal rule, but documentation sites often need something
more expressive. Examples might include: a chapter divider, a gradient accent that matches your
navbar, a decorative ornament between sections, or a labeled break that tells readers "Part Two
starts here."

The `{{{< hr >}}}` shortcode turns the humble `<hr>` into a flexible design tool. It supports four
line styles, eight palette colors (plus any custom CSS color), adjustable thickness and width, text
labels embedded in the rule, and nine ready-made presets.

## Quick Start

Drop a shortcode into any `.qmd` page to get a styled rule:

````markdown
{{{< hr >}}}
````

{{< hr >}}

That gives you a 2px solid line at full width. To make it more interesting:

````markdown
{{{< hr preset="gradient-shimmer" >}}}
````

{{< hr preset="gradient-shimmer" >}}

## Line Styles

Four border styles are available via the `style` parameter:

````markdown
{{{< hr style="solid" >}}}
{{{< hr style="dashed" >}}}
{{{< hr style="dotted" >}}}
{{{< hr style="double" >}}}
````

**Solid** (default):

{{< hr style="solid" >}}

**Dashed:**

{{< hr style="dashed" >}}

**Dotted:**

{{< hr style="dotted" >}}

**Double:**

{{< hr style="double" >}}

## Colors

### Palette Colors

Great Docs ships with eight gradient palette presets. Each one maps to a distinct color that adapts
to dark mode automatically:

| Name | Light | Dark | Example |
|------|-------|------|---------|
| `sky` | Deep blue | Bright sky | {{< hr color="sky" >}} |
| `peach` | Warm orange | Soft peach | {{< hr color="peach" >}} |
| `prism` | Rich purple | Soft violet | {{< hr color="prism" >}} |
| `lilac` | Bright lilac | Light purple | {{< hr color="lilac" >}} |
| `slate` | Cool gray | Light slate | {{< hr color="slate" >}} |
| `honey` | Golden amber | Bright gold | {{< hr color="honey" >}} |
| `dusk` | Indigo | Soft indigo | {{< hr color="dusk" >}} |
| `mint` | Teal | Bright mint | {{< hr color="mint" >}} |

### Custom Colors

Any CSS color value works (hex codes, named colors, `rgb()`, or `hsl()`):

````markdown
{{{< hr color="#e11d48" >}}}
{{{< hr color="#16a34a" >}}}
{{{< hr color="#2563eb" >}}}
````

{{< hr color="#e11d48" >}}

{{< hr color="#16a34a" >}}

{{< hr color="#2563eb" >}}

### Colored Line Styles

Colors combine naturally with line styles:

````markdown
{{{< hr style="dashed" color="#e11d48" >}}}
{{{< hr style="dotted" color="#2563eb" >}}}
````

{{< hr style="dashed" color="#e11d48" >}}

{{< hr style="dotted" color="#2563eb" >}}

## Thickness

Control the line weight with named values or exact pixel sizes:

| Value | Pixels |
|-------|--------|
| `thin` | 1px |
| `medium` | 2px (default) |
| `thick` | 4px |

````markdown
{{{< hr thickness="thin" >}}}
{{{< hr >}}}
{{{< hr thickness="thick" >}}}
{{{< hr thickness="6px" >}}}
````

{{< hr thickness="thin" >}}

{{< hr >}}

{{< hr thickness="thick" >}}

{{< hr thickness="6px" >}}

## Width and Alignment

By default, rules span the full container width. Use `width` to make them narrower, and `align` to
position them when they don't fill the container:

````markdown
{{{< hr width="75%" >}}}
{{{< hr width="50%" align="center" >}}}
{{{< hr width="50%" align="left" >}}}
{{{< hr width="50%" align="right" >}}}
````

{{< hr width="75%" >}}

{{< hr width="50%" align="center" >}}

{{< hr width="50%" align="left" >}}

{{< hr width="50%" align="right" >}}

The `width` parameter accepts any CSS length or percentage. Use `full` as a shorthand for `100%`.

## Spacing

Control the vertical margin around the rule with the `spacing` parameter:

| Value | Margin |
|-------|--------|
| `compact` | 1rem |
| `normal` | 2rem (default) |
| `spacious` | 4rem |

````markdown
{{{< hr spacing="compact" >}}}
{{{< hr spacing="spacious" >}}}
````

**Compact** (`1rem`):

This is some text before the rule.

{{< hr spacing="compact" >}}

This is some text after the rule. Notice the tight spacing above and below.

**Normal** (`2rem`, default):

This is some text before the rule.

{{< hr spacing="normal" >}}

This is some text after the rule. This is the default amount of breathing room.

**Spacious** (`4rem`):

This is some text before the rule.

{{< hr spacing="spacious" >}}

This is some text after the rule. The extra whitespace creates a clear section break.

## Embedded Text

Place text or symbols in the center of a rule. The rule splits into two lines flanking the text:

````markdown
{{{< hr text="§" >}}}
{{{< hr text="Continue Reading" >}}}
{{{< hr text="★ ★ ★" >}}}
````

{{< hr text="§" >}}

{{< hr text="Continue Reading" >}}

{{< hr text="★ ★ ★" >}}

### Text Size

The sizes `sm`, `md` (default), and `lg` are available:

````markdown
{{{< hr text="Small" text-size="sm" >}}}
{{{< hr text="Medium" >}}}
{{{< hr text="Large" text-size="lg" >}}}
````

{{< hr text="Small" text-size="sm" >}}

{{< hr text="Medium" >}}

{{< hr text="Large" text-size="lg" >}}

### Colored Text

Add `text-color` to style the label independently from the line, or use `color` to tint both at once:

````markdown
{{{< hr text="Warning" color="#e11d48" text-color="#e11d48" >}}}
{{{< hr text="Chapter One" color="#6366f1" >}}}
````

{{< hr text="Warning" color="#e11d48" text-color="#e11d48" >}}

{{< hr text="Chapter One" color="#6366f1" >}}

### Text with Width

Text rules respect `width` and `align`:

````markdown
{{{< hr text="Centered" width="70%" >}}}
{{{< hr text="Left" width="60%" align="left" >}}}
````

{{< hr text="Centered" width="70%" >}}

{{< hr text="Left" width="60%" align="left" >}}

## Presets

Presets are ready-made visual styles that go beyond what `style` and `color` can achieve. Use
`preset` to apply one:

### Gradient Shimmer

We can get a horizontal rule that animates with a gradient. It shimmers smoothly:

````markdown
{{{< hr preset="gradient-shimmer" >}}}
````

{{< hr preset="gradient-shimmer" >}}

::: {.callout-note}
The shimmer animation respects `prefers-reduced-motion`. Users who prefer reduced motion will see a
static gradient instead.
:::

### Gradient Static

The same gradient palette without animation:

````markdown
{{{< hr preset="gradient-static" >}}}
````

{{< hr preset="gradient-static" >}}

### Fade

Full opacity at center, fading to transparent at both edges:

````markdown
{{{< hr preset="fade" >}}}
````

{{< hr preset="fade" >}}

### Fade Edges

Transparent edges blooming into a colored center:

````markdown
{{{< hr preset="fade-edges" >}}}
````

{{< hr preset="fade-edges" >}}

### Dots

Three centered dots form a classic section break (with no line):

````markdown
{{{< hr preset="dots" >}}}
````

{{< hr preset="dots" >}}

### Diamond

A diamond ornament flanked by fading lines:

````markdown
{{{< hr preset="diamond" >}}}
````

{{< hr preset="diamond" >}}

### Ornament

An elegant fleuron (❧) between fading lines:

````markdown
{{{< hr preset="ornament" >}}}
````

{{< hr preset="ornament" >}}

### Wave

A subtle repeating diagonal pattern:

````markdown
{{{< hr preset="wave" >}}}
````

{{< hr preset="wave" >}}

### Double Line

Two parallel thin lines with a gap between them:

````markdown
{{{< hr preset="double-line" >}}}
````

{{< hr preset="double-line" >}}

## Combining Options

Presets define the visual pattern, but `width`, `align`, `spacing`, and `color` can still be
overridden on top:

````markdown
{{{< hr preset="gradient-shimmer" width="60%" >}}}
{{{< hr preset="fade" width="50%" spacing="spacious" >}}}
{{{< hr preset="dots" color="#e11d48" >}}}
{{{< hr preset="ornament" width="60%" spacing="spacious" >}}}
````

{{< hr preset="gradient-shimmer" width="60%" >}}

{{< hr preset="fade" width="50%" spacing="spacious" >}}

{{< hr preset="dots" color="#e11d48" >}}

{{< hr preset="ornament" width="60%" spacing="spacious" >}}

Style, color, and sizing options also combine freely:

````markdown
{{{< hr style="dashed" color="peach" width="75%" thickness="thick" >}}}
{{{< hr style="dotted" color="#2563eb" width="40%" thickness="thin" align="right" >}}}
````

{{< hr style="dashed" color="peach" width="75%" thickness="thick" >}}

{{< hr style="dotted" color="#2563eb" width="40%" thickness="thin" align="right" >}}

## Real-World Patterns

Here are some common documentation patterns and how to achieve them:

**Blog-style section break:**

````markdown
{{{< hr preset="dots" spacing="spacious" >}}}
````

{{< hr preset="dots" spacing="spacious" >}}

**Chapter divider with label:**

````markdown
{{{< hr text="Chapter Two" color="#6366f1" thickness="thick" width="80%" >}}}
````

{{< hr text="Chapter Two" color="#6366f1" thickness="thick" width="80%" >}}

**Elegant page separator:**

````markdown
{{{< hr preset="ornament" width="60%" spacing="spacious" >}}}
````

{{< hr preset="ornament" width="60%" spacing="spacious" >}}

**API section boundary:**

````markdown
{{{< hr preset="gradient-shimmer" >}}}
````

{{< hr preset="gradient-shimmer" >}}

**Light decorative pause:**

````markdown
{{{< hr preset="fade" thickness="thin" width="50%" >}}}
````

{{< hr preset="fade" thickness="thin" width="50%" >}}

## Parameter Reference

| Parameter | Values | Default | Description |
|-----------|--------|---------|-------------|
| `style` | `solid`, `dashed`, `dotted`, `double` | `solid` | Line style |
| `color` | Palette name, hex, CSS color | Site accent | Line color |
| `thickness` | `thin`, `medium`, `thick`, or CSS value | `medium` (2px) | Line weight |
| `width` | `full`, percentage, or CSS length | `100%` | Horizontal extent |
| `align` | `center`, `left`, `right` | `center` | Position when width < 100% |
| `spacing` | `compact`, `normal`, `spacious` | `normal` (2rem) | Vertical margin |
| `text` | Any string | — | Text centered on the rule |
| `text-size` | `sm`, `md`, `lg` | `md` | Size of embedded text |
| `text-color` | Hex or CSS color | Inherits `color` | Text label color |
| `preset` | See [Presets](#presets) | — | Ready-made visual style |

## Dark Mode

All colors adapt automatically in dark mode. Palette colors switch to brighter variants for
visibility on dark backgrounds, and the overall opacity is reduced slightly for a softer look.
Custom hex colors are preserved as-is but receive a subtle opacity adjustment.

No extra configuration is needed as the shortcode works identically in both modes.

## Next Steps

Horizontal rules provide visual separation between sections of content. The shortcode gives you
control over style, color, thickness, and spacing, with presets for common patterns.

- [Theming & Appearance](theming.qmd) covers the broader visual customization options
- [Authoring QMD Files](authoring-qmd-files.qmd) covers other content building blocks like callouts
and tabsets
- [Keyboard Keys](keyboard-keys.qmd) covers another visual shortcode for rendering key-cap styled
shortcuts


# Keyboard Keys

Documentation often needs to show keyboard shortcuts: "press {{< keys shortcut="Ctrl+S" >}} to
save" or "hit {{< keys "Esc" >}} to close the dialog". The `{{{< keys >}}}` shortcode renders these
as styled key caps with a subtle 3D border effect, monospace font, and automatic dark-mode support.

It handles single keys, multi-key combos, and platform-aware rendering so that macOS readers see
`⌘` while Windows readers see `Ctrl`.

## Quick Start

Wrap a key name in the shortcode to render a styled key cap:

````markdown
Press {{{< keys "Esc" >}}} to close.
````

Press {{< keys "Esc" >}} to close.

For a multi-key shortcut, use the `shortcut` parameter. Keys are split on `+` automatically:

````markdown
{{{< keys shortcut="Ctrl+Shift+P" >}}}
````

{{< keys shortcut="Ctrl+Shift+P" >}}

## Single Keys

The simplest usage is a single key name passed as a positional argument. This works for any key
you might find on a keyboard: letters, numbers, function keys, navigation keys, and modifiers.

````markdown
{{{< keys "Enter" >}}}
{{{< keys "Tab" >}}}
{{{< keys "Space" >}}}
{{{< keys "F5" >}}}
{{{< keys "A" >}}}
````

{{< keys "Enter" >}} {{< keys "Tab" >}} {{< keys "Space" >}} {{< keys "F5" >}} {{< keys "A" >}}

Modifier keys render just like regular keys:

{{< keys "Ctrl" >}} {{< keys "Shift" >}} {{< keys "Alt" >}}

All keys share the same visual style: a rounded border, subtle shadow, and monospace font that
mimics the appearance of physical key caps.

## Shortcut Combos

Most keyboard shortcuts involve pressing multiple keys together. The `shortcut` parameter accepts a
string like `"Ctrl+Shift+P"`, splits it on `+`, and renders each key with a `+` separator between
them:

````markdown
{{{< keys shortcut="Ctrl+C" >}}}
{{{< keys shortcut="Ctrl+Shift+P" >}}}
{{{< keys shortcut="Alt+F4" >}}}
````

{{< keys shortcut="Ctrl+C" >}}

{{< keys shortcut="Ctrl+Shift+P" >}}

{{< keys shortcut="Alt+F4" >}}

| Action | Shortcut |
|--------|----------|
| Copy | {{< keys shortcut="Ctrl+C" >}} |
| Paste | {{< keys shortcut="Ctrl+V" >}} |
| Undo | {{< keys shortcut="Ctrl+Z" >}} |
| Save | {{< keys shortcut="Ctrl+S" >}} |
| Find | {{< keys shortcut="Ctrl+F" >}} |
| Command palette | {{< keys shortcut="Ctrl+Shift+P" >}} |

You can also build combos manually by placing individual keys next to each other:

````markdown
{{{< keys "Ctrl" >}}}+{{{< keys "Shift" >}}}+{{{< keys "P" >}}}
````

{{< keys "Ctrl" >}}+{{< keys "Shift" >}}+{{< keys "P" >}}

Both approaches are valid. Use `shortcut=` for convenience, or manual placement when you want
different separators or spacing between keys.

## Platform-Aware Rendering

Different operating systems use different key names. macOS has Command (⌘) and Option (⌥), while
Windows uses Ctrl and Alt. The `platform` parameter translates key names so you can write
platform-specific documentation without hard-coding symbols.

### macOS

With `platform="mac"`, standard modifier names are replaced with their macOS symbol equivalents.
This is useful when writing documentation targeted at macOS users:

| Key name | macOS symbol |
|----------|-------------|
| Ctrl | {{< keys "Ctrl" platform="mac" >}} (⌃) |
| Cmd / Command | {{< keys "Cmd" platform="mac" >}} (⌘) |
| Alt / Option | {{< keys "Alt" platform="mac" >}} (⌥) |
| Shift | {{< keys "Shift" platform="mac" >}} (⇧) |
| Up / Down / Left / Right | {{< keys "Up" platform="mac" >}} {{< keys "Down" platform="mac" >}} {{< keys "Left" platform="mac" >}} {{< keys "Right" platform="mac" >}} (▲▼◀▶) |

A full shortcut with macOS rendering:

````markdown
{{{< keys shortcut="Cmd+Shift+P" platform="mac" >}}}
````

{{< keys shortcut="Cmd+Shift+P" platform="mac" >}}

The symbols are compact and universally recognized by macOS users, making them ideal for
application-specific documentation.

### Windows

With `platform="win"`, macOS-specific key names are translated to their Windows equivalents. This
lets you write a single shortcode and render it appropriately for Windows readers:

| macOS key | Windows key |
|-----------|------------|
| Cmd | {{< keys "Cmd" platform="win" >}} (Ctrl) |
| Option | {{< keys "Option" platform="win" >}} (Alt) |

````markdown
{{{< keys shortcut="Cmd+S" platform="win" >}}}
````

{{< keys shortcut="Cmd+S" platform="win" >}}

Keys that have no platform-specific equivalent (like letter keys and function keys) pass through
unchanged.

### Default (No Platform)

Without a `platform` parameter, key names are rendered exactly as written. This is the right choice
when your audience uses multiple platforms or when the shortcut is platform-neutral:

{{< keys shortcut="Ctrl+Shift+P" >}}

For most documentation, leaving `platform` unset is the simplest and most portable option.

## In Context

Keyboard keys work naturally in all common documentation contexts. The examples below show how
`{{{< keys >}}}` integrates with prose, lists, callouts, and blockquotes.

### Inline Prose

Keys blend seamlessly into running text without disrupting the reading flow:

To save your work, press {{< keys shortcut="Ctrl+S" >}}. If you need to undo, reach for
{{< keys shortcut="Ctrl+Z" >}}. For more advanced operations, open the command palette with
{{< keys shortcut="Ctrl+Shift+P" >}}.

This pattern works well in tutorials where you walk readers through a series of actions.

### Lists

Shortcuts pair naturally with list items. Place the key combo first, followed by a description:

- {{< keys shortcut="Ctrl+C" >}} Copy
- {{< keys shortcut="Ctrl+V" >}} Paste
- {{< keys shortcut="Ctrl+Z" >}} Undo
- {{< keys shortcut="Ctrl+Y" >}} Redo
- {{< keys shortcut="Ctrl+F" >}} Find

This layout makes it easy to scan a list of shortcuts at a glance.

### Callouts

Callouts are a great way to highlight important shortcuts that readers should remember:

:::{.callout-tip}
## Quick Navigation
Press {{< keys shortcut="Ctrl+P" >}} to quickly open any file by name, or
{{< keys shortcut="Ctrl+Shift+P" >}} to access the full command palette.
:::

The styled key caps remain legible inside colored callout backgrounds.

### Blockquotes

Keys also render correctly inside blockquotes:

> Press {{< keys "Esc" >}} to close any dialog or cancel the current operation.

This is useful for quoting interface instructions or reproducing help text from an application.

## Parameter Reference

The table below summarizes all available parameters for the `{{{< keys >}}}` shortcode.

| Parameter | Values | Default | Description |
|-----------|--------|---------|-------------|
| _(positional)_ | Any key name | (none) | Single key to render |
| `shortcut` | Key combo string | (none) | Multi-key shortcut, split on `+` |
| `platform` | `mac`, `win` | (none) | Translate keys for a specific OS |

Either the positional argument or `shortcut` is required. The `platform` parameter is always
optional.

## Function Keys

Function keys ({{< keys "F1" >}} through {{< keys "F20" >}}) receive a compact typographic
treatment inspired by macOS menu glyphs. The text is rendered at x-height scale with slightly
bolder weight, giving them a distinct look that sets them apart from regular keys:

{{< keys "F1" >}} {{< keys "F2" >}} {{< keys "F3" >}} {{< keys "F4" >}} {{< keys "F5" >}}
{{< keys "F6" >}} {{< keys "F7" >}} {{< keys "F8" >}} {{< keys "F9" >}} {{< keys "F10" >}}
{{< keys "F11" >}} {{< keys "F12" >}}

Function keys work in combos too:

{{< keys shortcut="Ctrl+F5" >}}

{{< keys shortcut="Alt+F4" >}}

{{< keys shortcut="Cmd+Shift+F12" platform="mac" >}}

The compact styling is applied automatically and is not platform-specific.

## Dark Mode

Key caps automatically adapt in dark mode. The background shifts to a dark gradient, borders become
more subtle, and text brightens for readability. No extra configuration is needed; the shortcode
works identically in both light and dark themes.

## Copy/Paste Friendly

Rendered shortcuts are plain text under the hood, so copying them from the page preserves the
readable key names and separators. For example, copying a macOS shortcut like
{{< keys shortcut="Cmd+Shift+P" platform="mac" >}} produces `⌘+⇧+P` in the clipboard. This
makes it easy for readers to paste shortcuts into notes, chat messages, or other documents without
losing meaning.

## Symbol Tooltips

When platform-aware rendering produces macOS symbols, each key cap includes a `title` attribute
with the full key name. Hovering over {{< keys "Cmd" platform="mac" >}} shows "Command",
{{< keys "Alt" platform="mac" >}} shows "Option", and so on. This helps readers who may not
recognize every symbol at a glance.

## Comparison with Quarto's Built-In `kbd`

Quarto ships with its own `{{{< kbd >}}}` shortcode
([documentation](https://quarto.org/docs/authoring/markdown-basics.html#keyboard-shortcuts)) that
renders keyboard shortcuts as plain text. It supports per-OS keyword arguments (`mac=`, `win=`,
`linux=`) and auto-detects the reader's operating system in HTML output:

````markdown
{{{< kbd Shift-Ctrl-P >}}}
{{{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}}
````

The Great Docs `{{{< keys >}}}` shortcode differs in three ways:

1. **Visual styling.** Keys render as styled caps with a 3D border, gradient background, and
   monospace font rather than plain text.
2. **Symbol translation.** With `platform="mac"`, modifier names are replaced by their macOS
   symbols (⌘, ⌥, ⇧, ⌃) rather than spelled out.
3. **Separator rendering.** Combo keys are joined by a styled `+` separator element.

Choose `{{{< kbd >}}}` when you want minimal, format-agnostic output that works in PDF, DOCX, and
other non-HTML targets. Choose `{{{< keys >}}}` when you are authoring HTML documentation and want
visually distinct key-cap styling that matches the Great Docs design system.

## Next Steps

The keyboard keys shortcode renders key combinations as styled caps that match the Great Docs design
system. Use it in tutorials, shortcut references, or anywhere you describe keyboard interactions.

- [Horizontal Rules](horizontal-rules.qmd) covers another visual shortcode for section separators
- [Authoring QMD Files](authoring-qmd-files.qmd) covers other content building blocks
- [Theming & Appearance](theming.qmd) explains how key-cap styling adapts to your site's theme


# Color Swatches

Documenting a project's colors (brand palette, theme variables, status indicators) is one of those
tasks that looks simple until you actually try to do it well. Static screenshots go stale,
hand-coded HTML is tedious to maintain, and plain text hex codes are meaningless without a visual
reference beside them.

The `{{{< color-swatch >}}}` shortcode solves this by turning a small YAML file into an interactive,
accessible color palette. Each swatch displays its hex code, shows RGB/HSL breakdowns on hover,
evaluates WCAG contrast ratios, and lets readers copy values with a single click. You can render
individual palettes, reference the built-in Great Docs gradient presets, or combine both approaches.

This guide walks through every feature (from a minimal first palette to advanced customization
options) so you can present colors as clearly as you present code.

## Quick Start

The fastest way to get a palette on the page is to create a YAML file with your colors and reference
it from a shortcode. No configuration beyond the file path is needed.

Start by creating a YAML file somewhere in your project. Each entry needs a `name` and a `hex`
value:

```{.yaml filename="assets/colors.yml"}
- name: Sky Blue
  hex: "#38bdf8"
- name: Deep Navy
  hex: "#1e3a5f"
- name: Coral
  hex: "#f97316"
```

Then reference it with the shortcode in any `.qmd` page:

````markdown
{{{< color-swatch file="assets/colors.yml" >}}}
````

Here is the result (three circle swatches with names and hex labels):

{{< color-swatch file="assets/color-data/demo-quick-start.yml" >}}

Hover over any swatch to see its full color breakdown in a tooltip. Click a swatch to copy its hex
value to the clipboard. That single shortcode line is all it takes to go from raw hex codes to a
polished, interactive palette.

## Display Modes

The shortcode supports two display modes, controlled by the `mode` parameter. The default is
`circles`, which works well for compact palettes and quick visual reference. The `rectangles` mode
is better suited for detailed documentation where contrast information needs to be front and center.
Additional modes (grid, gradient) are planned for future releases.

### Circles (Default)

Circle swatches are the default display mode. Each color appears as a filled circle with its name
and hex code underneath, arranged in a responsive row that wraps as needed.

To render circle swatches, simply omit the `mode` parameter (or set `mode="circles"` explicitly):

````markdown
{{{< color-swatch file="assets/brand-colors.yml" >}}}
````

Here is a five-color brand palette rendered as circles:

{{< color-swatch file="assets/color-data/demo-brand.yml" >}}

Circles are compact and scannable, making them ideal for showcasing a handful of brand or theme
colors at a glance. Each swatch is individually interactive (hover for details, click to copy).

### Rectangles

Rectangle mode renders each color as a full-width horizontal strip. This is useful when you want to
emphasize contrast information alongside the color itself.

Set `mode="rectangles"` to switch:

````markdown
{{{< color-swatch mode="rectangles" file="assets/brand-colors.yml" >}}}
````

Here are three colors rendered as rectangular strips:

{{< color-swatch mode="rectangles" file="assets/color-data/demo-rectangles.yml" >}}

Each strip displays the color name on the left, the hex code on the right, and white/black "Aa"
contrast samples. The "Aa" labels are marked pass or fail against WCAG AA thresholds, so you can
immediately see which text colors are safe to use on each background. Rectangle mode is especially
valuable for design-system documentation where accessibility compliance is a primary concern.

## Built-In Palette Presets

Great Docs ships with eight gradient presets that power the site's gradient theming system. Rather
than listing colors manually, you can reference any preset by name and the shortcode will render
its color stops as swatches.

To use a preset, pass its name to the `palette` parameter instead of providing a `file`:

````markdown
{{{< color-swatch palette="sky" >}}}
````

Here is the `sky` preset:

{{< color-swatch palette="sky" >}}

The full set of available presets is:

| Preset | Description |
|--------|-------------|
| `sky` | Soft sky blues |
| `peach` | Peach and blush |
| `prism` | Mint, sky, and lavender |
| `lilac` | Lilac and pink |
| `slate` | Cool grays |
| `honey` | Warm cream and apricot |
| `dusk` | Soft lavender-blue |
| `mint` | Pale aqua |

Each preset defines four color stops for both light and dark modes. The light-mode stops are shown
by default. These are the same palettes available through the `gradient-preset` option in your site
configuration, so the swatches you see here correspond exactly to the colors your site header and
other gradient elements will use.

### All Presets at a Glance

If you want to compare every preset side by side (for example, when choosing a gradient theme for
your site) use `palette="all"` to render all presets in a single view:

````markdown
{{{< color-swatch palette="all" >}}}
````

This renders every preset's light-mode color stops, grouped by preset name:

{{< color-swatch palette="all" >}}

The grid layout ensures each swatch is the same width, making visual comparison straightforward.
This view is handy for theme selection pages or internal style guides.

### Extend a Preset

Sometimes a preset is close to what you need but you want to add a few extra colors. You can combine
a preset with a YAML file (the file's colors are appended after the preset's stops).

For example, to add a custom accent color after the `sky` preset:

````markdown
{{{< color-swatch palette="sky" file="assets/extra-colors.yml" >}}}
````

Here is the `sky` preset extended with one additional brand accent color:

{{< color-swatch palette="sky" file="assets/color-data/demo-extend-accent.yml" >}}

The preset colors appear first, followed by any colors from the file. This lets you document how
your custom additions relate to the built-in palette without duplicating the preset definitions.

## Tooltips

Every swatch shows a rich tooltip on hover. Tooltips provide the detailed color information that
would clutter the main display but is essential for anyone working with the values.

Each tooltip contains:

- a mini color preview square
- the color name
- hex code with a clipboard copy button
- RGB values
- HSL values (rounded to integers)
- APCA contrast ratio against white and against black (in Lc units)
- WCAG AA pass/fail verdict for normal-size text

Tooltips are powered by the Tippy.js library that is already bundled with Great Docs, so no
additional dependencies are needed. The tooltips appear on hover for mouse users and on focus for
keyboard users, ensuring the information is accessible to everyone.

## Click to Copy

One of the most common reasons to look up a color palette is to grab a specific value for use in
code or design tools. The shortcode makes this effortless.

Click any swatch to copy its hex value (including the `#`) to the clipboard. A brief checkmark
animation confirms the copy succeeded. Inside the tooltip, each hex code also has a dedicated
clipboard button for a more targeted copy action.

The copied value is always the full hex code (e.g., `#38bdf8`), which is the format most commonly
pasted into CSS, design tools, and configuration files.

## Contrast Checks

Choosing colors that look good is only half the job: they also need to be readable. The shortcode
uses the APCA (Accessible Perceptual Contrast Algorithm) to evaluate every color against white
(`#FFFFFF`) and black (`#000000`) text. This is the same algorithm that powers the automatic navbar
text-color selection elsewhere in Great Docs.

By default, contrast information appears in tooltips and in the "Aa" samples on rectangle swatches.
You can control this behavior with the `show-contrast` parameter.

### Display Options

The `show-contrast` parameter accepts three values:

| `show-contrast` value | Behavior |
|----------------------|----------|
| `"true"` (default) | Contrast info appears in tooltips and rectangle "Aa" samples |
| `"inline"` | Contrast ratios also appear below the hex code on each circle swatch |
| `"false"` | Contrast info is hidden everywhere |

Setting `show-contrast="inline"` places the contrast ratios directly on the swatch, which is useful
when contrast is the primary focus of the documentation:

````markdown
{{{< color-swatch show-contrast="inline" file="assets/contrast-demo.yml" >}}}
````

Here are two colors with inline contrast ratios visible beneath the hex codes:

{{< color-swatch show-contrast="inline" file="assets/color-data/demo-contrast.yml" >}}

The inline display shows the Lc (lightness contrast) value for both white-on-color and
black-on-color combinations, along with a pass/fail indicator. Use this mode when your audience
needs to evaluate contrast at a glance without hovering.

## Controlling What's Shown

Sometimes you want a simpler display (perhaps just the color circles with names, without hex codes
cluttering the view). The shortcode provides three toggle parameters that control label visibility.

| Parameter | Default | Effect |
|-----------|---------|--------|
| `show-names` | `"true"` | Show or hide color names below swatches |
| `show-hex` | `"true"` | Show or hide hex codes below swatches |
| `show-contrast` | `"true"` | Show or hide contrast info (see above) |

For example, to show only the swatches and their names without hex labels:

````markdown
{{{< color-swatch show-hex="false" file="assets/colors.yml" >}}}
````

Here is a minimal palette with hex codes hidden:

{{< color-swatch show-hex="false" file="assets/color-data/demo-minimal.yml" >}}

The hex values are still available in the tooltip on hover (hiding them from the main display
reduces visual noise when the color names alone are sufficient). You can combine these toggles
freely: `show-names="false" show-hex="false"` gives you bare swatches with all information deferred
to tooltips.

## Customization

The shortcode offers several parameters for fine-tuning the appearance of the palette container and
individual swatches. These let you adapt the display to different contexts (from a prominent hero
palette to a compact inline reference).

### Title and Description

Add a heading and optional description above the palette to give it context within your page. This
is especially useful when you have multiple palettes on the same page and need to label each one.

````markdown
{{{< color-swatch title="Brand Colors" description="Our primary brand palette for 2026." file="assets/brand.yml" >}}}
````

Here is a palette with a title and description:

{{< color-swatch title="Brand Colors" description="Our primary brand palette for 2026." file="assets/color-data/demo-title.yml" >}}

The title renders as a heading within the palette container, and the description appears as a
subtitle beneath it. Both are optional and can be used independently.

### Swatch Size

The default circle diameter is 56px, which works well for most layouts. For hero sections, style
guides, or situations where you want the colors to be more prominent, increase the size:

````markdown
{{{< color-swatch size="80px" file="assets/colors.yml" >}}}
````

Here is a single swatch rendered at 80px:

{{< color-swatch size="80px" file="assets/color-data/demo-single.yml" >}}

The `size` parameter accepts any valid CSS length value. Smaller sizes (like `40px`) work well for
dense reference tables, while larger sizes (like `100px`) make colors the focal point of the page.

### Border

By default, the palette container has a subtle border that visually groups the swatches. If you
prefer a cleaner look (for example, when the palette sits inside a callout or a card that already
has its own border) you can disable it:

````markdown
{{{< color-swatch border="false" palette="mint" >}}}
````

Here is the `mint` preset without a container border:

{{< color-swatch border="false" palette="mint" >}}

The swatches themselves are unchanged; only the outer container border is removed.

### Extra CSS Classes

For advanced styling, add custom CSS classes to the palette wrapper with the `class` parameter:

````markdown
{{{< color-swatch class="my-special-palette" palette="lilac" >}}}
````

You can then target `.my-special-palette` in your custom CSS to override spacing, alignment,
background, or any other property. This provides an escape hatch for layouts that the built-in
parameters don't cover.

## Color Entry Format

Every YAML color file follows a simple structure. Each entry is a list item with two required
properties:

| Property | Required | Description |
|----------|----------|-------------|
| `name` | Yes | Display name shown below the swatch |
| `hex` | Yes | Hex color value (e.g., `"#38bdf8"`) |

A minimal file looks like this:

```{.yaml filename="assets/my-colors.yml"}
- name: Primary
  hex: "#2563eb"
- name: Accent
  hex: "#f97316"
```

Hex values must include the `#` prefix and can use either three-digit (`#fff`) or six-digit
(`#ffffff`) notation. The shortcode normalizes all values to six digits internally for consistent
display. Quoting the hex values in YAML is recommended to avoid parsing issues with the `#`
character.

## Accessibility

The color-swatch shortcode is designed to be usable by everyone, including keyboard-only users and
screen-reader users.

Key accessibility features include:

- **Keyboard navigation**: Every swatch is focusable via Tab and can be activated with Enter or
Space to copy its hex value.
- **ARIA labels**: Each swatch carries an `aria-label` describing the color name, hex value, and
available actions.
- **Live announcements**: Copy confirmations are announced through an `aria-live` region so screen
readers report the result.
- **Visibility safeguards**: Very light colors (nearly white) automatically receive a subtle border
ring so they remain visible against the page background. Very dark colors get the same treatment in
dark mode.
- **Reduced motion**: The `prefers-reduced-motion` media query disables hover and copy animations
for users who have requested reduced motion in their OS settings.

These features ensure that color documentation is not just visual as the information is available
through assistive technology as well.

## Dark Mode

Swatches adapt to the page theme automatically. When a reader toggles dark mode, the palette adjusts
without any extra configuration:

- container borders and shadow intensities shift for dark backgrounds.
- border rings on very light and very dark colors swap direction (light rings appear around dark
colors in dark mode, and dark rings appear around light colors in light mode).
- tooltips inherit the page's current theme context.

When using a palette preset, the light-mode color stops are shown regardless of page theme.
Dark-mode palette display (showing the preset's dark-mode stops when the page is in dark mode) is
planned for a future release.

## Responsive Behavior

The swatch layout is responsive and adjusts to smaller screens automatically.

On mobile viewports (below 576px):

- Circle swatches shrink to 44px and grid gaps tighten to keep the layout compact.
- Rectangle strips stack their labels vertically to avoid horizontal overflow.

On wider screens, the grid expands to fill the available width with equal-size columns. No
media-query configuration is needed on your part as the built-in CSS handles all breakpoints.

## Parameters Reference

The table below lists every parameter available on the `{{{< color-swatch >}}}` shortcode. All
parameters are optional and, at minimum, you need either `file` or `palette` (or both) to provide
colors.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file` | string | — | Path to a YAML file with color definitions (relative to project root) |
| `palette` | string | — | Preset name: `sky`, `peach`, `prism`, `lilac`, `slate`, `honey`, `dusk`, `mint`, or `all` |
| `mode` | string | `"circles"` | Display mode: `circles` or `rectangles` |
| `size` | string | `"56px"` | Circle swatch diameter (CSS length) |
| `show-contrast` | string | `"true"` | `"true"`, `"false"`, or `"inline"` |
| `show-names` | string | `"true"` | Show or hide color names |
| `show-hex` | string | `"true"` | Show or hide hex values |
| `copy-format` | string | `"hex"` | Clipboard format: `hex` |
| `title` | string | — | Title above the palette |
| `description` | string | — | Description below the title |
| `border` | string | `"true"` | Show or hide container border |
| `id` | string | auto | Custom HTML `id` for the wrapper |
| `class` | string | — | Additional CSS classes |

When both `file` and `palette` are provided, the preset colors appear first and the file colors are
appended after them.

## Next Steps

Color swatches turn color definitions into visual, interactive documentation. Whether you maintain a
design system or just want to showcase your package's theme palette, the shortcode handles
rendering, contrast checks, and copy-to-clipboard.

- [Theming & Appearance](theming.qmd) covers gradient themes, dark mode, and other visual
customization
- [Table Previews](table-previews.qmd) covers another visual component for rendering data tables
- [Configuration](configuration.qmd) covers all `great-docs.yml` options



## Build & Deploy

# Freeze & Caching

When your documentation includes executable code cells, you don't want to re-execute them on every
build if nothing has changed. The **freeze** feature caches execution outputs and reuses them across
builds, cutting build times dramatically.

Great Docs enables `freeze: auto` by default: code cells are only re-executed when their source
`.qmd` file changes. On a subsequent build where nothing has changed, execution is skipped entirely
and cached outputs are reused. The freeze cache is also persisted back to your project root
automatically after each build.

This guide covers how freeze works under the hood, how to customize it for individual pages, how to
use the `great-docs freeze` CLI command to manage your cache, and how the workflow fits into CI/CD
pipelines.

## How Freeze Works

The freeze mechanism stores the rendered output of executable code cells in a `_freeze/` directory.
When a page is frozen:

- **`freeze: auto`**: the page is only re-executed when its source code changes. If the `.qmd` file
hasn't changed since the last execution, the cached output is reused.
- **`freeze: true`**: the page is never re-executed during a project render. You must explicitly
render it to update its outputs.

::: {.callout-tip}
## Choosing `auto` vs `true`

Use **`freeze: auto`** for most pages. It strikes the right balance by re-executing only when the
source changes. Use **`freeze: true`** when you need absolute control: pages with non-deterministic
output (random seeds, API calls), pages requiring hardware you only have locally (GPUs, licensed
software), or pages where accidental re-execution could produce confusing diffs. With `true`, the
only way to update the cache is an explicit `great-docs freeze`.
:::

## Default Behavior

Since `freeze: auto` is the default, you don't need to configure anything for freeze to work. On
your first build, all executable cells run and their outputs are cached in `_freeze/`. On subsequent
builds, only pages whose `.qmd` source has changed are re-executed.

After each successful build, Great Docs automatically copies `_freeze/` from the build directory
back to your project root so it persists across builds (since the build directory is recreated each
time).

## Page-Level Overrides

While all executable pages are frozen by default, you can override the behavior for individual
pages. To force a page to always re-execute (useful for pages that display live data or current
status), add `freeze: false` to its frontmatter:

```{.yaml filename="user_guide/live-status.qmd"}
---
title: "Live Status"
freeze: false
---
```

You can also use `freeze: true` on specific pages to lock them completely (so they are never
re-executed during a project render, even if their source changes). The only way to update them is
an explicit `great-docs freeze <page>`. This is useful for pages with non-deterministic output
(random seeds, API calls) or pages requiring special hardware (GPUs, licensed software).

```{.yaml filename="user_guide/benchmarks.qmd"}
---
title: "Benchmarks"
freeze: true
---
```

Great Docs normalizes the shorthand `freeze:` into the nested form that Quarto requires
(`execute: freeze:`) automatically during the build.

## Disabling Freeze

If you want all pages to re-execute on every build, set `freeze: false` in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
freeze: false
```

## How the Cache Persists

You might wonder: if Great Docs recreates the build directory from scratch on each build, how does
the freeze cache survive? Great Docs handles this transparently with a two-step round-trip:

1. **Before rendering**: a built-in pre-render script copies `_freeze/` from your project root into
   the build directory
2. **After rendering**: Great Docs copies the updated `_freeze/` from the build directory back to
   your project root

You don't need to create or manage any scripts; it's all handled internally. This also works with
versioned builds, where each version's freeze cache is collected and merged back to the project
root.

## The `great-docs freeze` Command

The `great-docs freeze` command is your primary tool for managing frozen page outputs. It handles
the full lifecycle: executing code, capturing outputs, and persisting the cache to a location you
can commit. You never need to manually copy files or interact with the freeze internals directly.

### Freeze a Page

```{.bash filename="Terminal"}
great-docs freeze user_guide/benchmarks.qmd
```

This:

1. prepares the build directory (ensuring file transformations match a full build)
2. renders the specified page(s), always executing code regardless of cache state
3. copies updated `_freeze/` entries back to your project root
4. prints a ready-to-use `git add` + `git commit` command

```{.default filename="Example output"}
Preparing build directory...

  Rendering user_guide/benchmarks.qmd → user-guide/benchmarks.qmd ...
  ✓ user_guide/benchmarks.qmd

Persisting _freeze/ → _freeze/
  Updated 3 cached file(s)

To commit the updated freeze cache:
  git add _freeze/
  git commit -m "Update freeze cache for user_guide/benchmarks.qmd"
```

The suggested `git` commands at the end make it easy to commit the cache in a single copy-paste
step.

### Freeze Multiple Pages

You can pass any number of pages in a single invocation. Each page is rendered and its outputs are
persisted together, so you only need one `git add _freeze/` afterwards:

```{.bash filename="Terminal"}
great-docs freeze user_guide/benchmarks.qmd user_guide/mcmc-demo.qmd
```

### Full Refresh with `--clean`

Sometimes you want to start completely fresh. For example, after a major dependency upgrade that
changes plot styling or output format. The `--clean` flag deletes the entire `_freeze/` cache before
re-executing:

```{.bash filename="Terminal"}
great-docs freeze --clean user_guide/benchmarks.qmd user_guide/sampling.qmd
```

This deletes and regenerates only the entries for the specified pages, leaving any other cached
pages intact.

### Check Freeze Status with `--info`

Not sure which pages are frozen or whether they've been cached yet? The `--info` flag gives you a
quick dashboard:

```{.bash filename="Terminal"}
great-docs freeze --info
```

```{.default filename="Example output"}
  Project freeze: auto (all executable pages)
  Freeze cache:   _freeze/

  3 cached page(s):

  ✓  recipes/freeze-demo
       frozen at 2026-05-06 13:26:41
  ✓  reference/tbl_explorer
       frozen at 2026-07-22 01:15:23
  ✓  user-guide/writing-docstrings
       frozen at 2026-07-22 01:15:24

  3 page(s) cached

  ℹ To re-freeze a stale page: great-docs freeze <page>
```

The output shows the project-level freeze setting, any per-page overrides, and all cached entries
from `_freeze/` with their timestamps. This is useful for identifying pages that may benefit from a
re-freeze after updating dependencies or input data.

### Custom Persist Location

By default the cache is written to `_freeze/` at your project root. If your project layout requires
a different location (for example, a monorepo where docs live in a subdirectory), use `--freeze-dir`
to override:

```{.bash filename="Terminal"}
great-docs freeze user_guide/benchmarks.qmd --freeze-dir docs/_freeze
```

The build will look for the cache in the specified directory when restoring.

## Complete Workflow

Since freeze is enabled by default, the workflow is straightforward:

### First Build

Run `great-docs build` as normal. All executable cells run and their outputs are cached in
`_freeze/` at your project root. No configuration needed.

### Subsequent Builds

On subsequent builds, only pages whose `.qmd` source has changed are re-executed. Everything else
loads from the cache.

### Updating Frozen Pages

When you update a dependency that changes output (e.g., a new package release that fixes a bug in a
rendered table), the source hash won't detect this. Use `great-docs freeze` to explicitly
re-execute:

```{.bash filename="Terminal"}
great-docs freeze user_guide/benchmarks.qmd
```

Or wipe the entire cache for a full refresh:

```{.bash filename="Terminal"}
great-docs freeze --clean user_guide/benchmarks.qmd user_guide/sampling.qmd
```

### In CI

The `great-docs setup-github-pages` command generates a workflow with built-in freeze caching. The
cache is stored using `actions/cache` and keyed on both your dependency lockfile and `.qmd` content:

```{.yaml filename=".github/workflows/docs.yml"}
- name: Restore freeze cache
  uses: actions/cache@v4
  with:
    path: _freeze/
    key: freeze-${{ hashFiles('**/uv.lock', ...) }}-${{ hashFiles('**/*.qmd') }}
    restore-keys: |
      freeze-${{ hashFiles('**/uv.lock', ...) }}-
      freeze-
```

This means:

- **Same dependencies + same `.qmd` files** → full cache hit, no re-execution
- **Same dependencies + changed `.qmd` files** → partial hit, only changed pages re-execute
- **Updated dependencies** → cache miss, all pages re-execute with fresh outputs

GitHub Actions caches are branch-scoped, so PR branches benefit from `main`'s cache but never
pollute it.

::: {.callout-tip}
## Committing `_freeze/` works too

You can also commit `_freeze/` directly to your repository. Since `actions/checkout` restores it as
part of the repo, Great Docs picks it up automatically (no `actions/cache` step needed). This is the
simplest approach and gives maintainers direct control over what's cached.

**Choose one approach, not both.** If you commit `_freeze/` to your repo, do **not** also use the
`actions/cache` step. The cache can overwrite your freshly committed freeze data with stale entries
from a previous run, causing pages to re-execute unnecessarily.
:::

## Mixing Frozen and Fresh Pages

With the default `freeze: auto`, all executable pages are cached. Pages without executable code
cells are unaffected (i.e., they always render fresh). To force a specific executable page to always
re-execute, override it with `freeze: false` in its frontmatter:

```{.yaml filename="a-page-that-must-always-run.qmd"}
---
title: "Live Status"
freeze: false
---
```

This is useful for pages that pull live data or display current status information.

## When to Refresh the Cache

With `freeze: auto`, pages are automatically re-executed when their source `.qmd` changes. But some
triggers aren't captured by a source hash:

| Trigger | Automatic? | Action |
|---------|:----------:|--------|
| Source code of frozen page changes | Yes | Handled by `freeze: auto` |
| Package version update (bugfixes, new output) | No | `great-docs freeze <page>` |
| Input data files change | No | `great-docs freeze <page>` |
| Dependency updates (new plots, styling) | No | `great-docs freeze --clean <pages>` |
| Full refresh needed | No | `great-docs freeze --clean <pages>` |

::: {.callout-important}
## Dependency updates and stale outputs

When you update a package that your examples depend on (e.g., a new release that fixes a rendering
bug or deprecates a function), the cached outputs will be stale even though the `.qmd` source hasn't
changed. Run `great-docs freeze --clean` to re-execute with the updated dependency.

In CI, the generated workflow keys the cache on your lockfile hash, so dependency updates
automatically trigger a full re-execution.
:::

Use `great-docs freeze --info` at any time to check which pages are cached and when they were last
frozen.

## Where Does `_freeze/` Live?

The `_freeze/` directory always lives at your **project root**, the same directory as
`great-docs.yml`. You never need to create it manually; `great-docs freeze` generates it for you and
places it in the right spot.

```{.default filename="Your project"}
my-package/
├── great-docs.yml
├── _freeze/              ← always here, at the top level
│   └── ...
├── user_guide/
│   └── benchmarks.qmd
└── ...
```

::: {.callout-note}
## You don't need to look inside `_freeze/`

The contents of `_freeze/` are managed. Treat it as an opaque cache. You'll never need to edit,
inspect, or understand the JSON files inside. The only operations you perform on it are:

- **`git add _freeze/`**: commit it so CI and collaborators get the cache
- **`great-docs freeze --clean <pages>`**: wipe and rebuild when you need a fresh start

Think of it like a compiled artifact: you commit it for reproducibility, but you regenerate it with
`great-docs freeze` rather than editing it by hand.
:::

### What's Actually Inside (for the curious)

The directory mirrors your site structure with one JSON file per frozen page:

```{.default filename="_freeze/ structure"}
_freeze/
├── site_libs/                # Shared JS/CSS libraries (e.g., clipboard.min.js)
├── user-guide/
│   └── benchmarks/
│       └── execute-results/
│           └── html.json     # Cached cell outputs + content hash
└── recipes/
    └── mcmc-demo/
        └── execute-results/
            └── html.json
```

Each `html.json` contains the rendered cell outputs and a hash of the source file. This hash is
compared against the current `.qmd`. If they match, the cached output is used; if they differ (i.e.,
perhaps you edited the source), the page is re-executed. These files are typically small (a few KB
to a few MB depending on plot complexity).

## Advanced Configuration

The freeze feature works out of the box for most projects. The options below let you customize the
workflow for more complex setups, such as projects that need data generation before rendering or
monorepos with non-standard directory layouts.

### Additional Pre-Render Scripts

Pre-render scripts run once before any page rendering occurs. They are useful for tasks that prepare
shared data or assets that your `.qmd` pages depend on (e.g., downloading a dataset, generating
fixture files, or validating inputs). These scripts don't interact with individual page authoring
directly; they simply ensure that prerequisites are in place before the render starts.

Each script is run with the **build directory** as the working directory. This means scripts can
create files directly into the build tree where pages will pick them up. If a script exits with a
non-zero exit code, the build fails immediately with an error, which is useful for enforcing
preconditions.

If you have pre-render scripts of your own, add them via the `pre_render` key in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
pre_render:
  - scripts/generate-data.py
  - scripts/validate-inputs.py
```

Great Docs runs these scripts in order before rendering. The built-in freeze cache restore always
runs first (automatically), followed by your scripts. You don't need to include the restore script
in this list.

For example, we could generate a data file for pages to read:

```{.python filename="scripts/generate-data.py"}
"""Download latest metrics and write them where pages can find them."""
import json
import sys
from pathlib import Path

# CWD is the build directory; assets/data/ is accessible from pages
output = Path("assets/data/metrics.json")
output.parent.mkdir(parents=True, exist_ok=True)

try:
    # Your data-fetching logic here
    metrics = {"downloads": 142_000, "stars": 3_200}
    output.write_text(json.dumps(metrics, indent=2))
except Exception as e:
    print(f"ERROR: Failed to generate metrics: {e}", file=sys.stderr)
    sys.exit(1)  # Non-zero exit fails the build
```

A page can then read from that path:

````{.yaml filename="user_guide/dashboard.qmd"}
---
title: "Project Metrics"
---

```{{python}}
import json
from pathlib import Path

metrics = json.loads(Path("assets/data/metrics.json").read_text())
print(f"Downloads: {metrics['downloads']:,}")
```
````

As another example, we could validate that required files exist:

```{.python filename="scripts/validate-inputs.py"}
"""Fail the build early if expected input files are missing."""
import sys
from pathlib import Path

required = [
    Path("assets/data/benchmark-results.csv"),
    Path("assets/data/changelog-entries.json"),
]

missing = [str(p) for p in required if not p.exists()]
if missing:
    print("Build aborted. Missing required files:", file=sys.stderr)
    for m in missing:
        print(f"  - {m}", file=sys.stderr)
    sys.exit(1)
```

This pattern is helpful when frozen pages depend on external data files that must be present but
aren't generated by the freeze process itself.

## Build Log

The build log includes a step showing freeze cache status:

```{.default filename="Build log excerpt (Step 15)"}
━━ Step 15/18 ─ Prepare freeze cache ━━━━━━━━━━━━━━━━━━━━
   ✔ Freeze cache will be restored during render  <0.1s
```

After a successful build, the log also confirms the cache was persisted:

```{.default filename="Build log excerpt (after render)"}
      Saved freeze cache (42 files)
```

This makes it easy to confirm at a glance that freeze is working.

## Next Steps

Freeze eliminates re-execution overhead for expensive pages, making builds fast and CI pipelines
reliable. Once your cache is committed, collaborators and CI runners can build the full site without
needing your computational environment.

- [Use Freeze to Cache Expensive Notebooks](../recipes/use-freeze-cache.qmd): a recipe with more
detailed examples and CI patterns
- [Freeze Demo](../recipes/freeze-demo.qmd): a live page with frozen outputs you can inspect
- [Configuration](configuration.qmd): all `great-docs.yml` options including `pre_render`
- [Publishing](publishing.qmd): deploying your site to GitHub Pages, Netlify, or other hosts



## AI & Agents

# Agent Skills

AI coding agents (Claude Code, GitHub Copilot, Cursor, Windsurf, Codex, and many others) produce
better code when they have structured context about the libraries they're using. The
[Agent Skills](https://agentskills.io/) open standard provides that context through a `SKILL.md`
file: a concise cheat sheet that tells agents what a package does, how to use it correctly, and
what mistakes to avoid.

Great Docs has two roles in this ecosystem:

- **For package authors**: Great Docs generates, bundles, and serves `SKILL.md` files as part of
  your documentation site, making your package's skill discoverable by anyone.
- **For package users**: Great Docs provides a CLI (`great-docs skill install`) and Python API to
  install skills into your local project, keep them up to date, and manage them across different
  agents.

This guide covers both sides. If you maintain a Python package and want to ship a skill with it,
start with [Publishing Skills (for Authors)](#publishing-skills-for-authors). If you use a package
that ships a skill and want to install it into your project, skip ahead to
[Installing Skills (for Users)](#installing-skills-for-users).

## Publishing Skills (for Authors) {#publishing-skills-for-authors}

When you build a documentation site with Great Docs, a `SKILL.md` is automatically included.
During the build, Great Docs:

1. Resolves the skill content (hand-written, curated, or auto-generated)
2. Copies it to `skill.md` in the docs output directory
3. Places it at `.well-known/agent-skills/<name>/SKILL.md` with a discovery manifest at
   `.well-known/agent-skills/index.json`
4. Creates a legacy copy at `.well-known/skills/default/SKILL.md`

Once deployed, anyone can install the skill using the standard discovery protocol:

```bash
npx skills add https://your-docs-site.com
```

Or install directly from an installed Python package (if you bundle the skill in `skills/`):

```bash
great-docs skill install your-package
```

Great Docs never modifies a hand-written skill. If you provide one, it is copied and served
exactly as written. The content-hash stamping described later in
[How Freshness Checking Works](#how-freshness-checking-works) only happens on the *consumer* side
when a user installs the skill (it does not alter the published artifact).

### Writing Your Own Skill (Recommended)

The best results come from a hand-crafted skill written by someone who knows the package well.
Auto-generated skills capture the API surface, but only a human author can encode the tribal
knowledge (gotchas, decision tables, opinionated best practices) that makes an agent genuinely
useful.

Create a `SKILL.md` file in `skills/<package-name>/` at your project root:

```
my-package/
├── skills/
│   └── my-package/
│       └── SKILL.md    ← Your curated skill
├── pyproject.toml
└── great-docs.yml
```

Great Docs automatically detects this file and uses it instead of generating one. The following
sections explain what goes inside a `SKILL.md` and how to structure it effectively.

### YAML Frontmatter

Every `SKILL.md` must start with YAML frontmatter (required by the
[specification](https://agentskills.io/specification)):

```markdown
---
name: my-package
description: >
  Build widgets with my-package. Use when creating, configuring, or
  troubleshooting widgets in Python.
license: MIT
compatibility: Requires Python >=3.10.
---
```

| Field           | Required | Constraints                                       |
|-----------------|----------|---------------------------------------------------|
| `name`          | Yes      | ≤64 chars, lowercase + hyphens, matches dir name  |
| `description`   | Yes      | ≤1024 chars, what it does + when to use it         |
| `license`       | No       | SPDX identifier                                   |
| `compatibility` | No       | Runtime requirements                               |
| `metadata`      | No       | Arbitrary key-value map                            |

The `name` field must match the directory name under `skills/`. The `description` should answer
two questions in one sentence: *what does the skill do?* and *when should an agent activate it?*

### Recommended Body Sections

A good skill is a **cheat sheet for agents**: concise, opinionated, and focused on the decisions
and mistakes that matter most.

| Section                      | Purpose                                          |
|------------------------------|--------------------------------------------------|
| **Installation**             | `pip install` command                            |
| **Decision table**           | Map common tasks → the right class/function      |
| **Gotchas**                  | Mistakes agents make repeatedly without guidance |
| **Capabilities & boundaries**| What agents can configure vs. what needs human setup |
| **Resources**                | Links to `llms.txt`, `llms-full.txt`, full docs  |

**Example decision table:**

```markdown
| Need                    | Use                |
|-------------------------|--------------------|
| Create a widget         | `Widget()`         |
| Style a widget          | `Widget.style()`   |
| Export to HTML          | `Widget.to_html()` |
```

**Example gotchas:**

```markdown
1. Always call `init()` before `process()` (order matters).
2. The module name is `my_pkg`, not `my-package`.
3. Use `dynamic: false` for packages with circular imports.
```

Keep the file under 500 lines. Link out to `llms-full.txt` for anything that needs more detail.

### Extra Reference Files

You can include companion files alongside `SKILL.md` in the same directory. These are copied to
the `.well-known/agent-skills/<name>/` output and are available for agents to reference:

```
skills/
└── my-package/
    ├── SKILL.md
    ├── recipes.md        ← Additional reference material
    └── migration-v2.md   ← Upgrade guide for agents
```

These companion files are particularly useful for migration guides, code recipes, or schema
references that are too detailed for the main `SKILL.md` but valuable when an agent needs them.

### Automatic Generation (Fallback)

If no curated skill exists in `skills/<package-name>/`, Great Docs auto-generates one from your
package metadata and API reference. The generated file includes:

- Package name, description, and `pip install` command
- An API overview with section titles and docstring summaries
- Links to `llms.txt` and `llms-full.txt`

This is a reasonable starting point, but a hand-written skill will always produce better results
because you can encode knowledge that can't be inferred from docstrings alone.

### Enriching the Generated Skill

If you'd rather let Great Docs generate the base skill but want to add your own sections, use the
`skill` configuration options in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
skill:
  gotchas:
    - "Always call init() before process()"
    - "The config file must use YAML, not JSON"
    - "Module name is 'my_pkg', not 'my-pkg'"
  best_practices:
    - "Use context managers for resource cleanup"
    - "Prefer keyword arguments for clarity"
  decision_table:
    - need: "Parse a CSV file"
      use: "read_csv()"
    - need: "Write results to disk"
      use: "Writer()"
  extra_body: skill-extra.md  # Append extra Markdown from this file
```

These options only apply to the *auto-generated* skill. If you provide a hand-written skill
(via `skill.file` or `skills/<name>/SKILL.md`), these options are ignored and your file is used
as-is.

### Resolution Order

Great Docs resolves the skill file in this priority order:

1. **Multi-skill mode** (`skill.skills` list): each entry is a separate named skill
2. **`skill.file`** in `great-docs.yml`: explicit path to a single `SKILL.md`
3. **`skills/<package-name>/SKILL.md`**: curated skill in the repo (checked with both hyphenated
   and underscored package name variants)
4. **Auto-generated**: built from package metadata and API sections

In all cases except auto-generation, Great Docs copies your file verbatim. It does not inject
metadata or modify the content.

### Multi-Skill Mode

Some packages have distinct functional areas that benefit from separate skills. For example, a
data visualization library might have one skill for building charts and another for theming. The
`skill.skills` configuration lets you publish multiple named skills from a single package:

```{.yaml filename="great-docs.yml"}
skill:
  skills:
    - name: my-package
      file: skills/my-package/SKILL.md
    - name: my-package-themes
      file: skills/my-package-themes/SKILL.md
```

Each entry must have a `name` and a `file` path (relative to the project root). During the build:

- the first skill in the list becomes the primary `skill.md` in the docs output
- all skills are aggregated into a single `.well-known/agent-skills/index.json` manifest
- each skill gets its own directory under `.well-known/agent-skills/<name>/SKILL.md`

Users can then discover and install all skills at once:

```bash
npx skills add https://your-docs-site.com
```

Multi-skill mode is optional. Most packages need only a single skill, which Great Docs handles
automatically through the standard resolution order.

### Deployment Considerations {#deployment-considerations}

The `.well-known/` directory is a dotfile directory. Some deployment platforms strip dotfiles
by default. If you deploy to GitHub Pages, make sure both artifact upload steps in your workflow
include `include-hidden-files: true`:

```{.yaml filename=".github/workflows/docs.yml"}
# In the build job:
- uses: actions/upload-artifact@v4
  with:
    name: docs-site
    path: <docs-output-dir>/_site
    include-hidden-files: true    # Required

# In the deploy job:
- uses: actions/upload-pages-artifact@v4
  with:
    path: <docs-output-dir>/_site
    include-hidden-files: true    # Required
```

Without this, the `.well-known/agent-skills/` directory is silently dropped and `npx skills add`
will return a 404.

::: {.callout-tip}
Great Docs generates this workflow for you with the correct settings. See the
[Deployment](14-deployment.qmd) guide for the full workflow template.
:::

### Configuration Reference

```{.yaml filename="great-docs.yml"}
skill:
  enabled: true          # Set to false to disable skill.md entirely
  file: null             # Path to a SKILL.md (overrides curated and generated)
  well_known: true       # Serve at /.well-known/ discovery endpoints
  gotchas: []            # Gotcha strings (for auto-generated skill only)
  best_practices: []     # Best-practice strings (for auto-generated skill only)
  decision_table: []     # Rows: [{need: "...", use: "..."}]
  extra_body: null       # Path to extra Markdown to append (auto-generated only)
  skills: []             # Multi-skill mode: [{name: "...", file: "..."}]
```

All of these options are documented in detail in the sections above. For a quick setup, the only
required step is placing a `SKILL.md` in `skills/<package-name>/` (everything else has sensible
defaults).

## Installing Skills (for Users) {#installing-skills-for-users}

If you're a *user* of a Python package that ships a skill, you can install it into your local
project so your AI coding agent has context about the package whenever you're writing code.

::: {.callout-tip}
## Install the Great Docs skill itself

Great Docs ships its own skill. If you're building documentation sites with Great Docs, installing
it gives your AI agent context about `great-docs.yml` configuration, the build pipeline, CLI
commands, and common pitfalls:

```bash
great-docs skill install great-docs
```
:::

Great Docs provides three ways to install skills:

1. The **`great-docs skill` CLI**: the recommended approach for most users
2. The **Python API** (`great_docs.install_skill()`): for programmatic use or CI integration
3. **`npx skills add`**: the standard Agent Skills protocol (works without Great Docs installed)

The first two are covered in detail below. The third is the community standard and works with any
skills-compatible tool.

### `great-docs skill install`

Installs a skill from a Python package, a documentation site URL, or the current project:

```bash
# Install from an installed Python package
great-docs skill install great-tables

# Install from a documentation site URL
great-docs skill install https://posit-dev.github.io/great-tables/

# Install from the current project (auto-detects package from pyproject.toml)
great-docs skill install
```

Great Docs auto-detects which AI coding agents you have configured by scanning for marker files
(`.claude/`, `.github/`, `.cursor/`, etc.) and installs the skill into the correct directory. If
no agent is detected, it defaults to Claude Code (`.claude/skills/<name>/`).

You can also target a specific agent or a custom path:

```bash
# Target a specific agent
great-docs skill install great-tables --agent copilot

# Install to a custom path
great-docs skill install great-tables --path .claude/skills/my-gt

# Install globally (to ~/ instead of the current repo)
great-docs skill install great-tables --global

# Update all existing installations in place
great-docs skill install --detect
```

**Supported agents:**

| Agent           | Flag         | Default directory              |
|-----------------|--------------|--------------------------------|
| Claude Code     | `--agent claude`   | `.claude/skills/<name>/` |
| GitHub Copilot  | `--agent copilot`  | `.github/skills/<name>/` |
| Cursor          | `--agent cursor`   | `.cursor/skills/<name>/` |
| Windsurf        | `--agent windsurf` | `.windsurf/skills/<name>/` |
| OpenCode        | `--agent opencode` | `.opencode/skills/<name>/` |
| Codex           | `--agent codex`    | `.codex/skills/<name>/`  |

When multiple agents are detected (e.g., both `.claude/` and `.cursor/` exist), the skill is
installed into all of them in a single command.

### `great-docs skill check`

Checks whether installed skills are current or outdated:

```bash
# Check all installed skills
great-docs skill check

# Check a specific package
great-docs skill check great-tables

# Check and auto-update any outdated skills
great-docs skill check --update

# Check global installations only
great-docs skill check --global
```

Example output:

```
Checking installed skills...
  ✓ great-tables (Claude Code): v0.15.0 [current]
  ⚠ plotnine (Claude Code): v0.14.2 → v0.15.0 [outdated]
  · my-local-skill (Cursor) [local]

Summary: 1 current, 1 outdated, 1 local
```

The status labels mean:

| Status       | Meaning                                                        |
|--------------|----------------------------------------------------------------|
| **current**  | Installed skill matches the content in the installed package   |
| **outdated** | The package has newer skill content available                  |
| **local**    | Hand-written skill with no matching package (not checked)      |

Add `--update` to automatically replace any outdated skills with the latest content from the
installed package.

### `great-docs skill list`

Lists the skills bundled inside a package or available at a URL:

```bash
# List skills from an installed package
great-docs skill list great-tables

# List skills from a documentation site
great-docs skill list https://posit-dev.github.io/great-tables/

# List skills from the current project
great-docs skill list
```

This is useful for discovering what skills a package provides before installing them.

### How Freshness Checking Works {#how-freshness-checking-works}

When you install a skill from a Python package, Great Docs stamps two pieces of metadata into the
installed `SKILL.md`'s frontmatter:

- **`metadata.package_version`**: the Python package version at install time (e.g., `"0.15.0"`)
- **`metadata.content_hash`**: a SHA-256 prefix of the *original* skill content (before stamping)

When you later run `great-docs skill check`, the tool:

1. finds the bundled `SKILL.md` inside the currently installed Python package
2. hashes its content
3. compares that hash against the `content_hash` stored in the installed copy

If the hashes match, the skill is **current** (even if the package version has changed). This
eliminates false positives: if you upgrade from v0.10.0 to v0.11.1 and the skill text didn't
change, `check` correctly reports `current` instead of `outdated`.

This stamping only happens on the **consumer** side (during `skill install`). Published skills on
documentation sites are never modified and Great Docs copies them verbatim.

::: {.callout-note}
## What about hand-written skills?

If you create a `SKILL.md` manually (not via `great-docs skill install`), there is no matching
Python package to compare against. These skills are reported as `[local]` and are never flagged
as outdated. Great Docs leaves them entirely alone.
:::

### Python API

For programmatic use (CI scripts, setup automation, downstream package wrappers), the same
functionality is available as Python functions:

```python
from great_docs import install_skill, check_skill, list_skills

# Install a skill
paths = install_skill(package="great-tables")

# Check installed skills
results = check_skill(package="great-tables")
for r in results:
    print(f"{r['name']}: {r['status']}")

# List available skills
skills = list_skills(package="great-tables")
```

`install_skill()` accepts the same options as the CLI:

```python
install_skill(
    package="great-tables",    # or url="https://...", or skill_content="..."
    agent="claude",            # target agent (auto-detected if omitted)
    global_=False,             # install to ~/ instead of repo
    path=None,                 # explicit target path
    detect=False,              # update existing installations
    skill_name=None,           # override the skill name
    quiet=False,               # suppress output
)
```

All three functions return lists. The `install_skill()` function returns the paths of installed `SKILL.md`
files, `check_skill()` returns status dictionaries, and `list_skills()` returns skill metadata.

## How It All Fits Together

Here is the full lifecycle from authoring to consumption:

```
┌─────────────────────────────────────────────────────────────┐
│                     AUTHOR SIDE                             │
│                                                             │
│  1. Write SKILL.md in skills/<pkg>/                         │
│     (or let Great Docs auto-generate one)                   │
│                                                             │
│  2. great-docs build                                        │
│     → copies SKILL.md to docs output                        │
│     → places at .well-known/agent-skills/<name>/SKILL.md    │
│     → writes index.json discovery manifest                  │
│                                                             │
│  3. Deploy docs site                                        │
│     → skill is discoverable at the published URL            │
│                                                             │
│  4. pip install / pip publish                               │
│     → skill is bundled inside the Python package            │
│       (in skills/<name>/)                                   │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      USER SIDE                              │
│                                                             │
│  Install:                                                   │
│    great-docs skill install <package>                       │
│    great-docs skill install https://docs-site.com           │
│    npx skills add https://docs-site.com                     │
│    → stamps content_hash + package_version                  │
│    → writes to .claude/skills/<name>/SKILL.md (or other)    │
│                                                             │
│  Check:                                                     │
│    great-docs skill check                                   │
│    → hashes bundled SKILL.md from installed package         │
│    → compares against stored content_hash                   │
│    → reports current / outdated / local                     │
│                                                             │
│  Update:                                                    │
│    great-docs skill check --update                          │
│    → replaces outdated skills with latest content           │
│    → re-stamps content_hash + package_version               │
└─────────────────────────────────────────────────────────────┘
```

The key insight is that Great Docs never touches the *authored* skill content. The content-hash
stamping, version tracking, and freshness checking all happen exclusively on the consumer side.
Authors write a `SKILL.md`, and it is published and bundled exactly as written.

### Disabling Skills

If you don't want Great Docs to generate or serve a `SKILL.md` at all:

```{.yaml filename="great-docs.yml"}
skill:
  enabled: false
```

This suppresses both the `skill.md` generation and the `.well-known/` discovery endpoints.

## Next Steps

Agent Skills bridge the gap between your package's documentation and the AI coding agents that
help people use it. Whether you author a hand-crafted skill or let Great Docs generate one, the
result is a discoverable, installable cheat sheet that makes agents more effective.

- [Agent Skills Specification](https://agentskills.io/specification): the full open standard
- [llms.txt](39-llms-txt.qmd): the auto-generated LLM context files that complement skills
- [Configuration](05-configuration.qmd): all `great-docs.yml` options including the `skill` block
- [Deployment](14-deployment.qmd): deploying your site to GitHub Pages (with the `include-hidden-files` setting)
- [Building](13-building.qmd): the full build pipeline, including how skill generation fits in


# llms.txt

Large language models work best when they have accurate, structured context about the libraries
they're working with. The [llms.txt convention](https://llmstxt.org/) gives LLM-based tools a
machine-friendly summary of your package: what it does, what its API looks like, and where to find
the full documentation. Great Docs generates two files automatically during every build:

- **`llms.txt`**: a compact index of your API reference with one-line descriptions and links to
  each documented item
- **`llms-full.txt`**: a comprehensive document containing full function/class signatures,
  docstrings, CLI help text, and user guide content

Both files are placed in the root of your documentation site and are available at predictable URLs
(e.g., `https://your-docs-site.com/llms.txt`). No configuration is needed so if your project has an
API reference defined in `great-docs.yml`, the files are generated automatically.

## What Goes Into Each File

Great Docs generates both files from the same source data but at different levels of detail. The
compact `llms.txt` is a quick-reference index whereas `llms-full.txt` is the complete picture.

### `llms.txt`

The compact index follows the [llms.txt format](https://llmstxt.org/):

```markdown
# my_package

> A short description of the package

## Docs

### API Reference

#### Data Processing
> Functions for loading and transforming data

- [read_csv](https://example.com/reference/read_csv.html): Read a CSV file into a DataFrame
- [to_parquet](https://example.com/reference/to_parquet.html): Write a DataFrame to Parquet format

#### Visualization
> Plotting and display utilities

- [plot](https://example.com/reference/plot.html): Create a plot from a DataFrame
- [show](https://example.com/reference/show.html): Display a plot in the browser
```

The content is derived from:

- **Package name and description** from `pyproject.toml`
- **Section titles and descriptions** from the `api-reference.sections` block in `great-docs.yml`
- **One-line docstring summaries** extracted by importing the package at build time
- **URLs** constructed from the `site-url` in `great-docs.yml` or the `Documentation` URL in
  `pyproject.toml`

This file is typically small (a few KB) and is designed to give an LLM a quick overview of the
API surface without overwhelming its context window.

### `llms-full.txt`

The comprehensive file includes everything in `llms.txt` plus:

- **Full function and class signatures** with all parameters and type annotations
- **Complete docstrings** (not just the first line)
- **CLI help text** for all commands and subcommands (if CLI documentation is enabled)
- **User guide content** from all user guide pages, with YAML frontmatter stripped

This file can be large (tens of KB to hundreds of KB depending on your API surface and user guide
size). It's intended for tools that can handle larger context windows or that retrieve sections
selectively.

## How It Works

Both files are generated during Step 3 of the build pipeline (`great-docs build`), right after the
API reference configuration is refreshed and before the `SKILL.md` is generated. The generation
requires an `api-reference` block in `great-docs.yml`. Without one, both files are silently skipped.

Great Docs imports your package at build time to extract docstrings and signatures. This means the
package must be importable in the build environment. For CI builds, make sure your package is
installed before running `great-docs build`.

The build log shows the generation as a single step:

```
━━ Step 3/18 ─ Generate llms.txt / llms-full.txt ━━━━━━━━
   ✔ Created llms.txt + llms-full.txt                <0.2s
```

## Relationship to Agent Skills

The `llms.txt` files and [Agent Skills](38-agent-skills.qmd) serve complementary purposes:

| | `llms.txt` / `llms-full.txt` | `SKILL.md` |
|---|---|---|
| **Audience** | Any LLM-based tool | AI coding agents specifically |
| **Content** | Auto-generated from code | Hand-written (recommended) or auto-generated |
| **Scope** | Full API surface + docs | Curated cheat sheet: gotchas, decisions, patterns |
| **Size** | Can be very large | Under 500 lines (recommended) |
| **Protocol** | Direct URL fetch | `.well-known` discovery + install CLI |

A typical setup uses both: `llms-full.txt` for comprehensive reference and `SKILL.md` for
opinionated guidance that can't be inferred from code alone. Skills often link to `llms-full.txt`
in their Resources section so agents can pull in more detail when needed.

## Verifying the Output

After a build, you can inspect the generated files directly:

```bash
# Check that both files were created
ls -la great-docs/llms.txt great-docs/llms-full.txt

# Preview the compact index
head -30 great-docs/llms.txt

# Check the size of the full file
wc -l great-docs/llms-full.txt
```

Or visit them on your deployed site:

```
https://your-docs-site.com/llms.txt
https://your-docs-site.com/llms-full.txt
```

If the files are missing after a build, check that your `great-docs.yml` has an `api-reference` block
with at least one section and that the package is importable in the build environment.

## Next Steps

The `llms.txt` files are generated automatically with no configuration required. For more targeted
AI agent context, consider authoring a `SKILL.md` alongside them.

- [Agent Skills](38-agent-skills.qmd): hand-crafted context for AI coding agents
- [Configuration](05-configuration.qmd): all `great-docs.yml` options
- [Building](13-building.qmd): the full build pipeline and step order
- [API Documentation](06-api-documentation.qmd): configuring the `api-reference` sections that
  feed into `llms.txt`



## Site Content

# Collapsible Details

Long pages benefit from progressive disclosure: show a heading, let the reader decide whether to
expand the content beneath it. The `::: {.details}` fenced div turns any block of Markdown into a
collapsible `<details>` element with smooth open/close animation, optional type styling, gradient
backgrounds, accordion grouping, and a gleaming animated border effect.

## Quick Start

Wrap content in a fenced div with the `.details` class:

````markdown
::: {.details summary="Click to expand"}
This content is hidden until the reader clicks the summary.
:::
````

::: {.details summary="Click to expand"}
This content is hidden until the reader clicks the summary.
:::

The `summary` attribute sets the clickable heading text. If omitted it defaults to "Details".
That's all you need for a basic collapsible section. Everything else on this page is optional
enhancement.

## Open by Default

Add the `.open` class to render the section already expanded:

````markdown
::: {.details .open summary="Already visible"}
This section starts expanded. The reader can still collapse it.
:::
````

::: {.details .open summary="Already visible"}
This section starts expanded. The reader can still collapse it.
:::

Use `.open` for content that most readers will want to see immediately but that you still want
to be collapsible for a cleaner page layout when scanning.

## Callout Types

Four semantic types are available via the `type` attribute. Each applies a distinct color scheme
that matches common documentation conventions for notes, warnings, tips, and danger callouts.

````markdown
::: {.details summary="A note" type="note"}
Informational content highlighted in blue.
:::

::: {.details summary="A warning" type="warning"}
Caution-level content highlighted in amber.
:::

::: {.details summary="A tip" type="tip"}
Helpful suggestion highlighted in green.
:::

::: {.details summary="Danger zone" type="danger"}
Critical warning highlighted in red.
:::
````

::: {.details summary="A note" type="note"}
Informational content highlighted in blue.
:::

::: {.details summary="A warning" type="warning"}
Caution-level content highlighted in amber.
:::

::: {.details summary="A tip" type="tip"}
Helpful suggestion highlighted in green.
:::

::: {.details summary="Danger zone" type="danger"}
Critical warning highlighted in red.
:::

Types give readers an immediate visual signal about the nature of the hidden content before they
expand it. They pair well with icons (covered next) for even stronger affordance.

## Icons

Add a Lucide icon to the summary row with the `icon` attribute. The value should be any valid
[Lucide icon name](https://lucide.dev/icons):

````markdown
::: {.details summary="Database migrations" icon="database"}
Run `alembic upgrade head` to apply all pending migrations.
:::

::: {.details summary="Rocket launch checklist" icon="rocket"}
Ensure all pre-flight checks pass before deploying.
:::
````

::: {.details summary="Database migrations" icon="database"}
Run `alembic upgrade head` to apply all pending migrations.
:::

::: {.details summary="Rocket launch checklist" icon="rocket"}
Ensure all pre-flight checks pass before deploying.
:::

Icons are rendered inline at 16px and inherit the summary text color. They work with any
combination of type, gradient, and gleam.

## Accordion Groups

When multiple details elements share the same `group` attribute, they form an accordion: opening
one automatically closes the others. This is useful for FAQ sections, step-by-step flows, or any
context where only one panel should be visible at a time.

````markdown
::: {.details summary="Step 1: Install" group="steps"}
Install the package with `pip install great-docs`.
:::

::: {.details summary="Step 2: Configure" group="steps"}
Create a `_quarto.yml` and add the Great Docs format.
:::

::: {.details summary="Step 3: Build" group="steps"}
Run `quarto render` to produce the site.
:::
````

::: {.details summary="Step 1: Install" group="steps"}
Install the package with `pip install great-docs`.
:::

::: {.details summary="Step 2: Configure" group="steps"}
Create a `_quarto.yml` and add the Great Docs format.
:::

::: {.details summary="Step 3: Build" group="steps"}
Run `quarto render` to produce the site.
:::

Accordion behavior is particularly effective for FAQ pages, multi-step tutorials, and settings
panels where showing all options at once would overwhelm the reader.

## Nesting

Details elements can be nested to create hierarchical disclosure:

````markdown
:::: {.details summary="Outer section"}
This is the outer content.

::: {.details summary="Inner section"}
This is nested inside the first section.
:::
::::
````

:::: {.details summary="Outer section"}
This is the outer content.

::: {.details summary="Inner section"}
This is nested inside the first section.
:::
::::

Nested details work to any depth. Each level animates independently and can carry its own type,
gradient, or gleam styling.

## Rich Content

The body supports any Markdown: code blocks, lists, tables, images, and other shortcodes.

````markdown
::: {.details summary="Code example" type="tip" icon="code"}
Here's a Python snippet:

```python
from great_docs import build
build("my-project")
```

And a bullet list:

- First item
- Second item
- Third item
:::
````

::: {.details summary="Code example" type="tip" icon="code"}
Here's a Python snippet:

```python
from great_docs import build
build("my-project")
```

And a bullet list:

- First item
- Second item
- Third item
:::

Anything you can write in a `.qmd` file works inside the body. The collapsible wrapper is
transparent to Quarto's rendering pipeline, so code highlighting, cross-references, shortcodes,
and math all render normally.

## Theme Gradient

Set `type="gradient"` to apply an animated gradient background that uses your site's accent colors
(configured via `--gd-accent` and `--gd-accent-secondary` in your theme):

````markdown
::: {.details summary="Gradient background" type="gradient"}
The background shifts slowly through your accent palette.
:::
````

::: {.details summary="Gradient background" type="gradient"}
The background shifts slowly through your accent palette.
:::

The theme gradient pulls from `--gd-accent` and `--gd-accent-secondary`, so it automatically
matches your site's branding without any extra configuration.

## Gradient Presets

Eight named gradient presets are available via the `gradient` attribute. Each provides a
hand-crafted color palette with full dark-mode support:

| Preset   | Description                        |
|----------|------------------------------------|
| `sky`    | Soft sky blues                     |
| `peach`  | Warm peach and blush tones         |
| `prism`  | Multi-spectral mint and lavender   |
| `lilac`  | Elegant lilac and pink             |
| `slate`  | Understated cool grays             |
| `honey`  | Rich cream and apricot             |
| `dusk`   | Twilight lavender-blue             |
| `mint`   | Fresh pale aqua                    |

````markdown
::: {.details summary="Sky gradient" gradient="sky"}
A soft blue animated gradient.
:::

::: {.details summary="Peach gradient" gradient="peach"}
Warm peach and blush.
:::

::: {.details summary="Prism gradient" gradient="prism"}
Multi-spectral shimmer.
:::
````

::: {.details summary="Sky gradient" gradient="sky"}
A soft blue animated gradient.
:::

::: {.details summary="Peach gradient" gradient="peach"}
Warm peach and blush.
:::

::: {.details summary="Prism gradient" gradient="prism"}
Multi-spectral shimmer.
:::

::: {.details summary="Lilac gradient" gradient="lilac"}
Elegant lilac and pink.
:::

::: {.details summary="Slate gradient" gradient="slate"}
Understated cool grays.
:::

::: {.details summary="Honey gradient" gradient="honey"}
Rich cream and apricot.
:::

::: {.details summary="Dusk gradient" gradient="dusk"}
Twilight lavender-blue.
:::

::: {.details summary="Mint gradient" gradient="mint"}
Fresh pale aqua.
:::

Every preset includes carefully tuned dark-mode colors. The background animation is a slow
15-second cycle that adds visual texture without being distracting.

## Gleam Effect

Add the `.gleam` class to give the details frame a continuously animated border glow. A bright
spot of light traces the entire outer border in a smooth loop.

````markdown
::: {.details .gleam summary="Gleaming border"}
A subtle light sweeps around this frame.
:::
````

::: {.details .gleam summary="Gleaming border"}
A subtle light sweeps around this frame.
:::

The gleam completes a full revolution every six seconds. In light mode it appears as a white
highlight traveling along a colored border; in dark mode it appears as a colored highlight on
a transparent border. The effect respects `prefers-reduced-motion` and is completely disabled
when the user has motion sensitivity enabled.

### Gleam + Callout Types

The gleam color automatically matches the callout type:

````markdown
::: {.details .gleam summary="Note with gleam" type="note"}
Blue gleam matching the note style.
:::

::: {.details .gleam summary="Warning with gleam" type="warning"}
Amber gleam matching the warning style.
:::

::: {.details .gleam summary="Tip with gleam" type="tip"}
Green gleam matching the tip style.
:::

::: {.details .gleam summary="Danger with gleam" type="danger"}
Red gleam matching the danger style.
:::
````

::: {.details .gleam summary="Note with gleam" type="note"}
Blue gleam matching the note style.
:::

::: {.details .gleam summary="Warning with gleam" type="warning"}
Amber gleam matching the warning style.
:::

::: {.details .gleam summary="Tip with gleam" type="tip"}
Green gleam matching the tip style.
:::

::: {.details .gleam summary="Danger with gleam" type="danger"}
Red gleam matching the danger style.
:::

No extra configuration is needed. The gleam picks up the type's color automatically, so each
variant feels intentional rather than generic.

### Gleam + Gradient Presets

Combine `.gleam` with any gradient preset for animated backgrounds with a matching border glow:

````markdown
::: {.details .gleam summary="Sky with gleam" gradient="sky"}
Animated sky gradient plus a cyan border gleam.
:::

::: {.details .gleam summary="Dusk with gleam" gradient="dusk"}
Twilight gradient plus a purple border gleam.
:::

::: {.details .gleam summary="Mint with gleam" gradient="mint"}
Fresh aqua gradient plus a teal border gleam.
:::
````

::: {.details .gleam summary="Sky with gleam" gradient="sky"}
Animated sky gradient plus a cyan border gleam.
:::

::: {.details .gleam summary="Dusk with gleam" gradient="dusk"}
Twilight gradient plus a purple border gleam.
:::

::: {.details .gleam summary="Mint with gleam" gradient="mint"}
Fresh aqua gradient plus a teal border gleam.
:::

All eight presets work with gleam. The border color is derived from the preset's primary hue,
creating a unified look where the border and background feel like parts of the same design.

### Gleam + Theme Gradient

Pair `.gleam` with `type="gradient"` to use your site accent colors for both the background and
border animation:

````markdown
::: {.details .gleam summary="Theme accent gleam" type="gradient"}
Both the animated gradient and the gleam use your site's accent palette.
:::
````

::: {.details .gleam summary="Theme accent gleam" type="gradient"}
Both the animated gradient and the gleam use your site's accent palette.
:::

The gleam adapts its color to match whatever variant it's paired with (type colors, gradient
presets, or site accent), so the border always feels cohesive rather than bolted on.

## Combining Options

All options can be freely combined. Here are three panels in an accordion group, each using a
different gradient preset with the gleam effect and a custom icon:

````markdown
::: {.details .open .gleam summary="Design" gradient="prism" icon="sparkles" group="showcase"}
Prism gradient, gleam border, icon, and starts expanded.
:::

::: {.details .gleam summary="Development" gradient="sky" icon="code" group="showcase"}
Sky gradient with gleam, in the same accordion group.
:::

::: {.details .gleam summary="Deployment" gradient="mint" icon="cloud-upload" group="showcase"}
Mint gradient with gleam, also in the accordion.
:::
````

::: {.details .open .gleam summary="Design" gradient="prism" icon="sparkles" group="showcase"}
Prism gradient, gleam border, icon, and starts expanded.
:::

::: {.details .gleam summary="Development" gradient="sky" icon="code" group="showcase"}
Sky gradient with gleam, in the same accordion group.
:::

::: {.details .gleam summary="Deployment" gradient="mint" icon="cloud-upload" group="showcase"}
Mint gradient with gleam, also in the accordion.
:::

There are no invalid combinations. Every attribute and class can coexist. The rendering
layers compose naturally: structural behavior (open, group), visual theming (type, gradient),
and effects (gleam, icon) are independent concerns.

## Accessibility

Collapsible details are built on native HTML semantics, so they work out of the box with
assistive technologies and respect user preferences for motion.

- The native `<details>`/`<summary>` HTML elements provide built-in keyboard navigation and screen
  reader support.
- The expand/collapse animation respects `prefers-reduced-motion: reduce`. All animations
  (including gleam and gradient shifts) are disabled when the user prefers reduced motion.
- Type variants use semantic color schemes consistent with standard documentation conventions.

Because the implementation uses standard HTML elements rather than custom JavaScript widgets,
screen readers announce the expanded/collapsed state automatically without any ARIA attributes.

## Attribute Reference

The following table summarizes every attribute and class recognized by the details fenced div.
All are optional and can be combined freely.

| Attribute   | Values                                                   | Description                                      |
|-------------|----------------------------------------------------------|--------------------------------------------------|
| `summary`   | Any text                                                 | Clickable heading (default: "Details")           |
| `type`      | `note`, `warning`, `tip`, `danger`, `gradient`           | Semantic color variant                           |
| `gradient`  | `sky`, `peach`, `prism`, `lilac`, `slate`, `honey`, `dusk`, `mint` | Named gradient preset                  |
| `icon`      | Any Lucide icon name                                     | Icon shown before the summary text               |
| `group`     | Any string                                               | Accordion group name                             |
| `.open`     | Class                                                    | Start expanded                                   |
| `.gleam`    | Class                                                    | Animated border glow                             |

When `type` is set and no explicit `icon` is provided, a default icon is applied automatically
(speech bubble for note, lightning bolt for warning, light bulb for tip, and ban symbol for
danger). You can always override this by specifying the `icon` attribute directly.

## Next Steps

Collapsible details give you a flexible building block for progressive disclosure, from simple
hide/reveal panels to richly styled, animated sections that draw the reader's eye. Combined with
accordion groups and the gleam effect, they can structure complex pages without overwhelming
first-time visitors.

- [Theming](11-theming.qmd): customize `--gd-accent` colors that drive the gradient and gleam effects
- [Configuration](05-configuration.qmd): all `great-docs.yml` options for extensions and filters
- [Horizontal Rules](34-horizontal-rules.qmd): another styled content divider with gradient presets
- [Color Swatches](36-color-swatches.qmd): interactive color palettes using a similar shortcode pattern
- [Building](13-building.qmd): how Lua filters like Details fit into the Quarto build pipeline


# Terminal Recordings

Great Docs includes **Termshow**, a complete solution for recording, editing, and presenting
terminal sessions in your documentation. A Termshow recording captures everything you type and see
in a terminal with precise timing, stores it in a lightweight format, and renders it as an
interactive player on your site.

Unlike video files or animated GIFs, Termshow recordings render as crisp SVGs at any zoom level,
require no external hosting, and work offline. The full pipeline lives inside Great Docs: record,
annotate, and embed with a single shortcode. For annotation, you can either edit the YAML script
file directly or use the **Termshow Editor**, a browser-based visual editor that lets you add
chapters, annotations, and cuts by dragging and clicking rather than writing timestamps by hand.

Here's what a Termshow recording looks like in action. This one shows a typical workflow:
installing a package and verifying it:

{{< termshow file="assets/termshow-demo" pause_on_chapters="true" >}}

The player above is paused at each chapter boundary, waiting for you to press play. This is the
recommended presentation mode for tutorials: each chapter represents one logical step, giving
readers time to absorb what happened before moving on. Click the play button (or press
{{< keys "Space" >}}) to advance through each chapter at your own pace.

The two chapters in this demo correspond to the two stages of the workflow: installing the
package and verifying the result. You define chapters in a companion YAML file, and the player
renders gold markers on the timeline at each boundary.

## Quick Start

### 1. Record a session

Save recordings in your project's `assets/` directory, which is automatically
available to the `{{< termshow >}}` shortcode at build time.

```bash
great-docs termshow record assets/install-guide.termshow
```

This launches a recording session in your terminal. Everything you type and see is captured with
precise timing. Press {{< keys shortcut="Ctrl+D" >}} or type `exit` to end.

During the session, you will see status messages confirming the recording is active:

```
Recording... (cols=80, rows=24)
Press Ctrl+D or type 'exit' to stop.
```

These messages are for your benefit only. They are automatically stripped from the saved file so
viewers never see recorder diagnostics in the final output.

The command creates two files:

- `assets/install-guide.termshow`: the raw recording
- `assets/install-guide.termshow.yml`: a script template with commented sections

With the raw recording saved and the script template in place, you're ready to shape the
presentation.

### 2. Edit the script file

Open `assets/install-guide.termshow.yml` and uncomment/fill in the sections you need (or use the
Termshow Editor with `great-docs termshow edit assets/install-guide.termshow`):

```yaml
source: assets/install-guide.termshow

settings:
  window_chrome: colorful

chapters:
  - at: 0.0
    label: Setup
  - at: 8.0
    label: Install
  - at: 15.0
    label: Verify

annotations:
  - at: 1.0
    duration: 3.0
    text: Start by activating the virtual environment
    position: top-right
    style: callout
```

### 3. Embed in a page

```{shortcodes="false"}
{{< termshow file="assets/install-guide" pause_on_chapters="true" >}}
```

That single line is all you need. The shortcode handles discovery, rendering, and embedding
automatically during the build step.

### 4. Build

```bash
great-docs build
```

During the build, Great Docs automatically finds all `.termshow` files, renders them into SVG
keyframes, and embeds the data inline in your HTML pages. No runtime fetches are needed.

That's the entire workflow: record, annotate, embed, and build. The following sections cover each
piece in detail.

## The Recording Format

A Termshow recording consists of two files that work together: a raw capture file (`.termshow`)
and an optional script file (`.termshow.yml`). The capture file stores exactly what happened in
the terminal with precise timing. The script file layers presentation choices on top: where to
place chapters, what annotations to show, which segments to cut. This separation means you never
need to re-record just to change how something is presented.

### `.termshow` files

The raw recording is stored as NDJSON (newline-delimited JSON). The first line is a header with
terminal metadata; subsequent lines are events:

```json
{"version": 1, "format": "termshow", "term": {"cols": 80, "rows": 20}, "title": "My Demo"}
[0.5, "o", "$ "]
[0.0, "i", "echo hello"]
[0.1, "o", "echo hello"]
[0.6, "o", "\r\nhello\r\n"]
[1.0, "m", "Step complete"]
[0.3, "o", "$ "]
[0.0, "i", "date"]
[0.1, "o", "date"]
[0.4, "o", "\r\nWed May 28 09:15:03 UTC 2026\r\n"]
```

Each event is `[delay_seconds, type, data]`. The delay is relative to the previous event (not
absolute), and the type code identifies what kind of data the event carries:

| Type | Meaning |
|------|---------|
| `"o"` | Output: data written to the terminal |
| `"i"` | Input: user keystrokes (for display) |
| `"m"` | Marker: internal sync point for chapters |

You rarely need to edit `.termshow` files by hand. The recorder and importer produce them, and
the script file controls how they are presented.

### `.termshow.yml` script files

The companion YAML file controls how the recording is presented. It adds chapters, annotations,
cuts, highlights, and visual settings:

```yaml
source: assets/my-recording.termshow

settings:
  window_chrome: colorful     # Window decoration style
  theme: monokai              # Terminal color scheme
  font_family: "JetBrains Mono, Fira Code, monospace"
  font_size: 14               # Font size in rendered SVG (px)
  line_height: 1.2            # Line height multiplier
  padding: 12                 # Inner padding (px)
  prompt: "❯"                 # Replace detected prompts with ❯

chapters:
  - at: 0.0
    label: Introduction
  - at: 5.0
    label: Configuration
  - at: 12.0
    label: Running Tests

annotations:
  - at: 1.0
    duration: 3.0
    text: This installs all required dependencies
    position: top-right
    style: callout
  - at: 6.0
    duration: 2.5
    text: Configuration is auto-detected
    position: bottom-right
    style: subtle

cuts:
  - from: 8.0
    to: 11.0
    type: ellipsis

highlights:
  - at: 12.5
    duration: 3.0
    target:
      match: 'All \\d+ tests passed'
    style: spotlight
    color: "#50fa7b"
    fade_in: 0.3
```

All fields are optional except `source`. Start with just chapters and add annotations, cuts, or
highlights as you refine the presentation.

## Settings Reference

The `settings` block in your `.termshow.yml` controls how the recording is rendered into SVG
frames. All settings are optional and have sensible defaults.

| Setting | Default | Description |
|---------|---------|-------------|
| `window_chrome` | `colorful` | Window decoration style |
| `theme` | (auto) | Terminal color scheme |
| `font_family` | (system stack) | Font family for rendered SVG |
| `font_size` | `14` | Font size in px |
| `line_height` | `1.2` | Line height multiplier |
| `padding` | `12` | Inner padding in px |
| `prompt` | (none) | Prompt replacement character |
| `prompt_pattern` | (none) | Prompt detection regex |

The `window_chrome` setting accepts `colorful` (traffic-light buttons), `plain` (grey dots), or
`none` (no title bar). The `font_family` value is a comma-separated list passed directly to the
SVG `font-family` attribute. The `prompt` and `prompt_pattern` settings work together for prompt
substitution, described in the next section.

These settings are applied at render time. Changing them requires re-rendering but not
re-recording.

## Prompt Substitution

Terminal recordings often contain shell prompts that are visually noisy or environment-specific
(e.g., `user@host:~/project $`). The **prompt substitution** feature lets you replace the
prompt character in rendered output with a clean, consistent symbol.

### Configuration

Add `prompt` (and optionally `prompt_pattern`) to your script's `settings` block:

```yaml
settings:
  prompt: "❯"
```

This replaces detected prompt characters with `❯` in all rendered frames. Common replacement
choices include `$`, `%`, `#`, `>`, `❯`, and `→`.

### How detection works

Prompt substitution uses a three-tier detection strategy, applied in order of precision:

1. **Structural detection** (most precise): If the recording contains input (`"i"`) events,
   the renderer correlates them with cursor position to identify exactly which rows have
   prompts and where the prompt character sits. This is fully automatic and requires no
   additional configuration.

2. **Pattern detection** (explicit): If you provide `prompt_pattern`, the renderer uses it as
   a regex to match prompt lines. The last character of the match is replaced. Use this when
   your recording lacks input events or when the structural detection doesn't match your
   prompt format:

   ```yaml
   settings:
     prompt: "$"
     prompt_pattern: '^\S+@\S+[^$]*\$ '
   ```

3. **Heuristic detection** (automatic fallback): When neither input events nor a pattern are
   available, the renderer scans each row for lines that begin with a known prompt character
   (`$`, `%`, `#`, `>`, `❯`, `→`, etc.) followed by a space. This works well for simple
   prompt formats.

The tiers are tried in order: structural first, then pattern, then heuristic. Once a tier matches a
given row, the lower tiers are skipped for that row. In practice, most recordings have input events
and structural detection handles everything automatically.

### Examples

Replace a verbose prompt with a minimal symbol:

```yaml
settings:
  prompt: "❯"
```

Before: `user@dev:~/project$ echo hello`\
After: `❯ echo hello`

Use a regex for non-standard prompts:

```yaml
settings:
  prompt: "$"
  prompt_pattern: '^\(venv\) .*\$ '
```

This matches prompts like `(venv) user@host:~$ ` and replaces just the `$` character.

### Tips

Here are some practical guidelines for working with prompt substitution:

- start with just `prompt`: structural and heuristic detection handle most cases automatically
- add `prompt_pattern` only if the default detection misidentifies prompt lines
- the substitution affects rendered SVG frames only (the raw recording is never modified)
- the Termshow Editor shows prompt substitution live in the preview, so you can see the
  effect immediately as you configure it

In most cases, a single `prompt` line in your settings block is all you need. The detection system
is designed to do the right thing without manual tuning.

## Shortcode Reference

Embed a Termshow recording in any page with the `termshow` shortcode. At its simplest, you only need
the `file` path:

```{shortcodes="false"}
{{< termshow file="assets/my-demo" >}}
```

The shortcode discovers the companion `.termshow.yml` script, renders the recording into SVG frames,
and embeds everything inline during the build. No additional configuration or runtime fetches are
required.

### Options

The shortcode accepts the following options to control player behavior:

| Option | Default | Description |
|--------|---------|-------------|
| `file` | *(required)* | Path to the `.termshow` file (without extension) |
| `autoplay` | `"false"` | Start playing automatically on page load |
| `loop` | `"false"` | Loop playback when reaching the end |
| `speed` | `"1"` | Initial playback speed multiplier |
| `pause_on_chapters` | `"false"` | Auto-pause at each chapter boundary |
| `controls` | `"true"` | Show the control bar |
| `theme` | `"auto"` | Player theme: `auto`, `dark`, or `light` |

All options are specified as key-value attributes on the shortcode. Unrecognized options are
silently ignored, so you can safely add new ones as they become available.

### Examples

The following examples show common shortcode patterns, from a minimal embed to more tailored
presentations.

A basic embed with default settings (manual play, 1× speed, controls visible):

```{shortcodes="false"}
{{< termshow file="assets/getting-started" >}}
```

A chapter-pausing tutorial that stops at each chapter boundary so readers can follow along:

```{shortcodes="false"}
{{< termshow file="assets/workflow" pause_on_chapters="true" >}}
```

A fast autoplay preview for hero sections or landing pages:

```{shortcodes="false"}
{{< termshow file="assets/quick" autoplay="true" speed="1.5" >}}
```

Combine options freely. For instance, `autoplay` with `loop` creates a continuously cycling
demonstration, while `pause_on_chapters` with `speed="1.5"` produces a brisk but controlled
tutorial.

The shortcode is the only integration point between your Quarto pages and the Termshow pipeline.
Everything else (recording, scripting, rendering) happens automatically during the build.

## Player Controls

The embedded player provides interactive controls for navigating recordings. The following sections
describe what each component does.

### Control Bar

The control bar sits along the bottom edge of the player and provides everything you need to
navigate a recording. Its elements are arranged left to right:

1. **Play / Pause / Replay**: Toggles playback. Shows ↺ at the end of the recording.
2. **Elapsed time**: Current playback position.
3. **Timeline**: Click anywhere to seek. Gold chapter markers indicate chapter boundaries; their hit
targets are wider than the visible marks for easy clicking.
4. **Remaining time**: Counts down to zero during playback.
5. **Speed**: Cycles through 0.5×, 1×, 1.5×, 2×, 3×.

All controls are keyboard-accessible and respond to the shortcuts listed below.

### Chapter Bar

A semi-transparent overlay at the top of the player displays the current chapter name. It updates
as playback progresses and when pausing at chapter boundaries.

### Center Overlay

The center overlay provides a large, easy-to-hit target for the most common playback actions. It
appears as a semi-transparent button in the middle of the viewport and adapts to the current player
state:

- **Before playback**: Shows ▶ as a play call-to-action.
- **After playback ends**: Shows ↺. Clicking it returns the player to its initial state (frame 0)
  without auto-playing.
- **During chapter pauses**: Hidden, so the terminal content remains fully visible for reading.

The overlay never obscures content during active playback; it only appears when the player is
waiting for user input.

### Double-Tap to Seek

During playback (or when the recording has ended), double-tapping or double-clicking the left or
right third of the viewport seeks backward or forward by 5 seconds. This mirrors the seek gesture
familiar from video players: tap the left edge to rewind, or the right edge to skip ahead. Taps in
the middle 40% of the viewport are ignored to avoid conflicts with the center overlay.

### Keyboard Shortcuts

The player supports keyboard navigation once it has focus. Click anywhere on the viewport to
activate it, then use the following keys:

| Key | Action |
|-----|--------|
| {{< keys "Space" >}} | Play / Pause (or reset from ended state) |
| {{< keys "→" >}} | Seek forward 5 seconds |
| {{< keys "←" >}} | Seek backward 5 seconds |
| `]` | Jump to next chapter |
| `[` | Jump to previous chapter |

All shortcuts require the player to have focus. Click anywhere on the player viewport first.

## Chapters

Chapters divide a recording into labeled sections. They appear as gold markers on the timeline and
enable `pause_on_chapters` mode for step-by-step tutorials.

```yaml
chapters:
  - at: 0.0
    label: Introduction
  - at: 5.0
    label: Installation
  - at: 12.0
    label: Configuration
```

The `at` field is the timestamp in seconds. The `label` is shown in the chapter bar and as a
tooltip on the timeline marker.

### Tips

Here are some guidelines for effective chapter placement:

- Place chapters at logical transitions. Each should represent one distinct step.
- The first chapter at `0.0` names what's on screen before the viewer presses play.
- Use `pause_on_chapters="true"` for tutorials where readers need time to absorb each step.

Well-placed chapters transform a continuous recording into a structured, navigable lesson that
readers can work through at their own pace.

## Annotations

Annotations are contextual overlays that appear at specific timestamps to explain what's happening
in the terminal:

```yaml
annotations:
  - at: 2.0
    duration: 3.0
    text: This installs all dependencies from requirements.txt
    position: top-right
    style: callout
    width: medium
```

Annotations are purely presentational: they don't affect timing or terminal output, and you can
add or remove them at any point without re-recording.

### Styles

Each annotation has a `style` that controls its visual weight:

| Style | Appearance |
|-------|------------|
| `callout` | Dark semi-opaque card with accent border: draws focus |
| `subtle` | Lighter, smaller text: less intrusive |
| `highlight` | Amber-tinted with warm border: strong emphasis |

Choose the style that matches the annotation's importance. Most recordings need only `callout`
and `subtle`; reserve `highlight` for critical warnings or pivotal steps.

### Positions

Annotations can be placed at any edge or corner of the terminal viewport:

| Position | Placement |
|----------|-----------|
| `top-left` | Top-left corner |
| `top` | Top center |
| `top-right` | Top-right corner |
| `left` | Vertically centered, left edge |
| `right` | Vertically centered, right edge |
| `bottom-left` | Bottom-left corner |
| `bottom` | Bottom center |
| `bottom-right` | Bottom-right corner (default) |

Place annotations where they won't cover the terminal text you're explaining. `top-right` is a
good default because most CLI output scrolls along the left edge.

### Width

Control how wide an annotation can grow with the `width` field:

| Width | Max width |
|-------|-----------|
| `small` | 25% of the viewport |
| `medium` | 50% of the viewport (default) |
| `large` | 75% of the viewport |

Use `small` for brief one-word labels, `large` for longer explanations that need breathing room.

### Tips

Keep these principles in mind when adding annotations:

- Keep text to one sentence. Annotations complement the terminal output, not replace it.
- Use `callout` for important explanations, `subtle` for minor context.
- Ensure `duration` is long enough to read at 1.5× speed.

Good annotations enhance comprehension without competing with the terminal content for the
viewer's attention. When in doubt, shorter and fewer is better.

## Cuts

Terminal recordings often contain dead time: waiting for a package to download, watching a
progress bar crawl, or pausing to think about the next command. Cuts let you remove these
segments from the viewer's experience without re-recording. The raw file stays intact; cuts
are purely a playback instruction that tells the player to skip a time range.

```yaml
cuts:
  - from: 8.0
    to: 11.0
    type: ellipsis
```

The `from` and `to` fields define the time range to skip (in seconds). The `type` field
controls what viewers see during the cut:

| Value | Effect |
|-------|--------|
| `jump` | Seamless jump (no visual indicator) |
| `ellipsis` | Shows "…" briefly to indicate skipped time |

Use `jump` for short gaps where continuity isn't important (e.g., trimming a 2-second pause
between commands). Use `ellipsis` for longer skips where viewers should know time was removed
(e.g., a 30-second download reduced to a single "…" flash).

Cuts are non-destructive: they are stored in the script file, not applied to the raw recording.
You can always remove or adjust them later.

## Snippets

Snippets let you add a **copy button** to the player that appears during a time range. When visible,
readers can click it to copy the associated text to their clipboard: no manual retyping needed.

```yaml
snippets:
  - at: 0.5
    duration: 7.0
    text: "pip install great-tables"
    label: Install
  - at: 8.0
    duration: 6.0
    match: '\$ (.+)'
    label: Verify
```

You can provide text in two ways:

- **`text`**: a literal string that gets copied verbatim
- **`match`**: a regex run against the terminal buffer at that moment; copies the first capture
group (or the full match if no group is defined)

If both are set, `match` takes priority (with `text` as fallback if the regex doesn't match).

### Fields

Each snippet entry in the YAML accepts the following fields:

| Field | Default | Description |
|-------|---------|-------------|
| `at` | *(required)* | Time in seconds when the button appears |
| `duration` | `5.0` | How long the button stays visible |
| `text` | `""` | Literal text copied to the clipboard on click |
| `match` | `""` | Regex pattern matched against the visible terminal text |
| `label` | `"Copy"` | Button label shown alongside the copy icon |

At least one of `text` or `match` must be provided.

The button fades in and out smoothly, just like annotations. It appears in the **title bar** at
the far right of the player. Only one snippet button is visible at a time. If time ranges overlap,
the first one wins and subsequent ones are hidden.

### Tips

Practical guidance for working with snippets:

- Snippet time ranges **must not overlap**. The Editor enforces this; if you write overlapping
  ranges manually in YAML, only the first active snippet is shown.
- Align snippets with chapters: set `at` to the chapter start time and `duration` to the chapter
  length. This way the copy button is visible for the entire step.
- Use `text` when you know the exact string (e.g., a `pip install` invocation). Don't include
  prompts (`$`).
- Use `match` when the text is dynamic or you want to extract from what's visible. For example,
  `'\$ (.+)'` matches any shell prompt line and captures just the command. Use single quotes in
  YAML to avoid backslash escape issues.
- Use `label` to give context (e.g., "Install", "Build", "Test") so readers know what they're
  copying without reading the full snippet.
- Snippets work regardless of playback state: readers can copy while paused, playing, or at a
  chapter stop.

Snippets bridge the gap between watching and doing. By giving readers one-click access to the
exact commands shown in the recording, you eliminate transcription errors and reduce friction.

## Highlights

Highlights draw attention to specific terminal text during playback. Unlike annotations (which float
in corners), highlights are **attached to the terminal text itself**: they decorate characters
in-place, can follow scrolling, and support rich adornment styles.

Multiple highlights can be active simultaneously, and overlapping highlights stack naturally
(later ones render on top).

```yaml
highlights:
  - at: 8.0
    duration: 2.0
    target:
      region: { row: 5, col: 0, width: 40, height: 1 }
    style: box
    color: "#f1fa8c"
  - at: 10.0
    duration: 4.0
    target:
      match: 'Successfully installed (.+)'
      group: 1
    style: spotlight
    color: "#50fA7B"
```

### Targeting

A highlight must identify *which text* to decorate. Three targeting modes are available:

| Mode | YAML Key | Description |
|------|----------|-------------|
| **Region** | `target.region` | Fixed rectangle: `{ row, col, width, height }` (0-indexed) |
| **Pattern** | `target.match` | Regex matched against the visible terminal text each frame |
| **Lines** | `target.lines` | List of 0-indexed row numbers to highlight entirely |

For pattern matches, an optional `target.group` (default `0`) selects which capture group to
highlight. This lets you match context (e.g., a full line) while only decorating the interesting
part (e.g., a flag name).

**Scroll tracking.** Terminal output scrolls. A region-based highlight is positional: row 5
stays at row 5 even after scrolling pushes new content into that row. Set `target.track_scroll:
true` to have the highlight follow the matched text as it moves. Scroll tracking only works
with `target.match` (the renderer re-runs the regex each frame to locate the text's new position):

```yaml
highlights:
  - at: 20.0
    duration: 8.0
    target:
      match: 'error:'
      track_scroll: true
    style: underline-wavy
    color: "#ff5555"
```

### Styles

Each highlight has a `style` that controls its visual adornment:

| Style | Visual | Notes |
|-------|--------|-------|
| `box` | Bordered rectangle around text | Default style; technical look |
| `underline` | Underline beneath text | Solid or wavy (set via subtype) |
| `background` | Semi-transparent background fill | Good for multi-line selections |
| `spotlight` | Dims everything *except* the target | Viewport-wide dimming with cutout |
| `badge` | Small label pill adjacent to text | Position: before or after |
| `bracket` | Curly brace spanning lines | For grouping multiple rows |

### Badge Details

Badge style attaches a small inline pill adjacent to the highlighted text:

```yaml
highlights:
  - at: 18.0
    duration: 5.0
    target:
      match: '--verbose'
    style: badge
    badge_text: "recommended"
    color: "#8be9fd"
```

The `badge_text` field sets the label inside the badge. Use the badge position control in the
Properties Panel to place it before or after the matched text. Badges will wrap to the opposite
side if they would overflow the viewport.

### Animation & Transitions

Highlights support animated entry and exit:

| Field | Default | Description |
|-------|---------|-------------|
| `fade_in` | `0` | Duration of the appear transition (seconds) |
| `fade_out` | `0` | Duration of the disappear transition (seconds) |
| `pulse` | `false` | Gentle pulsing animation that loops continuously |

When `pulse` is enabled, the highlight's opacity oscillates between 100% and 50% on a 1.5-second
cycle with an ease-in-out curve. The animation runs for the entire duration of the highlight. This
works well for drawing attention to transient output or short-lived highlights where you want
sustained visual emphasis.

### Fields Reference

The complete set of fields available for each highlight entry:

| Field | Default | Description |
|-------|---------|-------------|
| `at` | *(required)* | Time in seconds when the highlight appears |
| `duration` | *(required)* | How long the highlight remains visible |
| `target` | *(required)* | Targeting object (see above) |
| `style` | `"box"` | Adornment style (see table above) |
| `color` | `"#f1fa8c"` | Adornment color (hex or rgba) |
| `opacity` | `1` | Overall opacity of the highlight (0–1) |
| `badge_text` | `""` | Label text for badge styles |
| `pulse` | `false` | Enable pulsing animation |
| `fade_in` | `0` | Appear transition duration (seconds) |
| `fade_out` | `0` | Disappear transition duration (seconds) |

Only `at`, `duration`, and `target` are required. All other fields have sensible defaults and
can be omitted for simple highlights.

### Examples

The following examples illustrate common highlight patterns, from simple region markers to animated
spotlights.

Highlight a fixed region of the terminal:

```yaml
highlights:
  - at: 3.0
    duration: 4.0
    target:
      region: { row: 2, col: 0, width: 80, height: 3 }
    style: background
    color: "rgba(255, 184, 108, 0.15)"
```

Call out a specific flag using regex with a badge:

```yaml
highlights:
  - at: 12.0
    duration: 5.0
    target:
      match: '--output'
    style: badge
    badge_text: "new in v2"
    color: "#bd93f9"
```

Spotlight an important result (dims the rest of the viewport):

```yaml
highlights:
  - at: 10.0
    duration: 3.0
    target:
      match: 'All tests passed'
    style: spotlight
    color: "#50fa7b"
    fade_in: 0.3
    fade_out: 0.3
```

These patterns combine freely. A single recording might use `background` for broad context, `badge`
to label a new flag, and `spotlight` for the final result (layering visual cues without competing
for attention).

### Tips

Guidelines for effective use of highlights:

- Highlights are purely visual: they don't affect timing or terminal output.
- Multiple highlights can overlap in time. Unlike snippets, there is no exclusivity rule.
- Use `spotlight` sparingly: it dims the entire viewport and works best for one focal point.
- Combine `pulse: true` with short highlights to draw the eye to transient output.
- Use `track_scroll: true` when highlighting text that may scroll off-screen during the
  highlight's duration.

Highlights are your most expressive tool for directing the viewer's eye. Used judiciously, they
turn a passive recording into an active guided tour of the terminal output.

## Importing Existing Recordings

Already have terminal recordings from asciinema? Import them:

```bash
# From asciinema (.cast files)
great-docs termshow import-cast recording.cast assets/my-demo
```

The import preserves timing and terminal dimensions. Create a `.termshow.yml` script afterward to
add chapters and annotations.

The importer produces the same `.termshow` format, so all editing and rendering features work
identically regardless of the original source.

## Rendering & Preview

You can preview and render recordings outside of a full site build using these CLI commands:

### Preview in terminal

```bash
great-docs termshow play assets/my-demo.termshow
```

Plays the recording directly in your terminal for quick review.

### Render SVG frames manually

```bash
great-docs termshow render assets/my-demo.termshow
```

Generates the SVG keyframes and `manifest.json` without a full site build. Useful for inspecting
the output or debugging chapter timing.

Both commands work with any `.termshow` file that has a companion `.termshow.yml` script.

## Best Practices

These guidelines help produce recordings that are clear, fast-loading, and pleasant to watch:

- **Keep recordings short**: 15–30 seconds is ideal. Split longer workflows into multiple
  recordings, each embedded with its own shortcode.
- **Use cuts to trim dead time**: Mark boring pauses (downloads, progress bars) as cuts so
  viewers skip them entirely.
- **80 columns, 20 rows** works well for CLI demos. Use 120 columns for wide output like log
  lines or tables. The Termshow Editor auto-scales the preview to fit any terminal size, so
  larger dimensions won't overflow the viewport.
- **Test at different speeds**: Make sure annotations are readable at 1.5× and 2×.
- **Place recordings in `assets/`**: Keep them in a dedicated directory at your project root.
  The build system discovers them automatically.

Following these guidelines ensures your recordings feel polished and load quickly, even on slower
connections.

## How It Works

The Termshow pipeline has two phases:

**Build time** (automatic during `great-docs build`):

1. Discovers all `.termshow` files in the project root
2. Parses each recording + its YAML script
3. Renders SVG keyframes at each visual change point
4. Generates `manifest.json` with timing, chapters, and annotations
5. The Quarto shortcode filter embeds the manifest and all SVGs inline as JSON

**Page load** (JavaScript, no network requests):

1. Reads inline manifest and SVG data from embedded `<script>` elements
2. Builds the player UI (viewport, controls, chapter bar, overlays)
3. On play: advances time via `requestAnimationFrame`, swaps SVG frames at correct timestamps

This architecture means zero runtime fetches, full offline support (including `file://` protocol),
and pixel-perfect SVG rendering at any zoom level.

## The Termshow Editor

The Termshow Editor is a browser-based non-linear editor (NLE) for `.termshow` recordings. It
lets you visually add, move, and fine-tune chapters, annotations, and cuts without editing YAML
by hand.

### Launching the Termshow Editor

```bash
great-docs termshow edit assets/my-demo.termshow
```

This opens a local web app at `http://127.0.0.1:8765`. The Termshow Editor loads the recording
and its companion `.termshow.yml` script file (creating one if it doesn't exist). Use `--port`
to change the port or `--no-browser` to suppress the automatic browser launch.

### Interface Layout

![The Termshow Editor interface with every named component labeled.](../assets/termshow-editor-diagram.png)

The Termshow Editor is divided into these primary areas:

**Header Bar.** The top bar shows the editor title and filename, along with action buttons organized
into thematic groups:

**Editing actions** (left):

- **+ Chapter**: add a chapter marker at the current playhead position (shortcut: {{< keys "C" >}})
- **+ Annotation**: add a 2-second annotation at the playhead (shortcut: {{< keys "A" >}})
- **+ Cut**: mark a cut region at the playhead (shortcut: {{< keys "X" >}})
- **+ Snippet**: add a snippet at the playhead (shortcut: {{< keys "D" >}})
- **+ Highlight**: add a highlight at the playhead (shortcut: {{< keys "H" >}})

**Layout presets** (center): A segmented button with three view presets that control the
split between the Preview Area and the Timeline Panel:

- **Preview**: 75/25 split: maximizes the terminal view for inspecting output
- **Balanced**: 50/50 split: equal space for preview and timeline (default)
- **Timeline**: 25/75 split: maximizes the timeline for detailed editing

**Document actions** (right):

- **YAML**: View the generated YAML script (shortcut: {{< keys "Y" >}})
- **▶ Preview**: Open the production preview modal (shortcut: {{< keys "P" >}})
- **Save**: Write changes to the `.termshow.yml` file (shortcut: {{< keys shortcut="Cmd+S" >}} /
  {{< keys shortcut="Ctrl+S" >}}). Pulses gold when there are unsaved changes.

**Preview Area.** The center panel shows a live terminal preview. It renders the recording state at
the current playhead position, updating in real time as you scrub, drag edges, or play back.

The viewport uses **auto-fit scaling**: the terminal always renders at its native character grid
(matching the recorded dimensions), then scales proportionally to fill the available space. This
means wide recordings (120 columns) and tall recordings (40+ rows) display without clipping or
scrollbars. When you expand the preview area (via the resize handle or layout presets), the terminal
scales up to fill it. The scaling recalculates on window resize and during drag.

Above the terminal viewport, a **Chapter Title Bar** displays the currently active chapter name,
simulating the window chrome appearance of the final player.

**Settings Button**: A small circular gear (⚙) button sits in the top-left corner of the
Preview Area, next to the Info Button. Clicking it (or pressing {{< keys "G" >}}) toggles the
**Settings Panel** described above.

**Info Button**: A small circular *i* button sits in the top-left corner of the Preview Area.
Clicking it (or pressing {{< keys "I" >}}) toggles the **Info Panel**, a floating overlay showing
recording metadata:

- terminal dimensions (cols × rows)
- duration (effective, accounting for cuts; raw duration shown in parentheses when cuts exist)
- event count (total and output events)
- chapter, annotation, and cut counts
- source file size
- estimated keyframe count and rendered SVG size

The Info Panel updates live as you add or remove items. Click the `×` in its top-right corner
or press {{< keys "I" >}} again to dismiss it.

**Resize Handle.** A draggable divider between the Preview Area and the Transport/Timeline section.
Drag it down to enlarge the terminal preview (the terminal scales up to fill), or drag it up to give
more space to the timeline tracks. The preview area has a minimum height of 150px, and the timeline
area is clamped so all three tracks remain visible. Manually dragging clears the active layout
preset indicator.

**Transport Controls.** Below the resize handle, centered transport controls provide:

- **Rewind** (⏮): Jump to the start of the recording
- **Previous Chapter** (⏴): Jump to the previous chapter marker (shortcut: `[`)
- **Play/Pause** (▶/⏸): Toggle playback (shortcut: {{< keys "Space" >}})
- **Next Chapter** (⏵): Jump to the next chapter marker (shortcut: `]`)
- **Timecode Display**: Shows elapsed time / total duration in `MM:SS.cc` precision. Click the
  current-time value to type an exact position (e.g., `01:23.45`) and press {{< keys "Enter" >}} to jump there.

**Timeline Panel.** The bottom panel contains five track lanes beneath a **Timeline Ruler**, the
graduated strip showing time markings. Click anywhere on the ruler to reposition the playhead
instantly, or drag the playhead indicator to scrub through the recording. The ruler is the safest
place to navigate without accidentally selecting or creating items.

1. **Chapters Track**: Gold vertical markers. Click a marker to select it; drag to reposition.
   Double-click empty space to add a new chapter with placeholder text.

2. **Annotations Track**: Green boxes spanning their time duration. The annotation text is shown
   inside each box (clipped if too long). Click a box to select it; drag to reposition.
   Boxes have left and right edge handles for resizing. Double-click empty space to add a 2-second
   placeholder; drag across the track to create a custom-duration annotation.

3. **Cuts Track**: Red (ellipsis) or purple-dashed (seamless) blocks. A centered `⋯` symbol
   distinguishes ellipsis cuts. Click a box to select it; drag to reposition. Boxes have edge
   handles. Double-click empty space to add a 2-second cut; drag across the track to create a
   custom-length cut.

4. **Snippets Track**: Blue boxes showing the snippet text. Click a box to select it; drag to
   reposition. Boxes have edge handles for resizing the time range. Double-click empty space to
   add a 5-second placeholder; drag across the track to create a custom-duration snippet.

5. **Highlights Track**: Color-coded boxes styled per highlight type (cyan for box, green for
   underline, yellow for background, orange for spotlight, pink for badge). Click a box to select
   it; drag to reposition. Boxes have edge handles for resizing. Double-click empty space to add
   a 3-second highlight; drag across the track to create a custom-duration highlight. Unlike
   snippets, **highlights may overlap in time** (multiple highlights can be active simultaneously).

A **Playhead** (white vertical line) spans all five tracks and moves with the current time.

### Global Settings Panel

The Termshow Editor includes a **Global Settings** panel for configuring global script settings
visually. Click the gear icon (⚙) in the top-left corner of the Preview Area or press
{{< keys "G" >}} to toggle it.

The Settings panel exposes the following controls:

| Control | Description |
|---------|-------------|
| **Default speed** | Playback speed multiplier (dropdown: 0.5×, 1×, 1.5×, 2×, 3×) |
| **Chrome** | Window decoration style (dropdown: colorful, simple, none) |
| **Font family** | Comma-separated font stack for rendered output |
| **Prompt** | Replacement character for prompt substitution, with preset buttons |
| **Pattern** | Regex pattern for prompt detection (see [Prompt Substitution]) |

All changes apply immediately to the live preview so you can see the effect of each setting in real
time. Settings are saved to the `settings` block of the `.termshow.yml` file when you press Save.

Press {{< keys "Escape" >}} or click outside the panel to dismiss it.

### Properties Panel

Clicking any item in the timeline opens the **Properties Panel** on the right side. The panel adapts
to show fields relevant to the selected item type, and all edits are live: changes apply immediately
as you type, with no Apply button needed.

For **chapters**, the panel shows the timestamp and label text. **Annotations** add duration, the
annotation body, and dropdowns for position, width, and style. **Cut regions** expose the start and
end times along with the cut type (jump or ellipsis). **Snippets** include the time range, literal
copy text or regex match pattern, and a label for the button.

**Highlights** have the richest panel: in addition to timing and style, you can configure the target
(a fixed region, regex pattern, or line list), color and opacity, fade transitions, pulse animation,
and badge-specific options like label text and placement.

Every panel also includes an **Undo** button (which reverts the item to its state when the panel
opened) and a **Delete** button to remove the item entirely. Because changes are live, you can watch
the terminal preview update as you adjust values.

### Edge Editing

Annotation boxes, cut regions, snippet boxes, and highlight boxes all have draggable edge handles
(left and right). When you grab an edge:

1. The **playhead snaps** to that edge's time position, showing the exact terminal frame at the
boundary.
2. The edge displays a **prominent vertical stem** extending beyond the track (green for
annotations, red for cuts, blue for snippets, style-colored for highlights) with a directional
glow so you know which side is active.
3. **Arrow keys** (← →) nudge the active edge by ±10ms for frame-accurate positioning. The
playhead tracks the edge so you can see the terminal state update with each nudge.

Clicking elsewhere or pressing {{< keys "Escape" >}} deselects and restores normal edge appearance.

### Drag-to-Create

On the Annotations, Cuts, Snippets, and Highlights tracks, clicking and dragging across empty
space creates a new item spanning the drag distance. The drag only initiates after a 4-pixel
movement threshold, preventing accidental creation from stray clicks. If you want a fixed-size
item without dragging, double-click instead (creates a 2-second item for annotations/cuts,
5-second for snippets, or 3-second for highlights).

### Cut Types

The two cut types have distinct visual appearances in the timeline:

| Type | Appearance | Playback Effect |
|------|-----------|-----------------|
| **Seamless** | Purple dashed block (no symbol) | Silent jump with no visual indicator |
| **Ellipsis** | Solid red block with `⋯` symbol | Shows a 1 second "⋯" overlay during playback |

Switch between types using the "Replace With" dropdown in the properties panel.

### Keyboard Shortcuts

The Termshow Editor supports these keyboard shortcuts for efficient editing:

| Key | Action |
|-----|--------|
| {{< keys "Space" >}} | Play / Pause |
| {{< keys "C" >}} | Add chapter at playhead |
| {{< keys "A" >}} | Add annotation at playhead |
| {{< keys "X" >}} | Add cut at playhead |
| {{< keys "D" >}} | Add snippet at playhead |
| {{< keys "H" >}} | Add highlight at playhead |
| {{< keys "G" >}} | Toggle global settings panel |
| {{< keys "I" >}} | Toggle info panel |
| {{< keys "←" >}} / {{< keys "→" >}} | Seek ±1 second (or nudge active edge ±10ms) |
| `[` / `]` | Jump to previous / next chapter |
| {{< keys "Y" >}} | View YAML |
| {{< keys "P" >}} | Preview |
| {{< keys "Delete" >}} / {{< keys "Backspace" >}} | Delete selected item |
| {{< keys "Escape" >}} | Close settings/properties panel, deselect |
| {{< keys shortcut="Cmd+S" >}} / {{< keys shortcut="Ctrl+S" >}} | Save |

### Unsaved Changes

Any modification (adding, moving, editing, or deleting items) marks the session as dirty. The
Save button changes to Save* with a pulsing gold glow to indicate unsaved changes. Saving resets the
indicator.

### Preview

The **Preview** button (shortcut: {{< keys "P" >}}) opens a full-screen modal showing your recording
exactly as it will appear on a built site. Unlike the in-editor live preview (which shows the raw
SVG frame at the current playhead), the Preview modal renders the complete player using Quarto with
the production `termshow` shortcode, embedded fonts, dark theme, and autoplay enabled.

This lets you verify the final presentation (including the control bar, chapter markers, speed
controls, and annotations) without running a full site build.

The modal provides three tabbed viewports at fixed widths:

| Tab | Viewport Width | Use Case |
|-----|---------------|----------|
| **Desktop** | 900px | Standard laptop/desktop browser |
| **Tablet** | 600px | Tablet or narrow browser window |
| **Mobile** | 375px | Phone-sized viewport |

Switch between tabs to verify that the player renders well at each breakpoint. The player is fully
interactive within each viewport: you can play, pause, seek, and test chapter navigation.

The preview is generated on-demand by rendering a temporary page that is fully self-contained with
no external dependencies. Generation takes a few seconds and a loading indicator is shown while the
render completes.

Press {{< keys "Escape" >}} or click outside the modal to close it.

### Recommended Workflow

1. **Record** the terminal session into `assets/` with `great-docs termshow record assets/demo.termshow`.
   This creates a paired set of files:
   - `assets/demo.termshow`: the raw recording (timing + terminal output)
   - `assets/demo.termshow.yml`: the script file (chapters, annotations, cuts, settings)

   Both files are always required. The `termshow record` command creates both automatically. The
   `.yml` file is generated with commented template sections you can uncomment and fill in.
   The `assets/` directory is recommended because it is automatically available to the
   `{{< termshow >}}` shortcode at build time.

2. **Open the Termshow Editor** with `great-docs termshow edit assets/demo.termshow` to visually
edit the script.
3. **Play through once** to get familiar with the recording's content and timing. Click the
**Timeline Ruler** (the graduated strip above the tracks) to scrub to any point.
4. **Add chapters** at logical transitions: double-click the Chapters Track or press
{{< keys "C" >}} at each transition point.
5. **Add annotations** to explain key moments: drag across the Annotations Track to set the
exact duration, or double-click for a 2-second default. Edit the text in the Properties Panel.
6. **Mark cuts** to remove dead time: drag across the Cuts Track to select the boring parts.
Use "ellipsis" for long skips (so viewers know time was removed) and "seamless" for short
gaps (smooth editing).
7. **Fine-tune edges**: click an edge handle, then use arrow keys to nudge it frame-by-frame
while watching the terminal preview update.
8. **Preview**: press {{< keys "P" >}} to open the production preview and verify the final player at
desktop, tablet, and mobile widths.
9. **Save** and embed in a page with the `{{< termshow >}}` shortcode.

The Termshow Editor saves only to the `.termshow.yml` script file. The raw recording is never
modified, so you can always start fresh by deleting the script and re-editing.

## Using Termshow in Any Quarto Project

The Termshow player is available as a **standalone Quarto extension** that works outside of Great
Docs. This means you can embed terminal recordings in any Quarto document (including revealjs
presentations, standalone websites, and blogs) without building a full Great Docs site.

### Install the extension

Install the Termshow extension directly from the Great Docs repository:

```bash
quarto add posit-dev/great-docs/extensions/termshow
```

This installs the player shortcode, styles, JavaScript runtime, and fonts into your project's
`_extensions/` directory. No other Great Docs components are required.

### Record and render

You still need the Great Docs CLI for recording and rendering terminal sessions:

```bash
pip install great-docs
```

Record a session as usual:

```bash
great-docs termshow record my-demo.termshow
```

Then optionally edit the companion `.termshow.yml` script (either by hand or with the Termshow
Editor via `great-docs termshow edit my-demo.termshow`) to add chapters, annotations, and cuts.

Since there is no `great-docs build` step in a standalone project, you need to explicitly render
the recording into SVG frames:

```bash
great-docs termshow render my-demo.termshow
```

This produces a `termshow/<name>/` directory containing SVG keyframes and a `manifest.json`. Move or
copy this directory into your Quarto project root if it isn't there already.

### Register termshow output as a resource

Add the rendered output to your project's resources so Quarto includes it in the build output.
In your `_quarto.yml`:

```yaml
project:
  resources:
    - termshow/**
```

### Embed with the shortcode

Use the same `{{< termshow >}}` shortcode as in a Great Docs site:

```{shortcodes="false"}
{{< termshow file="my-demo" autoplay="true" loop="true" >}}
```

All shortcode options (`autoplay`, `loop`, `speed`, `pause_on_chapters`, `controls`, `theme`) work
identically. The extension handles CSS, JavaScript, and font injection automatically via Quarto's
dependency system.

### Supported formats

The standalone extension works with any Quarto HTML-based format:

- **Websites** (`type: website`)
- **RevealJS presentations** (`format: revealjs`)
- **Single HTML pages** (`format: html`)
- **Books** (`type: book`)

The player adapts to available width and works with both light and dark themes.

### Sizing tips for RevealJS presentations

By default the Termshow player scales to fill the full slide width. On a RevealJS slide this can
make the terminal too large for the viewport, especially at 1920×1080 resolution where the
recording may overflow the bottom of the slide.

To fit it comfortably, add a small CSS file and reference it in your YAML header.

Create a `termshow-slides.css` file in your project:

```css
/* termshow-slides.css */
.reveal .gd-termshow {
    max-width: 70%;         /* adjust to taste */
    margin-inline: auto;
}
```

Then reference it in the YAML header of your presentation:

```yaml
format:
  revealjs:
    css: termshow-slides.css
```

A few guidelines:

- **Start around 70–75%** and adjust from there. The right value depends on your terminal
  dimensions (an 80-column recording needs less room than a 120-column one) and your slide
  aspect ratio.
- **Use `margin-inline: auto`** to center the player on the slide.
- **Avoid setting a fixed `height`**. The player maintains its aspect ratio automatically;
  constraining only the width lets it scale naturally.
- **Preview at presentation resolution** (typically 1920×1080 or 1280×720) to verify the recording
  fits comfortably within the slide bounds.

## Next Steps

Terminal recordings bring CLI workflows to life with crisp, interactive playback directly in your
documentation. Combined with chapters and annotations, they replace static code blocks with
guided, self-paced walkthroughs that readers can pause and study.

- [Videos](22-videos.qmd): embed video content for non-terminal demos and walkthroughs
- [CLI Documentation](07-cli-documentation.qmd): auto-generate reference pages for the commands you record
- [Diagrams](19-diagrams.qmd): complement terminal demos with architecture and flow visualizations
- [Theming](11-theming.qmd): customize player colors and appearance to match your site
- [Building](13-building.qmd): how Termshow shortcodes fit into the Quarto build pipeline



## AI & Agents

# MCP Documentation

If your Python package includes an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol)
server, Great Docs can generate a complete reference section for it automatically. Every tool,
resource, resource template, and prompt your server exposes gets its own structured page showing its
description, parameters (with types and required/optional markers), and return information. The pages
use the same layout as API and CLI reference pages and stay perfectly in sync with your code because
everything is extracted directly from your server definition at build time.

This page covers how to enable MCP documentation, what gets documented, how to organize tools into
categories, and how to write server definitions that produce clear, useful reference pages.

## Enabling MCP Server Documentation

MCP documentation is enabled by default. If your package has a module at a standard location
(`my_package.mcp`, `my_package.mcp_server`, or `my_package.server`), Great Docs will discover it
automatically and generate reference pages without any configuration. For most projects with an MCP
server, this means documentation appears on your next build with zero setup.

To point Great Docs at a non-standard module location, add:

```{.yaml filename="great-docs.yml"}
mcp:
  module: my_package.my_custom_mcp_module
```

To explicitly disable MCP documentation:

```{.yaml filename="great-docs.yml"}
mcp:
  enabled: false
```

If your module is importable and contains a valid `mcp.server.Server` instance, you're all set.
Great Docs handles discovery, introspection, page generation, and sidebar integration from there.

## How It Works

Understanding the discovery pipeline helps you troubleshoot when pages don't appear as expected and
gives you confidence that the output matches your code. When MCP documentation is enabled, Great
Docs runs the following steps during `great-docs build`:

1. **Imports your module**: loads the module at the path you specified (or auto-detected)
2. **Finds the Server instance**: auto-detects the first `mcp.server.Server` object in the module
3. **Extracts capabilities**: introspects registered tools, resources, resource templates, and
   prompts by calling the server's internal handlers
4. **Generates structured pages**: creates `.qmd` files in `reference/mcp/` with parameter tables,
   type annotations, and descriptions
5. **Builds an index page**: creates an overview with capability tiles and categorized tool listings
6. **Updates navigation**: adds an MCP Reference section to the sidebar

Because the pipeline uses the MCP server's own registration metadata, the documentation always
reflects the current state of your code. You never need to maintain a separate manifest of your
server's capabilities, just add a tool in Python and it appears in the reference on the next build.

## What Gets Documented

Great Docs documents every capability your MCP server exposes. Each capability type produces a
different style of reference page, tailored to the kind of information agents and developers need
when working with your server.

### Tools

Tools are the primary interface and they are the functions that AI agents can call. Each tool page
shows:

- The tool's description (from its docstring or registration)
- Every input parameter with its name, type, default value, and whether it's required
- Return value description (if provided)

This mirrors the structure of Python API reference pages, so users familiar with the function
documentation will feel at home browsing MCP tools.

### Resources

Static resources that agents can read (e.g., configuration files, build logs). Each resource page
shows:

- The resource URI
- Description text
- MIME type (if specified)

Resources give agents read access to project data without requiring a tool call, making them ideal
for context that agents need frequently.

### Resource Templates

URI-templated resources with variable segments (e.g., `docs://project/{path}`). Each template page
shows:

- The URI template pattern
- Template variables with types and descriptions
- Description text

Templates are especially useful for exposing file-based content where the path is parameterized,
like individual documentation pages or configuration sections.

### Prompts

Pre-built prompt templates for common workflows. Each prompt page shows:

- The prompt's purpose
- Arguments (named inputs the agent fills in)
- The message template text

Well-designed prompts encode your best practices into reusable templates, so agents can follow
established patterns without the user spelling out every step.

### Server-Level Information

The index page also surfaces:

- **Server instructions**: the instruction text displayed to agents at connection time
- **Completions**: whether the server provides argument auto-completion

Together, these capability types give both human developers and AI agents a comprehensive view of
what your server offers. The generated pages serve as a contract: anyone connecting to your server
can see exactly what tools are available, what inputs they expect, and what resources they can read.

## Configuration Options

While MCP documentation works out of the box for standard project layouts, several options let you
customize discovery, display names, and tool organization. The full set of MCP configuration
options in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
mcp:
  enabled: true                # Default: true (set false to disable)
  module: my_package.mcp       # Optional: auto-detected from common locations
  server_var: server           # Optional: variable name (auto-detected if omitted)
  name: My Package             # Optional: display name override
  categories:                  # Optional: organize tools into named groups
    "Build & Deploy":
      - build_docs
      - deploy_site
    "Analysis":
      - scan_project
      - lint_docs
```

### `module` (optional)

The dotted import path to the Python module containing your `mcp.server.Server` instance. If
omitted, Great Docs auto-detects by checking `<package>.mcp`, `<package>.mcp_server`, and
`<package>.server` in order.

### `server_var` (optional)

The variable name of the `Server` instance in your module. If omitted, Great Docs auto-detects the
first `mcp.server.Server` object it finds. Only needed if your module defines multiple server
instances.

### `name` (optional)

A display name for the server shown in page titles and the sidebar. Defaults to the server's
registered name.

### `categories` (optional)

A mapping of category names to lists of tool names. When provided, the index page groups tools
under these headings instead of listing them in a flat sequence. Tools not assigned to any category
appear in an "Other" group.

All options except `module` have sensible defaults. In practice, most projects only need to specify
`categories` once the server grows beyond a handful of tools.

## Organizing Tools with Categories

As your server grows, a flat list of tools becomes hard to scan. Categories let you group related
tools under meaningful headings, making it easier for both developers and agents to find what they
need. Define them by grouping tool function names under descriptive labels:

```{.yaml filename="great-docs.yml"}
mcp:
  enabled: true
  module: my_package.mcp
  categories:
    "Build & Deploy":
      - build
      - preview
      - deploy
    "Discovery & Analysis":
      - scan
      - lint
      - diff
    "Configuration":
      - config
      - status
    "Content":
      - add_page
      - add_section
```

Each category becomes a section on the index page with its own heading. Within each section, tools
are listed as a definition list linking to their individual reference pages.

Choose category names that reflect how users think about your server's capabilities (by workflow or
domain) rather than how the code is organized internally. A good set of categories helps both new
users browsing the reference and experienced users looking for a specific tool.

## Writing Good MCP Definitions

The quality of your generated documentation depends entirely on how you define your tools and
prompts in code. Great Docs extracts descriptions, parameter names, types, and default values
directly from your MCP registration. So investing a few extra minutes in clear definitions pays
off immediately in the reference output. The following patterns produce the best results.

### Tool Descriptions

The first sentence of a tool's description becomes the summary shown on the index page. Write it
as a concise action statement:

```python
@server.call_tool()
async def build(arguments: dict) -> list[TextContent]:
    """Build the documentation site.

    Runs a full documentation build, generating API reference pages,
    user guide content, and all configured extensions.
    """
    ...
```

Keep the first sentence short and specific. Avoid generic phrasing like "This tool does something".
Instead, lead with the action: "Build the documentation site", "Scan the package for public
symbols", or "Compare API surfaces between versions".

### Typed Parameters with Descriptions

Define tool input schemas with descriptions on each property. Great Docs extracts these into
the parameter table:

```python
@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="build",
            description="Build the documentation site.",
            inputSchema={
                "type": "object",
                "properties": {
                    "project_path": {
                        "type": "string",
                        "description": "Path to the project root directory.",
                    },
                    "clean": {
                        "type": "boolean",
                        "description": "Remove previous build artifacts first.",
                        "default": False,
                    },
                },
                "required": ["project_path"],
            },
        ),
    ]
```

This produces a parameter section with `project_path` marked as required and `clean` shown with its
default value.

### Prompt Arguments

For prompts, define arguments with clear descriptions:

```python
@server.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="setup_project",
            description="Guide through initial project setup.",
            arguments=[
                PromptArgument(
                    name="package_name",
                    description="Name of the Python package to document.",
                    required=True,
                ),
                PromptArgument(
                    name="framework",
                    description="Web framework used (if any).",
                    required=False,
                ),
            ],
        ),
    ]
```

Marking arguments as `required=True` or `required=False` controls whether Great Docs displays a
"required" badge next to the argument on the generated page.

### Server Instructions

Set `server.instructions` to provide context that agents see when they first connect. Great Docs
surfaces this on the index page in a callout block, giving visitors an immediate sense of what the
server does and how to get started:

```python
server = Server("my-package")
server.instructions = (
    "You are connected to the My Package MCP server. "
    "Use `status` to check the current project state before "
    "making changes."
)
```

Good instructions orient the agent (and the human reading the docs) quickly. A sentence or two
covering the server's purpose and a suggested starting point is usually sufficient.

## Generated Output

Once your server is discovered and your build completes, Great Docs produces a set of pages that
integrate seamlessly with the rest of your documentation site. This section describes what to
expect.

### Index Page

The index page provides an overview of the server's capabilities with:

- **Capability tiles**: visual indicators showing how many tools, resources, templates, and prompts
  are available
- **Callout blocks**: server instructions and completions status
- **Categorized tool listings**: each category as a section with tools shown as definition-list
  entries linking to their individual pages

The index page serves as the landing point for anyone exploring your server's capabilities, whether
they arrived from the sidebar or a search result.

### Individual Pages

Each tool, resource, template, or prompt page includes:

- A title with the item name
- Full description text
- Parameters or arguments table (with types, defaults, and required markers)
- Cross-references back to the server and related items

The generated pages use the same styling, navigation, and dark-mode support as the Python API
reference, giving your documentation site a consistent look regardless of whether someone is
browsing functions, CLI commands, or MCP tools.

## Internationalization

MCP reference pages support the same internationalization system as the rest of the site. If your
documentation targets a non-English audience, or if you ship a multilingual site, MCP pages
participate automatically. When you set a language in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
site:
  language: ja
```

All UI labels on MCP pages (section headings like "Parameters", "Arguments", badges like
"required") are translated into the configured language. Currently 25 languages are supported,
including right-to-left scripts like Arabic and Hebrew. See
[Internationalization](internationalization.qmd) for the full list.

Your tool descriptions and parameter help text remain in whatever language you write them in. Only
the structural UI chrome is translated.

## Example

To tie everything together, here's a complete minimal MCP server that produces a well-documented
reference section. This example includes a tool with typed parameters, a static resource, and
server instructions (the three most common capability types).

```{.python filename="my_package/mcp.py"}
from mcp.server import Server
from mcp.types import Resource, TextContent, Tool

server = Server("my-package")
server.instructions = "Use status to check project state before making changes."


@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="status",
            description="Show current project status and configuration.",
            inputSchema={
                "type": "object",
                "properties": {
                    "project_path": {
                        "type": "string",
                        "description": "Path to the project root.",
                    }
                },
                "required": ["project_path"],
            },
        ),
    ]


@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "status":
        return [TextContent(type="text", text="Project is configured.")]
    raise ValueError(f"Unknown tool: {name}")


@server.list_resources()
async def list_resources() -> list[Resource]:
    return [
        Resource(
            uri="docs://config",
            name="Configuration",
            description="Current great-docs.yml configuration.",
            mimeType="application/json",
        ),
    ]
```

With this module at `my_package/mcp.py` and the configuration:

```{.yaml filename="great-docs.yml"}
mcp:
  enabled: true
  module: my_package.mcp
  name: My Package
```

Running `great-docs build` produces a reference section with an index page, a `status` tool page,
and a `Configuration` resource page, all fully integrated into the site navigation.

From here you can add more tools, define prompts for common workflows, and organize everything
with categories as your server grows. The documentation will keep pace with your code automatically.

## Next Steps

Now that your MCP server has a generated reference section, here are some ways to build on it:

- **[Agent Skills](agent-skills.qmd)**: Ship a `SKILL.md` alongside your MCP server so agents have
  both the structured reference and a concise cheat sheet for common usage patterns.
- **[llms.txt](llms-txt.qmd)**: MCP tools are automatically included in the generated `llms.txt`
  and `llms-full.txt` files, giving LLM-based tools another way to discover your server's
  capabilities.
- **[Internationalization](internationalization.qmd)**: Translate the UI labels on your MCP
  reference pages into any of the 25 supported languages.
- **[Linting](linting.qmd)**: Run `great-docs lint` to catch missing descriptions, undocumented
  parameters, and other issues in your MCP definitions before they reach the published site.
- **[API Documentation](api-documentation.qmd)**: If your package also exposes a Python API, both
  reference sections share the same styling and navigation, giving users a unified experience.

With MCP documentation, Agent Skills, and `llms.txt` all working together, your package provides
agents with every level of context they need (from a quick skill summary to full tool-by-tool
reference pages).



## Site Content

# Lightbox

Screenshots, diagrams, and data visualizations carry most of the weight in technical documentation, yet readers usually see them shrunk to fit the column width. The Great Docs lightbox lets any image expand into a focused, full-screen view with zoom, panning, galleries, captions, dark-mode variants, annotations, before/after comparison, and a copy/download toolbar.

## Quick Start

Add the `.lightbox` class to any image to make it clickable:

```markdown
![The Hong Kong skyline at dusk](../assets/city-hong-kong.jpg){.lightbox}
```

![The Hong Kong skyline at dusk](../assets/city-hong-kong.jpg){.lightbox}

Click the image to open it. Press `Escape`, click the backdrop, or use the close button to dismiss it. That single class is all you need; everything else on this page is optional enhancement.

## Turning the Lightbox On

You control which images become interactive at two levels: per image, or per page.

The per-image approach is opt-in. Add `.lightbox` to the images you want to enlarge, and leave the rest as static figures:

```markdown
![Zurich by the lake](../assets/city-zurich.jpg){.lightbox}

![Florence at golden hour](../assets/city-florence.jpg)
```

The per-page approach is opt-out. Set `lightbox: true` (or `lightbox: auto`) in the page frontmatter to enlarge every block-level image automatically, including images produced by executable code cells:

```yaml
---
title: "My Page"
lightbox: auto
---
```

In auto mode, exclude individual images with the `.nolightbox` class:

```markdown
![A decorative skyline banner](../assets/city-warsaw.jpg){.nolightbox}
```

:::{.callout-note}
The lightbox assets load automatically on every Great Docs site. There is nothing to install or enable in `great-docs.yml`; the `.lightbox` class and the `lightbox` frontmatter key work out of the box.
:::

## Captions and Credits

A caption appears beneath the enlarged image, and a credit line attributes the source. When you omit `caption`, the lightbox falls back to the image's alt text.

```markdown
![Singapore skyline](../assets/city-singapore.jpg){.lightbox
  caption="The Singapore skyline along Marina Bay"
  credit="Photo via Pexels"}
```

![Singapore skyline](../assets/city-singapore.jpg){.lightbox caption="The Singapore skyline along Marina Bay" credit="Photo via Pexels"}

Write alt text for accessibility regardless of whether you set a caption. The alt text also becomes the screen-reader label for the enlarged view and the default download filename.

## Dark-Mode Image Variants

When your site supports dark mode, a bright daytime photo can look harsh against a dark backdrop. The lightbox can swap to a dark-optimized image automatically, but only when you opt in. Images without a declared dark variant keep their original source in both themes, so nothing ever breaks.

There are two ways to opt in. The first is an explicit `dark` attribute pointing at the alternate file:

```markdown
![Toronto by day](../assets/city-toronto-daytime.png){.lightbox
  dark="../assets/city-toronto-nighttime.png"
  caption="Toggle the site theme to watch day turn to night"}
```

![Toronto by day](../assets/city-toronto-daytime.png){.lightbox dark="../assets/city-toronto-nighttime.png" caption="Toggle the site theme to watch day turn to night"}

The second is a naming convention. If your source file is named with a `.light` segment, the lightbox looks for a matching `.dark` sibling:

```markdown
![Toronto skyline](../assets/city-toronto.light.png){.lightbox}
```

With that markup, a dark-mode reader sees `city-toronto.dark.png` while a light-mode reader sees `city-toronto.light.png`. Both the page thumbnail and the enlarged view follow the active theme, and the swap happens live when the reader toggles themes.

:::{.callout-warning}
The naming convention only triggers on the `.light` opt-in. A plain `skyline.png` will not silently look for `skyline.dark.png`, because that guessed file usually does not exist and would produce a broken image in the enlarged view.
:::

### How Dark-Mode Assets Are Copied

Great Docs automatically copies dark-mode image siblings to the built site, regardless of where the
images live. You can place images in any asset subdirectory within your user guide (`images/`,
`assets/`, `figures/`, or any other name) and both the light and dark variants will be included in
the final `_site/` output.

For example, a user guide structured like this:

```
user_guide/
├── getting-started.qmd
└── assets/
    └── orientation/
        ├── sweep-generator.light.png
        └── sweep-generator.dark.png
```

will have both `sweep-generator.light.png` and `sweep-generator.dark.png` available at
`user-guide/assets/orientation/` in the built site. The same applies to images referenced via the
`dark="..."` attribute. The target file is copied as long as it lives in an asset directory within
the user guide.

Custom sections configured via `sections:` in `great_docs.yaml` follow the same rules: any asset
subdirectory (a directory without `.qmd` files) is automatically registered for copying to the final
site.

## Galleries

Give several images the same `group` value to bind them into a gallery. Opening any one of them lets the reader page through the whole set with arrows, a filmstrip, keyboard keys, and touch swipes.

```markdown
![London](../assets/city-london.jpg){.lightbox group="cities" caption="London"}

![Shanghai](../assets/city-shanghai.jpg){.lightbox group="cities" caption="Shanghai"}

![Seattle](../assets/city-seattle.jpg){.lightbox group="cities" caption="Seattle"}

![Frankfurt](../assets/city-frankfurt.jpg){.lightbox group="cities" caption="Frankfurt"}

![Taipei](../assets/city-taipei.jpg){.lightbox group="cities" caption="Taipei"}
```

![London](../assets/city-london.jpg){.lightbox group="cities" caption="London"}

![Shanghai](../assets/city-shanghai.jpg){.lightbox group="cities" caption="Shanghai"}

![Seattle](../assets/city-seattle.jpg){.lightbox group="cities" caption="Seattle"}

![Frankfurt](../assets/city-frankfurt.jpg){.lightbox group="cities" caption="Frankfurt"}

![Taipei](../assets/city-taipei.jpg){.lightbox group="cities" caption="Taipei"}

A counter shows your position in the set, and a filmstrip at the bottom lets readers jump directly to any image.

### Navigation

Within a gallery, readers move between images using several input methods:

| Input            | Action                          |
| ---------------- | ------------------------------- |
| Arrow buttons    | Previous / next image           |
| `ArrowLeft` / `ArrowRight` | Previous / next image |
| Filmstrip thumb  | Jump to a specific image        |
| Swipe left/right | Previous / next (touch devices) |
| Swipe down       | Close the lightbox (touch)      |

### Looping and Autoplay

By default a gallery wraps around: paging past the last image returns to the first. Set `loop="false"` to stop at the ends instead, which also disables the navigation arrows at the first and last image:

```markdown
![Seattle](../assets/city-seattle.jpg){.lightbox group="steps" loop="false"}
![Frankfurt](../assets/city-frankfurt.jpg){.lightbox group="steps" loop="false"}
```

To advance the gallery automatically, add an `autoplay` interval. The value accepts seconds (`3s`), milliseconds (`2000ms`), or a bare number:

```markdown
![London](../assets/city-london.jpg){.lightbox group="reel" autoplay="4s"}
![Shanghai](../assets/city-shanghai.jpg){.lightbox group="reel" autoplay="4s"}
![Taipei](../assets/city-taipei.jpg){.lightbox group="reel" autoplay="4s"}
```

Manual navigation resets the autoplay timer, so a reader who takes control is not interrupted mid-view.

## Gallery Stack

A long gallery laid out inline takes a lot of vertical space. The `.lightbox-gallery` fenced div collapses a set of images into a single framed cover with a stacked-photo effect and a count badge. It occupies a fixed, compact footprint in the page, and clicking it opens the whole set as a gallery in the lightbox.

```markdown
::: {.lightbox-gallery}
![Singapore](../assets/city-singapore.jpg){caption="Singapore"}
![Hong Kong](../assets/city-hong-kong.jpg){caption="Hong Kong"}
![Zurich](../assets/city-zurich.jpg){caption="Zurich"}
![Florence](../assets/city-florence.jpg){caption="Florence"}
![Warsaw](../assets/city-warsaw.jpg){caption="Warsaw"}
:::
```

::: {.lightbox-gallery}
![Singapore](../assets/city-singapore.jpg){caption="Singapore"}
![Hong Kong](../assets/city-hong-kong.jpg){caption="Hong Kong"}
![Zurich](../assets/city-zurich.jpg){caption="Zurich"}
![Florence](../assets/city-florence.jpg){caption="Florence"}
![Warsaw](../assets/city-warsaw.jpg){caption="Warsaw"}
:::

The first image becomes the visible cover; the rest are bound into the same gallery behind it. Each image keeps its own `caption`, and once open, the full set of controls (filmstrip, arrows, autoplay, zoom) works as usual.

Constrain the footprint with a `width` attribute on the div:

```markdown
::: {.lightbox-gallery width="360px"}
![Singapore](../assets/city-singapore.jpg){caption="Singapore"}
![Hong Kong](../assets/city-hong-kong.jpg){caption="Hong Kong"}
:::
```

## Zooming and Panning

Every enlarged image can be magnified with the toolbar zoom controls. The toolbar shows a zoom-out button, the current zoom level, a zoom-in button, and a reset-to-fit button.

Readers have these zoom options:

| Input            | Action                  |
| ---------------- | ----------------------- |
| Zoom buttons     | Step in, out, or reset  |
| `+` / `-` keys   | Zoom in / out           |
| `0` key          | Reset to fit (100%)     |
| Drag             | Pan the magnified image |

Zoom runs from 100% up to 400% in steps. Once you pass 100%, the cursor becomes a grab hand and you can drag to pan around the image; the pan is clamped so the image always covers the frame. Annotation markers (covered next) hide while an image is zoomed to keep the view clean, and reappear when you reset.

## The Toolbar

The toolbar that floats over the enlarged image carries three actions beyond zoom and close. It fades away after a few seconds of inactivity and returns on mouse movement.

The actions are:

- **Copy image** places the picture on your clipboard. The image is rasterized to PNG first, so it pastes into editors and chat apps even when the source is an SVG.
- **Download image** saves the picture, using the alt text as the suggested filename.
- **Copy link** copies a deep link that reopens the lightbox on this exact image (see below).

:::{.callout-note}
Copy image works for same-origin images. If you load images from a CDN without cross-origin headers, the browser blocks the canvas read; the lightbox then falls back to copying the image URL as text.
:::

## Deep Linking

When a reader opens an image, the page URL gains a `#lightbox=` fragment that identifies it. Sharing that URL, or clicking the toolbar's copy-link button, reopens the page with that image already enlarged. This is useful for pointing a colleague at one specific screenshot or gallery frame.

```markdown
See the [Chicago skyline up close](my-page.html#lightbox=gd-lb-3).
```

Identifiers are assigned in document order as `gd-lb-1`, `gd-lb-2`, and so on. The copy-link button is the reliable way to capture the correct identifier without counting images by hand.

## Image Annotations

Annotations overlay numbered markers on an image, each revealing a tooltip on hover or click. They render both on the page thumbnail and inside the enlarged view, so a reader can study a labeled scene at full size. Provide them as a JSON array in the `annotations` attribute.

```markdown
![Chicago skyline](../assets/city-chicago-panoramic-skyline.png){.lightbox
  caption="Landmark towers of the Chicago skyline"
  annotations='[
    {"x": 7,  "y": 28, "label": "1", "text": "Willis Tower"},
    {"x": 13, "y": 48, "label": "2", "text": "Chicago Board of Trade Building"},
    {"x": 22, "y": 52, "label": "3", "text": "CNA Center"},
    {"x": 60, "y": 28, "label": "4", "text": "Aon Center"},
    {"x": 78, "y": 42, "label": "5", "text": "John Hancock Center"},
    {"x": 95, "y": 54, "label": "6", "text": "Lake Point Tower"}
  ]'}
```

![Chicago skyline](../assets/city-chicago-panoramic-skyline.png){.lightbox caption="Landmark towers of the Chicago skyline" annotations='[{"x": 7, "y": 28, "label": "1", "text": "Willis Tower"}, {"x": 13, "y": 48, "label": "2", "text": "Chicago Board of Trade Building"}, {"x": 22, "y": 52, "label": "3", "text": "CNA Center"}, {"x": 60, "y": 28, "label": "4", "text": "Aon Center"}, {"x": 78, "y": 42, "label": "5", "text": "John Hancock Center"}, {"x": 95, "y": 54, "label": "6", "text": "Lake Point Tower"}]'}

Each annotation object accepts the following keys:

| Key     | Required | Description                                            |
| ------- | -------- | ------------------------------------------------------ |
| `x`     | yes      | Horizontal position as a percentage (0 to 100)         |
| `y`     | yes      | Vertical position as a percentage (0 to 100)           |
| `label` | no       | Short text inside the marker (defaults to its number)  |
| `text`  | no       | Tooltip body shown on hover or click                   |
| `color` | no       | Marker color override (any CSS color)                  |

Positions are percentages relative to the image, so markers stay anchored to the same spot whether the image is shown as a thumbnail or enlarged. Keep label text short, one or two characters, and put the detail in `text`.

## Before/After Comparison

A comparison slider stacks two images and reveals one or the other as the reader drags a divider. It is ideal for showing a day/night pairing, a redesign, or the effect of a configuration change. Use the `compare` shortcode:

```markdown
{{< compare before="../assets/city-toronto-daytime.png" after="../assets/city-toronto-nighttime.png" label-before="Day" label-after="Night" >}}
```

{{< compare before="../assets/city-toronto-daytime.png" after="../assets/city-toronto-nighttime.png" label-before="Day" label-after="Night" >}}

The shortcode accepts these attributes:

| Attribute      | Default      | Description                              |
| -------------- | ------------ | ---------------------------------------- |
| `before`       |              | First (left or top) image path           |
| `after`        |              | Second (right or bottom) image path      |
| `label-before` | `Before`     | Caption for the first image              |
| `label-after`  | `After`      | Caption for the second image             |
| `direction`    | `horizontal` | Split orientation: `horizontal` or `vertical` |
| `start`        | `50`         | Initial divider position, as a percentage |

If you prefer Markdown over a shortcode, a fenced div with the `.lightbox-compare` class and two images works the same way, taking labels from each image's `caption` attribute:

```markdown
::: {.lightbox-compare direction="vertical" start="40"}
![](../assets/city-toronto-daytime.png){caption="Day"}
![](../assets/city-toronto-nighttime.png){caption="Night"}
:::
```

## Responsive Images

For large images, you can serve a smaller file inline and a sharper one in the enlarged view. The `srcset` and `sizes` attributes follow the standard HTML responsive-image syntax, and the lightbox automatically uses the highest-resolution entry when it opens:

```markdown
![Hong Kong](../assets/city-hong-kong.jpg){.lightbox
  srcset="../assets/city-hong-kong-800.jpg 800w, ../assets/city-hong-kong-1600.jpg 1600w"
  sizes="(max-width: 768px) 100vw, 800px"}
```

When you want to control the enlarged source directly, set `full-src` to the image the lightbox should display, independent of what appears inline:

```markdown
![Skyline thumbnail](../assets/city-shanghai.jpg){.lightbox full-src="../assets/city-shanghai-full.jpg"}
```

## Accessibility

The lightbox is built to work with keyboards and assistive technology, and to respect motion preferences.

- Opening an image moves focus into the dialog, and focus is trapped there until the lightbox closes, at which point it returns to the image you came from.
- The overlay is a labeled modal dialog, navigation is fully keyboard-operable, and slide changes are announced to screen readers.
- The origin-zoom open animation and gallery transitions respect `prefers-reduced-motion: reduce`.

:::{.callout-tip}
The lightbox manages its own zoom, so the browser's pinch-to-zoom is not needed inside the overlay. Use the toolbar controls or the `+`, `-`, and `0` keys for predictable, image-only magnification.
:::

## Attribute Reference

The following attributes apply to any image with the `.lightbox` class (or any image in a page using `lightbox: auto`). All are optional.

| Attribute     | Description                                                        |
| ------------- | ----------------------------------------------------------------- |
| `caption`     | Caption shown beneath the enlarged image                          |
| `credit`      | Attribution line shown below the caption                          |
| `dark`        | Path to a dark-mode image variant                                 |
| `group`       | Gallery name; images sharing a value navigate together            |
| `loop`        | Set `false` to stop gallery paging at the ends                    |
| `autoplay`    | Auto-advance interval, e.g. `3s`, `2000ms`, or a number           |
| `annotations` | JSON array of marker objects (`x`, `y`, `label`, `text`, `color`) |
| `srcset`      | Responsive source set; the widest entry is used when enlarged     |
| `sizes`       | Responsive sizes hint paired with `srcset`                        |
| `full-src`    | Explicit high-resolution source for the enlarged view             |

The two classes that control participation are `.lightbox` (opt in) and `.nolightbox` (opt out in auto mode).

## Next Steps

The lightbox turns ordinary figures into an explorable, shareable part of your documentation, from a single click-to-zoom screenshot to annotated galleries and before/after sliders. Reach for it whenever a reader would benefit from seeing an image larger or in more detail.

- [Authoring QMD Files](03-authoring-qmd-files.qmd): how images and figures fit into page content
- [Theming](11-theming.qmd): accent colors that the lightbox and annotation markers inherit
- [Diagrams](19-diagrams.qmd): pair Mermaid and other diagrams with the lightbox for detailed inspection
- [Collapsible Details](40-collapsible-details.qmd): another interactive content block with a similar attribute syntax


# Marimo Notebooks

Great Docs can embed interactive [Marimo](https://marimo.io/) notebooks directly in your
documentation pages. Readers run code examples live in their browser (no installation required)
powered by WebAssembly (Pyodide). They can also copy the notebook source to run locally with
`marimo edit`.

There are two ways to embed a notebook, and they make different trade-offs:

- **Island mode** (default) renders cells inline in the page. Outputs and `mo.ui` widgets are
live (drag a slider and the output updates) but the code shown is **read-only**. It's the
lightweight choice for illustrating a result in the flow of your prose.
- **Iframe mode** embeds a **fully editable, reactive** notebook. Readers edit any cell, re-run it,
and dependent cells recompute. It's the choice when you want readers to experiment with the code
itself, not just its inputs.

Pick island mode to *show* a live result, and pick iframe mode to let readers *rewrite* it.

## How It Works

Marimo notebooks are Python files with `@app.cell` decorators. What Great Docs does with them at
build time depends on the mode.

**Island mode** uses the [`@marimo-team/islands`](https://docs.marimo.io/guides/exporting/#islands)
runtime:

1. Reads the `.py` notebook at build time
2. Extracts each cell and emits `<marimo-island>` HTML elements
3. On page load, the islands runtime boots a Pyodide kernel in the browser
4. `mo.ui` widgets become interactive and changing a widget re-runs the cells that depend on it

The code editors in island mode are for display only. Editing the source text does not re-execute.
Reactivity flows from the UI controls, not from edits to the code.

**Iframe mode** self-hosts a full WASM export:

1. Runs `marimo export html-wasm --mode edit` on the notebook at build time
2. Bundles the result as static assets and embeds it in a sandboxed `<iframe>`
3. The notebook boots and auto-runs on load, so readers land on live outputs
4. Every cell is editable: edit, press <kbd>Ctrl</kbd>+<kbd>Enter</kbd>, and dependents re-run

Either way there's zero backend infrastructure: everything runs in the reader's browser.

## Quick Start

Getting a live notebook onto your documentation page takes three steps: enable the feature, create a
notebook, and drop in a shortcode. Here's each step in detail.

### 1. Enable marimo in `great-docs.yml`

```yaml
marimo: true
```

Or with explicit version pinning:

```yaml
marimo:
  enabled: true
  version: "0.23.7"
```

Iframe mode additionally needs [`uv`](https://docs.astral.sh/uv/) available at build time (marimo
uses it to resolve the notebook's dependencies for the WASM export). Installing the `marimo` extra
brings it in:

```bash
pip install "great-docs[marimo]"
```

### 2. Create a notebook

Marimo notebooks are standard Python files. Create a notebook in a `notebooks/` directory (or
anywhere in your project):

```bash
marimo edit --sandbox notebooks/my-demo.py
```

The `--sandbox` flag inlines package dependencies as [PEP 723](https://peps.python.org/pep-0723/)
metadata, ensuring they install automatically in the WASM environment.

### 3. Embed with the shortcode

In any `.qmd` page:

```markdown
{{{{< marimo file="notebooks/my-demo.py" >}}}}
```

Once you render the site, the notebook cells appear inline with live outputs and interactive
widgets. To make the code itself editable, add `mode="iframe"` (see below).

## Island Mode

Island mode is the default. The notebook's cells render **inline in the page**, in the natural flow
of your prose (outputs and `mo.ui()` widgets are live, while the code is shown for reference only).
It's the lightweight way to drop a live result into a paragraph.

```markdown
{{{{< marimo file="notebooks/reactive-intro.py" >}}}}
```

Here's a small notebook embedded this way. Drag the **sliders** and watch the summary, bar chart,
and table all recompute together. The dependent cells re-run reactively, with no "Run" button to
press:

{{< marimo file="notebooks/reactive-intro.py" >}}

The Pyodide runtime loads lazily (only when the notebook scrolls into view) so it doesn't slow down
initial page load. The following example uses only marimo (no third-party packages), so the kernel
boots quickly and reliably. It's a good default for a live demo (see
[Writing WASM-compatible notebooks](#writing-wasm-compatible-notebooks)).

::: {.callout-note}
## Island-mode code is read-only

The code above runs, but editing it won't re-execute (island mode keeps the *outputs* interactive
while showing the code for reference). When you want readers to edit and re-run the code itself,
use [iframe mode](#iframe-mode) instead.
:::

::: {.callout-important}
## One island notebook per page

All island embeds on a page share a **single** Pyodide kernel, and marimo requires every variable to
be defined in exactly one cell across that kernel. Two island notebooks on the same page therefore
collide and break each other's reactivity. Aim to embed at most one island notebook per page. if you
need several live notebooks together, use [iframe mode](#iframe-mode), which isolates each notebook
in its own kernel.
:::

### Outputs only

Pass `show-code="false"` to hide the source and show only the rendered outputs. This is useful for
dashboard- or app-style presentations where the code is secondary:

```markdown
{{{{< marimo file="notebooks/reactive-intro.py" show-code="false" >}}}}
```

## Iframe Mode

Iframe mode embeds the notebook as a **fully editable, reactive** environment in a sandboxed iframe.
This is the mode to use when you want to encourage experimentation with the code. Because each
iframe is its own isolated kernel, it's also the preferred method for placing several live notebooks
on one page.

```markdown
{{{{< marimo file="notebooks/reactive-intro.py" mode="iframe" height="600px" >}}}}
```

The notebook auto-runs on load, so readers see live outputs immediately, and **every cell is
editable**. Edit a cell and press <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to re-run it (dependent cells
will update automatically). Here's the same notebook from above. It's now fully editable so try
changing the chart-drawing code or the slider ranges:

{{< marimo file="notebooks/reactive-intro.py" mode="iframe" height="600px" >}}

By default the editor **chrome is trimmed** (marimo's sidebar and status bar are hidden) to keep the
embed clean. Use `chrome="full"` if you'd like to provide the complete editor interface. The iframe
also auto-sizes to fit the notebook, so it grows to hold all your cells and re-adjusts when reactive
outputs change size. The `height` parameter sets the initial height while the notebook loads.

## Shortcode Options

The `{{{< marimo >}}}` shortcode accepts several options that control how the notebook is rendered
and how readers interact with it.

| Option | Default | Applies to | Description |
|--------|---------|------------|-------------|
| `file` | *(required)* | both | Path to the `.py` marimo notebook (relative to project root) |
| `mode` | `"island"` | both | `"island"` for inline WASM cells, `"iframe"` for a full editable notebook |
| `show-code` | `"true"` | island | Show source code alongside output |
| `show-copy` | `"true"` | island | Display the "Copy Notebook" button |
| `theme` | `"auto"` | both | Color theme: `"auto"`, `"light"`, or `"dark"` |
| `height` | `"600px"` | iframe | Initial height. The iframe then auto-sizes to fit the notebook |
| `chrome` | `"trimmed"` | iframe | `"trimmed"` hides marimo's editor sidebar/status bar while `"full"` shows the complete editor |

You can combine these options to suit your needs. For instance, you might use `show-code="false"`
with `theme="dark"` for a polished island-mode demo, or `mode="iframe"` with a custom `height` for a
full-featured exploratory tool.

## Writing WASM-Compatible Notebooks

Because notebooks run in the browser via Pyodide, there are some differences from a standard Python
environment. Not all packages work in WebAssembly, and memory is limited. The guidelines below will
help you author notebooks that run reliably for your readers.

### Supported packages

All packages with **pure Python wheels** on PyPI work, plus many compiled packages bundled with
Pyodide: NumPy, SciPy, pandas, Polars, scikit-learn, Matplotlib, Plotly, and more. See
[Pyodide's package list](https://pyodide.org/en/stable/usage/packages-in-pyodide.html).

The catch is **compiled packages that aren't in Pyodide and don't ship a WASM wheel.** These fail to
install in the browser with an error like `Can't find a pure Python 3 wheel for '<pkg>'`. The
ecosystem is moving toward publishing emscripten/WASM wheels under
[PEP 783](https://peps.python.org/pep-0783/), so these pins should become unnecessary over time.

### Best practices

The following tips may be useful when setting up a Marimo notebook:

1. **Use `--sandbox`** when authoring: `marimo edit --sandbox notebook.py`
2. **Put `import marimo as mo` in its own cell**: this speeds up initial rendering
3. **Keep notebooks lightweight**: WASM has a 2 GB memory limit
4. **Use `mo.notebook_location()`** for data file paths that work both locally and in WASM
5. **Test in browser**: export with `marimo export html-wasm notebook.py -o test/` and serve with
`python -m http.server -d test/`

### Including data files

Place data files in a `public/` folder next to your notebook:

```
notebooks/
├── reactive-intro.py
└── public/
    └── sample-data.csv
```

Access them portably:

```python
import marimo as mo

path = mo.notebook_location() / "public" / "sample-data.csv"
```

Following these guidelines ensures your notebooks work consistently across local development and the
browser-based WASM environment your readers will use.

## Copy Notebook

Every embedded island-mode notebook includes a **Copy Notebook** button. Readers can copy the full
`.py` source and run it locally:

```bash
# Install marimo
pip install marimo

# Run the copied notebook
marimo edit reactive-intro.py
```

The button copies the complete notebook source including the PEP 723 dependency metadata, so
`marimo edit --sandbox` will auto-install all required packages.

## Performance Notes

Interactive notebooks add weight to a page, but several optimizations keep the experience smooth for
readers. Here's what to expect:

- **Pyodide weighs ~15 MB** on first load (cached by the browser afterward)
- **Lazy loading**: in island mode the WASM kernel only boots when the notebook scrolls into view
- **Single kernel per page**: multiple island-mode `{{{{< marimo >}}}}` shortcodes share one Pyodide instance
- **Iframe mode boots its own kernel** per embed, since each iframe is a self-contained notebook
- **First execution takes 3–5 seconds** while packages install whereas subsequent runs are fast

For pages where instant rendering matters, consider providing a static screenshot or pre-rendered
output above the interactive notebook as a visual anchor while Pyodide loads.

## Limitations

While Marimo notebooks offer a powerful interactive experience, there are some constraints imposed
by the browser-based execution environment. The table below summarizes the key limitations and
suggested workarounds.

| Limitation | Workaround |
|------------|------------|
| Not all packages available | Stick to Pyodide-supported or pure-Python packages and pin around compiled deps (see above) |
| 2 GB memory cap | Keep datasets small and use aggregated data for demos |
| No threading/multiprocessing | Use single-threaded patterns |
| ~15 MB initial download | Browser caches aggressively while lazy-load defers cost |
| No PDB debugging | Use `print()` or `mo.output` for debugging |
| Island-mode code is read-only | Use `mode="iframe"` when readers should edit the code |
| One island notebook per page (shared kernel) | Embed at most one island notebook per page; use `mode="iframe"` for multiple live notebooks |

For most documentation use cases (small datasets, pure-Python packages, and focused examples) these
limitations won't be an issue. Design your notebooks around concise, self-contained demonstrations
and the experience will be seamless.

## Next Steps

Now that you have interactive notebooks embedded in your documentation, here are some ways to build
on it:

- **[Marimo docs](https://docs.marimo.io/)**: Learn about reactive programming, UI elements
(`mo.ui.slider`, `mo.ui.dropdown`), and layout tools to make your notebooks more interactive.
- **Add interactivity**: Use `mo.ui` widgets to let readers explore data with sliders, dropdowns,
and toggles. All reactive by default, so outputs update the moment a value changes.
- **Let readers edit the code**: Use `mode="iframe"` on the examples where experimenting the code
is emphasized (you get a fully editable, reactive notebook right in the page).
- **Check WASM compatibility**: Run `marimo export html-wasm notebook.py -o test/` locally to verify
your notebook works in the browser before publishing.
- **[Marimo gallery](https://marimo.io/gallery)**: Browse examples of dashboards, explorable
explanations, and interactive tutorials you can adapt for your own documentation.

With Marimo notebooks, your documentation goes beyond static code examples. Readers can experiment
with your package directly in the browser, building intuition through hands-on exploration.