<p align="center">
<a href="https://posit-dev.github.io/great-docs/">
<img src="https://posit-dev.github.io/great-docs/assets/logo.svg" alt="Great Docs" width="350">
</a>
</p>
<p align="center">Documentation sites for Python packages: start simple, go deep</p>
<p align="center">
<a href="https://pypi.org/project/great-docs/"><img src="https://img.shields.io/pypi/v/great-docs?logo=python&logoColor=white&color=orange" alt="PyPI"></a>
<a href="https://pypi.org/project/great-docs/"><img src="https://img.shields.io/pypi/pyversions/great-docs.svg" alt="Python versions"></a>
<a href="https://pypistats.org/packages/great-docs"><img src="https://img.shields.io/pypi/dm/great-docs" alt="Downloads"></a>
<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
<a href="https://github.com/posit-dev/great-docs/actions/workflows/test.yml"><img src="https://github.com/posit-dev/great-docs/actions/workflows/test.yml/badge.svg?branch=main" alt="CI"></a>
</p>
<p align="center">
<a href="https://www.repostatus.org/#active"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Repo Status"></a>
<a href="https://posit-dev.github.io/gdg/"><img src="https://img.shields.io/badge/Great%20Docs%20Gauntlet-300%2B%20test%20sites-7c3aed?logo=pytest&logoColor=white" alt="Great Docs Gauntlet"></a>
</p>
<p align="center">
<a href="https://posit-dev.github.io/great-docs/"><img src="https://img.shields.io/badge/docs-project_website-blue.svg" alt="Documentation"></a>
<a href="https://github.com/posit-dev/great-docs/graphs/contributors"><img src="https://img.shields.io/github/contributors/posit-dev/great-docs" alt="Contributors"></a>
<a href="https://deepwiki.com/posit-dev/great-docs"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
<a href="https://www.contributor-covenant.org/version/3/0/"><img src="https://img.shields.io/badge/Contributor%20Covenant-v3.0%20adopted-ff69b4.svg" alt="Contributor Covenant"></a>
</p>
<p align="center">
<a href="#get-started-in-60-seconds">Quickstart</a> ·
<a href="#full-feature-set">Features</a> ·
<a href="#configuration">Configuration</a> ·
<a href="#recipes">Recipes</a> ·
<a href="https://posit-dev.github.io/great-docs/">Docs</a>
</p>

---

> [!TIP]
> **📺 Featured on Talk Python:** [**the "Great Docs" live stream**](https://www.youtube.com/live/rj2hY2Bsi30)
>
> See Great Docs in action and hear the story behind it: a full walkthrough on Talk Python.
>
> <a href="https://www.youtube.com/live/rj2hY2Bsi30"><img src="https://img.youtube.com/vi/rj2hY2Bsi30/maxresdefault.jpg" alt="Watch the Great Docs live stream on Talk Python" width="480"></a>

Great Docs turns your Python package into a polished documentation site in minutes. It auto-discovers your public API, detects your docstring format, generates structured reference pages, and renders a modern site, all from a single command. When you're ready to customize, there's a deep set of tools and options waiting for you.

And it's battle-tested: every release runs against [300+ synthetic packages](https://posit-dev.github.io/gdg/) in the Great Docs Gauntlet, backed by a suite of 15,600+ tests.

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/landing-demo.svg" alt="Great Docs in action: init, build, and preview a documentation site" width="720">
</p>
<p align="center"><em>From zero to a live site in three commands.</em></p>

<p align="center">
<a href="https://posit-dev.github.io/great-docs/assets/great-docs-tour.mp4"><img src="https://posit-dev.github.io/great-docs/assets/great-docs-tour-poster.png" alt="Watch a 22-second tour of a generated Great Docs site" width="720"></a>
</p>
<p align="center"><em>A 22-second tour of a generated site: going through some of the site's many useful pages. Great Docs documents itself -> <a href="https://posit-dev.github.io/great-docs/">explore the live site</a>.</em></p>

## Why Great Docs?

Writing documentation shouldn't be harder than writing the code it describes. Most documentation generators require you to author page templates, organize content by hand, and wire up a build system. Great Docs inverts that: point it at a Python package and get a great site right away, then explore further at your own pace.

- **Instant setup**: `great-docs init` inspects your package and generates a complete config
- **Smart defaults**: API reference pages are created automatically from your code (no manual authoring needed)
- **Real documentation, not stubs**: renders full parameter tables, return types, examples, and cross-references from your existing docstrings
- **Looks great out of the box**: gradient navbars, dark mode, responsive layout, GitHub widget, sidebar search, keyboard navigation
- **Deep when you need it**: user guides, multi-version docs, freeze caching, link checking, proofreading, SEO, internationalization (20+ languages), and more (all opt-in)
- **AI-ready**: auto-generates `llms.txt`, agent skills, and markdown pages for LLM consumption
- **Deploys anywhere**: one command creates a GitHub Actions workflow for GitHub Pages

## How It Compares

Most Python documentation tools hand you a framework and ask you to assemble the site yourself. Great Docs assembles a complete site for you first, then gets out of the way when you want control.

| | Great Docs | Sphinx | MkDocs | pdoc |
| --- | :---: | :---: | :---: | :---: |
| Polished site with **zero config** | ✅ | ➖ | ➖ | ✅ |
| API reference from your docstrings | ✅ | ✅ | plugin | ✅ |
| Prose guides, recipes, custom pages | ✅ | ✅ | ✅ | ➖ |
| Click CLI **and** MCP server reference | ✅ | ➖ | ➖ | ➖ |
| Dark mode, search, theming built in | ✅ | theme | theme | basic |
| AI-ready: `llms.txt`, agent skills | ✅ | ➖ | ➖ | ➖ |
| Link check, lint, proofread, SEO | ✅ | partial | plugins | ➖ |

Great Docs is built on [Quarto](https://quarto.org/), so you get its rendering power (executable code, math, diagrams) without having to wire any of it up.

## Get Started in 60 Seconds

> [!IMPORTANT]
> Great Docs needs two things on your system: **Python 3.11+** and **[Quarto](https://quarto.org/docs/get-started/)**, the rendering engine. Quarto is a separate, one-time install (it isn't a Python package), so set it up before running the commands below. See [Requirements](#requirements) for details.

### Install

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

### Initialize, build, and preview

```bash
cd your-python-package

great-docs init     # auto-detect package, generate config
great-docs build    # generate and render the site
great-docs preview  # open in your browser at localhost:3000
```

That's it. Your documentation site is ready.

## What Gets Generated

Every site built by Great Docs includes:

### Landing Page

Your README is transformed into a landing page with a hero section, metadata sidebar (authors, license, links), and quick-start instructions.

### API Reference

Classes, functions, methods, and attributes are automatically organized into categorized sections. Large classes get dedicated method pages. Every item links back to source code on GitHub.

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/api-reference-index.png" alt="API reference index with categorized sections" width="720">
</p>

<details>
<summary>See more: class page and method page</summary>
<br>
<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/class-page.png" alt="A class documentation page with parameters and methods" width="720">
</p>
<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/method-page.png" alt="A method documentation page with signature and examples" width="720">
</p>
</details>

### CLI Reference

Click-based CLIs get rich, sectioned reference pages with usage signatures, typed options, and descriptions extracted directly from code. Each command page includes structured documentation alongside a collapsible `--help` output view.

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/cli-page.png" alt="CLI reference page with structured documentation and collapsible help output" width="720">
</p>

### MCP Server Reference

If your package ships an [MCP](https://modelcontextprotocol.io/) server, Great Docs generates structured reference pages for every tool, resource, and prompt it exposes. Parameters, types, required/optional markers, and descriptions are extracted automatically from your server definitions. Both standard MCP and [FastMCP](https://gofastmcp.com/) servers are detected automatically.

### Terminal Recordings

Teach your CLI visually with Termshow: record terminal sessions, edit them in a browser-based visual editor, and embed the results as animated SVG players in your documentation. Recordings are lightweight, theme-aware, and play inline without JavaScript dependencies. It's incredibly useful in onboarding guides, tutorials, and landing pages.

### Lightbox

Any image can expand into a focused, full-screen view. Add a `.lightbox` class to a single image or set `lightbox: auto` on a page to enlarge them all. The viewer supports zoom and panning, multi-image galleries with a filmstrip, captions and credits, dark-mode variants, image annotations, before/after comparison, and a copy/download toolbar. Assets load automatically, so there's nothing to install or enable.

### Dark Mode

A persistent dark mode toggle with flash-free loading. Your users' preference is remembered across visits.

<p align="center">
<img src="https://posit-dev.github.io/great-docs/assets/dark-mode.png" alt="Documentation site in dark mode" width="720">
</p>

## Full Feature Set

<details>
<summary><em>80+ capabilities across 8 categories (click to expand)</em></summary>
<br>

<table>
<tr>
<td width="50%" valign="top">

**Documentation Generation**

- Auto-discovers exports via `__all__`, `dir()`, or static analysis
- Detects NumPy, Google, and Sphinx docstring formats
- 13 object types with smart categorization
- Click CLI documentation
- User Guide pages from `user_guide/` directory
- Custom sections (recipes, blog, tutorials, etc.)
- Custom HTML pages with passthrough or raw layouts
- Multi-version documentation with version selector
- Video embeds (YouTube, Vimeo, local files)
- Mermaid diagram pre-rendering (light + dark variants)
- Freeze/cache support for expensive computations

</td>
<td width="50%" valign="top">

**Site Features**

- Dark mode toggle with persistent preference
- Lightbox image viewer (zoom, pan, galleries)
- GitHub widget with live star/fork counts
- Sidebar search filter for large APIs
- Source links to GitHub for every item
- Copy-to-clipboard for code blocks
- Responsive, mobile-friendly layout
- Page tags and tag index pages
- Page status badges (experimental, stable, deprecated)
- API evolution annotations (new, changed, deprecated)
- Social cards (Open Graph / Twitter)
- Keyboard navigation with shortcut overlay
- Back-to-top floating button
- Navigation icons (Lucide icon set)
- Scale-to-fit for wide HTML output

</td>
</tr>
<tr>
<td width="50%" valign="top">

**AI & LLM Integration**

- Auto-generates `llms.txt` and `llms-full.txt`
- Agent Skills generation ([agentskills.io](https://agentskills.io/) compliant)
- Multiple named skills per package
- Skill install/check/list CLI commands
- Markdown page generation for LLM consumption
- MCP server reference pages (tools, resources, prompts)

</td>
<td width="50%" valign="top">

**Configuration & Branding**

- Announcement banners (dismissible, styled)
- Logo with light/dark variants
- Custom favicon and Open Graph images
- Author metadata with ORCID support
- Changelog from GitHub Releases
- Internationalization (20+ languages)
- Accent color (global or per-mode)
- Navbar gradient presets or solid colors
- Content area gradient presets

</td>
</tr>
<tr>
<td width="50%" valign="top">

**Quality & Reliability**

- Built-in link checker
- Documentation linter (docstrings, cross-refs, style)
- Proofreading (spelling & grammar)
- SEO auditing (sitemap, robots.txt, canonical URLs, structured data)
- API diff between versions
- Build timings reporting
- Tested against 300+ synthetic packages via the [Great Docs Gauntlet](https://posit-dev.github.io/gdg/)
- 15,600+ tests

</td>
<td width="50%" valign="top">

**Deployment**

- One-command GitHub Pages setup
- GitHub Actions workflow generation
- Multi-version deployment with version selector
- Floating version aliases (`/v/latest/`, `/v/stable/`, `/v/dev/`)
- Custom domain support
- Static output: host anywhere

</td>
</tr>
<tr>
<td width="50%" valign="top">

**Shortcodes & Widgets**

- Color swatches (inline and grid)
- Lightbox (zoom, galleries, annotations, before/after compare)
- Terminal recordings (record, edit, embed)
- Collapsible details sections
- Keyboard keys styling
- Horizontal rules with accent colors
- Table previews (Python API for notebooks)
- Table explorer (interactive data tables)

</td>
<td width="50%" valign="top">

**Developer Experience**

- `great-docs init` auto-detects package manager (uv, poetry, pip)
- `great-docs freeze` for caching expensive computations
- `great-docs timings` for build performance insight
- Pre-render script hooks
- Page metadata timestamps (creation/modification dates)

</td>
</tr>
</table>

</details>

## Configuration

All configuration lives in a single `great-docs.yml` file in your project root. The `init` command generates it for you, but you can customize everything:

```yaml
# Theming
navbar_style: sky
content_style: lilac
dark_mode_toggle: true
accent_color: "#3b82f6"

# Branding
display_name: My Package
logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg

# Announcement banner
announcement:
  content: "v2.0 is here!"
  style: mint
  dismissable: true

# GitHub integration
repo: https://github.com/your-org/your-package # Optional override
github_style: widget

# CLI documentation
cli:
  enabled: true
  module: my_package.cli
  name: cli

# Multi-version documentation
versions:
  - tag: v2.0.0
    label: "2.0 (latest)"
  - tag: v1.5.0
    label: "1.5"

# Freeze cache for expensive computations
freeze: auto

# Internationalization
site:
  language: fr

# Custom sections
sections:
  - title: Recipes
    dir: recipes
    navbar_after: User Guide
```

Custom HTML pages can live in a `custom/` directory and are discovered automatically during build.

```html
---
title: Landing Page
layout: passthrough
navbar: true
---
<section class="hero">...</section>
```

Use `layout: passthrough` to wrap the HTML body with the normal Great Docs shell, or `layout: raw` to copy the HTML file through unchanged.
Set `navbar: true` to add the page to the site navbar using its title, or use `navbar: {text: Showcase, after: Guide}` for explicit navbar label and placement.

See the [Configuration Guide](https://posit-dev.github.io/great-docs/user-guide/configuration.html) for the full reference.

## Deploying to GitHub Pages

```bash
great-docs setup-github-pages
```

This creates a `.github/workflows/` file that builds and publishes your site on every push to `main`. Your docs stay in sync with your code automatically.

## CLI Commands

Beyond `init`, `build`, and `preview`, Great Docs includes a full suite of quality and maintenance tools:

| Command | Purpose |
| --- | --- |
| `great-docs scan` | Preview discovered exports before building |
| `great-docs lint` | Check for missing docstrings, broken cross-refs, style issues |
| `great-docs proofread` | Catch spelling and grammar problems |
| `great-docs check-links` | Validate all links in the built site |
| `great-docs seo` | Audit SEO health (sitemap, meta tags, structured data) |
| `great-docs api-diff OLD NEW` | Show API changes between two versions |
| `great-docs api-snapshot` | Capture a JSON snapshot of your public API |
| `great-docs versions` | List and validate multi-version configuration |
| `great-docs changelog` | Generate changelog from GitHub Releases |
| `great-docs freeze` | Execute specific pages and persist their freeze cache |
| `great-docs timings` | Show page-level build timings from the last build |
| `great-docs setup-github-pages` | Create CI workflow for GitHub Pages deployment |
| `great-docs config` | Generate a fully-documented config template |
| `great-docs uninstall` | Remove great-docs from your project |
| `great-docs skill install` | Install AI agent skills for your package |
| `great-docs skill check` | Check if installed skills are up to date |
| `great-docs skill list` | List available skills from a package or URL |
| `great-docs termshow record` | Record a terminal session as a `.termshow` file |
| `great-docs termshow edit` | Open the browser-based visual editor for a recording |
| `great-docs termshow play` | Preview a recording in the terminal |
| `great-docs termshow render` | Render SVG frames without a full site build |
| `great-docs termshow import-cast` | Import an asciinema `.cast` file |

## Recipes

The documentation includes 24 step-by-step recipes.

<details>
<summary><em>Browse all 24 recipes (click to expand)</em></summary>
<br>

### Content & API

| Recipe                                                                                                       | Topic                                      |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Hide Internal Symbols](https://posit-dev.github.io/great-docs/recipes/hide-internal-symbols.html)           | Control what appears in your API reference |
| [Customize API Organization](https://posit-dev.github.io/great-docs/recipes/customize-api-organization.html) | Structure reference sections your way      |
| [Document a CLI](https://posit-dev.github.io/great-docs/recipes/document-a-cli.html)                         | Auto-generate CLI reference from Click     |
| [Cross-Reference Items](https://posit-dev.github.io/great-docs/recipes/cross-reference-items.html)           | Link between documented objects            |
| [Write Effective Docstrings](https://posit-dev.github.io/great-docs/recipes/write-effective-docstrings.html) | Get the most out of auto-generated docs    |
| [Add Images & Diagrams](https://posit-dev.github.io/great-docs/recipes/add-images-diagrams.html)             | Include visuals in your documentation      |
| [Embed Videos](https://posit-dev.github.io/great-docs/recipes/embed-videos.html)                             | Add YouTube, Vimeo, and local videos       |

### Theming & Appearance

| Recipe                                                                                                             | Topic                                      |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Add Custom CSS](https://posit-dev.github.io/great-docs/recipes/add-custom-css.html)                               | Override styles with your own SCSS         |
| [Choose Gradient Theme](https://posit-dev.github.io/great-docs/recipes/choose-gradient-theme.html)                 | Pick and customize navbar gradients        |
| [Add Logo & Favicon](https://posit-dev.github.io/great-docs/recipes/add-logo-favicon.html)                         | Brand your site with custom icons          |
| [Customize Announcement Banner](https://posit-dev.github.io/great-docs/recipes/customize-announcement-banner.html) | Add dismissible site-wide notices          |

### Publishing & Versioning

| Recipe                                                                                                             | Topic                                      |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Create Changelog](https://posit-dev.github.io/great-docs/recipes/create-changelog.html)                           | Pull changelog from GitHub Releases        |
| [GitHub Pages & CI](https://posit-dev.github.io/great-docs/recipes/github-pages-ci.html)                           | Automate deployment with Actions           |
| [Add Custom Domain](https://posit-dev.github.io/great-docs/recipes/add-custom-domain.html)                         | Serve docs from your own domain            |
| [Enable Multi-Version Docs](https://posit-dev.github.io/great-docs/recipes/enable-multi-version-docs.html)         | Add a version selector to your site        |
| [Use Version Fences and Badges](https://posit-dev.github.io/great-docs/recipes/use-version-fences-and-badges.html) | Annotate version-specific content          |

### AI-Assisted Workflows

| Recipe                                                                                                   | Topic                                      |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [Install Great Docs Skill](https://posit-dev.github.io/great-docs/recipes/install-great-docs-skill.html) | Generate an Agent Skill for your package   |
| [Build Site with LLM](https://posit-dev.github.io/great-docs/recipes/build-site-with-llm.html)           | Use an AI assistant to set up your site    |
| [Customize Site with LLM](https://posit-dev.github.io/great-docs/recipes/customize-site-with-llm.html)   | Use an AI assistant to tweak your site     |
| [Understand llms.txt](https://posit-dev.github.io/great-docs/recipes/understand-llms-txt.html)           | Make your docs AI-accessible               |

### Build & Quality

| Recipe                                                                                                 | Topic                                      |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| [Fix Common Build Errors](https://posit-dev.github.io/great-docs/recipes/fix-common-build-errors.html) | Troubleshoot build issues quickly          |
| [Proofread Documentation](https://posit-dev.github.io/great-docs/recipes/proofread-documentation.html) | Catch spelling and grammar issues          |
| [Use Freeze Cache](https://posit-dev.github.io/great-docs/recipes/use-freeze-cache.html)               | Cache expensive notebooks across builds    |

</details>

## Documentation

Full documentation is available at **[posit-dev.github.io/great-docs](https://posit-dev.github.io/great-docs/)**.

<details>
<summary><em>Full guide index (27 pages, click to expand)</em></summary>
<br>

- [Installation](https://posit-dev.github.io/great-docs/user-guide/installation.html): setup and requirements
- [Quick Start](https://posit-dev.github.io/great-docs/user-guide/quickstart.html): first site in minutes
- [Configuration](https://posit-dev.github.io/great-docs/user-guide/configuration.html): every option explained
- [API Documentation](https://posit-dev.github.io/great-docs/user-guide/api-documentation.html): how API references are generated
- [CLI Documentation](https://posit-dev.github.io/great-docs/user-guide/cli-documentation.html): documenting Click CLIs
- [User Guides](https://posit-dev.github.io/great-docs/user-guide/user-guides.html): adding prose documentation
- [Custom Sections](https://posit-dev.github.io/great-docs/user-guide/custom-sections.html): recipes, blog, tutorials
- [Custom Pages](https://posit-dev.github.io/great-docs/user-guide/custom-pages.html): static HTML pages
- [Theming & Appearance](https://posit-dev.github.io/great-docs/user-guide/theming.html): gradients, colors, dark mode
- [Diagrams](https://posit-dev.github.io/great-docs/user-guide/diagrams.html): Mermaid diagram pre-rendering
- [Videos](https://posit-dev.github.io/great-docs/user-guide/videos.html): embedding YouTube, Vimeo, and local videos
- [Internationalization](https://posit-dev.github.io/great-docs/user-guide/internationalization.html): 20+ language translations
- [Deployment](https://posit-dev.github.io/great-docs/user-guide/deployment.html): GitHub Pages and beyond
- [Multi-Version Docs](https://posit-dev.github.io/great-docs/user-guide/multi-version-docs.html): version selector and versioned builds
- [API Evolution](https://posit-dev.github.io/great-docs/user-guide/api-evolution.html): tracking API changes across versions
- [Freeze](https://posit-dev.github.io/great-docs/user-guide/freeze.html): caching expensive computations
- [Scale to Fit](https://posit-dev.github.io/great-docs/user-guide/scale-to-fit.html): auto-shrink wide output
- [Page Tags](https://posit-dev.github.io/great-docs/user-guide/page-tags.html): categorize pages with tags
- [Page Status Badges](https://posit-dev.github.io/great-docs/user-guide/page-status-badges.html): lifecycle indicators
- [Social Cards](https://posit-dev.github.io/great-docs/user-guide/social-cards.html): Open Graph and Twitter cards
- [Agent Skills](https://posit-dev.github.io/great-docs/user-guide/agent-skills.html): AI coding agent integration
- [Link Checker](https://posit-dev.github.io/great-docs/user-guide/link-checker.html): validate all links
- [Proofreading](https://posit-dev.github.io/great-docs/user-guide/proofreading.html): spelling & grammar checks
- [Linting](https://posit-dev.github.io/great-docs/user-guide/linting.html): documentation quality checks
- [SEO](https://posit-dev.github.io/great-docs/user-guide/seo.html): search engine optimization
- [Terminal Recordings](https://posit-dev.github.io/great-docs/user-guide/terminal-recordings.html): record, edit, and embed terminal sessions
- [Lightbox](https://posit-dev.github.io/great-docs/user-guide/lightbox.html): full-screen image viewer with zoom, galleries, and annotations

</details>

## Requirements

- **Python 3.11+**
- **[Quarto](https://quarto.org/docs/get-started/)** (the rendering engine)

## Contributing

Contributions are welcome! Please see [CONTRIBUTING](https://posit-dev.github.io/great-docs/contributing.html) for guidelines and the [Code of Conduct](https://posit-dev.github.io/great-docs/code-of-conduct.html).

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<p align="center">
Built by <a href="https://posit.co">Posit, PBC</a>.
</p>
