diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index 40704d9a0..f6550cc1b 100644 --- a/content/en/content-management/build-options.md +++ b/content/en/content-management/build-options.md @@ -93,7 +93,7 @@ title = 'Headless page' To include the content and images on the home page: -{{< code file=layouts/_default/home.html lang=go-html-template >}} +{{< code file=layouts/_default/home.html >}} {{ with .Site.GetPage "/headless" }} {{ .Content }} {{ range .Resources.ByType "image" }} @@ -153,7 +153,7 @@ In the front matter above, note that we have set `list` to `local` to include th To include the content and images on the home page: -{{< code file=layouts/_default/home.html lang=go-html-template >}} +{{< code file=layouts/_default/home.html >}} {{ with .Site.GetPage "/headless" }} {{ range .Pages }} {{ .Content }} @@ -212,7 +212,7 @@ render = 'always' To render the glossary: -{{< code file=layouts/glossary/list.html lang=go-html-template >}} +{{< code file=layouts/glossary/list.html >}}
{{ range .Pages }}
{{ .Title }}
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 249be56f8..329945b2a 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -188,8 +188,8 @@ public When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: ```text -Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) -Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en Press Ctrl+C to stop ``` diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index c2ae7e2cf..860fff2bb 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -61,11 +61,11 @@ content/ In the above example `content/` directory, there are four leaf bundles: -`about` +about : This leaf bundle is at the root level (directly under `content` directory) and has only the `index.md`. -`my-post` +my-post : This leaf bundle has the `index.md`, two other content Markdown files and two image files. @@ -78,10 +78,10 @@ These content files are page resources of `my-post` and only available in `my-post/index.md` resources. They will **not** be rendered as individual pages. -`my-other-post` +my-other-post : This leaf bundle has only the `index.md`. -`another-leaf-bundle` +another-leaf-bundle : This leaf bundle is nested under couple of directories. This bundle also has only the `index.md`. @@ -167,11 +167,11 @@ content/ In the above example `content/` directory, there are two branch bundles (and a leaf bundle): -`branch-bundle-1` +branch-bundle-1 : This branch bundle has the `_index.md`, two other content Markdown files and two image files. -`branch-bundle-2` +branch-bundle-2 : This branch bundle has the `_index.md` and a nested leaf bundle. diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 65b8000c4..a91fe21c0 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -425,8 +425,8 @@ Hugo renders alias files before rendering pages. A new page with the previous fi Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context: -`Permalink` +Permalink : the link to the page being aliased -`Page` +Page : the Page data for the page being aliased diff --git a/content/en/contribute/_index.md b/content/en/contribute/_index.md index dc6ce01cb..ca7a18c36 100644 --- a/content/en/contribute/_index.md +++ b/content/en/contribute/_index.md @@ -1,7 +1,7 @@ --- title: Contribute to the Hugo project linkTitle: Overview -description: Contribute to Hugo development and documentation. +description: Contribute to Hugo development, documentation, and themes. categories: [] keywords: [] menu: @@ -13,6 +13,4 @@ weight: 10 aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/] --- -Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support in both its development and documentation. - -Hugo's contribution guidelines are [detailed in a `CONTRIBUTING.md`](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md) in the Hugo source repository on GitHub. +Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support. diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index ede74b3e4..b4de88256 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -1,9 +1,8 @@ --- -title: Contribute to development -linkTitle: Development -description: Hugo relies heavily on contributions from the open source community. +title: Development +description: Contribute to the development of Hugo. categories: [contribute] -keywords: [dev,open source] +keywords: [development] menu: docs: parent: contribute diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 98a5b15fd..58af8c88a 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -1,20 +1,255 @@ --- -title: Contribute to documentation -linkTitle: Documentation -description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover. +title: Documentation +description: Help us to improve the documentation by identifying issues and suggesting changes. categories: [contribute] -keywords: [docs,documentation,community, contribute] +keywords: [documentation] menu: docs: parent: contribute weight: 30 -toc: true weight: 30 +toc: true aliases: [/contribute/docs/] --- +## Introduction + +We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository. + +For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository]. + +For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository]. + +## Guidelines + +### Markdown + +Please follow these markdown guidelines: + +- Use [ATX] headings, not [setext] headings +- Use [fenced code blocks], not [indented code blocks] +- Use hyphens, not asterisks, with unordered [list items] +- Use the [note shortcode] instead of blockquotes +- Do not mix [raw HTML] within markdown +- Do not use bold text instead of a heading or description term (`dt`) +- Remove consecutive blank lines (maximum of two) +- Remove trailing spaces + +### Style + +Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice. + +#### Terminology + +Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note: + +- The term "front matter" is two words unless you are referring to the configuration key +- Use the word "map" instead of "dictionary" +- Use the word "flag" instead of "option" when referring to a command line flag + +#### Page titles and headings + +Please follow these guidelines for page titles and headings: + +- Use sentence-style capitalization +- Avoid markdown in headings and page titles +- Shorter is better + +#### Use active voice with present tense + +In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible. + +No → With Hugo you can build a static site.\ +Yes → Build a static site with Hugo. + +No → This will cause Hugo to generate HTML files in the public directory.\ +Yes → Hugo generates HTML files in the public directory. + +#### Use second person instead of third person + +No → Users should exercise caution when deleting files.\ +Better → You must be cautious when deleting files.\ +Best → Be cautious when deleting files. + +#### Avoid adverbs when possible + +No → Hugo is extremely fast.\ +Yes → Hugo is fast. + +{{% note %}} +"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995). +{{% /note %}} + +#### Miscellaneous + +Other guidelines to consider: + +- Do not place list items directly under a heading; include an introductory sentence or phrase before the list. +- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content. +- Do not place description terms (`dt`) within backticks unless required for syntactic clarity. +- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments. +- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..." +- When including code samples, use short snippets that demonstrate the concept. +- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible. + +## Code examples + +Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimeters. + +### Fenced code blocks + +Always include the language code when using a fenced code block: + +````text +```go-html-template +{{ if eq $foo "bar" }} + {{ print "foo is bar" }} +{{ end }} +``` +```` + +Rendered: + +```go-html-template +{{ if eq $foo "bar" }} + {{ print "foo is bar" }} +{{ end }} +``` + +### Shortcode calls + +Use this syntax to include shortcodes calls within your code examples: + +```text +{{}} +{{%/*/* foo */*/%}} +``` + +Rendered: + +```text +{{}} +{{%/* foo */%}} +``` + +### Site configuration + +Use the [code-toggle shortcode] to include site configuration examples: + +```text +{{}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' +{{}} +``` + +Rendered: + +{{< code-toggle file=hugo >}} +baseURL = 'https://example.org/' +languageCode = 'en-US' +title = 'My Site' +{{< /code-toggle >}} + +### Front matter + +Use the [code-toggle shortcode] to include front matter examples: + +```text +{{}} +title = 'My first post' +date = 2023-11-09T12:56:07-08:00 +draft = false +{{}} +``` + +Rendered: + +{{< code-toggle file=content/posts/my-first-post.md fm=true >}} +title = 'My first post' +date = 2023-11-09T12:56:07-08:00 +draft = false +{{< /code-toggle >}} + +### Other code examples + +Use the [code shortcode] for other code examples that require a file name: + +```text +{{}} +{{ range .Site.RegularPages }} +

