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.

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:

great-docs.yml

# Your settings here

To generate a starter configuration file with all options documented:

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:

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:

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:

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

NumPy Style

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

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

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.

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:

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:

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:

great-docs.yml

source:
  branch: main  # Default: auto-detected from git

To disable source links entirely:

great-docs.yml

source:
  enabled: false

Full source link configuration:

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:

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:

great-docs.yml

markdown_pages: true   # Enable/disable (default: true)

To disable both the .md generation and the copy/view widget:

great-docs.yml

markdown_pages: false

To generate .md pages but hide the widget:

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

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

The homepage setting controls which layout to use:

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:

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:

great-docs.yml

cli:
  enabled: true

With optional explicit configuration:

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

great-docs.yml

changelog:
  enabled: true        # Enable/disable changelog (default: true)
  max_releases: 50     # Max releases to include (default: 50)

To disable it entirely:

great-docs.yml

changelog:
  enabled: false

See Changelog 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:

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 and Blog for full details.

Author Information

Customize author display in the landing page sidebar:

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:

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:

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:

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:

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

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:

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

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

| Need                    | Use                |
|-------------------------|--------------------|
| Create a widget         | `Widget()`         |
| Style a widget          | `Widget.style()`   |
| Export to HTML          | `Widget.to_html()` |

Example gotchas:

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:

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

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

great-docs.yml

skill:
  enabled: false

Complete Example

Here’s a comprehensive configuration demonstrating all available options:

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:

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 covers logos, gradients, banners, dark mode, hero sections, and other visual options
• API Documentation explains how API discovery and organization works
• CLI Documentation covers Click CLI documentation
• Cross-Referencing covers the Great Docs Linking System (GDLS)