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

  1. 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
└── ...
  1. Add the section to great-docs.yml:
great-docs.yml
sections:
  - title: Examples
    dir: examples
  1. 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
TipBlog sections

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

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:

  1. 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.
  2. 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
TipMixed 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.

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.).

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