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


## Classes

Core classes and types


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 the GreatDocs class


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 build directory from the project.

This method deletes the great-docs.yml configuration file and the great-docs/
build directory (if it exists).

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

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"]
)
```

spell_check(self, include_docs: bool = True, include_docstrings: bool = False, custom_dictionary: list[str] | None = None, language: str = 'en', verbose: bool = False) -> dict

Check spelling in documentation files and optionally docstrings.

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

This method scans documentation files (`.qmd`, `.md`) for spelling errors using a
dictionary-based approach. It intelligently skips code blocks, inline code, URLs, and common
technical terms.

Parameters
----------
include_docs
    If `True`, scan documentation files (`.qmd`, `.md`) for spelling errors. Default is
    `True`.
include_docstrings
    If `True`, also scan Python docstrings in the package. Default is `False`.
custom_dictionary
    List of additional words to consider correct (e.g., project-specific terms, library
    names). Default is `None`.
language
    Language for spell checking. Currently supports "en" (English). Default is `"en"`.
verbose
    If `True`, print detailed progress information. Default is `False`.

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

    - `total_words`: total number of words checked
    - `misspelled`: list of dicts with `word`, `suggestions`, `files`, `contexts`
    - `by_file`: dict mapping file paths to misspelled words in each file
    - `skipped_files`: list of files that couldn't be read

Examples
--------
Check spelling in documentation:

```python
from great_docs import GreatDocs

docs = GreatDocs()
results = docs.spell_check()

print(f"Checked {results['total_words']} words")
print(f"Misspelled: {len(results['misspelled'])}")

for item in results['misspelled']:
    print(f"  {item['word']}: {item['suggestions'][:3]}")
```

Check with custom dictionary:

```python
results = docs.spell_check(
    custom_dictionary=["griffe", "docstring", "navbar"]
)
```


----------------------------------------------------------------------
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.
  scan                Discover package exports and preview what can be...
  setup-github-pages  Set up automatic deployment to GitHub Pages.
  check-links         Check for broken links in source code and...
  spell-check         Check spelling in documentation files.
  changelog           Generate a Changelog page from GitHub Releases.
```

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

  1. Creates great-docs/ directory with all assets
  2. Copies user guide files from project root
  3. Generates index.qmd from README.md
  4. Refreshes API reference configuration (discovers API changes)
  5. Generates llms.txt and llms-full.txt for AI/LLM indexing
  6. Creates source links to GitHub
  7. Generates CLI reference pages (if enabled)
  8. Generates API reference pages
  9. Runs Quarto to render the final HTML site in great-docs/_site/

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

  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 --project-path ../pkg

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

  Examples:
    great-docs preview                    # Preview on port 3000
    great-docs preview --port 8080        # Preview on port 8080

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --port INTEGER            Port for the local preview server  [default: 3000]
  --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 great-docs.yml configuration file
  • Removes 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 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 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

  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                     # Use defaults
    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 --force             # Overwrite existing workflow

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: 3.11)
  --force                   Overwrite existing workflow file without prompting
  --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 spell-check

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

  Check spelling in documentation files.

  This command scans documentation files (.qmd, .md) for spelling errors. It
  intelligently skips code blocks, inline code, URLs, and technical terms.

  A built-in dictionary of common programming terms is included (e.g., "api",
  "cli", "json", "yaml", "pytest", etc.). You can add custom words using
  -d/--dictionary or --dictionary-file.

  Examples:
    great-docs spell-check                        # Check all docs
    great-docs spell-check --verbose              # Show progress
    great-docs spell-check -d myterm -d anotherterm  # Add custom words
    great-docs spell-check --dictionary-file words.txt  # Load custom dictionary
    great-docs spell-check --include-docstrings   # Also check Python docstrings
    great-docs spell-check --json-output          # Output as JSON

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 spelling in Python docstrings
  -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)
  -v, --verbose             Show detailed progress for each file 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.
