User Guides

API reference pages are valuable, but they only describe individual functions and classes in isolation. For users to truly understand your project, they need narrative documentation: tutorials that walk them through real tasks, guides that explain concepts in context, and explanations that connect the pieces together. Without this kind of content, users are left to figure out the bigger picture on their own.

Great Docs treats user guides as first-class content. When you add a user_guide/ directory to your project, Great Docs automatically generates sidebar navigation, adds a navbar link, applies narrative-optimized styling, and keeps everything in sync across builds. You write Quarto Markdown files and Great Docs handles the rest.

Creating a User Guide

Getting started takes just three steps:

  1. create a user_guide/ directory in your project root
  2. add .qmd files for each page
  3. run great-docs build

Great Docs automatically:

  • copies files to great-docs/user-guide/
  • generates sidebar navigation
  • adds a β€œUser Guide” link to the navbar
  • organizes pages into sections

No additional configuration is required. As soon as Great Docs finds .qmd files in the user_guide/ directory, the User Guide section appears in your site.

Directory Structure

A typical project with a User Guide looks like this:

Project structure
your-project/
β”œβ”€β”€ great-docs/              # Build directory (ephemeral, gitignored)
β”‚   β”œβ”€β”€ user-guide/          # Copied from user_guide/
β”‚   └── ...
β”œβ”€β”€ user_guide/              # Your source files (committed to git)
β”‚   β”œβ”€β”€ 00-introduction.qmd
β”‚   β”œβ”€β”€ 01-installation.qmd
β”‚   β”œβ”€β”€ 02-quickstart.qmd
β”‚   β”œβ”€β”€ 03-configuration.qmd
β”‚   └── images/              # Asset directories are copied too
β”‚       └── screenshot.png
β”œβ”€β”€ great-docs.yml
β”œβ”€β”€ pyproject.toml
└── your_package/

The user_guide/ directory is the default location. You can use a custom directory by setting user_guide in great-docs.yml.

Page Ordering

The order of pages in the sidebar matters for guiding readers through your content in a logical sequence. Files are sorted alphabetically by filename, so numeric prefixes give you full control over the ordering:

user_guide/
user_guide/
β”œβ”€β”€ 00-introduction.qmd    # First
β”œβ”€β”€ 01-installation.qmd    # Second
β”œβ”€β”€ 02-getting-started.qmd # Third
└── 03-advanced.qmd        # Fourth

The prefix is stripped from the title, so 01-installation.qmd becomes β€œInstallation” in the navigation. This means you can reorder pages at any time by renaming files without affecting how titles appear in the sidebar.

Organizing into Sections

As your user guide grows, flat lists of pages become hard to navigate. Sections let you group related pages together so readers can find what they need and understand how topics relate to each other.

The simplest approach is the guide-section frontmatter key:

01-installation.qmd
---
title: "Installation"
guide-section: "Getting Started"
---

Pages with the same guide-section value are grouped together in the sidebar:

Sidebar navigation
User Guide
β”œβ”€β”€ Getting Started
β”‚   β”œβ”€β”€ Introduction
β”‚   └── Installation
β”œβ”€β”€ Core Concepts
β”‚   β”œβ”€β”€ Configuration
β”‚   └── API Documentation
└── Advanced
    └── Customization

This grouping is purely visual in the sidebar. The pages themselves remain as flat files in the user_guide/ directory.

Section Order

Sections appear in the order they’re first encountered (based on file sort order). To control section order, ensure the first file in each section has the appropriate prefix:

user_guide/
user_guide/
β”œβ”€β”€ 00-introduction.qmd      # guide-section: "Getting Started"
β”œβ”€β”€ 01-installation.qmd      # guide-section: "Getting Started"
β”œβ”€β”€ 10-configuration.qmd     # guide-section: "Core Concepts"
β”œβ”€β”€ 11-api-docs.qmd          # guide-section: "Core Concepts"
β”œβ”€β”€ 20-customization.qmd     # guide-section: "Advanced"

Subdirectory-Based Sections

For larger user guides, you may prefer organizing pages into actual subdirectories rather than using frontmatter. Each subdirectory becomes a section in the sidebar, with the section title derived from the subdirectory’s index.qmd title (or the directory name if there is no index.qmd):

user_guide/
user_guide/
β”œβ”€β”€ index.qmd                        # Root page (appears first in sidebar)
β”œβ”€β”€ getting-started/
β”‚   β”œβ”€β”€ index.qmd                    # Section title: "Getting Started"
β”‚   β”œβ”€β”€ installation.qmd
β”‚   └── quickstart.qmd
└── advanced/
    β”œβ”€β”€ index.qmd                    # Section title: "Advanced Usage"
    β”œβ”€β”€ configuration.qmd
    └── deployment.qmd

