---
title: "User Guides"
guide-section: "Site Content"
tags: [Content]
---

# 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:

```{.default filename="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](#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:

```{.default filename="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:

```{.yaml filename="01-installation.qmd"}
---
title: "Installation"
guide-section: "Getting Started"
---
```

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

```{.default filename="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:

```{.default filename="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`):

```{.default filename="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:

```{.default filename="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:

```{.default filename="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.

### Mixing Root Files and Subdirectories

You can mix root-level files with subdirectory sections in the same user guide. Numeric prefixes
sort them together so the nav order follows the prefix regardless of whether an item is a file or a
directory:

```{.default filename="user_guide/"}
user_guide/
├── 01-overview.qmd              # Page: Overview
├── 02-concepts/
│   ├── index.qmd                # Section title: "Concepts"
│   └── details.qmd
└── 03-quickstart.qmd            # Page: Quickstart
```

This produces a sidebar that interleaves files and sections in prefix order:

```{.default filename="Sidebar navigation"}
User Guide
├── Overview
├── Concepts
│   └── Details
└── Quickstart
```

A root-level `index.qmd` always appears first regardless of its prefix.

::: {.callout-warning}
Avoid giving a root file and a subdirectory the same base name (e.g., `02-concepts.qmd` alongside
`02-concepts/`). After numeric prefixes are stripped from URLs, both would map to the same
`concepts` path, which causes duplicate entries in the sidebar.
:::

## 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:

```{.yaml filename="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:

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

```{.default filename="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:

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

```{.default filename="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:

```{.default filename="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`:

```{.yaml filename="great-docs.yml"}
user_guide: docs/guides
```

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

```{.yaml filename="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:

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