mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Merge commit 'a0c28c943c2f4714fa340b22a583b96f5013090b'
This commit is contained in:
Bjørn Erik Pedersen
commit
0508ca1856
12 changed files with 164 additions and 103 deletions
|
|
@ -100,7 +100,7 @@ Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as pr
|
|||
|
||||
## 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
|
||||
|
||||
|
|
@ -253,8 +253,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
|
|||
[mdguide]: https://www.markdownguide.org/
|
||||
[mdtutorial]: http://www.markdowntutorial.com/
|
||||
[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
|
||||
[mmark]: https://github.com/miekg/mmark
|
||||
[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
|
||||
[mmark]: https://github.com/mmarkdown/mmark
|
||||
[org]: http://orgmode.org/
|
||||
[pandoc]: http://www.pandoc.org/
|
||||
[Pygments]: http://pygments.org/
|
||||
|
|
|
|||
|
|
@ -53,12 +53,15 @@ The examples above use two different delimiters, the difference being the `%` ch
|
|||
|
||||
### 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
|
||||
|
||||
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).
|
||||
|
||||
### 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 %}}
|
||||
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.
|
||||
{{% /note %}}
|
||||
|
||||
{{% warning "`preserveTaxonomyNames` behaviour change" %}}
|
||||
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.
|
||||
{{% warning %}}
|
||||
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 %}}
|
||||
|
||||
## 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 comes in two forms:
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
|
||||
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)
|
||||
: Pluralize titles in lists.
|
||||
|
||||
preserveTaxonomyNames (false)
|
||||
: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
|
||||
|
||||
publishDir ("public")
|
||||
: The directory to where Hugo will write the final static site (the HTML files etc.).
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,6 @@ Usage:
|
|||
hugo [command]
|
||||
|
||||
Available Commands:
|
||||
benchmark Benchmark Hugo by building a site a number of times.
|
||||
check Contains some verification checks
|
||||
config Print the site configuration
|
||||
convert Convert your content to different formats
|
||||
|
|
@ -57,43 +56,43 @@ Available Commands:
|
|||
version Print the version number of Hugo
|
||||
|
||||
Flags:
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
|
||||
-D, --buildDrafts include content marked as draft
|
||||
-E, --buildExpired include expired content
|
||||
-F, --buildFuture include content with publishdate in the future
|
||||
--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
|
||||
--config string config file (default is path/config.yaml|json|toml)
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
--debug debug output
|
||||
-d, --destination string filesystem path to write files to
|
||||
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
|
||||
--enableGitInfo add Git revision, date and author info to the pages
|
||||
--forceSyncStatic copy all files when static is changed.
|
||||
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
||||
-h, --help help for hugo
|
||||
--i18n-warnings print missing translations
|
||||
--ignoreCache ignores the cache directory
|
||||
-l, --layoutDir string filesystem path to layout directory
|
||||
--log enable Logging
|
||||
--logFile string log File path (if set, logging enabled automatically)
|
||||
--noChmod don't sync permission mode of files
|
||||
--noTimes don't sync modification time of files
|
||||
--pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true)
|
||||
--preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (only useful for benchmark testing)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--stepAnalysis display memory and timing of different steps of the program
|
||||
--templateMetrics display metrics about template executions
|
||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||
-t, --theme string theme to use (located in /themes/THEMENAME/)
|
||||
--themesDir string filesystem path to themes directory
|
||||
--uglyURLs (deprecated) if true, use /filename.html instead of /filename/
|
||||
-v, --verbose verbose output
|
||||
--verboseLog verbose logging
|
||||
-w, --watch watch filesystem for changes and recreate as needed
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
|
||||
-D, --buildDrafts include content marked as draft
|
||||
-E, --buildExpired include expired content
|
||||
-F, --buildFuture include content with publishdate in the future
|
||||
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
|
||||
--cleanDestinationDir remove files from destination not found in static directories
|
||||
--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
|
||||
--debug debug output
|
||||
-d, --destination string filesystem path to write files to
|
||||
--disableKinds strings disable different kind of pages (home, RSS etc.)
|
||||
--enableGitInfo add Git revision, date and author info to the pages
|
||||
-e, --environment string build environment
|
||||
--forceSyncStatic copy all files when static is changed.
|
||||
--gc enable to run some cleanup tasks (remove unused cache files) after the build
|
||||
-h, --help help for hugo
|
||||
--i18n-warnings print missing translations
|
||||
--ignoreCache ignores the cache directory
|
||||
-l, --layoutDir string filesystem path to layout directory
|
||||
--log enable Logging
|
||||
--logFile string log File path (if set, logging enabled automatically)
|
||||
--minify minify any supported output format (HTML, XML etc.)
|
||||
--noChmod don't sync permission mode of files
|
||||
--noTimes don't sync modification time of files
|
||||
--path-warnings print warnings on duplicate target paths etc.
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (only useful for benchmark testing)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--templateMetrics display metrics about template executions
|
||||
--templateMetricsHints calculate some improvement hints when combined with --templateMetrics
|
||||
-t, --theme strings themes to use (located in /themes/THEMENAME/)
|
||||
--themesDir string filesystem path to themes directory
|
||||
--trace file write trace to file (not useful in general)
|
||||
-v, --verbose verbose output
|
||||
--verboseLog verbose logging
|
||||
-w, --watch watch filesystem for changes and recreate as needed
|
||||
|
||||
Use "hugo [command] --help" for more information about a command.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
---
|
||||
date: 2019-04-12
|
||||
title: "0.55.1"
|
||||
description: "0.55.1"
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
|
||||
---
|
||||
date: 2019-04-17
|
||||
title: "0.55.2"
|
||||
description: "0.55.2"
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
{{< 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`.
|
||||
* 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`
|
||||
: 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
|
||||
|
||||
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>`:
|
||||
|
||||
|
|
@ -183,13 +186,26 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an
|
|||
{{ 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
|
||||
{{ with .OutputFormats.Get "json" -}}
|
||||
<a href="{{ .Permalink }}">{{ .Name }}</a>
|
||||
{{ .RelPermalink }} > /that-page/index.json
|
||||
{{ with .OutputFormats.Get "html" -}}
|
||||
{{ .RelPermalink }} > /that-page/
|
||||
{{- 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`.
|
||||
|
||||
### 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:
|
||||
|
||||
|
|
|
|||
|
|
@ -124,6 +124,18 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
|||
|
||||
### 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
|
||||
<ul>
|
||||
{{ $type := .Type }}
|
||||
|
|
@ -137,35 +149,6 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
|||
</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/) -->
|
||||
|
||||
|
|
@ -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}
|
||||
|
||||
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
|
||||
<ul id="all-tags">
|
||||
{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ publish = "public"
|
|||
command = "hugo --gc --minify"
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_VERSION = "0.55.0"
|
||||
HUGO_VERSION = "0.55.2"
|
||||
HUGO_ENV = "production"
|
||||
HUGO_ENABLEGITINFO = "true"
|
||||
|
||||
|
|
@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true"
|
|||
command = "hugo --gc --minify --enableGitInfo"
|
||||
|
||||
[context.split1.environment]
|
||||
HUGO_VERSION = "0.55.0"
|
||||
HUGO_VERSION = "0.55.2"
|
||||
HUGO_ENV = "production"
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.deploy-preview.environment]
|
||||
HUGO_VERSION = "0.55.0"
|
||||
HUGO_VERSION = "0.55.2"
|
||||
|
||||
[context.branch-deploy]
|
||||
command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.branch-deploy.environment]
|
||||
HUGO_VERSION = "0.55.0"
|
||||
HUGO_VERSION = "0.55.2"
|
||||
|
||||
[context.next.environment]
|
||||
HUGO_ENABLEGITINFO = "true"
|
||||
|
|
|
|||
Loading…
Reference in a new issue