--- /dev/null
- * Support for [Go][], [Amber], and [Ace][] HTML templates
+---
+title: Hugo Features
+linktitle: Hugo Features
+description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+menu:
+ docs:
+ parent: "about"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+toc: true
+---
+
+## General
+
+* [Extremely fast][] build times (< 1 ms per page)
+* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
+* Renders changes on the fly with [LiveReload][] as you develop
+* [Powerful theming][]
+* [Host your site anywhere][hostanywhere]
+
+## Organization
+
+* Straightforward [organization for your projects][], including website sections
+* Customizable [URLs][]
+* Support for configurable [taxonomies][], including categories and tags
+* [Sort content][] as you desire through powerful template [functions][]
+* Automatic [table of contents][] generation
+* [Dynamic menu][] creation
+* [Pretty URLs][] support
+* [Permalink][] pattern support
+* Redirects via [aliases][]
+
+## Content
+
+* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
+* TOML, YAML, and JSON metadata support in [front matter][]
+* Customizable [homepage][]
+* Multiple [content types][]
+* Automatic and user defined [content summaries][]
+* [Shortcodes][] to enable rich content inside of Markdown
+* ["Minutes to Read"][pagevars] functionality
+* ["WordCount"][pagevars] functionality
+
+## Additional Features
+
+* Integrated [Disqus][] comment support
+* Integrated [Google Analytics][] support
+* Automatic [RSS][] creation
- [Ace]: /templates/alternatives/
++* Support for [Go][] HTML templates
+* [Syntax highlighting][] powered by [Chroma][]
+
+
- [Amber]: https://github.com/eknkc/amber
+[aliases]: /content-management/urls/#aliases
+[Chroma]: https://github.com/alecthomas/chroma
+[content summaries]: /content-management/summaries/
+[content types]: /content-management/types/
+[Disqus]: https://disqus.com/
+[Dynamic menu]: /templates/menus/
+[Extremely fast]: https://github.com/bep/hugo-benchmark
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[Go]: https://golang.org/pkg/html/template/
+[Google Analytics]: https://google-analytics.com/
+[homepage]: /templates/homepage/
+[hostanywhere]: /hosting-and-deployment/
+[install]: /getting-started/installing/
+[LiveReload]: /getting-started/usage/
+[organization for your projects]: /getting-started/directory-structure/
+[pagevars]: /variables/page/
+[Permalink]: /content-management/urls/#permalinks
+[Powerful theming]: /themes/
+[Pretty URLs]: /content-management/urls/
+[RSS]: /templates/rss/
+[Shortcodes]: /content-management/shortcodes/
+[sort content]: /templates/
+[supported formats]: /content-management/formats/
+[Syntax highlighting]: /tools/syntax-highlighting/
+[table of contents]: /content-management/toc/
+[taxonomies]: /content-management/taxonomies/
+[URLs]: /content-management/urls/
--- /dev/null
-
- The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
+---
+title: Links and Cross References
+description: Shortcodes for creating links to documents.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+categories: [content management]
+keywords: ["cross references","references", "anchors", "urls"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 100
+weight: 100 #rem
+aliases: [/extras/crossreferences/]
+toc: true
+---
+
- {{</* ref "#anchor" */>}}
++The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
+
+## Use `ref` and `relref`
+
+```go-html-template
++{{</* ref "document" */>}}
++{{</* ref "document#anchor" */>}}
+{{</* ref "document.md" */>}}
- {{</* relref "document.md#anchor" */>}}
+{{</* ref "document.md#anchor" */>}}
++{{</* ref "#anchor" */>}}
+{{</* ref "/blog/my-post" */>}}
+{{</* ref "/blog/my-post.md" */>}}
++{{</* relref "document" */>}}
+{{</* relref "document.md" */>}}
+{{</* relref "#anchor" */>}}
- The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
++{{</* relref "/blog/my-post.md" */>}}
++```
++
++To generate a hyperlink using `ref` or `relref` in markdown:
++
++```md
++[About]({{</* ref "/page/about" */>}} "About Us")
+```
+
- **Paths without a leading `/` will first be tried resolved relative to the current page.**
++The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
+
- You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below.
++**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
+
- Link to another language version of a document, you need to use this syntax:
++Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
+
+### Link to another language version
+
- To link to a given Output Format of a document, you can use this syntax:
++To link to another language version of a document, use this syntax:
+
+```go-html-template
+{{</* relref path="document.md" lang="ja" */>}}
+```
+
+### Get another Output Format
+
- ### Anchors
++To link to another Output Format of a document, use this syntax:
+
+```go-html-template
+{{</* relref path="document.md" outputFormat="rss" */>}}
+```
+
- When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
++### Heading IDs
+
- ```go-html-template
- {{</* relref "#anchors" */>}} => #anchors:9decaf7
++When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
+
- The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
++```md
++## Reference
+```
+
- ```go-html-template
- {{</* relref "#who" */>}} => #who:9decaf7
- {{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
++produces this HTML:
+
- More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
++```html
++<h2 id="reference">Reference</h2>
+```
+
- ## Hugo Heading Anchors
++Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
+
- When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
++```md
++{{</* ref "document.md#reference */>}}
++{{</* relref "document.md#reference */>}}
++```
+
- Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`.
++Generate a custom heading ID by including an attribute. For example:
+
- `ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
++```md
++## Reference A {#foo}
++## Reference B {id="bar"}
++```
+
- {{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
- /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
++produces this HTML:
+
++```html
++<h2 id="foo">Reference A</h2>
++<h2 id="bar">Reference B</h2>
+```
- The behaviour can, since Hugo 0.45, be configured in `config.toml`:
++
++Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
++
++```md
++## Reference
++## Reference
++## Reference
++```
++
++produces this HTML:
++
++```html
++<h2 id="reference">Reference</h2>
++<h2 id="reference-1">Reference</h2>
++<h2 id="reference-2">Reference</h2>
+```
+
+## Ref and RelRef Configuration
+
++The behavior can, since Hugo 0.45, be configured in `config.toml`:
+
+refLinksErrorLevel ("ERROR")
+: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
+
+refLinksNotFoundURL
+: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
+
+
+[lists]: /templates/lists/
+[output formats]: /templates/output-formats/
+[shortcode]: /content-management/shortcodes/
+[bfext]: /content-management/formats/#blackfriday-extensions
--- /dev/null
- This uses a definition like this one in `i18n/en-US.toml`:
+---
+title: Multilingual Mode
+linktitle: Multilingual and i18n
+description: Hugo supports the creation of websites with multiple languages side by side.
+date: 2017-01-10
+publishdate: 2017-01-10
+lastmod: 2017-01-10
+categories: [content management]
+keywords: [multilingual,i18n, internationalization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 150
+weight: 150 #rem
+draft: false
+aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
+toc: true
+---
+
+You should define the available languages in a `languages` section in your site configuration.
+
+> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
+
+## Configure Languages
+
+The following is an example of a site configuration for a multilingual Hugo project:
+
+{{< code-toggle file="config" >}}
+DefaultContentLanguage = "en"
+copyright = "Everything is mine"
+
+[params]
+[params.navigation]
+help = "Help"
+
+[languages]
+[languages.en]
+title = "My blog"
+weight = 1
+[languages.en.params]
+linkedin = "https://linkedin.com/whoever"
+
+[languages.fr]
+title = "Mon blogue"
+weight = 2
+[languages.fr.params]
+linkedin = "https://linkedin.com/fr/whoever"
+[languages.fr.params.navigation]
+help = "Aide"
+
+[languages.ar]
+title = "مدونتي"
+weight = 2
+languagedirection = "rtl"
+{{< /code-toggle >}}
+
+Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set.
+
+With the configuration above, all content, sitemap, RSS feeds, paginations,
+and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
+
+When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
+
+`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`.
+
+If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`.
+
+Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
+
+### Disable a Language
+
+You can disable one or more languages. This can be useful when working on a new translation.
+
+```toml
+disableLanguages = ["fr", "ja"]
+```
+
+Note that you cannot disable the default content language.
+
+We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables):
+
+```bash
+HUGO_DISABLELANGUAGES="fr ja" hugo
+```
+If you have already a list of disabled languages in `config.toml`, you can enable them in development like this:
+
+```bash
+HUGO_DISABLELANGUAGES=" " hugo server
+```
+
+
+### Configure Multilingual Multihost
+
+From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
+
+This means that you can now configure a `baseURL` per `language`:
+
+
+> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
+
+Example:
+
+{{< code-toggle file="config" >}}
+[languages]
+[languages.fr]
+baseURL = "https://example.fr"
+languageName = "Français"
+weight = 1
+title = "En Français"
+
+[languages.en]
+baseURL = "https://example.com"
+languageName = "English"
+weight = 2
+title = "In English"
+{{</ code-toggle >}}
+
+With the above, the two sites will be generated into `public` with their own root:
+
+```bash
+public
+├── en
+└── fr
+```
+
+**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.**
+
+When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console:
+
+```bash
+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)
+Press Ctrl+C to stop
+```
+
+Live reload and `--navigateToChanged` between the servers work as expected.
+
+### Taxonomies and Blackfriday
+
+Taxonomies and [Blackfriday configuration][config] can also be set per language:
+
+
+{{< code-toggle file="config" >}}
+[Taxonomies]
+tag = "tags"
+
+[blackfriday]
+angledQuotes = true
+hrefTargetBlank = true
+
+[languages]
+[languages.en]
+weight = 1
+title = "English"
+[languages.en.blackfriday]
+angledQuotes = false
+
+[languages.fr]
+weight = 2
+title = "Français"
+[languages.fr.Taxonomies]
+plaque = "plaques"
+{{</ code-toggle >}}
+
+## Translate Your Content
+
+There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
+
+### Translation by filename
+
+Considering the following example:
+
+1. `/content/about.en.md`
+2. `/content/about.fr.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is __assigned__ according to the language code added as a __suffix to the filename__.
+
+By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
+
+{{< note >}}
+If a file has no language code, it will be assigned the default language.
+{{</ note >}}
+
+### Translation by content directory
+
+This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param.
+
+{{< code-toggle file="config" >}}
+
+languages:
+ en:
+ weight: 10
+ languageName: "English"
+ contentDir: "content/english"
+ fr:
+ weight: 20
+ languageName: "Français"
+ contentDir: "content/french"
+
+{{< /code-toggle >}}
+
+The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
+
+Considering the following example in conjunction with the configuration above:
+
+1. `/content/english/about.md`
+2. `/content/french/about.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is __assigned__ according to the content directory they are __placed__ in.
+
+By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
+
+### Bypassing default linking.
+
+Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
+
+Considering the following example:
+
+1. `/content/about-us.en.md`
+2. `/content/om.nn.md`
+3. `/content/presentation/a-propos.fr.md`
+
+```yaml
+# set in all three pages
+translationKey: "about"
+```
+
+By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages.
+
+
+### Localizing permalinks
+
+Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
+
+To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file.
+
+For example, a French translation (`content/about.fr.md`) can have its own localized slug.
+
+{{< code-toggle >}}
+Title: A Propos
+slug: "a-propos"
+{{< /code-toggle >}}
+
+
+At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking.
+
+{{% note %}}
+If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`.
+{{%/ note %}}
+
+### Page Bundles
+
+To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...).
+
+Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
+
+If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows:
+
+* File from current language bundle, if present.
+* First file found across bundles by order of language `Weight`.
+
+{{% note %}}
+Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
+{{%/ note %}}
+
+## Reference the Translated Content
+
+To create a list of links to translated content, use a template similar to the following:
+
+{{< code file="layouts/partials/i18nlist.html" >}}
+{{ if .IsTranslated }}
+<h4>{{ i18n "translations" }}</h4>
+<ul>
+ {{ range .Translations }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page.
+
+The above also uses the [`i18n` function][i18func] described in the next section.
+
+### List All Available Languages
+
+`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
+
+
+{{< code file="layouts/partials/allLanguages.html" >}}
+<ul>
+{{ range $.Site.Home.AllTranslations }}
+<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+## Translation of Strings
+
+Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
+
+Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc.
+
+{{% note %}}
+From **Hugo 0.31** you no longer need to use a valid language code. It can be anything.
+
+See https://github.com/gohugoio/hugo/issues/3564
+
+{{% /note %}}
+
++### Query basic translation
++
+From within your templates, use the `i18n` function like this:
+
+```
+{{ i18n "home" }}
+```
+
- Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
++The function will search for the `"home"` id from `i18n/en-US.toml` file:
+
+```
+[home]
+other = "Home"
+```
+
- This uses a definition like this one in `i18n/en-US.toml`:
++The result will be
++
++```
++Home
++```
++
++### Query a flexible translation with variables
++
++Often you will want to use to the page variables in the translations strings. To do that, pass on the `.` context when calling `i18n`:
+
+```
+{{ i18n "wordCount" . }}
+```
+
- An example of singular and plural form:
++The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file:
+
+```
+[wordCount]
+other = "This article has {{ .WordCount }} words."
+```
- And then in the template:
++
++Assume `.WordCount` in the context has value is 101. The result will be:
++
++```
++This article has 101 words.
++```
++
++### Query a singular/plural translation
++
++In other to meet singular/plural requirement, you must pass a dictionary (map) data with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property.
++
++```
++{{ i18n "readingTime" .ReadingTime }}
++```
++
++The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
+
+```
+[readingTime]
+one = "One minute to read"
+other = "{{.Count}} minutes to read"
+```
- {{ i18n "readingTime" .ReadingTime }}
++
++Assume `.ReadingTime.Count` in the context has value is 525600. The result will be:
+
+```
++525600 minutes to read
++```
++
++If `.ReadingTime.Count` in the context has value is 1. The result is:
++
++```
++One minutes to read
+```
+
++In case you need to pass a custom data: (`"(dict Count" 25)` is minimum requirment)
++
++```
++{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
++```
++
++
+## Customize Dates
+
+At the time of this writing, Go does not yet have support for internationalized locales for dates, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content:
+
+~~~yaml
+1: "janvier"
+2: "février"
+3: "mars"
+4: "avril"
+5: "mai"
+6: "juin"
+7: "juillet"
+8: "août"
+9: "septembre"
+10: "octobre"
+11: "novembre"
+12: "décembre"
+~~~
+
+...then index the non-English date names in your templates like so:
+
+~~~html
+<time class="post-date" datetime="{{ .Date.Format '2006-01-02T15:04:05Z07:00' | safeHTML }}">
+ Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
+</time>
+~~~
+
+This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file.
+
+## Menus
+
+You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file:
+
+```
+defaultContentLanguage = "en"
+
+[languages.en]
+weight = 0
+languageName = "English"
+
+[[languages.en.menu.main]]
+url = "/"
+name = "Home"
+weight = 0
+
+
+[languages.de]
+weight = 10
+languageName = "Deutsch"
+
+[[languages.de.menu.main]]
+url = "/"
+name = "Startseite"
+weight = 0
+```
+
+The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory.
+
+```
+<ul>
+ {{- $currentPage := . -}}
+ {{ range .Site.Menus.main -}}
+ <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
+ <a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
+ </li>
+ {{- end }}
+</ul>
+
+```
+
+## Missing Translations
+
+If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
+
+While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
+
+{{% note %}}
+Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
+{{% /note %}}
+
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
+
+To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
+
+```
+ hugo --i18n-warnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Multilingual Themes support
+
+To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
+
+* Come from the built-in `.Permalink` or `.RelPermalink`
+* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}`
+
+If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
+
+[abslangurl]: /functions/abslangurl
+[config]: /getting-started/configuration/
+[contenttemplate]: /templates/single-page-templates/
+[go-i18n-source]: https://github.com/nicksnyder/go-i18n
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[homepage]: /templates/homepage/
+[i18func]: /functions/i18n/
+[menus]: /content-management/menus/
+[rellangurl]: /functions/rellangurl
+[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[singles]: /templates/single-page-templates/
--- /dev/null
- description: Looks up a content page by logical name.
+---
+title: ref
+linktitle: ref
- lastmod: 2019-12-28
++description: Returns the absolute permalink to a page.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
- signature: ["ref . CONTENT"]
++lastmod: 2020-09-05
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [cross references, anchors]
- `ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink:
++signature: ["ref . PAGE"]
+workson: []
+hugoversion:
+relatedfuncs: [relref]
+deprecated: false
+aliases: []
+---
+
- ```
++This function takes two parameters:
+
- {{% note "Usage Note" %}}
- `ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
- {{% /note %}}
++- The context of the page from which to resolve relative paths, typically the current page (`.`)
++- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site.
++
++```go-html-template
++{{ ref . "about" }}
++{{ ref . "about#anchor" }}
+{{ ref . "about.md" }}
++{{ ref . "about.md#anchor" }}
++{{ ref . "#anchor" }}
++{{ ref . "/blog/my-post" }}
++{{ ref . "/blog/my-post.md" }}
+```
+
- It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path.
++To return the absolute permalink to another language version of a page:
++
++```go-html-template
++{{ ref . (dict "path" "about.md" "lang" "fr") }}
++```
+
- ```
- {{ ref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }}
++To return the absolute permalink to another Output Format of a page:
+
- These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
++```go-html-template
++{{ ref . (dict "path" "about.md" "outputFormat" "rss") }}
+```
+
- For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
++Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration).
+
++This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).
--- /dev/null
- # linktitle: relref
- description: Looks up a content page by relative path.
+---
+title: relref
- lastmod: 2019-12-28
++linktitle: relref
++description: Returns the relative permalink to a page.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
- signature: ["relref . CONTENT"]
++lastmod: 2020-09-05
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [cross references, anchors]
- `ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink:
++signature: ["relref . PAGE"]
+workson: []
+hugoversion:
+relatedfuncs: [ref]
+deprecated: false
+aliases: []
+---
+
- ```
++This function takes two parameters:
+
- {{% note "Usage Note" %}}
- `relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
- {{% /note %}}
++- The context of the page from which to resolve relative paths, typically the current page (`.`)
++- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site.
++
++```go-html-template
++{{ relref . "about" }}
++{{ relref . "about#anchor" }}
+{{ relref . "about.md" }}
++{{ relref . "about.md#anchor" }}
++{{ relref . "#anchor" }}
++{{ relref . "/blog/my-post" }}
++{{ relref . "/blog/my-post.md" }}
+```
+
- It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path.
++The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example:
++
++Code|baseURL|Permalink
++:--|:--|:--
++`{{ relref . "/about" }}`|`http://example.org/`|`/about/`
++`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/`
++
++To return the relative permalink to another language version of a page:
++
++```go-html-template
++{{ relref . (dict "path" "about.md" "lang" "fr") }}
++```
+
- ```
- {{ relref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }}
++To return the relative permalink to another Output Format of a page:
+
- These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
++```go-html-template
++{{ relref . (dict "path" "about.md" "outputFormat" "rss") }}
+```
+
- For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
++Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration).
+
++This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).
--- /dev/null
- <h1>The World's Greatest City</h1>
- <div><a href="/locations/chicago-il/">Chicago IL</a></div>
+---
+title: urlize
+# linktitle: urlize
+description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [urls,strings]
+godocref:
+signature: ["urlize INPUT"]
+hugoversion:
+deprecated: false
+workson: []
+relatedfuncs: []
+---
+
+The following examples pull from a content file with the following front matter:
+
+{{< code file="content/blog/greatest-city.md" copy="false">}}
++++
+title = "The World's Greatest City"
+location = "Chicago IL"
+tags = ["pizza","beer","hot dogs"]
++++
+{{< /code >}}
+
+The following might be used as a partial within a [single page template][singletemplate]:
+
+{{< code file="layouts/partials/content-header.html" download="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 >}}
+
+The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs.
+
+{{< output file="/blog/greatest-city/index.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>
+{{< /output >}}
+
+
++
+[singletemplate]: /templates/single-page-templates/
--- /dev/null
- You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed.[^hooktemplate] Your `layouts` folder may look like this:
+---
+title: Configure Markup
+description: How to handle Markdown and other markup related configuration.
+date: 2019-11-15
+categories: [getting started,fundamentals]
+keywords: [configuration,highlighting]
+weight: 65
+sections_weight: 65
+slug: configuration-markup
+toc: true
+---
+
+## Configure Markup
+
+{{< new-in "0.60.0" >}}
+
+See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo.
+
+Below are all markup related configuration in Hugo with their default settings:
+
+{{< code-toggle config="markup" />}}
+
+**See each section below for details.**
+
+### Goldmark
+
+[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. Note that the feature set of Goldmark vs Blackfriday isn't the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions.
+
+This is the default configuration:
+
+{{< code-toggle config="markup.goldmark" />}}
+
+Some settings explained:
+
+unsafe
+: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
+
+typographer
+: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/).
+
+autoHeadingIDType ("github") {{< new-in "0.62.2" >}}
+: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs work as with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func.
+
+### Blackfriday
+
+
+[Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set `defaultMarkdownHandler` to `blackfriday` in your top level `markup` config.
+
+This is the default config:
+
+{{< code-toggle config="markup.blackFriday" />}}
+
+### Highlight
+
+This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/).
+
+{{< code-toggle config="markup.highlight" />}}
+
+For `style`, see these galleries:
+
+* [Short snippets](https://xyproto.github.io/splash/docs/all.html)
+* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html)
+
+For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css).
+
+### Table Of Contents
+
+{{< code-toggle config="markup.tableOfContents" />}}
+
+These settings only works for the Goldmark renderer:
+
+startLevel
+: The heading level, values starting at 1 (`h1`), to start render the table of contents.
+
+endLevel
+: The heading level, inclusive, to stop render the table of contents.
+
+ordered
+: Whether or not to generate an ordered list instead of an unordered list.
+
+
+## Markdown Render Hooks
+
+{{< new-in "0.62.0" >}}
+
+Note that this is only supported with the [Goldmark](#goldmark) renderer.
+
+Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names `render-{feature}` in `layouts/_default/_markup`.
+
+You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}}
+
+The features currently supported are:
+
+* `image`
+* `link`
+* `heading` {{< new-in "0.71.0" >}}
+
-
- [^hooktemplate]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version.
++You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
+
+```bash
+layouts
+└── _default
+ └── _markup
+ ├── render-image.html
+ ├── render-image.rss.xml
+ └── render-link.html
+```
+
+Some use cases for the above:
+
+* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
+* Add `target=_blank` to external links.
+* Resolve and [process](/content-management/image-processing/) images.
+* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
+
+### Render Hook Templates
+
+The `render-link` and `render-image` templates will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Destination
+: The URL.
+
+Title
+: The title attribute.
+
+Text
+: The rendered (HTML) link text.
+
+PlainText
+: The plain variant of the above.
+
+The `render-heading` template will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Level
+: The header level (1--6)
+
+Anchor
+: An auto-generated html id unique to the header within the page
+
+Text
+: The rendered (HTML) text.
+
+PlainText
+: The plain variant of the above.
+
+#### Link with title Markdown example:
+
+```md
+[Text](https://www.gohugo.io "Title")
+```
+
+Here is a code example for how the render-link.html template could look:
+
+{{< code file="layouts/_default/_markup/render-link.html" >}}
+<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
+{{< /code >}}
+
+#### Image Markdown example:
+
+```md
+
+```
+
+Here is a code example for how the render-image.html template could look:
+
+{{< code file="layouts/_default/_markup/render-image.html" >}}
+<p class="md__image">
+ <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
+</p>
+{{< /code >}}
+
+#### Heading link example
+
+Given this template file
+
+{{< code file="layouts/_default/_markup/render-heading.html" >}}
+<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
+{{< /code >}}
+
+And this markdown
+
+```md
+### Section A
+```
+
+The rendered html will be
+
+```html
+<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>
+```
--- /dev/null
- 1. The [Homebrew][brew] `brew` utility
+---
+title: Install Hugo
+linktitle: Install Hugo
+description: Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run.
+date: 2016-11-01
+publishdate: 2016-11-01
+lastmod: 2018-01-02
+categories: [getting started,fundamentals]
+authors: ["Michael Henderson"]
+keywords: [install,pc,windows,linux,macos,binary,tarball]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/]
+toc: true
+---
+
+
+{{% note %}}
+There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary!
+{{% /note %}}
+
+Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].
+
+Hugo currently provides pre-built binaries for the following:
+
+* macOS (Darwin) for x64, i386, and ARM architectures
+* Windows
+* Linux
+* OpenBSD
+* FreeBSD
+
+Hugo may also be compiled from source wherever the Go toolchain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See <https://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures.
+
+## Quick Install
+
+### Binary (Cross-platform)
+
+Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.
+
+Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location.
+
+### Docker
+
+We currently do not offer official Hugo images for Docker, but we do recommend these up to date distributions: https://hub.docker.com/r/klakegg/hugo/
+
+### Homebrew (macOS)
+
+If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:
+
+{{< code file="install-with-homebrew.sh" >}}
+brew install hugo
+{{< /code >}}
+
+For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.
+
++### MacPorts (macOS)
++
++If you are on macOS and using [MacPorts][macports], you can install Hugo with the following one-liner:
++
++{{< code file="install-with-macports.sh" >}}
++port install hugo
++{{< /code >}}
++
+### Homebrew (Linux)
+
+If you are using [Homebrew][linuxbrew] on Linux, you can install Hugo with the following one-liner:
+
+{{< code file="install-with-linuxbrew.sh" >}}
+brew install hugo
+{{< /code >}}
+
+Installation guides for Homebrew on Linux are available on their [website][linuxbrew].
+
+### Chocolatey (Windows)
+
+If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner:
+
+{{< code file="install-with-chocolatey.ps1" >}}
+choco install hugo -confirm
+{{< /code >}}
+
+Or if you need the “extended” Sass/SCSS version:
+
+{{< code file="install-extended-with-chocolatey.ps1" >}}
+choco install hugo-extended -confirm
+{{< /code >}}
+
+### Scoop (Windows)
+
+If you are on a Windows machine and use [Scoop][] for package management, you can install Hugo with the following one-liner:
+
+```bash
+scoop install hugo
+```
+
+Or install the extended version with:
+
+```bash
+scoop install hugo-extended
+```
+
+### Source
+
+#### Prerequisite Tools
+
+* [Git][installgit]
+* [Go (at least Go 1.11)](https://golang.org/dl/)
+
+#### Fetch from GitHub
+
+Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest way to get started is to clone Hugo in a directory outside of the GOPATH, as in the following example:
+
+{{< code file="from-gh.sh" >}}
+mkdir $HOME/src
+cd $HOME/src
+git clone https://github.com/gohugoio/hugo.git
+cd hugo
+go install --tags extended
+{{< /code >}}
+
+Remove `--tags extended` if you do not want/need Sass/SCSS support.
+
+{{% note %}}
+If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.
+{{% /note %}}
+
+## macOS
+
+### Assumptions
+
+1. You know how to open the macOS terminal.
+2. You're running a modern 64-bit Mac.
+3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.)
+
+### Pick Your Method
+
+There are three ways to install Hugo on your Mac
+
- 1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update.
++1. A package manager, like [Homebrew][brew] (`brew`) or [MacPorts][macports] (`port`)
+2. Distribution (i.e., tarball)
+3. Building from Source
+
+There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case.
+
+#### Pros and Cons
+
+There are pros and cons to each of the aforementioned methods:
+
- You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
++1. **Package Manager.** Using a package manager is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option in Homebrew). Releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, this is the recommended installation method if you want to work from a stable, widely used source. Package managers work well and they are easy to update.
+
+2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice.
+
+3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options.
+
+{{% note %}}
+Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball.
+{{% /note %}}
+
+### Install Hugo with Brew
+
+{{< youtube WvhCGlLcrF8 >}}
+
+#### Step 1: Install `brew` if you haven't already
+
+Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
+
+{{< code file="install-brew.sh" >}}
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+{{< /code >}}
+
+#### Step 2: Run the `brew` Command to Install `hugo`
+
+Installing Hugo using `brew` is as easy as the following:
+
+{{< code file="install-brew.sh" >}}
+brew install hugo
+{{< /code >}}
+
+If Homebrew is working properly, you should see something similar to the following:
+
+```
+==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
+######################################################################### 100.0%
+==> Pouring hugo-0.21.sierra.bottle.tar.gz
+🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB
+```
+
+{{% note "Installing the Latest Hugo with Brew" %}}
+Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version.
+{{% /note %}}
+
+`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands:
+
+```
+$ # show the location of the hugo executable
+which hugo
+/usr/local/bin/hugo
+
+# show the installed version
+ls -l $( which hugo )
+lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo
+
+# verify that hugo runs correctly
+hugo version
+Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00
+```
+
+### Install Hugo from Tarball
+
+#### Step 1: Decide on the location
+
+When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:
+
+1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.
+
+2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases.
+
+3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable.
+
+All three locations will work for you. In the interest of brevity, this guide focuses on option #2.
+
+#### Step 2: Download the Tarball
+
+1. Open <https://github.com/gohugoio/hugo/releases> in your browser.
+
+2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release."
+
+3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number.
+
+4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps.
+
+#### Step 3: Confirm your download
+
+Verify that the tarball wasn't corrupted during the download:
+
+```
+tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
+-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
+-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
+-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md
+```
+
+The `.md` files are documentation for Hugo. The other file is the executable.
+
+#### Step 4: Install Into Your `bin` Directory
+
+```
+# create the directory if needed
+mkdir -p ~/bin
+
+# make it the working directory
+cd ~/bin
+
+# extract the tarball
+tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz
+Archive: hugo_X.Y_osx-64bit.tgz
+ x ./
+ x ./hugo
+ x ./LICENSE.md
+ x ./README.md
+
+# verify that it runs
+./hugo version
+Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
+```
+
- If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:
++You may need to add your bin directory to your `PATH` environment variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
+
+```
+# check if hugo is in the path
+which hugo
+/Users/USERNAME/bin/hugo
+```
+
- ```
- nano ~/.bash_profile
- ```
++If `hugo` is not in your `PATH`:
+
- Add a line to update your `PATH` variable:
++1. Determine your default shell (zsh or bash).
+
- ```
- export PATH=$PATH:$HOME/bin
- ```
++ ```
++ echo $SHELL
++ ```
+
- Then save the file by pressing Control-X, then Y to save the file and return to the prompt.
++2. Edit your profile.
++
++ If your default shell is zsh:
++
++ ```
++ nano ~/.zprofile
++ ```
++
++ If your default shell is bash:
++
++ ```
++ nano ~/.bash_profile
++ ```
++
++3. Insert a line to add `$HOME/bin` to your existing `PATH`.
++
++ ```
++ export PATH=$PATH:$HOME/bin
++ ```
+
- Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again.
++4. Save the file by pressing Control-X, then Y.
+
++5. Close the terminal and open a new terminal to pick up the changes to your profile. Verify the change by running the `which hugo` command again.
+
+You've successfully installed Hugo.
+
+### Build from Source on Mac
+
+If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command:
+
+```
+brew install go
+```
+
+#### Step 1: Get the Source
+
+If you want to compile a specific version of Hugo, go to <https://github.com/gohugoio/hugo/releases> and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:
+
+```
+git clone https://github.com/gohugoio/hugo
+```
+
+{{% warning "Sometimes \"Latest\" = \"Bugs\""%}}
+Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new).
+{{% /warning %}}
+
+#### Step 2: Compiling
+
+Make the directory containing the source your working directory and then fetch Hugo's dependencies:
+
+```
+mkdir -p src/github.com/gohugoio
+ln -sf $(pwd) src/github.com/gohugoio/hugo
+
+go get
+```
+
+This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change.
+
+Once you have properly configured your directory, you can compile Hugo using the following command:
+
+```
+go build -o hugo main.go
+```
+
+Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
+
+## Windows
+
+The following aims to be a complete guide to installing Hugo on your Windows PC.
+
+{{< youtube G7umPCU-8xc >}}
+
+### Assumptions
+
+1. You will use `C:\Hugo\Sites` as the starting point for your new project.
+2. You will use `C:\Hugo\bin` to store executable files.
+
+### Set up Your Directories
+
+You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website:
+
+1. Open Windows Explorer.
+2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere
+3. Create a subfolder in the Hugo folder: `C:\Hugo\bin`
+4. Create another subfolder in Hugo: `C:\Hugo\Sites`
+
+### Technical Users
+
+1. Download the latest zipped Hugo executable from [Hugo Releases][releases].
+2. Extract all contents to your `..\Hugo\bin` folder.
+3. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator.
+
+### Less-technical Users
+
+1. Go to the [Hugo Releases][releases] page.
+2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files.
+3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).)
+4. Move the ZIP file into your `C:\Hugo\bin` folder.
+5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else.
+6. You should now have three new files: The hugo executable (`hugo.exe`), `LICENSE`, and `README.md`.
+
+Now you need to add Hugo to your Windows PATH settings:
+
+#### For Windows 10 Users:
+
+* Right click on the **Start** button.
+* Click on **System**.
+* Click on **Advanced System Settings** on the left.
+* Click on the **Environment Variables...** button on the bottom.
+* In the User variables section, find the row that starts with PATH (PATH will be all caps).
+* Double-click on **PATH**.
+* Click the **New...** button.
+* Type in the folder where `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The PATH entry should be the folder where Hugo lives and not the binary.* Press <kbd>Enter</kbd> when you're done typing.
+* Click OK at every window to exit.
+
+{{% note "Path Editor in Windows 10"%}}
+The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the <i class="fa fa-windows"></i> Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.)
+{{% /note %}}
+
+#### For Windows 7 and 8.x users:
+
+Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/).
+
+### Verify the Executable
+
+Run a few commands to verify that the executable is ready to run, and then build a sample site to get started.
+
+#### 1. Open a Command Prompt
+
+At the prompt, type `hugo help` and press the <kbd>Enter</kbd> key. You should see output that starts with:
+
+```
+hugo is the main command, used to build your Hugo site.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+```
+
+If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.
+
+At the prompt, change your directory to the `Sites` directory.
+
+```
+C:\Program Files> cd C:\Hugo\Sites
+C:\Hugo\Sites>
+```
+
+#### 2. Run the Command
+
+Run the command to generate a new site. I'm using `example.com` as the name of the site.
+
+```
+C:\Hugo\Sites> hugo new site example.com
+```
+
+You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following:
+
+```
+C:\Hugo\Sites> cd example.com
+C:\Hugo\Sites\example.com> dir
+Directory of C:\hugo\sites\example.com
+
+04/13/2015 10:44 PM <DIR> .
+04/13/2015 10:44 PM <DIR> ..
+04/13/2015 10:44 PM <DIR> archetypes
+04/13/2015 10:44 PM 83 config.toml
+04/13/2015 10:44 PM <DIR> content
+04/13/2015 10:44 PM <DIR> data
+04/13/2015 10:44 PM <DIR> layouts
+04/13/2015 10:44 PM <DIR> static
+ 1 File(s) 83 bytes
+ 7 Dir(s) 6,273,331,200 bytes free
+```
+
+### Troubleshoot Windows Installation
+
+[@dhersam][] has created a nice video on common issues:
+
+{{< youtube c8fJIRNChmU >}}
+
+## Linux
+
+### Snap Package
+
+In any of the [Linux distributions that support snaps][snaps], you may install the "extended" Sass/SCSS version with this command:
+
+ snap install hugo --channel=extended
+
+To install the non-extended version without Sass/SCSS support:
+
+ snap install hugo
+
+To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`.
+
+{{% note %}}
+Hugo installed via Snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143).
+{{% /note %}}
+
+### Debian and Ubuntu
+
+[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`:
+
+ sudo apt-get install hugo
+
+What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support.
+
+This option is not recommended because the Hugo in Linux package managers for Debian and Ubuntu is usually a few versions behind as described [here](https://github.com/gcushen/hugo-academic/issues/703)
+
+### Arch Linux
+
+You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro.
+
+```
+sudo pacman -Syu hugo
+```
+
+### Fedora, Red Hat and CentOS
+
+Fedora maintains an [official package for Hugo](https://apps.fedoraproject.org/packages/hugo) which may be installed with:
+
+ sudo dnf install hugo
+
+For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended:
+
+* <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/>
+
+See the [related discussion in the Hugo forums][redhatforum].
+
+### Solus
+
+Solus includes Hugo in its package repository, it may be installed with:
+
+```
+sudo eopkg install hugo
+```
+
+## OpenBSD
+
+OpenBSD provides a package for Hugo via `pkg_add`:
+
+ doas pkg_add hugo
+
+
+## Upgrade Hugo
+
+Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew.
+
+## Next Steps
+
+Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum].
+
+[brew]: https://brew.sh/
++[macports]: https://www.macports.org/
+[Chocolatey]: https://chocolatey.org/
+[content]: /content-management/
+[@dhersam]: https://github.com/dhersam
+[forum]: https://discourse.gohugo.io
+[mage]: https://github.com/magefile/mage
+[dep]: https://github.com/golang/dep
+[highlight shortcode]: /content-management/shortcodes/#highlight
+[installgit]: https://git-scm.com/
+[installgo]: https://golang.org/dl/
+[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux
+[Path Editor]: https://patheditor2.codeplex.com/
+[pygments]: https://pygments.org
+[quickstart]: /getting-started/quick-start/
+[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491
+[releases]: https://github.com/gohugoio/hugo/releases
+[Scoop]: https://scoop.sh/
+[snaps]: https://snapcraft.io/docs/installing-snapd
+[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx
+[Windows Environment Variables Editor]: http://eveditor.com/
--- /dev/null
- `Homebrew`, a package manager for `macOS`, can be installed from [brew.sh](https://brew.sh/). See [install](/getting-started/installing) if you are running Windows etc.
+---
+title: Quick Start
+linktitle: Quick Start
+description: Create a Hugo site using the beautiful Ananke theme.
+date: 2013-07-01
+publishdate: 2013-07-01
+categories: [getting started]
+keywords: [quick start,usage]
+authors: [Shekhar Gulati, Ryan Watters]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/quickstart/,/overview/quickstart/]
+toc: true
+---
+
+{{% note %}}
+This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing).
+
+It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial.
+
+For other approaches learning Hugo like book or a video tutorial refer to the [external learning resources](/getting-started/external-learning-resources/) page.
+{{% /note %}}
+
+## Step 1: Install Hugo
+
+{{% note %}}
- {{% note %}}
- Drafts do not get deployed; once you finish a post, update the header of the post to say `draft: false`. More info [here](/getting-started/usage/#draft-future-and-expired-content).
- {{% /note %}}
++`Homebrew` and `MacPorts`, package managers for `macOS`, can be installed from [brew.sh](https://brew.sh/) or [macports.org](https://www.macports.org/) respectively. See [install](/getting-started/installing) if you are running Windows etc.
+{{% /note %}}
+
+```bash
+brew install hugo
++# or
++port install hugo
+```
+
+To verify your new install:
+
+```bash
+hugo version
+```
+
+{{< asciicast ItACREbFgvJ0HjnSNeTknxWy9 >}}
+
+## Step 2: Create a New Site
+
+```bash
+hugo new site quickstart
+```
+
+The above will create a new Hugo site in a folder named `quickstart`.
+
+{{< asciicast 3mf1JGaN0AX0Z7j5kLGl3hSh8 >}}
+
+## Step 3: Add a Theme
+
+See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/).
+
+First, download the theme from GitHub and add it to your site's `themes` directory:
+
+```bash
+cd quickstart
+git init
+git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
+```
+
+*Note for non-git users:*
+ - If you do not have git installed, you can download the archive of the latest
+ version of this theme from:
+ https://github.com/budparr/gohugo-theme-ananke/archive/master.zip
+ - Extract that .zip file to get a "gohugo-theme-ananke-master" directory.
+ - Rename that directory to "ananke", and move it into the "themes/" directory.
+
+Then, add the theme to the site configuration:
+
+```bash
+echo 'theme = "ananke"' >> config.toml
+```
+
+{{< asciicast 7naKerRYUGVPj8kiDmdh5k5h9 >}}
+
+## Step 4: Add Some Content
+
+You can manually create content files (for example as `content/<CATEGORY>/<FILE>.<FORMAT>`) and provide metadata in them, however you can use the `new` command to do a few things for you (like add title and date):
+
+```
+hugo new posts/my-first-post.md
+```
+
+{{< asciicast eUojYCfRTZvkEiqc52fUsJRBR >}}
+
+Edit the newly created content file if you want, it will start with something like this:
+
+```markdown
+---
+title: "My First Post"
+date: 2019-03-26T08:47:11+01:00
+draft: true
+---
+
+```
+
++{{% note %}}
++Drafts do not get deployed; once you finish a post, update the header of the post to say `draft: false`. More info [here](/getting-started/usage/#draft-future-and-expired-content).
++{{% /note %}}
++
+## Step 5: Start the Hugo server
+
+Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled:
+
+{{< asciicast BvJBsF6egk9c163bMsObhuNXj >}}
+
+```
+▶ hugo server -D
+
+ | EN
++------------------+----+
+ Pages | 10
+ Paginator pages | 0
+ Non-page files | 0
+ Static files | 3
+ Processed images | 0
+ Aliases | 1
+ Sitemaps | 1
+ Cleaned | 0
+
+Total in 11 ms
+Watching for changes in /Users/bep/quickstart/{content,data,layouts,static,themes}
+Watching for config changes in /Users/bep/quickstart/config.toml
+Environment: "development"
+Serving pages from memory
+Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
+Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
+Press Ctrl+C to stop
+```
+
+**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).**
+
+Feel free to edit or add new content and simply refresh in browser to see changes quickly (You might need to force refresh in webbrowser, something like Ctrl-R usually works).
+
+## Step 6: Customize the Theme
+
+Your new site already looks great, but you will want to tweak it a little before you release it to the public.
+
+### Site Configuration
+
+Open up `config.toml` in a text editor:
+
+```
+baseURL = "https://example.org/"
+languageCode = "en-us"
+title = "My New Hugo Site"
+theme = "ananke"
+```
+
+Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server.
+
+{{% note %}}
+**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away, though you may need to [clear your cache](https://kb.iu.edu/d/ahic).
+{{% /note %}}
+
+For theme specific configuration options, see the [theme site](https://github.com/budparr/gohugo-theme-ananke).
+
+**For further theme customization, see [Customize a Theme](/themes/customizing/).**
+
+### Step 7: Build static pages
+
+It is simple. Just call:
+
+```
+hugo -D
+```
+
+Output will be in `./public/` directory by default (`-d`/`--destination` flag to change it, or set `publishdir` in the config file).
+
--- /dev/null
- When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work.
-
- But you should not have both. So if you add a `mounts` section you should make it complete and remove the old `staticDir` etc. settings.
+---
+title: Configure Modules
+linktitle: Configure Modules
+description: This page describes the configuration options for a module.
+date: 2019-07-24
+categories: [hugo modules]
+keywords: [themes, source, organization, directories]
+menu:
+ docs:
+ parent: "modules"
+ weight: 10
+weight: 10
+sections_weight: 10
+toc: true
+---
+
+## Module Config: Top level
+
+{{< code-toggle file="config">}}
+[module]
+proxy = "direct"
+noProxy = "none"
+private = "*.*"
+{{< /code-toggle >}}
+
+proxy
+: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar.
+
+noProxy
+: Comma separated glob list matching paths that should not use the proxy configured above.
+
+private
+: Comma separated glob list matching paths that should be treated as private.
+
+Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example:
+
+```
+env HUGO_MODULE_PROXY=https://proxy.example.org hugo
+```
+
+{{< gomodules-info >}}
+
+## Module Config: hugoVersion
+
+If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version.
+
+{{< code-toggle file="config">}}
+[module]
+[module.hugoVersion]
+ min = ""
+ max = ""
+ extended = false
+
+{{< /code-toggle >}}
+
+Any of the above can be omitted.
+
+min
+: The minimum Hugo version supported, e.g. `0.55.0`
+
+max
+: The maximum Hugo version supported, e.g. `0.55.0`
+
+extended
+: Whether the extended version of Hugo is required.
+
+## Module Config: imports
+
+{{< code-toggle file="config">}}
+[module]
+[[module.imports]]
+ path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
+ ignoreConfig = false
+ disable = false
+[[module.imports]]
+ path = "my-shortcodes"
+{{< /code-toggle >}}
+
+path
+: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder.
+
+ignoreConfig
+: If enabled, any module configuration file, e.g. `config.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies.
+
+disable
+: Set to `true` to disable the module off while keeping any version info in the `go.*` files.
+
+{{< gomodules-info >}}
+
+
+## Module Config: mounts
+
+{{% note %}}
++When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `staticDir` etc. settings.
+{{% /note %}}
+
++{{% warning %}}
++When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it.
++{{% /warning %}}
++
++**Default mounts**
+{{< code-toggle file="config">}}
+[module]
+[[module.mounts]]
+ source="content"
+ target="content"
+[[module.mounts]]
+ source="static"
+ target="static"
+[[module.mounts]]
+ source="layouts"
+ target="layouts"
+[[module.mounts]]
+ source="data"
+ target="data"
+[[module.mounts]]
+ source="assets"
+ target="assets"
+[[module.mounts]]
+ source="i18n"
+ target="i18n"
+[[module.mounts]]
+ source="archetypes"
+ target="archetypes"
+{{< /code-toggle >}}
+
+source
+: The source directory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative.
+
+target
+: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
+
+lang
+: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode.
+
--- /dev/null
- [index]: /functions/index/
+---
+title: Introduction to Hugo Templating
+linktitle: Introduction
+description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+godocref: https://golang.org/pkg/html/template/
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-25
+categories: [templates,fundamentals]
+keywords: [go]
+menu:
+ docs:
+ parent: "templates"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
+toc: true
+---
+
+{{% note %}}
+The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/).
+{{% /note %}}
+
+Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
+
+## Basic Syntax
+
+Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`.
+
+### Access a Predefined Variable
+
+A _predefined variable_ could be a variable already existing in the
+current scope (like the `.Title` example in the [Variables]({{< relref
+"#variables" >}}) section below) or a custom variable (like the
+`$address` example in that same section).
+
+
+```go-html-template
+{{ .Title }}
+{{ $address }}
+```
+
+Parameters for functions are separated using spaces. The general syntax is:
+
+```
+{{ FUNCTION ARG1 ARG2 .. }}
+```
+
+The following example calls the `add` function with inputs of `1` and `2`:
+
+```go-html-template
+{{ add 1 2 }}
+```
+
+#### Methods and Fields are Accessed via dot Notation
+
+Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
+
+```go-html-template
+{{ .Params.bar }}
+```
+
+#### Parentheses Can be Used to Group Items Together
+
+```go-html-template
+{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
+```
+
+## Variables {#variables}
+
+Each Go Template gets a data object. In Hugo, each template is passed
+a `Page`. In the below example, `.Title` is one of the elements
+accessible in that [`Page` variable][pagevars].
+
+With the `Page` being the default scope of a template, the `Title`
+element in current scope (`.` -- "the **dot**") is accessible simply
+by the dot-prefix (`.Title`):
+
+```go-html-template
+<title>{{ .Title }}</title>
+```
+
+Values can also be stored in custom variables and referenced later:
+
+{{% note %}}
+The custom variables need to be prefixed with `$`.
+{{% /note %}}
+
+```go-html-template
+{{ $address := "123 Main St." }}
+{{ $address }}
+```
+
+{{% warning %}}
+For Hugo v0.47 and older versions, variables defined inside `if`
+conditionals and similar are not visible on the outside.
+See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608).
+
+Hugo has created a workaround for this issue in [Scratch](/functions/scratch).
+{{% /warning %}}
+
+For **Hugo v0.48** and newer, variables can be re-defined using the
+new `=` operator (new in Go 1.11).
+
+Below example will work only in these newer Hugo versions. The example
+prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on
+all other pages:
+
+```go-html-template
+{{ $var := "Hugo Page" }}
+{{ if .IsHome }}
+ {{ $var = "Hugo Home" }}
+{{ end }}
+Var is {{ $var }}
+```
+
+## Functions
+
+Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
+
+[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
+
+### Example 1: Adding Numbers
+
+```go-html-template
+{{ add 1 2 }}
+<!-- prints 3 -->
+```
+
+### Example 2: Comparing Numbers
+
+```go-html-template
+{{ lt 1 2 }}
+<!-- prints true (i.e., since 1 is less than 2) -->
+```
+
+Note that both examples make use of Go Template's [math functions][].
+
+{{% note "Additional Boolean Operators" %}}
+There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions).
+{{% /note %}}
+
+## Includes
+
+When including another template, you will need to pass it the data that it would
+need to access.
+
+{{% note %}}
+To pass along the current context, please remember to include a trailing **dot**.
+{{% /note %}}
+
+The templates location will always be starting at the `layouts/` directory
+within Hugo.
+
+### Partial
+
+The [`partial`][partials] function is used to include *partial* templates using
+the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
+
+Example of including a `layouts/partials/header.html` partial:
+
+```go-html-template
+{{ partial "header.html" . }}
+```
+
+### Template
+
+The `template` function was used to include *partial* templates
+in much older Hugo versions. Now it's useful only for calling
+[*internal* templates][internal_templates]. The syntax is `{{ template
+"_internal/<TEMPLATE>.<EXTENSION>" . }}`.
+
+{{% note %}}
+The available **internal** templates can be found
+[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
+{{% /note %}}
+
+Example of including the internal `opengraph.html` template:
+
+```go-html-template
+{{ template "_internal/opengraph.html" . }}
+```
+
+## Logic
+
+Go Templates provide the most basic iteration and conditional logic.
+
+### Iteration
+
+The Go Templates make heavy use of `range` to iterate over a _map_,
+_array_, or _slice_. The following are different examples of how to
+use `range`.
+
+#### Example 1: Using Context (`.`)
+
+```go-html-template
+{{ range $array }}
+ {{ . }} <!-- The . represents an element in $array -->
+{{ end }}
+```
+
+#### Example 2: Declaring a variable name for an array element's value
+
+```go-html-template
+{{ range $elem_val := $array }}
+ {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 3: Declaring variable names for an array element's index _and_ value
+
+For an array or slice, the first declared variable will map to each
+element's index.
+
+```go-html-template
+{{ range $elem_index, $elem_val := $array }}
+ {{ $elem_index }} -- {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 4: Declaring variable names for a map element's key _and_ value
+
+For a map, the first declared variable will map to each map element's
+key.
+
+```go-html-template
+{{ range $elem_key, $elem_val := $map }}
+ {{ $elem_key }} -- {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 5: Conditional on empty _map_, _array_, or _slice_.
+
+If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated.
+
+```go-html-template
+{{ range $array }}
+ {{ . }}
+{{else}}
+ <!-- This is only evaluated if $array is empty -->
+{{ end }}
+```
+
+### Conditionals
+
+`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{ end }}`.
+
+Go Templates treat the following values as **false**:
+
+- `false` (boolean)
+- 0 (integer)
+- any zero-length array, slice, map, or string
+
+#### Example 1: `with`
+
+It is common to write "if something exists, do this" kind of
+statements using `with`.
+
+{{% note %}}
+`with` rebinds the context `.` within its scope (just like in `range`).
+{{% /note %}}
+
+It skips the block if the variable is absent, or if it evaluates to
+"false" as explained above.
+
+```go-html-template
+{{ with .Params.title }}
+ <h4>{{ . }}</h4>
+{{ end }}
+```
+
+#### Example 2: `with` .. `else`
+
+Below snippet uses the "description" front-matter parameter's value if
+set, else uses the default `.Summary` [Page variable][pagevars]:
+
+
+```go-html-template
+{{ with .Param "description" }}
+ {{ . }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+See the [`.Param` function][param].
+
+#### Example 3: `if`
+
+An alternative (and a more verbose) way of writing `with` is using
+`if`. Here, the `.` does not get rebinded.
+
+Below example is "Example 1" rewritten using `if`:
+
+```go-html-template
+{{ if isset .Params "title" }}
+ <h4>{{ index .Params "title" }}</h4>
+{{ end }}
+```
+
+#### Example 4: `if` .. `else`
+
+Below example is "Example 2" rewritten using `if` .. `else`, and using
+[`isset` function][isset] + `.Params` variable (different from the
+[`.Param` **function**][param]) instead:
+
+```go-html-template
+{{ if (isset .Params "description") }}
+ {{ index .Params "description" }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+#### Example 5: `if` .. `else if` .. `else`
+
+Unlike `with`, `if` can contain `else if` clauses too.
+
+```go-html-template
+{{ if (isset .Params "description") }}
+ {{ index .Params "description" }}
+{{ else if (isset .Params "summary") }}
+ {{ index .Params "summary" }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+#### Example 6: `and` & `or`
+
+```go-html-template
+{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
+```
+
+## Pipes
+
+One of the most powerful components of Go Templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
+
+Because of the very simple syntax of Go Templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
+
+A few simple examples should help convey how to use the pipe.
+
+### Example 1: `shuffle`
+
+The following two examples are functionally the same:
+
+```go-html-template
+{{ shuffle (seq 1 5) }}
+```
+
+
+```go-html-template
+{{ (seq 1 5) | shuffle }}
+```
+
+### Example 2: `index`
+
+The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function](/functions/index-function/), which is built into Go Templates:
+
+```go-html-template
+{{ index .Params "disqus_url" | html }}
+```
+
+### Example 3: `or` with `isset`
+
+```go-html-template
+{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
+Stuff Here
+{{ end }}
+```
+
+Could be rewritten as
+
+```go-html-template
+{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
+Stuff Here
+{{ end }}
+```
+
+### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments}
+
+By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
+
+```go-html-template
+{{ "<!--[if lt IE 9]>" | safeHTML }}
+ <script src="html5shiv.js"></script>
+{{ "<![endif]-->" | safeHTML }}
+```
+
+Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](https://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation:
+
+```go-html-template
+{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }}
+```
+
+## Context (aka "the dot") {#the-dot}
+
+The most easily overlooked concept to understand about Go Templates is
+that `{{ . }}` always refers to the **current context**.
+
+- In the top level of your template, this will be the data set made
+ available to it.
+- Inside of an iteration, however, it will have the value of the
+ current item in the loop; i.e., `{{ . }}` will no longer refer to
+ the data available to the entire page.
+
+If you need to access page-level data (e.g., page params set in front
+matter) from within the loop, you will likely want to do one of the
+following:
+
+### 1. Define a Variable Independent of Context
+
+The following shows how to define a variable independent of the context.
+
+{{< code file="tags-range-with-page-variable.html" >}}
+{{ $title := .Site.Title }}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% note %}}
+Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
+{{% /note %}}
+
+### 2. Use `$.` to Access the Global Context
+
+`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
+
+{{< code file="range-through-tags-w-global.html" >}}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $.Site.Title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% warning "Don't Redefine the Dot" %}}
+The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
+{{% /warning %}}
+
+## Whitespace
+
+Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
+
+For instance, the following Go Template will include the newlines and horizontal tab in its HTML output:
+
+```go-html-template
+<div>
+ {{ .Title }}
+</div>
+```
+
+Which will output:
+
+```html
+<div>
+ Hello, World!
+</div>
+```
+
+Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
+
+```go-html-template
+<div>
+ {{- .Title -}}
+</div>
+```
+
+Which then outputs:
+
+```html
+<div>Hello, World!</div>
+```
+
+Go considers the following characters _whitespace_:
+
+* <kbd>space</kbd>
+* horizontal <kbd>tab</kbd>
+* carriage <kbd>return</kbd>
+* newline
+
+## Comments
+
+In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo.
+
+### Go Templates comments
+
+Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
+
+For example:
+
+```go-html-template
+Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
+```
+
+Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
+
+### HTML comments
+
+If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example:
+
+```go-html-template
+{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}
+```
+
+#### HTML comments containing Go Templates
+
+HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process.
+
+{{% note %}}
+Do **not** try to comment out Go Template code using HTML comments.
+{{% /note %}}
+
+```go-html-template
+<!-- {{ $author := "Emma Goldman" }} was a great woman. -->
+{{ $author }}
+```
+
+The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error.
+
+## Hugo Parameters
+
+Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
+
+## Use Content (`Page`) Parameters
+
+You can provide variables to be used by templates in individual content's [front matter][].
+
+An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
+
+Here is the example front matter (YAML):
+
+```
+---
+title: Roadmap
+lastmod: 2017-03-05
+date: 2013-11-18
+notoc: true
+---
+```
+
+Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
+
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
+{{ if not .Params.notoc }}
+<aside>
+ <header>
+ <a href="#{{.Title | urlize}}">
+ <h3>{{.Title}}</h3>
+ </a>
+ </header>
+ {{.TableOfContents}}
+</aside>
+<a href="#" id="toc-toggle"></a>
+{{ end }}
+{{< /code >}}
+
+We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
+
+## Use Site Configuration Parameters
+
+You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
+
+For instance, you might declare the following:
+
+{{< code-toggle file="config" >}}
+params:
+ copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
+ twitteruser: "spf13"
+ sidebarrecentlimit: 5
+{{< /code >}}
+
+Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
+
+```go-html-template
+{{ if .Site.Params.copyrighthtml }}
+ <footer>
+ <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
+ </footer>
+{{ end }}
+```
+
+An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
+
+{{< code file="layouts/partials/twitter.html" >}}
+{{ with .Site.Params.twitteruser }}
+ <div>
+ <a href="https://twitter.com/{{.}}" rel="author">
+ <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
+
+```go-html-template
+<nav>
+ <h1>Recent Posts</h1>
+ <ul>
+ {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
+ <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
+ {{- end -}}
+ </ul>
+</nav>
+```
+
+## Example: Show Only Upcoming Events
+
+Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
+
+{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
+<h4>Upcoming Events</h4>
+<ul class="upcoming-events">
+{{ range where .Pages.ByDate "Section" "events" }}
+ {{ if ge .Date.Unix now.Unix }}
+ <li>
+ <!-- add span for event type -->
+ <span>{{ .Type | title }} —</span>
+ {{ .Title }} on
+ <!-- add span for event date -->
+ <span>{{ .Date.Format "2 January at 3:04pm" }}</span>
+ at {{ .Params.place }}
+ </li>
+ {{ end }}
+{{ end }}
+</ul>
+{{< /code >}}
+
+
+[`where` function]: /functions/where/
+[config]: /getting-started/configuration/
+[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
+[first]: /functions/first/
+[front matter]: /content-management/front-matter/
+[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples."
+[Go html/template]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating"
+[gohtmltemplate]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating"
++[index]: /functions/index-function/
+[math functions]: /functions/math/
+[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs"
+[internal_templates]: /templates/internal/
+[relpermalink]: /variables/page/
+[safehtml]: /functions/safehtml/
+[sitevars]: /variables/site/
+[pagevars]: /variables/page/
+[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
+[where]: /functions/where/
+[with]: /functions/with/
+[godocsindex]: https://golang.org/pkg/text/template/ "Godocs page for index function"
+[param]: /functions/param/
+[isset]: /functions/isset/
--- /dev/null
- {{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
+---
+title: Create Your Own Shortcodes
+linktitle: Shortcode Templates
+description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [shortcodes,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 100
+weight: 100
+sections_weight: 100
+draft: false
+aliases: []
+toc: true
+---
+
+Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][].
+
+{{% note %}}
+Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
+{{% /note %}}
+
+## Create Custom Shortcodes
+
+Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
+
+{{< youtube Eu4zSaKOY4A >}}
+
+### File Location
+
+To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
+
+You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
+
+```
+{{</* boxes/square */>}}
+```
+
+Note the forward slash.
+
+### Shortcode Template Lookup Order
+
+Shortcode templates have a simple [lookup order][]:
+
+1. `/layouts/shortcodes/<SHORTCODE>.html`
+2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
+
+### Positional vs Named Parameters
+
+You can create shortcodes using the following types of parameters:
+
+* Positional parameters
+* Named parameters
+* Positional *or* named parameters (i.e, "flexible")
+
+In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
+
+For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
+
+Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
+
+### Access Parameters
+
+All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
+
+To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
+
+```
+{{ .Get "class" }}
+```
+
+To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
+
+```
+{{ .Get 0 }}
+```
+
+For the second position, you would just use:
+
+```
+{{ .Get 1 }}
+```
+
+`with` is great when the output depends on a parameter being set:
+
+```
+{{ with .Get "class"}} class="{{.}}"{{ end }}
+```
+
+`.Get` can also be used to check if a parameter has been provided. This is
+most helpful when the condition depends on either of the values, or both:
+
+```
++{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
+```
+
+#### `.Inner`
+
+If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence.
+
+A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax:
+
+```
+{{</* innershortcode /*/>}}
+```
+
+#### `.Params`
+
+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`
+: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
+
+`$.Page.Params`
+: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
+
+`$.Page.Site.Params`
+: refers to global variables as defined in your [site's configuration file][config].
+
+#### `.IsNamedParams`
+
+The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
+
+For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
+
+```
+{{</* image src="images/my-image.jpg"*/>}}
+```
+
+You could then include the following as part of your shortcode templating:
+
+```
+{{ if .IsNamedParams }}
+<img src="{{.Get "src" }}" alt="">
+{{ else }}
+<img src="{{.Get 0}}" alt="">
+{{ end }}
+```
+
+See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
+
+{{% warning %}}
+While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
+{{% /warning %}}
+
+You can also use the variable `.Page` to access all the normal [page variables][pagevars].
+
+A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
+
+### Checking for Existence
+
+You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
+
+## Custom Shortcode Examples
+
+The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`.
+
+### Single-word Example: `year`
+
+Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows:
+
+```
+{{</* year */>}}
+```
+
+{{< code file="/layouts/shortcodes/year.html" >}}
+{{ now.Format "2006" }}
+{{< /code >}}
+
+### Single Positional Example: `youtube`
+
+Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
+
+```
+{{</* youtube 09jf3ow9jfw */>}}
+```
+
+Would load the template at `/layouts/shortcodes/youtube.html`:
+
+{{< code file="/layouts/shortcodes/youtube.html" >}}
+<div class="embed video-player">
+<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
+</iframe>
+</div>
+{{< /code >}}
+
+{{< code file="youtube-embed.html" copy="false" >}}
+<div class="embed video-player">
+ <iframe class="youtube-player" type="text/html"
+ width="640" height="385"
+ src="https://www.youtube.com/embed/09jf3ow9jfw"
+ allowfullscreen frameborder="0">
+ </iframe>
+</div>
+{{< /code >}}
+
+### Single Named Example: `image`
+
+Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
+
+{{< code file="content-image.md" >}}
+{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
+
+{{< code file="/layouts/shortcodes/img.html" >}}
+<!-- image -->
+<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
+ {{ with .Get "link"}}<a href="{{.}}">{{ end }}
+ <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
+ {{ if .Get "link"}}</a>{{ end }}
+ {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
+ <figcaption>{{ if isset .Params "title" }}
+ <h4>{{ .Get "title" }}</h4>{{ end }}
+ {{ if or (.Get "caption") (.Get "attr")}}<p>
+ {{ .Get "caption" }}
+ {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
+ {{ .Get "attr" }}
+ {{ if .Get "attrlink"}}</a> {{ end }}
+ </p> {{ end }}
+ </figcaption>
+ {{ end }}
+</figure>
+<!-- image -->
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="img-output.html" copy="false" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /code >}}
+
+### Single Flexible Example: `vimeo`
+
+```
+{{</* vimeo 49718712 */>}}
+{{</* vimeo id="49718712" class="flex-video" */>}}
+```
+
+Would load the template found at `/layouts/shortcodes/vimeo.html`:
+
+{{< code file="/layouts/shortcodes/vimeo.html" >}}
+{{ if .IsNamedParams }}
+ <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
+ </div>
+{{ else }}
+ <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="vimeo-iframes.html" copy="false" >}}
+<div class="vimeo-container">
+ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+<div class="flex-video">
+ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+{{< /code >}}
+
+### Paired Example: `highlight`
+
+The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
+
+{{< code file="highlight-example.md" >}}
+{{</* highlight html */>}}
+ <html>
+ <body> This HTML </body>
+ </html>
+{{</* /highlight */>}}
+{{< /code >}}
+
+The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
+
+```
+{{ .Get 0 | highlight .Inner }}
+```
+
+The rendered output of the HTML example code block will be as follows:
+
+{{< code file="syntax-highlighted.html" copy="false" >}}
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
+ <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
+<span style="color: #f92672"></html></span>
+</pre></div>
+{{< /code >}}
+
+### Nested Shortcode: Image Gallery
+
+Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
+
+The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
+
+{{< code file="layouts/shortcodes/gallery.html" >}}
+<div class="{{.Get "class"}}">
+ {{.Inner}}
+</div>
+{{< /code >}}
+
+You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+
+{{< code file="layouts/shortcodes/img.html" >}}
+{{- $src := .Get "src" -}}
+{{- with .Parent -}}
+ <img src="{{$src}}" class="{{.Get "class"}}-image">
+{{- else -}}
+ <img src="{{$src}}">
+{{- end }}
+{{< /code >}}
+
+You can then call your shortcode in your content as follows:
+
+```
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
+
+```
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+
+## Error Handling in Shortcodes
+
+Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
+
+```bash
+{{ with .Get "name" }}
+{{ else }}
+{{ errorf "missing value for param 'name': %s" .Position }}
+{{ end }}
+```
+
+When the above fails, you will see an `ERROR` log similar to the below:
+
+```bash
+ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
+```
+
+## More Shortcode Examples
+
+More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
+
+
+## Inline Shortcodes
+
+Since Hugo 0.52, you can implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place.
+
+This feature is disabled by default, but can be enabled in your site config:
+
+{{< code-toggle file="config">}}
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files.
+
+And once enabled, you can do this in your content files:
+
+ ```go-text-template
+ {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}}
+ ```
+
+The above will print the current date and time.
+
+ Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
+
+This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
+
+The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax:
+
+ ```go-text-template
+{{</* time.inline /*/>}}
+```
+
+
+[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
+[built-in shortcode]: /content-management/shortcodes/
+[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website."
+[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files."
+[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
+[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
+[figure]: /content-management/shortcodes/#figure
+[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
+[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time"
+[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates."
+[parent]: /variables/shortcodes/
+[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
+[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
+[templates]: /templates/ "The templates section of the Hugo docs."
+[vimeoexample]: #single-flexible-example-vimeo
+[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
--- /dev/null
- When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
+---
+title: Taxonomy Templates
+# linktitle:
+description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [taxonomies,metadata,front matter,terms,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 50
+weight: 50
+sections_weight: 50
+draft: false
+aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
+toc: true
+---
+
+<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND
+https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.-->
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
+
+Hugo provides multiple ways to use taxonomies throughout your project templates:
+
+* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template)
+* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template)
+* List a single content's taxonomy terms within a [single page template][]
+
+## Taxonomy List Templates
+
+Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
+
+### Taxonomy List Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Taxonomy Terms Template
+
+### Taxonomy Terms Templates Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+### Taxonomy Methods
+
+A Taxonomy is a `map[string]WeightedPages`.
+
+.Get(term)
+: Returns the WeightedPages for a term.
+
+.Count(term)
+: The number of pieces of content assigned to this term.
+
+.Alphabetical
+: Returns an OrderedTaxonomy (slice) ordered by Term.
+
+.ByCount
+: Returns an OrderedTaxonomy (slice) ordered by number of entries.
+
+.Reverse
+: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.
+
+### OrderedTaxonomy
+
+Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
+
+```go
+[]struct {
+ Name string
+ WeightedPages WeightedPages
+}
+```
+
+Each element of the slice has:
+
+.Term
+: The Term used.
+
+.WeightedPages
+: A slice of Weighted Pages.
+
+.Count
+: The number of pieces of content assigned to this term.
+
+.Pages
+: All Pages assigned to this term. All [list methods][renderlists] are available to this.
+
+## WeightedPages
+
+WeightedPages is simply a slice of WeightedPage.
+
+```go
+type WeightedPages []WeightedPage
+```
+
+.Count(term)
+: The number of pieces of content assigned to this term.
+
+.Pages
+: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
+
+## Displaying custom metadata in Taxonomy Terms Templates
+
+If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
+
+```go-html-template
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ {{ .Params.wikipedia }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+<!-- Begin /taxonomies/ordering/ -->
+
+## Order Taxonomies
+
+Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
+
+### 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 }}
+ {{ range $key, $value := .Data.Terms.Alphabetical }}
+ {{ $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/) -->
+
+## Order Content within Taxonomies
+
+Hugo uses both `date` and `weight` to order content within taxonomies.
+
+Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
+
++When iterating over content within taxonomies, the default sort is the same as that used for section and list pages first by weight then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.
++
++The default weight for any piece of content is 0.
++
++Weights of zero are treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
+
+### Assign Weight
+
+Content can be assigned weight for each taxonomy that it's assigned to.
+
+```
++++
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+title = "foo"
+categories_weight = 44
++++
+Front Matter with weighted tags and categories
+```
+
+The convention is `taxonomyname_weight`.
+
+In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
+
+It has also been assigned the weight of 44 when rendering the 'd' category.
+
+With this the same piece of content can appear in different positions in different taxonomies.
+
+Currently taxonomies only support the default ordering of content which is weight -> date.
+
+<!-- Begin /taxonomies/templates/ -->
+
+There are two different templates that the use of taxonomies will require you to provide.
+
+Both templates are covered in detail in the templates section.
+
+A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
+
+A [taxonomy terms template](/templates/terms/) is a template used to
+generate the list of terms for a given template.
+
+<!-- Begin /taxonomies/displaying/ -->
+
+There are four common ways you can display the data in your
+taxonomies in addition to the automatic taxonomy pages created by hugo
+using the [list templates](/templates/list/):
+
+1. For a given piece of content, you can list the terms attached
+2. For a given piece of content, you can list other content with the same
+ term
+3. You can list all terms for a taxonomy
+4. You can list all taxonomies (with their terms)
+
+## Display a Single Piece of Content's Taxonomies
+
+Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.
+
+Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`).
+
+### Example: List Tags in a Single Page Template
+
+{{< new-in "0.65.0" >}}
+
+```go-html-template
+<ul>
+ {{ range (.GetTerms "tags") }}
+ <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Before Hugo 0.65.0 you needed to do something like this:
+
+```go-html-template
+{{ $taxo := "tags" }} <!-- Use the plural form here -->
+<ul id="{{ $taxo }}">
+ {{ range .Param $taxo }}
+ {{ $name := . }}
+ {{ with $.Site.GetPage (printf "/%s/%s" $taxo ($name | urlize)) }}
+ <li><a href="{{ .Permalink }}">{{ $name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
+
+To list such taxonomies, use the following:
+
+### Example: Comma-delimit Tags in a Single Page Template
+
+```go-html-template
+{{ $taxo := "directors" }} <!-- Use the plural form here -->
+{{ with .Param $taxo }}
+ <strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong>
+ {{ range $index, $director := . }}
+ {{- if gt $index 0 }}, {{ end -}}
+ {{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}}
+ <a href="{{ .Permalink }}">{{ $director }}</a>
+ {{- end -}}
+ {{- end -}}
+{{ end }}
+```
+
+Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
+
+## List Content with the Same Taxonomy Term
+
+If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
+
+### Example: Showing Content in Same Series
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.series.golang }}
+ <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+## List All content in a Given taxonomy
+
+This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
+
+### Example: Grouping "Featured" Content
+
+```go-html-template
+<section id="menu">
+ <ul>
+ {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
+ <li>{{ $key }}</li>
+ <ul>
+ {{ range $taxonomy.Pages }}
+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+</section>
+```
+
+## Render a Site's Taxonomies
+
+If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
+
+This may take the form of a tag cloud, a menu, or simply a list.
+
+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 }}
+ {{ with $.Site.GetPage (printf "/tags/%s" $name) }}
+ <li><a href="{{ .Permalink }}">{{ $name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+### Example: List All Taxonomies, Terms, and Assigned Content
+
+This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
+
+{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
+<section>
+ <ul id="all-taxonomies">
+ {{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}
+ {{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }}
+ <li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a>
+ <ul>
+ {{ range $key, $value := $taxonomy }}
+ <li>{{ $key }}</li>
+ <ul>
+ {{ range $value.Pages }}
+ <li hugo-nav="{{ .RelPermalink}}">
+ <a href="{{ .Permalink}}">{{ .LinkTitle }}</a>
+ </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+ </li>
+ {{ end }}
+ {{ end }}
+ </ul>
+</section>
+{{< /code >}}
+
+## `.Site.GetPage` for Taxonomies
+
+Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above]({{< relref "#example-list-all-site-tags" >}}):
+
+{{< code file="links-to-all-tags.html" >}}
+{{ $taxo := "tags" }}
+<ul class="{{ $taxo }}">
+ {{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
+ {{ range .Pages }}
+ <li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+{{< /code >}}
+
+<!-- TODO: ### `.Site.GetPage` Taxonomy List Example -->
+
+<!-- TODO: ### `.Site.GetPage` Taxonomy Terms Example -->
+
+
+[delimit]: /functions/delimit/
+[getpage]: /functions/getpage/
+[lists]: /templates/lists/
+[renderlists]: /templates/lists/
+[single page template]: /templates/single-page-templates/
+[sitevars]: /variables/site/
--- /dev/null
+---
+title: Page Variables
+linktitle:
+description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [variables and params]
+keywords: [pages]
+draft: false
+menu:
+ docs:
+ title: "variables defined by a page"
+ parent: "variables"
+ weight: 20
+weight: 20
+sections_weight: 20
+aliases: []
+toc: true
+---
+
+The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself.
+
+{{% note "`.Scratch`" %}}
+See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
+{{% /note %}}
+
+## Page Variables
+
+.AlternativeOutputFormats
+: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's `<head>`. (See [Output Formats](/templates/output-formats/).)
+
+.Aliases
+: aliases of this page
+
+.Content
+: the content itself, defined below the front matter.
+
+.Data
+: the data specific to this type of page.
+
+.Date
+: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`.
+
+.Description
+: the description for the page.
+
+.Dir
+: the path of the folder containing this content file. The path is relative to the `content` folder.
+
+.Draft
+: a boolean, `true` if the content is marked as a draft in the front matter.
+
+.ExpiryDate
+: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`.
+
+.File
+: filesystem-related data for this content file. See also [File Variables][].
+
+.FuzzyWordCount
+: the approximate number of words in the content.
+
+.Hugo
+: see [Hugo Variables](/variables/hugo/).
+
+.IsHome
+: `true` in the context of the [homepage](/templates/homepage/).
+
+.IsNode
+: always `false` for regular content pages.
+
+.IsPage
+: always `true` for regular content pages.
+
++.IsSection
++: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`.
++
+.IsTranslated
+: `true` if there are translations to display.
+
+.Keywords
+: the meta keywords for the content.
+
+.Kind
+: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
+
+.Language
+: a language object that points to the language's definition in the site `config`. `.Language.Lang` gives you the language code.
+
+.Lastmod
+: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter.
+
+ - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used.
+ - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead.
+
+See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
+
+.LinkTitle
+: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
+
+.Next
+: Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{with .Next}}{{.Permalink}}{{end}}`. Calling `.Next` from the first page returns `nil`.
+
+.NextInSection
+: Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{with .NextInSection}}{{.Permalink}}{{end}}`. Calling `.NextInSection` from the first page returns `nil`.
+
+.OutputFormats
+: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)
+
+.Pages
+: a collection of associated pages. This value will be `nil` within
+ the context of regular content pages. See [`.Pages`](#pages).
+
+.Permalink
+: the Permanent link for this page; see [Permalinks](/content-management/urls/)
+
+.Plain
+: the Page content stripped of HTML tags and presented as a string.
+
+.PlainWords
+: the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice.
+
+.Prev
+: Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath)). Example: `{{if .PrevPage}}{{.PrevPage.Permalink}}{{end}}`. Calling `.Prev` from the last page returns `nil`.
+
+.PrevInSection
+: Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight-date-linktitle-filepath). Example: `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. Calling `.PrevInSection` from the last page returns `nil`.
+
+.PublishDate
+: 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)
+: link to the page's RSS feed. This is deprecated. You should instead do something like this: `{{ with .OutputFormats.Get "RSS" }}{{ .RelPermalink }}{{ end }}`.
+
+.RawContent
+: raw markdown content without the front matter. Useful with [remarkjs.com](
+https://remarkjs.com)
+
+.ReadingTime
+: the estimated time, in minutes, it takes to read the content.
+
+.Resources
+: resources such as images and CSS that are associated with this page
+
+.Ref
+: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
+
+.RelPermalink
+: the relative permanent link for this page.
+
+.RelRef
+: returns the relative permalink for a given reference (e.g., `RelRef
+"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
+
+.Site
+: see [Site Variables](/variables/site/).
+
+.Sites
+: returns all sites (languages). A typical use case would be to link back to the main language: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`.
+
+.Sites.First
+: returns the site for the first language. If this is not a multilingual setup, it will return itself.
+
+.Summary
+: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code><!--more--></code> at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details.
+
+.TableOfContents
+: the rendered [table of contents](/content-management/toc/) for the page.
+
+.Title
+: the title for this page.
+
+.Translations
+: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
+
+.TranslationKey
+: the key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
+
+.Truncated
+: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information.
+
+.Type
+: the [content type](/content-management/types/) of the content (e.g., `posts`).
+
+.UniqueID (deprecated)
+: the MD5-checksum of the content file's path. This variable is deprecated and will be removed, use `.File.UniqueID` instead.
+
+.Weight
+: assigned weight (in the front matter) to this content, used in sorting.
+
+.WordCount
+: the number of words in the content.
+
+## Section Variables and Methods
+
+Also see [Sections](/content-management/sections/).
+
+{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
+
+## The `.Pages` Variable {#pages}
+
+`.Pages` is an alias to `.Data.Pages`. It is conventional to use the
+aliased form `.Pages`.
+
+### `.Pages` compared to `.Site.Pages`
+
+{{< readfile file="/content/en/readfiles/pages-vs-site-pages.md" markdown="true" >}}
+
+## Page-level Params
+
+Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
+
+```
+---
+title: My First Post
+date: 2017-02-20T15:26:23-06:00
+categories: [one]
+tags: [two,three,four]
+```
+
+With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
+
+* `.Params.tags`
+* `.Params.categories`
+
+{{% note "Casing of Params" %}}
+Page-level `.Params` are *only* accessible in lowercase.
+{{% /note %}}
+
+The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
+
+```
+---
+...
+affiliatelink: "http://www.my-book-link.here"
+recommendedby: "My Mother"
+...
+---
+```
+
+These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
+
+Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
+
+{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
+<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
+<p>It was recommended by {{ .Params.recommendedby }}.</p>
+{{< /code >}}
+
+This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
+
+{{< output file="yourbaseurl/review/book01/index.html" >}}
+<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
+<p>It was recommended by my Mother.</p>
+{{< /output >}}
+
+{{% note %}}
+See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
+{{% /note %}}
+
+### The `.Param` Method
+
+In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image):
+
+```
+{{ $.Param "header_image" }}
+```
+
+The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`).
+
+### Access Nested Fields in Front Matter
+
+When front matter contains nested fields like the following:
+
+```
+---
+author:
+ given_name: John
+ family_name: Feminella
+ display_name: John Feminella
+---
+```
+`.Param` can access these fields by concatenating the field names together with a dot:
+
+```
+{{ $.Param "author.display_name" }}
+```
+
+If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case:
+
+```
+---
+favorites.flavor: vanilla
+favorites:
+ flavor: chocolate
+---
+```
+
+The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`:
+
+```
+{{ $.Param "favorites.flavor" }}
+=> vanilla
+```
+
+[gitinfo]: /variables/git/
+[File Variables]: /variables/files/
projects / brevno-suite / hugo / commitdiff