toc.md (5793B)
1 ---
2 title: Table of Contents
3 linktitle:
4 description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [content management]
9 keywords: [table of contents, toc]
10 menu:
11 docs:
12 parent: "content-management"
13 weight: 130
14 weight: 130 #rem
15 draft: false
16 aliases: [/extras/toc/]
17 toc: true
18 ---
19
20 {{% note "TOC Heading Levels are Fixed" %}}
21
22 Previously, there was no out-of-the-box way 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>` was going to start at `<h1>` when pulling from `{{.Content}}`.
23
24 Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
25
26 {{% /note %}}
27
28 ## Usage
29
30 Create your markdown the way you normally would with the appropriate headings. Here is some example content:
31
32 ```
33 <!-- Your front matter up here -->
34
35 ## Introduction
36
37 One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
38
39 ## My Heading
40
41 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.
42
43 ### My Subheading
44
45 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
46 ```
47
48 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`.
49
50 The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
51
52 ## Template Example: Basic TOC
53
54 The following is an example of a very basic [single page template][]:
55
56 {{< code file="layout/_default/single.html" download="single.html" >}}
57 {{ define "main" }}
58 <main>
59 <article>
60 <header>
61 <h1>{{ .Title }}</h1>
62 </header>
63 {{ .Content }}
64 </article>
65 <aside>
66 {{ .TableOfContents }}
67 </aside>
68 </main>
69 {{ end }}
70 {{< /code >}}
71
72 ## Template Example: TOC Partial
73
74 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:
75
76 {{< code file="layouts/partials/toc.html" download="toc.html" >}}
77 {{ if and (gt .WordCount 400 ) (.Params.toc) }}
78 <aside>
79 <header>
80 <h2>{{.Title}}</h2>
81 </header>
82 {{.TableOfContents}}
83 </aside>
84 {{ end }}
85 {{< /code >}}
86
87 {{% note %}}
88 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.
89 {{% /note %}}
90
91 ## Usage with AsciiDoc
92
93 Hugo supports table of contents with AsciiDoc content format.
94
95 In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
96
97 ```asciidoc
98 // <!-- Your front matter up here -->
99 :toc:
100 // Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
101 :toclevels: 4
102
103 == Introduction
104
105 One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
106
107 == My Heading
108
109 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.
110
111 === My Subheading
112
113 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
114 ```
115 Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
116
117 [conditionals]: /templates/introduction/#conditionals
118 [front matter]: /content-management/front-matter/
119 [pagevars]: /variables/page/
120 [partials]: /templates/partials/
121 [single page template]: /templates/single-page-templates/