{{ .LinkTitle }}

+{{ end }} +{{}} +``` + +Rendered: + +{{< code file=layouts/_default/single.html >}} +{{ range .Site.RegularPages }} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +## Shortcodes + +These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use. + +### note + +Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content: + +```text +{{%/* note */%}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{%/* /code */%}} +``` + +Rendered: + +{{% note %}} +Use the [`math.Mod`] function to control... + +[`math.Mod`]: /functions/math/mod/ +{{% /code %}} + +### code-toggle + +Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments: + +copy +: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. + +file +: (`string`) The file name to display. Omit the file extension for site configuration examples. + +fm +: (`bool`) Whether the example is front matter. Default is `false`. + +### code + +Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments: + +copy +: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`. + +file +: (`string`) The file name to display. + +lang +: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`. + ## GitHub workflow +{{% note %}} +This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line. +{{% /note %}} + +Use this workflow to create and submit pull requests. + Step 1 : Fork the [documentation repository]. @@ -25,7 +260,7 @@ Step 3 : Create a new branch with a descriptive name. ```sh -git checkout -b fix/typos-site-variables +git checkout -b fix/typos-shortcode-templates ``` Step 4 @@ -35,7 +270,7 @@ Step 5 : Commit your changes with a descriptive commit message, typically 50 characters or less. Add the "Closes" keyword if your change addresses one or more open [issues]. ```sh -git commit -m "Fix typos on site variables page +git commit -m "Fix typos on the shortcode templates page Closes #1234 Closes #5678" @@ -47,130 +282,22 @@ Step 5 Step 6 : Visit the [documentation repository] and create a pull request (PR). -[documentation repository]: https://github.com/gohugoio/hugoDocs/ -[issues]: https://github.com/gohugoio/hugoDocs/issues - Step 7 -: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR. +: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. -## Including sample code - -{{% note %}} -Use this syntax to include shortcodes calls within your code samples: - -`{{}}`\ -`{{%/*/* foo */*/%}}` -{{% /note %}} - -### Fenced code blocks - -Include the language when using a fenced code block. - -````text -```go-html-template -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} -{{ end }} -``` -```` - -Rendered: - -```go-html-template -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} -{{ end }} -``` - -### The code shortcode - -Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters: - -copy -: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `false`. - -file -: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language. - -lang -: (`string`) The code language. Default is `text`. - -````text -{{}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} -{{ end }} -{{}} - -```` - -Rendered: - -{{< code file=layouts/_default_/single.html >}} -{{ if eq $foo "bar" }} - {{ print "foo is bar" }} -{{ end }} -{{< /code >}} - -### The code-toggle shortcode - -Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters: - -copy -: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `false`. - -file -: (`string`) The file name to display. Omit the file extension for site configuration and data file examples. - -fm -: (`bool`) If `true`, displays the code as front matter. Default is `false`. - -#### Site configuration example - -```text -{{}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{}} -``` - -Rendered: - -{{< code-toggle file=hugo >}} -baseURL = 'https://example.org' -languageCode = 'en-US' -title = "Example Site" -{{< /code-toggle >}} - -#### Front matter example - -```text -{{}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false -{{}} -``` - -Rendered: - -{{< code-toggle file=content/about.md fm=true >}} -title = "About" -date = 2023-04-02T12:47:24-07:00 -draft = false -{{< /code-toggle >}} - -## Admonitions - -Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode. - -```text -{{%/* note */%}} -This is **bold** text. -{{%/* /note */%}} -``` - -{{% note %}} -This is **bold** text. -{{% /note %}} +[ATX]: https://spec.commonmark.org/0.30/#atx-headings +[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/ +[basic english]: https://simple.wikipedia.org/wiki/Basic_English +[code examples]: #code-examples +[code shortcode]: #code +[code-toggle shortcode]: #code-toggle +[documentation repository]: https://github.com/gohugoio/hugoDocs/ +[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks +[glossary of terms]: /getting-started/glossary/ +[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks +[issues]: https://github.com/gohugoio/hugoDocs/issues +[list items]: https://spec.commonmark.org/0.30/#list-items +[note shortcode]: #note +[project repository]: https://github.com/gohugoio/hugo +[raw HTML]: https://spec.commonmark.org/0.30/#raw-html +[setext]: https://spec.commonmark.org/0.30/#setext-heading diff --git a/content/en/contribute/themes.md b/content/en/contribute/themes.md index d7844f130..34056c35a 100644 --- a/content/en/contribute/themes.md +++ b/content/en/contribute/themes.md @@ -1,24 +1,30 @@ --- -title: Add your hugo theme to the showcase -linkTitle: Themes -description: If you've built a Hugo theme and want to contribute back to the Hugo Community, share it with us. +title: Themes +description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us. categories: [contribute] -keywords: [contribute,themes,design] +keywords: [themes] menu: docs: parent: contribute weight: 40 weight: 40 -toc: true aliases: [/contribute/theme/] --- -A collection of all themes created by the Hugo community, including screenshots and demos, can be found at [themes.gohugo.io]. Every theme in this list will automatically be added to the theme site. +Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo community. -Another great site for Hugo themes is [jamstackthemes.dev/](https://jamstackthemes.dev/ssg/hugo/). +To submit your theme: -### Add your theme to the repository +1. Read the [submission guidelines] +2. Open a pull request in the [themes repository] -In order to add your Hugo theme to [themes.gohugo.io] please [open a pull request in the theme repository](https://github.com/gohugoio/hugoThemesSiteBuilder). **Please make sure that you've read the theme submission guidelines in the [README](https://github.com/gohugoio/hugoThemesSiteBuilder/blob/main/README.md#hugo-themes) of the hugoThemesSiteBuilder repository.** +Other useful theme directories: +- [jamstack.club] +- [jamstackthemes.dev] + +[jamstack.club]: https://jamstack.club/#ssg=hugo +[jamstackthemes.dev]: https://jamstackthemes.dev/ssg/hugo +[submission guidelines]: https://github.com/gohugoio/hugoThemesSiteBuilder/tree/main#readme +[themes repository]: https://github.com/gohugoio/hugoThemesSiteBuilder [themes.gohugo.io]: https://themes.gohugo.io/ diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index 3dfe0efa9..04734f086 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -227,11 +227,11 @@ With custom front matter dates, the comparison depends on the front matter data Using TOML for pages with custom front matter dates enables precise date comparisons. {{% /note %}} -With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML data value, it is [`time.Time`] value, enabling precise comparisons. +With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. In the TOML example below, note that the event date is not quoted. -{{< code file="content/events/2024-user-conference.md" lang=go-html-template >}} +{{< code file="content/events/2024-user-conference.md" >}} +++ title = '2024 User Conference" eventDate = 2024-04-01 diff --git a/content/en/functions/math/Add.md b/content/en/functions/math/Add.md index 5e3bfb162..afa8d48aa 100644 --- a/content/en/functions/math/Add.md +++ b/content/en/functions/math/Add.md @@ -15,8 +15,10 @@ action: signatures: [math.Add VALUE VALUE...] --- -If one of the numbers is a float, the result is a float. +If one of the numbers is a [`float`], the result is a `float`. ```go-html-template {{ add 12 3 2 }} → 17 ``` + +[`float`]: /getting-started/glossary/#float diff --git a/content/en/functions/math/Div.md b/content/en/functions/math/Div.md index 5123791b2..530474a78 100644 --- a/content/en/functions/math/Div.md +++ b/content/en/functions/math/Div.md @@ -15,8 +15,10 @@ action: signatures: [math.Div VALUE VALUE...] --- -If one of the numbers is a float, the result is a float. +If one of the numbers is a [`float`], the result is a `float`. ```go-html-template {{ div 12 3 2 }} → 2 ``` + +[`float`]: /getting-started/glossary/#float diff --git a/content/en/functions/math/Mul.md b/content/en/functions/math/Mul.md index 1db8ad9eb..6824599e3 100644 --- a/content/en/functions/math/Mul.md +++ b/content/en/functions/math/Mul.md @@ -15,8 +15,10 @@ action: signatures: [math.Mul VALUE VALUE...] --- -If one of the numbers is a float, the result is a float. +If one of the numbers is a [`float`], the result is a `float`. ```go-html-template {{ mul 12 3 2 }} → 72 ``` + +[`float`]: /getting-started/glossary/#float diff --git a/content/en/functions/math/Sub.md b/content/en/functions/math/Sub.md index 6c4ef10d5..2865ac191 100644 --- a/content/en/functions/math/Sub.md +++ b/content/en/functions/math/Sub.md @@ -14,8 +14,10 @@ action: signatures: [math.Sub VALUE VALUE...] --- -If one of the numbers is a float, the result is a float. +If one of the numbers is a [`float`], the result is a `float`. ```go-html-template {{ sub 12 3 2 }} → 7 ``` + +[`float`]: /getting-started/glossary/#float diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md index 6cfe539f1..d17f0580c 100644 --- a/content/en/functions/resources/ExecuteAsTemplate.md +++ b/content/en/functions/resources/ExecuteAsTemplate.md @@ -15,7 +15,7 @@ Hugo publishes the resource to the target path when you call its`.Publish`, `.Pe Let's say you have a CSS file that you wish to populate with values from your site configuration: -{{< code lang=go-html-template file=assets/css/template.css >}} +{{< code file=assets/css/template.css lang=go-html-template >}} body { background-color: {{ site.Params.style.bg_color }}; color: {{ site.Params.style.text_color }}; diff --git a/content/en/functions/strings/Contains.md b/content/en/functions/strings/Contains.md index a645d09f3..0344b2981 100644 --- a/content/en/functions/strings/Contains.md +++ b/content/en/functions/strings/Contains.md @@ -1,6 +1,6 @@ --- title: strings.Contains -description: Reports whether the string contains a substring. +description: Reports whether the given string contains the given substring. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/ContainsAny.md b/content/en/functions/strings/ContainsAny.md index 24ae31f4b..f331d09f7 100644 --- a/content/en/functions/strings/ContainsAny.md +++ b/content/en/functions/strings/ContainsAny.md @@ -1,6 +1,6 @@ --- title: strings.ContainsAny -description: Reports whether a string contains any character from a given string. +description: Reports whether the given string contains any character within the given set. categories: [] keywords: [] action: @@ -12,7 +12,7 @@ action: - functions/strings/HasSuffix - functions/collections/In returnType: bool - signatures: [strings.ContainsAny STRING CHARACTERS] + signatures: [strings.ContainsAny STRING SET] aliases: [/functions/strings.containsany] --- diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md index 284f625f8..2c4cb29e1 100644 --- a/content/en/functions/strings/ContainsNonSpace.md +++ b/content/en/functions/strings/ContainsNonSpace.md @@ -1,6 +1,6 @@ --- title: strings.ContainsNonSpace -description: Reports whether a string contains any non-space characters as defined by Unicode’s White Space property. +description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/Count.md b/content/en/functions/strings/Count.md index bc483d578..43b5baeff 100644 --- a/content/en/functions/strings/Count.md +++ b/content/en/functions/strings/Count.md @@ -1,6 +1,6 @@ --- title: strings.Count -description: Returns the number of non-overlapping instances of a substring within a string. +description: Returns the number of non-overlapping instances of the given substring within the given string. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/CountRunes.md b/content/en/functions/strings/CountRunes.md index 702c8c3b3..10788e174 100644 --- a/content/en/functions/strings/CountRunes.md +++ b/content/en/functions/strings/CountRunes.md @@ -1,6 +1,6 @@ --- title: strings.CountRunes -description: Returns the number of runes in a string excluding whitespace. +description: Returns the number of runes in the given string excluding whitespace. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/CountWords.md b/content/en/functions/strings/CountWords.md index ef439f417..3e4ec0465 100644 --- a/content/en/functions/strings/CountWords.md +++ b/content/en/functions/strings/CountWords.md @@ -1,6 +1,6 @@ --- title: strings.CountWords -description: Returns the number of words in a string. +description: Returns the number of words in the given string. categories: [] keywords: [] action: @@ -15,10 +15,6 @@ action: aliases: [/functions/countwords] --- -The template function works similar to the [.WordCount page variable][pagevars]. - ```go-html-template {{ "Hugo is a static site generator." | countwords }} → 6 ``` - -[pagevars]: /variables/page/ diff --git a/content/en/functions/strings/RuneCount.md b/content/en/functions/strings/RuneCount.md index 13b97b7e0..46fedf01f 100644 --- a/content/en/functions/strings/RuneCount.md +++ b/content/en/functions/strings/RuneCount.md @@ -1,6 +1,6 @@ --- title: strings.RuneCount -description: Returns the number of runes in a string. +description: Returns the number of runes in the given string. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/Title.md b/content/en/functions/strings/Title.md index 458768ab0..b7f1f9e5c 100644 --- a/content/en/functions/strings/Title.md +++ b/content/en/functions/strings/Title.md @@ -1,6 +1,6 @@ --- title: strings.Title -description: Converts the given string to title case. +description: Returns the given string, converting it to title case. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/Trim.md b/content/en/functions/strings/Trim.md index 63324667b..6dfac024b 100644 --- a/content/en/functions/strings/Trim.md +++ b/content/en/functions/strings/Trim.md @@ -1,6 +1,6 @@ --- title: strings.Trim -description: Returns the given string, removing leading and trailing characters that appear in the cutset. +description: Returns the given string, removing leading and trailing characters specified in the cutset. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/TrimLeft.md b/content/en/functions/strings/TrimLeft.md index 7fb323e48..07cdf0064 100644 --- a/content/en/functions/strings/TrimLeft.md +++ b/content/en/functions/strings/TrimLeft.md @@ -1,6 +1,6 @@ --- title: strings.TrimLeft -description: Returns the given string, removing leading characters that appear in the cutset. +description: Returns the given string, removing leading characters specified in the cutset. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/TrimRight.md b/content/en/functions/strings/TrimRight.md index 26a18ab35..b244925ef 100644 --- a/content/en/functions/strings/TrimRight.md +++ b/content/en/functions/strings/TrimRight.md @@ -1,6 +1,6 @@ --- title: strings.TrimRight -description: Returns the given string, removing trailing characters that appear in the cutset. +description: Returns the given string, removing trailing characters specified in the cutset. categories: [] keywords: [] action: diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md index 204d6b7ed..17ae0afc6 100644 --- a/content/en/functions/strings/Truncate.md +++ b/content/en/functions/strings/Truncate.md @@ -1,6 +1,6 @@ --- title: strings.Truncate -description: Truncates a text to a max length without cutting words or leaving unclosed HTML tags. +description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. categories: [] keywords: [] action: @@ -18,5 +18,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s ``` {{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML` template function](/functions/safe/html) before sending the value to truncate. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. +If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. + +[`safeHTML`]: /functions/safe/html {{% /note %}} diff --git a/content/en/functions/templates/Exists.md b/content/en/functions/templates/Exists.md index c96726ff9..e57610488 100644 --- a/content/en/functions/templates/Exists.md +++ b/content/en/functions/templates/Exists.md @@ -11,9 +11,9 @@ action: aliases: [/functions/templates.exists] --- -A template file is any file living below the `layouts` directories of either the project or any of its theme components including partials and shortcodes. +A template file is any file within the `layouts` directory of either the project or any of its theme components. -The function is particularly handy with dynamic path. The following example ensures the build will not break on a `.Type` missing its dedicated `header` partial. +Use the `templates.Exists` function with dynamic template paths: ```go-html-template {{ $partialPath := printf "headers/%s.html" .Type }} @@ -23,3 +23,5 @@ The function is particularly handy with dynamic path. The following example ensu {{ partial "headers/default.html" . }} {{ end }} ``` + +In the example above, if a "headers" partial does not exist for the given content type, Hugo falls back to a default template. diff --git a/content/en/functions/transform/Highlight.md b/content/en/functions/transform/Highlight.md index 7dc6b766c..341d68ca3 100644 --- a/content/en/functions/transform/Highlight.md +++ b/content/en/functions/transform/Highlight.md @@ -76,10 +76,10 @@ If the `LANG` argument is blank or an unrecognized language, auto-detect the lan {{% note %}} Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: -`lineNos=inline` +lineNos=inline : equivalent to `lineNos=true` and `lineNumbersInTable=false` -`lineNos=table` +lineNos=table : equivalent to `lineNos=true` and `lineNumbersInTable=true` {{% /note %}} diff --git a/content/en/functions/transform/Plainify.md b/content/en/functions/transform/Plainify.md index cd163b36d..040145170 100644 --- a/content/en/functions/transform/Plainify.md +++ b/content/en/functions/transform/Plainify.md @@ -14,7 +14,3 @@ aliases: [/functions/plainify] ```go-html-template {{ "BatMan" | plainify }} → BatMan ``` - -See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars]. - -[pagevars]: /variables/page/ diff --git a/content/en/functions/urls/Anchorize.md b/content/en/functions/urls/Anchorize.md index e74e885b2..72b3d54a9 100644 --- a/content/en/functions/urls/Anchorize.md +++ b/content/en/functions/urls/Anchorize.md @@ -1,6 +1,6 @@ --- title: urls.Anchorize -description: Returns a sanitized string to use as an id attribute within an anchor element. +description: Returns the given string, sanitized for usage in an HTML id attribute. categories: [] keywords: [] action: @@ -12,15 +12,26 @@ action: aliases: [/functions/anchorize] --- -If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark). +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags. +## Sanitizing logic -```go-html-template -{{ anchorize "This is a header" }} → this-is-a-header -{{ anchorize "This is also a header" }} → this-is-also----a-header -{{ anchorize "main.go" }} → maingo -{{ anchorize "Article 123" }} → article-123 -{{ anchorize "<- Let's try this, shall we?" }} → --lets-try-this-shall-we -{{ anchorize "Hello, 世界" }} → hello-世界 -``` +With the default markdown renderer, Goldmark, the sanitizing logic is controlled by your site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +autoHeadingIDType = 'github' +{{< /code-toggle >}} + +This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering markdown to HTML. + +Set `autoHeadingIDType` to one of: + +github +: Compatible with GitHub. This is the default, and strongly recommended. + +github-ascii +: Similar to the "github" setting, but removes non-ASCII characters. + +blackfriday +: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release. diff --git a/content/en/functions/urls/URLize.md b/content/en/functions/urls/URLize.md index 0017baf18..bf44a82d1 100644 --- a/content/en/functions/urls/URLize.md +++ b/content/en/functions/urls/URLize.md @@ -1,6 +1,6 @@ --- title: urls.URLize -description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens. +description: Returns the given string, sanitized for usage in a URL. categories: [] keywords: [] action: @@ -12,53 +12,52 @@ action: aliases: [/functions/urlize] --- -The following examples pull from a content file with the following front matter: +{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} -{{< code-toggle file=content/blog/greatest-city.md fm=true >}} -title = "The World's Greatest City" -location = "Chicago IL" -tags = ["pizza","beer","hot dogs"] +## Example + +Use the `urlize` function to create a link to a [term] page. + +Consider this site configuration: + +{{< code-toggle file=hugo >}} +[taxonomies] +author = 'authors' {{< /code-toggle >}} -The following might be used as a partial within a [single page template][singletemplate]: +And this front matter: -{{< code file=layouts/partials/content-header.html >}} -
-

