Skip to main content

Navigation

Overview

HTML pages rendered with Quarto can include a table of contents that tracks the section structure of the document and lets readers jump to any section. This page covers the table of contents options; for site-level navigation (navbars, sidebars, breadcrumbs), see the websites guides.

Table of Contents

Enable the table of contents with the toc option:

---
title: My Document
toc: true
---

By default the table of contents shows headings up to level 3 and renders in the right margin of the page. You can control both:

---
title: My Document
toc: true
toc-depth: 4
toc-title: Contents
---
  • toc-depth sets the deepest heading level included (default: 3).
  • toc-title sets the heading shown above the table of contents (default: “Table of contents”, localized to the document language).

Following the reader

As the page scrolls, the entry for the current section is highlighted, and nested entries open around it: by default only the top level is shown, plus the branch that holds the current section. Use toc-expand to show more (or less) of the tree from the start:

---
title: My Document
toc: true
toc-expand: 2
---
Value Behavior
1 The default: top-level entries, plus the current branch
N Entries down to level N stay open; deeper ones follow the reader
true Every entry is always open
false Nested entries are shown only while their section is current

0 behaves like false, and a number with a fractional part is rounded down (2.5 behaves like 2). Any other value, such as a word or a negative depth, produces a warning (Q-13-19) and the default depth is used.

The tracking is a small script shipped with the page (quarto-toc.js). Without JavaScript the table of contents is a plain list with its first entry marked as current. On a page too short to scroll, the last entry is current, as in Quarto 1. A page script can listen for the quarto-sectionChanged event on window, which fires whenever the current section changes.

Replacing the table of contents with a component

To render the table of contents yourself, point toc-component at a React component, written the same way as any component:

---
title: My Document
toc: true
toc-component: my-toc.tsx
---

The component is mounted over the nav#TOC element in place of the default script, and receives:

  • props: the table of contents as data, typed as QuartoTocProps in the @quarto/components package: title, entries (each with id, title, level, number and children), expanded (the toc-expand value as a number, or null) and location;
  • children: the default markup (the title, the list, and any repository action links), which a component can render as-is or replace;
  • host: the nav element.
import type { QuartoComponentProps, QuartoTocProps } from "@quarto/components";

export default function Toc({ props }: QuartoComponentProps<QuartoTocProps>) {
  return (
    <ol>
      {props.entries.map((e) => (
        <li key={e.id}><a href={`#${e.id}`}>{e.title}</a></li>
      ))}
    </ol>
  );
}

Without JavaScript the page shows the default list. The option is inert on pages that render no table of contents, like toc-location.

Note

The q2 preview shows the default table of contents for a page that sets toc-component; mounting the component in the preview is planned.

Location

Use toc-location to choose where the table of contents appears:

---
title: My Document
toc: true
toc-location: left
---

The available locations:

Value Placement
right In the right margin (the default)
left In a sidebar to the left of the document body
body In the document body, above the content

On pages of a website project, toc-location: left places the table of contents inside the site’s navigation sidebar — after the navigation entries when the page has a sidebar, or on its own when it does not.

On narrow screens the left and right table-of-contents sidebars are hidden; use toc-location: body if the table of contents should remain visible at every screen size.

Note

The left-body and right-body values (which show the table of contents both in a sidebar and in the body) are not supported yet; they currently fall back to left and right respectively, with a warning.