Installation

This guide covers how to install Great Docs and its prerequisites.

Prerequisites

Before installing Great Docs, ensure you have:

  • Python 3.11 or later
  • Quarto – The publishing system that renders your documentation

Installing Quarto

Great Docs uses Quarto to render documentation. Install it from quarto.org:

Terminal
# Using Homebrew
brew install quarto

# Or download the installer from quarto.org
SVG generation is not working

Please confirm the successful import via

Python
import cairosvg

If cairosvg is installed but the required libraries still cannot be found, add the brew dynamic library to your terminal environment by running:

Terminal
echo 'export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_FALLBACK_LIBRARY_PATH"' >> ~/.zshrc
Terminal
# Download and install the .deb package (Ubuntu/Debian)
# Get the latest release URL from https://quarto.org/docs/get-started/
wget <quarto-release-url>.deb
sudo dpkg -i <quarto-release-filename>.deb

# Or use your package manager

Download and run the installer from quarto.org.

Verify the installation:

Terminal
quarto --version

Installing Great Docs

From PyPI

The simplest way to install Great Docs:

Terminal
pip install great-docs

From GitHub

Install the latest development version directly from GitHub:

Terminal
pip install git+https://github.com/posit-dev/great-docs.git

Or install a specific version:

Terminal
# Install from a specific branch
pip install git+https://github.com/posit-dev/great-docs.git@main

# Install from a specific tag
pip install git+https://github.com/posit-dev/great-docs.git@v0.1.0

Development Installation

For contributing to Great Docs or testing the latest features:

Terminal
# Clone the repository
git clone https://github.com/posit-dev/great-docs.git
cd great-docs

# Install in editable mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Verify Installation

After installation, verify everything is working:

Terminal
# Check Great Docs version
great-docs --help

# Check Quarto version
quarto --version

You should see the Great Docs help message and the Quarto version number.

Upgrading Great Docs

When a new version of Great Docs is released, upgrade using the same tool you used to install it:

Terminal
pip install --upgrade great-docs
Terminal
uv pip install --upgrade great-docs

If Great Docs is declared in your pyproject.toml dependencies, update the version constraint there and run uv sync instead.

Terminal
pipx upgrade great-docs

After upgrading

  1. Verify the new version

    Terminal
    great-docs --version

  2. Review the changelog — Check the release notes for breaking changes, new configuration options, or deprecated features that may affect your site.

  3. Rebuild your site — Run great-docs build to pick up any changes in the build pipeline, templates, or default configuration.

Tip

You do not need to re-execute user guide notebooks after upgrading. A plain great-docs build is sufficient as it regenerates reference pages and templates without re-running notebook code (which can be time-consuming).

Next Steps

With Great Docs and Quarto installed, you’re ready to generate your first documentation site.

  • Quick Start walks you through great-docs init and great-docs build
  • Configuration covers customizing behavior through great-docs.yml