# 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.md).
For HTML-based landing pages and demo surfaces, see [Custom Static Pages](custom-pages.md). That feature is configured with `custom_pages` and still falls back to `custom/` when omitted.
# Configuration Location
All Great Docs settings go in a `great-docs.yml` file in your project root directory. This dedicated configuration file keeps your documentation settings separate and easy to manage:
great-docs.yml
``` yaml
# 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:
great-docs.yml
``` yaml
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
``` yaml
exclude:
- InternalClass
- helper_function
```
Note: The `exclude` setting affects what appears when running `great-docs init` (which auto-generates your `reference` config) and `great-docs scan` (which shows discovered exports). Once you have a `reference` config, you control exactly what's documented by listing items there.
## Auto-Excluded Names
Great Docs automatically excludes these common internal names during discovery:
| Category | Names |
|----|----|
| CLI/Entry points | `main`, `cli` |
| Version/Metadata | `version`, `VERSION`, `VERSION_INFO` |
| Module re-exports | `core`, `utils`, `helpers`, `constants`, `config`, `settings` |
| Standard library | `PackageNotFoundError`, `typing`, `annotations`, `TYPE_CHECKING` |
| Logging | `logger`, `log`, `logging` |
## Force-Including Auto-Excluded Names
Some packages intentionally export names that match the auto-exclude list (e.g., a `config` or `logging` module that is part of the public API). Use `auto_include` to force specific names back into discovery:
great-docs.yml
``` yaml
auto_include:
- config
- logging
```
Names listed in `auto_include` are removed from the auto-exclude filter while all other auto-excluded names remain filtered as usual.
## Disabling Auto-Exclude Entirely
If the auto-exclude list doesn't suit your package at all, you can bypass it completely:
great-docs.yml
``` yaml
no_auto_exclude: true
```
With this setting, no names are automatically excluded. You can still use `exclude` to manually remove specific items.
# Docstring Parser
Different projects use different docstring conventions, so Great Docs automatically detects your docstring style during initialization. For a full guide on structuring docstrings (sections, executable examples, directives), see [Writing Docstrings](writing-docstrings.md).
## 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
``` yaml
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
- Google Style
- Sphinx 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
```
``` 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
```
``` 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.
great-docs.yml
``` yaml
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
``` yaml
dynamic: false
```
## When to Set `dynamic: false`
- your package has cyclic aliases or complex re-export patterns
- the build fails with `AttributeError` during introspection
- you're documenting a compiled extension (PyO3/Rust/Cython)
# GitHub Integration
Several Great Docs features require knowing your GitHub repository URL:
- **GitHub widget/icon** in the navbar (with star count)
- **Source links** on API reference pages
- **Version badge** next to the package name (from GitHub Releases)
- **Changelog** page (from GitHub Releases)
## Repository URL Detection
Great Docs looks for your GitHub repository in this order:
1. **`repo:` in great-docs.yml**: explicit override, takes precedence
2. **`[project.urls]` in pyproject.toml**: looks for `Repository`, `Source`, `GitHub`, or `Homepage` keys containing a GitHub URL
great-docs.yml
``` yaml
repo: https://github.com/your-org/your-package
```
Or via pyproject.toml:
pyproject.toml
``` toml
[project.urls]
Repository = "https://github.com/your-org/your-package"
```
> **Note: Build Messages**
>
> During `great-docs build`, you may see messages about GitHub integration:
>
> - **"No GitHub repository info available"**: no repository URL was found. Check that `repo:` is set in great-docs.yml or `[project.urls]` is configured in pyproject.toml.
> - **"No GitHub releases found"**: the repository was detected, but has no published GitHub Releases. The version badge feature requires at least one published release.
## GitHub Link Style
Choose how the GitHub link appears in the navbar:
great-docs.yml
``` yaml
# Shows stars count (default)
github_style: widget
# Or use a simple GitHub icon
github_style: icon
```
## Version Badge
When your repository has published GitHub Releases, Great Docs automatically displays a version badge next to your package name in the navbar. The badge shows the latest release version and updates automatically on each build.
This feature requires:
1. a detected GitHub repository URL (see above)
2. at least one published [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
No configuration is needed (the badge appears automatically when these conditions are met).
## Source Links
Great Docs automatically creates "source" links to GitHub. Configure the branch:
great-docs.yml
``` yaml
source:
branch: main # Default: auto-detected from git
```
To disable source links entirely:
great-docs.yml
``` yaml
source:
enabled: false
```
Full source link configuration:
great-docs.yml
``` yaml
source:
enabled: true # Enable/disable source links (default: true)
branch: main # Git branch/tag to link to (default: auto-detect)
path: src/package # Custom source path for monorepos (default: auto-detect)
placement: usage # Where to place the link: "usage" (default) or "title"
```
# PyPI Link
The homepage metadata sidebar includes a "View on PyPI" link, auto-detected from your package name in `pyproject.toml`. You can disable it or point it to a custom package index:
great-docs.yml
``` yaml
# Disable the PyPI link entirely
pypi: false
```
great-docs.yml
``` yaml
# Use a custom package index URL (e.g., a private registry)
pypi: "https://packages.example.com/simple/my-package"
```
When `pypi` is `true` (the default), the link is auto-generated as `https://pypi.org/project/{package_name}/`.
# Site URL
Set `site_url` to the canonical URL where your documentation site is (or will be) hosted. This value is used in several places:
- **Skills page** install instructions (e.g., `npx skills add `)
- **`.well-known/` discovery** endpoints for agent skills
- **Quarto's `website.site-url`** (canonical links, sitemaps)
- **Subdirectory deployments** where the site lives at a path other than `/` (e.g., `https://internal.example.com/docs/mypackage/`)
Without it, the Skills page renders literal `` placeholders instead of working install commands, and subdirectory-hosted sites will have broken asset paths.
great-docs.yml
``` yaml
# Site URL: the canonical address of the deployed documentation site.
# Used for skills page install commands, .well-known/ discovery, and sitemaps.
site_url: "https://your-org.github.io/your-package/"
```
Alternatively, you can set a `Documentation` entry in `pyproject.toml`:
pyproject.toml
``` toml
[project.urls]
Documentation = "https://your-org.github.io/your-package/"
```
Great Docs checks these sources in order:
1. `site_url` in `great-docs.yml`
2. `Documentation` URL in `[project.urls]` (pyproject.toml)
3. `website.site-url` already present in `_quarto.yml`
If none are found, the build emits a warning:
⚠ No site URL found -- skills page will show placeholders.
Set site_url in great-docs.yml or add a Documentation URL to
[project.urls] in pyproject.toml.
> **Tip: Tip**
>
> Set `site_url` even before your site is deployed. Once the site goes live at that address, all generated install commands will already be correct.
# Sidebar Filter
The API reference sidebar includes a search filter for large APIs. Configure it:
great-docs.yml
``` yaml
sidebar_filter:
enabled: true # Enable/disable filter (default: true)
min_items: 20 # Minimum items before showing filter (default: 20)
```
# Method Page Splitting
Control whether class methods get their own pages or stay inline on the class page:
great-docs.yml
``` yaml
inline_methods: 5 # Split above 5 methods (default)
inline_methods: 10 # Split above 10 methods
inline_methods: true # Always inline (never split)
inline_methods: false # Always split to separate pages
```
See [API Documentation: Smart Method Handling](api-documentation.md#smart-method-handling) for detailed examples.
# Markdown Pages
Every HTML page gets a companion `.md` file generated automatically. A small widget appears in the top-right corner of each page allowing visitors to **copy** the page content as Markdown or **view** the raw `.md` file. This is enabled by default:
great-docs.yml
``` yaml
markdown_pages: true # Enable/disable (default: true)
```
To disable both the `.md` generation and the copy/view widget:
great-docs.yml
``` yaml
markdown_pages: false
```
To generate `.md` pages but hide the widget:
great-docs.yml
``` yaml
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.md) 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
``` yaml
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.md) for details on writing and organizing User Guide content.
# Homepage Mode
By default, Great Docs generates a separate homepage from your project's README (or `index.qmd`/`index.md`), with a "User Guide" link in the top navbar. Many Python documentation sites use a different layout where the first User Guide page *is* the landing page.
The `homepage` setting controls which layout to use:
great-docs.yml
``` yaml
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
``` yaml
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
``` yaml
cli:
enabled: true
```
With optional explicit configuration:
great-docs.yml
``` yaml
cli:
enabled: true
module: my_package.cli # Module containing Click commands
name: cli # Name of the Click command object
```
See [CLI Documentation](cli-documentation.md) for details.
# Changelog
Great Docs auto-generates a Changelog page from your GitHub Releases. It's enabled by default so if your `pyproject.toml` has a GitHub repository URL, a changelog page will appear automatically.
To customize:
great-docs.yml
``` yaml
changelog:
enabled: true # Enable/disable changelog (default: true)
max_releases: 50 # Max releases to include (default: 50)
```
To disable it entirely:
great-docs.yml
``` yaml
changelog:
enabled: false
```
See [Changelog](changelog.md) 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
``` yaml
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.md) and [Blog](blog.md) for full details.
# Author Information
Customize author display in the landing page sidebar:
great-docs.yml
``` yaml
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
``` yaml
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
``` yaml
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
``` yaml
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
``` yaml
reference:
title: "API Docs"
desc: "All public symbols documented below."
sections:
- title: Core
contents:
- MyClass
```
# Agent Skills (skill.md)
Great Docs supports the [Agent Skills](https://agentskills.io/) open standard, which gives AI coding agents structured context about your package so they can write better code when using it.
During the build, a `SKILL.md` is generated (or copied from your hand-written version) and served at `.well-known/agent-skills//SKILL.md` for discovery. Users can then install it with `npx skills add` or `great-docs skill install`.
great-docs.yml
``` yaml
skill:
enabled: true # Set to false to disable skill.md entirely
file: null # Path to a SKILL.md (overrides curated and generated)
well_known: true # Serve at /.well-known/ discovery endpoints
gotchas: [] # Gotcha strings (for auto-generated skill only)
best_practices: [] # Best-practice strings (for auto-generated skill only)
decision_table: [] # Rows: [{need: "...", use: "..."}]
extra_body: null # Path to extra Markdown to append (auto-generated only)
skills: [] # Multi-skill mode: [{name: "...", file: "..."}]
```
For the full guide -- including how to write a skill, the resolution order, multi-skill mode, the `great-docs skill` CLI, freshness checking, and the Python API -- see [Agent Skills](agent-skills.md).
# Page Metadata New in 0.2
Display page creation and modification dates at the bottom of documentation pages, giving readers a sense of content freshness.
## Enabling Page Metadata
great-docs.yml
``` yaml
site:
show_dates: true
```
When enabled, pages display timestamps in a compact horizontal format:
✏️ 4 months ago 📄 2 years ago
- **✏️ (pencil icon)**: Last modification date
- **📄 (file icon)**: Creation date
Hovering over a timestamp shows the full date (e.g., "March 24, 2026").
## How Dates Are Determined
Great Docs determines dates from Git history when available:
| Date Type | Source |
|--------------|----------------------------------------------------------|
| **Created** | Date of the first Git commit that added the file |
| **Modified** | Date of the most recent Git commit that changed the file |
If Git history is unavailable (e.g., shallow clones in CI), the file system timestamps are used as a fallback.
## Overriding Dates in Frontmatter
You can override Git-derived dates using frontmatter, which is useful when:
- you want to set a specific "last updated" date
- git history is unavailable or incorrect (shallow clones, file renames)
- you're migrating content from another system
guide.qmd
``` yaml
---
title: "Getting Started"
last_update:
date: "2026-01-15"
author: "Jane Developer"
date_created: "2024-06-01"
---
```
The `last_update` field follows this format:
- `date`: ISO date string (with or without time/timezone)
- `author`: optional author name override
Frontmatter values take precedence over Git history. If only `last_update.date` is provided, the creation date still comes from Git.
## CI/CD Considerations
In CI environments like GitHub Actions, the default checkout only fetches the latest commit (shallow clone). This means all pages would show identical timestamps.
The `great-docs setup-github-pages` command generates a workflow with full Git history enabled:
``` yaml
- uses: actions/checkout@v6
with:
fetch-depth: 0 # Full history for accurate timestamps
```
For large repositories, you can use sparse checkout to speed up builds while still getting full history for documentation files:
``` yaml
- uses: actions/checkout@v6
with:
fetch-depth: 0
sparse-checkout: |
user_guide
recipes
```
## Auto-Generated Pages
Pages that Great Docs generates automatically (API reference, changelog, CLI reference) show a "Refreshed" timestamp instead:
🔄 Refreshed 2 hours ago
This indicates when the page content was last regenerated during a build, not when source code was edited.
## Which Pages Show Metadata
| Page Type | Shows Metadata |
|-----------------------------|------------------------|
| User Guide pages | ✓ Yes |
| Recipes | ✓ Yes |
| Roadmap, Contributing, etc. | ✓ Yes |
| API Reference pages | ✓ Yes (as "Refreshed") |
| Changelog | ✓ Yes (as "Refreshed") |
| Homepage | ✗ No |
## Configuration Options
great-docs.yml
``` yaml
site:
show_dates: true # Enable/disable page metadata (default: false)
show_author: true # Show author attribution when enabled (default: true)
show_security: true # Show security policy page from SECURITY.md (default: true)
```
## Author Attribution
When `show_author` is enabled and a page has author information in its frontmatter, author avatars appear alongside the timestamps:
✏️ 4 months ago 📄 2 years ago -- ○ ○
To add author information to a page, include it in the YAML frontmatter:
guide.qmd
``` yaml
---
title: "Getting Started"
author:
name: "Jane Developer"
image: "https://github.com/janedev.png"
url: "https://github.com/janedev"
---
```
Great Docs automatically looks up author details from the `authors` list in `great-docs.yml`, so you can often just specify the name:
guide.qmd
``` yaml
---
title: "Getting Started"
author: "Jane Developer"
---
```
If the author is listed in `great-docs.yml` with a `github` field, their GitHub avatar is used automatically.
# Complete Example
Here's a comprehensive configuration demonstrating all available options:
great-docs.yml
``` yaml
# Display Name
display_name: My Package # Custom display name for navbar/title
# Docstring Parser
parser: numpy # Auto-detected: numpy, google, or sphinx
# API Discovery
exclude:
- _InternalClass
# GitHub Integration
repo: https://github.com/your-org/your-package # Override auto-detect
github_style: widget
# Site URL -- canonical address of the deployed documentation site.
# Used for skills page install commands, .well-known/ discovery, and sitemaps.
# site_url: "https://your-org.github.io/your-package/"
# Source Links
source:
enabled: true
branch: main
placement: usage
# PyPI Link
pypi: true # true (default), false to disable, or a custom URL string
# Sidebar
sidebar_filter:
enabled: true
min_items: 15
# Site Settings
site:
show_dates: true # Show page timestamps
show_author: true # Show author avatars
# Markdown Pages
markdown_pages: true
# User Guide Directory
# user_guide: docs/guides
# Homepage Mode
# homepage: user_guide # First UG page becomes the landing page
# CLI Documentation
cli:
enabled: true
# Changelog (GitHub Releases)
changelog:
enabled: true
max_releases: 50
# Custom Sections
sections:
- title: Examples
dir: examples
- title: Tutorials
dir: tutorials
navbar_after: Examples
- title: Blog
dir: blog
type: blog
# API Reference Structure
reference:
title: "API Reference"
desc: "Complete reference for the library's public API."
sections:
- title: Core Classes
desc: Main classes for the library
contents:
- name: MainClass
members: false
- HelperClass
- title: MainClass Methods
desc: Methods for the MainClass
contents:
- MainClass.process
- MainClass.validate
- title: Utility Functions
desc: Helper functions
contents:
- utility_func
- helper_func
# Authors
authors:
- name: Jane Developer
email: jane@example.com
role: Lead Developer
github: janedev
orcid: 0000-0001-2345-6789
- name: John Contributor
role: Contributor
github: johncontrib
# Agent Skills (skill.md)
skill:
gotchas:
- "Always call init() before using other functions"
best_practices:
- "Use context managers for resource cleanup"
decision_table:
- need: "Create a widget"
use: "Widget()"
- need: "Process data"
use: "MainClass.process()"
```
You don't need all of these settings. Start with just the options you need and add more as your project grows. The defaults work well for most packages, so you may find that a minimal configuration (or none at all) is sufficient.
# Generating a Configuration File
To create a starter `great-docs.yml` with all options documented:
``` bash
great-docs config
```
This creates a file with all available options as comments, making it easy to enable the features you need.
# Quarto Configuration
Great Docs generates and maintains a `_quarto.yml` file in the `great-docs/` output directory. This is an internal file that controls how Quarto renders your site, including navigation, theming, and the API reference configuration. It is regenerated on every `great-docs build`.
**Should you edit it?** No. Any manual edits will be overwritten on the next build. All customization should go through `great-docs.yml`, which is the single source of truth for your documentation configuration.
**Should you commit it?** No. The entire `great-docs/` output directory is ephemeral and should be gitignored (which `great-docs init` offers to set up for you).
# Next Steps
With `great-docs.yml` you control everything from API discovery and docstring parsing to sidebar layout and GitHub integration. Most projects only need a handful of settings, but the full range is here when you need it.
- [Theming & Appearance](theming.md) covers logos, gradients, banners, dark mode, hero sections, and other visual options
- [API Documentation](api-documentation.md) explains how API discovery and organization works
- [CLI Documentation](cli-documentation.md) covers Click CLI documentation
- [Cross-Referencing](cross-referencing.md) covers the Great Docs Linking System (GDLS)