This produces a sidebar like:

Sidebar navigation
User Guide
β”œβ”€β”€ User Guide           # Root index.qmd
β”œβ”€β”€ Getting Started
β”‚   β”œβ”€β”€ Installation
β”‚   └── Quickstart
└── Advanced Usage
    β”œβ”€β”€ Configuration
    └── Deployment

A root-level index.qmd is recommended so the β€œUser Guide” navbar link has a landing page. Subdirectory index.qmd files provide section titles but don’t appear as separate pages in the sidebar. Rather, their title is used as the collapsible section heading.

Subdirectories are sorted alphabetically by directory name. To control the order of sections and pages within them, use numeric prefixes. They are stripped from both directory names and filenames in URLs and navigation:

user_guide/
user_guide/
β”œβ”€β”€ index.qmd
β”œβ”€β”€ 01-getting-started/
β”‚   β”œβ”€β”€ index.qmd                    # Section title: "Getting Started"
β”‚   β”œβ”€β”€ 01-installation.qmd
β”‚   └── 02-quickstart.qmd
β”œβ”€β”€ 02-guides/
β”‚   β”œβ”€β”€ index.qmd                    # Section title: "Guides"
β”‚   β”œβ”€β”€ 01-configuration.qmd
β”‚   └── 02-troubleshooting.qmd
└── 03-advanced/
    β”œβ”€β”€ index.qmd                    # Section title: "Advanced"
    └── 01-deployment.qmd

The prefixes control ordering but don’t appear in the output:

  • 01-getting-started/ β†’ getting-started/ in URLs
  • 01-installation.qmd β†’ installation.html in rendered pages
  • Numbering restarts at 01- in each subdirectory

This pattern gives you full control over section and page order while keeping URLs clean.

The subdirectory approach works well for larger user guides where the directory structure itself communicates the organization, while guide-section frontmatter is better suited for flat file layouts.

Writing Pages

User Guide pages are standard Quarto Markdown files, which means you have access to all of Quarto’s powerful features for creating rich, interactive documentation. Here are some of the most useful features for writing guides.

Basic Frontmatter

Every User Guide page needs frontmatter at the top to define its title and section. The title appears in the sidebar navigation and as the page heading, while guide-section determines which group the page belongs to:

your-page.qmd
---
title: "Your Page Title"
guide-section: "Section Name"
---

Code Blocks

Code blocks with syntax highlighting are essential for technical documentation. Specify the language after the opening backticks to enable highlighting:

```python
from great_docs import GreatDocs

docs = GreatDocs()
docs.build()
```

Quarto supports syntax highlighting for dozens of languages including Python, JavaScript, TypeScript, R, Bash, YAML, TOML, and many more.

For Python code that you want to actually execute and show the output, use {python} instead of just python. You can control execution behavior with hash-pipe options at the top of the code block. Some useful hash-pipe options include:

  • #| echo: false: hide the code, show only output
  • #| eval: false: show the code but don’t run it
  • #| output: false: run the code but hide output
  • #| warning: false: suppress warning messages
  • #| fig-cap: "Caption": add a caption to figure output

Tabsets

Tabsets let you present alternative content (like code in multiple languages or instructions for different platforms) without cluttering the page. Readers can click to switch between tabs:

::: {.panel-tabset}

## Python

```python
print("Hello")
```

## JavaScript

```javascript
console.log("Hello");
```

:::

This is particularly useful for showing installation commands for different operating systems or demonstrating concepts in multiple programming languages.

Callouts

Callouts draw attention to important information. Use them sparingly to highlight notes, warnings, or tips that readers shouldn’t miss:

::: {.callout-note}
This is a note.
:::

::: {.callout-warning}
This is a warning.
:::

::: {.callout-tip}
This is a tip.
:::

Each callout type has distinct styling. Notes are informational, warnings alert readers to potential issues, and tips offer helpful suggestions.

Images

Visual content like screenshots, diagrams, and architecture charts can greatly improve documentation. Store images in a subdirectory to keep your User Guide organized:

user_guide/
user_guide/
β”œβ”€β”€ 01-getting-started.qmd
└── images/
    └── screenshot.png

Reference them in your content using standard Markdown image syntax. The alt text in brackets improves accessibility:

![Screenshot](images/screenshot.png)

Cross-References

Link freely between pages to help readers navigate related content. For other User Guide pages, use relative paths:

See the [Installation](installation.qmd) guide for details.

To link to API reference pages, use a relative path that goes up one directory level first:

See the [GreatDocs](../reference/GreatDocs.qmd) class for the full API.

