# 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


``` default
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](#custom-user-guide-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/


``` default
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


``` yaml
---
title: "Installation"
guide-section: "Getting Started"
---
```


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


    Sidebar navigation


``` default
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/


``` default
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/


``` default
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


``` default
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/


``` default
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


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

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

```` markdown
::: {.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:

``` markdown
::: {.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/


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

``` markdown
![Screenshot](images/screenshot.png)
```


## Cross-References

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

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

``` markdown
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/


``` default
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/


``` default
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


``` yaml
user_guide: docs/guides
```


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


    great-docs.yml


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

``` yaml
---
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](custom-sections.md) explains how to add entirely new sidebar sections beyond the User Guide and API reference
- [Cross-Referencing](cross-referencing.md) covers linking between User Guide pages and API reference pages
- [Theming](theming.md) lets you customize the look and feel of your entire site, including User Guide pages
- [Deployment](deployment.md) covers publishing your finished documentation to GitHub Pages