# 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-pages.md). 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`:


    great-docs.yml


``` yaml
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:


    great-docs.yml


``` yaml
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


``` yaml
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

> **Tip: Blog sections**
>
> The `type: blog` option uses Quarto's native listing directive for date-sorted, searchable blog posts. See [Blog](blog.md) 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


``` yaml
---
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


``` yaml
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.


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


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


> **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:


    great-docs.yml


``` yaml
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:

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:


    demos/index.qmd


``` markdown
---
title: "Examples"
toc: false
---

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

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

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

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


3.  Add to config:


    great-docs.yml


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