Miscellaneous edits towards the goal of consistent language

This commit is contained in:
Joe Mooring 2024-03-10 08:37:06 -07:00 committed by GitHub
parent f9fc2d5d63
commit e04291a990
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 68 additions and 91 deletions

View File

@ -24,14 +24,14 @@ The current list of content formats in Hugo:
| Name | Markup identifiers | Comment |
| ------------- | ------------- |-------------|
| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `Markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
| Goldmark | `markdown`, `goldmark` |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).|
|Emacs Org-Mode|`org`|See [go-org](https://github.com/niklasfasching/go-org).|
|AsciiDoc|`asciidocext`, `adoc`, `ad`|Needs [Asciidoctor][ascii] installed.|
|RST|`rst`|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
|Pandoc|`pandoc`, `pdc`|Needs [Pandoc](https://www.pandoc.org/) installed.|
|HTML|`html`, `htm`|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
The `markup` identifier is fetched from either the `markup` field in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
## External helpers

View File

@ -249,19 +249,21 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
{{ end }}
```
#### EXIF variables
#### EXIF methods
.Date
: Image creation date/time. Format with the [time.Format] function.
Date
: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
.Lat
: GPS latitude in degrees.
[time.Format]: /functions/time/format/
.Long
: GPS longitude in degrees.
Lat
: (`float64`) Returns the GPS latitude in degrees.
.Tags
: A collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration](#exif-data).
Long
: (`float64`) Returns the GPS longitude in degrees.
Tags
: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration].
## Image processing options
@ -500,7 +502,7 @@ If you change image processing methods or options, or if you rename or remove im
hugo --gc
```
[time.Format]: /functions/time/format/
[`anchor`]: /content-management/image-processing#anchor
[mounted]: /hugo-modules/configuration#module-configuration-mounts
[page bundle]: /content-management/page-bundles/

View File

@ -587,7 +587,7 @@ To support Multilingual mode in your themes, some considerations must be taken f
* Come from the built-in `.Permalink` or `.RelPermalink`
* Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}`
If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefor harmless for single-language Hugo websites).
## Generate multilingual content with `hugo new content`

View File

