``` git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash ``` Closes #11925
3.9 KiB
title | description | categories | keywords | action | toc | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Fragments | Returns a data structure of the fragments in the given page. |
|
true |
{{< new-in 0.111.0 >}}
In a URL, whether absolute or relative, the fragment links to an id
attribute of an HTML element on the page.
/articles/article-1#section-2
------------------- ---------
path fragment
Hugo assigns an id
attribute to each markdown ATX and setext heading within the page content. You can override the id
with a markdown attribute as needed. This creates the relationship between an entry in the table of contents (TOC) and a heading on the page.
Use the Fragments
method on a Page
object to create a table of contents with the Fragments.ToHTML
method, or by walking the Fragments.Map
data structure.
Methods
- Headings
- (
map
) A nested map of all headings on the page. Each map contains the following keys:ID
,Level
,Title
andHeadings
. To inspect the data structure:
<pre>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre>
- HeadingsMap
- (
slice
) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys:ID
,Level
,Title
andHeadings
. To inspect the data structure:
<pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre>
- Identifiers
- (
slice
) A slice containing theid
of each heading on the page. To inspect the data structure:
<pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre>
- Identifiers.Contains ID
- (
bool
) Reports whether one or more headings on the page has the givenid
attribute, useful for validating fragments within a link render hook.
{{ .Fragments.Identifiers.Contains "section-2" }} → true
- Identifiers.Count ID
- (
int
) The number of headings on a page with the givenid
attribute, useful for detecting duplicates.
{{ .Fragments.Identifiers.Count "section-2" }} → 1
- ToHTML
- (
template.HTML
) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by theTableOfContents
method. This method take three arguments: the start level (int
), the end level (int
), and a boolean (true
to return an ordered list,false
to return an unordered list).
Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration.
{{ $startLevel := 2 }}
{{ $endLevel := 3 }}
{{ $ordered := true }}
{{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
Hugo renders this to:
<nav id="TableOfContents">
<ol>
<li><a href="#section-1">Section 1</a>
<ol>
<li><a href="#section-11">Section 1.1</a></li>
<li><a href="#section-12">Section 1.2</a></li>
</ol>
</li>
<li><a href="#section-2">Section 2</a></li>
</ol>
</nav>
{{% note %}}
It is safe to use the Fragments
methods within a render hook, even for the current page.
When using the Fragments
methods within a shortcode, call the shortcode using the {{</* */>}}
notation. If you use the {{%/* */%}}
notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
{{% /note %}}