gohugoio-hugo/docs/content/en/methods/page/Fragments.md

title, description, categories, keywords, action, toc

title	description	categories	keywords	action	toc
Fragments	Returns a data structure of the fragments in the given page.			related returnType signatures methods/page/TableOfContents tableofcontents.Fragments PAGE.Fragments	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 and Headings. 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 and Headings. To inspect the data structure:

<pre>{{ .Fragments.HeadingsMap | jsonify (dict "indent" "  ") }}</pre>

Identifiers

(slice) A slice containing the id 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 given id 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 given id 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 the TableOfContents 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 %}}