--- /dev/null
- "mmark",
+{
+ "version": "0.2",
+ "words": [
+ "aaabaab",
+ "aabb",
+ "aabba",
+ "aabbaa",
+ "aabbaabb",
+ "aabbaabbab",
+ "abbaa",
+ "abourget",
+ "absurl",
+ "adoc",
+ "algolia",
+ "allowfullscreen",
+ "ananke",
+ "anchorize",
+ "anthonyfok",
+ "asciidoctor",
+ "attrlink",
+ "azblob",
+ "baseof",
+ "bbaa",
+ "bcde",
+ "bcdef",
+ "beevelop",
+ "Bergevin",
+ "bibtex",
+ "Bjørn",
+ "blackfriday",
+ "blogue",
+ "bogem",
+ "Bootcamp",
+ "brlink",
+ "Brotli",
+ "Browsersync",
+ "canonify",
+ "Catmull",
+ "Catwoman",
+ "changefreq",
+ "Cheatsheet",
+ "choco",
+ "chromastyles",
+ "clockoon",
+ "Cloudinary",
+ "CNAME",
+ "Codecademy's",
+ "CODEOWNERS",
+ "Coen",
+ "Commento",
+ "Cond",
+ "contentdir",
+ "Contentful",
+ "Copr",
+ "copyrighthtml",
+ "corejs",
+ "countrunes",
+ "countwords",
+ "crossreferences",
+ "daftaupe",
+ "datatable",
+ "DATOCMS",
+ "debugconfig",
+ "DELIM",
+ "dhersam",
+ "digitalcraftsman",
+ "Disqus",
+ "Dmdh",
+ "doas",
+ "dokuwiki",
+ "dpkg",
+ "DRING",
+ "Eiqc",
+ "Eliott",
+ "Emojify",
+ "Enwrite",
+ "eopkg",
+ "eparis",
+ "errorf",
+ "erroridf",
+ "Evernote",
+ "exitwp",
+ "expirydate",
+ "Feminella",
+ "firstpost",
+ "Formspree",
+ "fpath",
+ "Francia",
+ "freenode",
+ "frontmatter",
+ "funcs",
+ "funcsig",
+ "Garen",
+ "gcloud",
+ "Getenv",
+ "getjson",
+ "getpage",
+ "Gmfc",
+ "Goel",
+ "Gohugo",
+ "gohugoio",
+ "goldenbridge",
+ "Goldmark",
+ "gomodules",
+ "GOPATH",
+ "govendor",
+ "Gowans",
+ "Grayscale",
+ "Gruber",
+ "gtag",
+ "gvfs",
+ "hidecaption",
+ "hmac",
+ "Hokus",
+ "hola",
+ "hügó",
+ "hugodeps",
+ "hugodoc",
+ "Hugofy",
+ "hugolang",
+ "hugoversion",
+ "Hyas",
+ "Hyvor",
+ "iframes",
+ "ifttt",
+ "iife",
+ "imgproc",
+ "importr",
+ "IMWQ",
+ "indice",
+ "innershortcode",
+ "Intelli",
+ "interdoc",
+ "IPTC",
+ "ismenucurrent",
+ "Isset",
+ "Isso",
+ "Jaco",
+ "JIRN",
+ "johnpatitucci",
+ "Joomla",
+ "JRBR",
+ "jsonify",
+ "katex",
+ "keycdn",
+ "KEYVALS",
+ "kubernetes",
+ "Lanczos",
+ "langformatnumber",
+ "lastmod",
+ "libwebp",
+ "linktitle",
+ "Lipi",
+ "lrwxr",
+ "maingo",
+ "markdownified",
+ "markdownify",
+ "mathjax",
+ "mdhender",
+ "mdshortcode",
+ "MENUENTRY",
+ "mercredi",
+ "Milli",
+ "Mittwoch",
+ "mkdir",
+ "modh",
+ "monokai",
+ "Morling",
+ "mspowerpoint",
+ "Multihost",
+ "Muut",
+ "myclass",
+ "mydeployment",
+ "myindex",
+ "mylayout",
+ "mylogin",
+ "mypage",
+ "mypartials",
+ "mypost",
+ "mysite",
+ "myspa",
+ "mystyle",
+ "mytextpartial",
+ "mytheme",
+ "NDJSON",
+ "needsexample",
+ "Netravali",
+ "newparam",
+ "Nichlas",
+ "Nikhil",
+ "Njjy",
+ "nlist",
+ "nobr",
+ "nocopy",
+ "Norsk",
+ "nosniff",
+ "NOSQL",
+ "notoc",
+ "novembre",
+ "numfmt",
+ "NUMWORKERMULTIPLIER",
+ "Obhu",
+ "octohug",
+ "Octopress",
+ "oldparam",
+ "onrender",
+ "opengraph",
+ "OWASP",
+ "Pandoc",
+ "partialcached",
+ "Pastorius",
+ "Patitucci",
+ "PCRE",
+ "peaceiris",
+ "Pedersen",
+ "Pekka",
+ "permalinkable",
+ "plainify",
+ "POSIX",
+ "postprocess",
+ "Poupin",
+ "prerender",
+ "println",
+ "publishdate",
+ "Pygments",
+ "qref",
+ "querify",
+ "QVOMC",
+ "Racic",
+ "Rclone",
+ "rdwatters",
+ "readfile",
+ "rebinded",
+ "recommendedby",
+ "REDIR",
+ "reftext",
+ "relatedfuncs",
+ "relref",
+ "relurl",
+ "remarkjs",
+ "rgba",
+ "Riku",
+ "rlimit",
+ "roboto",
+ "rssxml",
+ "rwxrwxrwx",
+ "RYUGV",
+ "safehtml",
+ "safejs",
+ "Samsa",
+ "schemaorg",
+ "Shekhar",
+ "Shortcode",
+ "Shortcodes",
+ "signup",
+ "Silvola",
+ "Sindre",
+ "sitemapindex",
+ "sitemapxml",
+ "Smartcrop",
+ "Sprintf",
+ "Startseite",
+ "strconv",
+ "stringifier",
+ "struct",
+ "structs",
+ "subdir",
+ "svgs",
+ "symdiff",
+ "Talkyard",
+ "taxo",
+ "taxonomyname",
+ "tbody",
+ "tdewolff",
+ "testshortcodes",
+ "thead",
+ "Thinkful",
+ "Tknx",
+ "TLDR",
+ "TMPDIR",
+ "TOCSS",
+ "todos",
+ "tojson",
+ "Tomango",
+ "topologix",
+ "Torikian",
+ "totoml",
+ "toyaml",
+ "twitteruser",
+ "Unmarshal",
+ "urlize",
+ "urlset",
+ "utimestamp",
+ "vendored",
+ "vimrc",
+ "wanghc",
+ "Wappalyzer",
+ "warnf",
+ "webp",
+ "Wercker",
+ "wibble",
+ "wordcount",
+ "workson",
+ "wpxr",
+ "Xbaabbab",
+ "xvzf",
+ "yoyoyo",
+ "Zgotmpl",
+ "zzbbaabb",
+ "مدونتي"
+ ],
+ "language": "en,en-GB,en-US,de,fr",
+ "allowCompoundWords": true,
+ "files": [
+ "**/*.md"
+ ],
+ "ignoreRegExpList": [
+ "<!-- prettier-ignore -->\\n(`{3,})\\w*\\n[\\s\\S]+?\\1",
+ "\\[(\\*{2})?@\\w+?\\1\\]",
+ "\\[`\\w+`\\]",
+ "ve{2,}r{2,}y",
+ "ve+r+y+long\\w*",
+ "\\/.*?\\/",
+ "\\_\\w+",
+ "\\#\\w+"
+ ],
+ "ignorePaths": [
+ ".cspell.json",
+ "**/node_modules/**",
+ "*.min.*",
+ "**/news/*",
+ "**/showcase/*"
+ ],
+ "useGitignore": true
+}
--- /dev/null
- [Dynamic menu]: /templates/menus/
+---
+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
+* Support for [Go][] HTML templates
+* [Syntax highlighting][] powered by [Chroma][]
+
+
+[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/
- [Powerful theming]: /themes/
++[Dynamic menu]: /templates/menu-templates/
+[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
- [Syntax highlighting]: /tools/syntax-highlighting/
++[Powerful theming]: /hugo-modules/theme-components/
+[Pretty URLs]: /content-management/urls/
+[RSS]: /templates/rss/
+[Shortcodes]: /content-management/shortcodes/
+[sort content]: /templates/
+[supported formats]: /content-management/formats/
++[Syntax highlighting]: /content-management/syntax-highlighting/
+[table of contents]: /content-management/toc/
+[taxonomies]: /content-management/taxonomies/
+[URLs]: /content-management/urls/
--- /dev/null
- [disquspartial]: /templates/partials/#disqus
+---
+title: Comments
+linktitle: Comments
+description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-09
+keywords: [sections,content,organization]
+categories: [project organization, fundamentals]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 140
+weight: 140 #rem
+draft: false
+aliases: [/extras/comments/]
+toc: true
+---
+
+Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
+
+Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
+
+## Add Disqus
+
+Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
+
+### Configure Disqus
+
+Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
+
+{{< code-toggle copy="false" >}}
+disqusShortname = "yourDisqusShortname"
+{{</ code-toggle >}}
+
+For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:
+
+* `disqus_identifier`
+* `disqus_title`
+* `disqus_url`
+
+### Render Hugo's Built-in Disqus Partial Template
+
+Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear:
+
+```
+{{ template "_internal/disqus.html" . }}
+```
+
+## Alternatives
+
+These are some alternatives to Disqus:
+
+* [Cactus Comments](https://cactus.chat/docs/integrations/hugo/) (Open Source, Matrix appservice, Docker install)
+* [Commento](https://commento.io/) (Open Source, available as a service, local install, or docker image)
+* [Graph Comment](https://graphcomment.com/)
+* [Hyvor Talk](https://talk.hyvor.com/) (Available as a service)
+* [IntenseDebate](https://intensedebate.com/)
+* [Isso](https://posativ.org/isso/) (Self-hosted, Python) ([tutorial][issotutorial])
+* [Muut](https://muut.com/)
+* [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker)
+* [Staticman](https://staticman.net/)
+* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting)
+* [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues)
+
+[configuration]: /getting-started/configuration/
++[disquspartial]: /templates/internal/#disqus
+[disqussetup]: https://disqus.com/profile/signup/
+[forum]: https://discourse.gohugo.io
+[front matter]: /content-management/front-matter/
+[kaijuissue]: https://github.com/spf13/kaiju/issues/new
+[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
+[partials]: /templates/partials/
+[MongoDB]: https://www.mongodb.com/
+[tweet]: https://twitter.com/spf13
--- /dev/null
- keywords: [markdown,asciidoc,mmark,pandoc,content format]
+---
+title: Content Formats
+linktitle: Content Formats
+description: Both HTML and Markdown are supported content formats.
+date: 2017-01-10
+publishdate: 2017-01-10
+categories: [content management]
- |MMark|mmark|Mmark is deprecated and will be removed in a future release.|
++keywords: [markdown,asciidoc,pandoc,content format]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 20
+weight: 20 #rem
+draft: false
+aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
+toc: true
+---
+
+You can put any file type into your `/content` directories, but Hugo uses the `markup` front matter value if set or the file extension (see `Markup identifiers` in the table below) to determine if the markup needs to be processed, e.g.:
+
+* Markdown converted to HTML
+* [Shortcodes](/content-management/shortcodes/) processed
+* Layout applied
+
+## List of content formats
+
+The current list of content formats in Hugo:
+
+| Name | Markup identifiers | Comment |
+| ------------- | ------------- |-------------|
+| Goldmark | md, markdown, goldmark |Note that you can set the default handler of `md` and `markdown` to something else, see [Configure Markup](/getting-started/configuration-markup/).{{< new-in "0.60.0" >}} |
+| Blackfriday | blackfriday |Blackfriday will eventually be deprecated.|
- [mmark]: https://github.com/miekg/mmark
+|Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).|
+|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.|
+|RST|rst|Needs [RST](https://docutils.sourceforge.io/rst.html) installed.|
+|Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.|
+|HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
+
+The `markup identifier` is fetched from either the `markup` variable in front matter or from the file extension. For markup-related configuration, see [Configure Markup](/getting-started/configuration-markup/).
+
+## External Helpers
+
+Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files,
+Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated
+tool on your machine to be able to use these formats.
+
+Hugo passes reasonable default arguments to these external helpers by default:
+
+- `asciidoctor`: `--no-header-footer -`
+- `rst2html`: `--leave-comments --initial-header-level=2`
+- `pandoc`: `--mathjax`
+
+{{% warning "Performance of External Helpers" %}}
+Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
+{{% /warning %}}
+
+### External Helper AsciiDoc
+
+[AsciiDoc](https://github.com/asciidoc/asciidoc) implementation EOLs in Jan 2020 and is no longer supported.
+AsciiDoc development is being continued under [Asciidoctor](https://github.com/asciidoctor). The format AsciiDoc
+remains of course. Please continue with the implementation Asciidoctor.
+
+### External Helper Asciidoctor
+
+The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.
+[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all
+optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required.
+
+{{% note %}}
+External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`.
+{{% /note %}}
+
+Some [Asciidoctor](https://asciidoctor.org/man/asciidoctor/) parameters can be customized in Hugo:
+
+Parameter | Comment
+--- | ---
+backend | Don't change this unless you know what you are doing.
+doctype | Currently, the only document type supported in Hugo is `article`.
+extensions | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`.
+attributes | Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See [Asciidoctor's attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions).
+noHeaderOrFooter | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing.
+safeMode | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing.
+sectionNumbers | Auto-number section titles.
+verbose | Verbosely print processing information and configuration file checks to stderr.
+trace | Include backtrace information on errors.
+failureLevel | The minimum logging level that triggers a non-zero exit code (failure).
+
+Hugo provides additional settings that don't map directly to Asciidoctor's CLI options:
+
+workingFolderCurrent
+: Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering diagrams with [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/), `workingFolderCurrent` must be set to `true`.
+
+preserveTOC
+: By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable [`.TableOfContents`](/content-management/toc/) to enable further customization and better integration with the various Hugo themes. This option can be set to `true` to preserve Asciidoctor's TOC in the generated page.
+
+Below are all the AsciiDoc related settings in Hugo with their default values:
+
+{{< code-toggle config="markup.asciidocExt" />}}
+
+Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in one's ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted.
+
+Example of how to set extensions and attributes:
+
+```
+[markup.asciidocExt]
+ extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
+ workingFolderCurrent = true
+ [markup.asciidocExt.attributes]
+ my-base-url = "https://example.com/"
+ my-attribute-name = "my value"
+```
+
+In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all
+parameters. Run Hugo with `-v`. You will get an output like
+
+```
+INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
+```
+
+## Learn Markdown
+
+Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
+
+* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
+* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
+* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
+* [The Markdown Guide, Matt Cone][mdguide]
+
+[`emojify` function]: /functions/emojify/
+[ascii]: https://asciidoctor.org/
+[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering
+[blackfriday]: https://github.com/russross/blackfriday
- [Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/
+[config]: /getting-started/configuration/
+[developer tools]: /tools/
+[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/
+[fireball]: https://daringfireball.net/projects/markdown/
+[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
+[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
+[hl]: /content-management/syntax-highlighting/
+[hlsc]: /content-management/shortcodes/#highlight
+[hugocss]: /css/style.css
+[ietf]: https://tools.ietf.org/html/
+[mathjaxdocs]: https://docs.mathjax.org/en/latest/
+[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
+[mdguide]: https://www.markdownguide.org/
+[mdtutorial]: https://www.markdowntutorial.com/
+[org]: https://orgmode.org/
+[pandoc]: https://www.pandoc.org/
+[rest]: https://docutils.sourceforge.io/rst.html
+[sc]: /content-management/shortcodes/
+[sct]: /templates/shortcode-templates/
--- /dev/null
- : the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype]
+---
+title: Front Matter
+linktitle:
+description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+date: 2017-01-09
+publishdate: 2017-01-09
+lastmod: 2017-02-24
+categories: [content management]
+keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 30
+weight: 30 #rem
+draft: false
+aliases: [/content/front-matter/]
+toc: true
+---
+
+**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+
+{{< youtube Yh2xKRJGff4 >}}
+
+## Front Matter Formats
+
+Hugo supports four formats for front matter, each with their own identifying tokens.
+
+TOML
+: identified by opening and closing `+++`.
+
+YAML
+: identified by opening and closing `---`.
+
+JSON
+: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+
+ORG
+: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
+ Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
+
+### Example
+
+{{< code-toggle >}}
+title = "spf13-vim 3.0 release and new website"
+description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+date = "2012-04-06"
+categories = [
+ "Development",
+ "VIM"
+]
+slug = "spf13-vim-3-0-release-and-new-website"
+{{< /code-toggle >}}
+
+## Front Matter Variables
+
+### Predefined
+
+There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+
+aliases
+: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+
+audio
+: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
+
+cascade
+: a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
+
+date
+: the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behaviour is configurable.
+
+description
+: the description for the content.
+
+draft
+: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+
+expiryDate
+: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+
+headless
+: if `true`, sets a leaf bundle to be [headless][headless-bundle].
+
+images
+: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
+
+isCJKLanguage
+: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+
+keywords
+: the meta keywords for the content.
+
+layout
- [definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
++: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
+
+lastmod
+: the datetime at which the content was last modified.
+
+linkTitle
+: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
+
+markup
+: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+
+outputs
+: allows you to specify output formats specific to the content. See [output formats][outputs].
+
+publishDate
+: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+
+resources
+: used for configuring page bundle resources. See [Page Resources][page-resources].
+
+series
+: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
+
+slug
+: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
+
+summary
+: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+
+title
+: the title for the content.
+
+type
+: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
+
+url
+: the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
+
+videos
+: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
+
+weight
+: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
+
+\<taxonomies\>
+: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._
+
+{{% note "Hugo's Default URL Destinations" %}}
+If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
+{{% /note %}}
+
+### User-Defined
+
+You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+
+The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+{{< code-toggle copy="false" >}}
+include_toc: true
+show_comments: false
+{{</ code-toggle >}}
+
+## Front Matter Cascade
+
+Any node or section can pass down to descendants a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key.
+
+### Target Specific Pages
+
+{{< new-in "0.76.0" >}}
+
+Since Hugo 0.76 the `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
+
+{{< code-toggle copy="false" >}}
+title ="Blog"
+[[cascade]]
+background = "yosemite.jpg"
+[cascade._target]
+path="/blog/**"
+lang="en"
+kind="page"
+[[cascade]]
+background = "goldenbridge.jpg"
+[cascade._target]
+kind="section"
+{{</ code-toggle >}}
+
+Keywords available for `_target`:
+
+path
+: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching support double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
+
+kind
+: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+
+lang
+: A Glob pattern matching the Page's language, e.g. "{en,sv}".
+
+environment
+: A Glob pattern matching the build environment, e.g. "{production,development}"
+
+Any of the above can be omitted.
+
+### Example
+
+In `content/blog/_index.md`
+
+{{< code-toggle copy="false" >}}
+title: Blog
+cascade:
+ banner: images/typewriter.jpg
+{{</ code-toggle >}}
+
+With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
+
+- Said descendant has its own `banner` value set
+- Or a closer ancestor node has its own `cascade.banner` value set.
+
+
+
+## Order Content Through Front Matter
+
+You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+
+## Override Global Markdown Configuration
+
+It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config].
+
+## Front Matter Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[variables]: /variables/
+[aliases]: /content-management/urls/#aliases
+[archetype]: /content-management/archetypes/
+[bylinktitle]: /templates/lists/#by-link-title
+[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
+[content type]: /content-management/types/
+[contentorg]: /content-management/organization/
- [lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
+[headless-bundle]: /content-management/page-bundles/#headless-bundle
+[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
++[lists]: /templates/lists/#order-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
+[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
+[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
+[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
+[page-resources]: /content-management/page-resources/
+[pagevars]: /variables/page/
+[section]: /content-management/sections/
+[taxweight]: /content-management/taxonomies/
+[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
+[urls]: /content-management/urls/
+[variables]: /variables/
+[yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
--- /dev/null
- [lang.FormatNumberCustom]: functions/lang/#langformatnumbercustom
+---
+title: Multilingual Mode
+linktitle: Multilingual
+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]
+
+## 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"
+
+[languages.pt-pt]
+title = "O meu blog"
+weight = 3
+{{< /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], 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.
+
+**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344)
+
+### Disable a Language
+
+You can disable one or more languages. This can be useful when working on a new translation.
+
+{{< code-toggle file="config" >}}
+disableLanguages = ["fr", "ja"]
+{{< /code-toggle >}}
+
+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]:
+
+```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:
+
+```text
+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:
+
+```text
+Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1)
+Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
+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`
+
+{{< code-toggle >}}
+translationKey: "about"
+{{< /code-toggle >}}
+
+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.
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7](https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7) are also supported. You may omit the `art-x-` prefix for brevity. For example:
+
+```text
+art-x-hugolang
+hugolang
+```
+
+Private use subtags must not exceed 8 alphanumeric characters.
+
+### Query basic translation
+
+From within your templates, use the `i18n` function like this:
+
+```go-html-template
+{{ i18n "home" }}
+```
+
+The function will search for the `"home"` id:
+
+{{< code-toggle file="i18n/en-US" >}}
+[home]
+other = "Home"
+{{< /code-toggle >}}
+
+The result will be
+
+```text
+Home
+```
+
+### Query a flexible translation with variables
+
+Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
+
+```go-html-template
+{{ i18n "wordCount" . }}
+```
+
+The function will pass the `.` context to the `"wordCount"` id:
+
+{{< code-toggle file="i18n/en-US" >}}
+[wordCount]
+other = "This article has {{ .WordCount }} words."
+{{< /code-toggle >}}
+
+Assume `.WordCount` in the context has value is 101. The result will be:
+
+```text
+This article has 101 words.
+```
+
+### Query a singular/plural translation
+
+In order to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property.
+
+```go-html-template
+{{ 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:
+
+{{< code-toggle file="i18n/en-US" >}}
+[readingTime]
+one = "One minute to read"
+other = "{{.Count}} minutes to read"
+{{< /code-toggle >}}
+
+Assume `.ReadingTime.Count` in the context has value of 525600. The result will be:
+
+```text
+525600 minutes to read
+```
+
+If `.ReadingTime.Count` in the context has value is 1. The result is:
+
+```text
+One minute to read
+```
+
+In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement)
+
+```go-html-template
+{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }}
+```
+
+## Localization
+
+The following localization examples assume your site's primary language is English, with translations to French and German.
+
+{{< code-toggle file="config" >}}
+defaultContentLang = 'en'
+
+[languages]
+[languages.en]
+contentDir = 'content/en'
+languageName = 'English'
+weight = 1
+[languages.fr]
+contentDir = 'content/fr'
+languageName = 'Français'
+weight = 2
+[languages.de]
+contentDir = 'content/de'
+languageName = 'Deutsch'
+weight = 3
+
+{{< /code-toggle >}}
+
+### Dates
+
+With this front matter:
+
+{{< code-toggle >}}
+date = 2021-11-03T12:34:56+01:00
+{{< /code-toggle >}}
+
+And this template code:
+
+```go-html-template
+{{ .Date | time.Format ":date_full" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|Wednesday, November 3, 2021
+Français|mercredi 3 novembre 2021
+Deutsch|Mittwoch, 3. November 2021
+
+See [time.Format] for details.
+
+### Currency
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatCurrency 2 "USD" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|$512.50
+Français|512,50 $US
+Deutsch|512,50 $
+
+See [lang.FormatCurrency] and [lang.FormatAccounting] for details.
+
+### Numbers
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatNumber 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50
+Français|512,50
+Deutsch|512,50
+
+See [lang.FormatNumber] and [lang.FormatNumberCustom] for details.
+
+### Percentages
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatPercent 2 }} ---> 512.50%
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50%
+Français|512,50 %
+Deutsch|512,50 %
+
+See [lang.FormatPercent] for details.
+
+## 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:
+
+{{< code-toggle file="config" >}}
+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
+{{< /code-toggle >}}
+
+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.
+
+```go-html-template
+<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].
+
+To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
+
+```bash
+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/
+[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/
+[i18func]: /functions/i18n/
+[lang.FormatAccounting]: /functions/lang/#langformataccounting
+[lang.FormatCurrency]: /functions/lang/#langformatcurrency
+[lang.FormatNumber]: /functions/lang/#langformatnumber
++[lang.FormatNumberCustom]: /functions/lang/#langformatnumbercustom
+[lang.FormatPercent]: /functions/lang/#langformatpercent
+[lang.Merge]: /functions/lang.merge/
+[menus]: /content-management/menus/
+[OS environment]: /getting-started/configuration/#configure-with-environment-variables
+[rellangurl]: /functions/rellangurl
+[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[single page templates]: /templates/single-page-templates/
+[time.Format]: /functions/dateformat
--- /dev/null
- This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+---
+title: Shortcodes
+linktitle:
+description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2019-11-07
+menu:
+ docs:
+ parent: "content-management"
+ weight: 35
+weight: 35 #rem
+categories: [content management]
+keywords: [markdown,content,shortcodes]
+draft: false
+aliases: [/extras/shortcodes/]
+testparam: "Hugo Rocks!"
+toc: true
+---
+
+## What a Shortcode is
+
+Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+
+Hugo created **shortcodes** to circumvent these limitations.
+
+A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+
+In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+
+## Use Shortcodes
+
+{{< youtube 2xkNJL4gJ9E >}}
+
+In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+
+The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
+
+Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+
+Here are two examples of paired shortcodes:
+
+```
+{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```
+
+```
+{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+```
+
+The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+
+### Shortcodes with raw string parameters
+
+{{< new-in "0.64.1" >}}
+
+You can pass multiple lines as parameters to a shortcode by using raw string literals:
+
+```
+{{</* myshortcode `This is some <b>HTML</b>,
+and a new line with a "quoted string".` */>}}
+```
+
+### Shortcodes with Markdown
+
+In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc.
+
+If you want the old behavior, you can put the following line in the start of your shortcode template:
+
+```
+{{ $_hugo_config := `{ "version": 1 }` }}
+```
+
+
+### Shortcodes Without Markdown
+
+The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
+
+```
+{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
+```
+
+### Nested Shortcodes
+
+You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+
+## Use Hugo's Built-in Shortcodes
+
+Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
+
+### `figure`
+
+`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
+
+The `figure` shortcode can use the following named parameters:
+
+src
+: URL of the image to be displayed.
+
+link
+: If the image needs to be hyperlinked, URL of the destination.
+
+target
+: Optional `target` attribute for the URL if `link` parameter is set.
+
+rel
+: Optional `rel` attribute for the URL if `link` parameter is set.
+
+alt
+: Alternate text for the image if the image cannot be displayed.
+
+title
+: Image title.
+
+caption
+: Image caption. Markdown within the value of `caption` will be rendered.
+
+class
+: `class` attribute of the HTML `figure` tag.
+
+height
+: `height` attribute of the image.
+
+width
+: `width` attribute of the image.
+
+attr
+: Image attribution text. Markdown within the value of `attr` will be rendered.
+
+attrlink
+: If the attribution text needs to be hyperlinked, URL of the destination.
+
+#### Example `figure` Input
+
+{{< code file="figure-input-example.md" >}}
+{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+#### Example `figure` Output
+
+{{< output file="figure-output-example.html" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /output >}}
+
+### `gist`
+
+Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
+
+```
+https://gist.github.com/spf13/7896402
+```
+
+We can embed the gist in our content via username and gist ID pulled from the URL:
+
+```
+{{</* gist spf13 7896402 */>}}
+```
+
+#### Example `gist` Input
+
+If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
+
+{{< code file="gist-input.md" >}}
+{{</* gist spf13 7896402 "img.html" */>}}
+{{< /code >}}
+
+#### Example `gist` Output
+
+{{< output file="gist-output.html" >}}
+{{< gist spf13 7896402 >}}
+{{< /output >}}
+
+#### Example `gist` Display
+
+To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< gist spf13 7896402 >}}
+
+### `highlight`
+
++This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/content-management/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+
+#### Example `highlight` Input
+
+{{< code file="content/tutorials/learn-html.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+#### Example `highlight` Output
+
+The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+
+{{< output file="tutorials/learn-html/index.html" >}}
+<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
+ <span style="color: #f92672"><div></span>
+ <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
+ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ <span style="color: #f92672"></div></span>
+<span style="color: #f92672"></section></span>
+{{< /output >}}
+
+{{% note "More on Syntax Highlighting" %}}
+To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
+{{% /note %}}
+
+### `instagram`
+
+If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
+
+```
+https://www.instagram.com/p/BWNjjyYFxVx/
+```
+
+#### Example `instagram` Input
+
+{{< code file="instagram-input.md" >}}
+{{</* instagram BWNjjyYFxVx */>}}
+{{< /code >}}
+
+You also have the option to hide the caption:
+
+{{< code file="instagram-input-hide-caption.md" >}}
+{{</* instagram BWNjjyYFxVx hidecaption */>}}
+{{< /code >}}
+
+#### Example `instagram` Output
+
+By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="instagram-hide-caption-output.html" >}}
+{{< instagram BWNjjyYFxVx hidecaption >}}
+{{< /output >}}
+
+#### Example `instagram` Display
+
+Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< instagram BWNjjyYFxVx hidecaption >}}
+
+
+
+{{% note %}}
+The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879).
+{{% /note %}}
+
+### `param`
+
+Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. It will log an `ERROR` if the param with the given key could not be found in either.
+
+```bash
+{{</* param testparam */>}}
+```
+
+Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
+
+{{< param testparam >}}
+
+To access deeply nested params, use "dot syntax", e.g:
+
+```bash
+{{</* param "my.nested.param" */>}}
+```
+
+### `ref` and `relref`
+
+These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
+
+`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+
+{{% note "More on Cross References" %}}
+Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+{{% /note %}}
+
+`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+
+#### Example `ref` and `relref` Input
+
+```
+[Neat]({{</* ref "blog/neat.md" */>}})
+[Who]({{</* relref "about.md#who" */>}})
+```
+
+#### Example `ref` and `relref` Output
+
+Assuming that standard Hugo pretty URLs are turned on.
+
+```
+<a href="https://example.com/blog/neat">Neat</a>
+<a href="/about/#who">Who</a>
+```
+
+### `tweet`
+
+You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
+
+```
+https://twitter.com/SanDiegoZoo/status/1453110110599868418
+```
+
+#### Example `tweet` Input
+
+Pass the tweet's user (case-insensitive) and id from the URL as parameters to the `tweet` shortcode.
+
+{{< code file="example-tweet-input.md" >}}
+{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
+{{< /code >}}
+
+#### Example `tweet` Output
+
+Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-tweet-output.html" >}}
+{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
+{{< /output >}}
+
+#### Example `tweet` Display
+
+Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
+
+### `vimeo`
+
+Adding a video from [Vimeo][] is equivalent to the [YouTube Input shortcode][].
+
+```
+https://vimeo.com/channels/staffpicks/146022717
+```
+
+#### Example `vimeo` Input
+
+Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
+
+{{< code file="example-vimeo-input.md" >}}
+{{</* vimeo 146022717 */>}}
+{{< /code >}}
+
+#### Example `vimeo` Output
+
+Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-vimeo-output.html" >}}
+{{< vimeo 146022717 >}}
+{{< /output >}}
+
+{{% tip %}}
+If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
+
+```
+{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
+```
+{{% /tip %}}
+
+#### Example `vimeo` Display
+
+Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< vimeo 146022717 >}}
+
+### `youtube`
+
+The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
+
+```
+https://www.youtube.com/watch?v=w7Ft2ymGmfc
+```
+
+
+#### Example `youtube` Input
+
+Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
+
+{{< code file="example-youtube-input.md" >}}
+{{</* youtube w7Ft2ymGmfc */>}}
+{{< /code >}}
+
+Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
+
+
+{{< code file="example-youtube-input-with-autoplay.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
+{{< /code >}}
+
+For [accessibility reasons](https://dequeuniversity.com/tips/provide-iframe-titles), it's best to provide a title for your YouTube video. You can do this using the shortcode by providing a `title` parameter. If no title is provided, a default of "YouTube Video" will be used.
+
+{{< code file="example-youtube-input-with-title.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" title="A New Hugo Site in Under Two Minutes" */>}}
+{{< /code >}}
+
+
+#### Example `youtube` Output
+
+Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
+
+{{< code file="example-youtube-output.html" >}}
+{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
+{{< /code >}}
+
+#### Example `youtube` Display
+
+Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
+
+{{< youtube w7Ft2ymGmfc >}}
+
+## Privacy Config
+
+To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
+
+## Create Custom Shortcodes
+
+To learn more about creating custom shortcodes, see the [shortcode template documentation][].
+
+[`figure` shortcode]: #figure
+[contentmanagementsection]: /content-management/formats/
+[examplegist]: https://gist.github.com/spf13/7896402
+[figureelement]: https://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
+[Hugo and the GDPR]: /about/hugo-and-gdpr/
+[Instagram]: https://www.instagram.com/
+[pagevariables]: /variables/page/
+[partials]: /templates/partials/
+[quickstart]: /getting-started/quick-start/
+[sctemps]: /templates/shortcode-templates/
+[scvars]: /variables/shortcodes/
+[shortcode template documentation]: /templates/shortcode-templates/
+[templatessection]: /templates/
+[Vimeo]: https://vimeo.com/
+[YouTube Videos]: https://www.youtube.com/
+[YouTube Input shortcode]: #youtube
--- /dev/null
- Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configuring-taxonomies) as below:
+---
+title: Taxonomies
+linktitle:
+description: Hugo includes support for user-defined taxonomies.
+date: 2017-02-01
+publishdate: 2017-02-01
+keywords: [taxonomies,metadata,front matter,terms]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 80
+weight: 80 #rem
+draft: false
+aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
+toc: true
+---
+
+## What is a Taxonomy?
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
+
+### Definitions
+
+Taxonomy
+: a categorization that can be used to classify content
+
+Term
+: a key within the taxonomy
+
+Value
+: a piece of content assigned to a term
+
+
+## Example Taxonomy: Movie Website
+
+Let's assume you are making a website about movies. You may want to include the following taxonomies:
+
+* Actors
+* Directors
+* Studios
+* Genre
+* Year
+* Awards
+
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+
+### Movie Taxonomy Organization
+
+To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
+
+```
+Actor <- Taxonomy
+ Bruce Willis <- Term
+ The Sixth Sense <- Value
+ Unbreakable <- Value
+ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
+ Unbreakable <- Value
+ The Avengers <- Value
+ xXx <- Value
+```
+
+From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
+
+```
+Unbreakable <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Samuel L. Jackson <- Term
+ Director <- Taxonomy
+ M. Night Shyamalan <- Term
+ ...
+Moonrise Kingdom <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Bill Murray <- Term
+ Director <- Taxonomy
+ Wes Anderson <- Term
+ ...
+```
+
+## Hugo Taxonomy Defaults {#default-taxonomies}
+
+Hugo natively supports taxonomies.
+
- Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
++Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be the same as manually [configuring your taxonomies](#configure-taxonomies) as below:
+
+{{< code-toggle copy="false" >}}
+[taxonomies]
+ tag = "tags"
+ category = "categories"
+{{</ code-toggle >}}
+
+If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following:
+
+{{< code-toggle copy="false" >}}
+disableKinds = ["taxonomy","term"]
+{{</ code-toggle >}}
+
+{{< new-in "0.73.0" >}} We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your `disableKinds` section.
+
+{{% page-kinds %}}
+
+### Default Destinations
+
+When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+
+* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
+* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
+
+## Configure Taxonomies
+
+Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
+
+### Example: Adding a custom taxonomy named "series"
+
+{{% note %}}
+While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_.
+{{% /note %}}
+
+{{< code-toggle copy="false" >}}
+[taxonomies]
+ tag = "tags"
+ category = "categories"
+ series = "series"
+{{</ code-toggle >}}
+
+### Example: Removing default taxonomies
+
+If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config].
+
+{{< code-toggle copy="false" >}}
+[taxonomies]
+ tag = "tags"
+{{</ code-toggle >}}
+
+If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies).
+
+{{% note %}}
+You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
+
+Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
+{{% /note %}}
+
+{{% warning %}}
+The configuration option `preserveTaxonomyNames` was removed in Hugo 0.55.
+
+You can now use `.Page.Title` on the relevant taxonomy node to get the original value.
+{{% /warning %}}
+
+## Add Taxonomies to Content
+
+Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][].
+
+Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
+
+{{% note %}}
+If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
+{{% /note %}}
+
+### Example: Front Matter with Taxonomies
+
+{{< code-toggle copy="false">}}
+title = "Hugo: A fast and flexible static site generator"
+tags = [ "Development", "Go", "fast", "Blogging" ]
+categories = [ "Development" ]
+series = [ "Go Web Dev" ]
+slug = "hugo"
+project_url = "https://github.com/gohugoio/hugo"
+{{</ code-toggle >}}
+
+## Order Taxonomies
+
+A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
+
+The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
+
+### Example: Taxonomic `weight`
+
+{{< code-toggle copy="false" >}}
+title = "foo"
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+categories_weight = 44
+{{</ code-toggle >}}
+
+By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
+
+{{% note "Limits to Ordering Taxonomies" %}}
- [taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates
++Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight--date--linktitle--filepath). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
+{{% /note %}}
+
+## Add custom metadata to a Taxonomy or Term
+
+If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:
+
+{{< code file="/content/actors/bruce-willis/_index.md" >}}
+---
+title: "Bruce Willis"
+wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
+---
+{{< /code >}}
+
+
+[`urlize` template function]: /functions/urlize/
+[content section]: /content-management/sections/
+[content type]: /content-management/types/
+[documentation on archetypes]: /content-management/archetypes/
+[front matter]: /content-management/front-matter/
++[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-list-templates
+[taxonomy templates]: /templates/taxonomy-templates/
+[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy"
+[config]: /getting-started/configuration/
--- /dev/null
- {{% note "Table of contents not available for MMark" %}}
- Hugo documents created in the [MMark](/content-management/formats/#mmark) Markdown dialect do not currently display TOCs. TOCs are, however, compatible with all other supported Markdown formats.
- {{% /note %}}
-
+---
+title: Table of Contents
+linktitle:
+description: Hugo can automatically parse Markdown content and create a Table of Contents you can use in your templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [content management]
+keywords: [table of contents, toc]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 130
+weight: 130 #rem
+draft: false
+aliases: [/extras/toc/]
+toc: true
+---
+
+{{% note "TOC Heading Levels are Fixed" %}}
+
+Previously, there was no out-of-the-box way to specify which heading levels you want the TOC to render. [See the related GitHub discussion (#1778)](https://github.com/gohugoio/hugo/issues/1778). As such, the resulting `<nav id="TableOfContents"><ul></ul></nav>` was going to start at `<h1>` when pulling from `{{.Content}}`.
+
+Hugo [v0.60.0](https://github.com/gohugoio/hugo/releases/tag/v0.60.0) made a switch to [Goldmark](https://github.com/yuin/goldmark/) as the default library for Markdown which has improved and configurable implementation of TOC. Take a look at [how to configure TOC](/getting-started/configuration-markup/#table-of-contents) for Goldmark renderer.
+
+{{% /note %}}
+
+## Usage
+
+Create your markdown the way you normally would with the appropriate headings. Here is some example content:
+
+```
+<!-- Your front matter up here -->
+
+## Introduction
+
+One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
+
+## My Heading
+
+He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
+
+### My Subheading
+
+A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
+```
+
+Hugo will take this Markdown and create a table of contents from `## Introduction`, `## My Heading`, and `### My Subheading` and then store it in the [page variable][pagevars]`.TableOfContents`.
+
+The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">` element with a child `<ul>`, whose child `<li>` elements begin with appropriate HTML headings. See [the available settings](/getting-started/configuration-markup/#table-of-contents) to configure what heading levels you want to include in TOC.
+
+## Template Example: Basic TOC
+
+The following is an example of a very basic [single page template][]:
+
+{{< code file="layout/_default/single.html" download="single.html" >}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{ .Title }}</h1>
+ </header>
+ {{ .Content }}
+ </article>
+ <aside>
+ {{ .TableOfContents }}
+ </aside>
+</main>
+{{ end }}
+{{< /code >}}
+
+## Template Example: TOC Partial
+
+The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
+
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
+{{ if and (gt .WordCount 400 ) (.Params.toc) }}
+<aside>
+ <header>
+ <h2>{{.Title}}</h2>
+ </header>
+ {{.TableOfContents}}
+</aside>
+{{ end }}
+{{< /code >}}
+
+{{% note %}}
+With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
+{{% /note %}}
+
+## Usage with AsciiDoc
+
+Hugo supports table of contents with AsciiDoc content format.
+
+In the header of your content file, specify the AsciiDoc TOC directives necessary to ensure that the table of contents is generated. Hugo will use the generated TOC to populate the page variable `.TableOfContents` in the same way as described for Markdown. See example below:
+
+```asciidoc
+// <!-- Your front matter up here -->
+:toc:
+// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
+:toclevels: 4
+
+== Introduction
+
+One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin.
+
+== My Heading
+
+He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment.
+
+=== My Subheading
+
+A collection of textile samples lay spread out on the table - Samsa was a travelling salesman - and above it there hung a picture that he had recently cut out of an illustrated magazine and housed in a nice, gilded frame. It showed a lady fitted out with a fur hat and fur boa who sat upright, raising a heavy fur muff that covered the whole of her lower arm towards the viewer. Gregor then turned to look out the window at the dull weather. Drops
+```
+Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown.
+
+[conditionals]: /templates/introduction/#conditionals
+[front matter]: /content-management/front-matter/
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[single page template]: /templates/single-page-templates/
--- /dev/null
- The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not crawl and index your new alias page.
+---
+title: URL Management
+linktitle: URL Management
+description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-09
+keywords: [aliases,redirects,permalinks,urls]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 110
+weight: 110 #rem
+draft: false
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+toc: true
+---
+
+## Permalinks
+
+The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
+
+The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
+
+{{% note "Default Publish and Content Folders" %}}
+These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
+{{% /note %}}
+
+For example, if one of your [sections][] is called `posts` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
+
+### Permalinks Configuration Example
+
+{{< code-toggle file="config" copy="false" >}}
+permalinks:
+ posts: /:year/:month/:title/
+{{< /code-toggle >}}
+
+Only the content under `posts/` will have the new URL structure. For example, the file `content/posts/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
+
+To configure the `permalinks` option for pages in the "root" section, use **/** as the key:
+
+{{< code-toggle file="config" copy="false" >}}
+permalinks:
+ /: /:year/:month/:filename/
+{{< /code-toggle >}}
+
+If the standard date-based permalink configuration does not meet your needs, you can also format URL segments using [Go time formatting directives](https://golang.org/pkg/time/#Time.Format). For example, a URL structure with two digit years and month and day digits without zero padding can be accomplished with:
+
+{{< code-toggle file="config" copy="false" >}}
+permalinks:
+ posts: /:06/:1/:2/:title/
+{{< /code-toggle >}}
+
+You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`.
+
+### Permalink Configuration Values
+
+The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date.
+
+`:year`
+: the 4-digit year
+
+`:month`
+: the 2-digit month
+
+`:monthname`
+: the name of the month
+
+`:day`
+: the 2-digit day
+
+`:weekday`
+: the 1-digit day of the week (Sunday = 0)
+
+`:weekdayname`
+: the name of the day of the week
+
+`:yearday`
+: the 1- to 3-digit day of the year
+
+`:section`
+: the content's section
+
+`:sections`
+: the content's sections hierarchy. {{< new-in "0.83.0" >}} Since Hugo 0.83 you can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:title`
+: the content's title
+
+`:slug`
+: the content's slug (or title if no slug is provided in the front matter)
+
+`:filename`
+: the content's filename (without extension)
+
+Additionally, a Go time format string prefixed with `:` may be used.
+
+## Aliases
+
+Aliases can be used to create redirects to your page from other URLs.
+
+Aliases comes in two forms:
+
+1. Starting with a `/` meaning they are relative to the `BaseURL`, e.g. `/posts/my-blogpost/`
+2. They are relative to the `Page` they're defined in, e.g. `my-blogpost` or even something like `../blog/my-blogpost` (new in Hugo 0.55).
+
+### Example: Aliases
+
+Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively.
+
+#### TOML Front Matter
+
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
++++
+aliases = [
+ "/posts/my-original-url/",
+ "/2010/01/01/even-earlier-url.html"
+]
++++
+{{< /code >}}
+
+#### YAML Front Matter
+
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
+---
+aliases:
+ - /posts/my-original-url/
+ - /2010/01/01/even-earlier-url.html
+---
+{{< /code >}}
+
+Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`.
+
+### Example: Aliases in Multilingual
+
+On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
+
+In `/posts/my-new-post.es.md`:
+
+```
+---
+aliases:
+ - /es/posts/my-original-post/
+---
+```
+
+From Hugo 0.55 you can also have page-relative aliases, so ` /es/posts/my-original-post/` can be simplified to the more portable `my-original-post/`
+
+### How Hugo Aliases Work
+
+When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
+
+For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
+
+```
+---
+title: My New post
+aliases: [/posts/my-old-url/]
+---
+```
+
+Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following:
+
+```
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>https://example.com/posts/my-intended-url</title>
+ <link rel="canonical" href="https://example.com/posts/my-intended-url"/>
+ <meta name="robots" content="noindex">
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
+ </head>
+</html>
+```
+
++The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not index your alias page (`https://example.com/posts/my-old-url/`).
+
+### Customize
+
+You may customize this alias page by creating an `alias.html` template in the
+layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is
+
+`Permalink`
+: the link to the page being aliased
+
+`Page`
+: the Page data for the page being aliased
+
+### Important Behaviors of Aliases
+
+1. Hugo makes no assumptions about aliases. They also do not change based
+on your UglyURLs setting. You need to provide absolute paths to your web root
+and the complete filename or directory.
+2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location.
+
+## Pretty URLs
+
+Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work.
+
+The following demonstrates the concept:
+
+```
+content/posts/_index.md
+=> example.com/posts/
+content/posts/post-1.md
+=> example.com/posts/post-1/
+```
+
+## Ugly URLs
+
+If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also set the `HUGO_UGLYURLS` environment variable to `true` when running `hugo` or `hugo server`.
+
+If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
+
+See [Content Organization][contentorg] for more details on paths.
+
+```
+.
+└── content
+ └── about
+ | └── _index.md // <- https://example.com/about/
+ ├── posts
+ | ├── firstpost.md // <- https://example.com/posts/firstpost/
+ | ├── happy
+ | | └── ness.md // <- https://example.com/posts/happy/ness/
+ | └── secondpost.md // <- https://example.com/posts/secondpost/
+ └── quote
+ ├── first.md // <- https://example.com/quote/first/
+ └── second.md // <- https://example.com/quote/second/
+```
+
+Here's the same organization run with `hugo --uglyURLs`:
+
+```
+.
+└── content
+ └── about
+ | └── _index.md // <- https://example.com/about.html
+ ├── posts
+ | ├── firstpost.md // <- https://example.com/posts/firstpost.html
+ | ├── happy
+ | | └── ness.md // <- https://example.com/posts/happy/ness.html
+ | └── secondpost.md // <- https://example.com/posts/secondpost.html
+ └── quote
+ ├── first.md // <- https://example.com/quote/first.html
+ └── second.md // <- https://example.com/quote/second.html
+```
+
+
+## Canonicalization
+
+By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
+
+By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`.
+
+Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
+
+Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
+
+{{% note "`canonifyURLs` default change" %}}
+In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
+{{% /note %}}
+
+To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
+
+```
+hugo config | grep -i canon
+```
+
+Or, if you are on Windows and do not have `grep` installed:
+
+```
+hugo config | FINDSTR /I canon
+```
+
+## Set URL in Front Matter
+
+In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
+
+Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
+
+From Hugo 0.55, you can use URLs relative to the current site context (the language), which makes it simpler to maintain. For a Japanese translation, both of the following examples would get the same URL:
+
+```markdown
+---
+title: "Custom URL!"
+url: "/jp/custom/foo"
+---
+```
+
+```markdown
+---
+title: "Custom URL!"
+url: "custom/foo"
+---
+```
+
+
+## Relative URLs
+
+By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
+
+Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
+
+For example, if your `/posts/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
+
+[config]: /getting-started/configuration/
+[contentorg]: /content-management/organization/
+[front matter]: /content-management/front-matter/
+[multilingual]: /content-management/multilingual/
+[sections]: /content-management/sections/
+[usage]: /getting-started/usage/
--- /dev/null
- * [GitHub Pull Request Tutorial, Thinkful][thinkful]
+---
+title: Contribute to Hugo Development
+linktitle: Development
+description: Hugo relies heavily on contributions from the open source community.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [contribute]
+keywords: [dev,open source]
+authors: [digitalcraftsman]
+menu:
+ docs:
+ parent: "contribute"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+toc: true
+---
+
+## Introduction
+
+Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
+
+## Assumptions
+
+This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
+
+* You are new to Git or open-source projects in general
+* You are a fan of Hugo and enthusiastic about contributing to the project
+
+{{% note "Additional Questions?" %}}
+If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
+{{% /note %}}
+
+## Install Go
+
+The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.
+
+If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
+
+### Install Go From Source
+
+[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
+
+Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
+
+```
+go version
+```
+
+You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
+
+```
+go version go1.12 darwin/amd64
+```
+
+Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath].
+
+You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example:
+
+```
+/Users/<yourusername>/Code/go
+```
+
+### Install Go with Homebrew
+
+If you are a MacOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:
+
+{{< code file="install-go.sh" >}}
+brew install go
+{{< /code >}}
+
+### Install Go via GVM
+
+More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.
+
+GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
+
+## Create a GitHub Account
+
+If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
+
+## Install Git on Your System
+
+You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
+
+Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.
+
+Go ships with a sub-command called `get` that will download these packages for us when we setup our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies.
+
+Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+Finally, check again with `git version` if Git was installed successfully.
+
+### Git Graphical Front Ends
+
+There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere.
+
+### Install Hub on Your System (Optional)
+
+Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
+
+On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
+
+```
+brew install hub
+```
+
+Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
+
+```
+echo "alias git='hub'" >> ~/.bash_profile
+```
+
+Confirm the installation:
+
+```
+git version 2.21.0
+hub version 2.10.0
+```
+
+## Set up your working copy
+
+You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.
+
+### Clone the repository
+
+We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
+
+> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
+
+We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
+
+So, let's make a new directory and clone that master repository:
+
+```
+mkdir $HOME/src
+cd $HOME/src
+git clone https://github.com/gohugoio/hugo.git
+```
+
+> Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build.
+> The easiest is to clone Hugo in a directory outside of GOPATH
+
+And then, install dependencies of Hugo by running the following in the cloned directory:
+
+```
+cd $HOME/src/hugo
+go install
+```
+
+
+Hugo relies on [mage](https://github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
+
+```
+go install github.com/magefile/mage@latest
+```
+
+### Fork the repository
+
+If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
+
+> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
+
+#### Fork by hand
+
+Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right.
+
+
+
+Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
+
+
+
+Switch back to the terminal and move into the directory of the cloned master repository from the last step.
+
+```
+cd $HOME/src/hugo
+```
+
+Now Git needs to know that our fork exists by adding the copied remote url:
+
+```
+git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
+```
+
+#### Fork with Hub
+
+Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
+
+```
+git fork
+```
+
+That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.
+
+#### Trust, but verify
+
+Let's check if everything went right by listing all known remotes:
+
+```
+git remote -v
+```
+
+The output should look similar:
+
+```
+digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
+digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
+origin https://github.com/gohugoio/hugo (fetch)
+origin https://github.com/gohugoio/hugo (push)
+```
+
+## The Hugo Git Contribution Workflow
+
+### Create a new branch
+
+You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it.
+
+First, you should always pull the latest changes from the master repository:
+
+```
+git checkout master
+git pull
+```
+
+Now we can create a new branch for your additions:
+
+```
+git checkout -b <BRANCH-NAME>
+```
+
+You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
+
+### Contribute to Documentation
+
+Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
+
+You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content.
+
+We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.
+
+### Build Hugo
+
+While making changes in the codebase it's a good idea to build the binary to test them:
+
+```
+mage hugo
+```
+
+This command generates the binary file at the root of the repository.
+
+If you want to install the binary in `$GOPATH/bin`, run
+
+```
+mage install
+```
+
+### Test
+Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`.
+
+Make sure the commands
+
+```
+mage -v check
+```
+
+passes.
+
+### Formatting
+The Go code styleguide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our additions:
+
+```
+mage fmt
+```
+
+Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
+
+```
+# Add all changed files
+git add --all
+git commit --message "YOUR COMMIT MESSAGE"
+```
+
+The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done.
+
+### Modify commits
+
+You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.
+
+If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.
+
+#### Modify the last commit
+
+Let's say you want to modify the last commit message. Run the following command and replace the current message:
+
+```
+git commit --amend -m"YOUR NEW COMMIT MESSAGE"
+```
+
+Take a look at the commit log to see the change:
+
+```
+git log
+# Exit with q
+```
+
+After making the last commit you may have forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
+
+```
+git add --all
+git commit --amend
+```
+
+#### Modify multiple commits
+
+{{% warning "Be Careful Modifying Multiple Commits"%}}
+Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
+{{% /warning %}}
+
+This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
+
+```
+git rebase --interactive @~6
+```
+
+The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
+
+```
+pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
+pick aaee038 tpl: Sort the smoke tests
+pick f0dbf2c tpl: Add the other test case for hasPrefix
+pick 911c35b Add "How to contribute to Hugo" tutorial
+pick 33c8973 Begin workflow
+pick 3502f2e Refactoring and typo fixes
+```
+
+In the case above we should merge the last two commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one.
+
+All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
+
+```
+pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
+pick aaee038 tpl: Sort the smoke tests
+pick f0dbf2c tpl: Add the other test case for hasPrefix
+pick 911c35b Add "How to contribute to Hugo" tutorial
+squash 33c8973 Begin workflow
+squash 3502f2e Refactoring and typo fixes
+```
+
+We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut).
+
+You should end up with a similar setup:
+
+```
+pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
+pick aaee038 tpl: Sort the smoke tests
+pick f0dbf2c tpl: Add the other test case for hasPrefix
+reword 911c35b Add "How to contribute to Hugo" tutorial
+squash 33c8973 Begin workflow
+squash 3502f2e Refactoring and typo fixes
+```
+
+Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with <kbd>CTRL</kbd>+<kbd>S</kbd> and close the editor again.
+
+A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
+
+```
+Successfully rebased and updated refs/heads/<BRANCHNAME>.
+```
+
+Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`.
+
+### Push commits
+
+To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
+
+```
+git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
+```
+
+Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.
+
+If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`.
+
+## Open a pull request
+
+We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser.
+
+You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
+
+
+
+The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
+
+### Accept the contributor license agreement
+
+Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
+
+
+
+### Automatic builds
+
+We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (masOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
+
+## Where to start?
+
+Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.
+
+Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
+
+## Additional References for Learning Git and Go
+
+* [Codecademy's Free "Learn Git" Course][codecademy] (Free)
+* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
+* [The Git Book][gitbook] (Free)
+* [Go Bootcamp][gobootcamp]
- [thinkful]: https://www.thinkful.com/learn/github-pull-request-tutorial/
+
+
+[codecademy]: https://www.codecademy.com/learn/learn-git
+[contributors]: https://github.com/gohugoio/hugo/graphs/contributors
+[docscontrib]: /contribute/documentation/
+[forums]: https://discourse.gohugo.io
+[gitbook]: https://git-scm.com/
+[gobootcamp]: https://www.golangbootcamp.com/book/get_setup
+[godl]: https://golang.org/dl/
+[goinstall]: https://golang.org/doc/install
+[gvm]: https://github.com/moovweb/gvm
+[issues]: https://github.com/gohugoio/hugo/issues
+[newissue]: https://github.com/gohugoio/hugo/issues/new
+[releases]: /getting-started/
+[setupgopath]: https://golang.org/doc/code.html#Workspaces
+[trygit]: https://try.github.io/levels/1/challenges/1
--- /dev/null
- In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#adding-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
+---
+title: Contribute to the Hugo Docs
+linktitle: Documentation
+description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [contribute]
+keywords: [docs,documentation,community, contribute]
+menu:
+ docs:
+ parent: "contribute"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/contribute/docs/]
+toc: true
+---
+
+## Create Your Fork
+
+It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
+
+You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
+
+```
+git checkout -b jon-doe-showcase-addition
+```
+
+## Add New Content
+
+The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content sections in Hugo documentation have an assigned archetype.
+
+Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
+
+```
+hugo new <DOCS-SECTION>/<new-content-lowercase>.md
+```
+
+### Add a New Function
+
+Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase.
+
+```
+hugo new functions/newfunction.md
+```
+
+The archetype for `functions` according to the Hugo docs is as follows:
+
+{{< code file="archetypes/functions.md" >}}
+{{< readfile file="/archetypes/functions.md">}}
+{{< /code >}}
+
+#### New Function Required Fields
+
+Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
+
+***`title`***
+: this will be auto-populated in all lowercase when you use `hugo new` generator.
+
+***`linktitle`***
+: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
+
+***`description`***
+: a brief description used to populate the [Functions Quick Reference](/functions/).
+
+`categories`
+: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
+
+`tags`
+: only if you think it will help end users find other related functions
+
+`signature`
+: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
+
+`workson`
+: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.
+
+`hugoversion`
+: the version of Hugo that will ship with this new function.
+
+`relatedfuncs`
+: other [templating functions][] you feel are related to your new function to help fellow Hugo users.
+
+`{{.Content}}`
+: an extended description of the new function; examples are not only welcomed but encouraged.
+
++In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#add-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
+
+## Add Code Blocks
+
+Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.
+
+### Standard Syntax
+
+Across many pages on the Hugo docs, the typical triple-back-tick markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages.
+
+Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`.
+
+````
+```
+<h1>Hello world!</h1>
+```
+````
+
+
+### Code Block Shortcode
+
+The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.
+
+{{% note %}}
+With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs.
+{{% /note %}}
+
+### `code`
+
+`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
+
+```
+{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
+A whole bunch of coding going on up in here!
+{{%/* /code */%}}
+```
+
+The following are the arguments passed into `code`:
+
+
+***`file`***
+: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
+
+`download`
+: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
+
+`copy`
+: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`.
+
+#### Example `code` Input
+
+This example HTML code block tells Hugo users the following:
+
+1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
+2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
+
+```
+{{</* code file="layouts/_default/single.html" download="single.html" */>}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ {{with .Params.subtitle}}
+ <span>{{.}}</span>
+ </header>
+ <div>
+ {{.Content}}
+ </div>
+ <aside>
+ {{.TableOfContents}}
+ </aside>
+ </article>
+</main>
+{{ end }}
+{{</* /code */>}}
+```
+
+##### Example 'code' Display
+
+The output of this example will render to the Hugo docs as follows:
+
+{{< code file="layouts/_default/single.html" download="single.html" >}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ {{with .Params.subtitle}}
+ <span>{{.}}</span>
+ </header>
+ <div>
+ {{.Content}}
+ </div>
+ <aside>
+ {{.TableOfContents}}
+ </aside>
+ </article>
+</main>
+{{ end }}
+{{< /code >}}
+
+<!-- #### Output Code Block
+
+The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
+
+```
+{{%/* output file="posts/my-first-post/index.html" */%}}
+<h1>This is my First Hugo Blog Post</h1>
+<p>I am excited to be using Hugo.</p>
+{{%/* /output */%}}
+```
+
+The preceding `output` example will render as follows to the Hugo docs:
+
+{{< output file="posts/my-first-post/index.html" >}}
+<h1>This is my First Hugo Blog Post</h1>
+<p>I am excited to be using Hugo.</p>
+{{< /output >}} -->
+
+## Blockquotes
+
+Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
+
+```
+> Without the threat of punishment, there is no joy in flight.
+```
+
+The preceding blockquote will render as follows in the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight.
+
+However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
+
+```
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
+```
+
+Which will render as follows in the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]
+
+{{% note "Blockquotes `!=` Admonitions" %}}
+Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](https://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
+{{% /note %}}
+
+## Admonitions
+
+**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation:
+
+> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
+
+The Hugo docs contain three admonitions: `note`, `tip`, and `warning`.
+
+### `note` Admonition
+
+Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.
+
+#### Example `note` Input
+
+{{< code file="note-with-heading.md" >}}
+{{%/* note */%}}
+Here is a piece of information I would like to draw your **attention** to.
+{{%/* /note */%}}
+{{< /code >}}
+
+#### Example `note` Output
+
+{{< output file="note-with-heading.html" >}}
+{{% note %}}
+Here is a piece of information I would like to draw your **attention** to.
+{{% /note %}}
+{{< /output >}}
+
+#### Example `note` Display
+
+{{% note %}}
+Here is a piece of information I would like to draw your **attention** to.
+{{% /note %}}
+
+### `tip` Admonition
+
+Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`.
+
+#### Example `tip` Input
+
+{{< code file="using-tip.md" >}}
+{{%/* tip */%}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{%/* /tip */%}}
+{{< /code >}}
+
+#### Example `tip` Output
+
+{{< output file="tip-output.html" >}}
+{{% tip %}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{% /tip %}}
+{{< /output >}}
+
+#### Example `tip` Display
+
+{{% tip %}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{% /tip %}}
+
+### `warning` Admonition
+
+Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."
+
+#### Example `warning` Input
+
+{{< code file="warning-admonition-input.md" >}}
+{{%/* warning */%}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{%/* /warning */%}}
+{{< /code >}}
+
+#### Example `warning` Output
+
+{{< output file="warning-admonition-output.html" >}}
+{{% warning %}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{% /warning %}}
+{{< /output >}}
+
+#### Example `warning` Display
+
+{{% warning %}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{% /warning %}}
+
+{{% note "Pull Requests and Branches" %}}
+Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
+{{% /note %}}
+
+[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
+[archetypes]: /content-management/archetypes/
+[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
+[charcount]: https://www.lettercount.com/
+[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
+[ghforking]: https://help.github.com/articles/fork-a-repo/
+[hugodev]: /contribute/development/
+[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
+[sourceforge]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
+[templating function]: /functions/
--- /dev/null
+---
+title: Hugo Documentation
+linktitle: Hugo
+description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
+date: 2017-02-01
+publishdate: 2017-02-01
+menu:
+ main:
+ parent: "section name"
+ weight: 01
+weight: 01 #rem
+draft: false
+slug:
+aliases: []
+toc: false
+layout: documentation-home
+---
+
+Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors).
+
+Below you will find some of the most common and helpful pages from our documentation.
++foo
--- /dev/null
- description: Returns the time corresponding to adding the given number of years, months, and days passed to the function.
+---
+title: .AddDate
- The `AddDate` function takes three arguments in logical order of `years`, `months`, and `days`.
-
- ## Example: Randomized Tweets from the Last 2 Years
-
- Let's assume you have a file at `data/tweets.toml` that contains a list of Tweets to display on your site's homepage. The file is filled with `[[tweet]]` blocks; e.g.---
-
- {{< code-toggle file="data/tweets" >}}
- [[tweet]]
- name = "Steve Francia"
- twitter_handle = "@spf13"
- quote = "I'm creator of Hugo. #metadocreference"
- link = "https://twitter.com/spf13"
- date = "2017-01-07T00:00:00Z"
- {{< /code-toggle >}}
-
- Let's assume you want to grab Tweets from the last two years and present them in a random order. In conjunction with the [`where`](/functions/where/) and [`now`](/functions/now/) functions, you can limit our range to the last two years via `now.AddDate -2 0 0`, which represents a point in time 2 years, 0 months, and 0 days before the time of your last site build.
-
- {{< code file="partials/templates/random-tweets.html" download="tweets.html" >}}
- {{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }}
- <div class="item">
- <blockquote>
- <p>
- {{ .quote | safeHTML }}
- </p>
- — {{ .name }} ({{ .twitter_handle }}) <a href="{{ .link }}">
- {{ dateFormat "January 2, 2006" .date }}
- </a>
- </blockquote>
- </div>
- {{ end }}
- {{< /code >}}
++description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [dates,time]
+signature: [".AddDate YEARS MONTHS DAYS"]
+workson: [times]
+hugoversion:
+relatedfuncs: [now]
+deprecated: false
+aliases: []
+---
+
++```go-html-template
++{{ $d := "2022-01-01" | time.AsTime }}
+
++{{ $d.AddDate 0 0 1 | time.Format "2006-01-02" }} --> 2022-01-02
++{{ $d.AddDate 0 1 1 | time.Format "2006-01-02" }} --> 2022-02-02
++{{ $d.AddDate 1 1 1 | time.Format "2006-01-02" }} --> 2023-02-02
++
++{{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} --> 2020-11-30
++```
++
++{{% note %}}
++When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year.
++
++See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team.
++{{% /note %}}
++
++```go-html-template
++{{ $d := "2023-01-31" | time.AsTime }}
++{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} --> 2023-03-03
++
++{{ $d := "2024-01-31" | time.AsTime }}
++{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} --> 2024-03-02
++
++{{ $d := "2024-02-29" | time.AsTime }}
++{{ $d.AddDate 1 0 0 | time.Format "2006-01-02" }} --> 2025-03-01
++```
--- /dev/null
- `absLangURL` and `relLangURL` functions are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl/) relatives but will add the correct language prefix when the site is configured with more than one language. (See [Configuring Multilingual][multiliconfig].)
+---
+title: relLangURL
+description: Adds the relative URL with correct language prefix according to site configuration for multilingual.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [multilingual,i18n,urls]
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+signature: ["relLangURL INPUT"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
- [multiliconfig]: /content-management/multilingual/#configuring-multilingual-mode
++`absLangURL` and `relLangURL` functions are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl/) relatives but will add the correct language prefix when the site is configured with more than one language. (See [Configure Languages][multiliconfig].)
+
+So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`:
+
+```
+{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/"
+{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
+```
+
++[multiliconfig]: /content-management/multilingual/#configure-languages
--- /dev/null
- See [Image Processing Config](/content-management/image-processing/#image-processing-config).
+---
+title: Configure Hugo
+linktitle: Configuration
+description: How to configure your Hugo site.
+date: 2013-07-01
+publishdate: 2017-01-02
+lastmod: 2017-03-05
+categories: [getting started,fundamentals]
+keywords: [configuration,toml,yaml,json]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: [/overview/source-directory/,/overview/configuration/]
+toc: true
+---
+
+
+## Configuration File
+
+Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
+site root) as the default site config file.
+
+The user can choose to override that default with one or more site config files
+using the command line `--config` switch.
+
+Examples:
+
+```
+hugo --config debugconfig.toml
+hugo --config a.toml,b.toml,c.toml
+```
+
+{{% note %}}
+Multiple site config files can be specified as a comma-separated string to the `--config` switch.
+{{% /note %}}
+
+{{< todo >}}TODO: distinct config.toml and others (the root object files){{< /todo >}}
+
+## Configuration Directory
+
+In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings.
+
+- Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc...
+- Each file's content must be top-level, for example:
+
+{{< code-toggle file="config" >}}
+[Params]
+ foo = "bar"
+{{< /code-toggle >}}
+
+{{< code-toggle file="params" >}}
+foo = "bar"
+{{< /code-toggle >}}
+
+- Each directory holds a group of files containing settings unique to an environment.
+- Files can be localized to become language specific.
+
+
+```
+├── config
+│ ├── _default
+│ │ ├── config.toml
+│ │ ├── languages.toml
+│ │ ├── menus.en.toml
+│ │ ├── menus.zh.toml
+│ │ └── params.toml
+│ ├── production
+│ │ ├── config.toml
+│ │ └── params.toml
+│ └── staging
+│ ├── config.toml
+│ └── params.toml
+```
+
+Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those.
+{{% note %}}
+Default environments are __development__ with `hugo server` and __production__ with `hugo`.
+{{%/ note %}}
+
+## Merge Configuration from Themes
+
+{{< new-in "0.84.0" >}} The configuration merge described below was improved in Hugo 0.84.0 and made fully configurable. The big change/improvement was that we now, by default, do deep merging of `params` maps from themes.
+
+The configuration value for `_merge` can be one of:
+
+none
+: No merge.
+
+shallow
+: Only add values for new keys.
+
+deep
+: Add values for new keys, merge existing.
+
+Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
+
+{{< code-toggle config="mergeStrategy" skipHeader=true />}}
+
+## All Configuration Settings
+
+The following is the full list of Hugo-defined variables with their default
+value in parentheses. Users may choose to override those values in their site
+config file(s).
+
+### archetypeDir
+
+**Default value:** "archetypes"
+
+The directory where Hugo finds archetype files (content templates). {{% module-mounts-note %}}
+
+### assetDir
+
+**Default value:** "assets"
+
+The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}}
+
+### baseURL
+Hostname (and path) to the root, e.g. https://bep.is/
+
+### blackfriday
+See [Configure Blackfriday](/getting-started/configuration-markup#blackfriday)
+
+### build
+See [Configure Build](#configure-build)
+
+### buildDrafts (false)
+
+**Default value:** false
+
+Include drafts when building.
+
+### buildExpired
+
+**Default value:** false
+
+Include content already expired.
+
+### buildFuture
+
+**Default value:** false
+
+Include content with publishdate in the future.
+
+### caches
+See [Configure File Caches](#configure-file-caches)
+
+### cascade
+
+{{< new-in "0.86.0" >}}
+
+Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade).
+
+### canonifyURLs
+
+**Default value:** false
+
+Enable to turn relative URLs into absolute.
+
+### contentDir
+
+**Default value:** "content"
+
+The directory from where Hugo reads content files. {{% module-mounts-note %}}
+
+### copyright
+
+**Default value:** ""
+
+Copyright notice for your site, typically displayed in the footer.
+
+### dataDir
+
+**Default value:** "data"
+
+The directory from where Hugo reads data files. {{% module-mounts-note %}}
+
+### defaultContentLanguage
+
+**Default value:** "en"
+
+Content without language indicator will default to this language.
+
+### defaultContentLanguageInSubdir
+
+**Default value:** false
+
+Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`.
+
+### disableAliases
+
+**Default value:** false
+
+Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format.
+
+### disableHugoGeneratorInject
+
+**Default value:** false
+
+Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise.
+
+### disableKinds
+
+**Default value:** []
+
+Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"term"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`.
+
+### disableLiveReload
+
+**Default value:** false
+
+Disable automatic live reloading of browser window.
+
+### disablePathToLower
+
+**Default value:** false
+
+: Do not convert the url/path to lowercase.
+
+### enableEmoji
+
+**Default value:** false
+
+Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/).
+
+### enableGitInfo
+
+**Default value:** false
+
+Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file.
+
+### enableInlineShortcodes
+
+**Default value:** false
+
+Enable inline shortcode support. See [Inline Shortcodes](/templates/shortcode-templates/#inline-shortcodes).
+
+### enableMissingTranslationPlaceholders
+
+**Default value:** false
+
+Show a placeholder instead of the default value or an empty string if a translation is missing.
+
+### enableRobotsTXT
+
+**Default value:** false
+
+Enable generation of `robots.txt` file.
+
+### frontmatter
+
+See [Front matter Configuration](#configure-front-matter).
+
+### googleAnalytics
+
+**Default value:** ""
+
+Google Analytics tracking ID.
+
+### hasCJKLanguage
+
+**Default value:** false
+
+If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages.
+
+### imaging
+
- Default [sitemap configuration](/templates/sitemap-template/#configure-sitemapxml).
++See [Image Processing Config](/content-management/image-processing/#imaging-configuration).
+
+### languageCode
+
+**Default value:** ""
+
+A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). The internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) populates its `<language>` element with this value. The value is not used elsewhere.
+
+### languages
+
+See [Configure Languages](/content-management/multilingual/#configure-languages).
+
+### disableLanguages
+
+See [Disable a Language](/content-management/multilingual/#disable-a-language)
+
+### markup
+See [Configure Markup](/getting-started/configuration-markup).{{< new-in "0.60.0" >}}
+
+### mediaTypes
+See [Configure Media Types](/templates/output-formats/#media-types).
+
+### menus
+See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu).
+
+### minify
+See [Configure Minify](#configure-minify)
+
+### module
+Module config see [Module Config](/hugo-modules/configuration/).{{< new-in "0.56.0" >}}
+
+### newContentEditor
+
+**Default value:** ""
+
+The editor to use when creating new content.
+
+### noChmod
+
+**Default value:** false
+
+Don't sync permission mode of files.
+
+### noTimes
+
+**Default value:** false
+
+Don't sync modification time of files.
+
+### outputFormats
+See [Configure Output Formats](#configure-additional-output-formats).
+
+### paginate
+
+**Default value:** 10
+
+Default number of elements per page in [pagination](/templates/pagination/).
+
+### paginatePath
+
+**Default value:** "page"
+
+The path element used during pagination (`https://example.com/page/2`).
+
+### permalinks
+See [Content Management](/content-management/urls/#permalinks).
+
+### pluralizeListTitles
+
+**Default value:** true
+
+Pluralize titles in lists.
+
+### publishDir
+
+**Default value:** "public"
+
+The directory to where Hugo will write the final static site (the HTML files etc.).
+
+### related
+: See [Related Content](/content-management/related/#configure-related-content).{{< new-in "0.27" >}}
+
+### relativeURLs
+
+**Default value:** false
+
+Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
+
+### refLinksErrorLevel
+
+**Default value:** "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.
+
+### removePathAccents
+
+**Default value:** false
+
+Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths.
+
+```text
+content/post/hügó.md --> https://example.org/post/hugo/
+```
+
+
+### rssLimit
+
+**Default value:** -1 (unlimited)
+
+Maximum number of items in the RSS feed.
+
+### sectionPagesMenu
+See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers).
+
+### security
+
+See [Security Policy](/about/security-model/#security-policy)
+
+### sitemap
- The length of text in words to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting).
++Default [sitemap configuration](/templates/sitemap-template/#configuration).
+
+### summaryLength
+
+**Default value:** 70
+
++The length of text in words to show in a [`.Summary`](/content-management/summaries/#automatic-summary-splitting).
+
+### taxonomies
+See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
+
+### theme
+: See [Module Config](/hugo-modules/configuration/#module-config-imports) for how to import a theme.
+
+### themesDir
+
+**Default value:** "themes"
+
+The directory where Hugo reads the themes from.
+
+### timeout
+
+**Default value:** "30s"
+
+Timeout for generating page contents, specified as a [duration](https://pkg.go.dev/time#Duration) or in milliseconds. *Note:* this is used to bail out of recursive content generation. You might need to raise this limit if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents).
+
+### timeZone
+
+{{< new-in "0.87.0" >}}
+
+The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+### title
+Site title.
+
+### titleCaseStyle
+
+**Default value:** "AP"
+
+See [Configure Title Case](#configure-title-case)
+
+### uglyURLs
+When enabled, creates URL of the form `/filename.html` instead of `/filename/`.
+
+### watch
+
+**Default value:** false
+
+Watch filesystem for changes and recreate as needed.
+
+{{% note %}}
+If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
+```
+cd ~/sites/yourhugosite
+hugo config | grep emoji
+```
+
+which shows output like
+
+```
+enableemoji: true
+```
+{{% /note %}}
+
+## Configure Build
+
+{{< new-in "0.66.0" >}}
+
+The `build` configuration section contains global build-related configuration options.
+
+{{< code-toggle file="config">}}
+[build]
+useResourceCacheWhen="fallback"
+writeStats = false
+noJSConfigInAssets = false
+{{< /code-toggle >}}
+
+
+useResourceCacheWhen
+: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
+
+writeStats {{< new-in "0.69.0" >}}
+: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build.
+
+**Note** that the prime use case for this is purging of unused CSS; it is build for speed and there may be false positives (e.g. elements that isn't really a HTML element).
+
+noJSConfigInAssets {{< new-in "0.78.0" >}}
+: Turn off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
+
+## Configure Server
+
+{{< new-in "0.67.0" >}}
+
+This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
+
+
+{{< code-toggle file="config">}}
+[server]
+[[server.headers]]
+for = "/**"
+
+[server.headers.values]
+X-Frame-Options = "DENY"
+X-XSS-Protection = "1; mode=block"
+X-Content-Type-Options = "nosniff"
+Referrer-Policy = "strict-origin-when-cross-origin"
+Content-Security-Policy = "script-src localhost:1313"
+{{< /code-toggle >}}
+
+Since this is is "development only", it may make sense to put it below the `development` environment:
+
+
+{{< code-toggle file="config/development/server">}}
+[[headers]]
+for = "/**"
+
+[headers.values]
+X-Frame-Options = "DENY"
+X-XSS-Protection = "1; mode=block"
+X-Content-Type-Options = "nosniff"
+Referrer-Policy = "strict-origin-when-cross-origin"
+Content-Security-Policy = "script-src localhost:1313"
+{{< /code-toggle >}}
+
+
+{{< new-in "0.72.0" >}}
+
+You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's.
+
+Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g:
+
+{{< code-toggle file="config/development/server">}}
+[[redirects]]
+from = "/myspa/**"
+to = "/myspa/"
+status = 200
+force = false
+{{< /code-toggle >}}
+
+{{< new-in "0.76.0" >}} Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behaviour, but this is inline with how Netlify does it.
+
+## Configure Title Case
+
+Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. It defaults to [AP Stylebook](https://www.apstylebook.com/) for title casing, but you can also set it to `Chicago` or `Go` (every word starts with a capital letter).
+
+## Configuration Environment Variables
+
+HUGO_NUMWORKERMULTIPLIER
+: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used.
+
+## Configuration Lookup Order
+
+Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
+
+1. `./config.toml`
+2. `./config.yaml`
+3. `./config.json`
+
+In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
+
+
+## Example Configuration
+
+The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
+
+{{< code-toggle file="config">}}
+baseURL: "https://yoursite.example.com/"
+title: "My Hugo Site"
+permalinks:
+ posts: /:year/:month/:title/
+params:
+ Subtitle: "Hugo is Absurdly Fast!"
+ AuthorName: "Jon Doe"
+ GitHubUser: "spf13"
+ ListOfFoo:
+ - "foo1"
+ - "foo2"
+ SidebarRecentLimit: 5
+{{< /code-toggle >}}
+
+## Configure with Environment Variables
+
+In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
+
+For example, the following command will effectively set a website's title on Unix-like systems:
+
+```
+$ env HUGO_TITLE="Some Title" hugo
+```
+
+This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example.
+
+{{% note "Setting Environment Variables" %}}
+Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
+
+To set config params, prefix the name with `HUGO_PARAMS_`
+{{% /note %}}
+
+{{< new-in "0.79.0" >}} If you are using snake_cased variable names, the above will not work, so since Hugo 0.79.0 Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter.
+
+{{< todo >}}
+Test and document setting params via JSON env var.
+{{< /todo >}}
+
+## Ignore Content and Data Files when Rendering
+
+To exclude specific files from the `content` and `data` directories when rendering your site, set `ignoreFiles` to one or more regular expressions to match against the absolute file path.
+
+To ignore files ending with `.foo` or `.boo`:
+
+{{< code-toggle copy="false" >}}
+ignoreFiles = ['\.foo$', '\.boo$']
+{{< /code-toggle >}}
+
+To ignore a file using the absolute file path:
+
+{{< code-toggle copy="false" >}}
+ignoreFiles = ['^/home/user/project/content/test\.md$']
+{{< /code-toggle >}}
+
+## Configure Front Matter
+
+### Configure Dates
+
+Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`.
+
+
+The default configuration is:
+
+{{< code-toggle file="config" >}}
+[frontmatter]
+date = ["date", "publishDate", "lastmod"]
+lastmod = [":git", "lastmod", "date", "publishDate"]
+publishDate = ["publishDate", "date"]
+expiryDate = ["expiryDate"]
+{{< /code-toggle >}}
+
+If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`:
+
+{{< code-toggle file="config" >}}
+[frontmatter]
+date = ["myDate", ":default"]
+{{< /code-toggle >}}
+
+The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date.
+
+In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
+
+The special date handlers are:
+
+
+`:fileModTime`
+: Fetches the date from the content file's last modification timestamp.
+
+An example:
+
+{{< code-toggle file="config" >}}
+[frontmatter]
+lastmod = ["lastmod", ":fileModTime", ":default"]
+{{< /code-toggle >}}
+
+
+The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`.
+
+
+`:filename`
+: Fetches the date from the content file's filename. For example, `2018-02-22-mypage.md` will extract the date `2018-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`.
+
+An example:
+
+{{< code-toggle file="config" >}}
+[frontmatter]
+date = [":filename", ":default"]
+{{< /code-toggle >}}
+
+The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
+
+
+`:git`
+: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config.
+
+## Configure Additional Output Formats
+
+Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file.
+
+## Configure Minify
+
+{{< new-in "0.68.0" >}}
+
+Default configuration:
+
+{{< code-toggle config="minify" />}}
+
+## Configure File Caches
+
+Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration:
+
+{{< code-toggle >}}
+[caches]
+[caches.getjson]
+dir = ":cacheDir/:project"
+maxAge = -1
+[caches.getcsv]
+dir = ":cacheDir/:project"
+maxAge = -1
+[caches.getresource]
+dir = ":cacheDir/:project"
+maxAge = -1
+[caches.images]
+dir = ":resourceDir/_gen"
+maxAge = -1
+[caches.assets]
+dir = ":resourceDir/_gen"
+maxAge = -1
+[caches.modules]
+dir = ":cacheDir/modules"
+maxAge = -1
+{{< /code-toggle >}}
+
+You can override any of these cache settings in your own `config.toml`.
+
+### The keywords explained
+
+`:cacheDir`
+: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml).
+
+`:project`
+: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC.
+
+`:resourceDir`
+: This is the value of the `resourceDir` config option.
+
+maxAge
+: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours).
+
+dir
+: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above).
+
+## Configuration Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[`.Site.Params`]: /variables/site/
+[directory structure]: /getting-started/directory-structure
+[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
+[lookup order]: /templates/lookup-order/
+[Output Formats]: /templates/output-formats/
+[templates]: /templates/
+[toml]: https://github.com/toml-lang/toml
+[yaml]: https://yaml.org/spec/
+[static-files]: /content-management/static-files/
--- /dev/null
- : Hugo ships with a large number of [configuration directives](https://gohugo.io/getting-started/configuration/#all-variables-yaml).
+---
+title: Directory Structure
+linktitle: Directory Structure
+description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website.
+date: 2017-01-02
+publishdate: 2017-02-01
+lastmod: 2017-03-09
+categories: [getting started,fundamentals]
+keywords: [source, organization, directories]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 50
+weight: 50
+sections_weight: 50
+draft: false
+aliases: [/overview/source-directory/]
+toc: true
+---
+
+## New Site Scaffolding
+
+{{< youtube sB0HLHjgQ7E >}}
+
+Running the `hugo new site` generator from the command line will create a directory structure with the following elements:
+
+```
+.
+├── archetypes
+├── config.toml
+├── content
+├── data
+├── layouts
+├── static
+└── themes
+```
+
+
+## Directory Structure Explained
+
+The following is a high-level overview of each of the directories with links to each of their respective sections within the Hugo docs.
+
+[`archetypes`](/content-management/archetypes/)
+: You can create new content files in Hugo using the `hugo new` command.
+By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
+
+[`assets`][]
+: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default.
+
+[`config`](/getting-started/configuration/)
- [configuration directives]: /getting-started/configuration/#all-variables-yaml
++: Hugo ships with a large number of [configuration directives][].
+The [config directory](/getting-started/configuration/#configuration-directory) is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments.
+Projects with minimal settings and no need for environment awareness can use a single `config.toml` file at its root.
+
+Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website. Note: config directory is not created by default.
+
+[`content`][]
+: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][].
+
+[`data`](/templates/data-templates/)
+: This directory is used to store configuration files that can be
+used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create [data templates][] that pull from dynamic content.
+
+[`layouts`][]
+: Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more.
+
+[`static`][]
+: Stores all the static content: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
+
+{{% note %}}
+From **Hugo 0.31** you can have multiple static directories.
+{{% /note %}}
+
+resources
+: Caches some files to speed up generation. Can be also used by template authors to distribute built SASS files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default.
+
+
+[archetypes]: /content-management/archetypes/
++[configuration directives]: /getting-started/configuration/#all-configuration-settings
+[`content`]: /content-management/organization/
+[content section]: /content-management/sections/
+[content types]: /content-management/types/
+[data templates]: /templates/data-templates/
+[homepage]: /templates/homepage/
+[`layouts`]: /templates/
+[`static`]: /content-management/static-files/
+[lists]: /templates/list/
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[searchconsole]: https://support.google.com/analytics/answer/1142414?hl=en
+[singles]: /templates/single-page-templates/
+[starters]: /tools/starter-kits/
+[taxonomies]: /content-management/taxonomies/
+[taxonomy templates]: /templates/taxonomy-templates/
+[types]: /content-management/types/
+[`assets`]: {{< ref "/hugo-pipes/introduction#asset-directory" >}}
--- /dev/null
- 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/).
+---
+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. 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:
+
+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
+```
+
+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
+```
+
+If `hugo` is not in your `PATH`:
+
+1. Determine your default shell (zsh or bash).
+
+ ```
+ echo $SHELL
+ ```
+
+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
+ ```
+
+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 right.
+* Click on the **Environment Variables...** button on the bottom.
+* In the User variables section, select the row labeled "Path" and click the **Edit...** button.
+* Click the **Browse...** button and select the directory to which `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 itself.*
+* Click OK at every window to exit.
+
+#### For Windows 7 and 8.x users:
+
- [Path Editor]: https://patheditor2.codeplex.com/
++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].
+
+### 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://packages.fedoraproject.org/pkgs/hugo/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].
+
+### openSUSE Tumbleweed
+
+openSUSE maintains an [official package](https://software.opensuse.org/package/hugo) for the Tumbleweed rolling release distribution, it may be installed with:
+
+````
+sudo zypper install hugo
+````
+
+### 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
+[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]: https://eveditor.com/
--- /dev/null
- It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial.
+---
+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).
+
- *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/theNewDynamic/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.
-
++It is required to have [Git installed](https://git-scm.com/downloads) to run this tutorial.
+
+For other approaches to learning Hugo (like books or video tutorials), refer to the [external learning resources](/getting-started/external-learning-resources/) page.
+{{% /note %}}
+
+## Step 1: Install Hugo
+
+{{% 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/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+```
+
+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 your web browser, 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/theNewDynamic/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
--- /dev/null
++---
++title: Host on Cloudflare Pages
++linktitle: Host on Cloudflare Pages
++description: Cloudflare Pages can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own environment variables.
++date: 2022-04-07
++publishdate: 2022-04-07
++categories: [hosting and deployment]
++menu:
++ docs:
++ parent: "hosting-and-deployment"
++ weight: 50
++weight: 50
++sections_weight: 50
++toc: true
++---
++
++You can host your Hugo site using [Cloudflare Pages](https://developers.cloudflare.com/pages/). Pages are super fast, always up-to-date, and deployed directly from your Git provider (currently supports only GitHub and GitLab).
++
++Cloudflare Pages has a handy tutorial on [how to deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/).
--- /dev/null
- - [where](/templates/lists/#where) template function to filter lists of content, taxonomies, etc
+---
+date: 2015-01-21T20:35:00Z
+description: "Hugo 0.12 focused on polishing the theme engine and adding critical functionality to the templates."
+title: "Hugo 0.12"
+categories: ["Releases"]
+---
+
+A lot has happened since Hugo v0.11.0 was released. Most of the work has been
+focused on polishing the theme engine and adding critical functionality to the
+templates.
+
+This release represents over 90 code commits from 28 different contributors.
+
+- 10 [new themes](https://github.com/spf13/hugoThemes) created by the community
+- fully themable [partials](/templates/partials/)
+- [404 template](/templates/404/) support in themes
+- [shortcode](/extras/shortcodes/) support in themes
+- [views](/templates/views/) support in themes
+- inner [shortcode](/extras/shortcodes/) content now treated as markdown
+- support for header ids in markdown (# header {#myid})
++- [where](/functions/where/) template function to filter lists of content, taxonomies, etc.
+- [groupby](/templates/list) & [groupbydate](/templates/list) methods to group pages
+- taxonomy [pages list](/taxonomies/methods/) now sortable, filterable, limitable & groupable
+- general cleanup to taxonomies & documentation to make it more clear and consistent
+- [showcase](/showcase/) returned and has been expanded
+- pretty links now always have trailing slashes
+- [baseurl](/overview/configuration/) can now include a subdirectory
+- better feedback about draft & future post rendering
+- a variety of improvements to [the website](/)
--- /dev/null
+---
+title: Custom 404 Page
+linktitle: 404 Page
+description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+categories: [templates]
+keywords: [404, page not found]
+menu:
+ docs:
+ parent: "templates"
+ weight: 120
+weight: 120 #rem
+draft: false
+aliases: []
+toc: false
+---
+
+When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
+
+404 pages will have all the regular [page variables][pagevars] available to use in the templates.
+
+In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
+
+```
+▾ layouts/
+ 404.html
+```
+
+## 404.html
+
+This is a basic example of a 404.html template:
+
+{{< code file="layouts/404.html" download="404.html" >}}
+{{ define "main"}}
+ <main id="main">
+ <div>
+ <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1>
+ </div>
+ </main>
+{{ end }}
+{{< /code >}}
+
+## Automatic Loading
+
+Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
+
+* [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic.
+* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
+* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. [Details here](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
+* Amazon CloudFront. You can specify the page in the Error Pages section in the CloudFront Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html)
+* Caddy Server. Use the `handle_errors` directive to specify error pages for one or more status codes. [Details here](https://caddyserver.com/docs/caddyfile/directives/handle_errors)
+* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404)
+* Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website).
++* DigitalOcean App Platform. You can specify `error_document` in your app specification file or use control panel to set up error document. [Details here](https://docs.digitalocean.com/products/app-platform/references/app-specification-reference/).
+
+{{% note %}}
+`hugo server` will not automatically load your custom `404.html` file, but you
+can test the appearance of your custom "not found" page by navigating your
+browser to `/404.html`.
+{{% /note %}}
+
+[pagevars]: /variables/page/
--- /dev/null
+---
+title: Lists of Content in Hugo
+linktitle: List Templates
+description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,rss,taxonomies,terms]
+menu:
+ docs:
+ parent: "templates"
+ weight: 22
+weight: 22
+sections_weight: 22
+draft: false
+aliases: [/templates/list/,/layout/indexes/]
+toc: true
+---
+
+## What is a List Page Template?
+
+{{< youtube 8b2YTSMdMps >}}
+
+A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage].
+
+Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
+
+* [Taxonomy terms pages][taxterms]
+* [Taxonomy list pages][taxlists]
+* [Section list pages][sectiontemps]
+* [RSS][rss]
+
+For template lookup order, see [Template Lookup](/templates/lookup-order/).
+
+The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
+
+[](/images/site-hierarchy.svg)
+
+## List Defaults
+
+### Default Templates
+
+Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`.
+
+See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
+
+## Add Content and Front Matter to List Pages
+
+Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content.
+
+This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars].
+
+{{% note %}}
+It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/).
+{{% /note %}}
+
+### Example Project Directory
+
+The following is an example of a typical Hugo project directory's content:
+
+```
+.
+...
+├── content
+| ├── posts
+| | ├── _index.md
+| | ├── post-01.md
+| | └── post-02.md
+| └── quote
+| | ├── quote-01.md
+| | └── quote-02.md
+...
+```
+
+Using the above example, let's assume you have the following in `content/posts/_index.md`:
+
+{{< code file="content/posts/_index.md" >}}
+---
+title: My Go Journey
+date: 2017-03-23
+publishdate: 2017-03-24
+---
+
+I decided to start learning Go in March 2017.
+
+Follow my journey through this new blog.
+{{< /code >}}
+
+You can now access this `_index.md`'s' content in your list template:
+
+{{< code file="layouts/_default/list.html" download="list.html" >}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ </header>
+ <!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
+ {{.Content}}
+ </article>
+ <ul>
+ <!-- Ranges through content/posts/*.md -->
+ {{ range .Pages }}
+ <li>
+ <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
+ </li>
+ {{ end }}
+ </ul>
+</main>
+{{ end }}
+{{< /code >}}
+
+This above will output the following HTML:
+
+{{< code file="example.com/posts/index.html" copy="false" >}}
+<!--top of your baseof code-->
+<main>
+ <article>
+ <header>
+ <h1>My Go Journey</h1>
+ </header>
+ <p>I decided to start learning Go in March 2017.</p>
+ <p>Follow my journey through this new blog.</p>
+ </article>
+ <ul>
+ <li><a href="/posts/post-01/">Post 1</a></li>
+ <li><a href="/posts/post-02/">Post 2</a></li>
+ </ul>
+</main>
+<!--bottom of your baseof-->
+{{< /code >}}
+
+### List Pages Without `_index.md`
+
+You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc.
+
+Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
+
+{{< code file="example.com/quote/index.html" copy="false" >}}
+<!--baseof-->
+<main>
+ <article>
+ <header>
+ <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
+ <h1>Quotes</h1>
+ </header>
+ </article>
+ <ul>
+ <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
+ <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
+ </ul>
+</main>
+<!--baseof-->
+{{< /code >}}
+
+{{% note %}}
+The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
+{{% /note %}}
+
+## Example List Templates
+
+### Section Template
+
+This list template has been modified slightly from a template originally used in [spf13.com](https://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base]. The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
+
+{{< code file="layouts/section/posts.html" >}}
+{{ partial "header.html" . }}
+{{ partial "subheader.html" . }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <ul>
+ <!-- Renders the li.html content view for each content/posts/*.md -->
+ {{ range .Pages }}
+ {{ .Render "li"}}
+ {{ end }}
+ </ul>
+ </div>
+</main>
+{{ partial "footer.html" . }}
+{{< /code >}}
+
+### Taxonomy Template
+
+{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}}
+{{ define "main" }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
+ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</main>
+{{ end }}
+{{< /code >}}
+
+## Order Content
+
+Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
+
+### Default: Weight > Date > LinkTitle > FilePath
+
+{{< code file="layouts/partials/default-order.html" >}}
+<ul>
+ {{ range .Pages }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Weight
+
+Lower weight gets higher precedence. So content with lower weight will come first.
+
+{{< code file="layouts/partials/by-weight.html" >}}
+<ul>
+ {{ range .Pages.ByWeight }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Date
+
+{{< code file="layouts/partials/by-date.html" >}}
+<ul>
+ <!-- orders content according to the "date" field in front matter -->
+ {{ range .Pages.ByDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Publish Date
+
+{{< code file="layouts/partials/by-publish-date.html" >}}
+<ul>
+ <!-- orders content according to the "publishdate" field in front matter -->
+ {{ range .Pages.ByPublishDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Expiration Date
+
+{{< code file="layouts/partials/by-expiry-date.html" >}}
+<ul>
+ {{ range .Pages.ByExpiryDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Last Modified Date
+
+{{< code file="layouts/partials/by-last-mod.html" >}}
+<ul>
+ <!-- orders content according to the "lastmod" field in front matter -->
+ {{ range .Pages.ByLastmod }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Length
+
+{{< code file="layouts/partials/by-length.html" >}}
+<ul>
+ <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
+ {{ range .Pages.ByLength }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Title
+
+{{< code file="layouts/partials/by-title.html" >}}
+<ul>
+ <!-- ranges through content in ascending order according to the "title" field set in front matter -->
+ {{ range .Pages.ByTitle }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Link Title
+
+{{< code file="layouts/partials/by-link-title.html" >}}
+<ul>
+ <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
+ {{ range .Pages.ByLinkTitle }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Parameter
+
+Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
+
+{{< code file="layouts/partials/by-rating.html" >}}
+<!-- Ranges through content according to the "rating" field set in front matter -->
+{{ range (.Pages.ByParam "rating") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+If the targeted front matter field is nested beneath another field, you can access the field using dot notation.
+
+{{< code file="layouts/partials/by-nested-param.html" >}}
+{{ range (.Pages.ByParam "author.last_name") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+### Reverse Order
+
+Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
+
+{{< code file="layouts/partials/by-date-reverse.html" >}}
+<ul>
+ {{ range .Pages.ByDate.Reverse }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+## Group Content
+
+Hugo provides some functions for grouping pages by Section, Type, Date, etc.
+
+### By Page Field
+
+{{< code file="layouts/partials/by-page-field.html" >}}
+<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
+{{ range .Pages.GroupBy "Section" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
+
+{{< code file="layouts/partials/by-page-field.html" >}}
+<!-- Groups content according to content section.-->
+{{ range .Pages.GroupBy "Section" }}
+<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
+{{ with $.Site.GetPage "section" .Key }}
+<h3>{{.Title}}</h3>
+{{ else }}
+<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
+<h3>{{ .Key | title }}</h3>
+{{ end }}
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Date
+
+{{< code file="layouts/partials/by-page-date.html" >}}
+<!-- Groups content by month according to the "date" field in front matter -->
+{{ range .Pages.GroupByDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
++{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
++
+### By Publish Date
+
+{{< code file="layouts/partials/by-page-publish-date.html" >}}
+<!-- Groups content by month according to the "publishDate" field in front matter -->
+{{ range .Pages.GroupByPublishDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
++{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
+
+### By Lastmod
+
+{{< code file="layouts/partials/by-page-lastmod.html" >}}
+<!-- Groups content by month according to the "lastMod" field in front matter -->
+{{ range .Pages.GroupByLastmod "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Lastmod.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
++{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
++
+### By Expiry Date
+
+{{< code file="layouts/partials/by-page-expiry-date.html" >}}
+<!-- Groups content by month according to the "expiryDate" field in front matter -->
+{{ range .Pages.GroupByExpiryDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
++{{< new-in "0.97.0" >}} `GroupByDate` accepts the same time layouts as in [time.Format](/functions/dateformat/) and The `.Key` in the result will be localized for the current language.
++
+### By Page Parameter
+
+{{< code file="layouts/partials/by-page-param.html" >}}
+<!-- Groups content according to the "param_key" field in front matter -->
+{{ range .Pages.GroupByParam "param_key" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page Parameter in Date Format
+
+The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo.
+
+{{< code file="layouts/partials/by-page-param-as-date.html" >}}
+<!-- Groups content by month according to the "param_key" field in front matter -->
+{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### Reverse Key Order
+
+Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates.
+
+While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way.
+
+#### 1. Adding the Reverse Method
+
+```
+{{ range (.Pages.GroupBy "Section").Reverse }}
+```
+
+```
+{{ range (.Pages.GroupByDate "2006-01").Reverse }}
+```
+
+#### 2. Providing the Alternate Direction
+
+```
+{{ range .Pages.GroupByDate "2006-01" "asc" }}
+```
+
+```
+{{ range .Pages.GroupBy "Section" "desc" }}
+```
+
+### Order Within Groups
+
+Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available.
+
+Here is the ordering for the example that follows:
+
+1. Content is grouped by month according to the `date` field in front matter.
+2. Groups are listed in ascending order (i.e., the oldest groups first)
+3. Pages within each respective group are ordered alphabetically according to the `title`.
+
+{{< code file="layouts/partials/by-group-by-page.html" >}}
+{{ range .Pages.GroupByDate "2006-01" "asc" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages.ByTitle }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+## Filtering and Limiting Lists {#filtering-and-limiting-lists}
+
+Sometimes you only want to list a subset of the available content. A
+common is to only display posts from [**main sections**][mainsections]
+on the blog's homepage.
+
+See the documentation on [`where` function][wherefunction] and
+[`first` function][firstfunction] for further details.
+
+[base]: /templates/base/
+[bepsays]: https://bepsays.com/en/2016/12/19/hugo-018/
+[directorystructure]: /getting-started/directory-structure/
+[`Format` function]: /functions/format/
+[front matter]: /content-management/front-matter/
+[getpage]: /functions/getpage/
+[homepage]: /templates/homepage/
+[homepage]: /templates/homepage/
+[mentalmodel]: https://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[RSS 2.0]: https://cyber.harvard.edu/rss/rss.html "RSS 2.0 Specification"
+[rss]: /templates/rss/
+[sections]: /content-management/sections/
+[sectiontemps]: /templates/section-templates/
+[sitevars]: /variables/site/
+[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates
+[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates
+[taxvars]: /variables/taxonomy/
+[views]: /templates/views/
+[wherefunction]: /functions/where/
+[firstfunction]: /functions/first/
+[mainsections]: /functions/where/#mainsections
--- /dev/null
- {{< new-in "0.62.0" >}} Note that this is only supported with the [Goldmark](#goldmark) renderer.
+---
+title: "Markdown Render Hooks"
+linkTitle: "Render Hooks"
+description: "Render Hooks allow custom templates to override markdown rendering functionality."
+date: 2017-03-11
+categories: [templates]
+keywords: [markdown]
+toc: true
+menu:
+ docs:
+ title: "Markdown Render Hooks"
+ parent: "templates"
+ weight: 20
+---
+
++{{< new-in "0.62.0" >}} Note that this is only supported with the [Goldmark](/getting-started/configuration-markup#goldmark) renderer.
+
+
+You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` 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 hook kinds currently supported are:
+
+* `image`
+* `link`
+* `heading` {{< new-in "0.71.0" >}}
+* `codeblock`{{< new-in "0.93.0" >}}
+
+You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
+
+```goat { class="black f7" }
+layouts
+└── _default
+ └── _markup
+ ├── render-image.html
+ ├── render-image.rss.xml
+ └── render-link.html
+ └── render-codeblock.html
+ └── render-codeblock-bash.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 Hooks for Headings, Links and Images
+
+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.
+
+Attributes (map) {{< new-in "0.82.0" >}}
+: A map of attributes (e.g. `id`, `class`)
+
+### 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>
+```
+
+## Render Hooks for Code Blocks
+
+{{< new-in "0.93.0" >}}
+
+You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below):
+
+```goat { class="black f7" }
+layouts
+└── _default
+ └── _markup
+ └── render-codeblock.html
+ └── render-codeblock-bash.html
+```
+
+The default behaviour for these code blocks is to do [Code Highlighting](/content-management/syntax-highlighting/#highlighting-in-code-fences), but since you can pass attributes to these code blocks, they can be used for almost anything. One example would be the built-in [GoAT Diagrams](/content-management/diagrams/#goat-diagrams-ascii) or this [Mermaid Diagram Code Block Hook](/content-management/diagrams/#mermaid-diagrams) example.
+
+The context (the ".") you receive in a code block template contains:
+
+Type (string)
+: The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting.
+
+Attributes (map)
+: Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`).
+
+Options (map)
+: Chroma highlighting processing options. This will only be filled if `Type` is a known [Chroma Lexer](/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).
+
+Inner (string)
+: The text between the code fences.
+
+Ordinal (integer)
+: Zero-based ordinal for all code blocks in the current document.
+
+Page
+: The owning `Page`.
+
+Position
+: Useful in error logging as it prints the filename and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`.
--- /dev/null
- [pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies
+---
+title: Single Page Templates
+linktitle:
+description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-04-06
+categories: [templates]
+keywords: [page,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: [/layout/content/]
+toc: true
+---
+
+## Single Page Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Example Single Page Templates
+
+Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
+
+### `posts/single.html`
+
+This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
+
+{{< code file="layouts/posts/single.html" download="single.html" >}}
+{{ define "main" }}
+<section id="main">
+ <h1 id="title">{{ .Title }}</h1>
+ <div>
+ <article id="content">
+ {{ .Content }}
+ </article>
+ </div>
+</section>
+<aside id="meta">
+ <div>
+ <section>
+ <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
+ <h5 id="wordcount"> {{ .WordCount }} Words </h5>
+ </section>
+ {{ with .Params.topics }}
+ <ul id="topics">
+ {{ range . }}
+ <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ {{ with .Params.tags }}
+ <ul id="tags">
+ {{ range . }}
+ <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </div>
+ <div>
+ {{ with .PrevInSection }}
+ <a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
+ {{ end }}
+ {{ with .NextInSection }}
+ <a class="next" href="{{.Permalink}}"> {{.Title}}</a>
+ {{ end }}
+ </div>
+</aside>
+{{ end }}
+{{< /code >}}
+
+To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
+
+[archetypes]: /content-management/archetypes/
+[base templates]: /templates/base/
+[config]: /getting-started/configuration/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+[`.Format` function]: /functions/format/
+[front matter]: /content-management/front-matter/
++[pagetaxonomy]: /templates/taxonomy-templates/#display-a-single-piece-of-contents-taxonomies
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[section]: /content-management/sections/
+[site variables]: /variables/site/
+[spf13]: https://spf13.com/
+[`with`]: /functions/with/
--- /dev/null
- * 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)
+---
+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:
+
- ## Taxonomy Terms Template
++* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-templates)
++* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
+* 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/).
+
- 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:
++## Taxonomy Terms Templates
+
+### 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-metadata-to-a-taxonomy-or-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
+
+```go-html-template
+<ul>
+ {{ range .Data.Terms.Alphabetical }}
+ <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
+ {{ 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. Zero means "does not have a weight", not "has a weight of numerical value zero".
+
+Weights of zero are thus 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
+
+```go-html-template
+<ul>
+ {{ range (.GetTerms "tags") }}
+ <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
+ {{ 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}
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.tags }}
+ <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
+ {{ 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: Frequently Asked Questions
+linktitle: FAQ
+description: Solutions to some common Hugo problems.
+date: 2018-02-10
+categories: [troubleshooting]
+menu:
+ docs:
+ parent: "troubleshooting"
+keywords: [faqs]
+weight: 2
+toc: true
+aliases: [/faq/]
+---
+
+{{% note %}}
+**Note:** The answers/solutions presented below are short, and may not be enough to solve your problem. Visit [Hugo Discourse](https://discourse.gohugo.io/) and use the search. It that does not help, start a new topic and ask your questions.
+{{% /note %}}
+
+## I can't see my content!
+
+Is your markdown file [in draft mode](https://gohugo.io/content-management/front-matter/#front-matter-variables)? When testing, run `hugo server` with the `-D` or `--buildDrafts` [switch](https://gohugo.io/getting-started/usage/#draft-future-and-expired-content).
+
+## Can I set configuration variables via OS environment?
+
+Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables).
+
+## How do I schedule posts?
+
+1. Set `publishDate` in the page [Front Matter](/content-management/front-matter/) to a datetime in the future. If you want the creation and publication datetime to be the same, it's also sufficient to only set `date`[^date-hierarchy].
+2. Build and publish at intervals.
+
+How to automate the "publish at intervals" part depends on your situation:
+
+* If you deploy from your own PC/server, you can automate with [Cron](https://en.wikipedia.org/wiki/Cron) or similar.
+* If your site is hosted on a service similar to [Netlify](https://www.netlify.com/) you can use a service such as [ifttt](https://ifttt.com/date_and_time) to schedule the updates.
+
+Also see this Twitter thread:
+
+{{< tweet user="ChrisShort" id="962380712027590657" >}}
+
+[^date-hierarchy]: See [Configure Dates](https://gohugo.io/getting-started/configuration/#configure-dates) for the order in which the different date variables are complemented by each other when not explicitly set.
+
+## Can I use the latest Hugo version on Netlify?
+
+Yes you can! Read [this](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify).
+
+## I get "TOCSS ... this feature is not available in your current Hugo version"
+
+If you process `SCSS` or `SASS` to `CSS` in your Hugo project, you need the Hugo `extended` version, or else you may see this error message:
+
+```bash
+error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
+```
+
+We release two set of binaries for technical reasons. The extended version is not what you get by default for some installation methods. On the [release page](https://github.com/gohugoio/hugo/releases), look for archives with `extended` in the name. To build `hugo-extended`, use `go install --tags extended`
+
+To confirm, run `hugo version` and look for the word `extended`.
++
++## Do I need to install Git to create, deploy, and maintain a website with Hugo?
++
++>Technically, no.
++>
++>Practically, yes.
++
++* The primary installation method documented by most (perhaps all) themes is via Git or the Hugo Modules feature.
++* The Hugo Modules feature requires Go, and Go “gets” with Git.
++* A Git repository is required by CI/CD hosting (Bitbucket, Cloudflare, GitHub Pages, GitLab Pages, Netlify, et. al.).
++* The canonical “last modified” date for content is its Git committer date; using anything else is error-prone.
--- /dev/null
- : 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`.
+---
+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
+
+.BundleType
+: the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle.
+
+.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.
+
+.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.
+
+.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 `term`. 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) 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`.
++: 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 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 .Prev}}{{.Prev.Permalink}}{{end}}`. Calling `.Prev` from the last page returns `nil`.
++: 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 slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://golang.org/pkg/strings/#Fields).
+
+.Prev
- : 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`.
++: 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 .Prev}}{{.Prev.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`.
+
+.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`).
+
+.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`
+
+{{< getcontent path="readfiles/pages-vs-site-pages.md" >}}
+
+## 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/
+[bundle]: {{< relref "content-management/page-bundles" >}}
--- /dev/null
- HUGO_VERSION = "0.96.0"
+[build]
+publish = "public"
+command = "hugo --gc --minify"
+
+[context.production.environment]
- HUGO_VERSION = "0.96.0"
++HUGO_VERSION = "0.97.3"
+HUGO_ENV = "production"
+HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
+command = "hugo --gc --minify --enableGitInfo"
+
+[context.split1.environment]
- HUGO_VERSION = "0.96.0"
++HUGO_VERSION = "0.97.3"
+HUGO_ENV = "production"
+
+[context.deploy-preview]
+command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
+
+[context.deploy-preview.environment]
- HUGO_VERSION = "0.96.0"
++HUGO_VERSION = "0.97.3"
+
+[context.branch-deploy]
+command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy.environment]
++HUGO_VERSION = "0.97.3"
+
+[context.next.environment]
+HUGO_ENABLEGITINFO = "true"
+
+[[redirects]]
+from = "/npmjs/*"
+to = "/npmjs/"
+status = 200
projects / brevno-suite / hugo / commitdiff