mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
ecf5e081b5
4628b9ec2 commands: Regen CLI doc 2525f2ed0 data: Regenerate docs helper 6f5a0eb19 Add Hugo 0.30 poster image 72c3fac9e Merge branch 'chroma-next2' into next 364973d3f Fix typo in syntax highlighting. ce10cc02e Update Chroma highlighting docs 9dcc4d4dd Update robots.md 1e64cb483 Rename title of cross references' page d6dfbbc51 Add warning about MMark and TOCs e8d259d32 Fix link to subsection in page 6adead19d Merge commit '040d8d2833c26c53cf9f0e035910821ed50e3863' 040d8d283 Squashed 'themes/gohugoioTheme/' changes from cdaa89c8..6b632895 bde95d890 Add Atlas starter kit fc40d078d Remove page arg from examples of relref shortcode c578620b5 Remove page arg from examples of ref shortcode ee81931a4 Remove delimiters in YAML and TOML config examples 62d7b269f Clarify that .Lastmod automatically uses .GitInfo.AuthorDate (#226) git-subtree-dir: docs git-subtree-split: 4628b9ec2c52df4de673a4d6b9621a65d8e8f5a4
95 lines
No EOL
4 KiB
Markdown
95 lines
No EOL
4 KiB
Markdown
---
|
|
title: Table of Contents
|
|
linktitle:
|
|
description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
|
|
date: 2017-02-01
|
|
publishdate: 2017-02-01
|
|
lastmod: 2017-02-01
|
|
categories: [content management]
|
|
keywords: [table of contents, toc]
|
|
menu:
|
|
docs:
|
|
parent: "content-management"
|
|
weight: 130
|
|
weight: 130 #rem
|
|
draft: false
|
|
aliases: [/extras/toc/,/content-management/toc/]
|
|
toc: true
|
|
---
|
|
|
|
{{% note "TOC Heading Levels are Fixed" %}}
|
|
Currently, the `{{.TableOfContents}}` [page variable](/variables/page/) does not allow you to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` is going to start at `<h1>` when pulling from `{{.Content}}`.
|
|
{{% /note %}}
|
|
|
|
## Usage
|
|
|
|
Create your markdown the way you normally would with the appropriate headings. Here is some example content:
|
|
|
|
```
|
|
<!-- Your front matter up here -->
|
|
|
|
## Introduction
|
|
|
|
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
|
|
|
|
## My Heading
|
|
|
|
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
|
|
|
|
### My Subheading
|
|
|
|
A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
|
|
```
|
|
|
|
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
|
|
|
|
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with any `<h1>`'s (i.e., `#` in markdown) inside your content.'
|
|
|
|
{{% note "Table of contents not available for MMark" %}}
|
|
Hugo documents created in the [MMark](/content-management/formats/#mmark) Markdown dialect do not currently display TOCs. TOCs are, however, compatible with all other supported Markdown formats.
|
|
{{% /note %}}
|
|
|
|
## Template Example: Basic TOC
|
|
|
|
The following is an example of a very basic [single page template][]:
|
|
|
|
{{< code file="layout/_default/single.html" download="single.html" >}}
|
|
{{ define "main" }}
|
|
<main>
|
|
<article>
|
|
<header>
|
|
<h1>{{ .Title }}</h1>
|
|
</header>
|
|
{{ .Content }}
|
|
</article>
|
|
<aside>
|
|
{{ .TableOfContents }}
|
|
</aside>
|
|
</main>
|
|
{{ end }}
|
|
{{< /code >}}
|
|
|
|
## Template Example: TOC Partial
|
|
|
|
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
|
|
|
|
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
|
|
{{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }}
|
|
<aside>
|
|
<header>
|
|
<h2>{{.Title}}</h2>
|
|
</header>
|
|
{{.TableOfContents}}
|
|
</aside>
|
|
{{ end }}
|
|
{{< /code >}}
|
|
|
|
{{% note %}}
|
|
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
|
|
{{% /note %}}
|
|
|
|
[conditionals]: /templates/introduction/#conditionals
|
|
[front matter]: /content-management/table-of-contents/
|
|
[pagevars]: /variables/page/
|
|
[partials]: /templates/partials/
|
|
[single page template]: /templates/single-page-templates/ |