Structure

What the Navigation Bar Does

The navigation bar is the dark navy bar that runs across the top of every page on your report. It helps readers navigate between sections without getting lost — think of it as the table of contents for your entire website. Every page on your Quarto report shares the same navigation bar. This means readers can jump between pages at any time. It also gives your report a polished, professional feel — like a real website rather than a static document.

What You Can Customize

Page Links

Add or remove pages from the navbar by editing the _quarto.yml file. Each page you want to appear in the navbar needs a href (the file name) and text (what the reader sees).

Colors

The navbar background and text colors are set in _quarto.yml. The default is Omni navy (#081C39) with white text. These should not be changed without consulting the branding guidelines.

Order of Pages

The order pages appear in the navbar matches the order they are listed in _quarto.yml. Simply move items up or down in the file to reorder them.

New to Qmd.files?

Think of _quarto.yml as the settings file for your entire website. It controls the navbar, footer, and overall site structure. You only need to edit it when adding new pages or changing the site layout — not for everyday content updates.

Note that YAML files are sensitive to spacing and indentation. If something looks off after editing, check that your indentation uses spaces (not tabs) and that all items are aligned correctly.

Subtabs in Navbar

Subtabs are dropdown menus that appear in the navbar when you hover over a top-level item. They are useful when you have multiple related pages that belong under one category — rather than cluttering the navbar with too many links, you can group them neatly under a single label.

On this site, Static Components and Interactive Components are examples of navbar items with subtabs.

When Should You Use Subtabs?

Use subtabs when you have 3 or more related pages that belong together. For example, if your report has separate pages for each program area, you could group them under a single “Programs” dropdown rather than listing each one separately in the navbar.

How to Add Subtabs in _quarto.yml

To create a dropdown menu in your navbar, use the menu key under a navbar item. Here is an example:

website:
  navbar:
    left:
      - text: Static Components
        menu:
          - href: components.qmd
            text: Overview
          - href: components_metrics.qmd
            text: Metrics
          - href: components_text.qmd
            text: Text/Narrative

The top-level item (e.g. “Static Components”) does not need its own page — it just acts as a label for the dropdown. If you want it to link somewhere, add a href to it as well.

Each item under menu must be indented consistently. If your dropdown is not appearing, double check that all href and text lines under menu are aligned with two spaces.

Table of Contents On Each Page

Every page on your report automatically includes a table of contents (TOC) on the right-hand side. This TOC is generated from the headers on the page — any section marked with ## will appear as a clickable link, making it easy for readers to jump to the content they need.

Automatic Generation

You don’t need to build the TOC yourself. It updates automatically whenever you add, remove, or rename a ## header on the page.

What Shows Up

By default, only first-level headers (##) appear in the TOC. Subheaders (###, ####) and section labels do not appear, keeping the TOC clean and scannable for readers.

Because the TOC pulls directly from your headers, clear and descriptive header names make a big difference. Aim for short, meaningful labels — for example, “Youth Outcomes” is more useful than “Section 3.” Readers will see these names in the TOC before they scroll to the content.

Columns and Grids

Columns and grids let you place content side by side rather than stacking everything vertically. This is useful for comparing metrics, pairing a chart with a summary, or making dashboards feel more polished.

The template includes several built-in layout options. The examples below show what each looks like and when to use it.

Two Columns

Use a two-column layout when you want to place two pieces of content side by side — such as a pair of stat cards, a chart next to a summary, or two related text blocks.

Wrap your content in a :::: {.two-column-grid} container, with each item inside its own ::: {} block.

Column A

This is the left column. It takes up equal space alongside Column B.

Column B

This is the right column. Both columns resize together on smaller screens and stack vertically on mobile.

Three or More Columns

Use a multi-column layout when you need to display three or more items in a row — such as a set of feature cards or key metrics. The .multi-column-section class creates an evenly spaced grid that wraps items as needed.

Metric A

First item in the grid.

Metric B

Second item in the grid.

Metric C

Third item in the grid.

Stat Card Grids

For displaying a row of key numbers or metrics, use :::: {.stat-cards-grid}. This layout automatically fits as many cards per row as space allows and adjusts on smaller screens.

Participants
1,245

Total number of program participants.

Completion Rate
87%

Percentage who completed the program.

Satisfaction
4.6/5

Average participant satisfaction score.

  • Two-column grid — best for pairing two related items side by side (e.g., a chart + summary).
  • Multi-column section — best for three or more feature cards or content blocks.
  • Stat card grid — best for a row of key metrics or numbers that should be scannable at a glance.

All layouts are responsive and will stack vertically on mobile devices.

Spacing

Consistent spacing keeps your report feeling organized and easy to read. The template handles most spacing automatically — headers, cards, and grids all come with built-in margins. However, there are times when you may want to fine-tune the space between elements manually.

Built-In Spacing

Most components in this template — stat cards, feature cards, callouts, and grids — already include appropriate spacing above and below them. In general, you should not need to add extra spacing between these elements. If something looks too cramped or too spread out, it is usually a sign that a header level or container class needs adjusting rather than adding manual space.

General Tips

  • Don’t use empty lines or <br> tags to create space. These are fragile and render inconsistently. Use the margin utility classes instead.
  • Headers create natural separation. A well-placed ## or ### often provides all the spacing you need without any extra classes.
  • When in doubt, less is more. A clean report with consistent, moderate spacing feels more professional than one with large gaps between sections.