mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 15:28:54 +00:00
Miscellaneous edits
This commit is contained in:
Joe Mooring
@@ -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 >}}
|
||||
<dl>
|
||||
{{ range .Pages }}
|
||||
<dt>{{ .Title }}</dt>
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 */*/>}}
|
||||
{{%/*/* foo */*/%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```text
|
||||
{{</* foo */>}}
|
||||
{{%/* foo */%}}
|
||||
```
|
||||
|
||||
### Site configuration
|
||||
|
||||
Use the [code-toggle shortcode] to include site configuration examples:
|
||||
|
||||
```text
|
||||
{{</* code-toggle file=hugo */>}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-US'
|
||||
title = 'My Site'
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
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
|
||||
{{</* 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 */>}}
|
||||
```
|
||||
|
||||
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
|
||||
{{</* code file=layouts/_default/single.html */>}}
|
||||
{{ range .Site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{</* /code */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ range .Site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ 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 */*/>}}`\
|
||||
`{{%/*/* 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
|
||||
{{</* code file=layouts/_default_/single.html */>}}
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
{{ end }}
|
||||
{{</* /code */>}}
|
||||
|
||||
````
|
||||
|
||||
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
|
||||
{{</* code-toggle file=hugo */>}}
|
||||
baseURL = 'https://example.org'
|
||||
languageCode = 'en-US'
|
||||
title = "Example Site"
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org'
|
||||
languageCode = 'en-US'
|
||||
title = "Example Site"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Front matter example
|
||||
|
||||
```text
|
||||
{{</* code-toggle file=content/about.md fm=true */>}}
|
||||
title = "About"
|
||||
date = 2023-04-02T12:47:24-07:00
|
||||
draft = false
|
||||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 }};
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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]
|
||||
---
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 %}}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 %}}
|
||||
|
||||
|
||||
@@ -14,7 +14,3 @@ aliases: [/functions/plainify]
|
||||
```go-html-template
|
||||
{{ "<b>BatMan</b>" | plainify }} → BatMan
|
||||
```
|
||||
|
||||
See also the `.PlainWords`, `.Plain`, and `.RawContent` [page variables][pagevars].
|
||||
|
||||
[pagevars]: /variables/page/
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 >}}
|
||||
<header>
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.location }}
|
||||
<div><a href="/locations/{{ . | urlize }}">{{ . }}</a></div>
|
||||
{{ end }}
|
||||
<!-- Creates a list of tags for the content and links to each of their pages -->
|
||||
{{ with .Params.tags }}
|
||||
<ul>
|
||||
{{ range .}}
|
||||
<li>
|
||||
<a href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
</header>
|
||||
{{< /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
|
||||
<header>
|
||||
<h1>The World's Greatest City</h1>
|
||||
<div><a href="/locations/chicago-il">Chicago IL</a></div>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="/tags/pizza">pizza</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/tags/beer">beer</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/tags/hot-dogs">hot dogs</a>
|
||||
</li>
|
||||
</ul>
|
||||
</header>
|
||||
```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) }}
|
||||
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
|
||||
{{ 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
|
||||
|
||||
@@ -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.
|
||||
-->
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 >}}
|
||||
<head>
|
||||
...
|
||||
<meta name="description" content="{{ .Description }}">
|
||||
|
||||
@@ -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 >}}
|
||||
|
||||
|
||||
@@ -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 >}}
|
||||
<head>
|
||||
...
|
||||
{{ if .HasShortcode "math" }}
|
||||
|
||||
@@ -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 >}}
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 }}
|
||||
<p>Related pages:</p>
|
||||
<ul>
|
||||
@@ -30,7 +30,7 @@ The argument passed to the `Related` method may be a `Page` or an options map. F
|
||||
|
||||
To pass an options map:
|
||||
|
||||
{{< code file=layouts/_default/single.html lang=go-html-template >}}
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ $opts := dict
|
||||
"document" .
|
||||
"indices" (slice "tags" "keywords")
|
||||
|
||||
@@ -34,7 +34,7 @@ content/
|
||||
|
||||
With the structure above, we can range through page resources of type `page` to build content:
|
||||
|
||||
{{< code file=layouts/lessons/single.html lang=go-html-template >}}
|
||||
{{< code file=layouts/lessons/single.html >}}
|
||||
{{ range .Resources.ByType "page" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
|
||||
@@ -28,7 +28,7 @@ This shortcode call uses positional parameters:
|
||||
|
||||
To retrieve parameters by position:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
|
||||
{{< /code >}}
|
||||
|
||||
@@ -42,7 +42,7 @@ This shortcode call uses named parameters:
|
||||
|
||||
To retrieve parameters by name:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ We design the **best** widgets in the world.
|
||||
|
||||
With this shortcode:
|
||||
|
||||
{{< code file=layouts/shortcodes/card.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/card.html >}}
|
||||
<div class="card">
|
||||
{{ with .Get "title" }}
|
||||
<div class="card-title">{{ . }}</div>
|
||||
@@ -62,7 +62,7 @@ Let's modify the example above to pass the value returned by `Inner` through the
|
||||
|
||||
[`RenderString`]: /methods/page/renderstring
|
||||
|
||||
{{< code file=layouts/shortcodes/card.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/card.html >}}
|
||||
<div class="card">
|
||||
{{ with .Get "title" }}
|
||||
<div class="card-title">{{ . }}</div>
|
||||
@@ -112,7 +112,7 @@ This configuration is not unsafe if _you_ control the content. Read more about H
|
||||
|
||||
Second, because we are rendering the entire shortcode as markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
|
||||
|
||||
{{< code file=layouts/shortcodes/card.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/card.html >}}
|
||||
<div class="card">
|
||||
{{ with .Get "title" }}
|
||||
<div class="card-title">{{ . }}</div>
|
||||
|
||||
@@ -36,7 +36,7 @@ In the example above, notice that the content between the opening and closing sh
|
||||
|
||||
With this shortcode, calling `Inner` instead of `InnerDeindent`:
|
||||
|
||||
{{< code file=layouts/shortcodes/gallery.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/gallery.html >}}
|
||||
<div class="gallery">
|
||||
{{ trim .Inner "\r\n" | .Page.RenderString }}
|
||||
</div>
|
||||
@@ -67,7 +67,7 @@ Hugo renders the markdown to:
|
||||
|
||||
Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method:
|
||||
|
||||
{{< code file=layouts/shortcodes/gallery.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/gallery.html >}}
|
||||
<div class="gallery">
|
||||
{{ trim .InnerDeindent "\r\n" | .Page.RenderString }}
|
||||
</div>
|
||||
|
||||
@@ -14,7 +14,7 @@ To support both positional and named parameters when calling a shortcode, use th
|
||||
|
||||
With this shortcode template:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ if .IsNamedParams }}
|
||||
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
|
||||
{{ else }}
|
||||
|
||||
@@ -13,7 +13,7 @@ action:
|
||||
|
||||
The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ $greeting := "" }}
|
||||
{{ with .Get "greeting" }}
|
||||
{{ $greeting = . }}
|
||||
|
||||
@@ -21,7 +21,7 @@ This method is useful for, among other things, assigning unique element IDs when
|
||||
|
||||
This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
|
||||
|
||||
{{< code file=layouts/shortcodes/img.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/img.html >}}
|
||||
{{ $src := "" }}
|
||||
{{ with .Get "src" }}
|
||||
{{ $src = . }}
|
||||
|
||||
@@ -26,7 +26,7 @@ Calling this shortcode:
|
||||
|
||||
We can access the front matter values using the `Page` method:
|
||||
|
||||
{{< code file=layouts/shortcodes/book-details.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/book-details.html >}}
|
||||
<ul>
|
||||
<li>Title: {{ .Page.Title }}</li>
|
||||
<li>Author: {{ .Page.Params.author }}</li>
|
||||
|
||||
@@ -16,7 +16,7 @@ When you call a shortcode using positional parameters, the `Params` method retur
|
||||
{{</* myshortcode "Hello" "world" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ index .Params 0 }} → Hello
|
||||
{{ index .Params 1 }} → world
|
||||
{{< /code >}}
|
||||
@@ -27,7 +27,7 @@ When you call a shortcode using named parameters, the `Params` method returns a
|
||||
{{</* myshortcode greeting="Hello" name="world" */>}}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ .Params.greeting }} → Hello
|
||||
{{ .Params.name }} → world
|
||||
{{< /code >}}
|
||||
|
||||
@@ -19,13 +19,13 @@ Welcome. Today is {{</* now */>}}.
|
||||
{{</* /greeting */>}}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/shortcodes/greeting.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/greeting.html >}}
|
||||
<div class="greeting">
|
||||
{{ trim .Inner "\r\n" | .Page.RenderString }}
|
||||
</div>
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/shortcodes/now.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/now.html >}}
|
||||
{{- $dateFormat := "January 2, 2006 15:04:05" }}
|
||||
|
||||
{{- with .Params }}
|
||||
|
||||
@@ -13,7 +13,7 @@ action:
|
||||
|
||||
The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter:
|
||||
|
||||
{{< code file=layouts/shortcodes/myshortcode.html lang=go-html-template >}}
|
||||
{{< code file=layouts/shortcodes/myshortcode.html >}}
|
||||
{{ $greeting := "" }}
|
||||
{{ with .Get "greeting" }}
|
||||
{{ $greeting = . }}
|
||||
@@ -29,5 +29,5 @@ ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/us
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The position can relatively expensive to calculate. Limit its use to error reporting.
|
||||
The position can be expensive to calculate. Limit its use to error reporting.
|
||||
{{% /note %}}
|
||||
|
||||
@@ -34,7 +34,7 @@ To capture the "genres" taxonomy object from within any template, use the [`Taxo
|
||||
|
||||
To capture the "genres" taxonomy object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object:
|
||||
|
||||
{{< code file=layouts/_default/taxonomy.html lang=go-html-template >}}
|
||||
{{< code file=layouts/_default/taxonomy.html >}}
|
||||
{{ $taxonomyObject := .Data.Terms }}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
@@ -38,7 +38,7 @@ To process an emoji shortcode from within a template, use the [`emojify`] functi
|
||||
|
||||
## Introduction
|
||||
|
||||
This quick reference guide was automatically generated from [GitHub Emoji API] and [Unicode Full Emoji List]. Specials thanks to [@ikatyang] for making [this list] available to the open source community.
|
||||
This quick reference guide was automatically generated from [GitHub Emoji API] and [Unicode Full Emoji List]. Specials thanks to [@ikatyang] for making [this list] available to the open-source community.
|
||||
|
||||
GitHub [custom emoji] are not supported.
|
||||
|
||||
|
||||
@@ -85,40 +85,40 @@ The above example is fictional, but if used for the homepage on a site with `bas
|
||||
|
||||
The following is the full list of configuration options for output formats and their default values:
|
||||
|
||||
`name`
|
||||
name
|
||||
: the output format identifier. This is used to define what output format(s) you want for your pages.
|
||||
|
||||
`mediaType`
|
||||
mediaType
|
||||
: this must match the `Type` of a defined media type.
|
||||
|
||||
`path`
|
||||
path
|
||||
: sub path to save the output files.
|
||||
|
||||
`baseName`
|
||||
baseName
|
||||
: the base file name for the list file names (homepage, etc.). **Default:** `index`.
|
||||
|
||||
`rel`
|
||||
rel
|
||||
: can be used to create `rel` values in `link` tags. **Default:** `alternate`.
|
||||
|
||||
`protocol`
|
||||
protocol
|
||||
: will replace the "http://" or "https://" in your `baseURL` for this output format.
|
||||
|
||||
`isPlainText`
|
||||
isPlainText
|
||||
: use Go's plain text templates parser for the templates. **Default:** `false`.
|
||||
|
||||
`isHTML`
|
||||
isHTML
|
||||
: used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
|
||||
|
||||
`noUgly`
|
||||
noUgly
|
||||
: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`.
|
||||
|
||||
`notAlternative`
|
||||
notAlternative
|
||||
: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term _alternative_ and not _alternate_ here, as it does not necessarily replace the other format. **Default:** `false`.
|
||||
|
||||
`permalinkable`
|
||||
permalinkable
|
||||
: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`.
|
||||
|
||||
`weight`
|
||||
weight
|
||||
: Setting this to a non-zero value will be used as the first sort criteria.
|
||||
|
||||
## Output formats for pages
|
||||
|
||||
@@ -18,10 +18,10 @@ The real power of Hugo pagination shines when combined with the [`where`] functi
|
||||
|
||||
Pagination can be configured in your [site configuration][configuration]:
|
||||
|
||||
`paginate`
|
||||
paginate
|
||||
: default = `10`. This setting can be overridden within the template.
|
||||
|
||||
`paginatePath`
|
||||
paginatePath
|
||||
: default = `page`. Allows you to set a different path for your pagination pages.
|
||||
|
||||
Setting `paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
|
||||
@@ -93,46 +93,46 @@ Without the `where` filter, the above example is even simpler:
|
||||
|
||||
If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties:
|
||||
|
||||
`PageNumber`
|
||||
PageNumber
|
||||
: The current page's number in the pager sequence
|
||||
|
||||
`URL`
|
||||
URL
|
||||
: The relative URL to the current pager
|
||||
|
||||
`Pages`
|
||||
Pages
|
||||
: The pages in the current pager
|
||||
|
||||
`NumberOfElements`
|
||||
NumberOfElements
|
||||
: The number of elements on this page
|
||||
|
||||
`HasPrev`
|
||||
HasPrev
|
||||
: Whether there are page(s) before the current
|
||||
|
||||
`Prev`
|
||||
Prev
|
||||
: The pager for the previous page
|
||||
|
||||
`HasNext`
|
||||
HasNext
|
||||
: Whether there are page(s) after the current
|
||||
|
||||
`Next`
|
||||
Next
|
||||
: The pager for the next page
|
||||
|
||||
`First`
|
||||
First
|
||||
: The pager for the first page
|
||||
|
||||
`Last`
|
||||
Last
|
||||
: The pager for the last page
|
||||
|
||||
`Pagers`
|
||||
Pagers
|
||||
: A list of pagers that can be used to build a pagination menu
|
||||
|
||||
`PageSize`
|
||||
PageSize
|
||||
: Size of each pager
|
||||
|
||||
`TotalPages`
|
||||
TotalPages
|
||||
: The number of pages in the paginator
|
||||
|
||||
`TotalNumberOfElements`
|
||||
TotalNumberOfElements
|
||||
: The number of elements on all pages in this paginator
|
||||
|
||||
## Additional information
|
||||
|
||||
@@ -118,13 +118,13 @@ Any shortcode that refers to `.Inner` must be closed or self-closed.
|
||||
|
||||
The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
|
||||
|
||||
`$.Params`
|
||||
$.Params
|
||||
: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
|
||||
|
||||
`$.Page.Params`
|
||||
$.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`
|
||||
$.Page.Site.Params
|
||||
: refers to global variables as defined in your [site's configuration file][config].
|
||||
|
||||
#### `.IsNamedParams`
|
||||
|
||||
@@ -24,7 +24,7 @@ aliases: [/tools/frontends/]
|
||||
## Open source
|
||||
|
||||
[Decap CMS](https://decapcms.org/)
|
||||
: Decap CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
|
||||
: Decap CMS is an open-source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
|
||||
|
||||
[Sveltia CMS](https://github.com/sveltia/sveltia-cms/)
|
||||
: Sveltia CMS is a drop-in replacement for Decap CMS which is built from the ground up with powerful and performant modern UI library Svelte. Sveltia CMS incorporates i18n into every corner of the product, while striving to radically improve UX, performance and productivity.
|
||||
|
||||
Reference in New Issue
Block a user