# Quick Start

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


# Initialize Your Documentation

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


    Terminal


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


    Terminal output


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

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

✅ Great Docs initialization complete!

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

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


> **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.md) for all available options.


# Build Your Documentation

Build (and rebuild) your docs with:


    Terminal


``` bash
great-docs build
```


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


    Build output (abbreviated)


``` default
━━ Step  1/19 ─ Prepare build directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   [OK] great-docs/ ready                                                <0.1s

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

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

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

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

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


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

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

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


    Terminal


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


    Project structure


``` default
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/
    └── ...
```


> **Important: What to Commit**
>
> - ✅ `great-docs.yml` - Your configuration
> - ✅ `user_guide/` - Your narrative documentation
> - ✅ `README.md` - Your project readme
> - ❌ `great-docs/` - Ephemeral build directory (gitignored)


# Scan Your API

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


    Terminal


``` bash
great-docs scan            # Show discovered exports
great-docs scan --verbose  # Include method names for each class
```


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


# Command Options


## Initialize Options


    Terminal


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


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


    Terminal


``` bash
# Skip API re-discovery for faster rebuilds
great-docs build --no-refresh

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

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

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


## Preview Options


    Terminal


``` bash
# Preview on the default port (3000)
great-docs preview

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


# Using the Python API

You can also use Great Docs programmatically:


    Python


``` python
from great_docs import GreatDocs

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

# Build documentation
docs.build()

# Preview documentation
docs.preview()

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


# Next Steps

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

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