mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-31 22:41:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/content/en/methods/page/Fragments.md
View File

@@ -3,12 +3,10 @@ title: Fragments
description: Returns a data structure of the fragments in the given page.
categories: []
keywords: []
action:
related:
- methods/page/TableOfContents
returnType: tableofcontents.Fragments
signatures: [PAGE.Fragments]
toc: true
params:
functions_and_methods:
returnType: tableofcontents.Fragments
signatures: [PAGE.Fragments]
---
In a URL, whether absolute or relative, the [fragment](g) links to an `id` attribute of an HTML element on the page.
@@ -25,43 +23,53 @@ Use the `Fragments` method on a `Page` object to create a table of contents with
## Methods
Headings
: (`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:
### Headings
(`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:
```go-html-template
<pre>{{ debug.Dump .Fragments.Headings }}</pre>
```
HeadingsMap
: (`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:
### HeadingsMap
(`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:
```go-html-template
<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre>
```
Identifiers
: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure:
### Identifiers
(`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page.
See [configure Markup](/configuration/markup/#parserautodefinitiontermid).
To inspect the data structure:
```go-html-template
<pre>{{ debug.Dump .Fragments.Identifiers }}</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](g).
### 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](g).
```go-html-template
{{ .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.
### Identifiers.Count ID
(`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
```go-html-template
{{ .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&nbsp;(`int`), the end level&nbsp;(`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
### 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&nbsp;(`int`), the end level&nbsp;(`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.
@@ -88,13 +96,14 @@ Hugo renders this to:
</nav>
```
{{% note %}}
It is safe to use the `Fragments` methods within a render hook, even for the current page.
> [!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 [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
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 %}}
[atx]: https://spec.commonmark.org/0.30/#atx-headings
[`TableOfContents`]: /methods/page/tableofcontents/
[ATX]: https://spec.commonmark.org/0.30/#atx-headings
[Markdown notation]: /content-management/shortcodes/#notation
[setext]: https://spec.commonmark.org/0.30/#setext-headings
[standard notation]: /content-management/shortcodes/#notation
[table of contents]: /methods/page/tableofcontents/
[`tableofcontents`]: /methods/page/tableofcontents/