Custom Sections

Great Docs lets you add any number of custom page groups to your documentation site — examples, tutorials, demos, or anything else. Each section gets its own navbar link and sidebar navigation. By default, the navbar links directly to the first page in the section. Set index: true to generate a card-based index page instead. For blog-style content, there’s a dedicated type: blog mode that uses Quarto’s native listing directive.

Quick Start

Create a directory in your project root with .qmd files:

my-package/
├── examples/
│   ├── 01-basic-usage.qmd
│   ├── 02-advanced.qmd
│   └── 03-real-world.qmd
├── great-docs.yml
└── ...

Add the section to great-docs.yml:

great-docs.yml

sections:
  - title: Examples
    dir: examples

Run great-docs build — the Examples link appears in the navbar and the pages are rendered with a sidebar.

Configuration

Each section is defined as an entry in the sections array:

great-docs.yml

sections:
  - title: Examples          # Navbar link text (required)
    dir: examples            # Source directory (required)
    index: true              # Generate card-based index page (optional)
    navbar_after: User Guide  # Insert after this navbar item (optional)
    type: default            # Section type: "default" or "blog" (optional)

Required Fields

Field	Description
`title`	The text shown in the navbar link and sidebar heading
`dir`	Path to the source directory (relative to project root)

Optional Fields

Field	Default	Description
`index`	`false`	When `true`, auto-generates a card-based index page; when `false`, navbar links to the first page
`navbar_after`	Before “Reference”	Name of an existing navbar item to place this section after
`type`	`default`	`"default"` for card-grid index with sidebar; `"blog"` for Quarto listing page

Multiple Sections

Add as many sections as you need:

great-docs.yml

sections:
  - title: Examples
    dir: examples
  - title: Tutorials
    dir: tutorials
    navbar_after: Examples
  - title: Blog
    dir: blog
    type: blog
    navbar_after: Reference

This produces a navbar like:

Home | User Guide | Examples | Tutorials | Reference | Blog

Blog sections

The type: blog option uses Quarto’s native listing directive for date-sorted, searchable blog posts. See Blog for the full guide.

Navbar Positioning

By default, custom sections are inserted before “Reference” in the navbar. Use navbar_after to control placement:

`navbar_after` value	Result
(not set)	Before “Reference”
`Home`	After “Home”
`User Guide`	After “User Guide”
`Reference`	After “Reference”
`Changelog`	After “Changelog”

Sections appear in the order they’re listed in the config.

Page Files

Place .qmd or .md files in the section directory. Great Docs will:

Strip numeric prefixes from filenames for clean URLs (01-basic.qmd → basic.qmd)
Add bread-crumbs: false to frontmatter automatically
Copy all files to the build directory

Frontmatter

Each page’s YAML frontmatter is used to populate the auto-generated index and the sidebar:

examples/01-basic-usage.qmd

---
title: "Basic Usage"
description: "A simple example showing core functionality"
image: "img/basic.png"
---

Field	Used for
`title`	Sidebar link text, index page heading
`description`	Index page summary text
`image`	Index page thumbnail (optional)

Index Page

No Index (Default)

By default, sections do not get an index page. The navbar links directly to the first page in the section, and all pages are accessible via the sidebar. This is the simplest setup and works well when pages are self-explanatory.

Auto-Generated Index

Set index: true to generate a gallery-style index page with cards for each page, using each file’s title, description, and image from frontmatter:

great-docs.yml

sections:
  - title: Examples
    dir: examples
    index: true

Custom Index

If you provide your own index.qmd in the directory, Great Docs uses it as-is — regardless of the index setting. This gives you full control over the landing page layout — you can write custom HTML, use Quarto grid layouts, or embed interactive content.

examples/
├── index.qmd          ← Your custom gallery page
├── 01-basic.qmd
├── 02-advanced.qmd
└── img/
    ├── basic.png
    └── advanced.png

Subdirectories

Sections support nested subdirectories. Files in subdirectories are copied with their relative paths preserved:

tutorials/
├── getting-started/
│   ├── installation.qmd
│   └── first-steps.qmd
└── advanced/
    └── custom-config.qmd

Example: Visual Gallery

To create a visual gallery with a hand-crafted index page:

Create the directory structure:

demos/
├── index.qmd
├── 01-starter/
│   └── index.qmd
├── 02-advanced/
│   └── index.qmd
└── img/
    ├── starter.png
    └── advanced.png

Write your custom index.qmd with a visual grid:

demos/index.qmd

---
title: "Examples"
toc: false
---

:::::: {.column-page}
::::: {.grid}

:::{.g-col-lg-6 .g-col-12}
### [Starter](01-starter/index.qmd)
![](img/starter.png){width="100%"}
A validation with the basics.
:::

:::{.g-col-lg-6 .g-col-12}
### [Advanced](02-advanced/index.qmd)
![](img/advanced.png){width="100%"}
A comprehensive example.
:::

:::::
::::::

Add to config:

great-docs.yml

sections:
  - title: Examples
    dir: demos

Next Steps

Blog covers setting up a blog with Quarto’s listing directive
Configuration covers all available great-docs.yml options
User Guides covers the User Guide section setup