diff options
Diffstat (limited to 'docs/content/en/variables')
| -rw-r--r-- | docs/content/en/variables/_common/_index.md | 13 | ||||
| -rw-r--r-- | docs/content/en/variables/_common/consistent-terminology.md | 20 | ||||
| -rw-r--r-- | docs/content/en/variables/_index.md | 16 | ||||
| -rw-r--r-- | docs/content/en/variables/file.md | 18 | ||||
| -rw-r--r-- | docs/content/en/variables/files.md | 102 | ||||
| -rw-r--r-- | docs/content/en/variables/git.md | 69 | ||||
| -rw-r--r-- | docs/content/en/variables/menu-entry.md | 16 | ||||
| -rw-r--r-- | docs/content/en/variables/menus.md | 92 | ||||
| -rw-r--r-- | docs/content/en/variables/page.md | 356 | ||||
| -rw-r--r-- | docs/content/en/variables/pages.md | 40 | ||||
| -rw-r--r-- | docs/content/en/variables/shortcode.md | 16 | ||||
| -rw-r--r-- | docs/content/en/variables/shortcodes.md | 45 | ||||
| -rw-r--r-- | docs/content/en/variables/site.md | 115 | ||||
| -rw-r--r-- | docs/content/en/variables/sitemap.md | 24 | ||||
| -rw-r--r-- | docs/content/en/variables/taxonomy.md | 139 |
15 files changed, 198 insertions, 883 deletions
diff --git a/docs/content/en/variables/_common/_index.md b/docs/content/en/variables/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/docs/content/en/variables/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + +<!-- +Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. + +Include the rendered content using the "include" shortcode. +--> diff --git a/docs/content/en/variables/_common/consistent-terminology.md b/docs/content/en/variables/_common/consistent-terminology.md new file mode 100644 index 000000000..8774c817b --- /dev/null +++ b/docs/content/en/variables/_common/consistent-terminology.md @@ -0,0 +1,20 @@ +--- +# Do not remove front matter. +--- + +{{% note %}} +We are making an effort to unify our [terminology], and to use these terms consistently throughout the documentation. + +Historically, we have inconsistently referred to the items on this page as [functions], [parameters], [variables], or [methods]. They are not functions, parameters, or variables; they are methods. + +This page will remain in place as readers become familiar with the unified terminology. See the [methods section] for a list of methods by [object], or the [methods quick reference guide]. + +[functions]: /getting-started/glossary/#function +[methods quick reference guide]: /quick-reference/methods +[methods section]: /methods +[methods]: /getting-started/glossary/#method +[object]: /getting-started/glossary/#object +[parameters]: /getting-started/glossary/#parameter +[terminology]: /getting-started/glossary/ +[variables]: /getting-started/glossary/#variable +{{% /note %}} diff --git a/docs/content/en/variables/_index.md b/docs/content/en/variables/_index.md index c1f80a62c..d8dbf9d67 100644 --- a/docs/content/en/variables/_index.md +++ b/docs/content/en/variables/_index.md @@ -1,18 +1,16 @@ --- -title: Variables and parameters +title: Variables linkTitle: Overview -description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. -categories: [variables and parameters] -keywords: [variables,params,values,globals] +description: Use these variables in your templates. +categories: [] +keywords: [] menu: docs: identifier: variables-overview parent: variables - weight: 1 -weight: 1 + weight: 10 +weight: 10 aliases: [/templates/variables/] --- -Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. - -[Go templates]: /templates/introduction/ +{{% include "variables/_common/consistent-terminology.md" %}} diff --git a/docs/content/en/variables/file.md b/docs/content/en/variables/file.md new file mode 100644 index 000000000..248d84991 --- /dev/null +++ b/docs/content/en/variables/file.md @@ -0,0 +1,18 @@ +--- +title: File variables +description: Retrieve file information about any page that is backed by a file. +categories: [variables] +keywords: [] +menu: + docs: + parent: variables + weight: 20 +weight: 20 +aliases: [/variables/file-variables/,/variables/files/] +--- + +{{% include "variables/_common/consistent-terminology.md" %}} + +To retrieve file information about any page that is backed by a file, see the documentation for the [`File`] method on a `Page` object. + +[`File`]: /methods/page/file diff --git a/docs/content/en/variables/files.md b/docs/content/en/variables/files.md deleted file mode 100644 index fa2a63a9c..000000000 --- a/docs/content/en/variables/files.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: File variables -description: "Use File variables to access file-related values for each page that is backed by a file." -categories: [variables and parameters] -keywords: [files] -menu: - docs: - parent: variables - weight: 40 -toc: true -weight: 40 -aliases: [/variables/file-variables/] ---- -## Variables - -{{% note %}} -The path separators (slash or backslash) in `.File.Path`, `.File.Dir`, and `.File.Filename` depend on the operating system. -{{% /note %}} - -.File.Path -: (`string`) The file path, relative to the `content` directory. - -.File.Dir -: (`string`) The file path, excluding the file name, relative to the `content` directory. - -.File.LogicalName -: (`string`) The file name. - -.File.BaseFileName -: (`string`) The file name, excluding the extension. - -.File.TranslationBaseName -: (`string`) The file name, excluding the extension and language identifier. - -.File.Ext -: (`string`) The file extension. - -.File.Lang -: (`string`) The language associated with the given file. - - -.File.ContentBaseName -: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `.TranslationBaseName`. - -.File.Filename -: (`string`) The absolute file path. - -.File.UniqueID -: (`string`) The MD5 hash of `.File.Path`. - -## Examples - -```text -content/ -├── news/ -│ ├── b/ -│ │ ├── index.de.md <-- leaf bundle -│ │ └── index.en.md <-- leaf bundle -│ ├── a.de.md <-- regular content -│ ├── a.en.md <-- regular content -│ ├── _index.de.md <-- branch bundle -│ └── _index.en.md <-- branch bundle -├── _index.de.md -└── _index.en.md -``` - -With the content structure above, the `.File` objects for the English pages contain the following properties: - - |regular content|leaf bundle|branch bundle -:--|:--|:--|:-- -Path|news/a.en.md|news/b/index.en.md|news/_index.en.md -Dir|news/|news/b/|news/ -LogicalName|a.en.md|index.en.md|_index.en.md -BaseFileName|a.en|index.en|_index.en -TranslationBaseName|a|index|_index -Ext|md|md|md -Lang|en|en|en -ContentBaseName|a|b|news -Filename|/home/user/...|/home/user/...|/home/user/... -UniqueID|15be14b...|186868f...|7d9159d... - -## Defensive coding - -Some of the pages on a site may not be backed by a file. For example: - -- Top level section pages -- Taxonomy pages -- Term pages - -Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example: - -```text -WARN .File.ContentBaseName on zero object. Wrap it in if or with... -``` - -To code defensively: - -```go-html-template -{{ with .File }} - {{ .ContentBaseName }} -{{ end }} -``` diff --git a/docs/content/en/variables/git.md b/docs/content/en/variables/git.md index 8928ca6f0..3dc473265 100644 --- a/docs/content/en/variables/git.md +++ b/docs/content/en/variables/git.md @@ -1,71 +1,18 @@ --- title: Git variables -linkTitle: Git variables -description: Get the last Git revision information for every content file. -categories: [variables and parameters] -keywords: [git] +description: Retrieve Git information related to the last commit of any page. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 70 -weight: 70 + weight: 30 +weight: 30 aliases: [/extras/gitinfo/] --- -{{% note %}} -Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history. -{{% /note %}} +{{% include "variables/_common/consistent-terminology.md" %}} -## `.GitInfo` prerequisites +To retrieve Git information related to the last commit of any page, see the documentation for the [`GitInfo`] method on a `Page` object. -1. The Hugo site must be in a Git-enabled directory. -2. The Git executable must be installed and in your system `PATH`. -3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration]. - -## The `.GitInfo` object - -The `GitInfo` object contains the following fields: - -.AbbreviatedHash -: the abbreviated commit hash (e.g., `866cbcc`) - -.AuthorName -: the author's name, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) - -.AuthorEmail -: the author's email address, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap) - -.AuthorDate -: the author date - -.Hash -: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`) - -.Subject -: commit message subject (e.g., `tpl: Add custom index function`) - -## `.Lastmod` - -If the `.GitInfo` feature is enabled, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. This behavior can be changed by adding your own [front matter configuration for dates](/getting-started/configuration/#configure-front-matter). - -[configuration]: /getting-started/configuration/ - -## Hosting considerations - -On the site host, your repository must be "deep-cloned," so the returned `.GitInfo` data will be accurate. Otherwise, your site may display only data from your latest commit. Where it's not possible to configure a host's cloning depth, you must handle this through CI/CD (*e.g.*, a GitHub Action or GitLab CI/CD). See the following table: - -| Hosting service | Clone depth | Configurable? | -| :-------------- | :---------- | :-----------: | -| Cloudflare Pages | Shallow | ✔️ [^CFP] | -| DigitalOcean App Platform | Deep | ❌ | -| GitHub Pages | Shallow | ✔️ [^GHP] | -| GitLab Pages | Shallow | ✔️ [^GLP] | -| Netlify | Deep | ❌ | -| Render | Shallow | ❌ | -| Vercel | Shallow | ❌ | - -[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`). - -[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure). - -[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](https://gohugo.io/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd). +[`GitInfo`]: /methods/page/gitinfo diff --git a/docs/content/en/variables/menu-entry.md b/docs/content/en/variables/menu-entry.md new file mode 100644 index 000000000..5b90dab6f --- /dev/null +++ b/docs/content/en/variables/menu-entry.md @@ -0,0 +1,16 @@ +--- +title: Menu entry variables +description: Use these methods in your menu templates. +categories: [variables] +keywords: [] +menu: + docs: + parent: variables + weight: 40 +weight: 40 +aliases: [/variables/menus/] +--- + +{{% include "variables/_common/consistent-terminology.md" %}} + +{{< list-pages-in-section path=/methods/menu-entry titlePrefix=. >}} diff --git a/docs/content/en/variables/menus.md b/docs/content/en/variables/menus.md deleted file mode 100644 index 0fe727cd8..000000000 --- a/docs/content/en/variables/menus.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Menu variables -description: Use these variables and methods in your menu templates. -categories: [variables and parameters] -keywords: [menus] -menu: - docs: - parent: variables - weight: 50 -weight: 50 -aliases: [/variables/menu/] ---- - -## Variables - -After [defining menu entries], access their properties in [menu templates] with these variables. - -.Children -: (`menu`) A collection of child menu entries, if any, under the current menu entry. - -.Identifier -: (`string`) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`. - -.KeyName -: (`string`) The `identifier` property of the menu entry, else the `name` property. - -.Menu -: (`string`) The identifier of the menu that contains the menu entry. - -.Name -: (`string`) The `name` property of the menu entry. - -- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. -- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. - -.Page -: (`page`) A reference to the page associated with the menu entry. - -<!-- This provides no value when rendering menu. Omitting to avoid confusion. -.PageRef -: (`string`) The `pageRef` property of the menu entry. ---> - -.Params -: (`map`) The `params` property of the menu entry. - -.Parent -: (`string`) The `parent` property of the menu entry. - -.Post -: (`template.HTML`) The `post` property of the menu entry. - -.Pre -: (`template.HTML`) The `pre` property of the menu entry. - -.Title -: (`string`) The `title` property of the menu entry. - -- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`. -- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`. - -.URL -: (`string`) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry. - -.Weight -: (`int`) The `weight` property of the menu entry. - -- If you define the menu entry [automatically], the page's `.Weight`. -- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`. - -## Methods - -.HasChildren -: (`bool`) Returns `true` if `.Children` is non-nil. - -.IsEqual -: (`bool`) Returns `true` if the compared menu entries represent the same menu entry. - -.IsSameResource -: (`bool`) Returns `true` if the compared menu entries point to the same resource. - -.Page.HasMenuCurrent -: (`bool`) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/). - -.Page.IsMenuCurrent -: (`bool`) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/). - -[automatically]: /content-management/menus/#define-automatically -[defining menu entries]: /content-management/menus/#overview -[in front matter]: /content-management/menus/#define-in-front-matter -[in site configuration]: /content-management/menus/#define-in-site-configuration -[menu templates]: /templates/menu-templates/ diff --git a/docs/content/en/variables/page.md b/docs/content/en/variables/page.md index 16e5f31ff..732cf5499 100644 --- a/docs/content/en/variables/page.md +++ b/docs/content/en/variables/page.md @@ -1,357 +1,63 @@ --- title: Page variables -description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. -categories: [variables and parameters] -keywords: [pages] +description: Use these methods with a Page object. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 20 -weight: 20 + weight: 50 +weight: 50 toc: true --- -The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. +{{% include "variables/_common/consistent-terminology.md" %}} -## Page variables +## All methods -.AlternativeOutputFormats -: Contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's `<head>`. (See [Output Formats](/templates/output-formats/).) +Use any of these methods in your templates. -.Aliases -: Aliases of this page +{{< list-pages-in-section path=/methods/page titlePrefix=. >}} -.Ancestors -: Ancestors of this page. +## Dates -.BundleType -: The [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle. +Use these methods to access content dates. -.Content -: The content itself, defined below the front matter. +{{< list-pages-in-section path=/methods/page filter=methods_page_dates filterType=include titlePrefix=. omitElementIDs=true >}} -.Data -: The data specific to this type of page. +## Multilingual -.Date -: The date associated with the page. By default, this is the front matter `date` value. See [configuring dates] for a description of fallback values and precedence. See also `.ExpiryDate`, `.Lastmod`, and `.PublishDate`. +Use these methods with your multilingual projects. -.Description -: The description for the page. +{{< list-pages-in-section path=/methods/page filter=methods_page_multilingual filterType=include titlePrefix=. omitElementIDs=true >}} -.Draft -: A boolean, `true` if the content is marked as a draft in the front matter. +## Navigation -.ExpiryDate -: The date on which the content is scheduled to expire. By default, this is the front matter `expiryDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.Lastmod`, and `.PublishDate`. +Use these methods to create navigation links between pages. -.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. - -.IsHome -: `true` in the context of the [homepage](/templates/homepage/). - -.IsNode -: Always `false` for regular content pages. - -.IsPage -: Always `true` for regular content pages. - -.IsSection -: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`. - -.IsTranslated -: `true` if there are translations to display. - -.Keywords -: The meta keywords for the content. - -.Kind -: The page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. - -.Language -: A language object that points to the language's definition in the site configuration. `.Language.Lang` gives you the language code. - -.Lastmod -: The date on which the content was last modified. By default, if `enableGitInfo` is `true` in your site configuration, this is the Git author date, otherwise the front matter `lastmod` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`,`ExpiryDate`, `.PublishDate`, and [`.GitInfo`][gitinfo]. - -.LinkTitle -: Access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. - -.Next -: Points up to the next regular page (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`. - -.NextInSection -: Points up to the next regular page below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`. - -.OutputFormats -: Contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) - -.Permalink -: The Permanent link for this page; see [Permalinks](/content-management/urls/) - -.Plain -: The Page content stripped of HTML tags and presented as a string. You may need to pipe the result through the [`htmlUnescape`](/functions/transform/htmlunescape) function when rendering this value with the HTML [output format](/templates/output-formats#output-format-definitions). - -.PlainWords -: The slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields). - -.Prev -: Points down to the previous regular page(sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`. Calling `.Prev` from the last page returns `nil`. - -.PrevInSection -: Points down to the previous regular page below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`. Calling `.PrevInSection` from the last page returns `nil`. - -.PublishDate -: The date on which the content was or will be published. By default, this is the front matter `publishDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.ExpiryDate`, and `.Lastmod`. - -.RawContent -: Raw markdown content without the front matter. Useful with [remarkjs.com]( -https://remarkjs.com) - -.RenderShortcodes -: See [Render Shortcodes](#rendershortcodes). - -.ReadingTime -: The estimated time, in minutes, it takes to read the content. - -.Resources -: Resources such as images and CSS that are associated with this page - -.Ref -: Returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). - -.RelPermalink -: The relative permanent link for this page. - -.RelRef -: Returns the relative permalink for a given reference (e.g., `RelRef -"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). - -.Site -: See [Site Variables](/variables/site/). - -.Sites -: Returns all sites (languages). A typical use case would be to link back to the main language: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`. - -.Sites.First -: Returns the site for the first language. If this is not a multilingual setup, it will return itself. - -.Summary -: A generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code><!--more--></code> at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details. - -.TableOfContents -: The rendered [table of contents](/content-management/toc/) for the page. - -.Title -: The title for this page. - -.Translations -: A list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. - -.TranslationKey -: The key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. - -.Truncated -: A boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. - -.Type -: The [content type](/content-management/types/) of the content (e.g., `posts`). - -.Weight -: Assigned weight (in the front matter) to this content, used in sorting. - -.WordCount -: The number of words in the content. +{{< list-pages-in-section path=/methods/page filter=methods_page_navigation filterType=include titlePrefix=. omitElementIDs=true >}} ## Page collections -List pages receive the following page collections in [context](/getting-started/glossary/#context): - -.Pages -: Regular pages within the current section (not recursive), and section pages for immediate descendant sections (not recursive). - -.RegularPages -: Regular pages within the current section (not recursive). - -.RegularPagesRecursive -: Regular pages within the current section, and regular pages within all descendant sections. - -## Writable page-scoped variables - -[.Scratch][scratch] -: Returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds. - -[.Store][store] -: Returns a Scratch to store and manipulate data. In contrast to the [`.Scratch`][scratch] method, this scratch is not reset on server rebuilds. - -## Section variables and methods - -Also see [Sections](/content-management/sections/). - -.CurrentSection -: The page's current section. The value can be the page itself if it is a section or the homepage. - -.FirstSection -: The page's first section below root, e.g. `/docs`, `/blog` etc. - -.InSection $anotherPage -: Whether the given page is in the current section. - -.IsAncestor $anotherPage -: Whether the current page is an ancestor of the given page. - -.IsDescendant $anotherPage -: Whether the current page is a descendant of the given page. - -.Parent -: A section's parent section or a page's section. - -.Section -: The [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`. - -.Sections -: The [sections](/content-management/sections/) below this content. - -## 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" }} - <p>Page contains identifier "my-identifier"</p> -{{ end }} - -{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }} - <p>Page contains duplicate "my-identifier" fragments</p> -{{ 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). - -## The `.RenderShortcodes` method {#rendershortcodes} - -{{< new-in "0.117.0" >}} This renders all the shortcodes in the content, preserving the surrounding markup (e.g. Markdown) as is. - -The common use case this is to composing a page from multiple content files while preserving a global context for table of contents and foot notes. - -This method is most often used in shortcode templates. A simple example of shortcode template including content from another page would look like: - -```go-html-template -{{ $p := site.GetPage (.Get 0) }} -{{ $p.RenderShortcodes }} -``` - -In the above it's important to understand and the difference between the two delimiters used when including a shortcode: - -* `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing (e.g. it's HTML). -* `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing (e.g. it's Markdown). - -The latter is what you want to use for the include shortcode outlined above: - -```md -## Mypage -{{%/* include "mypage" */%}} -`````` - - -Also see [Use Shortcodes](/content-management/shortcodes/#use-shortcodes). - -## 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. - -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -categories: [one] -tags: [two,three,four] -{{< /code-toggle >}} - -With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: - -* `.Params.tags` -* `.Params.categories` - -The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter: - -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -affiliatelink: "http://www.my-book-link.here" -recommendedby: "My Mother" -{{< /code-toggle >}} - -These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`. - -```go-html-template -<h3><a href="{{ .Params.affiliatelink }}">Buy this book</a></h3> -<p>It was recommended by {{ .Params.recommendedby }}.</p> -``` - -This template would render as follows: - -```html -<h3><a href="http://www.my-book-link.here">Buy this book</a></h3> -<p>It was recommended by my Mother.</p> -``` - -{{% note %}} -See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. -{{% /note %}} - -### The `.Param` method +Range through these collections when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page. -In Hugo, you can declare parameters in individual pages and globally for your entire website. A common use case is to have a general value for the site parameter and a more specific value for some of the pages (i.e., a header image): +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term +[context]: /getting-started/glossary/#context -```go-html-template -{{ $.Param "header_image" }} -``` +{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=. omitElementIDs=true >}} -The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your site configuration). +## Parameters -### Access nested fields in front matter +Use these methods to access page parameters. -When front matter contains nested fields like the following: +{{< list-pages-in-section path=/methods/page filter=methods_page_parameters filterType=include titlePrefix=. omitElementIDs=true >}} -{{< code-toggle file="content/example.md" fm=true copy=false >}} -title: Example -author: - given_name: John - family_name: Feminella - display_name: John Feminella -{{< /code-toggle >}} +## Sections -`.Param` can access these fields by concatenating the field names together with a dot: +Use these methods to access section pages, and their ancestors and descendants. See [details]. -```go-html-template -{{ $.Param "author.display_name" }} -``` +[details]: /content-management/sections/ -[configuring dates]: /getting-started/configuration/#configure-dates -[gitinfo]: /variables/git/ -[File Variables]: /variables/files/ -[bundle]: /content-management/page-bundles -[scratch]: /functions/scratch -[store]: /functions/store +{{< list-pages-in-section path=/methods/page filter=methods_page_sections filterType=include titlePrefix=. omitElementIDs=true >}} diff --git a/docs/content/en/variables/pages.md b/docs/content/en/variables/pages.md index 3917a6558..24b8fbbf4 100644 --- a/docs/content/en/variables/pages.md +++ b/docs/content/en/variables/pages.md @@ -1,25 +1,39 @@ --- -title: Pages methods -description: Pages is the core page collection in Hugo and has many useful methods. -categories: [variables and parameters] -keywords: [pages] +title: Pages variables +description: Use these methods with a collection of Page objects. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 21 -weight: 21 -aliases: [/pages] + weight: 60 +weight: 60 toc: true +aliases: [/variables/site-variables/] --- -Also see [List templates](/templates/lists) for an overview of sort methods. +{{% include "variables/_common/consistent-terminology.md" %}} -## .Next PAGE +## All methods -`.Next` and `.Prev` on `Pages` work similar to the methods with the same names on `.Page`, but are more flexible (and slightly slower) as they can be used on any page collection. +Use any of these methods with page collections in your templates. -`.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Next . }}{{ .RelPermalink }}{{ end }}`. Calling `.Next` with the first page in the collection returns `nil`. +{{< list-pages-in-section path=/methods/pages titlePrefix=. >}} -## .Prev PAGE +## Sort by -`.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Prev . }}{{ .RelPermalink }}{{ end }}`. Calling `.Prev` with the last page in the collection returns `nil`. +Use these methods to sort page collections. + +{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}} + +## Group by + +Use these methods to group page collections. + +{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}} + +## Navigation + +Use these methods to create navigation links between pages. + +{{< list-pages-in-section path=/methods/pages filter=methods_pages_navigation filterType=include titlePrefix=. omitElementIDs=true >}} diff --git a/docs/content/en/variables/shortcode.md b/docs/content/en/variables/shortcode.md new file mode 100644 index 000000000..57279b5de --- /dev/null +++ b/docs/content/en/variables/shortcode.md @@ -0,0 +1,16 @@ +--- +title: Shortcode variables +description: Use these methods in your shortcode templates. +categories: [variables] +keywords: [] +menu: + docs: + parent: variables + weight: 70 +weight: 70 +aliases: [/variables/shortcodes] +--- + +{{% include "variables/_common/consistent-terminology.md" %}} + +{{< list-pages-in-section path=/methods/shortcode titlePrefix=. >}} diff --git a/docs/content/en/variables/shortcodes.md b/docs/content/en/variables/shortcodes.md deleted file mode 100644 index a03485d6f..000000000 --- a/docs/content/en/variables/shortcodes.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Shortcode variables -description: Shortcodes can access page variables and also have their own specific built-in variables. -categories: [variables and parameters] -keywords: [shortcodes] -menu: - docs: - parent: variables - weight: 20 -weight: 20 ---- - -[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields: - -.Name -: Shortcode name. - -.Ordinal -: Zero-based ordinal in relation to its parent. If the parent is the page itself, this ordinal will represent the position of this shortcode in the page content. - -.Page -: The owning ´Page`. - -.Parent -: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root. - -.Position -: Contains [file name and position](https://godoc.org/github.com/gohugoio/hugo/common/text#Position) for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See [Error Handling in Shortcodes](/templates/shortcode-templates/#error-handling-in-shortcodes). - -.IsNamedParams -: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] - -.Inner -: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used - -.Scratch -: returns a writable [`Scratch`][scratch] to store and manipulate data which will be attached to the shortcode context. This scratch is reset on server rebuilds. - -.InnerDeindent {{< new-in "0.100.0" >}} -: Gets the `.Inner` with any indentation removed. This is what's used in the built-in `{{</* highlight */>}}` shortcode. - -[getfunction]: /functions/get/ -[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown -[shortcodes]: /templates/shortcode-templates/ -[scratch]: /functions/scratch diff --git a/docs/content/en/variables/site.md b/docs/content/en/variables/site.md index 2b9402c5f..532357785 100644 --- a/docs/content/en/variables/site.md +++ b/docs/content/en/variables/site.md @@ -1,108 +1,55 @@ --- title: Site variables -description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. -categories: [variables and parameters] -keywords: [global,site] +description: Use these methods with Site objects. A multilingual project will have two or more sites, one for each language. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 10 -weight: 10 -aliases: [/variables/site-variables/] + weight: 80 +weight: 80 toc: true +aliases: [/variables/site-variables/] --- -The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. - -## Get the site object from a partial - -All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available. - -## Site variables - -.Site.AllPages -: array of all pages, regardless of their translation. - -.Site.BaseURL -: the base URL for the site as defined in the site configuration. - -.Site.BuildDrafts -: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. - -.Site.Copyright -: a string representing the copyright of your website as defined in the site configuration. - -.Site.Data -: custom data, see [Data Templates](/templates/data-templates/). - -.Site.Home -: reference to the homepage's [page object](/variables/page/) - -.Site.IsMultiLingual -: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. - -.Site.Language.Lang -: the language code of the current locale (e.g., `en`). - -.Site.Language.LanguageName -: the full language name (e.g. `English`). - -.Site.Language.Weight -: the weight that defines the order in the `.Site.Languages` list. - -.Site.Language -: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. - -.Site.LanguageCode -: a string representing the language tag as defined in the site configuration. - -.Site.LanguagePrefix -: this can be used to prefix URLs to point to the correct language. It will even work when there is only one defined language. See also the functions [absLangURL](/functions/urls/abslangurl) and [relLangURL](/functions/urls/rellangurl). - -.Site.Languages -: an ordered list (ordered by defined weight) of languages. +{{% include "variables/_common/consistent-terminology.md" %}} -.Site.LastChange -: a [time.Time](https://godoc.org/time#Time) value representing the date/time of the most recent change to your site. +## All methods -.Site.Menus -: all the menus in the site. +Use any of these methods in your templates. -.Site.Pages -: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. +{{< list-pages-in-section path=/methods/site titlePrefix=.Site. >}} -.Site.RegularPages -: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. +## Multilingual -.Site.Sections -: top-level directories of the site. +Use these methods with your multilingual projects. -.Site.Taxonomies -: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template). +{{< list-pages-in-section path=/methods/site filter=methods_site_multilingual filterType=include titlePrefix=.Site. omitElementIDs=true >}} -.Site.Title -: a string representing the title of the site. +[`site`]: /functions/global/site +[context]: /getting-started/glossary/#context +[configuration file]: /getting-started/configuration -## Site parameters +## Page collections -`.Site.Params` is a container holding the values from the `params` section of your site configuration. +Range through these collections when rendering lists on any page. -### Example: `.Site.Params` +{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=.Site. omitElementIDs=true >}} -The following `config.[yaml|toml|json]` defines a site-wide parameter for `description`: +## Global site function -{{< code-toggle file="hugo" >}} -baseURL = "https://yoursite.example.com/" +Within a partial template, if you did not pass a `Page` or `Site` object in [context], you cannot use this syntax: -[params] - description = "Tesla's Awesome Hugo Site" - author = "Nikola Tesla" -{{</ code-toggle >}} +```go-html-template +{{ .Site.SomeMethod }} +``` -You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: +Instead, use the global [`site`] function: -{{< code file="layouts/partials/head.html" >}} -<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" /> -{{< /code >}} +```go-html-template +{{ site.SomeMethod }} +``` -[config]: /getting-started/configuration/ +{{% note %}} +You can use the global site function in all templates to avoid context problems. Its usage is not limited to partial templates. +{{% /note %}} diff --git a/docs/content/en/variables/sitemap.md b/docs/content/en/variables/sitemap.md deleted file mode 100644 index 80fb11076..000000000 --- a/docs/content/en/variables/sitemap.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Sitemap variables -description: -categories: [variables and parameters] -keywords: [sitemap] -menu: - docs: - parent: variables - weight: 80 -weight: 80 ---- - -A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them: - -.Sitemap.ChangeFreq -: the page change frequency - -.Sitemap.Priority -: the priority of the page - -.Sitemap.Filename -: the sitemap file name - -[pagevars]: /variables/page/ diff --git a/docs/content/en/variables/taxonomy.md b/docs/content/en/variables/taxonomy.md index 2c1e051a9..ee6d73b2e 100644 --- a/docs/content/en/variables/taxonomy.md +++ b/docs/content/en/variables/taxonomy.md @@ -1,138 +1,21 @@ --- title: Taxonomy variables -description: Hugo's taxonomy system exposes variables to taxonomy and term templates. -categories: [variables and parameters] -keywords: [taxonomy,term] +description: Use these methods with Taxonomy objects. +categories: [variables] +keywords: [] menu: docs: parent: variables - weight: 30 -toc: true -weight: 30 + weight: 90 +weight: 90 --- -## Taxonomy templates +{{% include "variables/_common/consistent-terminology.md" %}} -Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name. +{{< list-pages-in-section path=/methods/taxonomy titlePrefix=. >}} -In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ variables: +{{% note %}} +Within a taxonomy or term template use the [`Data`] method to retrieve information specific to the taxonomy or term. -.Data.Singular -: The singular name of the taxonomy (e.g., `tags => tag`). - -.Data.Plural -: The plural name of the taxonomy (e.g., `tags => tags`). - -.Data.Pages -: The collection of term pages related to this taxonomy. Aliased by `.Pages`. - -.Data.Terms -: A map of terms and weighted pages related to this taxonomy. - -.Data.Terms.Alphabetical -: A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with`.Data.Terms.Alphabetical.Reverse`. - -.Data.Terms.ByCount -: A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with`.Data.Terms.ByCount.Reverse`. - -## Term templates - -Pages rendered by term templates have `.Kind` set to `term` and `.Type` set to the taxonomy name. - -In term templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _term_ variables: - -.Data.Singular -: The singular name of the taxonomy (e.g., `tags => tag`). - -.Data.Plural -: The plural name of the taxonomy (e.g., `tags => tags`). - -.Data.Pages -: The collection of content pages related to this taxonomy. Aliased by `.Pages`. - -.Data.Term -: The term itself (e.g., `tag-one`). - -## Access taxonomy data from any template - -Access the entire taxonomy data structure from any template with `site.Taxonomies`. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example: - -```json -{ - "categories": { - "news": [ - { - "Weight": 0, - "Page": { - "Title": "Post 1", - "Date": "2022-12-18T15:13:35-08:00" - ... - } - }, - { - "Weight": 0, - "Page": { - "Title": "Post 2", - "Date": "2022-12-18T15:13:46-08:00", - ... - } - } - ] - }, - "tags": { - "international": [ - { - "Weight": 0, - "Page": { - "Title": "Post 1", - "Date": "2021-01-01T00:00:00Z" - ... - } - } - ] - } -} -``` - -Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the [`index`] function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following: - -[`index`]: /functions/collections/indexfunction/ - -```go-html-template -{{ $pages := site.Taxonomies.categories.news }} -{{ $pages := index site.Taxonomies "categories" "news" }} -``` - -For example, to render the entire taxonomy data structure as a nested unordered list: - -```go-html-template -<ul> - {{ range $taxonomy, $terms := site.Taxonomies }} - <li> - {{ with site.GetPage $taxonomy }} - <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ end }} - <ul> - {{ range $term, $weightedPages := $terms }} - <li> - {{ with site.GetPage (path.Join $taxonomy $term) }} - <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> - {{ end }} - </li> - <ul> - {{ range $weightedPages }} - <li> - <a href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a> - </li> - {{ end }} - </ul> - {{ end }} - </ul> - </li> - {{ end }} -</ul> -``` - -See [Taxonomy Templates] for more examples. - -[Taxonomy Templates]: /templates/taxonomy-templates/ +[`Data`]: /methods/page/data +{{% /note %}} |