ReferenceBuilt-in steps
headings
Gives every heading of an HTML page an id and sets headings, toc and page.heading.
uses: headings works on the HTML of a page, whatever produced its headings (Markdown, a template, a shortcode, an
include). It gives every heading an id, optionally adds anchor links, and sets headings, toc and page.heading for
the layout. It runs after markdown and before layout, and is not in the default workflow.
| Shape | map |
Default match |
**/*.html |
| Default workflow | no |
What it doesLink to this heading
Scans the
h1toh6elements of the page in one pass, so the headings of the page, its shortcodes and includes share one set of ids. Headings insidepre,code,script,style,templateand comments are ignored, and so are those inside an element with one of theskip-classes.Keeps the ids headings already have (
## Title {#custom}with theattributesextension), and reserves them first. Other headings get a GitHub style id: lowercase, characters other than letters, marks, digits, spaces, hyphens and underscores removed, spaces replaced by hyphens (What's new?iswhats-new). A duplicate gets-1,-2... (a secondSetupissetup-1).With
anchors: true, appends an anchor to each heading:<h2 id="setup">Setup<a class="heading-anchor" href="#setup"><span aria-hidden="true">#</span><span class="sr-only">Link to this heading</span></a></h2>With
wrapper-class, wraps each heading in<div class="<wrapper-class> level-hN">, and puts the anchor (whenanchorsis true) after the heading inside that element instead of inside the heading.Sets on the file:
| Key | Value |
|---|---|
headings |
Every heading, in order: depth (1 to 6), text (its text without tags) and id |
toc |
The headings of levels as a tree: each entry has depth, text, id and children, a heading being a child of the closest previous heading of a lower depth |
page.heading |
The text of the first h1, when the page has one |
A page without headings passes through unchanged. A layout renders toc with the toc filter.
OptionsLink to this heading
| Option | Type | Default | Meaning |
|---|---|---|---|
anchors |
boolean | false |
Appends an anchor link to each heading |
anchor-class |
string | heading-anchor |
The class of the anchor |
anchor-label |
string | Link to this heading |
The screen reader text of the anchor, in a sr-only span; {text} is replaced by the heading's text |
anchor-html |
string | # |
The visible content of the anchor, in an aria-hidden span (raw HTML, such as an SVG) |
wrapper-class |
string | none | Wraps each heading and its anchor in <div class="<wrapper-class> level-hN"> |
levels |
integer or list of integers | [2, 3] |
The heading levels of toc, from 1 to 6 |
skip-classes |
string or list of strings | none | Headings inside an element with one of these classes (a component) are left alone |
ErrorsLink to this heading
option 'levels' of step 'headings' must be a list of heading levels from 1 to 6
ExampleLink to this heading
steps:
pages:
inputs: "**/*.md"
uses: frontmatter
markdown:
needs: pages
uses: markdown
headings:
needs: markdown
uses: headings
with:
anchors: true
levels: [2, 3]
anchor-label: "Link to {text}"
layout:
needs: headings
uses: layout
write:
needs: layout
uses: write
<h1>{{ page.heading | default: title }}</h1>
{{ toc | toc: class: "toc", max-depth: 3 }}
{{ content }}