```


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


## Getting Started

# Welcome to Great Docs

Great Docs is a comprehensive documentation site generator for Python packages. It creates beautiful, professional documentation sites with auto-generated API references, smart navigation, and modern styling. Best of all, it requires minimal configuration.

## Why Great Docs?

Creating documentation for Python packages often involves:

- Writing configuration files by hand
- Manually listing every class, function, and method
- Keeping documentation in sync as your API evolves
- Wrestling with styling and navigation

Great Docs eliminates these pain points by:

- **Auto-discovering your API**: Automatically finds and documents your public classes, functions, and methods
- **Intelligent organization**: Groups related items together and handles large classes gracefully
- **Zero configuration**: Works out of the box with sensible defaults
- **Modern styling**: Professional appearance with responsive design for all devices

## Key Features

### One-Command Setup

A single `great-docs init` creates your entire documentation site, including:

- Auto-generated `index.qmd` from your `README.md`
- Complete API reference configuration
- Navigation and sidebar setup
- Styling and post-processing scripts

### Auto-Generated API Documentation

Great Docs automatically discovers and documents your package's public API:

- Classes with their methods and attributes
- Functions with parameters and return types
- Smart categorization and organization
- Source code links to GitHub

### CLI Documentation

If your package has a Click-based command-line interface, Great Docs can automatically generate reference pages showing the `--help` output for each command.

### User Guide Support

Create narrative documentation alongside your API reference. Just add `.qmd` files to a `user_guide/` directory and Great Docs handles the rest.

## What You'll Learn

This User Guide covers everything you need to know:

1. **Installation** – Getting Great Docs set up
2. **Quick Start** – Creating your first documentation site
3. **Configuration** – Customizing behavior via `great-docs.yml`
4. **API Documentation** – How auto-discovery works and how to customize it
5. **CLI Documentation** – Documenting Click-based CLIs
6. **User Guides** – Writing narrative documentation
7. **Deployment** – Publishing to GitHub Pages

Let's get started!


# Installation

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

## Prerequisites

Before installing Great Docs, ensure you have:

- **Python 3.9 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
```

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

## Dependencies

Great Docs automatically installs these dependencies:

| Package | Purpose |
|---------|---------|
| `griffe` | Static analysis and API discovery |
| `click` | Command-line interface |
| `py-yaml12` | YAML configuration handling |

## Next Steps

Now that Great Docs is installed, let's create your first documentation site in the [Quick Start](quickstart.qmd) guide.


# Quick Start

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

## Initialize Your Documentation (One-Time)

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
Discovered 15 public names
Auto-excluding 3 item(s): cli, main, version
  MyClass: class with 8 public methods
  helper_function: function
  ...
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]:
✅ Updated .gitignore to exclude great-docs/ directory

✅ Great Docs initialization complete!
```

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

1. Creates the `great-docs/` directory with all assets (CSS, JS, etc.)
2. Copies your configuration from `great-docs.yml`
3. Creates landing page from your `README.md`
4. Discovers and processes CLI documentation (if present)
5. Copies user guide files from `user_guide/` directory (if present)
6. Generates `llms.txt` and `llms-full.txt` for AI documentation indexing
7. Creates source links JSON for GitHub integration
8. Generates API reference pages
9. Runs `quarto render` to build the HTML site

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

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

## 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"}
# Build with file watching (auto-rebuild on changes)
great-docs build --watch
```

## 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()
```
docs.build()
```

## What's Next?

Your documentation site is ready! Here's what to explore next:

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



## Configuration & 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).

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

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

## Docstring Parser

Different projects use different docstring conventions, so Great Docs automatically detects your docstring style during initialization.

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

:::

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

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

### 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"
```

## 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)
```

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

## 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 — for example, [chatlas](https://posit-dev.github.io/chatlas/).

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

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

See [CLI Documentation](cli-documentation.qmd) for details.

## Changelog

Great Docs auto-generates a Changelog page from your GitHub Releases. It's enabled by default — 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.

## 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 (Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, and 30+ others) structured context about your package so they can write better code when using it.

During the build, a `skill.md` file is placed in your docs directory (and at `.well-known/skills/default/SKILL.md` for auto-discovery). Users of your package can then install the skill into their agent of choice:

```bash
npx skills add https://your-docs-site.com
```

### Writing your own skill (recommended)

The best results come from a hand-crafted skill written by someone who knows the package well: you! 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 `skills/` directory also makes your skill installable directly from GitHub:

```bash
npx skills add owner/my-package
```

#### What to include

A good skill is a **cheat sheet for agents**: concise, opinionated, and focused on the decisions and mistakes that matter most.

