diff --git a/content/en/variables/page.md b/content/en/variables/page.md index 2de54ff8b..f21c74b60 100644 --- a/content/en/variables/page.md +++ b/content/en/variables/page.md @@ -59,6 +59,9 @@ See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. .File : filesystem-related data for this content file. See also [File Variables]. +.Fragments +: Fragments returns the fragments for this page. See [Page Fragments](#page-fragments). + .FuzzyWordCount : the approximate number of words in the content. @@ -199,6 +202,42 @@ aliased form `.Pages`. {{< getcontent path="readfiles/pages-vs-site-pages.md" >}} +## Page Fragments + +{{< new-in "0.111.0" >}} + +The `.Fragments` method returns a list of fragments for the current page. + +.Headings +: A recursive list of headings for the current page. Can be used to generate a table of contents. + +{{< todo >}}add .Headings toc example{{< /todo >}} + +.Identifiers +: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers: + +```go-html-template +{{ if .Fragments.Identifiers.Contains "my-identifier" }} +
Page contains identifier "my-identifier"
+{{ end }} + +{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} +Page contains duplicate "my-idenfifier" fragments
+{{ end }} +``` + +.HeadingsMap +: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading. + +Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type. + +### Fragments in hooks and shortcodes + +`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{**/>}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail). + + + + ## Page-level Params Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. @@ -299,3 +338,4 @@ The top-level key will be preferred. Therefore, the following method, when appli [gitinfo]: /variables/git/ [File Variables]: /variables/files/ [bundle]: {{< relref "content-management/page-bundles" >}} +