mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Squashed 'docs/' changes from 0f2bf195e..13097daf2
13097daf2 Update shortcode docs vs 0.55 9a7e19231 Update URL docs for relative URLs etc bd58dd877 Adjust Output Formats docs f3e9fbc00 Document output format `permalinkable` 3778ce689 Update partials.md 7b207a404 Partial: Update variable name in example 7d7b1f03c Document partials returning a value. 7ae93b7ca Merge branch 'temp552' 81910d266 releaser: Add release notes to /docs for release of 0.55.2 c166cef47 Fix typo 23adeb672 Point mmark links to its new repository 369a87339 Merge branch 'temp551' eb6097e9f Bump to 0.55.1 766ee61a8 releaser: Add release notes to /docs for release of 0.55.1 a5a5f5d75 Start of taxonomy docs update for Hugo 0.55 fb5f75e9a Remove the space in `. RelPermalink` git-subtree-dir: docs git-subtree-split: 13097daf2e22fabfdb7528ca8709e86dba2b4a72
This commit is contained in:
Bjørn Erik Pedersen
parent
8b73644d81
commit
a0c28c943c
13 changed files with 265 additions and 100 deletions
|
|
@ -100,7 +100,7 @@ Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as pr
|
||||||
|
|
||||||
## Mmark
|
## Mmark
|
||||||
|
|
||||||
Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmarkgh] or the full syntax on [Miek Gieben's website][].
|
Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmark] or the full syntax on [Miek Gieben's website][].
|
||||||
|
|
||||||
### Use Mmark
|
### Use Mmark
|
||||||
|
|
||||||
|
|
@ -253,8 +253,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
|
||||||
[mdguide]: https://www.markdownguide.org/
|
[mdguide]: https://www.markdownguide.org/
|
||||||
[mdtutorial]: http://www.markdowntutorial.com/
|
[mdtutorial]: http://www.markdowntutorial.com/
|
||||||
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
|
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
|
||||||
[mmark]: https://github.com/miekg/mmark
|
[mmark]: https://github.com/mmarkdown/mmark
|
||||||
[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
|
|
||||||
[org]: http://orgmode.org/
|
[org]: http://orgmode.org/
|
||||||
[pandoc]: http://www.pandoc.org/
|
[pandoc]: http://www.pandoc.org/
|
||||||
[Pygments]: http://pygments.org/
|
[Pygments]: http://pygments.org/
|
||||||
|
|
|
||||||
|
|
@ -53,12 +53,15 @@ The examples above use two different delimiters, the difference being the `%` ch
|
||||||
|
|
||||||
### Shortcodes with Markdown
|
### Shortcodes with Markdown
|
||||||
|
|
||||||
The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
|
In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.
|
||||||
|
|
||||||
|
If you want the old behavior, you can put the following line in the start of your shortcode template:
|
||||||
|
|
||||||
```
|
```
|
||||||
{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
|
{{ $_hugo_config := `{ "version": 1 }` }}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
### Shortcodes Without Markdown
|
### Shortcodes Without Markdown
|
||||||
|
|
||||||
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
|
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
|
||||||
|
|
|
||||||
|
|
@ -135,24 +135,16 @@ If you want to have just the default `tags` taxonomy, and remove the `categories
|
||||||
|
|
||||||
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
|
If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
|
||||||
|
|
||||||
### Preserve Taxonomy Values
|
|
||||||
|
|
||||||
By default, taxonomy names are normalized.
|
|
||||||
|
|
||||||
Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site config][config]. Hugo will then preserve special characters in taxonomy values but will still normalize them in URLs.
|
|
||||||
|
|
||||||
Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][].
|
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
|
You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
|
||||||
|
|
||||||
Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
|
Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
{{% warning "`preserveTaxonomyNames` behaviour change" %}}
|
{{% warning %}}
|
||||||
Before 0.49, Hugo would make the first character upper case for the taxonomy values for titles even if `preserveTaxonomyNames` was active. This no longer the case, which (for instance) makes it possible to have fully lower-case values.
|
The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
|
||||||
|
|
||||||
If you actually need to title-ize these values, you can do so using the `strings.FirstUpper` template function.
|
You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
|
||||||
{{% /warning %}}
|
{{% /warning %}}
|
||||||
|
|
||||||
## Add Taxonomies to Content
|
## Add Taxonomies to Content
|
||||||
|
|
|
||||||
|
|
@ -84,7 +84,6 @@ The following is a list of values that can be used in a `permalink` definition i
|
||||||
|
|
||||||
Aliases can be used to create redirects to your page from other URLs.
|
Aliases can be used to create redirects to your page from other URLs.
|
||||||
|
|
||||||
|
|
||||||
Aliases comes in two forms:
|
Aliases comes in two forms:
|
||||||
|
|
||||||
1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
|
1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
|
||||||
|
|
@ -130,6 +129,8 @@ aliases:
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
|
From Hugo 0.55 you can also have page-relative aliases, so ` /es/posts/my-original-post/` can be simplified to the more portable `my-original-post/`
|
||||||
|
|
||||||
### How Hugo Aliases Work
|
### How Hugo Aliases Work
|
||||||
|
|
||||||
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
|
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
|
||||||
|
|
@ -257,12 +258,29 @@ Or, if you are on Windows and do not have `grep` installed:
|
||||||
hugo config | FINDSTR /I canon
|
hugo config | FINDSTR /I canon
|
||||||
```
|
```
|
||||||
|
|
||||||
## Override URLs with Front Matter
|
## Set URL in Front Matter
|
||||||
|
|
||||||
In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
|
In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
|
||||||
|
|
||||||
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
|
Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
|
||||||
|
|
||||||
|
From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Custom URL!"
|
||||||
|
url: "/jp/custom/foo"
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Custom URL!"
|
||||||
|
url: "custom/foo"
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
## Relative URLs
|
## Relative URLs
|
||||||
|
|
||||||
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
|
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
|
||||||
|
|
|
||||||
|
|
@ -211,9 +211,6 @@ permalinks
|
||||||
pluralizeListTitles (true)
|
pluralizeListTitles (true)
|
||||||
: Pluralize titles in lists.
|
: Pluralize titles in lists.
|
||||||
|
|
||||||
preserveTaxonomyNames (false)
|
|
||||||
: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
|
|
||||||
|
|
||||||
publishDir ("public")
|
publishDir ("public")
|
||||||
: The directory to where Hugo will write the final static site (the HTML files etc.).
|
: The directory to where Hugo will write the final static site (the HTML files etc.).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -43,7 +43,6 @@ Usage:
|
||||||
hugo [command]
|
hugo [command]
|
||||||
|
|
||||||
Available Commands:
|
Available Commands:
|
||||||
benchmark Benchmark Hugo by building a site a number of times.
|
|
||||||
check Contains some verification checks
|
check Contains some verification checks
|
||||||
config Print the site configuration
|
config Print the site configuration
|
||||||
convert Convert your content to different formats
|
convert Convert your content to different formats
|
||||||
|
|
@ -57,43 +56,43 @@ Available Commands:
|
||||||
version Print the version number of Hugo
|
version Print the version number of Hugo
|
||||||
|
|
||||||
Flags:
|
Flags:
|
||||||
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
|
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
|
||||||
-D, --buildDrafts include content marked as draft
|
-D, --buildDrafts include content marked as draft
|
||||||
-E, --buildExpired include expired content
|
-E, --buildExpired include expired content
|
||||||
-F, --buildFuture include content with publishdate in the future
|
-F, --buildFuture include content with publishdate in the future
|
||||||
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
|
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
|
||||||
--canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL
|
--cleanDestinationDir remove files from destination not found in static directories
|
||||||
--cleanDestinationDir remove files from destination not found in static directories
|
--config string config file (default is path/config.yaml|json|toml)
|
||||||
--config string config file (default is path/config.yaml|json|toml)
|
--configDir string config dir (default "config")
|
||||||
-c, --contentDir string filesystem path to content directory
|
-c, --contentDir string filesystem path to content directory
|
||||||
--debug debug output
|
--debug debug output
|
||||||
-d, --destination string filesystem path to write files to
|
-d, --destination string filesystem path to write files to
|
||||||
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
|
--disableKinds strings disable different kind of pages (home, RSS etc.)
|
||||||
--enableGitInfo add Git revision, date and author info to the pages
|
--enableGitInfo add Git revision, date and author info to the pages
|
||||||
--forceSyncStatic copy all files when static is changed.
|
-e, --environment string build environment
|
||||||
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
--forceSyncStatic copy all files when static is changed.
|
||||||
-h, --help help for hugo
|
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
||||||
--i18n-warnings print missing translations
|
-h, --help help for hugo
|
||||||
--ignoreCache ignores the cache directory
|
--i18n-warnings print missing translations
|
||||||
-l, --layoutDir string filesystem path to layout directory
|
--ignoreCache ignores the cache directory
|
||||||
--log enable Logging
|
-l, --layoutDir string filesystem path to layout directory
|
||||||
--logFile string log File path (if set, logging enabled automatically)
|
--log enable Logging
|
||||||
--noChmod don't sync permission mode of files
|
--logFile string log File path (if set, logging enabled automatically)
|
||||||
--noTimes don't sync modification time of files
|
--minify minify any supported output format (HTML, XML etc.)
|
||||||
--pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true)
|
--noChmod don't sync permission mode of files
|
||||||
--preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
|
--noTimes don't sync modification time of files
|
||||||
--quiet build in quiet mode
|
--path-warnings print warnings on duplicate target paths etc.
|
||||||
--renderToMemory render to memory (only useful for benchmark testing)
|
--quiet build in quiet mode
|
||||||
-s, --source string filesystem path to read files relative from
|
--renderToMemory render to memory (only useful for benchmark testing)
|
||||||
--stepAnalysis display memory and timing of different steps of the program
|
-s, --source string filesystem path to read files relative from
|
||||||
--templateMetrics display metrics about template executions
|
--templateMetrics display metrics about template executions
|
||||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||||
-t, --theme string theme to use (located in /themes/THEMENAME/)
|
-t, --theme strings themes to use (located in /themes/THEMENAME/)
|
||||||
--themesDir string filesystem path to themes directory
|
--themesDir string filesystem path to themes directory
|
||||||
--uglyURLs (deprecated) if true, use /filename.html instead of /filename/
|
--trace file write trace to file (not useful in general)
|
||||||
-v, --verbose verbose output
|
-v, --verbose verbose output
|
||||||
--verboseLog verbose logging
|
--verboseLog verbose logging
|
||||||
-w, --watch watch filesystem for changes and recreate as needed
|
-w, --watch watch filesystem for changes and recreate as needed
|
||||||
|
|
||||||
Use "hugo [command] --help" for more information about a command.
|
Use "hugo [command] --help" for more information about a command.
|
||||||
```
|
```
|
||||||
|
|
|
||||||
53
content/en/news/0.55.1-relnotes/index.md
Normal file
53
content/en/news/0.55.1-relnotes/index.md
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
|
||||||
|
---
|
||||||
|
date: 2019-04-12
|
||||||
|
title: "0.55.1: 3 Bug Fixes"
|
||||||
|
description: "Fixes 3 issues introduced in 0.55.0."
|
||||||
|
categories: ["Releases"]
|
||||||
|
images:
|
||||||
|
- images/blog/hugo-bug-poster.png
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
This is a bug-fix release with a couple of important fixes.
|
||||||
|
|
||||||
|
|
||||||
|
Hugo now has:
|
||||||
|
|
||||||
|
* 34225+ [stars](https://github.com/gohugoio/hugo/stargazers)
|
||||||
|
* 439+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
|
||||||
|
* 307+ [themes](http://themes.gohugo.io/)
|
||||||
|
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
* Replace deprecated .GetParam usage [27a8049d](https://github.com/gohugoio/hugo/commit/27a8049da7996b703d02083182b84a002eae2599) [@bep](https://github.com/bep) [#5834](https://github.com/gohugoio/hugo/issues/5834)
|
||||||
|
|
||||||
|
## Enhancements
|
||||||
|
|
||||||
|
### Core
|
||||||
|
|
||||||
|
* Add a test for parent's resources in shortcode [8d7607ae](https://github.com/gohugoio/hugo/commit/8d7607aed10b3fe7373126ff5fa7dae36c559d7f) [@bep](https://github.com/bep) [#5833](https://github.com/gohugoio/hugo/issues/5833)
|
||||||
|
|
||||||
|
### Other
|
||||||
|
|
||||||
|
* Remove the space in `. RelPermalink` [7966c0b5](https://github.com/gohugoio/hugo/commit/7966c0b5b7b2297527f8be9040b793de5e4e3f48) [@yihui](https://github.com/yihui)
|
||||||
|
|
||||||
|
## Fixes
|
||||||
|
|
||||||
|
### Core
|
||||||
|
|
||||||
|
* Fix simple menu config [9e9a1f92](https://github.com/gohugoio/hugo/commit/9e9a1f92baf151f8d840d6b5b963945d1410ce25) [@bep](https://github.com/bep)
|
||||||
|
|
||||||
|
### Other
|
||||||
|
|
||||||
|
* Fix [4d425a86](https://github.com/gohugoio/hugo/commit/4d425a86f5c03a5cca27d4e0f99d61acbb938d80) [@bep](https://github.com/bep)
|
||||||
|
* Fix paginator refresh on server change [f7375c49](https://github.com/gohugoio/hugo/commit/f7375c497239115cd30ae42af6b4d298e4e7ad7d) [@bep](https://github.com/bep) [#5838](https://github.com/gohugoio/hugo/issues/5838)
|
||||||
|
* Fix .RSSLinke deprecation message [3b86b4a9](https://github.com/gohugoio/hugo/commit/3b86b4a9f5ce010c9714d813d5b8ecddda22c69f) [@bep](https://github.com/bep) [#4427](https://github.com/gohugoio/hugo/issues/4427)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
51
content/en/news/0.55.2-relnotes/index.md
Normal file
51
content/en/news/0.55.2-relnotes/index.md
Normal file
|
|
@ -0,0 +1,51 @@
|
||||||
|
|
||||||
|
---
|
||||||
|
date: 2019-04-17
|
||||||
|
title: "Hugo 0.55.2: Some Important Bug Fixes"
|
||||||
|
description: "Fixes some more issues introduced in Hugo 0.55.0."
|
||||||
|
categories: ["Releases"]
|
||||||
|
images:
|
||||||
|
- images/blog/hugo-bug-poster.png
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
This is a bug-fix release with a couple of important fixes.
|
||||||
|
|
||||||
|
|
||||||
|
Hugo now has:
|
||||||
|
|
||||||
|
* 34386+ [stars](https://github.com/gohugoio/hugo/stargazers)
|
||||||
|
* 439+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
|
||||||
|
* 307+ [themes](http://themes.gohugo.io/)
|
||||||
|
|
||||||
|
## Enhancements
|
||||||
|
|
||||||
|
### Templates
|
||||||
|
|
||||||
|
* Handle late transformation of templates [2957795f](https://github.com/gohugoio/hugo/commit/2957795f5276cc9bc8d438da2d7d9b61defea225) [@bep](https://github.com/bep) [#5865](https://github.com/gohugoio/hugo/issues/5865)
|
||||||
|
|
||||||
|
### Core
|
||||||
|
|
||||||
|
* Add more tests for Permalinkable [35f41834](https://github.com/gohugoio/hugo/commit/35f41834ea3a8799b9b7eda360cf8d30b1b727ba) [@bep](https://github.com/bep) [#5849](https://github.com/gohugoio/hugo/issues/5849)
|
||||||
|
|
||||||
|
## Fixes
|
||||||
|
|
||||||
|
### Core
|
||||||
|
|
||||||
|
* Fix Pages reinitialization on rebuilds [9b17cbb6](https://github.com/gohugoio/hugo/commit/9b17cbb62a056ea7e26b1146cbf3ba42f5acf805) [@bep](https://github.com/bep) [#5833](https://github.com/gohugoio/hugo/issues/5833)
|
||||||
|
* Fix shortcode namespace issue [56550d1e](https://github.com/gohugoio/hugo/commit/56550d1e449f45ebee398ac8a9e3b9818b3ee60e) [@bep](https://github.com/bep) [#5863](https://github.com/gohugoio/hugo/issues/5863)
|
||||||
|
* Fix false WARNINGs in lang prefix check [7881b096](https://github.com/gohugoio/hugo/commit/7881b0965f8b83d03379e9ed102cd0c3bce297e2) [@bep](https://github.com/bep) [#5860](https://github.com/gohugoio/hugo/issues/5860)
|
||||||
|
* Fix bundle resource publishing when multiple output formats [49d0a826](https://github.com/gohugoio/hugo/commit/49d0a82641581aa7dd66b9d5e8c7d75e23260083) [@bep](https://github.com/bep) [#5858](https://github.com/gohugoio/hugo/issues/5858)
|
||||||
|
* Fix panic for unused taxonomy content files [b799b12f](https://github.com/gohugoio/hugo/commit/b799b12f4a693dfeae8a5a362f131081a727bb8f) [@bep](https://github.com/bep) [#5847](https://github.com/gohugoio/hugo/issues/5847)
|
||||||
|
* Fix dates for sections with dates in front matter [70148672](https://github.com/gohugoio/hugo/commit/701486728e21bc0c6c78c2a8edb988abdf6116c7) [@bep](https://github.com/bep) [#5854](https://github.com/gohugoio/hugo/issues/5854)
|
||||||
|
|
||||||
|
### Other
|
||||||
|
|
||||||
|
* Fix WeightedPages in union etc. [f2795d4d](https://github.com/gohugoio/hugo/commit/f2795d4d2cef30170af43327f3ff7114923833b1) [@bep](https://github.com/bep) [#5850](https://github.com/gohugoio/hugo/issues/5850)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -68,7 +68,7 @@ Given a media type and some additional configuration, you get an **Output Format
|
||||||
|
|
||||||
This is the full set of Hugo's built-in output formats:
|
This is the full set of Hugo's built-in output formats:
|
||||||
|
|
||||||
{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly">}}
|
{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
|
||||||
|
|
||||||
* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
|
* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
|
||||||
* The `MediaType` must match the `Type` of an already defined media type.
|
* The `MediaType` must match the `Type` of an already defined media type.
|
||||||
|
|
@ -120,6 +120,9 @@ The following is the full list of configuration options for output formats and t
|
||||||
`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`.
|
: 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`
|
||||||
|
: 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`.
|
||||||
|
|
||||||
## Output Formats for Pages
|
## Output Formats for Pages
|
||||||
|
|
||||||
A `Page` in Hugo can be rendered to multiple *output formats* on the file
|
A `Page` in Hugo can be rendered to multiple *output formats* on the file
|
||||||
|
|
@ -173,7 +176,7 @@ outputs:
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
## Link to Output Formats
|
## List Output formats
|
||||||
|
|
||||||
Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
|
Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
|
||||||
|
|
||||||
|
|
@ -183,13 +186,26 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
|
||||||
{{ end -}}
|
{{ end -}}
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that `.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined).
|
## Link to Output Formats
|
||||||
|
|
||||||
This is how you link to a given output format:
|
`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from.
|
||||||
|
|
||||||
|
__from `single.json.json`:__
|
||||||
|
```go-html-template
|
||||||
|
{{ .RelPermalink }} > /that-page/
|
||||||
|
{{ with .OutputFormats.Get "json" -}}
|
||||||
|
{{ .RelPermalink }} > /that-page/index.json
|
||||||
|
{{- end }}
|
||||||
|
```
|
||||||
|
|
||||||
|
In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true.
|
||||||
|
|
||||||
|
__Same template file as above with json output format's `permalinkable` set to true:__
|
||||||
|
|
||||||
```go-html-template
|
```go-html-template
|
||||||
{{ with .OutputFormats.Get "json" -}}
|
{{ .RelPermalink }} > /that-page/index.json
|
||||||
<a href="{{ .Permalink }}">{{ .Name }}</a>
|
{{ with .OutputFormats.Get "html" -}}
|
||||||
|
{{ .RelPermalink }} > /that-page/
|
||||||
{{- end }}
|
{{- end }}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -77,7 +77,47 @@ The second argument in a partial call is the variable being passed down. The abo
|
||||||
|
|
||||||
This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
|
This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
|
||||||
|
|
||||||
### Cached Partials
|
## Returning a value from a Partial
|
||||||
|
|
||||||
|
In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement.
|
||||||
|
|
||||||
|
### Example GetFeatured
|
||||||
|
```go-html-template
|
||||||
|
{{/* layouts/partials/GetFeatured.html */}}
|
||||||
|
{{ return first . (where site.RegularPages ".Params.featured" true) }}
|
||||||
|
```
|
||||||
|
|
||||||
|
```go-html-template
|
||||||
|
{{/* layouts/index.html */}}
|
||||||
|
{{ range partial "GetFeatured.html" 5 }}
|
||||||
|
[...]
|
||||||
|
{{ end }}
|
||||||
|
```
|
||||||
|
### Example GetImage
|
||||||
|
```go-html-template
|
||||||
|
{{/* layouts/partials/GetImage.html */}}
|
||||||
|
{{ $image := false }}
|
||||||
|
{{ with .Params.gallery }}
|
||||||
|
{{ $image = index . 0 }}
|
||||||
|
{{ end }}
|
||||||
|
{{ with .Params.image }}
|
||||||
|
{{ $image = . }}
|
||||||
|
{{ end }}
|
||||||
|
{{ return $image }}
|
||||||
|
```
|
||||||
|
|
||||||
|
```go-html-template
|
||||||
|
{{/* layouts/_default/single.html */}}
|
||||||
|
{{ with partial "GetImage.html" . }}
|
||||||
|
[...]
|
||||||
|
{{ end }}
|
||||||
|
```
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
Only one `return` statement is allowed per partial file.
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
## Cached Partials
|
||||||
|
|
||||||
The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows:
|
The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -124,6 +124,18 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
||||||
|
|
||||||
### Order Alphabetically Example
|
### Order Alphabetically Example
|
||||||
|
|
||||||
|
In Hugo 0.55 and later you can do:
|
||||||
|
|
||||||
|
```go-html-template
|
||||||
|
<ul>
|
||||||
|
{{ range .Data.Terms.Alphabetical }}
|
||||||
|
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
|
||||||
|
{{ end }}
|
||||||
|
</ul>
|
||||||
|
```
|
||||||
|
|
||||||
|
Before that you would have to do something like:
|
||||||
|
|
||||||
```go-html-template
|
```go-html-template
|
||||||
<ul>
|
<ul>
|
||||||
{{ $type := .Type }}
|
{{ $type := .Type }}
|
||||||
|
|
@ -137,35 +149,6 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
||||||
</ul>
|
</ul>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Order by Popularity Example
|
|
||||||
|
|
||||||
```go-html-template
|
|
||||||
<ul>
|
|
||||||
{{ $type := .Type }}
|
|
||||||
{{ range $key, $value := .Data.Terms.ByCount }}
|
|
||||||
{{ $name := .Name }}
|
|
||||||
{{ $count := .Count }}
|
|
||||||
{{ with $.Site.GetPage (printf "/%s/%s" $type $name) }}
|
|
||||||
<li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li>
|
|
||||||
{{ end }}
|
|
||||||
{{ end }}
|
|
||||||
</ul>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Order by Least Popular Example
|
|
||||||
|
|
||||||
```go-html-template
|
|
||||||
<ul>
|
|
||||||
{{ $type := .Type }}
|
|
||||||
{{ range $key, $value := .Data.Terms.ByCount.Reverse }}
|
|
||||||
{{ $name := .Name }}
|
|
||||||
{{ $count := .Count }}
|
|
||||||
{{ with $.Site.GetPage (printf "/%s/%s" $type $name) }}
|
|
||||||
<li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li>
|
|
||||||
{{ end }}
|
|
||||||
{{ end }}
|
|
||||||
</ul>
|
|
||||||
```
|
|
||||||
|
|
||||||
<!-- [See Also Taxonomy Lists](/templates/list/) -->
|
<!-- [See Also Taxonomy Lists](/templates/list/) -->
|
||||||
|
|
||||||
|
|
@ -311,6 +294,20 @@ The following example displays all terms in a site's tags taxonomy:
|
||||||
|
|
||||||
### Example: List All Site Tags {#example-list-all-site-tags}
|
### Example: List All Site Tags {#example-list-all-site-tags}
|
||||||
|
|
||||||
|
In Hugo 0.55 and later you can simply do:
|
||||||
|
|
||||||
|
```go-html-template
|
||||||
|
<ul>
|
||||||
|
{{ range .Site.Taxonomies.tags }}
|
||||||
|
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
|
||||||
|
{{ end }}
|
||||||
|
</ul>
|
||||||
|
```
|
||||||
|
|
||||||
|
Before that you would do something like this:
|
||||||
|
|
||||||
|
{{< todo >}}Clean up rest of the taxonomy examples re Hugo 0.55.{{< /todo >}}
|
||||||
|
|
||||||
```go-html-template
|
```go-html-template
|
||||||
<ul id="all-tags">
|
<ul id="all-tags">
|
||||||
{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
|
{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
|
||||||
|
|
|
||||||
|
|
@ -124,7 +124,7 @@ See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
|
||||||
: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`.
|
: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`.
|
||||||
|
|
||||||
.RSSLink (deprecated)
|
.RSSLink (deprecated)
|
||||||
: link to the page's RSS feed. This is deprecated. You should instead do something like this: `{{ with .OutputFormats.Get "RSS" }}{{ . RelPermalink }}{{ end }}`.
|
: link to the page's RSS feed. This is deprecated. You should instead do something like this: `{{ with .OutputFormats.Get "RSS" }}{{ .RelPermalink }}{{ end }}`.
|
||||||
|
|
||||||
.RawContent
|
.RawContent
|
||||||
: raw markdown content without the front matter. Useful with [remarkjs.com](
|
: raw markdown content without the front matter. Useful with [remarkjs.com](
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,7 @@ publish = "public"
|
||||||
command = "hugo --gc --minify"
|
command = "hugo --gc --minify"
|
||||||
|
|
||||||
[context.production.environment]
|
[context.production.environment]
|
||||||
HUGO_VERSION = "0.55.0"
|
HUGO_VERSION = "0.55.2"
|
||||||
HUGO_ENV = "production"
|
HUGO_ENV = "production"
|
||||||
HUGO_ENABLEGITINFO = "true"
|
HUGO_ENABLEGITINFO = "true"
|
||||||
|
|
||||||
|
|
@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true"
|
||||||
command = "hugo --gc --minify --enableGitInfo"
|
command = "hugo --gc --minify --enableGitInfo"
|
||||||
|
|
||||||
[context.split1.environment]
|
[context.split1.environment]
|
||||||
HUGO_VERSION = "0.55.0"
|
HUGO_VERSION = "0.55.2"
|
||||||
HUGO_ENV = "production"
|
HUGO_ENV = "production"
|
||||||
|
|
||||||
[context.deploy-preview]
|
[context.deploy-preview]
|
||||||
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
|
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
|
||||||
|
|
||||||
[context.deploy-preview.environment]
|
[context.deploy-preview.environment]
|
||||||
HUGO_VERSION = "0.55.0"
|
HUGO_VERSION = "0.55.2"
|
||||||
|
|
||||||
[context.branch-deploy]
|
[context.branch-deploy]
|
||||||
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
|
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
|
||||||
|
|
||||||
[context.branch-deploy.environment]
|
[context.branch-deploy.environment]
|
||||||
HUGO_VERSION = "0.55.0"
|
HUGO_VERSION = "0.55.2"
|
||||||
|
|
||||||
[context.next.environment]
|
[context.next.environment]
|
||||||
HUGO_ENABLEGITINFO = "true"
|
HUGO_ENABLEGITINFO = "true"
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue