---
title: "Custom Sections"
guide-section: "Site Content"
bread-crumbs: false
tags: [Content, Customization]
---

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

::: {.version-only versions=">=0.6"}
If you need a single hand-written HTML page rather than a section of `.qmd` files, see [Custom Static Pages](custom-pages.qmd). 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
└── ...
```

2. Add the section to `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Examples
    dir: examples
```

3. 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:

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

::: {.version-only versions=">=0.7"}
| `index_columns`  | `2`                | Number of columns for image cards on the index page (1 or 2). Only applies when `index: true` [version-badge new 0.7] |
:::

::: {.version-only versions="dev"}
| `dir_titles`     | `{}`               | Mapping of subdirectory names to custom sidebar section titles (see [Subdirectories](#subdirectories)) [version-badge new dev] |
:::

## Multiple Sections

Add as many sections as you need:

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

::: {.callout-tip}
## Blog sections
The `type: blog` option uses Quarto's native listing directive for date-sorted, searchable blog posts. See [Blog](blog.qmd) 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:

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

```{.yaml filename="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](https://posit-dev.github.io/pointblank/demos/), where featured items with screenshots sit above a simpler list of additional entries.

::: {.version-only versions=">=0.7"}

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

```{.yaml filename="great-docs.yml"}
sections:
  - title: Gallery
    dir: gallery
    index: true
    index_columns: 1
```

::: {.callout-tip}
## 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:

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

::: {.version-only versions="dev"}

### Custom Subdirectory Titles {#custom-subdirectory-titles}

The auto-generated title converts hyphens and underscores to spaces and applies title case. If you need different capitalization or phrasing, use `dir_titles` to override specific subdirectory headings:

```{.yaml filename="great-docs.yml"}
sections:
  - title: Demos
    dir: examples
    index: true
    dir_titles:
      getting-started: "Getting Started"
      results-and-reporting: "Results/Reporting"
      advanced-topics: "Advanced Topics"
```

The keys in `dir_titles` are the subdirectory names **after** numeric prefix stripping (e.g., use `getting-started`, not `01-getting-started`). Any subdirectory not listed in the mapping falls back to the auto-generated title.

::: {.callout-tip}
## When to use `dir_titles`
This is useful when the auto-generated title doesn't match your preferred style — for example, turning "Results And Reporting" into "Results/Reporting", or "Actions And Thresholds" into "Actions & Thresholds".
:::

:::

## Example: Visual Gallery

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

1. Create the directory structure:

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

2. Write your custom `index.qmd` with a visual grid:

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

:::::
::::::
```

3. Add to config:

```{.yaml filename="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](blog.qmd) covers setting up a blog with Quarto's listing directive
- [Configuration](configuration.qmd) covers all available `great-docs.yml` options
- [User Guides](user-guides.qmd) covers the User Guide section setup
