User Guides

Beyond API reference documentation, you often need narrative documentation: tutorials, guides, and explanations. Great Docs makes this easy with automatic User Guide support.

Creating a User Guide

To add a User Guide to your documentation:

Create a user_guide/ directory in your project root
Add .qmd files for each page
Run great-docs build

That’s it! 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

Directory Structure

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

Files are sorted alphabetically by filename. Use numeric prefixes to control order:

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.

Organizing into Sections

Group related pages into sections using 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

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

As an alternative to guide-section frontmatter, you can organize pages into subdirectories. 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

Subdirectories that don’t contain .qmd files are treated as asset directories 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

User Guide Styling

Great Docs applies different styling to User Guide pages compared to API reference pages, optimizing for the narrative documentation experience. The sidebar filter that helps navigate large APIs 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 documentation.

Example: This User Guide

The Great Docs User Guide you’re reading uses this exact structure:

user_guide/
├── 00-introduction.qmd      # Getting Started
├── 01-installation.qmd      # Getting Started
├── 02-quickstart.qmd        # Getting Started
├── 03-configuration.qmd     # Core Concepts
├── 04-api-documentation.qmd # Core Concepts
├── 05-cli-documentation.qmd # Core Concepts
├── 06-user-guides.qmd       # Core Concepts
└── 07-deployment.qmd        # Deployment

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

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

Deployment covers publishing your documentation to GitHub Pages