**YAML frontmatter** (required by the [spec](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.
---
```

The `name` field must be lowercase with hyphens only (max 64 chars) and match the directory name. The `description` should say both **what the skill does** and **when to use it**.

**Recommended body sections:**

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

### 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 tribal knowledge (gotchas, decision tables, best practices) 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 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
```

### 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 both curated and generated)
  well_known: true       # Also serve at /.well-known/skills/default/SKILL.md
  gotchas: []            # Gotcha strings (for auto-generated skill)
  best_practices: []     # Best-practice strings (for auto-generated skill)
  decision_table: []     # Rows: [{need: "...", use: "..."}]
  extra_body: null       # Path to extra Markdown to append (for auto-generated skill)
```

### Resolution order

Great Docs resolves the skill file in this order:

1. **`skill.file`** in `great-docs.yml`: explicit path, highest priority
2. **`skills/<package-name>/SKILL.md`**: curated skill in the repo (checked with both hyphenated and underscored package name)
3. **Auto-generated**: built from package metadata and API sections

### Disabling skill generation

```{.yaml filename="great-docs.yml"}
skill:
  enabled: false
```

## 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
github_style: widget

# Source Links
source:
  enabled: true
  branch: main
  placement: usage

# Sidebar
sidebar_filter:
  enabled: true
  min_items: 15

# 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

# 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 your docs directory. This file controls how Quarto renders your site, including navigation, theming, and the API reference configuration.

**Should you edit it?** Generally, no. Great Docs updates this file automatically during `great-docs build` to keep API sections in sync with your package exports. Manual edits to the API reference sections will be overwritten. However, you can safely customize other parts like the site title, theme, or additional navbar items.

**Should you commit it?** Yes: commit `_quarto.yml` along with your other docs files. This ensures your documentation builds consistently across environments, including GitHub Actions CI.

**GitHub CI considerations:** When using `great-docs setup-github-pages`, the workflow runs `great-docs build` which regenerates any auto-managed sections. This means CI builds will always use the latest API structure from your code, keeping documentation in sync even if local `_quarto.yml` changes weren't committed.

## Next Steps

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

Great Docs automatically discovers and documents your package's public API. This guide explains how discovery works and how to customize the output.

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

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

## What Gets Documented

By default, Great Docs documents everything it discovers in your package's public API. Each export is classified into one of the following 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

Some names are automatically excluded:

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

```{.yaml filename="great-docs.yml"}
exclude:
  - InternalHelper
  - deprecated_function
```

Note: 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.

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

### Small Classes (≤5 methods)

Methods are documented inline on the class page:

```{.yaml filename="_quarto.yml"}
sections:
  - title: Classes
    contents:
      - MySmallClass  # Methods shown inline
```

### Large Classes (>5 methods)

Methods get their own section with individual pages:

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

This creates better navigation for classes with many methods.

## API Organization

### Default Sections

Great Docs creates sections automatically based on what it discovers. Only non-empty sections appear:

| 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 with >5 methods |

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

You can explicitly control the API reference 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.

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

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

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

## Sphinx & RST Cleanup

Docstrings sometimes contain Sphinx cross-reference roles (like `` :py:exc:`ValueError` ``) or RST directives (like `.. versionadded:: 2.0`). These constructs are designed for Sphinx but appear as literal text in non-Sphinx renderers.

Great Docs automatically translates these into clean, styled HTML during the post-render step.

### Sphinx Cross-Reference Roles

Sphinx roles like `:py:class:`, `:func:`, and `:exc:` are converted into plain inline code formatting. For example, `` :py:exc:`ValueError` `` becomes `ValueError`, and `` :py:class:`datetime.datetime` `` becomes `datetime.datetime`. Function and method roles automatically receive trailing `()` to indicate they are callable, so `` :func:`my_function` `` renders as `my_function()` and `` :meth:`MyClass.run` `` renders as `MyClass.run()`.

### RST Admonition & Version Directives

RST directives are converted into styled callout boxes with appropriate icons and colors:

| Directive | Appearance |
| --- | --- |
| `.. versionadded:: 2.0` | 🆕 Green callout: "Added in version 2.0" |
| `.. versionchanged:: 3.1` | 🔄 Blue callout: "Changed in version 3.1" |
| `.. deprecated:: 2.6` | ⚠️ Red callout: "Deprecated since version 2.6" |
| `.. note:: ...` | ℹ️ Blue callout |
| `.. warning:: ...` | ⚠️ Amber callout |
| `.. tip:: ...` | 💡 Green callout |
| `.. danger:: ...` | 🚨 Red callout |
| `.. important:: ...` | ❗ Orange callout |

Optional description text after the version number is preserved in the callout body.

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

## Next Steps

- [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 automatically generate reference documentation for Click-based command-line interfaces. This creates terminal-style pages showing the `--help` output for each command.

## Enabling CLI Documentation

Add the following to your `great-docs.yml`:

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

That's it! Great Docs will automatically discover and document your CLI.

## How It Works

When CLI documentation is enabled, Great Docs:

1. **Finds your CLI** – Looks for Click commands in common locations
2. **Discovers entry point** – Reads `[project.scripts]` from `pyproject.toml`
3. **Extracts help text** – Captures `--help` output for each command
4. **Generates pages** – Creates `.qmd` files in `reference/cli/`
5. **Updates navigation** – Adds CLI section to the sidebar

## Auto-Discovery

Great Docs searches for Click commands in these locations (in order):

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

### Entry Point Detection

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

For non-standard setups, specify the module and command name:

```{.yaml filename="great-docs.yml"}
cli:
  enabled: true
  module: my_package.commands   # Module containing Click commands
  name: app                      # Name of the Click command object
```

## Generated Output

### 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 displays the `--help` output in a terminal-style format:

```
Usage: my-cli build [OPTIONS] PATH

  Build the project at PATH.

  This command compiles all source files and generates output
  in the specified directory.

Options:
  --output DIR    Output directory (default: ./dist)
  --verbose       Enable verbose output
  --help          Show this message and exit.
```

The styling mimics a terminal with:

- Dark background
- Monospace font
- Proper spacing for readability

## Writing Good CLI Help

Great Docs displays your Click help text as-is. To get the best documentation:

### Use Descriptive Help Text

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

### Document All Options

```{.python filename="cli.py"}
@click.option(
    "--format",
    type=click.Choice(["json", "yaml", "toml"]),
    default="json",
    help="Output format (default: json)"
)
```

### Use Click Groups for Subcommands

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

## Example: Great Docs CLI

Great Docs itself uses this feature. Its CLI documentation shows:

**Main command (`great-docs`):**

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

  Great Docs - Beautiful documentation for Python packages.

  Generate professional documentation sites with auto-discovered API
  references, CLI documentation, and smart navigation.

Commands:
  init              Initialize great-docs in your project
  build             Build documentation site
  preview           Build and preview locally
  scan              Scan package exports
  setup-github-pages  Create GitHub Pages workflow
  uninstall         Remove great-docs from project
```

**Subcommand (`great-docs build`):**

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

  Build your documentation site.

  Generates API reference pages and runs quarto render
  to build the HTML site.

Options:
  --no-refresh  Skip API discovery refresh (faster rebuild)
  --watch       Watch for changes and rebuild
  --help        Show this message and exit.
```

## Styling

CLI documentation uses special styling that:

- Disables the sidebar filter (CLIs are usually small)
- Removes breadcrumb navigation
- Uses a wider content area on large screens
- Maintains responsive design on mobile

## Troubleshooting

### CLI Not Detected

If your 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
```

### Help Text Missing

If commands show minimal help:

1. Add docstrings to your Click functions
2. Add `help=` to all options
3. Use `@click.argument()` with proper names

## Next Steps

- [User Guides](user-guides.qmd) explains how to add narrative documentation
- [Deployment](deployment.qmd) covers publishing to GitHub Pages


# User Guides

Beyond API reference documentation, you often need narrative documentation: tutorials, guides, and explanations. Great Docs makes this easy with automatic User Guide support.

## Creating a User Guide

To add a User Guide to your documentation:

1. Create a `user_guide/` directory in your project root
2. Add `.qmd` files for each page
3. Run `great-docs build`

That's it! 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

## Directory Structure

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

Files are sorted alphabetically by filename. Use numeric prefixes to control order:

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

## Organizing into Sections

Group related pages into sections using 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
```

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

As an alternative to `guide-section` frontmatter, you can organize pages into subdirectories. 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.

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

Subdirectories that don't contain `.qmd` files are treated as asset directories 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
```

## User Guide Styling

Great Docs applies different styling to User Guide pages compared to API reference pages, optimizing for the narrative documentation experience. The sidebar filter that helps navigate large APIs 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 documentation.

## Example: This User Guide

The Great Docs User Guide you're reading uses this exact structure:

```
user_guide/
├── 00-introduction.qmd      # Getting Started
├── 01-installation.qmd      # Getting Started
├── 02-quickstart.qmd        # Getting Started
├── 03-configuration.qmd     # Core Concepts
├── 04-api-documentation.qmd # Core Concepts
├── 05-cli-documentation.qmd # Core Concepts
├── 06-user-guides.qmd       # Core Concepts
└── 07-deployment.qmd        # Deployment
```

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

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

- [Deployment](deployment.qmd) covers publishing your 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.

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

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

### 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 — 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:

```
tutorials/
├── getting-started/
│   ├── installation.qmd
│   └── first-steps.qmd
└── advanced/
    └── custom-config.qmd
```

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

- [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 (like [Great Tables' blog](https://posit-dev.github.io/great-tables/blog/)):

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

- [Custom Sections](custom-sections.qmd) covers adding non-blog sections (examples, tutorials, etc.)
- [Configuration](configuration.qmd) covers all available `great-docs.yml` options



## Configuration & Theming

# Theming & Appearance

Great Docs ships with a polished default look, but every visual layer of the site is configurable. You can adjust the color scheme, add animated gradients to the navbar and content areas, enable dark mode, display an announcement banner, inject custom HTML into the page head, configure logos, and set up a hero section on your landing page. All of these options live in `great-docs.yml`.

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 enable or disable the toggle:

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

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

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

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

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

```{.yaml filename="great-docs.yml"}
hero:
  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:
  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` or `{}` to enable; dict to customize |
| `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 |

## Next Steps

- [Configuration](configuration.qmd) covers the functional settings (API discovery, parsers, GitHub integration)
- [User Guides](user-guides.qmd) explains how to write and organize narrative documentation
- [Deployment](deployment.qmd) shows how to publish your site to GitHub Pages


# Cross-Referencing

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 `objects.json` inventory that Great Docs generates during the build. To preview which symbols are available for linking before you build, run:

```bash
great-docs scan
```

## The `%seealso` Directive

The `%seealso` directive adds a "See Also" section to 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.
    """
    ...
```

## Inline Interlinks

You can create inline links to other API items anywhere in your docstring text using the interlinks syntax. 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.
    """
    ...
```

In the rendered documentation, each interlinks reference becomes a clickable link pointing to the target's reference page. Interlinks work in any part of a docstring: the summary line, extended description, parameter descriptions, notes, or any other section.

## Code Autolinks

Great Docs automatically converts inline code in docstrings into clickable links when the code matches a documented API symbol. No special syntax is needed; you use standard backtick code formatting and Great Docs does the rest:

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

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

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

## Next Steps

- [API Documentation](api-documentation.qmd) covers how discovery and organization work
- [Configuration](configuration.qmd) covers the functional settings in `great-docs.yml`
- [Theming & Appearance](theming.qmd) covers visual customization options



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

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

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

9. `llms.txt` and `llms-full.txt` files are generated. These provide AI-friendly summaries of your package documentation.

10. Source link metadata (`_source_links.json`) is generated, mapping each documented symbol to its file and line numbers on GitHub.

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

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

## Next Steps

- [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@v4
        with:
          path: great-docs/_site

  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@v4
```

## 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/`

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

## Summary

With Great Docs and GitHub Pages, you get:

- **Automatic builds** on every push
- **Preview deployments** for pull requests
- **Zero maintenance** hosting
- **Custom domains** support
- **HTTPS** out of the box

Your documentation stays in sync with your code automatically!



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


### Spell Checking

Good documentation requires accurate spelling. Great-Docs includes a built-in spell checker that scans your documentation source files for spelling errors while intelligently skipping code, URLs, and technical terms.

## What Gets Scanned

The spell checker scans **source documentation**, not generated output:

- Files in `user_guide/` directory (`.qmd` and `.md` files)
- `README.md` in the project root
- Optionally: docstrings from your Python source code

It does **not** scan the `great-docs/` build directory, as that contains generated output.

## Basic Usage

Run the spell checker from your project directory:

```bash
great-docs spell-check
```

The spell checker will scan all `.qmd` and `.md` files in your `user_guide/` directory and report any misspellings found.

## Verbose Output

For detailed progress information, use the `--verbose` flag:

```bash
great-docs spell-check --verbose
```

This shows each file as it's scanned:

```
✅ user_guide/index.qmd: OK
📄 user_guide/guide.qmd: 2 issue(s)
✅ user_guide/reference.qmd: OK
```

## Custom Dictionary

### Adding Words on the Command Line

For project-specific terminology, add custom words using `-d`:

```bash
great-docs spell-check -d "griffe" -d "pkgdown" -d "navbar"
```

### Using a Dictionary File

For larger custom dictionaries, create a text file with one word per line:

```{.text filename="custom_words.txt"}
griffe
pkgdown
docstring
navbar
frontmatter
```

Then reference it with `--dictionary-file`:

```bash
great-docs spell-check --dictionary-file custom_words.txt
```

## Smart Content Skipping

The spell checker automatically skips content that shouldn't be spell-checked:

| Content Type | Example |
|-------------|---------|
| Code blocks | ` ```python...``` ` |
| Inline code | `` `function_name` `` |
| URLs | `https://example.com` |
| Email addresses | `user@example.com` |
| YAML frontmatter | `--- title: "Page" ---` |
| HTML tags | `<div class="example">` |
| Quarto directives | `{.callout-note}` |
| LaTeX math | `$x^2 + y^2$` |
| File paths | `/path/to/file.py` |

## Built-in Technical Terms

Common programming and documentation terms are automatically recognized:

- **Languages**: python, javascript, typescript, rust, etc.
- **Tools**: pytest, numpy, pandas, sphinx, mkdocs, etc.
- **Formats**: json, yaml, toml, html, css, etc.
- **Abbreviations**: api, cli, sdk, url, etc.
- **Documentation**: docstring, frontmatter, readme, changelog, etc.

## Checking Docstrings

To also scan Python docstrings in your package:

```bash
great-docs spell-check --include-docstrings
```

This uses [griffe](https://mkdocstrings.github.io/griffe/) to extract docstrings from your Python modules.

## CI/CD Integration

### JSON Output

For programmatic processing, use `--json-output`:

```bash
great-docs spell-check --json-output
```

This returns structured JSON:

```json
{
  "total_words": 1234,
  "misspelled": [
    {
      "word": "documment",
      "suggestions": ["document", "documents"],
      "files": ["user_guide/guide.qmd"],
      "contexts": ["This documment explains..."]
    }
  ],
  "by_file": {
    "user_guide/guide.qmd": ["documment"]
  },
  "skipped_files": []
}
```

### GitHub Actions

Add spell checking to your CI workflow:

```{.yaml filename=".github/workflows/docs.yml"}
name: Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  spell-check:
    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 great-docs

      - name: Run spell check
        run: great-docs spell-check --dictionary-file custom_words.txt
```

### Pre-commit Hook

Add spell checking as a pre-commit hook:

```{.yaml filename=".pre-commit-config.yaml"}
repos:
  - repo: local
    hooks:
      - id: spell-check
        name: Spell Check Documentation
        entry: great-docs spell-check
        language: system
        types: [markdown]
        pass_filenames: false
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | No spelling issues found |
| 1 | Spelling issues found or error occurred |

## Best Practices

1. **Create a custom dictionary file** for your project-specific terms
2. **Run spell check in CI** to catch issues early
3. **Review suggestions** - the spell checker provides up to 5 suggestions for each misspelling
4. **Use `--verbose`** when debugging to see exactly what's being checked
5. **Combine with link checking** for comprehensive documentation QA:

```bash
great-docs check-links && great-docs spell-check
```

## Programmatic Usage

You can also use the spell checker programmatically:

```python
from great_docs import GreatDocs

docs = GreatDocs()

# Basic spell check
results = docs.spell_check()
print(f"Checked {results['total_words']} words")
print(f"Found {len(results['misspelled'])} misspellings")

# With custom dictionary
results = docs.spell_check(
    custom_dictionary=["griffe", "pkgdown"],
    verbose=True
)

# Include docstrings
results = docs.spell_check(include_docstrings=True)

# Process results
for item in results['misspelled']:
    print(f"'{item['word']}' in {item['files']}")
    print(f"  Suggestions: {item['suggestions'][:3]}")
```


# Changelog

Great Docs can automatically generate 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.

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

## Prerequisites

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.

## Configuration

The changelog works out of the box with sensible defaults. To customize behavior, add a `changelog` section to `great-docs.yml`:

```{.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 fine, but if you hit rate limits — particularly in CI — 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:

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

This is useful for testing or regenerating just the changelog. You can also override the max releases:

```{.bash filename="Terminal"}
great-docs changelog --max-releases 10
```

## What Gets Included

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

## 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()`
```

## Edge Cases

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

In all cases, the build completes successfully — the changelog is never a hard failure.

## Next Steps

- [Configuration](configuration.qmd) covers all available `great-docs.yml` options
- [Deployment](deployment.qmd) covers publishing your docs (including the changelog) to GitHub Pages
- [Link Checker](link-checker.qmd) explains how to validate links across your site