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-depthsets the deepest heading level included (default: 3).toc-titlesets 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 asQuartoTocPropsin the@quarto/componentspackage:title,entries(each withid,title,level,numberandchildren),expanded(thetoc-expandvalue as a number, ornull) andlocation;children: the default markup (the title, the list, and any repository action links), which a component can render as-is or replace;host: thenavelement.
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.
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.
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.