@ -68,7 +68,7 @@ The `<` character indicates that the shortcode's inner content does *not* need f
### Nested shortcodes
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
## Embedded shortcodes
@ -443,19 +443,10 @@ To learn how to configure your Hugo site to meet the new EU privacy regulation,
To learn more about creating custom shortcodes, see the [shortcode template documentation].
[`figure` shortcode]: #figure
[contentmanagementsection]: /content-management/formats/
[examplegist]: https://gist.github.com/spf13/7896402
[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/
[Hugo and the GDPR]: /about/hugo-and-gdpr/
[Instagram]: https://www.instagram.com/
[pagevariables]: /methods/page/
[partials]: /templates/partials/
[quickstart]: /getting-started/quick-start/
[sctemps]: /templates/shortcode-templates/
[scvars]: /methods/shortcode/
[shortcode template documentation]: /templates/shortcode-templates/
[templatessection]: /templates/
[Vimeo]: https://vimeo.com/
[YouTube Videos]: https://www.youtube.com/
[YouTube Input shortcode]: #youtube

View File

@ -13,9 +13,7 @@ toc: true
aliases: [/content/summaries/,/content-management/content-summaries/]
---
<!--more-->
With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
With the use of the [`Summary`] method on `Page` object, Hugo generates summaries of content to use as a short version in summary views.
## Summary splitting options
@ -23,7 +21,7 @@ With the use of the `.Summary` [page variable][pagevariables], Hugo generates su
* Manual Summary Split
* Front Matter Summary
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the [`RelPermalink`], [`Permalink`], and [`Truncated`] methods.
### Automatic summary splitting
@ -105,6 +103,9 @@ You can show content summaries with the following code. You could use the follow
Note how the `.Truncated` boolean variable value may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
[`Permalink`]: /methods/page/permalink/
[`RelPermalink`]: /methods/page/relpermalink/
[`Summary`]: /methods/page/summary/
[`Truncated`]: /methods/page/truncated/
[org]: /content-management/formats/
[pagevariables]: /methods/page/
[section template]: /templates/section-templates/

View File

@ -42,7 +42,7 @@ A collection of textile samples lay spread out on the table - Samsa was a travel
Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
The `.TableOfContents` method on a `Page` object outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
## Template example: basic TOC
@ -66,28 +66,16 @@ The following is an example of a very basic [single page template]:
## Template example: TOC partial
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
{{< code file=layouts/partials/toc.html >}}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>
<h2>{{ .Title }}</h2>
</header>
{{ .TableOfContents }}
</aside>
{{ end }}
{{< /code >}}
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a [`WordCount`] greater than 400. This example also demonstrates how to use [conditionals] in your templating:
{{% note %}}
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{ .TableOfContents }}` variable to pull from.
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `.TableOfContents` method to pull from.
{{% /note %}}
## Usage with AsciiDoc
Hugo supports table of contents with AsciiDoc content format.
In the header of your content file, specify the AsciiDoc TOC directives required to generate the table of contents. Then use the `.TableOfContents` method within your template.
In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
```asciidoc
// <!-- Your front matter up here -->
@ -95,22 +83,19 @@ In the header of your content file, specify the AsciiDoc TOC directives necessar
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] configuration key
:toclevels: 4
== Introduction
== Section 1
One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
Paragraph 1.
== My Heading
== Section 2
He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
=== My Subheading
A collection of textile samples lay spread out on the table - Samsa was a traveling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
Paragraph 2.
```
Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
[conditionals]: /templates/introduction/#conditional-blocks
[`WordCount`]: /methods/page/wordcount
[front matter]: /content-management/front-matter/
[pagevars]: /methods/page/
[partials]: /templates/partials/

View File

@ -421,7 +421,7 @@ To transform a serialized object into a data structure. For example, transformin
###### variable
A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo`&nbsp;and&nbsp;`$bar` are variables.
A user-defined [identifier](#identifier) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo`&nbsp;and&nbsp;`$bar` are variables.
###### walk

View File

@ -68,7 +68,7 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [
{{< new-in 0.123.0 >}}
{{% note %}}
Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendent pages.
Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
[build options]: /content-management/build-options/
[`cascade`]: /content-management/front-matter/#cascade-field

View File

@ -155,10 +155,10 @@ Hugo's Open Graph template is configured using a mix of configuration variables
series = "series"
{{</ code-toggle >}}
{{< code-toggle file=content/blog/my-post.md >}}
{{< code-toggle file=content/blog/my-post.md fm=true >}}
title = "Post title"
description = "Text about this post"
date = "2006-01-02"
date = 2024-03-08T08:18:11-08:00
images = ["post-cover.png"]
audio = []
videos = []

View File

@ -64,7 +64,7 @@ In the example above the dot represents the `Page` object, and we call its [`Tit
[front matter]: /content-management/front-matter/
[`Title`]: /methods/page/title
The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we can rebind the context to another value or object within [`range`] or [`with`] blocks.
The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
[`range`]: /functions/go-template/range/
[`with`]: /functions/go-template/with/
@ -221,7 +221,7 @@ This is line two.`
## Variables
A variable is a user-defined [identifier] prefaced with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
A variable is a user-defined [identifier] prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
[identifier]: /getting-started/glossary/#identifier
@ -299,7 +299,7 @@ As shown above, frequently used functions have an alias. Use aliases in your tem
When calling a function, separate the arguments from the function, and from each other, with a space. For example:
```go-html-template
{{ $total := add 1 2 3 4 }} → 10
{{ $total := add 1 2 3 4 }}
```
## Methods

View File

@ -82,7 +82,7 @@ Call the partial above, passing a menu ID and the current page in context.
## Page references
Regardless of how you [define menu entries], an entry associated with a page has access to page variables and methods.
Regardless of how you [define menu entries], an entry associated with a page has access to page context.
This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.

View File

@ -178,7 +178,10 @@ outputs:
## List output formats
Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
Each `Page` object has both an [`OutputFormats`] method (all formats, including the current) and an [`AlternativeOutputFormats`] method, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
[`OutputFormats`]: /methods/page/outputformats
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats
```go-html-template
{{ range .AlternativeOutputFormats -}}
@ -188,7 +191,10 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
## Link to output formats
The `Permalink` and `RelPermalink` methods on a `Page` object return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template from which they are called.
The [`Permalink`] and [`RelPermalink`] methods on a `Page` object return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template from which they are called.
[`Permalink`]: /methods/page/permalink
[`RelPermalink`]: /methods/page/relpermalink
__from `single.json.json`:__
```go-html-template

View File

@ -125,11 +125,11 @@ $.Page.Params
: refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
$.Page.Site.Params
: refers to global variables as defined in your [site's configuration file][config].
: refers to parameters defined in your site configuration.
#### `.IsNamedParams`
The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
The `.IsNamedParams` method checks whether the shortcode declaration uses named parameters and returns a boolean value.
For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
@ -350,19 +350,20 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
## Error handling in shortcodes
Use the [errorf](/functions/fmt/errorf) template function and [`.Position`] shortcode method to get useful error messages in shortcodes:
Use the [`errorf`] template function with the [`Name`] and [`Position`] shortcode methods to generate useful error messages:
```sh
{{< code file=layouts/shortcodes/greeting.html >}}
{{ with .Get "name" }}
<p>Hello, my name is {{ . }}.</p>
{{ else }}
{{ errorf "missing value for parameter 'name': %s" .Position }}
{{ errorf "The %q shortcode requires a 'name' parameter. See %s" .Name .Position }}
{{ end }}
```
{{< /code >}}
When the above fails, you will see an `ERROR` log similar to the below:
When the above fails, you will see an `ERROR` message such as:
```sh
ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
ERROR The "greeting" shortcode requires a 'name' parameter. See "/home/user/project/content/_index.md:12:1"
```
## Inline shortcodes
@ -396,18 +397,14 @@ The same inline shortcode can be reused later in the same content file, with dif
{{</* time.inline /*/>}}
```
[basic content files]: /content-management/formats/
[`.Parent`]: /methods/shortcode/parent/
[`errorf`]: /functions/fmt/errorf/
[`Name`]: /methods/shortcode/name/
[`Position`]: /methods/shortcode/position/
[built-in shortcode]: /content-management/shortcodes/
[config]: /getting-started/configuration/
[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
[source organization]: /getting-started/directory-structure/
[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
[figure]: /content-management/shortcodes/#figure
[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
[lookup order]: /templates/lookup-order/
[pagevars]: /methods/page/
[`.Parent`]: /methods/shortcode/parent/
[`.Position`]: /methods/shortcode/position/
[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes
[source organization]: /getting-started/directory-structure/
[vimeoexample]: #single-flexible-example-vimeo
[youtubeshortcode]: /content-management/shortcodes/#youtube

View File

@ -22,7 +22,7 @@ Hugo provides multiple ways to use taxonomies throughout your project templates:
## Taxonomy list templates
Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
Taxonomy list page templates are lists and therefore have all the methods available to [list pages][lists].
### Taxonomy list template lookup order
@ -102,7 +102,7 @@ type WeightedPages []WeightedPage
## Displaying custom metadata in taxonomy terms templates
If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by ranging over the page collection returned by the [`Pages`] method:
```go-html-template
<ul>
@ -311,6 +311,7 @@ Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to
</ul>
{{< /code >}}
[`Pages`]: /methods/page/pages/
[getpage]: /methods/page/getpage/
[lists]: /templates/lists/
[renderlists]: /templates/lists/

View File

@ -46,7 +46,7 @@ Hugo also has support for a default content template to be used in the event tha
## Which template will be rendered?
The following is the [lookup order][lookup] for content views:
The following is the [lookup order] for content views:
1. `/layouts/<TYPE>/<VIEW>.html`
2. `/layouts/_default/<VIEW>.html`
@ -74,7 +74,7 @@ In this example, `.Render` is passed into the template to call the [render funct
### `summary.html`
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
Hugo passes the page object to the following `summary.html` view template.
{{< code file=layouts/_default/summary.html >}}
<article class="post">
@ -101,13 +101,7 @@ Continuing on the previous example, we can change our render function to use a s
{{< /code >}}
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
[pagevars]: /methods/page/
[render]: /methods/page/render/
[single]: /templates/single-page-templates/
[spf]: https://spf13.com
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
[summaries]: /content-management/summaries/
[taxonomylists]: /templates/taxonomy-templates/