--- /dev/null
- The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
+---
+title: Menus
+linktitle: Menus
+description: Hugo has a simple yet powerful menu system.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+categories: [content management]
+keywords: [menus]
+draft: false
+menu:
+ docs:
+ parent: "content-management"
+ weight: 120
+weight: 120 #rem
+aliases: [/extras/menus/]
+toc: true
+---
+
+{{% note "Lazy Blogger"%}}
+If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers).
+{{% /note %}}
+
+You can do this:
+
+* Place content in one or many menus
+* Handle nested menus with unlimited depth
+* Create menu entries without being attached to any content
+* Distinguish active element (and active branch)
+
+## What is a Menu in Hugo?
+
+A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
+
+{{% note "Menus on Multilingual Sites" %}}
+If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
+{{% /note %}}
+
+A menu entry has the following properties (i.e., variables) available to it:
+
+`.URL`
+: string
+
+`.Name`
+: string
+
+`.Menu`
+: string
+
+`.Identifier`
+: string
+
+`.Pre`
+: template.HTML
+
+`.Post`
+: template.HTML
+
+`.Weight`
+: int
+
+`.Parent`
+: string
+
+`.Children`
+: Menu
+
+Note that menus also have the following functions available as well:
+
+`.HasChildren`
+: boolean
+
+Additionally, there are some relevant functions available to menus on a page:
+
+`.IsMenuCurrent`
+: (menu string, menuEntry *MenuEntry ) boolean
+
+`.HasMenuCurrent`
+: (menu string, menuEntry *MenuEntry) boolean
+
+## Add content to menus
+
+Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
+
+### Simple
+
+If all you need to do is add an entry to a menu, the simple form works well.
+
+#### A Single Menu
+
+```
+---
+menu: "main"
+---
+```
+
+#### Multiple Menus
+
+```
+---
+menu: ["main", "footer"]
+---
+```
+
+#### Advanced
+
+
+```
+---
+menu:
+ docs:
+ parent: 'extras'
+ weight: 20
+---
+```
+
+## Add Non-content Entries to a Menu
+
+You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config].
+
+Here’s an example snippet pulled from a `config.toml`:
+
+{{< code file="config.toml" >}}
+[[menu.main]]
+ name = "about hugo"
+ pre = "<i class='fa fa-heart'></i>"
+ weight = -110
+ identifier = "about"
+ url = "/about/"
+[[menu.main]]
+ name = "getting started"
+ pre = "<i class='fa fa-road'></i>"
+ weight = -100
+ url = "/getting-started/"
+{{< /code >}}
+
+Here's the equivalent snippet in a `config.yaml`:
+
+{{< code file="config.yml" >}}
+menu:
+ main:
+ - name: "about hugo"
+ pre: "<i class='fa fa-heart'></i>"
+ weight: -110
+ identifier: "about"
+ url: "/about/"
+ - name: "getting started"
+ pre: "<i class='fa fa-road'></i>"
+ weight: -100
+ url: "/getting-started/"
+{{< /code >}}
+
+{{% note %}}
++The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
+{{% /note %}}
+
+## Nesting
+
+All nesting of content is done via the `parent` field.
+
+The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
+
+The following order is used to determine an Identifier:
+
+`.Name > .LinkTitle > .Title`
+
+This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed.
+
+In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field.
+
+## Render Menus
+
+See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
+
+[config]: /getting-started/configuration/
+[multilingual]: /content-management/multilingual/
+[sitevars]: /variables/
--- /dev/null
+---
+title: Multilingual Mode
+linktitle: Multilingual and i18n
+description: Hugo supports the creation of websites with multiple languages side by side.
+date: 2017-01-10
+publishdate: 2017-01-10
+lastmod: 2017-01-10
+categories: [content management]
+keywords: [multilingual,i18n, internationalization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 150
+weight: 150 #rem
+draft: false
+aliases: [/content/multilingual/,/content-management/multilingual/,/tutorials/create-a-multilingual-site/]
+toc: true
+---
+
+You should define the available languages in a `languages` section in your site configuration.
+
+## Configure Languages
+
+The following is an example of a TOML site configuration for a multilingual Hugo project:
+
+{{< code file="config.toml" download="config.toml" >}}
+DefaultContentLanguage = "en"
+copyright = "Everything is mine"
+
+[params.navigation]
+help = "Help"
+
+[languages]
+[languages.en]
+title = "My blog"
+weight = 1
+linkedin = "english-link"
+
+[languages.fr]
+copyright = "Tout est à moi"
+title = "Mon blog"
+weight = 2
+linkedin = "lien-francais"
+
+# skip params key for front matter
+[languages.fr.navigation]
+help = "Aide"
+{{< /code >}}
+
+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).
+
+With the configuration above, all content, sitemap, RSS feeds, paginations,
+and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
+
+When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
+
+If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`.
+
+Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
+
++## Disable a Language
++
++You can disable one or more languages. This can be useful when working on a new translation.
++
++```toml
++disableLanguages = ["fr", "jp"]
++```
++
++Note that you cannot disable the default content language.
++
++We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables):
++
++```bash
++HUGO_DISABLELANGUAGES="fr jp" 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:
+
+```bash
+[languages]
+[languages.no]
+baseURL = "https://example.no"
+languageName = "Norsk"
+weight = 1
+title = "På norsk"
+
+[languages.en]
+baseURL = "https://example.com"
+languageName = "English"
+weight = 2
+title = "In English"
+```
+
+With the above, the two sites will be generated into `public` with their own root:
+
+```bash
+public
+├── en
+└── no
+```
+
+**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 typlically see something like this in the console:
+
+```bash
+Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1)
+Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
+Press Ctrl+C to stop
+```
+
+Live reload and `--navigateToChanged` between the servers work as expected.
+
+## Taxonomies and Blackfriday
+
+Taxonomies and [Blackfriday configuration][config] can also be set per language:
+
+
+{{< code file="bf-config.toml" >}}
+[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 >}}
+
+## Translate Your Content
+
+Translated articles are identified by the name of the content file.
+
+### Examples of Translated Articles
+
+1. `/content/about.en.md`
+2. `/content/about.fr.md`
+
+In this example, the `about.md` will be assigned the configured `defaultContentLanguage`.
+
+1. `/content/about.md`
+2. `/content/about.fr.md`
+
+This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`.
+
+By having the same **directory and base filename**, the content pieces are linked together as translated pieces.
+
+You can also set the key used to link the translations explicitly in front matter:
+
+```yaml
+translationKey: "my-story"
+```
+
+
+{{% note %}}
+**Before Hugo 0.31**, the file's directory was not considered when looking for translations. This did not work when you named all of your content files, say, `index.md`. Now we use the full content path.
+{{% /note %}}
+
+If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
+
+```yaml
+slug: "a-propos"
+
+```
+
+At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages.
+
+
+## Link to 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, be it for 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 itself. Called on the home page it can be used to build a language navigator:
+
+
+{{< code file="layouts/partials/allLanguages.html" >}}
+<ul>
+{{ range $.Site.Home.AllTranslations }}
+<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+## Translation of Strings
+
+Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
+
+Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc.
+
+{{% note %}}
+From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything.
+
+See https://github.com/gohugoio/hugo/issues/3564
+
+{{% /note %}}
+
+From within your templates, use the `i18n` function like this:
+
+```
+{{ i18n "home" }}
+```
+
+This uses a definition like this one in `i18n/en-US.toml`:
+
+```
+[home]
+other = "Home"
+```
+
+Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
+
+```
+{{ i18n "wordCount" . }}
+```
+
+This uses a definition like this one in `i18n/en-US.toml`:
+
+```
+[wordCount]
+other = "This article has {{ .WordCount }} words."
+```
+An example of singular and plural form:
+
+```
+[readingTime]
+one = "One minute read"
+other = "{{.Count}} minutes read"
+```
+And then in the template:
+
+```
+{{ i18n "readingTime" .ReadingTime }}
+```
+To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
+
+```
+ hugo --i18n-warnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Customize Dates
+
+At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content:
+
+~~~yaml
+1: "janvier"
+2: "février"
+3: "mars"
+4: "avril"
+5: "mai"
+6: "juin"
+7: "juillet"
+8: "août"
+9: "septembre"
+10: "octobre"
+11: "novembre"
+12: "décembre"
+~~~
+
+... then index the non-English date names in your templates like so:
+
+~~~html
+<time class="post-date" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" | safeHTML }}">
+ Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
+</time>
+~~~
+
+This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file.
+
+## Menus
+
+You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
+
+```
+defaultContentLanguage = "en"
+
+[languages.en]
+weight = 0
+languageName = "English"
+
+[[languages.en.menu.main]]
+url = "/"
+name = "Home"
+weight = 0
+
+
+[languages.de]
+weight = 10
+languageName = "Deutsch"
+
+[[languages.de.menu.main]]
+url = "/"
+name = "Startseite"
+weight = 0
+```
+
+The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory.
+
+```
+<ul>
+ {{- $currentPage := . -}}
+ {{ range .Site.Menus.main -}}
+ <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
+ <a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
+ </li>
+ {{- end }}
+</ul>
+
+```
+
+## Missing translations
+
+If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
+
+While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
+
+{{% note %}}
+Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments.
+{{% /note %}}
+
+## 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 `.URL`
+* Be constructed with
+ * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR**
+ * Prefixed with `{{ .LanguagePrefix }}`
+
+If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites.
+
+[abslangurl]: /functions/abslangurl
+[config]: /getting-started/configuration/
+[contenttemplate]: /templates/single-page-templates/
+[go-i18n-source]: https://github.com/nicksnyder/go-i18n
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[homepage]: /templates/homepage/
+[i18func]: /functions/i18n/
+[menus]: /content-management/menus/
+[rellangurl]: /functions/rellangurl
+[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[singles]: /templates/single-page-templates/
--- /dev/null
- type as a content resource as long as it is a MIME type recognized by
- Hugo (`json` files will, as one example, work fine). If you want to
- get exotic, you can define your own media type.
+---
+title : "Page Bundles"
+description : "Content organization using Page Bundles"
+date : 2018-01-24T13:09:00-05:00
+lastmod : 2018-01-28T22:26:40-05:00
+linktitle : "Page Bundles"
+keywords : ["page", "bundle", "leaf", "branch"]
+categories : ["content management"]
+toc : true
+menu :
+ docs:
+ identifier : "page-bundles"
+ parent : "content-management"
+ weight : 11
+---
+
+Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
+
+A Page Bundle can be one of:
+
+- Leaf Bundle (leaf means it has no children)
+- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
+
+| | Leaf Bundle | Branch Bundle |
+|-----------------|--------------------------------------------------------|---------------------------------------------------------|
+| Usage | Collection of resources (pages, images etc.) for single pages | Collection of non-page resources (images etc.)for list pages |
+| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
+| Layout type | `single` | `list` |
+| Nesting | Doesn't allow nesting of more bundles under it | Allows nesting of leaf/branch bundles under it |
+| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
+
+
+## Leaf Bundles {#leaf-bundles}
+
+A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
+directory, that contains an **`index.md`** file.
+
+### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
+
+```text
+content/
+├── about
+│ ├── index.md
+├── posts
+│ ├── my-post
+│ │ ├── content1.md
+│ │ ├── content2.md
+│ │ ├── image1.jpg
+│ │ ├── image2.png
+│ │ └── index.md
+│ └── my-another-post
+│ └── index.md
+│
+└── another-section
+ ├── ..
+ └── not-a-leaf-bundle
+ ├── ..
+ └── another-leaf-bundle
+ └── index.md
+```
+
+In the above example `content/` directory, there are four leaf
+bundles:
+
+about
+: This leaf bundle is at the root level (directly under
+ `content` directory) and has only the `index.md`.
+
+my-post
+: This leaf bundle has the `index.md`, two other content
+ Markdown files and two image files.
+
+my-another-post
+: This leaf bundle has only the `index.md`.
+
+another-leaf-bundle
+: This leaf bundle is nested under couple of
+ directories. This bundle also has only the `index.md`.
+
+{{% note %}}
+The hierarchy depth at which a leaf bundle is created does not matter,
+as long as it is not inside another **leaf** bundle.
+{{% /note %}}
+
+
+### Headless Bundle {#headless-bundle}
+
+A headless bundle is a bundle that is configured to not get published
+anywhere:
+
+- It will have no `Permalink` and no rendered HTML in `public/`.
+- It will not be part of `.Site.RegularPages`, etc.
+
+But you can get it by `.Site.GetPage`. Here is an example:
+
+```html
+{{ $headless := .Site.GetPage "page" "some-headless-bundle" }}
+{{ $reusablePages := $headless.Resources.Match "author*" }}
+<h2>Authors</h2>
+{{ range $reusablePages }}
+ <h3>{{ .Title }}</h3>
+ {{ .Content }}
+{{ end }}
+```
+
+A leaf bundle can be made headless by adding below in the Front Matter
+(in the `index.md`):
+
+```toml
+headless = true
+```
+
+{{% note %}}
+Only leaf bundles can be made headless.
+{{% /note %}}
+
+There are many use cases of such headless page bundles:
+
+- Shared media galleries
+- Reusable page content "snippets"
+
+
+## Branch Bundles {#branch-bundles}
+
+A _Branch Bundle_ is any directory at any hierarchy within the
+`content/` directory, that contains at least an **`_index.md`** file.
+
+This `_index.md` can also be directly under the `content/` directory.
+
+{{% note %}}
+Here `md` (markdown) is used just as an example. You can use any file
++type as a content resource as long as it is a content type recognized by Hugo.
+{{% /note %}}
+
+
+### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization}
+
+```text
+content/
+├── branch-bundle-1
+│ ├── branch-content1.md
+│ ├── branch-content2.md
+│ ├── image1.jpg
+│ ├── image2.png
+│ └── _index.md
+└── branch-bundle-2
+ ├── _index.md
+ └── a-leaf-bundle
+ └── index.md
+```
+
+In the above example `content/` directory, there are two branch
+bundles (and a leaf bundle):
+
+`branch-bundle-1`
+: This branch bundle has the `_index.md`, two
+ other content Markdown files and two image files.
+
+`branch-bundle-2`
+: This branch bundle has the `_index.md` and a
+ nested leaf bundle.
+
+{{% note %}}
+The hierarchy depth at which a branch bundle is created does not
+matter.
+{{% /note %}}
+
+[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type.
--- /dev/null
- blog
- ├── funny-cats
- │ └── kittens
- │ └── _index.md
- └── tech
- └── _index.md
+---
+title: Content Sections
+linktitle: Sections
+description: "Hugo generates a **section tree** that matches your content."
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [content management]
+keywords: [lists,sections,content types,organization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 50
+weight: 50 #rem
+draft: false
+aliases: [/content/sections/]
+toc: true
+---
+
++A **Section** is a collection of pages that gets defined based on the
++organization structure under the `content/` directory.
++
++By default, all the **first-level** directories under `content/` form their own
++sections (**root sections**).
++
++If a user needs to define a section `foo` at a deeper level, they need to create
++a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
++for more information).
++
++
++{{% note %}}
++A **section** cannot be defined or overridden by a front matter parameter -- it
++is strictly derived from the content organization structure.
++{{% /note %}}
+
+## Nested Sections
+
+The sections can be nested as deeply as you need.
+
+```bash
-
- **The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
-
++content
++└── blog <-- Section, because first-level dir under content/
++ ├── funny-cats
++ │ ├── mypost.md
++ │ └── kittens <-- Section, because contains _index.md
++ │ └── _index.md
++ └── tech <-- Section, because contains _index.md
++ └── _index.md
+```
+
- When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`).
++**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
+
+{{% note %}}
-
++When we talk about a **section** in correlation with template selection, it is
++currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
+
+If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
+{{% /note %}}
+
-
+## Example: Breadcrumb Navigation
+
+With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
+
- Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
+{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
+<ol class="nav navbar-nav">
+ {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
+</ol>
+{{ define "breadcrumbnav" }}
+{{ if .p1.Parent }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }}
+{{ else if not .p1.IsHome }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }}
+{{ end }}
+<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
+ <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
+</li>
+{{ end }}
+{{< /code >}}
+
+## Section Page Variables and Methods
+
+Also see [Page Variables](/variables/page/).
+
+{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}}
+
+## Content Section Lists
+
- By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
++Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
+
+## Content *Section* vs Content *Type*
+
-
-
++By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
+
+[archetype]: /content-management/archetypes/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[section templates]: /templates/section-templates/
++[branch bundles]: /content-management/page-bundles/#branch-bundles
--- /dev/null
- Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Intial Caps.
+---
+title: title
+# linktitle:
+description: Converts all characters in the provided string to title case.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [strings]
+signature: ["title INPUT"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
+
+```
+{{title "BatMan"}}` → "Batman"
+```
+
++Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Initial Caps.
+
+```
+{{ range $name, $items := .Site.Taxonomies.categories }}
+ <li><a href="{{ printf "%s/%s" "categories" ($name | urlize | lower) | absURL }}">{{ $name | humanize | title }} ({{ len $items }})</a></li>
+{{ end }}
+```
--- /dev/null
- The following is the full list of Hugo-defined variables with its default value in parens.
+---
+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
+---
+
++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 %}}
+
+## All Configuration Settings
+
- config ("config.toml")
- : Config file (default is path/config.yaml|json|toml).
-
++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 ("archetypes")
+: The directory where Hugo finds archetype files (content templates).
+
+baseURL
+: Hostname (and path) to the root, e.g. http://bep.is/
+
++blackfriday
++: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday)
++
+buildDrafts (false)
+: Include drafts when building.
+
+buildExpired (false)
+: Include content already expired.
+
+buildFuture (false)
+: Include content with publishdate in the future.
+
+canonifyURLs (false)
+: Enable to turn relative URLs into absolute.
+
- : Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/.
+contentDir ("content")
+: The directory from where Hugo reads content files.
+
+dataDir ("data")
+: The directory from where Hugo reads data files.
+
+defaultContentLanguage ("en")
+: Content without language indicator will default to this language.
+
+defaultContentLanguageInSubdir (false)
- : Allows you to disable all page types and will render nothing related to 'kind'. Allowed values are "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404".
++: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`.
+
+disableHugoGeneratorInject (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 ([])
- : Turn off automatic live reloading of browser window.
++: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`.
+
+disableLiveReload (false)
- : Do not make the url/path to lowercase.
++: Disable automatic live reloading of browser window.
+
+disablePathToLower (false)
- : Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com.
++: Do not convert the url/path to lowercase.
+
+enableEmoji (false)
- : If the Hugo site is versioned by Git, you will then get a `.GitInfo` object per page, and `Lastmod` will get updated by the last commit date for content.
++: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/).
+
+enableGitInfo (false)
- : Show a placeholder instead of the default value or an empty string if a translation is missing
++: 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.
+
+enableMissingTranslationPlaceholders (false)
- : When enabled, Hugo will generate a `robots.txt` file.
++: Show a placeholder instead of the default value or an empty string if a translation is missing.
+
+enableRobotsTXT (false)
- : A prefix for your footnote anchors.
++: Enable generation of `robots.txt` file.
+
+frontmatter
+
+: See [Front matter Configuration](#configure-front-matter).
+
+footnoteAnchorPrefix ("")
- : A return link for your footnote.
++: Prefix for footnote anchors.
+
+footnoteReturnLinkContents ("")
- : google analytics tracking id
++: Text to display for footnote return links.
+
+googleAnalytics ("")
- : If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly in CJK languages.
++: Google Analytics tracking ID.
+
+hasCJKLanguage (false)
- : "toml","yaml", or "json"
++: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages.
+
+imaging
+: See [Image Processing Config](/content-management/image-processing/#image-processing-config).
+
+languages
+: See [Configure Languages](/content-management/multilingual/#configure-languages).
+
+languageCode ("")
+: The site's language code.
+
++disableLanguages
++: See [Disable a Language](/content-management/multilingual/#disable-a-language)
++
+layoutDir ("layouts")
+: The directory from where Hugo reads layouts (templates).
+
+log (false)
+: Enable logging.
+
+logFile ("")
+: Log File path (if set, logging enabled automatically).
+
+menu
+: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu).
+
+metaDataFormat ("toml")
- : Don't sync modification time of files
++: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`.
+
+newContentEditor ("")
+: The editor to use when creating new content.
+
+noChmod (false)
+: Don't sync permission mode of files.
+
+noTimes (false)
- : Default number of pages per page in pagination.
++: Don't sync modification time of files.
+
+paginate (10)
- : The path element used during pagination (http://example.com/page/2).
++: Default number of pages per page in [pagination](/templates/pagination/).
+
+paginatePath ("page")
- : See [Content Management](/content-management/urls/#permalinks)
++: The path element used during pagination (https://example.com/page/2).
+
+permalinks
- : Pluralize titles in lists using inflect.
++: See [Content Management](/content-management/urls/#permalinks).
+
+pluralizeListTitles (true)
- : Enables syntax guessing for code fences without specified language.
++: Pluralize titles in lists.
+
+preserveTaxonomyNames (false)
+: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
+
+publishDir ("public")
+: The directory to where Hugo will write the final static site (the HTML files etc.).
+
+pygmentsCodeFencesGuessSyntax (false)
- : Color-codes for highlighting derived from this style. See https://help.farbox.com/pygments.html
++: Enable syntax guessing for code fences without specified language.
+
+pygmentsStyle ("monokai")
- : Enable to use external CSS for code highlighting.
++: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html).
+
+pygmentsUseClasses (false)
- rssLimit (15)
++: Enable using external CSS for syntax highlighting.
+
+related
+: See [Related Content](/content-management/related/#configure-related-content).
+
+relativeURLs (false)
+: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
+
- sectionPagesMenu ("")(
++rssLimit (unlimited)
+: Maximum number of items in the RSS feed.
+
- : Default sitemap configuration.
++sectionPagesMenu ("")
+: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers).
+
+sitemap
- : The length of text to show in a `.Summary`.
++: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml).
+
+staticDir ("static")
+: Relative directory from where Hugo reads static files.
+
+stepAnalysis (false)
+: Display memory and timing of different steps of the program.
+
+summaryLength (70)
- : See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies)
++: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting).
+
+taxonomies
- : Theme to use (located by default in /themes/THEMENAME/)
++: See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies).
+
+theme ("")
- : When enabled creates URL on the form `/filename.html` instead of `/filename/`
++: Theme to use (located by default in `/themes/THEMENAME/`).
+
+themesDir ("themes")
+: The directory where Hugo reads the themes from.
+
+title ("")
+: Site title.
+
+uglyURLs (false)
++: When enabled, creates URL on the form `/filename.html` instead of `/filename/`.
+
+verbose (false)
+: Enable verbose output.
+
+verboseLog (false)
+: Enable verbose logging.
+
+watch (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 %}}
+
+## 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.
+
+## YAML Configuration
+
+The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
+
+{{< code file="config.yml">}}
+baseURL: "https://yoursite.example.com/"
+title: "My Hugo Site"
+footnoteReturnLinkContents: "↩"
+permalinks:
+ post: /:year/:month/:title/
+params:
+ Subtitle: "Hugo is Absurdly Fast!"
+ AuthorName: "Jon Doe"
+ GitHubUser: "spf13"
+ ListOfFoo:
+ - "foo1"
+ - "foo2"
+ SidebarRecentLimit: 5
+{{< /code >}}
+
+## TOML Configuration
+
+The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
+
+{{< code file="config.toml">}}
+contentDir = "content"
+layoutDir = "layouts"
+publishDir = "public"
+buildDrafts = false
+baseURL = "https://yoursite.example.com/"
+canonifyURLs = true
+title = "My Hugo Site"
+
+[taxonomies]
+ category = "categories"
+ tag = "tags"
+
+[params]
+ subtitle = "Hugo is Absurdly Fast!"
+ author = "John Doe"
+{{< /code >}}
+
+
+
+## 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.
+{{% /note %}}
+
+{{< todo >}}
+Test and document setting params via JSON env var.
+{{< /todo >}}
+
+## Ignore Files When Rendering
+
+The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering:
+
+```
+ignoreFiles = [ "\\.foo$", "\\.boo$" ]
+```
+
+The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
+
+## 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:
+
+```toml
+[frontmatter]
+date = ["date","publishDate", "lastmod"]
+lastmod = [":git" "lastmod", "date","publishDate"]
+publishDate = ["publishDate", "date"]
+expiryDate = ["expiryDate"]
+```
+
+If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`:
+
+ ```toml
+[frontmatter]
+date = [ "myDate", ":default"]
+```
+
+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:
+
+ ```toml
+[frontmatter]
+lastmod = ["lastmod" ,":fileModTime", ":default"]
+```
+
+
+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, `218-02-22-mypage.md` will extract the date `218-02-22`. Also, if `slug is not set, `mypage` will be used as the value for `.Slug`.
+
+An example:
+
+```toml
+[frontmatter]
+date = [":filename", ":default"]
+```
+
+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 Blackfriday
+
+[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.
+
+Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well.
+
+However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)).
+
+{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}}
+
+{{% note %}}
+1. Blackfriday flags are *case sensitive* as of Hugo v0.15.
+2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
+{{% /note %}}
+
+{{< code file="bf-config.toml" >}}
+[blackfriday]
+ angledQuotes = true
+ fractions = false
+ plainIDAnchors = true
+ extensions = ["hardLineBreak"]
+{{< /code >}}
+
+{{< code file="bf-config.yml" >}}
+blackfriday:
+ angledQuotes: true
+ fractions: false
+ plainIDAnchors: true
+ extensions:
+ - hardLineBreak
+{{< /code >}}
+
+## 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.
+
+## 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]: http://yaml.org/spec/
--- /dev/null
- 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.
+---
+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.
- : stores all the static content for your future website: 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.
++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.
+
+[`config.toml`](/getting-started/configuration/)
+: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the 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.
+
+[`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 for your future website: 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 %}}
+
+{{% note %}}
+Hugo does not currently ship with an asset pipeline ([#3207](https://github.com/gohugoio/hugo/issues/3207)). You can solicit support from the community in the [Hugo forums](https://discourse.gohugo.io) or check out a few of the [Hugo starter kits](/tools/starter-kits/) for examples of how Hugo developers are managing static assets.
+{{% /note %}}
+
+
+[archetypes]: /content-management/archetypes/
+[configuration directives]: /getting-started/configuration/#all-variables-yaml
+[`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/
--- /dev/null
- This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most noteable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier.
+
+---
+date: 2017-10-16
+title: "Hugo 0.30: Race Car Edition!"
+description: "Fast Render Mode boosts live reloading!"
+categories: ["Releases"]
+slug: "0.30-relnotes"
+images:
+- images/blog/hugo-30-poster.png
+---
+
+
+Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but much wants more. So we added **Fast Render Mode**. It is hard to explain, so start the Hugo development server with `hugo server` and start editing. Live reloads just got so much faster! The "how and what" is discussed at length in [other places](https://github.com/gohugoio/hugo/pull/3959), but the short version is that we now re-render only the parts of the site that you are working on.
+
+The second performance-related feature is a follow-up to the Template Metrics added in Hugo `0.29`. Now, if you add the flag `--templateMetricsHints`, we will calculate a score for how your partials can be cached (with the `partialCached` template func).
+
++This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most notable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier.
+
+This release represents **31 contributions by 10 contributors** to the main Hugo code base.
+[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contribution, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@digitalcraftsman](https://github.com/digitalcraftsman), and [@bmon](https://github.com/bmon) for their ongoing contributions.
+And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition.
+
+Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs),
+which has received **26 contributions by 15 contributors**. A special thanks to [@bep](https://github.com/bep), [@digitalcraftsman](https://github.com/digitalcraftsman), [@moorereason](https://github.com/moorereason), and [@kaushalmodi](https://github.com/kaushalmodi) for their work on the documentation site.
+
+Hugo now has:
+
+* 20195+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 454+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 180+ [themes](http://themes.gohugo.io/)
+
+## Notes
+
+* Running `hugo server` will now run with the new "Fast Render Mode" default on. To turn it off, run `hugo server --disableFastRender` or set `disableFastRender=true` in your site config.
+* There have been several fixes and enhancements in the Chroma highlighter. One is that it now creates Pygments compatible CSS classes, which means that you may want to re-generate the stylesheet. See the [Syntax Highlighting Doc](https://gohugo.io/content-management/syntax-highlighting/).
+
+## Enhancements
+
+### Performance
+* Only re-render the view(s) you're working on [60bd332c](https://github.com/gohugoio/hugo/commit/60bd332c1f68e49e6ac439047e7c660865189380) [@bep](https://github.com/bep) [#3962](https://github.com/gohugoio/hugo/issues/3962)
+* Detect `partialCached` candidates [5800a20a](https://github.com/gohugoio/hugo/commit/5800a20a258378440e203a6c4a4343f5077755df) [@bep](https://github.com/bep)
+* Move metrics output to the end of the site build [b277cb33](https://github.com/gohugoio/hugo/commit/b277cb33e4dfa7440fca3b7888026944ce056154) [@moorereason](https://github.com/moorereason)
+
+### Templates
+
+* Output `xmlns:xhtml` only if there are translations available [0859d9df](https://github.com/gohugoio/hugo/commit/0859d9dfe647db3b8a192da38ad7efb5480a29a1) [@jamieconnolly](https://github.com/jamieconnolly)
+* Add `errorf` template function [4fc67fe4](https://github.com/gohugoio/hugo/commit/4fc67fe44a3c65fc7faaed21d5fa5bb5f87edf2c) [@bmon](https://github.com/bmon) [#3817](https://github.com/gohugoio/hugo/issues/3817)
+* Add `os.FileExists` template function [28188789](https://github.com/gohugoio/hugo/commit/2818878994e906c292cbe00cb2a83f1531a21f32) [@digitalcraftsman](https://github.com/digitalcraftsman) [#3839](https://github.com/gohugoio/hugo/issues/3839)
+* Add `float` template function [57adc539](https://github.com/gohugoio/hugo/commit/57adc539fc98dcb6fba8070b9611b8bd545f6f7f) [@x3ro](https://github.com/x3ro) [#3307](https://github.com/gohugoio/hugo/issues/3307)
+* Rework the partial test and benchmarks [e2e8bcbe](https://github.com/gohugoio/hugo/commit/e2e8bcbec34702a27047b91b6b007a15f1fc0797) [@bep](https://github.com/bep)
+
+### Other
+
+* Change `SummaryLength` to be configurable (#3924) [8717a60c](https://github.com/gohugoio/hugo/commit/8717a60cc030f4310c1779c0cdd51db37ad636cd) [@bmon](https://github.com/bmon) [#3734](https://github.com/gohugoio/hugo/issues/3734)
+* Replace `make` with `mage` in CircleCI build [fe71cb6f](https://github.com/gohugoio/hugo/commit/fe71cb6f5f83cdc8374cf1fc35a6d48102bd4b12) [@bep](https://github.com/bep) [#3969](https://github.com/gohugoio/hugo/issues/3969)
+* Add table `linenos` support for Chroma highlighter [7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)
+* Replace `make` with `mage` [8d2580f0](https://github.com/gohugoio/hugo/commit/8d2580f07c0253e12524a4b5c13165f876d00b21) [@bep](https://github.com/bep) [#3937](https://github.com/gohugoio/hugo/issues/3937)
+* Create `magefile` from `Makefile` [384a6ac4](https://github.com/gohugoio/hugo/commit/384a6ac4bd2de16fcd6a1c952e7ca41b66023a12) [@natefinch](https://github.com/natefinch)
+* Clean up lint in various packages [47fdfd51](https://github.com/gohugoio/hugo/commit/47fdfd5196cd24a23b30afe1d88969ffb413ab59) [@moorereason](https://github.com/moorereason)
+
+## Fixes
+
+* Make sure `Date` and `PublishDate` are always set to a value if one is available [6a30874f](https://github.com/gohugoio/hugo/commit/6a30874f19610a38e846e120aac03c68e12f9b7b) [@bep](https://github.com/bep) [#3854](https://github.com/gohugoio/hugo/issues/3854)
+* Add correct config file name to verbose server log [15ec031d](https://github.com/gohugoio/hugo/commit/15ec031d9818d239bfbff525c00cd99cc3118a96) [@mdhender](https://github.com/mdhender)
--- /dev/null
- * `Resources.GetByPrefix` and `Resources.ByPrefix` are depracated. They still work, but will eventually be removed. Use `Resources.Match` (many) and `Resources.GetMatch` (one).
+
+---
+date: 2018-01-22
+title: "Hugo 0.34: Pattern matching to filter images and other resources"
+description: "Hugo 0.34 adds full glob with super-asterisk support, for example `*.jpg`."
+categories: ["Releases"]
+---
+
+Hugo `0.34` is a small release. It contains a few smaller bug-fixes, but more important is an overhaul of the API used to find images and other resources in your page bundles.
+
+We have added two simple methods on the `Resources` object:
+
+* `.Match` finds every resource matching a pattern. Examples: `.Match "images/*.jpg"` finds every JPEG image in `images` and `.Match "**.jpg"` finds every JPEG image in the bundle.
+* `.GetMatch` finds the first resource matching the pattern given.
+
+**Note: The path separators used are Unix-style forward slashes, even on Windows.**
+
+It uses [standard wildcard syntax](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) with the addition of the `**`, aka super-asterisk, which matches across path boundaries.
+
+Thanks to [@gobwas](https://github.com/gobwas/glob) for a fast and easy-to-use Glob library.
+
+This release represents **5 contributions by 1 contributors** to the main Hugo code base.
+
+Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs),
+which has received **25 contributions by 16 contributors**. A special thanks to [@bep](https://github.com/bep), [@rmetzler](https://github.com/rmetzler), [@chris-rudmin](https://github.com/chris-rudmin), and [@stkevintan](https://github.com/stkevintan) for their work on the documentation site.
+
+
+Hugo now has:
+
+* 22689+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 448+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 197+ [themes](http://themes.gohugo.io/)
+
+## Notes
++* `Resources.GetByPrefix` and `Resources.ByPrefix` are deprecated. They still work, but will eventually be removed. Use `Resources.Match` (many) and `Resources.GetMatch` (one).
+* When filtering bundles pages in sub-folders, you need to include the sub-folder when matching. This was a bug introduced in `0.33` and gets it in line with images and other resources.
+
+## Enhancements
+
+* Add `Resources.Match` and `Resources.GetMatch` [94213801](https://github.com/gohugoio/hugo/commit/9421380168f66620cb73203e1267814b3086d805) [@bep](https://github.com/bep) [#4301](https://github.com/gohugoio/hugo/issues/4301)
+
+## Fixes
+* Add validation for `defaultContentLanguage` [4d5e4f37](https://github.com/gohugoio/hugo/commit/4d5e4f379a890a3c6cbc11ddb40d77a90f14c015) [@bep](https://github.com/bep) [#4298](https://github.com/gohugoio/hugo/issues/4298)
+* Fix lookup of pages bundled in sub-folders in `ByPrefix` etc. [5d030869](https://github.com/gohugoio/hugo/commit/5d03086981b4a7d4bc450269a6a2e0fd22dbeed7) [@bep](https://github.com/bep) [#4295](https://github.com/gohugoio/hugo/issues/4295)
--- /dev/null
--- /dev/null
++
++Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo.
++
++Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams.
++
--- /dev/null
--- /dev/null
++---
++title: Forestry.io
++date: 2018-03-16
++description: "A Git-backed CMS (content management system) for websites and web products built using static site generators."
++siteURL: https://forestry.io/
++siteSource: https://github.com/forestryio/forestry.io
++---
++
++It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us?
++
++### Why Hugo?
++
++In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast.
++
++We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look:
++
++```bash
++ | EN
+++------------------+-----+
++ Pages | 141
++ Paginator pages | 4
++ Non-page files | 0
++ Static files | 537
++ Processed images | 0
++ Aliases | 60
++ Sitemaps | 1
++ Cleaned | 0
++
++Total in 739 ms
++```
++
++In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing.
++
++Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website.
++
++### What tools did we use?
++
++* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a designer’s dream come true.
++* Some say our main graphic is [mesmerizing](https://twitter.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
++* [**Hugo**](https://gohugo.io/) -- of course.
++* Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization.
++* Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes.
++* We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia]([https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](https://gohugo.io/templates/output-formats/).
++* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website.
++* We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer.
++* For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/).
++* [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests.
++* We also use browser cookies and JS to customize our user’s experience and give it a more dynamic feel.
--- /dev/null
--- /dev/null
++
++
++Let's Encrypt is a free, automated, and open certificate authority (CA), run for the public's benefit. It is a service provided by the [Internet Security Research Group (ISRG)](https://letsencrypt.org/isrg/).
--- /dev/null
--- /dev/null
++---
++title: "Let’s Encrypt"
++date: 2018-03-13
++description: "Showcase: Lessons learned from taking letsencrypt.org to Hugo."
++siteURL: https://letsencrypt.org/
++siteSource: https://github.com/letsencrypt/website
++byline: "[bep](https://github.com/bep), Hugo Lead"
++---
++
++The **Let’s Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1]
++
++{{< tweet 971755920639307777 >}}
++
++I helped them port the site from Jekyll to Hugo. There are usually very few surprises doing this. I know Hugo very well, but working on sites with a history usually comes up with something new.
++
++That site is bookmarked in many browsers, so preserving the URLs was a must. Hugo's URL handling is very flexible, but there was one challenge. The website has a mix of standard and what we in Hugo call _ugly URLs_ (`https://letsencrypt.org/2017/12/07/looking-forward-to-2018.html`). In Hugo this is handled automatically, and you can turn it on globally or per language. But before Hugo `0.33` you could not configure it for parts of your site. You could set it manually for the relevant pages in front matter -- which is how it was done in Jekyll -- but that would be hard to manage, especially when you start to introduce translations. So, in [Hugo 0.33](https://gohugo.io/news/0.33-relnotes/) I added support for _ugly URLs_ per section and also `url` set in front matter for list pages (`https://letsencrypt.org/blog/`).
++
++The lessons learned from this also lead to [disableLanguages](/content-management/multilingual/#disable-a-language) in Hugo `0.34` (a way to turn off languages during translation). And I also registered [this issue](https://github.com/gohugoio/hugo/issues/4463). Once fixed it will make it easier to handle partially translated sites.
++
++
++[^1]: The work on getting the content translated is in progress.
--- /dev/null
- When including another template, you will pass to it the data it will be
- able to access. To pass along the current context, please remember to
- include a trailing dot. The templates location will always be starting at
- the `/layouts/` directory within Hugo.
+---
+title: Introduction to Hugo Templating
+linktitle: Introduction
+description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+godocref: https://golang.org/pkg/html/template/
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-25
+categories: [templates,fundamentals]
+keywords: [go]
+menu:
+ docs:
+ parent: "templates"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
+toc: true
+---
+
+{{% note %}}
+The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/).
+{{% /note %}}
+
+Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
+
+{{< youtube gnJbPO-GFIw >}}
+
+## Basic Syntax
+
+Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`.
+
+### Access a Predefined Variable
+
+```
+{{ foo }}
+```
+
+Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`:
+
+```
+{{ add 1 2 }}
+```
+
+#### Methods and Fields are Accessed via dot Notation
+
+Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
+
+```
+{{ .Params.bar }}
+```
+
+#### Parentheses Can be Used to Group Items Together
+
+```
+{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
+```
+
+## Variables
+
+Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information.
+
+This is how you access a `Page` variable from a template:
+
+```
+<title>{{ .Title }}</title>
+```
+
+Values can also be stored in custom variables and referenced later:
+
+```
+{{ $address := "123 Main St."}}
+{{ $address }}
+```
+
+{{% warning %}}
+Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608).
+
+Hugo has created a workaround for this issue in [Scratch](/functions/scratch).
+
+{{% /warning %}}
+
+## Functions
+
+Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
+
+[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
+
+### Example 1: Adding Numbers
+
+```
+{{ add 1 2 }}
+=> 3
+```
+
+### Example 2: Comparing Numbers
+
+```
+{{ lt 1 2 }}
+=> true (i.e., since 1 is less than 2)
+```
+
+Note that both examples make use of Go template's [math functions][].
+
+{{% note "Additional Boolean Operators" %}}
+There are more boolean operators than those listed in the Hugo docs in the [Golang template documentation](http://golang.org/pkg/text/template/#hdr-Functions).
+{{% /note %}}
+
+## Includes
+
- ### Template and Partial Examples
++When including another template, you will need to pass it the data that it would
++need to access.
+
- {{ template "partials/header.html" . }}
++{{% note %}}
++To pass along the current context, please remember to include a trailing **dot**.
++{{% /note %}}
++
++The templates location will always be starting at the `layouts/` directory
++within Hugo.
++
++### Partial
++
++The [`partial`][partials] function is used to include *partial* templates using
++the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
++
++Example:
+
+```
- Starting with Hugo v0.12, you may also use the `partial` call
- for [partial templates][partials]:
++{{ partial "header.html" . }}
+```
+
- {{ partial "header.html" . }}
++### Template
++
++The `template` function was used to include *partial* templates in much older
++Hugo versions. Now it is still useful for calling [*internal*
++templates][internal_templates]:
+
+```
- ### Example 4: Internet Explorer Conditional Comments
++{{ template "_internal/opengraph.html" . }}
+```
+
+## Logic
+
+Go templates provide the most basic iteration and conditional logic.
+
+### Iteration
+
+Just like in Go, the Go templates make heavy use of `range` to iterate over
+a map, array, or slice. The following are different examples of how to use
+range.
+
+#### Example 1: Using Context
+
+```
+{{ range array }}
+ {{ . }}
+{{ end }}
+```
+
+#### Example 2: Declaring Value => Variable name
+
+```
+{{range $element := array}}
+ {{ $element }}
+{{ end }}
+```
+
+#### Example 3: Declaring Key-Value Variable Name
+
+```
+{{range $index, $element := array}}
+ {{ $index }}
+ {{ $element }}
+{{ end }}
+```
+
+### Conditionals
+
+`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`.
+
+Go Templates treat the following values as false:
+
+* false
+* 0
+* any zero-length array, slice, map, or string
+
+#### Example 1: `if`
+
+```
+{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
+```
+
+#### Example 2: `if` … `else`
+
+```
+{{ if isset .Params "alt" }}
+ {{ index .Params "alt" }}
+{{else}}
+ {{ index .Params "caption" }}
+{{ end }}
+```
+
+#### Example 3: `and` & `or`
+
+```
+{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
+```
+
+#### Example 4: `with`
+
+An alternative way of writing "`if`" and then referencing the same value
+is to use "`with`" instead. `with` rebinds the context `.` within its scope
+and skips the block if the variable is absent.
+
+The first example above could be simplified as:
+
+```
+{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
+```
+
+#### Example 5: `if` … `else if`
+
+```
+{{ if isset .Params "alt" }}
+ {{ index .Params "alt" }}
+{{ else if isset .Params "caption" }}
+ {{ index .Params "caption" }}
+{{ end }}
+```
+
+## Pipes
+
+One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
+
+Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
+
+A few simple examples should help convey how to use the pipe.
+
+### Example 1: `shuffle`
+
+The following two examples are functionally the same:
+
+```
+{{ shuffle (seq 1 5) }}
+```
+
+
+```
+{{ (seq 1 5) | shuffle }}
+```
+
+### Example 2: `index`
+
+The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates:
+
+```
+{{ index .Params "disqus_url" | html }}
+```
+
+### Example 3: `or` with `isset`
+
+```
+{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
+Stuff Here
+{{ end }}
+```
+
+Could be rewritten as
+
+```
+{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
+Stuff Here
+{{ end }}
+```
+
++### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments}
+
+By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
+
+```
+{{ "<!--[if lt IE 9]>" | safeHTML }}
+ <script src="html5shiv.js"></script>
+{{ "<![endif]-->" | safeHTML }}
+```
+
+Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation:
+
+```
+{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }}
+```
+
+## Context (aka "the dot")
+
+The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following:
+
+### 1. Define a Variable Independent of Context
+
+The following shows how to define a variable independent of the context.
+
+{{< code file="tags-range-with-page-variable.html" >}}
+{{ $title := .Site.Title }}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% note %}}
+Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
+{{% /note %}}
+
+### 2. Use `$.` to Access the Global Context
+
+`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
+
+{{< code file="range-through-tags-w-global.html" >}}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $.Site.Title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% warning "Don't Redefine the Dot" %}}
+The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
+{{% /warning %}}
+
+## Whitespace
+
+Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
+
+For instance, the following Go template will include the newlines and horizontal tab in its HTML output:
+
+```
+<div>
+ {{ .Title }}
+</div>
+```
+
+Which will output:
+
+```
+<div>
+ Hello, World!
+</div>
+```
+
+Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
+
+```
+<div>
+ {{- .Title -}}
+</div>
+```
+
+Which then outputs:
+
+```
+<div>Hello, World!</div>
+```
+
+Go considers the following characters whitespace:
+
+* <kbd>space</kbd>
+* horizontal <kbd>tab</kbd>
+* carriage <kbd>return</kbd>
+* newline
+
++## Comments
++
++In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo.
++
++### Go templates comments
++
++Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
++
++For example:
++
++```
++Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
++```
++
++Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
++
++### HTML comments
++
++If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example:
++
++```
++{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}
++```
++
++#### HTML comments containing Go templates
++
++HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process.
++
++{{% note %}}
++Do **not** try to comment out Go template code using HTML comments.
++{{% /note %}}
++
++```
++<!-- {{ $author := "Emma Goldman" }} was a great woman. -->
++{{ $author }}
++```
++
++The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error.
++
+## Hugo Parameters
+
+Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file.
+
+## Use Content (`Page`) Parameters
+
+You can provide variables to be used by templates in individual content's [front matter][].
+
+An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
+
+Here is the example front matter:
+
+```
+---
+title: Roadmap
+lastmod: 2017-03-05
+date: 2013-11-18
+notoc: true
+---
+```
+
+Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
+
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
+{{ if not .Params.notoc }}
+<aside>
+ <header>
+ <a href="#{{.Title | urlize}}">
+ <h3>{{.Title}}</h3>
+ </a>
+ </header>
+ {{.TableOfContents}}
+</aside>
+<a href="#" id="toc-toggle"></a>
+{{end}}
+{{< /code >}}
+
+We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
+
+## Use Site Configuration Parameters
+
+You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
+
+For instance, you might declare the following:
+
+{{< code file="config.yaml" >}}
+params:
+ copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
+ twitteruser: "spf13"
+ sidebarrecentlimit: 5
+{{< /code >}}
+
+Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
+
+```
+{{if .Site.Params.copyrighthtml}}<footer>
+<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
+</footer>{{end}}
+```
+
+An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
+
+{{< code file="layouts/partials/twitter.html" >}}
+{{with .Site.Params.twitteruser}}
+<div>
+ <a href="https://twitter.com/{{.}}" rel="author">
+ <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
+</div>
+{{end}}
+{{< /code >}}
+
+Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
+
+```
+<nav>
+ <h1>Recent Posts</h1>
+ <ul>
+ {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
+ <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
+ {{- end -}}
+ </ul>
+</nav>
+```
+
+## Example: Show Only Upcoming Events
+
+Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
+
+{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
+<h4>Upcoming Events</h4>
+<ul class="upcoming-events">
+{{ range where .Data.Pages.ByDate "Section" "events" }}
+ {{ if ge .Date.Unix .Now.Unix }}
+ <li>
+ <!-- add span for event type -->
+ <span>{{ .Type | title }} —</span>
+ {{ .Title }} on
+ <!-- add span for event date -->
+ <span>{{ .Date.Format "2 January at 3:04pm" }}</span>
+ at {{ .Params.place }}
+ </li>
+ {{ end }}
+{{ end }}
+</ul>
+{{< /code >}}
+
+
+[`where` function]: /functions/where/
+[config]: /getting-started/configuration/
+[dotdoc]: http://golang.org/pkg/text/template/#hdr-Variables
+[first]: /functions/first/
+[front matter]: /content-management/front-matter/
+[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples."
+[Go html/template]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
+[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
+[index]: /functions/index/
+[math functions]: /functions/math/
+[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs"
++[internal_templates]: /templates/internal/
+[relpermalink]: /variables/page/
+[safehtml]: /functions/safehtml/
+[sitevars]: /variables/site/
+[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
+[where]: /functions/where/
+[with]: /functions/with/
+[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function"
--- /dev/null
- `URL`:
- The relative URL to the current pager
+---
+title: Pagination
+linktitle: Pagination
+description: Hugo supports pagination for your homepage, section pages, and taxonomies.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,pagination]
+menu:
+ docs:
+ parent: "templates"
+ weight: 140
+weight: 140
+sections_weight: 140
+draft: false
+aliases: [/extras/pagination,/doc/pagination/]
+toc: true
+---
+
+The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo.
+
+## Configure Pagination
+
+Pagination can be configured in your [site configuration][configuration]:
+
+`Paginate`
+: default = `10`. This setting can be overridden within the template.
+
+`PaginatePath`
+: default = `page`. Allows you to set a different path for your pagination pages.
+
+Setting `Paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below).
+
+`PaginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`.
+
+## List Paginator Pages
+
+{{% warning %}}
+`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists).
+{{% /warning %}}
+
+There are two ways to configure and use a `.Paginator`:
+
+1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*.
+2. Select a subset of the pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. `{{ range (.Paginate ( first 50 .Data.Pages.ByTitle )).Pages }}`.
+
+For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created.
+
+The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page:
+
+* `{{ range (.Paginator 5).Pages }}`
+* `{{ $paginator := .Paginate (where .Data.Pages "Type" "post") 5 }}`
+
+It is also possible to use the `GroupBy` functions in combination with pagination:
+
+```
+{{ range (.Paginate (.Data.Pages.GroupByDate "2006")).PageGroups }}
+```
+
+## Build the navigation
+
+The `.Paginator` contains enough information to build a paginator interface.
+
+The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
+
+```
+{{ template "_internal/pagination.html" . }}
+```
+
+{{% note "When to Create `.Paginator`" %}}
+If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used.
+{{% /note %}}
+
+The following example shows how to create `.Paginator` before its used:
+
+```
+{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
+{{ template "_internal/pagination.html" . }}
+{{ range $paginator.Pages }}
+ {{ .Title }}
+{{ end }}
+```
+
+Without the `where` filter, the above example is even simpler:
+
+```
+{{ template "_internal/pagination.html" . }}
+{{ range .Paginator.Pages }}
+ {{ .Title }}
+{{ end }}
+```
+
+If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties:
+
+`PageNumber`
+: The current page's number in the pager sequence
+
- `Pages`:
- The pages in the current pager
++`URL`
++: The relative URL to the current pager
+
- [where]: /functions/where/
++`Pages`
++: The pages in the current pager
+
+`NumberOfElements`
+: The number of elements on this page
+
+`HasPrev`
+: Whether there are page(s) before the current
+
+`Prev`
+: The pager for the previous page
+
+`HasNext`
+: Whether there are page(s) after the current
+
+`Next`
+: The pager for the next page
+
+`First`
+: The pager for the first page
+
+`Last`
+: The pager for the last page
+
+`Pagers`
+: A list of pagers that can be used to build a pagination menu
+
+`PageSize`
+: Size of each pager
+
+`TotalPages`
+: The number of pages in the paginator
+
+`TotalNumberOfElements`
+: The number of elements on all pages in this paginator
+
+## Additional information
+
+The pages are built on the following form (`BLANK` means no value):
+
+```
+[SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html
+[SECTION/TAXONOMY/BLANK]/page/2/index.html
+....
+```
+
+
+[`first`]: /functions/first/
+[`last`]: /functions/last/
+[`after`]: /functions/after/
+[configuration]: /getting-started/configuration/
+[lists]: /templates/lists/
++[where]: /functions/where/
--- /dev/null
- {{% note %}}
- Before v0.12, Hugo used the `template` call to include partial templates. When using Hugo v0.12 and newer, be sure to use the `{{ partial "<PATH>/<PARTIAL>.html" . }}` syntax. The old approach will still work but has fewer benefits.
- {{% /note %}}
-
+---
+title: Partial Templates
+linktitle: Partial Templates
+description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,partials]
+menu:
+ docs:
+ parent: "templates"
+ weight: 90
+weight: 90
+sections_weight: 90
+draft: false
+aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
+toc: true
+---
+
+{{< youtube pjS4pOLyB7c >}}
+
+## Partial Template Lookup Order
+
+Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places:
+
+1. `layouts/partials/*<PARTIALNAME>.html`
+2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`
+
+This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize].
+
+## Use Partials in your Templates
+
+All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well:
+
+```
+.
+└── layouts
+ └── partials
+ ├── footer
+ │ ├── scripts.html
+ │ └── site-footer.html
+ ├── head
+ │ ├── favicons.html
+ │ ├── metadata.html
+ │ ├── prerender.html
+ │ └── twitter.html
+ └── header
+ ├── site-header.html
+ └── site-nav.html
+```
+
+All partials are called within your templates using the following pattern:
+
+```
+{{ partial "<PATH>/<PARTIAL>.html" . }}
+```
+
+{{% note %}}
+One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/).
+{{% /note %}}
+
+As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory:
+
+```
+{{ partial "header/site-header.html" . }}
+{{ partial "footer/scripts.html" . }}
+```
+
- [themes]: /themes/
+### Variable Scoping
+
+The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context].
+
+This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`.
+
+### Cached Partials
+
+The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows:
+
+```
+{{ partialCached "footer.html" . }}
+```
+
+You can also pass additional parameters to `partialCached` to create *variants* of the cached partial.
+
+For example, you can tell Hugo to only render the partial `footer.html` once per section:
+
+```
+{{ partialCached "footer.html" . .Section }}
+```
+
+If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
+
+```
+{{ partialCached "footer.html" . .Params.country .Params.province }}
+```
+
+Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key.
+
+### Example `header.html`
+
+The following `header.html` partial template is used for [spf13.com](http://spf13.com/):
+
+{{< code file="layouts/partials/header.html" download="header.html" >}}
+<!DOCTYPE html>
+<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
+<head>
+ <meta charset="utf-8">
+
+ {{ partial "meta.html" . }}
+
+ <base href="{{ .Site.BaseURL }}">
+ <title> {{ .Title }} : spf13.com </title>
+ <link rel="canonical" href="{{ .Permalink }}">
+ {{ if .RSSLink }}<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
+
+ {{ partial "head_includes.html" . }}
+</head>
+<body lang="en">
+{{< /code >}}
+
+{{% note %}}
+The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
+{{% /note %}}
+
+### Example `footer.html`
+
+The following `footer.html` partial template is used for [spf13.com](http://spf13.com/):
+
+{{< code file="layouts/partials/footer.html" download="footer.html" >}}
+<footer>
+ <div>
+ <p>
+ © 2013-14 Steve Francia.
+ <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
+ please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
+ </p>
+ </div>
+</footer>
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script');
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
+ 'http://www') + '.google-analytics.com/ga.js';
+ ga.setAttribute('async', 'true');
+ document.documentElement.firstChild.appendChild(ga);
+ })();
+
+</script>
+</body>
+</html>
+{{< /code >}}
+
+[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context."
+[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order."
+[listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered."
+[lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order."
+[partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page."
+[singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages."
++[themes]: /themes/
--- /dev/null
- ## `.Site.GetPage` with Sections
+---
+title: Section Page Templates
+linktitle: Section Templates
+description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 40
+weight: 40
+sections_weight: 40
+draft: false
+aliases: [/templates/sections/]
+toc: true
+---
+
+## Add Content and Front Matter to Section Templates
+
+To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
+
+## Section Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
- Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
++## Page Kinds
+
- The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
++Every `Page` in Hugo has a `.Kind` attribute.
+
- {{% note %}}
- `.GetPage` is not currently supported to grab single content files but *may* be supported in the future.
- {{% /note %}}
++| Kind | Description | Example |
++|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------|
++| `home` | The home page | `/index.html` |
++| `page` | A page showing a _regular page_ | `my-post` page (`/posts/my-post/index.html`) |
++| `section` | A page listing _regular pages_ from a given [_section_][sections] | `posts` section (`/posts/index.html`) |
++| `taxonomy` | A page listing _regular pages_ from a given _taxonomy term_ | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) |
++| `taxonomyTerm` | A page listing terms from a given _taxonomy_ | page for the `tags` taxonomy (`/tags/index.html`) |
+
- You can call `.Site.GetPage` with two arguments: `kind` and `kind value`.
++## `.Site.GetPage` with Sections
+
- These are the valid values for 'kind':
++`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
++
++The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
+
- 1. `home`
- 2. `section`
- 3. `taxonomy`
- 4. `taxonomyTerm`
++You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values
++of `Kind` from above) and `kind value`.
+
++Examples:
+
++- `{{ .Site.GetPage "section" "posts" }}`
++- `{{ .Site.GetPage "page" "search" }}`
+
+## Example: Creating a Default Section Template
+
+{{< code file="layouts/_default/section.html" download="section.html" >}}
+{{ define "main" }}
+ <main>
+ {{ .Content }}
+ <ul class="contents">
+ {{ range .Paginator.Pages }}
+ <li>{{.Title}}
+ <div>
+ {{ partial "summary.html" . }}
+ </div>
+ </li>
+ {{ end }}
+ </ul>
+ {{ partial "pagination.html" . }}
+ </main>
+{{ end }}
+{{< /code >}}
+
+### Example: Using `.Site.GetPage`
+
+The `.Site.GetPage` example that follows assumes the following project directory structure:
+
+```
+.
+└── content
+ ├── blog
+ │ ├── _index.md # "title: My Hugo Blog" in the front matter
+ │ ├── post-1.md
+ │ ├── post-2.md
+ │ └── post-3.md
+ └── events #Note there is no _index.md file in "events"
+ ├── event-1.md
+ └── event-2.md
+```
+
+`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
+
+```
+<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
+```
+
+Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
+
+```
+<h1>My Hugo Blog</h1>
+```
+
+If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
+
+```
+<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
+```
+
+Which then returns the following:
+
+```
+<h1>Events</h1>
+```
+
+
+[contentorg]: /content-management/organization/
+[getpage]: /functions/getpage/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[where]: /functions/where/
++[sections]: /content-management/sections/
--- /dev/null
- * [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you seperate the Chinese keywords.
+---
+title: Search for your Hugo Website
+linktitle: Search
+description: See some of the open-source and commercial search options for your newly created Hugo website.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-26
+categories: [developer tools]
+keywords: [search,tools]
+menu:
+ docs:
+ parent: "tools"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: []
+toc: true
+---
+
+A static website with a dynamic search function? Yes. As alternatives to embeddable scripts from Google or other search engines, you can provide your visitors a custom search by indexing your content files directly.
+
+* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results.
+* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project.
++* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
+* [Github Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](http://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo!
+
+## Commercial Search Services
+
+* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
projects / brevno-suite / hugo / commitdiff