{{ .Title }}

- {{ with .Params.location }} -
{{ . }}
- {{ end }} - - {{ with .Params.tags }} - - {{ end }} -
-{{< /code >}} +{{< code-toggle file=content/books/les-miserables.md fm=true >}} +title = 'Les Misérables' +authors = ['Victor Hugo'] +{{< /code-toggle >}} -The preceding partial would then output to the rendered page as follows: +The published site will have this structure: -```html -
-

The World's Greatest City

-
Chicago IL
- -
+```text +public/ +├── authors/ +│ ├── victor-hugo/ +│ │ └── index.html +│ └── index.html +├── books/ +│ ├── les-miserables/ +│ │ └── index.html +│ └── index.html +└── index.html ``` -[singletemplate]: /templates/single-page-templates/ +To create a link to the term page: + +```go-html-template +{{ $taxonomy := "authors" }} +{{ $term := "Victor Hugo" }} +{{ with index .Site.Taxonomies $taxonomy (urlize $term) }} + {{ .Page.LinkTitle }} +{{ end }} +``` + +To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object. + +[`GetTerms`]: /methods/page/getterms/ +[term]: /getting-started/glossary/#term diff --git a/content/en/functions/urls/_common/_index.md b/content/en/functions/urls/_common/_index.md new file mode 100644 index 000000000..47d5812fb --- /dev/null +++ b/content/en/functions/urls/_common/_index.md @@ -0,0 +1,13 @@ +--- +cascade: + _build: + list: never + publishResources: false + render: never +--- + + diff --git a/content/en/functions/urls/_common/anchorize-vs-urlize.md b/content/en/functions/urls/_common/anchorize-vs-urlize.md new file mode 100644 index 000000000..0f01bcf78 --- /dev/null +++ b/content/en/functions/urls/_common/anchorize-vs-urlize.md @@ -0,0 +1,35 @@ +--- +# Do not remove front matter. +--- + +The [`anchorize`] and [`urlize`] functions are similar: + +[`anchorize`]: /functions/urls/anchorize +[`urlize`]: /functions/urls/urlize + +- Use the `anchorize` function to generate an HTML `id` attribute value +- Use the `urlize` function to sanitize a string for usage in a URL + +For example: + +```go-html-template +{{ $s := "A B C" }} +{{ $s | anchorize }} → a-b-c +{{ $s | urlize }} → a-b-c + +{{ $s := "a b c" }} +{{ $s | anchorize }} → a-b---c +{{ $s | urlize }} → a-b-c + +{{ $s := "< a, b, & c >" }} +{{ $s | anchorize }} → -a-b--c- +{{ $s | urlize }} → a-b-c + +{{ $s := "main.go" }} +{{ $s | anchorize }} → maingo +{{ $s | urlize }} → main.go + +{{ $s := "Hugö" }} +{{ $s | anchorize }} → hugö +{{ $s | urlize }} → hug%C3%B6 +``` diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 50ca884b0..d80a7e1fb 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -811,20 +811,20 @@ You can override any of these cache settings in your own `hugo.toml`. ### The keywords explained -`:cacheDir` -: See [Configure cacheDir](#configure-cachedir). +cacheDir +: (`string`) See [Configure cacheDir](#configure-cachedir). -`:project` -: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. +project +: (`string`) The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. -`:resourceDir` -: This is the value of the `resourceDir` configuration option. +resourceDir +: (`string`) This is the value of the `resourceDir` configuration option. maxAge -: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). +: (`string`) This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). dir -: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). +: (`string`) The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). ## Configuration format specs diff --git a/content/en/installation/_common/homebrew.md b/content/en/installation/_common/homebrew.md index 61436113e..8d6ff90fc 100644 --- a/content/en/installation/_common/homebrew.md +++ b/content/en/installation/_common/homebrew.md @@ -4,7 +4,7 @@ ### Homebrew -[Homebrew] is a free and open source package manager for macOS and Linux. This will install the extended edition of Hugo: +[Homebrew] is a free and open-source package manager for macOS and Linux. This will install the extended edition of Hugo: ```sh brew install hugo diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md index c2e9328ac..bb8f4b555 100644 --- a/content/en/installation/linux.md +++ b/content/en/installation/linux.md @@ -20,7 +20,7 @@ toc: true ### Snap -[Snap] is a free and open source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated. +[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated. The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that’s deemed always safe. The sites you create and build must be located within your home directory, or on removable media. diff --git a/content/en/installation/macos.md b/content/en/installation/macos.md index 288eb5971..eba977481 100644 --- a/content/en/installation/macos.md +++ b/content/en/installation/macos.md @@ -22,7 +22,7 @@ toc: true ### MacPorts -[MacPorts] is a free and open source package manager for macOS. This will install the extended edition of Hugo: +[MacPorts] is a free and open-source package manager for macOS. This will install the extended edition of Hugo: ```sh sudo port install hugo diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md index 7ac54b6ad..97e767af8 100644 --- a/content/en/installation/windows.md +++ b/content/en/installation/windows.md @@ -20,7 +20,7 @@ toc: true ### Chocolatey -[Chocolatey] is a free and open source package manager for Windows. This will install the extended edition of Hugo: +[Chocolatey] is a free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh choco install hugo-extended @@ -30,7 +30,7 @@ choco install hugo-extended ### Scoop -[Scoop] is a free and open source package manager for Windows. This will install the extended edition of Hugo: +[Scoop] is a free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh scoop install hugo-extended @@ -40,7 +40,7 @@ scoop install hugo-extended ### Winget -[Winget] is Microsoft's official free and open source package manager for Windows. This will install the extended edition of Hugo: +[Winget] is Microsoft's official free and open-source package manager for Windows. This will install the extended edition of Hugo: ```sh winget install Hugo.Hugo.Extended diff --git a/content/en/methods/page/Description.md b/content/en/methods/page/Description.md index 91623d7a0..fbb43b8b5 100644 --- a/content/en/methods/page/Description.md +++ b/content/en/methods/page/Description.md @@ -17,7 +17,7 @@ title = 'How to make spicy tuna hand rolls' description = 'Instructions for making spicy tuna hand rolls.' {{< /code-toggle >}} -{{< code file=layouts/baseof.html lang=go-html-template >}} +{{< code file=layouts/baseof.html >}} ... diff --git a/content/en/methods/page/GetTerms.md b/content/en/methods/page/GetTerms.md index e611af491..3020e4c2e 100644 --- a/content/en/methods/page/GetTerms.md +++ b/content/en/methods/page/GetTerms.md @@ -12,7 +12,7 @@ action: Given this front matter: {{< code-toggle file=content/books/les-miserables.md fm=true >}} -title = 'Les Miserables' +title = 'Les Misérables' tags = ['historical','classic','fiction'] {{< /code-toggle >}} diff --git a/content/en/methods/page/HasShortcode.md b/content/en/methods/page/HasShortcode.md index d142241da..81268ecba 100644 --- a/content/en/methods/page/HasShortcode.md +++ b/content/en/methods/page/HasShortcode.md @@ -31,14 +31,14 @@ the kinetic energy (E) of that body. The shortcode is simple: -{{< code file=layouts/shortcodes/math.html lang=go-html-template >}} +{{< code file=layouts/shortcodes/math.html >}} {{ trim .Inner "\r\n" }} {{< /code >}} Now we can selectively load the required CSS and JavaScript on pages that call the "math" shortcode: -{{< code file=layouts/baseof.html lang=go-html-template >}} +{{< code file=layouts/baseof.html >}} ... {{ if .HasShortcode "math" }} diff --git a/content/en/methods/page/Page.md b/content/en/methods/page/Page.md index edd6d45b3..2c0536bee 100644 --- a/content/en/methods/page/Page.md +++ b/content/en/methods/page/Page.md @@ -11,19 +11,19 @@ action: This is a convenience method, useful within partial templates that are called from both [shortcodes] and page templates. -{{< code file=layouts/shortcodes/foo.html lang=go-html-template >}} +{{< code file=layouts/shortcodes/foo.html >}} {{ partial "my-partial.html" . }} {{< /code >}} When the shortcode calls the partial, it passes the current [context] (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`. -{{< code file=layouts/_default/single.html lang=go-html-template >}} +{{< code file=layouts/_default/single.html >}} {{ partial "my-partial.html" . }} {{< /code >}} When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object. -{{< code file=layouts/partials/my-partial.html lang=go-html-template >}} +{{< code file=layouts/partials/my-partial.html >}} The page title is: {{ .Page.Title }} {{< /code >}} diff --git a/content/en/methods/page/Ref.md b/content/en/methods/page/Ref.md index 2f52a74c1..966ce9f7a 100644 --- a/content/en/methods/page/Ref.md +++ b/content/en/methods/page/Ref.md @@ -27,13 +27,13 @@ The examples below show the rendered output when visiting a page on the English ```go-html-template {{ $opts := dict "path" "/books/book-1" }} -{{ .Ref $opts }} → http://localhost:1314/en/books/book-1/ +{{ .Ref $opts }} → https://example.org/en/books/book-1/ {{ $opts := dict "path" "/books/book-1" "lang" "de" }} -{{ .Ref $opts }} → http://localhost:1314/de/books/book-1/ +{{ .Ref $opts }} → https://example.org/de/books/book-1/ {{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} -{{ .Ref $opts }} → http://localhost:1314/de/books/book-1/index.json +{{ .Ref $opts }} → https://example.org/de/books/book-1/index.json ``` By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. diff --git a/content/en/methods/pages/Related.md b/content/en/methods/pages/Related.md index 86ee0d281..1fc6102be 100644 --- a/content/en/methods/pages/Related.md +++ b/content/en/methods/pages/Related.md @@ -17,7 +17,7 @@ Based on front matter, Hugo uses several factors to identify content related to The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page: -{{< code file=layouts/_default/single.html lang=go-html-template >}} +{{< code file=layouts/_default/single.html >}} {{ with .Site.RegularPages.Related . | first 5 }}

Related pages: