# Welcome to Great Docs

Great Docs is a documentation site generator for Python packages. Run one command, get a complete documentation site. Customize as much or as little as you want.


# Get Up and Running Fast

Point Great Docs at your Python package and it does the rest. `great-docs init` scans your codebase, discovers your public API, detects your docstring format, and writes all the configuration for you. Then `great-docs build` produces a full documentation site (landing page, API reference, navigation) ready to preview and deploy.

No templates to author. No content pages to write by hand. No build system to learn.


# Your Site Looks Great From the Start

The default site isn't a starting point you'll need to overhaul. It's a polished, modern documentation site right away: dark mode, responsive layout, GitHub integration, structured parameter tables, and source links. Whether your package exposes a handful of functions or a deep class hierarchy, Great Docs figures out how to present it well.


# Explore a World of Possibilities

When you're ready for more, there's a lot here:

- Narrative user guides and tutorials alongside your API reference
- Blogs, recipe sections, custom pages, and additional content sections
- Diagrams, videos, color swatches, and interactive table previews
- Gradient themes, announcement banners, and custom branding
- Internationalization across twenty-three languages

Every feature is opt-in. Your site stays clean until you decide to expand it.


# Go as Deep as You Need

As your project grows, Great Docs keeps up. Publish multiple versions with a version selector. Track API changes across releases. Run the built-in link checker, linter, and proofreader. Generate `llms.txt` for AI tools. Deploy to GitHub Pages in one step.

We keep on building the tools you'll need, and they'll be here when the time is right for you.


# What You'll Learn

This User Guide covers everything you need to know to build and maintain great documentation sites. Here's what to expect:

**Getting started**: Installing Great Docs, creating your first site, authoring `.qmd` files, writing effective docstrings, and understanding the project structure.

**Configuration and theming**: Tuning site behavior through `great-docs.yml`, customizing appearance, setting up cross-references, internationalization, and responsive scaling.

**Site content**: Auto-generated API and CLI references, narrative user guides, custom sections and static pages, blogs, diagrams, videos, tables, color swatches, and more.

**Building and deployment**: Previewing locally, publishing to GitHub Pages, SEO optimization, social cards, and multi-version documentation.

**Quality and maintenance**: Link checking, proofreading, linting, changelogs, community files, page status badges, and tracking API evolution.


# Next Steps

This User Guide covers everything from first install to production deployment. Start at the beginning or jump to whatever topic you need.

- [Installation](installation.md) gets Great Docs and Quarto set up on your machine
- [Quick Start](quickstart.md) walks you through creating your first documentation site
- [Authoring QMD Files](authoring-qmd-files.md) teaches the Markdown, frontmatter, and Quarto features you'll use everywhere