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.

If you need a single hand-written HTML page rather than a section of .qmd files, see Custom Static Pages. Custom sections and custom static pages are complementary features.

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

index_columns | 2 | Number of columns for image cards on the index page (1 or 2). Only applies when index: true New in 0.7 |

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

The generated index page renders entries in two zones:

Image cards — pages with an image field in frontmatter appear first as clickable cards in a responsive grid. Each card shows the hero image, title, and description.
Plain links — pages without an image field appear below as a single-column list of title + description links.

When both zones are present, a horizontal rule separates them. This design mirrors the pattern used by the pointblank demos page, where featured items with screenshots sit above a simpler list of additional entries.

Controlling Columns

By default, image cards use a 2-column responsive grid. Set index_columns: 1 for a single-column layout (useful for wide screenshots or fewer items):

great-docs.yml

sections:
  - title: Gallery
    dir: gallery
    index: true
    index_columns: 1

Mixed layouts

You can combine both approaches in the same site: a 2-column demos section with featured screenshots alongside a 1-column gallery with full-width images, plus plain text links for supplementary pages that don’t need a visual.

Example: Featured Demos with Plain Links

Given this directory:

demos/
├── 01-starter.qmd       ← Has image: "img/starter.png"
├── 02-advanced.qmd      ← Has image: "img/advanced.png"
├── 03-tips.qmd          ← No image
├── 04-faq.qmd           ← No image
└── img/
    ├── starter.png
    └── advanced.png

With this config:

great-docs.yml

sections:
  - title: Demos
    dir: demos
    index: true

The generated index page shows:

Two image cards side by side (Starter and Advanced) at the top
A horizontal rule
Two plain link entries (Tips and FAQ) in a single-column list below

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 as 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, and each subdirectory becomes a sidebar section with its own heading.

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

Numeric Prefix Stripping

Just like individual files, subdirectory names have numeric prefixes stripped automatically. This lets you control the sort order of sidebar sections while keeping clean display titles:

examples/
├── 01-getting-started/
│   ├── installation.qmd
│   └── first-steps.qmd
├── 02-results-and-reporting/
│   ├── basic-report.qmd
│   └── custom-output.qmd
└── 03-advanced-topics/
    └── custom-config.qmd

The sidebar displays these as “Getting Started”, “Results And Reporting”, and “Advanced Topics” (not “01 Getting Started”, etc.).

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

Custom sections let you go beyond the standard User Guide and API Reference to organize content in whatever way makes sense for your project. Whether it’s a tutorials section, a cookbook, or a gallery of examples, each section gets its own navbar link, sidebar navigation, and optional index page.

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