These links are validated during the build, so you’ll catch broken references early.

Asset Directories

User guide pages often need supporting files like images, diagrams, or sample data. Any subdirectory that doesn’t contain .qmd files is treated as an asset directory and copied as-is:

user_guide/
user_guide/
β”œβ”€β”€ 01-guide.qmd
β”œβ”€β”€ images/          # Copied to great-docs/user-guide/images/
β”‚   β”œβ”€β”€ logo.png
β”‚   └── diagram.svg
└── data/            # Copied to great-docs/user-guide/data/
    └── example.json

This means you can reference images and other files using simple relative paths (e.g., images/screenshot.png) in your .qmd files, and Great Docs will make sure those files are available in the built site.

User Guide Styling

Because user guides serve a different purpose than API references, Great Docs applies different styling to match. The sidebar filter that helps navigate large API listings is hidden since user guides are typically smaller and have a clear hierarchical structure. Breadcrumb navigation is also removed to provide a cleaner reading experience. The sidebar itself uses section-based navigation that mirrors your guide-section organization, making it easy for readers to see where they are in the guide.

These styling differences are applied automatically. You don’t need to configure anything to get the narrative-optimized layout.

Example: This User Guide

The User Guide you’re reading right now is built with Great Docs, using the same features described on this page. Here’s a representative sample of its structure:

user_guide/
user_guide/
β”œβ”€β”€ 00-introduction.qmd           # Getting Started
β”œβ”€β”€ 01-installation.qmd           # Getting Started
β”œβ”€β”€ 02-quickstart.qmd             # Getting Started
β”œβ”€β”€ 03-authoring-qmd-files.qmd    # Getting Started
β”œβ”€β”€ 04-writing-docstrings.qmd     # Getting Started
β”œβ”€β”€ 05-configuration.qmd          # Config & Theming
β”œβ”€β”€ 06-api-documentation.qmd      # Site Content
β”œβ”€β”€ 07-cli-documentation.qmd      # Site Content
β”œβ”€β”€ 08-user-guides.qmd            # Site Content (this page)
β”œβ”€β”€ ...                           # 26 more pages
└── 35-keyboard-keys.qmd          # Site Content

The guide spans 36 pages organized across five sections: Getting Started, Config & Theming, Site Content, Build & Deploy, and Quality & Maintenance. Numeric prefixes control page order, and guide-section frontmatter handles the grouping.

Custom User Guide Directory

By default, Great Docs looks for a user_guide/ directory in your project root. If you need your User Guide source files in a different location (e.g., inside a docs/ folder or a monorepo subdirectory), you can specify a custom path in great-docs.yml:

great-docs.yml
user_guide: docs/guides

The path is relative to the project root. Any directory structure works, including nested paths:

great-docs.yml
user_guide: content/user-docs

Precedence Rules

If both a user_guide config option and a conventional user_guide/ directory exist, the config option takes precedence and the user_guide/ directory is ignored. Great Docs will print a warning to let you know:

⚠️  Both 'user_guide' config option ('docs/guides') and 'user_guide/' directory exist; using
configured path

Warnings

Great Docs warns you if the resolved directory:

  • Doesn’t exist: the path specified in user_guide couldn’t be found
  • Is empty: the directory exists but contains no files at all
  • Has no .qmd files: the directory exists but doesn’t contain any Quarto Markdown files

In all three cases, the User Guide is skipped and processing continues normally.

Tips

These tips cover common patterns and best practices for maintaining user guides as they grow.

Keep Source Separate from Output

Whether you use the default user_guide/ directory or a custom path, Great Docs copies files to great-docs/user-guide/ during each build, keeping your source separate from generated output.

Use Descriptive Titles

The title in frontmatter appears in navigation. Make it clear and concise:

---
title: "Configuration Options"  # Good
guide-section: "Reference"
---

Organize Logically

Group related content into sections that make sense for your users. A common pattern starts with β€œGetting Started” content that covers installation and quick start guides. This is everything new users need to get up and running. β€œCore Concepts” sections explain the main features and typical usage patterns. β€œAdvanced” sections dive into complex topics and customization options for power users. Finally, a β€œReference” section can house configuration options and troubleshooting guides. Adapt this structure to fit your project’s needs.

Next Steps

User guides bring the narrative depth that API references alone can’t provide. With numbered files, frontmatter sections, and automatic sidebar generation, you can build a structured guide that grows alongside your project.

  • Custom Sections explains how to add entirely new sidebar sections beyond the User Guide and API reference
  • Cross-Referencing covers linking between User Guide pages and API reference pages
  • Theming lets you customize the look and feel of your entire site, including User Guide pages
  • Deployment covers publishing your finished documentation to GitHub Pages