diff options
Diffstat (limited to 'docs/content/en/methods/page/Fragments.md')
-rw-r--r-- | docs/content/en/methods/page/Fragments.md | 106 |
1 files changed, 0 insertions, 106 deletions
diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md deleted file mode 100644 index 89f82d2ce..000000000 --- a/docs/content/en/methods/page/Fragments.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -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 ---- - -{{< 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. - -```text -/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: - -```go-html-template -<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: - -```go-html-template -<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: - -```go-html-template -<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]. - -```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. - -```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 (`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. - -```go-html-template -{{ $startLevel := 2 }} -{{ $endLevel := 3 }} -{{ $ordered := true }} -{{ .Fragments.ToHTML $startLevel $endLevel $ordered }} -``` - -Hugo renders this to: - -```html -<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 %}} - -[atx]: https://spec.commonmark.org/0.30/#atx-headings -[fragment]: /getting-started/glossary/#fragment -[markdown attribute]: /getting-started/glossary/#markdown-attribute -[setext]: https://spec.commonmark.org/0.30/#setext-headings -[table of contents]: /methods/page/tableofcontents -[walking]: /getting-started/glossary/#walk -[`tableofcontents`]: /methods/page/tableofcontents -[render hook]: /getting-started/glossary/#render-hook |