--- /dev/null
- suffix = ""
+baseURL = "https://gohugo.io/"
+paginate = 100
+defaultContentLanguage = "en"
+enableEmoji = true
+# Set the unicode character used for the "return" link in page footnotes.
+footnotereturnlinkcontents = "↩"
+languageCode = "en-us"
+metaDataFormat = "yaml"
+title = "Hugo"
+theme = "gohugoioTheme"
+
+googleAnalytics = "UA-7131036-4"
+
+pluralizeListTitles = false
+
+# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
+disableAliases = true
+
+# Highlighting config (Pygments)
+# It is (currently) not in use, but you can do ```go in a content file if you want to.
+pygmentsCodeFences = true
+
+pygmentsOptions = ""
+# Use the Chroma stylesheet
+pygmentsUseClasses = true
+pygmentsUseClassic = false
+
+# See https://help.farbox.com/pygments.html
+pygmentsStyle = "trac"
+
+[outputs]
+home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
+section = [ "HTML", "RSS"]
+
+[mediaTypes]
+[mediaTypes."text/netlify"]
+delimiter = ""
+
+[outputFormats]
+[outputFormats.REDIR]
+mediatype = "text/netlify"
+baseName = "_redirects"
+isPlainText = true
+notAlternative = true
+[outputFormats.HEADERS]
+mediatype = "text/netlify"
+baseName = "_headers"
+isPlainText = true
+notAlternative = true
+
+[related]
+
+threshold = 80
+includeNewer = true
+toLower = false
+
+[[related.indices]]
+name = "keywords"
+weight = 100
+[[related.indices]]
+name = "date"
+weight = 10
+pattern = "2006"
+
+[social]
+twitter = "GoHugoIO"
+
+#CUSTOM PARAMS
+[params]
+ description = "The world’s fastest framework for building websites"
+ ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable)
+ release = "0.45-DEV"
+ ## Setting this to true will add a "noindex" to *EVERY* page on the site
+ removefromexternalsearch = false
+ ## Gh repo for site footer (include trailing slash)
+ ghrepo = "https://github.com/gohugoio/hugoDocs/"
+ ## GH Repo for filing a new issue
+ github_repo = "https://github.com/gohugoio/hugo/issues/new"
+ ### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links)
+ ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs"
+ ## Gitter URL
+ gitter = "https://gitter.im/spf13/hugo"
+ ## Discuss Forum URL
+ forum = "https://discourse.gohugo.io/"
+ ## Google Tag Manager
+ gtmid = ""
+
+ # First one is picked as the Twitter card image if not set on page.
+ images = ["images/gohugoio-card.png"]
+
+ flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height"
+
+ #sidebar_direction = "sidebar_left"
+
+# MARKDOWN
+## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
+[blackfriday]
+ plainIDAnchors = true
+ # See https://github.com/gohugoio/hugo/issues/2424
+ hrefTargetBlank = false
+ angledQuotes = false
+ latexDashes = true
+
+[imaging]
+# See https://github.com/disintegration/imaging
+# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots.
+# Note that you can also set this per image processing.
+resampleFilter = "CatmullRom"
+
+# Defatult JPEG quality setting. Default is 75.
+quality = 75
+
+anchor = "smart"
+
+
+## As of v0.20, all content files include a default "categories" value that's the same as the section. This was a cheap future-proofing method and should/could be changed accordingly.
+[taxonomies]
+ category = "categories"
+
+# High level items
+
+[[menu.docs]]
+ name = "About Hugo"
+ weight = 1
+ identifier = "about"
+ url = "/about/"
+
+[[menu.docs]]
+ name = "Getting Started"
+ weight = 5
+ identifier = "getting-started"
+ url = "/getting-started/"
+
+
+[[menu.docs]]
+ name = "Themes"
+ weight = 15
+ identifier = "themes"
+ post = "break"
+ url = "/themes/"
+
+# Core Menus
+
+[[menu.docs]]
+ name = "Content Management"
+ weight = 20
+ identifier = "content-management"
+ post = "expanded"
+ url = "/content-management/"
+
+[[menu.docs]]
+ name = "Templates"
+ weight = 25
+ identifier = "templates"
+
+ url = "/templates/"
+
+[[menu.docs]]
+ name = "Functions"
+ weight = 30
+ identifier = "functions"
+ url = "/functions/"
+
+[[menu.docs]]
+ name = "Variables"
+ weight = 35
+ identifier = "variables"
+ url = "/variables/"
+
+[[menu.docs]]
+ name = "CLI"
+ weight = 40
+ post = "break"
+ identifier = "commands"
+ url = "/commands/"
+
+
+
+# LOW LEVEL ITEMS
+
+
+[[menu.docs]]
+ name = "Troubleshooting"
+ weight = 60
+ identifier = "troubleshooting"
+ url = "/troubleshooting/"
+
+[[menu.docs]]
+ name = "Tools"
+ weight = 70
+ identifier = "tools"
+ url = "/tools/"
+
+[[menu.docs]]
+ name = "Hosting & Deployment"
+ weight = 80
+ identifier = "hosting-and-deployment"
+ url = "/hosting-and-deployment/"
+
+[[menu.docs]]
+ name = "Contribute"
+ weight = 100
+ post = "break"
+ identifier = "contribute"
+ url = "/contribute/"
+
+#[[menu.docs]]
+# name = "Tags"
+# weight = 120
+# identifier = "tags"
+# url = "/tags/"
+
+
+# [[menu.docs]]
+# name = "Categories"
+# weight = 140
+# identifier = "categories"
+# url = "/categories/"
+
+######## QUICKLINKS
+
+ [[menu.quicklinks]]
+ name = "Fundamentals"
+ weight = 1
+ identifier = "fundamentals"
+ url = "/tags/fundamentals/"
+
+
+
+
+######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES
+
+[[menu.global]]
+ name = "News"
+ weight = 1
+ identifier = "news"
+ url = "/news/"
+
+ [[menu.global]]
+ name = "Docs"
+ weight = 5
+ identifier = "docs"
+ url = "/documentation/"
+
+ [[menu.global]]
+ name = "Themes"
+ weight = 10
+ identifier = "themes"
+ url = "https://themes.gohugo.io/"
+
+ [[menu.global]]
+ name = "Showcase"
+ weight = 20
+ identifier = "showcase"
+ url = "/showcase/"
+
+ # Anything with a weight > 100 gets an external icon
+ [[menu.global]]
+ name = "Community"
+ weight = 150
+ icon = true
+ identifier = "community"
+ post = "external"
+ url = "https://discourse.gohugo.io/"
+
+
+ [[menu.global]]
+ name = "GitHub"
+ weight = 200
+ identifier = "github"
+ post = "external"
+ url = "https://github.com/gohugoio/hugo"
+
+### LANGUAGES ###
+
+[languages]
+ [languages.en]
+ contentDir = "content/en"
+ languageName = "English"
+ weight = 1
+ [languages.zh]
+ contentDir = "content/zh"
+ languageName = "中文"
+ weight = 2
+
+
+### LANGUAGE-SPECIFIC MENUS ###
+
+# Chinese menus
+
+[[languages.zh.menu.docs]]
+ name = "关于 Hugo"
+ weight = 1
+ identifier = "about"
+ url = "/zh/about/"
+
+[[languages.zh.menu.docs]]
+ name = "入门"
+ weight = 5
+ identifier = "getting-started"
+ url = "/zh/getting-started/"
+
+[[languages.zh.menu.docs]]
+ name = "主题"
+ weight = 15
+ identifier = "themes"
+ post = "break"
+ url = "/zh/themes/"
+
+# Core languages.zh.menus
+
+[[languages.zh.menu.docs]]
+ name = "内容管理"
+ weight = 20
+ identifier = "content-management"
+ post = "expanded"
+ url = "/zh/content-management/"
+
+[[languages.zh.menu.docs]]
+ name = "模板"
+ weight = 25
+ identifier = "templates"
+ url = "/zh/templates/"
+
+[[languages.zh.menu.docs]]
+ name = "函数"
+ weight = 30
+ identifier = "functions"
+ url = "/zh/functions/"
+
+[[languages.zh.menu.docs]]
+ name = "变量"
+ weight = 35
+ identifier = "variables"
+ url = "/zh/variables/"
+
+[[languages.zh.menu.docs]]
+ name = "CLI"
+ weight = 40
+ post = "break"
+ identifier = "commands"
+ url = "/commands/"
+
+# LOW LEVEL ITEMS
+[[languages.zh.menu.docs]]
+ name = "故障排除"
+ weight = 60
+ identifier = "troubleshooting"
+ url = "/zh/troubleshooting/"
+
+[[languages.zh.menu.docs]]
+ name = "工具"
+ weight = 70
+ identifier = "tools"
+ url = "/zh/tools/"
+
+[[languages.zh.menu.docs]]
+ name = "托管与部署"
+ weight = 80
+ identifier = "hosting-and-deployment"
+ url = "/zh/hosting-and-deployment/"
+
+[[languages.zh.menu.docs]]
+ name = "贡献"
+ weight = 100
+ post = "break"
+ identifier = "contribute"
+ url = "/zh/contribute/"
+
+[[languages.zh.menu.global]]
+ name = "新闻"
+ weight = 1
+ identifier = "news"
+ url = "/zh/news/"
+
+[[languages.zh.menu.global]]
+ name = "文档"
+ weight = 5
+ identifier = "docs"
+ url = "/zh/documentation/"
+
+[[languages.zh.menu.global]]
+ name = "主题"
+ weight = 10
+ identifier = "themes"
+ url = "https://themes.gohugo.io/"
+
+[[languages.zh.menu.global]]
+ name = "作品展示"
+ weight = 20
+ identifier = "showcase"
+ url = "/zh/showcase/"
+
+# Anything with a weight > 100 gets an external icon
+[[languages.zh.menu.global]]
+ name = "社区"
+ weight = 150
+ icon = true
+ identifier = "community"
+ post = "external"
+ url = "https://discourse.gohugo.io/"
+
+[[languages.zh.menu.global]]
+ name = "GitHub"
+ weight = 200
+ identifier = "github"
+ post = "external"
+ url = "https://github.com/gohugoio/hugo"
--- /dev/null
- * http://hugotest.bep.is/
+---
+title: Hugo 0.32 HOWTO
+description: About page bundles, image processing and more.
+date: 2017-12-28
+keywords: [ssg,static,performance,security]
+menu:
+ docs:
+ parent: "about"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: []
+toc: true
+images:
+- images/blog/sunset.jpg
+---
+
+
+{{% note %}}
+This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast.
+{{% /note %}}
+
+
+Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features:
+
++* https://temp.bep.is/hugotest/
+* https://github.com/bep/hugotest (source)
+
+## Page Resources
+
+### Organize Your Content
+
+{{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}}
+
+The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources.
+
+{{% note %}}
+You can use any file 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](/templates/output-formats/#media-types).
+{{% /note %}}
+
+The 3 page bundles marked in red explained from top to bottom:
+
+1. The home page with one image resource (`1-logo.png`)
+2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section.
+3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article.
+
+The content files below `blog/posts` are just regular standalone pages.
+
+{{% note %}}
+Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`.
+{{% /note %}}
+
+#### Sort Order
+
+* Pages are sorted according to standard Hugo page sorting rules.
+* Images and other resources are sorted in lexicographical order.
+
+### Handle Page Resources in Templates
+
+
+#### List all Resources
+
+```go-html-template
+{{ range .Resources }}
+<li><a href="{{ .RelPermalink }}">{{ .ResourceType | title }}</a></li>
+{{ end }}
+```
+
+For an absolute URL, use `.Permalink`.
+
+**Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`.
+
+#### List All Resources by Type
+
+```go-html-template
+{{ with .Resources.ByType "image" }}
+{{ end }}
+
+```
+
+Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc.
+
+#### Get a Specific Resource
+
+```go-html-template
+{{ $logo := .Resources.GetByPrefix "logo" }}
+{{ with $logo }}
+{{ end }}
+```
+
+#### Include Page Resource Content
+
+```go-html-template
+{{ with .Resources.ByType "page" }}
+{{ range . }}
+<h3>{{ .Title }}</h3>
+{{ .Content }}
+{{ end }}
+{{ end }}
+
+```
+
+
+## Image Processing
+
+The `image` resource implements the methods `Resize`, `Fit` and `Fill`:
+
+Resize
+: Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width.
+
+Fit
+: Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high.
+
+Fill
+: Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100
+
+
+{{% note %}}
+Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future.
+{{% /note %}}
+
+
+### Image Processing Examples
+
+_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
+
+
+{{< imgproc sunset Resize "300x" />}}
+
+{{< imgproc sunset Fill "90x120 left" />}}
+
+{{< imgproc sunset Fill "90x120 right" />}}
+
+{{< imgproc sunset Fit "90x90" />}}
+
+{{< imgproc sunset Resize "300x q10" />}}
+
+
+This is the shortcode used in the examples above:
+
+
+{{< code file="layouts/shortcodes/imgproc.html" >}}
+{{< readfile file="layouts/shortcodes/imgproc.html" >}}
+{{< /code >}}
+
+And it is used like this:
+
+```go-html-template
+{{</* imgproc sunset Resize "300x" */>}}
+```
+
+### Image Processing Options
+
+In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options:
+
+Anchor
+: Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}`
+
+JPEG Quality
+: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}`
+
+Rotate
+: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images.
+
+Resample Filter
+: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test.
+
+
+
+### Performance
+
+Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused.
+
+If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project.
+
+To clean up, run:
+
+```bash
+hugo --gc
+```
+
+
+{{% note %}}
+**GC** is short for **Garbage Collection**.
+{{% /note %}}
+
+
+## Configuration
+
+### Default Image Processing Config
+
+You can configure an `imaging` section in `config.toml` with default image processing options:
+
+```toml
+[imaging]
+# Default resample filter used for resizing. Default is Box,
+# a simple and fast averaging filter appropriate for downscaling.
+# See https://github.com/disintegration/imaging
+resampleFilter = "box"
+
+# Defatult JPEG quality setting. Default is 75.
+quality = 68
+```
+
+
+
+
+
--- /dev/null
- [Amazon S3]: http://aws.amazon.com/s3/
+---
+title: What is Hugo
+linktitle: What is Hugo
+description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+layout: single
+menu:
+ docs:
+ parent: "about"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/overview/introduction/,/about/why-i-built-hugo/]
+toc: true
+---
+
+Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.
+
+Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [GitLab Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.
+
+We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.
+
+## How Fast is Hugo?
+
+{{< youtube "CdiDYZ51a2o" >}}
+
+## What Does Hugo Do?
+
+In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.
+
+## Who Should Use Hugo?
+
+Hugo is for people that prefer writing in a text editor over a browser.
+
+Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.
+
+Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.
+
+
+
+[@spf13]: https://twitter.com/@spf13
+[Aerobatic]: https://www.aerobatic.com/
- [CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
- [contributing to it]: https://github.com/gohugoio/hugo
- [DreamHost]: http://www.dreamhost.com/
++[Amazon S3]: https://aws.amazon.com/s3/
+[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/
- [Google Cloud Storage]: http://cloud.google.com/storage/
++[CloudFront]: https://aws.amazon.com/cloudfront/ "Amazon CloudFront"
++[DreamHost]: https://www.dreamhost.com/
+[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting"
+[GitHub Pages]: https://pages.github.com/
+[GitLab Pages]: https://about.gitlab.com/features/pages/
+[Go language]: https://golang.org/
+[GoDaddy]: https://www.godaddy.com/ "Godaddy.com Hosting"
- [Jekyll]: http://jekyllrb.com/
++[Google Cloud Storage]: https://cloud.google.com/storage/
+[Heroku]: https://www.heroku.com/
- [Middleman]: https://middlemanapp.com/
- [Nanoc]: http://nanoc.ws/
+[Jekyll]: https://jekyllrb.com/
+[Middleman]: https://middlemanapp.com/
- [rackspace]: https://www.rackspace.com/cloud/files
- [static site generator]: /about/benefits/
+[Nanoc]: https://nanoc.ws/
+[Netlify]: https://netlify.com
- [static site generator]: /about/benefits/
+[Rackspace]: https://www.rackspace.com/cloud/files
+[Surge]: https://surge.sh
++[contributing to it]: https://github.com/gohugoio/hugo
++[rackspace]: https://www.rackspace.com/cloud/files
++[static site generator]: /about/benefits/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Authors
+linktitle: Authors
+description:
+date: 2016-08-22
+publishdate: 2017-03-12
+lastmod: 2017-03-12
+keywords: [authors]
+categories: ["content management"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 55
+weight: 55 #rem
+draft: true
+aliases: [/content/archetypes/]
+toc: true
+comments: Before this page is published, need to also update both site- and page-level variables documentation.
+---
+
+
+
+Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model.
+
+## Author Profiles
+
+You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format.
+
+### Example: Author Profile
+
+Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML:
+
+{{< code file="data/_authors/alice.toml" >}}
+givenName = "Alice" # or firstName as alias
+familyName = "Allison" # or lastName as alias
+displayName = "Alice Allison"
+thumbnail = "static/authors/alice-thumb.jpg"
+image = "static/authors/alice-full.jpg"
+shortBio = "My name is Alice and I'm a blogger."
+bio = "My name is Alice and I'm a blogger... some other stuff"
+email = "alice.allison@email.com"
+weight = 10
+
+[social]
+ facebook = "alice.allison"
+ twitter = "alice"
+ googleplus = "aliceallison1"
+ website = "www.example.com"
+
+[params]
+ random = "whatever you want"
+{{< /code >}}
+
+All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
+
+You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`.
+
+`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable.
+
+The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched.
+
+The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you.
+
+## Associate Content Through Identifiers
+
+Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively.
+
+```
+---
+title: Why Hugo is so Awesome
+date: 2016-08-22T14:27:502:00
+authors: ["alice"]
+---
+
+Nothing to read here. Move along...
+```
+
+```
++++
+title = Why Hugo is so Awesome
+date = "2016-08-22T14:27:502:00"
+authors: ["alice"]
++++
+
+Nothing to read here. Move along...
+```
+
+Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well.
+
+## Work with Templates
+
+After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter.
+
+The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward:
+
+```
+{{ range .Authors }}
+ {{ .DisplayName }}
+{{ end }}
+=> Alice Allison
+```
+
+Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter.
+
+{{% note %}}
+You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/).
+{{% /note %}}
+
+### Link Social Network Accounts
+
+As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corrersponding identifiers are supported: `github`, `facebook`, `twitter`, `googleplus`, `pinterest`, `instagram`, `youtube` and `linkedin`.
+
+This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `googleplus`). Custom variables like `website` remain as they are.
+
+Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks:
+
+{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
+{{ with .Author }}
+ <h3>{{ .DisplayName }}</h3>
+ <img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
+ <p>{{ .ShortBio }}</p>
+ <ul>
+ {{ range $network, $username := .Social }}
+ <li><a href="{{ $.Author.Social.URL $network }}">{{ $network }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+{{< /code >}}
+
+## Who Published What?
+
+That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right?
+
+In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively:
+
+```
+taxonomies:
+ author: authors
+```
+
+```
+[taxonomies]
+ author = "authors"
+```
+
+
+### List All Authors
+
+In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy.
+
+{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
+<ul>
+{{ range $author, $v := .Data.Terms }}
+ {{ $profile := $.Authors.Get $author }}
+ <li>
+ <a href="{{ printf "%s/%s/" $.Data.Plural $author | absURL }}">
+ {{ $profile.DisplayName }} - {{ $profile.ShortBio }}
+ </a>
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
+
+### List Each Author's Publications
+
+Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/<IDENTIFIER>`. Replace `<IDENTIFIER>` with a valid author identifier like `alice`.
+
+The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
+
+{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
++{{ range .Pages }}
+ <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
+ <span>written by {{ .Author.DisplayName }}</span>
+ {{ .Summary }}
+{{ end }}
+{{< /code >}}
+
+The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
+
+With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages.
+
+[pagevars]: /variables/page/
+[pagination]: /templates/pagination/
--- /dev/null
- 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
+---
+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 %}}
+
-
++See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry.
+
+## 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 configuration file:
+
+{{< code-toggle 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-toggle >}}
+
+{{% 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/
++[me-props]: /variables/menus/
--- /dev/null
- The full set of methods available on the page lists can bee seen in this Go interface:
+---
+title: Related Content
+description: List related content in "See Also" sections.
+date: 2017-09-05
+categories: [content management]
+keywords: [content]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 40
+weight: 30
+draft: false
+aliases: [/content/related/,/related/]
+toc: true
+---
+
+{{% note %}}
+We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
+{{% /note %}}
+
+## List Related Content
+
+To list up to 5 related pages is as simple as including something similar to this partial in your single page template:
+
+{{< code file="layouts/partials/related.html" >}}
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+<h3>See Also</h3>
+<ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+
+{{% note %}}
+Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
+{{% /note %}}
+
++The full set of methods available on the page lists can be seen in this Go interface:
+
+```go
+// A PageGenealogist finds related pages in a page collection. This interface is implemented
+// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc.
+type PageGenealogist interface {
+
+ // Template example:
+ // {{ $related := .RegularPages.Related . }}
+ Related(doc related.Document) (Pages, error)
+
+ // Template example:
+ // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
+ RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error)
+
+ // Template example:
+ // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
+ RelatedTo(args ...types.KeyValues) (Pages, error)
+}
+```
+## Configure Related Content
+Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
+
+{{% note %}}
+If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
+{{% /note %}}
+
+Below is a sample `config.toml` section:
+
+```
+[related]
+
+# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100.
+threshold = 80
+
+# To get stable "See also" sections we, by default, exclude newer related pages.
+includeNewer = false
+
+# Will lower case keywords in both queries and in the indexes.
+toLower = false
+
+[[related.indices]]
+name = "keywords"
+weight = 150
+[[related.indices]]
+name = "author"
+toLower = true
+weight = 30
+[[related.indices]]
+name = "tags"
+weight = 100
+[[related.indices]]
+name = "date"
+weight = 10
+pattern = "2006"
+```
+### Top Level Config Options
+
+threshold
+: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
+
+includeNewer
+: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
+
+toLower
+: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
+
+### Config Options per Index
+
+name
+: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
+
+weight
+: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
+
+pattern
+: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
+
+toLower
+: See above.
+
+## Performance Considerations
+
+**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
+
+This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
+
+{{< tweet 898398437527363585 >}}
+
+Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
+
+He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
+
+* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
+* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
+
+
+
+
+
+
+
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Shortcodes
+linktitle:
+description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+menu:
+ docs:
+ parent: "content-management"
+ weight: 35
+weight: 35 #rem
+categories: [content management]
+keywords: [markdown,content,shortcodes]
+draft: false
+aliases: [/extras/shortcodes/]
+toc: true
+---
+
+## What a Shortcode is
+
+Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframes>`) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+
+Hugo created **shortcodes** to circumvent these limitations.
+
+A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+
+In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+
+## Use Shortcodes
+
+{{< youtube 2xkNJL4gJ9E >}}
+
+In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+
+The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
+
+Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+
+Here are two examples of paired shortcodes:
+
+```
+{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```
+
+```
+{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+```
+
+The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+
+### Shortcodes with Markdown
+
+The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
+
+```
+{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
+```
+
+### Shortcodes Without Markdown
+
+The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
+
+```
+{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
+```
+
+### Nested Shortcodes
+
+You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+
+## Use Hugo's Built-in Shortcodes
+
+Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
+
+### `figure`
+
+`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
+
+The `figure` shortcode can use the following named parameters:
+
+src
+: URL of the image to be displayed.
+
+link
+: If the image needs to be hyperlinked, URL of the destination.
+
+target
+: Optional `target` attribute for the URL if `link` parameter is set.
+
+rel
+: Optional `rel` attribute for the URL if `link` parameter is set.
+
+alt
+: Alternate text for the image if the image cannot be displayed.
+
+title
+: Image title.
+
+caption
+: Image caption.
+
+class
+: `class` attribute of the HTML `figure` tag.
+
+height
+: `height` attribute of the image.
+
+width
+: `width` attribute of the image.
+
+attr
+: Image attribution text.
+
+attrlink
+: If the attribution text needs to be hyperlinked, URL of the destination.
+
+#### Example `figure` Input
+
+{{< code file="figure-input-example.md" >}}
+{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+#### Example `figure` Output
+
+{{< output file="figure-output-example.html" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /output >}}
+
+### `gist`
+
+Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
+
+```
+https://gist.github.com/spf13/7896402
+```
+
+We can embed the gist in our content via username and gist ID pulled from the URL:
+
+```
+{{</* gist spf13 7896402 */>}}
+```
+
+#### Example `gist` Input
+
+If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
+
+{{< code file="gist-input.md" >}}
+{{</* gist spf13 7896402 "img.html" */>}}
+{{< /code >}}
+
+#### Example `gist` Output
+
+{{< output file="gist-output.html" >}}
+{{< gist spf13 7896402 >}}
+{{< /output >}}
+
+#### Example `gist` Display
+
+To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< gist spf13 7896402 >}}
+
+### `highlight`
+
+This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+
+#### Example `highlight` Input
+
+{{< code file="content/tutorials/learn-html.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+#### Example `highlight` Output
+
+The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+
+{{< output file="tutorials/learn-html/index.html" >}}
+<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
+ <span style="color: #f92672"><div></span>
+ <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ <span style="color: #f92672"></div></span>
+<span style="color: #f92672"></section></span>
+{{< /output >}}
+
+{{% note "More on Syntax Highlighting" %}}
+To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
+{{% /note %}}
+
+### `instagram`
+
+If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
+
+```
+https://www.instagram.com/p/BWNjjyYFxVx/
+```
+
+#### Example `instagram` Input
+
+{{< code file="instagram-input.md" >}}
+{{</* instagram BWNjjyYFxVx */>}}
+{{< /code >}}
+
+You also have the option to hide the caption:
+
+{{< code file="instagram-input-hide-caption.md" >}}
+{{</* instagram BWNjjyYFxVx hidecaption */>}}
+{{< /code >}}
+
+#### Example `instagram` Output
+
+By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="instagram-hide-caption-output.html" >}}
+{{< instagram BWNjjyYFxVx hidecaption >}}
+{{< /output >}}
+
+#### Example `instagram` Display
+
+Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< instagram BWNjjyYFxVx hidecaption >}}
+
+
+### `ref` and `relref`
+
+These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
+
+`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+
+{{% note "More on Cross References" %}}
+Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+{{% /note %}}
+
+`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+
+#### Example `ref` and `relref` Input
+
+```
+[Neat]({{</* ref "blog/neat.md" */>}})
+[Who]({{</* relref "about.md#who" */>}})
+```
+
+#### Example `ref` and `relref` Output
+
+Assuming that standard Hugo pretty URLs are turned on.
+
+```
+<a href="/blog/neat">Neat</a>
+<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
+```
+
+### `tweet`
+
+You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
+
+```
+https://twitter.com/spf13/status/877500564405444608
+```
+
+#### Example `tweet` Input
+
+Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
+
+{{< code file="example-tweet-input.md" >}}
+{{</* tweet 877500564405444608 */>}}
+{{< /code >}}
+
+#### Example `tweet` Output
+
+Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-tweet-output.html" >}}
+{{< tweet 877500564405444608 >}}
+{{< /output >}}
+
+#### Example `tweet` Display
+
+Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< tweet 877500564405444608 >}}
+
+### `vimeo`
+
+Adding a video from [Vimeo][] is equivalent to the YouTube shortcode above.
+
+```
+https://vimeo.com/channels/staffpicks/146022717
+```
+
+#### Example `vimeo` Input
+
+Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
+
+{{< code file="example-vimeo-input.md" >}}
+{{</* vimeo 146022717 */>}}
+{{< /code >}}
+
+#### Example `vimeo` Output
+
+Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-vimeo-output.html" >}}
+{{< vimeo 146022717 >}}
+{{< /output >}}
+
+{{% tip %}}
+If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well.
+
+```
+{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" */>}}
+```
+{{% /tip %}}
+
+#### Example `vimeo` Display
+
+Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< vimeo 146022717 >}}
+
+### `youtube`
+
+The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
+
+```
+https://www.youtube.com/watch?v=w7Ft2ymGmfc
+```
+
+
+#### Example `youtube` Input
+
+Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
+
+{{< code file="example-youtube-input.md" >}}
+{{</* youtube w7Ft2ymGmfc */>}}
+{{< /code >}}
+
+Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named an unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
+
+
+{{< code file="example-youtube-input-with-autoplay.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
+{{< /code >}}
+
+#### Example `youtube` Output
+
+Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
+
+{{< code file="example-youtube-output.html" >}}
+{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
+{{< /code >}}
+
+#### Example `youtube` Display
+
+Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
+
+{{< youtube w7Ft2ymGmfc >}}
+
+## Privacy Config
+
+To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
+
+## Create Custom Shortcodes
+
+To learn more about creating custom shortcodes, see the [shortcode template documentation][].
+
+[`figure` shortcode]: #figure
+[contentmanagementsection]: /content-management/formats/
+[examplegist]: https://gist.github.com/spf13/7896402
+[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
+[Hugo and the GDPR]: /about/hugo-and-gdpr/
+[Instagram]: https://www.instagram.com/
+[pagevariables]: /variables/page/
+[partials]: /templates/partials/
+[Pygments]: http://pygments.org/
+[quickstart]: /getting-started/quick-start/
+[sctemps]: /templates/shortcode-templates/
+[scvars]: /variables/shortcodes/
+[shortcode template documentation]: /templates/shortcode-templates/
+[templatessection]: /templates/
+[Vimeo]: https://vimeo.com/
+[YouTube Videos]: https://www.youtube.com/
--- /dev/null
- description: "The `static` folder is where you place all your **static files**."
+---
+title: Static Files
- The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc.
++description: "Files that get served **statically** (as-is, no modification) on the site root."
+date: 2017-11-18
+categories: [content management]
+keywords: [source, directories]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 130
+weight: 130 #rem
+aliases: [/static-files]
+toc: true
+---
+
- You can set the name of the static folder to use in your configuration file. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
++By default, the `static/` directory in the site project is used for
++all **static files** (e.g. stylesheets, JavaScript, images).
+
- Example:
++Hugo can be configured to look into a different directory, or even
++**multiple directories** for such static files by configuring the
++`staticDir` parameter in the [site config][]. All the files in all the
++static directories will form a union filesystem.
+
- [languages]
- [languages.no]
- staticDir = ["staticDir_override", "static_no"]
- baseURL = "https://example.no"
- languageName = "Norsk"
- weight = 1
- title = "På norsk"
++This union filesystem will be served from your site root. So a file
++`<SITE PROJECT>/static/me.png` will be accessible as
++`<MY_BASEURL>/me.png`.
++
++Here's an example of setting `staticDir` and `staticDir2` for a
++multi-language site:
+
+{{< code-toggle copy="false" file="config" >}}
+staticDir = ["static1", "static2"]
- * The English site will get its static files as a union of "static1", "static2" and "static_en". On file duplicates, the right-most version will win.
- * The Norwegian site will get its static files as a union of "staticDir_override" and "static_no".
+
++[languages]
+[languages.en]
+staticDir2 = "static_en"
+baseURL = "https://example.com"
+languageName = "English"
+weight = 2
+title = "In English"
++[languages.no]
++staticDir = ["staticDir_override", "static_no"]
++baseURL = "https://example.no"
++languageName = "Norsk"
++weight = 1
++title = "På norsk"
+{{</ code-toggle >}}
+
+In the above, with no theme used:
+
- **Note:** The `2` `static2` (can be a number between 0 and 10) is added to tell Hugo that you want to **add** this directory to the global set of static directories. Using `staticDir` on the language level would replace the global value.
++- The English site will get its static files as a union of "static1",
++ "static2" and "static_en". On file duplicates, the right-most
++ version will win.
++- The Norwegian site will get its static files as a union of
++ "staticDir_override" and "static_no".
++
++Note 1
++: The **2** (can be a number between 0 and 10) in `staticDir2` is
++ added to tell Hugo that you want to **add** this directory to the
++ global set of static directories defined using `staticDir`. Using
++ `staticDir` on the language level would replace the global value (as
++ can be seen in the Norwegian site case).
+
- **Note:** The example above is a [multihost setup](/content-management/multilingual/#configure-multilingual-multihost). In a regular setup, all the static directories will be available to all sites.
++Note 2
++: The example above is a [multihost setup][]. In a regular setup, all
++ the static directories will be available to all sites.
+
+
++[site config]: /getting-started/configuration/#all-configuration-settings
++[multihost setup]: /content-management/multilingual/#configure-multilingual-multihost
--- /dev/null
- description: Hugo generates summaries of your content.
+---
+title: Content Summaries
+linktitle: Summaries
- {{ range first 10 .Data.Pages }}
++description: Hugo generates summaries of your content.
+date: 2017-01-10
+publishdate: 2017-01-10
+lastmod: 2017-01-10
+categories: [content management]
+keywords: [summaries,abstracts,read more]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 90
+weight: 90 #rem
+draft: false
+aliases: [/content/summaries/,/content-management/content-summaries/]
+toc: true
+---
+
+With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views.
+
+## Summary Splitting Options
+
+* Hugo-defined Summary Split
+* User-defined Summary Split
+
+It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
+
+### Hugo-defined: Automatic Summary Splitting
+
+By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. Taking the Hugo-defined approach to summaries may save time, but it has pros and cons:
+
+* **Pros:** Automatic, no additional work on your part.
+* **Cons:** All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all put into one paragraph.
+
+{{% note %}}
+The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive white space characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in you [site configuration](/getting-started/configuration/).
+{{% /note %}}
+
+### User-defined: Manual Summary Splitting
+
+Alternatively, you may add the <code><!--more--></code> summary divider where you want to split the article. For [org content][org], use `# more` where you want to split the article. Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact.
+
+{{% note "Summary Divider"%}}
+The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature.
+{{% /note %}}
+
+* Pros: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved.
+* Cons: Extra work for content authors, since they need to remember to type <code><!--more--></code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/).
+
+{{% warning "Be Precise with the Summary Divider" %}}
+Be careful to enter <code><!--more--></code> exactly; i.e., all lowercase and with no whitespace.
+{{% /warning %}}
+
+## Example: First 10 Articles with Summaries
+
+You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][].
+
+{{< code file="page-list-with-summaries.html" >}}
- [section template]: /templates/section-templates/
++{{ range first 10 .Pages }}
+ <article>
+ <!-- this <div> includes the title summary -->
+ <div>
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+ {{ .Summary }}
+ </div>
+ {{ if .Truncated }}
+ <!-- This <div> includes a read more link, but only if the summary is truncated... -->
+ <div>
+ <a href="{{ .RelPermalink }}">Read More…</a>
+ </div>
+ {{ end }}
+ </article>
+{{ end }}
+{{< /code >}}
+
+Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
+
+[org]: /content-management/formats/
+[pagevariables]: /variables/page/
++[section template]: /templates/section-templates/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Syntax Highlighting
+description: Hugo comes with really fast syntax highlighting from Chroma.
+date: 2017-02-01
+publishdate: 2017-02-01
+keywords: [highlighting,pygments,chroma,code blocks,syntax]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 300
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
+toc: true
+---
+
+From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.
+
+If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
+
+The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)).
+
+* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers.
+* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
+* `linenostart=199` starts the line number count from 199.
+
+With that, this:
+
+```
+{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
+// ... code
+{{</* / highlight */>}}
+```
+
+Gives this:
+
+{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
+// GetTitleFunc returns a func that can be used to transform a string to
+// title case.
+//
+// The supported styles are
+//
+// - "Go" (strings.Title)
+// - "AP" (see https://www.apstylebook.com/)
+// - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)
+//
+// If an unknown or empty style is provided, AP style is what you get.
+func GetTitleFunc(style string) func(s string) string {
+ switch strings.ToLower(style) {
+ case "go":
+ return strings.Title
+ case "chicago":
+ tc := transform.NewTitleConverter(transform.ChicagoStyle)
+ return tc.Title
+ default:
+ tc := transform.NewTitleConverter(transform.APStyle)
+ return tc.Title
+ }
+}
+{{< / highlight >}}
+
+
+## Configure Syntax Highlighter
+To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
+
+pygmentsOptions
+: A comma separated list of options. See below for a full list.
+
+pygmentsCodefences
+: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
+
+pygmentsStyle
+: The style of code highlighting. Note that this option is not
+ relevant when `pygmentsUseClasses` is set.
+
+ Syntax highlighting galleries:
+ **Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html),
+ [long snippets](https://xyproto.github.io/splash/docs/longer/all.html)),
+ [Pygments](https://help.farbox.com/pygments.html)
+
+pygmentsUseClasses
+: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
+
+pygmentsCodefencesGuessSyntax
+: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
+
+pygmentsUseClassic
+: Set to true to use Pygments instead of the much faster Chroma.
+
+### Options
+
+`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
+
+noclasses
+: Use inline style.
+
+linenos
+: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
+
+linenostart
+: Start the line numbers from this value (default is 1).
+
+
+hl_lines
+: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
+
+
+The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details.
+
+
+## Generate Syntax Highlighter CSS
+
+If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
+
+You can generate one with Hugo:
+
+```bash
+hugo gen chromastyles --style=monokai > syntax.css
+```
+
+Run `hugo gen chromastyles -h` for more options. See https://help.farbox.com/pygments.html for a gallery of available styles.
+
+
+## Highlight Shortcode
+
+Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
+
+### Example `highlight` Shortcode
+
+{{< code file="example-highlight-shortcode-input.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+
+
+## Highlight Template Func
+
+See [Highlight](/functions/highlight/).
+
+## Highlight in Code Fences
+
+It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
+
+````
+```go-html-template
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+```
+````
+
+## List of Chroma Highlighting Languages
+
+The full list of Chroma lexers and their aliases (which is the identifier used in the `hightlight` template func or when doing highlighting in code fences):
+
+{{< chroma-lexers >}}
+
+## Highlight with Pygments Classic
+
+If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path.
+
+{{% note "Disclaimers on Pygments" %}}
+* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
+* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
+* The languages available for highlighting depend on your Pygments installation.
+{{% /note %}}
+
+If you have never worked with Pygments before, here is a brief primer:
+
++ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
++ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
+
+On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
+
+
+
+[Prism]: http://prismjs.com
+[prismdownload]: http://prismjs.com/download.html
+[Highlight.js]: http://highlightjs.org/
+[Rainbow]: http://craig.is/making/rainbows
+[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
+[Google Prettify]: https://github.com/google/code-prettify
+[Yandex]: http://yandex.ru/
--- /dev/null
- {{ range first 1 .Data.Pages.ByPublishDate.Reverse }}
+---
+title: after
+description: "`after` slices an array to only the items after the <em>N</em>th item."
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [iteration]
+signature: ["after INDEX COLLECTION"]
+workson: []
+hugoversion:
+relatedfuncs: [last,first,seq]
+deprecated: false
+aliases: []
+---
+
+The following shows `after` being used in conjunction with the [`slice` function][slice]:
+
+```
+{{ $data := slice "one" "two" "three" "four" }}
+{{ range after 2 $data }}
+ {{ . }}
+{{ end }}
+→ ["three", "four"]
+```
+
+## Example of `after` with `first`: 2nd–4th Most Recent Articles
+
+You can use `after` in combination with the [`first` function][] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page][] to show only two rows:
+
+1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
+2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+
+{{< code file="layouts/section/articles.html" download="articles.html" >}}
+{{ define "main" }}
+<section class="row featured-article">
+ <h2>Featured Article</h2>
- {{ range first 3 (after 1 .Data.Pages.ByPublishDate.Reverse) }}
++ {{ range first 1 .Pages.ByPublishDate.Reverse }}
+ <header>
+ <h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
+ </header>
+ <p>{{.Description}}</p>
+ {{ end }}
+</section>
+<div class="row recent-articles">
+ <h2>Recent Articles</h2>
++ {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
+ <section class="recent-article">
+ <header>
+ <h3><a href="{{.Permalink}}">{{.Title}}</a></h3>
+ </header>
+ <p>{{.Description}}</p>
+ </section>
+ {{ end }}
+</div>
+{{ end }}
+{{< /code >}}
+
+[`first` function]: /functions/first/
+[list/section page]: /templates/section-templates/
+[lists]: /lists/
+[slice]: /functions/slice/
--- /dev/null
- {{ range first 10 .Data.Pages }}
+---
+title: first
+linktitle: first
+description: "Slices an array to only the first _N_ elements."
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [iteration]
+signature: ["first LIMIT COLLECTION"]
+workson: [lists,taxonomies,terms,groups]
+hugoversion:
+relatedfuncs: [after,last]
+deprecated: false
+aliases: []
+---
+
+
+```
-
++{{ range first 10 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
--- /dev/null
- signature: ["HasMenuCurrent"]
+---
+title: .HasMenuCurrent
+description:
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [menus]
- relatedfuncs: []
++signature: ["PAGE.HasMenuCurrent MENU MENUENTRY"]
+workson: [menus]
+hugoversion:
- draft: true
++relatedfuncs: ["IsMenuCurrent"]
+deprecated: false
+toc: false
- Used in [menu templates](/templates/menu-templates/).
++draft: false
+aliases: []
+---
+
++`.HasMenuCurrent` is a method in `Page` object returning a _boolean_ value. It
++returns `true` if the PAGE is the same object as the `.Page` in one of the
++**children menu entries** under MENUENTRY in a given MENU.
++
++You can find its example use in [menu templates](/templates/menu-templates/).
--- /dev/null
- signature: ["IsMenuCurrent"]
+---
+title: .IsMenuCurrent
+description:
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [menus]
- relatedfuncs: []
++signature: ["PAGE.IsMenuCurrent MENU MENUENTRY"]
+workson: [menus]
+hugoversion:
- draft: true
++relatedfuncs: ["HasMenuCurrent"]
+deprecated: false
- Used in [menu templates](/templates/menu-templates/).
++draft: false
+aliases: []
+needsexample: true
+---
+
++`.IsMenuCurrent` is a method in `Page` object returning a _boolean_ value. It
++returns `true` if the PAGE is the same object as the `.Page` in MENUENTRY in a
++given MENU.
++
++You can find its example use in [menu templates](/templates/menu-templates/).
--- /dev/null
- {{ range last 10 .Data.Pages }}
+---
+title: last
+linktitle: last
+description: "slices an array to only the last <em>N</em>th elements."
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: []
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+toc:
+signature: ["last INDEX COLLECTION"]
+workson: [lists, taxonomies, terms, groups]
+hugoversion:
+relatedfuncs: []
+deprecated: false
+draft: false
+aliases: []
+---
+
+
+```
-
++{{ range last 10 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: render
+# linktitle: Render
+description: Takes a view to apply when rendering content.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [views]
+signature: ["render LAYOUT"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
+The view is an alternative layout and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
+
+This function is only available when applied to a single piece of content within a [list context][].
+
+This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
+
+```
++{{ range .Pages }}
+ {{ .Render "summary"}}
+{{ end }}
+```
+
+[list context]: /templates/lists/
--- /dev/null
- ## Methods
+---
+title: .Scratch
+description: Acts as a "scratchpad" to allow for writable page- or shortcode-scoped variables.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [iteration]
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+toc:
+signature: []
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+draft: false
+aliases: [/extras/scratch/,/doc/scratch/]
+---
+
+In most cases you can do okay without `Scratch`, but due to scoping issues, there are many use cases that aren't solvable in Go Templates without `Scratch`'s help.
+
+`.Scratch` is available as methods on `Page` and `Shortcode`. Since Hugo 0.43 you can also create a locally scoped `Scratch` using the template func `newScratch`.
+
+
+{{% note %}}
+See [this Go issue](https://github.com/golang/go/issues/10608) for the main motivation behind Scratch.
+{{% /note %}}
+
+{{% note %}}
+For a detailed analysis of `.Scratch` and in context use cases, see this [post](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/).
+{{% /note %}}
+
- `Scratch` is added to both `Page` and `Shortcode` -- with following methods:
++## Get a Scratch
+
++From Hugo `0.43` you can also create a locally scoped `Scratch` by calling `newScratch`:
++
++```go-html-template
++$scratch := newScratch
++$scratch.Set "greeting" "Hello"
++```
++
++A `Scratch` is also added to both `Page` and `Shortcode`. `Sratch` have the following methods:
+
+#### .Set
++
+Set the given value to a given key
+
+```go-html-template
+{{ .Scratch.Set "greeting" "Hello" }}
+```
+#### .Get
+Get the value of a given key
+
+```go-html-template
+{{ .Scratch.Set "greeting" "Hello" }}
+----
+{{ .Scratch.Get "greeting" }} > Hello
+```
+
+#### .Add
+Will add a given value to existing value of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ .Scratch.Add "greetings" "Hello" }}
+{{ .Scratch.Add "greetings" "Welcome" }}
+----
+{{ .Scratch.Get "greetings" }} > HelloWelcome
+```
+
+```go-html-template
+{{ .Scratch.Add "total" 3 }}
+{{ .Scratch.Add "total" 7 }}
+----
+{{ .Scratch.Get "total" }} > 10
+```
+
+
+```go-html-template
+{{ .Scratch.Add "greetings" (slice "Hello") }}
+{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }}
+----
+{{ .Scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"}
+```
+
+#### .SetInMap
+Takes a `key`, `mapKey` and `value` and add a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
+{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
+----
+{{ .Scratch.Get "greetings" }} > map[french:Bonjour english:Hello]
+```
+
+#### .GetSortedMapValues
+Returns array of values from `key` sorted by `mapKey`
+
+```go-html-template
+{{ .Scratch.SetInMap "greetings" "english" "Hello" }}
+{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }}
+----
+{{ .Scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour]
+```
+#### .Delete
+Removes the given key
+
+```go-html-template
+{{ .Scratch.Delete "greetings" }}
+```
+
+## Scope
+The scope of the backing data is global for the given `Page` or `Shortcode`, and spans partial and shortcode includes.
+
+Note that `.Scratch` from a shortcode will return the shortcode's `Scratch`, which in most cases is what you want. If you want to store it in the page scoped Scratch, then use `.Page.Scratch`.
+
+
+
+
+[pagevars]: /variables/page/
--- /dev/null
- {{ range where .Data.Pages "Section" "post" }}
+---
+title: where
+# linktitle: where
+description: Filters an array to only the elements containing a matching value for a given field.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [filtering]
+signature: ["where COLLECTION KEY [OPERATOR] MATCH"]
+workson: [lists,taxonomies,terms,groups]
+hugoversion:
+relatedfuncs: [intersect,first,after,last]
+deprecated: false
+toc: true
+needsexample: true
+---
+
+`where` filters an array to only the elements containing a matching value for a given field.
+
+```go-html-template
- {{ range where .Data.Pages "Section" "!=" "post" }}
++{{ range where .Pages "Section" "post" }}
+ {{ .Content }}
+{{ end }}
+```
+
+It can be used by dot-chaining the second argument to refer to a nested element of a value.
+
+```
++++
+series: golang
++++
+```
+
+```go-html-template
+{{ range where .Site.Pages "Params.series" "golang" }}
+ {{ .Content }}
+{{ end }}
+```
+
+It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`.
+
+```go-html-template
- {{ range first 5 (where .Data.Pages "Section" "post") }}
++{{ range where .Pages "Section" "!=" "post" }}
+ {{ .Content }}
+{{ end }}
+```
+
+The following logical operators are available with `where`:
+
+`=`, `==`, `eq`
+: `true` if a given field value equals a matching value
+
+`!=`, `<>`, `ne`
+: `true` if a given field value doesn't equal a matching value
+
+`>=`, `ge`
+: `true` if a given field value is greater than or equal to a matching value
+
+`>`, `gt`
+: `true` if a given field value is greater than a matching value
+
+`<=`, `le`
+: `true` if a given field value is lesser than or equal to a matching value
+
+`<`, `lt`
+: `true` if a given field value is lesser than a matching value
+
+`in`
+: `true` if a given field value is included in a matching value; a matching value must be an array or a slice
+
+`not in`
+: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice
+
+`intersect`
+: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect].
+
+## Use `where` with `intersect`
+
+```go-html-template
+{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }}
+ {{ if ne .Permalink $.Permalink }}
+ {{ .Render "summary" }}
+ {{ end }}
+{{ end }}
+```
+
+You can also put the returned value of the `where` clauses into a variable:
+
+{{< code file="where-intersect-variables.html" >}}
+{{ $v1 := where .Site.Pages "Params.a" "v1" }}
+{{ $v2 := where .Site.Pages "Params.b" "v2" }}
+{{ $filtered := $v1 | intersect $v2 }}
+{{ range $filtered }}
+{{ end }}
+{{< /code >}}
+
+## Use `where` with `first`
+
+The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
+
+{{< code file="where-with-first.html" >}}
- {{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
++{{ range first 5 (where .Pages "Section" "post") }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+## Nest `where` Clauses
+
+You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured:
+
+```go-html-template
- {{ range where .Data.Pages ".Params.specialpost" "!=" nil }}
++{{ range where (where .Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
+```
+
+## Unset Fields
+
+Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`.
+
+This can be useful to filter a small amount of pages from a large pool. Instead of set field on all pages, you can set field on required pages only.
+
+Only the following operators are available for `nil`
+
+* `=`, `==`, `eq`: True if the given field is not set.
+* `!=`, `<>`, `ne`: True if the given field is set.
+
+```go-html-template
++{{ range where .Pages ".Params.specialpost" "!=" nil }}
+ {{ .Content }}
+{{ end }}
+```
+
+## Portable `where` filters
+
+This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list.
+
+This will, by default, list pages from the _section with the most pages_.
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
+```
+
+The user can override the default in `config.toml`:
+
+```toml
+[params]
+mainSections = ["blog", "docs"]
+```
+
+[intersect]: /functions/intersect/
--- /dev/null
- : Relative directory from where Hugo reads static files.
+---
+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
+
+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.
+
+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)
+: 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 ([])
+: 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)
+: Disable automatic live reloading of browser window.
+
+disablePathToLower (false)
+: Do not convert the url/path to lowercase.
+
+enableEmoji (false)
+: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/).
+
+enableGitInfo (false)
+: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file.
+
+enableMissingTranslationPlaceholders (false)
+: Show a placeholder instead of the default value or an empty string if a translation is missing.
+
+enableRobotsTXT (false)
+: Enable generation of `robots.txt` file.
+
+frontmatter
+
+: See [Front matter Configuration](#configure-front-matter).
+
+footnoteAnchorPrefix ("")
+: Prefix for footnote anchors.
+
+footnoteReturnLinkContents ("")
+: Text to display for footnote return links.
+
+googleAnalytics ("")
+: Google Analytics tracking ID.
+
+hasCJKLanguage (false)
+: 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")
+: 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)
+: Don't sync modification time of files.
+
+paginate (10)
+: Default number of pages per page in [pagination](/templates/pagination/).
+
+paginatePath ("page")
+: The path element used during pagination (https://example.com/page/2).
+
+permalinks
+: See [Content Management](/content-management/urls/#permalinks).
+
+pluralizeListTitles (true)
+: Pluralize titles in lists.
+
+preserveTaxonomyNames (false)
+: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
+
+publishDir ("public")
+: The directory to where Hugo will write the final static site (the HTML files etc.).
+
+pygmentsCodeFencesGuessSyntax (false)
+: Enable syntax guessing for code fences without specified language.
+
+pygmentsStyle ("monokai")
+: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html).
+
+pygmentsUseClasses (false)
+: 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.
+
+rssLimit (unlimited)
+: Maximum number of items in the RSS feed.
+
+sectionPagesMenu ("")
+: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers).
+
+sitemap
+: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml).
+
+staticDir ("static")
++: A directory or a list of directories from where Hugo reads [static files][static-files].
+
+stepAnalysis (false)
+: Display memory and timing of different steps of the program.
+
+summaryLength (70)
+: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting).
+
+taxonomies
+: See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies).
+
+theme ("")
+: Theme to use (located by default in `/themes/THEMENAME/`).
+
+themesDir ("themes")
+: The directory where Hugo reads the themes from.
+
+timeout (10000)
+: Timeout for generating page contents, in milliseconds (defaults to 10 seconds). *Note:* this is used to bail out of recursive content generation, if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents) you might need to raise this limit.
+
+title ("")
+: Site title.
+
+uglyURLs (false)
+: When enabled, creates URL of 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.
+
+
+## Example Configuration
+
+The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
+
+{{< code-toggle file="config">}}
+baseURL: "https://yoursite.example.com/"
+title: "My Hugo Site"
+footnoteReturnLinkContents: "↩"
+permalinks:
+ post: /:year/:month/:title/
+params:
+ Subtitle: "Hugo is Absurdly Fast!"
+ AuthorName: "Jon Doe"
+ GitHubUser: "spf13"
+ ListOfFoo:
+ - "foo1"
+ - "foo2"
+ SidebarRecentLimit: 5
+{{< /code-toggle >}}
+
+## Configure with Environment Variables
+
+In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
+
+For example, the following command will effectively set a website's title on Unix-like systems:
+
+```
+$ env HUGO_TITLE="Some Title" hugo
+```
+
+This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example.
+
+{{% note "Setting Environment Variables" %}}
+Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
+{{% /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/en/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-toggle file="config" >}}
+[blackfriday]
+ angledQuotes = true
+ fractions = false
+ plainIDAnchors = true
+ extensions = ["hardLineBreak"]
+{{< /code-toggle >}}
+
+## 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/
++[static-files]: /content-management/static-files/
--- /dev/null
- description: Install Hugo on macOS, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run.
+---
+title: Install Hugo
+linktitle: Install Hugo
- sudo pacman -Sy hugo
++description: Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run.
+date: 2016-11-01
+publishdate: 2016-11-01
+lastmod: 2018-01-02
+categories: [getting started,fundamentals]
+authors: ["Michael Henderson"]
+keywords: [install,pc,windows,linux,macos,binary,tarball]
+menu:
+ docs:
+ parent: "getting-started"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/]
+toc: true
+---
+
+
+{{% note %}}
+There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary!
+{{% /note %}}
+
+Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].
+
+Hugo currently provides pre-built binaries for the following:
+
+* macOS (Darwin) for x64, i386, and ARM architectures
+* Windows
+* Linux
++* OpenBSD
+* FreeBSD
+
+Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See <https://golang.org/doc/install/source> for the full set of supported combinations of target operating systems and compilation architectures.
+
+## Quick Install
+
+### Binary (Cross-platform)
+
+Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.
+
+Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location.
+
+### Homebrew (macOS)
+
+If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:
+
+{{< code file="install-with-homebrew.sh" >}}
+brew install hugo
+{{< /code >}}
+
+For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.
+
+### Chocolatey (Windows)
+
+If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner:
+
+{{< code file="install-with-chocolatey.ps1" >}}
+choco install hugo -confirm
+{{< /code >}}
+
+### Source
+
+#### Prerequisite Tools
+
+* [Git][installgit]
+* [Go (latest or previous version)][installgo]
+
+#### Vendored Dependencies
+
+Hugo uses [dep][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware.
+
+The simplest way is to use [mage][] (a Make alternative for Go projects.)
+
+#### Fetch from GitHub
+
+{{< code file="from-gh.sh" >}}
+go get github.com/magefile/mage
+go get -d github.com/gohugoio/hugo
+cd ${GOPATH:-$HOME/go}/src/github.com/gohugoio/hugo
+mage vendor
+mage install
+{{< /code >}}
+
+{{% note %}}
+If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.
+{{% /note %}}
+
+## macOS
+
+### Assumptions
+
+1. You know how to open the macOS terminal.
+2. You're running a modern 64-bit Mac.
+3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.)
+
+### Pick Your Method
+
+There are three ways to install Hugo on your Mac
+
+1. The [Homebrew][brew] `brew` utility
+2. Distribution (i.e., tarball)
+3. Building from Source
+
+There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case.
+
+#### Pros and Cons
+
+There are pros and cons to each of the aforementioned methods:
+
+1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update.
+
+2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice.
+
+3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options.
+
+{{% note %}}
+Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball.
+{{% /note %}}
+
+### Install Hugo with Brew
+
+{{< youtube WvhCGlLcrF8 >}}
+
+#### Step 1: Install `brew` if you haven't already
+
+Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
+
+{{< code file="install-brew.sh" >}}
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+{{< /code >}}
+
+#### Step 2: Run the `brew` Command to Install `hugo`
+
+Installing Hugo using `brew` is as easy as the following:
+
+{{< code file="install-brew.sh" >}}
+brew install hugo
+{{< /code >}}
+
+If Homebrew is working properly, you should see something similar to the following:
+
+```
+==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
+######################################################################### 100.0%
+==> Pouring hugo-0.21.sierra.bottle.tar.gz
+🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB
+```
+
+{{% note "Installing the Latest Hugo with Brew" %}}
+Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version.
+{{% /note %}}
+
+`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands:
+
+```
+$ # show the location of the hugo executable
+which hugo
+/usr/local/bin/hugo
+
+# show the installed version
+ls -l $( which hugo )
+lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo
+
+# verify that hugo runs correctly
+hugo version
+Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00
+```
+
+### Install Hugo from Tarball
+
+#### Step 1: Decide on the location
+
+When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:
+
+1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.
+
+2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases.
+
+3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable.
+
+All three locations will work for you. In the interest of brevity, this guide focuses on option #2.
+
+#### Step 2: Download the Tarball
+
+1. Open <https://github.com/gohugoio/hugo/releases> in your browser.
+
+2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release."
+
+3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number.
+
+4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps.
+
+#### Step 3: Confirm your download
+
+Verify that the tarball wasn't corrupted during the download:
+
+```
+tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
+-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
+-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
+-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md
+```
+
+The `.md` files are documentation for Hugo. The other file is the executable.
+
+#### Step 4: Install Into Your `bin` Directory
+
+```
+# create the directory if needed
+mkdir -p ~/bin
+
+# make it the working directory
+cd ~/bin
+
+# extract the tarball
+tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz
+Archive: hugo_X.Y_osx-64bit.tgz
+ x ./
+ x ./hugo
+ x ./LICENSE.md
+ x ./README.md
+
+# verify that it runs
+./hugo version
+Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
+```
+
+You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
+
+```
+# check if hugo is in the path
+which hugo
+/Users/USERNAME/bin/hugo
+```
+
+If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:
+
+```
+nano ~/.bash_profile
+```
+
+Add a line to update your `PATH` variable:
+
+```
+export PATH=$PATH:$HOME/bin
+```
+
+Then save the file by pressing Control-X, then Y to save the file and return to the prompt.
+
+Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again.
+
+You've successfully installed Hugo.
+
+### Build from Source on Mac
+
+If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command:
+
+```
+brew install go
+```
+
+#### Step 1: Get the Source
+
+If you want to compile a specific version of Hugo, go to <https://github.com/gohugoio/hugo/releases> and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:
+
+```
+git clone https://github.com/gohugoio/hugo
+```
+
+{{% warning "Sometimes \"Latest\" = \"Bugs\""%}}
+Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new).
+{{% /warning %}}
+
+#### Step 2: Compiling
+
+Make the directory containing the source your working directory and then fetch Hugo's dependencies:
+
+```
+mkdir -p src/github.com/gohugoio
+ln -sf $(pwd) src/github.com/gohugoio/hugo
+
+# set the build path for Go
+export GOPATH=$(pwd)
+
+go get
+```
+
+This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change.
+
+Once you have properly configured your directory, you can compile Hugo using the following command:
+
+```
+go build -o hugo main.go
+```
+
+Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
+
+## Windows
+
+The following aims to be a complete guide to installing Hugo on your Windows PC.
+
+{{< youtube G7umPCU-8xc >}}
+
+### Assumptions
+
+1. You will use `C:\Hugo\Sites` as the starting point for your new project.
+2. You will use `C:\Hugo\bin` to store executable files.
+
+### Set up Your Directories
+
+You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website:
+
+1. Open Windows Explorer.
+2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere
+3. Create a subfolder in the Hugo folder: `C:\Hugo\bin`
+4. Create another subfolder in Hugo: `C:\Hugo\Sites`
+
+### Technical Users
+
+1. Download the latest zipped Hugo executable from [Hugo Releases][releases].
+2. Extract all contents to your `..\Hugo\bin` folder.
+3. The `hugo` executable will be named as `hugo_hugo-version_platform_arch.exe`. Rename the executable to `hugo.exe` for ease of use.
+4. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator.
+
+### Less-technical Users
+
+1. Go to the [Hugo Releases][releases] page.
+2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files.
+3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).)
+4. Move the ZIP file into your `C:\Hugo\bin` folder.
+5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else.
+6. You should now have three new files: hugo executable (e.g. `hugo_0.18_windows_amd64.exe`), `license.md`, and `readme.md`. (You can delete the ZIP download now.) Rename that hugo executable (`hugo_hugo-version_platform_arch.exe`) to `hugo.exe` for ease of use.
+
+Now you need to add Hugo to your Windows PATH settings:
+
+#### For Windows 10 Users:
+
+* Right click on the **Start** button.
+* Click on **System**.
+* Click on **Advanced System Settings** on the left.
+* Click on the **Environment Variables...** button on the bottom.
+* In the User variables section, find the row that starts with PATH (PATH will be all caps).
+* Double-click on **PATH**.
+* Click the **New...** button.
+* Type in the folder where `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The PATH entry should be the folder where Hugo lives and not the binary.* Press <kbd>Enter</kbd> when you're done typing.
+* Click OK at every window to exit.
+
+{{% note "Path Editor in Windows 10"%}}
+The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the <i class="fa fa-windows"></i> Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.)
+{{% /note %}}
+
+#### For Windows 7 and 8.x users:
+
+Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/).
+
+### Verify the Executable
+
+Run a few commands to verify that the executable is ready to run, and then build a sample site to get started.
+
+#### 1. Open a Command Prompt
+
+At the prompt, type `hugo help` and press the <kbd>Enter</kbd> key. You should see output that starts with:
+
+```
+hugo is the main command, used to build your Hugo site.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+```
+
+If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.
+
+At the prompt, change your directory to the `Sites` directory.
+
+```
+C:\Program Files> cd C:\Hugo\Sites
+C:\Hugo\Sites>
+```
+
+#### 2. Run the Command
+
+Run the command to generate a new site. I'm using `example.com` as the name of the site.
+
+```
+C:\Hugo\Sites> hugo new site example.com
+```
+
+You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following:
+
+```
+C:\Hugo\Sites> cd example.com
+C:\Hugo\Sites\example.com> dir
+Directory of C:\hugo\sites\example.com
+
+04/13/2015 10:44 PM <DIR> .
+04/13/2015 10:44 PM <DIR> ..
+04/13/2015 10:44 PM <DIR> archetypes
+04/13/2015 10:44 PM 83 config.toml
+04/13/2015 10:44 PM <DIR> content
+04/13/2015 10:44 PM <DIR> data
+04/13/2015 10:44 PM <DIR> layouts
+04/13/2015 10:44 PM <DIR> static
+ 1 File(s) 83 bytes
+ 7 Dir(s) 6,273,331,200 bytes free
+```
+
+### Troubleshoot Windows Installation
+
+[@dhersam][] has created a nice video on common issues:
+
+{{< youtube c8fJIRNChmU >}}
+
+## Linux
+
+### Snap Package
+
+In any of the [Linux distributions that support snaps][snaps]:
+
+```
+snap install hugo
+```
+
+### Debian and Ubuntu
+
+Debian and Ubuntu provide a `hugo` version via `apt-get`:
+
+```
+sudo apt-get install hugo
+```
+
+#### Pros
+
+* Native Debian/Ubuntu package maintained by Debian Developers
+* Pre-installed bash completion script and `man` pages
+
+#### Cons
+
+* Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo.
+
+{{% note %}}
+Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo snap install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory.
+{{% /note %}}
+
+### Arch Linux
+
+You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also for derivatives such as Manjaro.
+
+```
++sudo pacman -Syu hugo
+```
+
+### Fedora
+
+Fedora provides a package for Hugo. The installation is done with the command :
+
+```
+sudo dnf install hugo
+```
+
+### CentOS, and Red Hat
+
+* <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/>
+
+See the [related discussion in the Hugo forums][redhatforum].
+
++## OpenBSD
++
++OpenBSD provides a package for Hugo via `pkg_add`:
++
++```
++doas pkg_add hugo
++```
++
+## Upgrade Hugo
+
+Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew.
+
+## Install Pygments (Optional)
+
+The Hugo executable has one *optional* external dependency for source code highlighting ([Pygments][pygments]).
+
+If you want to have source code highlighting using the [highlight shortcode][], you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments homepage][pygments].
+
+## Next Steps
+
+Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum].
+
+[brew]: https://brew.sh/
+[Chocolatey]: https://chocolatey.org/
+[content]: /content-management/
+[@dhersam]: https://github.com/dhersam
+[forum]: https://discourse.gohugo.io
+[mage]: https://github.com/magefile/mage
+[dep]: https://github.com/golang/dep
+[highlight shortcode]: /content-management/shortcodes/#highlight
+[installgit]: http://git-scm.com/
+[installgo]: https://golang.org/dl/
+[Path Editor]: https://patheditor2.codeplex.com/
+[pygments]: http://pygments.org
+[quickstart]: /getting-started/quick-start/
+[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491
+[releases]: https://github.com/gohugoio/hugo/releases
+[snaps]: http://snapcraft.io/docs/core/install
+[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx
+[Windows Environment Variables Editor]: http://eveditor.com/
--- /dev/null
- 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.
+
+---
+date: 2017-10-16
+title: "Hugo 0.30: Race Car Edition!"
+description: "Fast Render Mode boosts live reloading!"
+categories: ["Releases"]
+images:
+- images/blog/hugo-30-poster.png
+---
+
+
++Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but wants much 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
- title: "0.43"
- description: "0.43"
+
+---
+date: 2018-07-09
++title: "And Now: Hugo Pipes!"
++description: "Hugo 0.43 adds a powerful and simple to use assets pipeline with SASS/SCSS and much, much more …"
+categories: ["Releases"]
+---
+
+ Hugo `0.43` adds a powerful and very simple to use **Assets Pipeline** with **SASS and SCSS** with source map support, **PostCSS** and **minification** and **fingerprinting** and **Subresource Integrity** and ... much more. Oh, did we mention that you can now do **ad-hoc image processing** and execute text resources as Go templates?
+
+An example pipeline:
+
+```go-html-template
+{{ $styles := resources.Get "scss/main.scss" | toCSS | postCSS | minify | fingerprint }}
+<link rel="stylesheet" href="{{ $styles.Permalink }}" integrity="{{ $styles.Data.Integrity }}" media="screen">
+```
+
+To me, the above is beautiful in its speed and simplicity. It could be printed on a t-shirt. I wrote in the [Hugo Birthday Post](https://gohugo.io/news/lets-celebrate-hugos-5th-birthday/) some days ago about the value of a single binary with native and fast implementations. I should have added _simplicity_ as a keyword. There seem to be a misconception that all of this needs to be hard and painful.
+
+New functions to create `Resource` objects:
+
+* `resources.Get`
+* `resources.FromString`: Create a Resource from a string.
+
+New `Resource` transformation funcs:
+
+* `resources.ToCSS`: Compile `SCSS` or `SASS` into `CSS`.
+* `resources.PostCSS`: Process your CSS with PostCSS. Config file support (project or theme or passed as an option).
+* `resources.Minify`: Currently supports `css`, `js`, `json`, `html`, `svg`, `xml`.
+* `resources.Fingerprint`: Creates a fingerprinted version of the given Resource with Subresource Integrity.
+* `resources.Concat`: Concatenates a list of Resource objects. Think of this as a poor man's bundler.
+* `resources.ExecuteAsTemplate`: Parses and executes the given Resource and data context (e.g. .Site) as a Go template.
+
+
+I, [@bep](https://github.com/bep), implemented this in [dea71670](https://github.com/gohugoio/hugo/commit/dea71670c059ab4d5a42bd22503f18c087dd22d4). We will work hard to get the documentation up to date, but follow the links above for details, and also see this [demo project](https://github.com/bep/hugo-sass-test).
+
+
+This release represents **35 contributions by 7 contributors** to the main Hugo code base.
+[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@anthonyfok](https://github.com/anthonyfok), [@openscript](https://github.com/openscript), and [@caarlos0](https://github.com/caarlos0) for their ongoing contributions.
+And a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the themes site in pristine condition and to [@kaushalmodi](https://github.com/kaushalmodi) for his great work on the documentation site.
+
+Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs),
+which has received **11 contributions by 5 contributors**. A special thanks to [@bep](https://github.com/bep), [@danrl](https://github.com/danrl), [@regisphilibert](https://github.com/regisphilibert), and [@digitalcraftsman](https://github.com/digitalcraftsman) for their work on the documentation site.
+
+Hugo now has:
+
+* 26968+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 443+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 238+ [themes](http://themes.gohugo.io/)
+
+## Notes
+
+* Replace deprecated {Get,}ByPrefix with {Get,}Match [42ed6025](https://github.com/gohugoio/hugo/commit/42ed602580a672e420e1d860384e812f4871ff67) [@anthonyfok](https://github.com/anthonyfok)
+* Hugo is now released with two binary version: One with and one without SCSS/SASS support. At the time of writing, this is only available in the binaries on the GitHub release page. Brew, Snap builds etc. will come. But note that you **only need the extended version if you want to edit SCSS**. For your CI server, or if you don't use SCSS, you will most likely want the non-extended version.
+
+## Enhancements
+
+### Templates
+
+* Return en empty slice in `after` instead of error [f8212d20](https://github.com/gohugoio/hugo/commit/f8212d20009c4b5cc6e1ec733d09531eb6525d9f) [@bep](https://github.com/bep) [#4894](https://github.com/gohugoio/hugo/issues/4894)
+* Update internal pagination template to support Bootstrap 4 [ca1e46ef](https://github.com/gohugoio/hugo/commit/ca1e46efb94e3f3d2c8482cb9434d2f38ffd2683) [@bep](https://github.com/bep) [#4881](https://github.com/gohugoio/hugo/issues/4881)
+* Support text/template/parse API change in go1.11 [9f27091e](https://github.com/gohugoio/hugo/commit/9f27091e1067875e2577c331acc60adaef5bb234) [@anthonyfok](https://github.com/anthonyfok) [#4784](https://github.com/gohugoio/hugo/issues/4784)
+
+### Core
+
+* Allow forward slash in shortcode names [de37455e](https://github.com/gohugoio/hugo/commit/de37455ec73cffd039b44e8f6c62d2884b1d6bbd) [@bep](https://github.com/bep) [#4886](https://github.com/gohugoio/hugo/issues/4886)
+* Reset the global pages cache on server rebuilds [128f14ef](https://github.com/gohugoio/hugo/commit/128f14efad90886ffef37c01ac1e20436a732f97) [@bep](https://github.com/bep) [#4845](https://github.com/gohugoio/hugo/issues/4845)
+
+### Other
+
+* Bump CircleCI image [e3df6478](https://github.com/gohugoio/hugo/commit/e3df6478f09a7a5fed96aced791fa94fd2c35d1a) [@bep](https://github.com/bep)
+* Add Goreleaser extended config [626afc98](https://github.com/gohugoio/hugo/commit/626afc98254421f5a5edc97c541b10bd81d5bbbb) [@bep](https://github.com/bep) [#4908](https://github.com/gohugoio/hugo/issues/4908)
+* Build both hugo and hugo.extended for 0.43 [e1027c58](https://github.com/gohugoio/hugo/commit/e1027c5846b48c4ad450f6cc27e2654c9e0dae39) [@anthonyfok](https://github.com/anthonyfok) [#4908](https://github.com/gohugoio/hugo/issues/4908)
+* Add temporary build script [bfc3488b](https://github.com/gohugoio/hugo/commit/bfc3488b8e8b3dc1ffc6a339ee2dac8dcbdb55a9) [@bep](https://github.com/bep)
+* Add "extended" to "hugo version" [ce84b524](https://github.com/gohugoio/hugo/commit/ce84b524f4e94299b5b66afe7ce1a9bd4a9959fc) [@anthonyfok](https://github.com/anthonyfok) [#4913](https://github.com/gohugoio/hugo/issues/4913)
+* Add a newScratch template func [2b8d907a](https://github.com/gohugoio/hugo/commit/2b8d907ab731627f4e2a30442cd729064516c8bb) [@bep](https://github.com/bep) [#4685](https://github.com/gohugoio/hugo/issues/4685)
+* Add Hugo Piper with SCSS support and much more [dea71670](https://github.com/gohugoio/hugo/commit/dea71670c059ab4d5a42bd22503f18c087dd22d4) [@bep](https://github.com/bep) [#4381](https://github.com/gohugoio/hugo/issues/4381)[#4903](https://github.com/gohugoio/hugo/issues/4903)[#4858](https://github.com/gohugoio/hugo/issues/4858)
+* Consider root and current section's content type if set in front matter [c790029e](https://github.com/gohugoio/hugo/commit/c790029e1dbb0b66af18d05764bd6045deb2e180) [@bep](https://github.com/bep) [#4891](https://github.com/gohugoio/hugo/issues/4891)
+* Update docker image [554553c0](https://github.com/gohugoio/hugo/commit/554553c09c7657d28681e1fa0638806a452737a0) [@bep](https://github.com/bep)
+* Merge branch 'release-0.42.2' [282f6035](https://github.com/gohugoio/hugo/commit/282f6035e7c36f8550d91033e3a66718468c6c8b) [@bep](https://github.com/bep)
+* Release 0.42.2 [1637d12e](https://github.com/gohugoio/hugo/commit/1637d12e3762fc1ebab4cd675f75afaf25f59cdb) [@bep](https://github.com/bep)
+* Update GoReleaser config [1f0c4e1f](https://github.com/gohugoio/hugo/commit/1f0c4e1fb347bb233f3312c424fbf5a013c03604) [@caarlos0](https://github.com/caarlos0)
+* Create missing head.html partial on new theme generation [fd71fa89](https://github.com/gohugoio/hugo/commit/fd71fa89bd6c197402582c87b2b76d4b96d562bf) [@openscript](https://github.com/openscript)
+* Add html doctype to baseof.html template for new themes [b5a3aa70](https://github.com/gohugoio/hugo/commit/b5a3aa7082135d0a573f4fbb00f798e26b67b902) [@openscript](https://github.com/openscript)
+* Adds .gitattributes to force Go files to LF [6a2968fd](https://github.com/gohugoio/hugo/commit/6a2968fd5c0116d93de0f379ac615e9076821899) [@neurocline](https://github.com/neurocline)
+* Update to Go 1.9.7 and Go 1.10.3 [23d5fc82](https://github.com/gohugoio/hugo/commit/23d5fc82ee01d56440d0991c899acd31e9b63e27) [@anthonyfok](https://github.com/anthonyfok)
+* Update Dockerfile to a multi-stage build [8531ec7c](https://github.com/gohugoio/hugo/commit/8531ec7ca36fd35a57fba06bbb06a65c94dfd3ed) [@skoblenick](https://github.com/skoblenick) [#4154](https://github.com/gohugoio/hugo/issues/4154)
+* Release 0.42.1 [d67e843c](https://github.com/gohugoio/hugo/commit/d67e843c1212e1f53933556b5f946c8541188d9a) [@bep](https://github.com/bep)
+* Do not fail server build when /static is missing [34ee27a7](https://github.com/gohugoio/hugo/commit/34ee27a78b9e2b5f475d44253ae234067b76cc6e) [@bep](https://github.com/bep) [#4846](https://github.com/gohugoio/hugo/issues/4846)
+
+## Fixes
+
+* Do not create paginator pages for the other output formats [43338c3a](https://github.com/gohugoio/hugo/commit/43338c3a99769eb7d0df0c12559b8b3d42b67dba) [@bep](https://github.com/bep) [#4890](https://github.com/gohugoio/hugo/issues/4890)
+* Fix the shortcodes/partials vs base template detection [a5d0a57e](https://github.com/gohugoio/hugo/commit/a5d0a57e6bdab583134a68c035aac9b3007f006a) [@bep](https://github.com/bep) [#4897](https://github.com/gohugoio/hugo/issues/4897)
+* nfpm replacements [e1a052ec](https://github.com/gohugoio/hugo/commit/e1a052ecb823c688406a8af97dfaaf52a75231da) [@caarlos0](https://github.com/caarlos0)
+* Fix typos [3cea2932](https://github.com/gohugoio/hugo/commit/3cea2932e17a08ebc19cd05f3079d9379bc8fba5) [@idealhack](https://github.com/idealhack)
+
+
+
+
--- /dev/null
- title: "0.44"
- description: "0.44"
+
+---
+date: 2018-07-13
++title: "Hugo 0.44: Friday the 13th Edition"
++description: "A sequel to the very popular Hugo Pipes Edition; bug-fixes and enhancements …"
+categories: ["Releases"]
+---
+
+
+Hugo `0.44` is the follow-up release, or **The Sequel**, of the very well received `0.43` only days ago. That release added **Hugo Pipes**, with SCSS/SASS support, assets bundling and minification, ad-hoc image processing and much more.
+
+This is mostly a bug-fix release, but it also includes several important improvements.
+
+Many complained that their SVG images vanished when browsed from the `hugo server`. With **Hugo Pipes** MIME types suddenly got really important, but Hugo's use of `Suffix` was ambiguous. This became visible when we redefined the `image/svg+xml` to work with **Hugo Pipes**. We have now added a `Suffixes` field on the MIME type definition in Hugo, which is a list of one or more filename suffixes the MIME type is identified with. If you need to add a custom MIME type definition, this means that you also need to specify the full MIME type as the key, e.g. `image/svg+xml`.
+
+Hugo now has:
+
+* 27120+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 443+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 239+ [themes](http://themes.gohugo.io/)
+
+## Notes
+* `MediaType.Suffix` is deprecated and replaced with a plural version, `MediaType.Suffixes`, with a more specific definition. You will get a detailed WARNING in the console if you need to do anything.
+
+## Enhancements
+* Allow multiple file suffixes per media type [b874a1ba](https://github.com/gohugoio/hugo/commit/b874a1ba7ab8394dc741c8c70303a30a35b63e43) [@bep](https://github.com/bep) [#4920](https://github.com/gohugoio/hugo/issues/4920)
+* Clean up the in-memory Resource reader usage [47d38628](https://github.com/gohugoio/hugo/commit/47d38628ec0f4e72ff17661f13456b2a1511fe13) [@bep](https://github.com/bep) [#4936](https://github.com/gohugoio/hugo/issues/4936)
+* Move opening of the transformed resources after cache check [0024dcfe](https://github.com/gohugoio/hugo/commit/0024dcfe3e016c67046de06d1dac5e7f5235f9e1) [@bep](https://github.com/bep)
+* Improve type support in `resources.Concat` [306573de](https://github.com/gohugoio/hugo/commit/306573def0e20ec16ee5c447981cc09ed8bb7ec7) [@bep](https://github.com/bep) [#4934](https://github.com/gohugoio/hugo/issues/4934)
+* Flush `partialCached` cache on rebuilds [6b6dcb44](https://github.com/gohugoio/hugo/commit/6b6dcb44a014699c289bf32fe57d4c4216777be0) [@bep](https://github.com/bep) [#4931](https://github.com/gohugoio/hugo/issues/4931)
+* Include the transformation step in the error message [d96f2a46](https://github.com/gohugoio/hugo/commit/d96f2a460f58e91d8f6253a489d4879acfec6916) [@bep](https://github.com/bep) [#4924](https://github.com/gohugoio/hugo/issues/4924)
+* Exclude *.svg from CRLF/LF conversion [9c1e8208](https://github.com/gohugoio/hugo/commit/9c1e82085eb07d5b4dcdacbe82d5bafd26e08631) [@anthonyfok](https://github.com/anthonyfok)
+
+## Fixes
+
+* Fix `resources.Concat` for transformed resources [beec1fc9](https://github.com/gohugoio/hugo/commit/beec1fc98e5d37bba742d6bc2a0ff7c344b469f8) [@bep](https://github.com/bep) [#4936](https://github.com/gohugoio/hugo/issues/4936)
+* Fix static filesystem for themed multihost sites [80c8f3b8](https://github.com/gohugoio/hugo/commit/80c8f3b81a9849080e64bf877288ede28d960d3f) [@bep](https://github.com/bep) [#4929](https://github.com/gohugoio/hugo/issues/4929)
+* Set permission of embedded templates to 0644 [2b73e89d](https://github.com/gohugoio/hugo/commit/2b73e89d6d2822e86360a6c92c87f539677c119b) [@anthonyfok](https://github.com/anthonyfok)
+
--- /dev/null
- We have some more technical tasks that needs to be done (there is ongoing work to get the page quries into a more consistent state, also a simpler `.GetPage` method), but also some cool new functionality. The following roadmap is taken from memory, and may not be complete, but should be a good indication of what's ahead.
+---
+date: 2018-07-04
+title: "Let’s celebrate Hugo’s 5th birthday"
+description: "How a side project became one of the most popular frameworks for building websites."
+categories: [blog]
+author: bep
+---
+
+_By Bjørn Erik Pedersen ([@bepsays](https://twitter.com/bepsays) / [@bep](https://github.com/bep)), Hugo Lead_
+
+**Five years ago today, [Steve Francia](https://github.com/spf13/) made his [first commit](https://github.com/gohugoio/hugo/commit/50a1d6f3f155ab837310e00ffb309a9199773c73
+) on the Hugo project: "Hugo: A Fast and Flexible Static Site Generator built with love by spf13 in GoLang".**
+
+Steve was writing that on a train commute to New York. I'm writing this article running Hugo `v0.43-DEV`, the preview version of the next Hugo release. The release is scheduled for Monday and adds a powerful [assets pipeline](https://github.com/gohugoio/hugo/issues/4854#issue-333062459), with SCSS/SASS support, assets minification, fingerprinting/subresource integrity, ad-hoc image processing and much more.
+
+**I cannot remember the last time I was this excited about a Hugo release. "Game changer" may be too strong, but it makes for a really nice integrated website design-workflow that, with Hugo's build speed, is hard to beat.**
+
+{{< imgproc sunset Fill "600x300" >}}
+Fetch and scale an image in the upcoming Hugo 0.43.
+{{< /imgproc >}}
+
+But that is a release for Monday. Now is a time to look at the current status of Hugo after the first five years.
+
+## Hugo in Numbers
+
+According to [BuiltWith](https://trends.builtwith.com/cms/Hugo), more than 29 000 live websites are built with Hugo. Of those, 390 are in the top 1 million. Wappalyzer [reports](https://www.wappalyzer.com/categories/static-site-generator) that Hugo serves almost 50% of the static sites.
+
+Hugo is big in the [public sector](https://discourse.gohugo.io/t/hugo-in-public-administration/8792), with the US Government as a prominent user. Some examples are [vote.gov](https://vote.gov/) and [digital.gov](https://digital.gov/).
+
+[Smashing Magazine](https://www.smashingmagazine.com/) is a big and very popular Hugo site. It is [reported](https://discourse.gohugo.io/t/smashing-magazine-s-redesign-powered-by-hugo-jamstack/5826/7) that they build their complex site with 7500 content pages in 13 seconds.
+
+Some other example sites are [kubernetes.io](https://kubernetes.io/), [letsencrypt.org](https://gohugo.io/showcase/letsencrypt/), [support.1password.com](http://gohugo.io/showcase/1password-support/), [netlify.com](https://www.netlify.com), [litecoin.org](https://litecoin.org/), and [forestry.io](https://forestry.io/).
+
+
+{{< imgproc graph-stars Fit "600x400" >}}
+Number of GitHub stars in relation to the Hugo release dates.
+{{< /imgproc >}}
+
+More numbers:
+
+* 26800+ [stars](https://github.com/gohugoio/hugo/stargazers) on GitHub.
+* 444+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) to the Hugo source repository, 654+ to [Hugo Docs](https://github.com/gohugoio/hugoDocs/graphs/contributors). [@bep](https://github.com/bep) is the most active with around 70% of the current code base (line count).
+* 235+ [themes](https://themes.gohugo.io/)
+* 50% increase in the number of user sessions on the [gohugo.io](https://gohugo.io/) web sites the last 12 months.[^2]
+* Hugo build release binaries for [a myriad](https://github.com/gohugoio/hugo/releases/tag/v0.42.2) of platforms. And since it can also be installed from Chocolatey on Windows, Brew on MacOs, Snap on Linux and `apt-get` on Debian/Ubuntu, it is impossible to give accurate download numbers. But the number is not small.
+
+## Hugo Next
+
+We're not finished with Hugo, but Hugo `0.43` very nicely wraps up the first five years. It started out as a small and fast static site generator. It is now [even faster](https://forestry.io/blog/hugo-vs-jekyll-benchmark/), and now so loaded with features that it has grown out of being just a "static site generator". It is a _framework for building websites_.
+
+My interest in Hugo started on the Sunday when I moved my blog, [bepsays.com](https://bepsays.com/en/), twice. The second static generator choice of that day, Hugo, was a good match. I remember Steve being very enthusiastic about getting patches with fixes and enhancements, and I was eventually taken over by the simplicity and power of Go, the programming language, and started to implement lots of new features.
+
+My goal with all of this, if there is one, is to get a single binary with native and really fast implementations of the complete stack I need for web development and content editing. The single binary takes most of the pain out of installation and upgrades (if you stick with the same binary, it will continue to just work for decades).
+
+**With 0.43, we are almost there.** With that release, it should be possible to set up a Hugo-only project without any additional tools (Gulp, WebPack) for all aspects of website building. There will still be situations where those tools will still be needed, of course, but we will continue to fill the gaps in the feature set.
+
+Hugo has stuck with the sub-zero versions to signal active development, with a new main release every 5-6 weeks. But we take stability very seriously (breaking things add lots of support work, we don't like that) and most site upgrades are [smooth](https://twitter.com/tmmx/status/1006288444459503616). But we are closing in on the first major stable version.
+
+
+### The Road to 1.0
+
- We should be able to create a better and easier-to-use data structure from the rendered content: Summary, the content after the summary, being able to range over the footnotes and the ToC. Having ToC as a proper data structure also open up a few other potential uses; using it as an index in [Related Content](https://gohugo.io/content-management/related/) would be one example.
++We have some more technical tasks that needs to be done (there is ongoing work to get the page queries into a more consistent state, also a simpler `.GetPage` method), but also some cool new functionality. The following roadmap is taken from memory, and may not be complete, but should be a good indication of what's ahead.
+
+Pages from "other data sources"
+: Currently, in addition to Hugo's list pages, every URL must be backed by a content file (Markdown, HTML etc.). This covers most use cases, but we need a flexible way to generate pages from other data sources. Think product catalogues and similar.
+
+Upgrade Blackfriday to v2
+: [Blackfriday](https://github.com/russross/blackfriday) is the main content renderer in Hugo. It has been rewritten to a more flexible architecture, which should allow us to fix some of the current shortcomings.
+
- These are the items that first comes to mind if you ask me to think even further ahead:
++We should be able to create a better and easier-to-use data structure from the rendered content: Summary, the content after the summary, being able to range over the footnotes and the ToC. Having ToC as a proper data structure also opens up a few other potential uses; using it as an index in [Related Content](https://gohugo.io/content-management/related/) would be one example.
+
+This should also enable us to _do more_ with [Custom Output Formats](/templates/output-formats). It is already very powerful. GettyPubs are using it in [Quire](https://github.com/gettypubs/quire) to build [beautiful multi-platform publications](http://www.getty.edu/publications/digital/digitalpubs.html). But it can be improved. For rendering of content files, you are currently restricted to HTML. It would be great if we could configure alternative renderers per output format, such as LaTeX and EPUB.
+
+Related to this is also to add a configurable "Markdown URL rewriter", which should make more portable URLs in Markdown, e.g. image links that work both when viewed on GitHub and your published site.
+
+### The Road to the Future
+
- : A Theme Component could also be called a plugin. But there are several potential plugin hooks into Hugo's build pipeline: Resource transformations, content rendering etc. We will eventually get there, but we should do it without giving up too much of the Hugo speed and simplicity.
++These are the items that first come to mind if you ask me to think even further ahead:
+
+Dependency manager for Theme Components
+: In Hugo `0.42` we added [Theme Components](/themes/theme-components/) and Theme Inheritance. With SCSS support in Hugo `0.43`, which also follows the same project/themes precedence order (add `_variables.scss` to your project, configure SASS colour variables in `config.toml`), we have a solid foundation for creating easy to use and extensible themes. But we are missing some infrastructure around this. We have a site with 235+ [themes](https://themes.gohugo.io/)[^themes] listed, but you currently need to do some added work to get the theme up and running for your site. In the Go world, we don't have NPM to use, which is a curse and a blessing, but I have some ideas about building a simple dependency manager into Hugo, modelled after how Go is doing it (`hugo install`). You should be able to configure what theme and theme components you want to use, and Hugo should handle the installation of the correct versions. This should make it easier for the user, but it would also enable community driven and even commercial "theme stores".
+
+
+{{< imgproc graph-themes Fit "600x400" >}}
+Number of Hugo themes on themes.gohugo.io in relation to the Hugo release dates.
+{{< /imgproc >}}
+
+
+The "New York Times on Hugo" Use Case
+: There are recurring questions on the support forum from [really big sites](https://discourse.gohugo.io/t/transition-2m-posts-from-wordpress-to-hugo/12704) that want to move to Hugo. There are many [good reasons](https://www.netlify.com/blog/2016/05/18/9-reasons-your-site-should-be-static/) why they want this (security, cost-saving, EU regulations etc.). And while there have been reports about companies building 600 000 pages with Hugo on very powerful hardware, we will have to rethink the build model to make this usable. Keywords are: streaming builds, segmented builds, partial rebuilds. There are other site generators also talking about this. It should be possible, and my instinct tells me that it should be easier to do when your starting point is "really fast". But this is not a small weekend project for me, and I have already talked to several companies about sponsoring this.
+
+Plugins
- So, thanks to everyone who have contributed to getting Hugo where it is today. It is hard to single out individuals, but a big shout-out to all the Hugo experts and moderators helping out making the [discourse.gohugo.io](https://discourse.gohugo.io/) a very active and possibly one of the best support forums out there.
++: A Theme Component could also be called a plugin. But there are several potential plugin hooks into Hugo's build pipeline: resource transformations, content rendering, etc. We will eventually get there, but we should do it without giving up too much of the Hugo speed and simplicity.
+
+
+## Thanks
+
- And the last shout-out goes to two maintainers who have been there more or less from the start. [@digitalcraftsman](https://github.com/digitalcraftsman/) has been doing a fantastic job keeping the fast growing theme site and [repository](https://github.com/gohugoio/hugoThemes) in pristine condition. I have it on my watch list, but that is just out of curiosity. There are lots of activity, but it runs as clock work. [Anthony Fok](https://github.com/anthonyfok) has contributed with a variety of things but is most notable as the Linux expert on the team. He manages the Debian build and is the one to thank for up-to-date binaries on Debian and Ubuntu.
++So, thanks to everyone who has contributed to getting Hugo where it is today. It is hard to single out individuals, but a big shout-out to all the Hugo experts and moderators helping out making [discourse.gohugo.io](https://discourse.gohugo.io/) a very active and possibly one of the best support forums out there.
+
- [^2]: Numbers from Google Analytics. The Hugo websites are https://discourse.gohugo.io/, https://gohugo.io/ and https://themes.gohugo.io/. It is rumoured that when [Matt Biilman](https://twitter.com/biilmann?lang=en), CEO and Co-founder of Netlify, opened the first power bill after sponsoring Hugo's hosting, said: "Du må lave fis med mig, those Hugo sites have lots of web traffic!"
++And the last shout-out goes to two maintainers who have been there more or less from the start. [@digitalcraftsman](https://github.com/digitalcraftsman/) has been doing a fantastic job keeping the fast growing theme site and [repository](https://github.com/gohugoio/hugoThemes) in pristine condition. I have it on my watch list, but that is just out of curiosity. There is lots of activity, but it runs as clock work. [Anthony Fok](https://github.com/anthonyfok) has contributed with a variety of things but is most notable as the Linux expert on the team. He manages the Debian build and is the one to thank for up-to-date binaries on Debian and Ubuntu.
+
+One final note: If you have not done so already, please visit [github.com/gohugoio/hugo](https://github.com/gohugoio/hugo) and push the "star button".
+
+Gopher artwork by [Ashley McNamara](https://github.com/ashleymcnamara/gophers/) (licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)). Inspired by [Renee French](https://reneefrench.blogspot.com/).
+
- [^themes]: We pull all the themes from GitHub and build the theme site and 235 demo sites on Netlify in 4 minutes. And that is impressing.
++[^2]: Numbers from Google Analytics. The Hugo websites are https://discourse.gohugo.io, https://gohugo.io and https://themes.gohugo.io. It is rumoured that when [Matt Biilman](https://twitter.com/biilmann?lang=en), CEO and Co-founder of Netlify, opened the first power bill after sponsoring Hugo's hosting, said: "Du må lave fis med mig, those Hugo sites have lots of web traffic!"
+[^sgen]: That was at the time of writing this article. _Next_, a React based static site generator, has momentum and is closing in on Hugo's 2nd place.
++[^themes]: We pull all the themes from GitHub and build the theme site and 235 demo sites on Netlify in 4 minutes. That is impressive.
--- /dev/null
- In addition to the standard page variables, the 404 page has access to all site content accessible from `.Data.Pages`.
+---
+title: Custom 404 Page
+linktitle: 404 Page
+description: If you know how to create a single page template, you have unlimited options for creating a custom 404.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+categories: [templates]
+keywords: [404, page not found]
+menu:
+ docs:
+ parent: "templates"
+ weight: 120
+weight: 120 #rem
+draft: false
+aliases: [/templates/404/]
+toc: false
+---
+
+When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root.
+
+404 pages will have all the regular [page variables][pagevars] available to use in the templates.
+
++In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`.
+
+```
+▾ layouts/
+ 404.html
+```
+
+## 404.html
+
+This is a basic example of a 404.html template:
+
+{{< code file="layouts/404.html" download="404.html" >}}
+{{ define "main"}}
+ <main id="main">
+ <div>
+ <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1>
+ </div>
+ </main>
+{{ end }}
+{{< /code >}}
+
+## Automatic Loading
+
+Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example:
+
+* [GitHub Pages](/hosting-and-deployment/hosting-on-github/). The 404 page is automatic.
+* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site.
+* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file.
+* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI.
+* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors)
+
+{{% note %}}
+`hugo server` will not automatically load your custom `404.html` file, but you
+can test the appearance of your custom "not found" page by navigating your
+browser to `/404.html`.
+{{% /note %}}
+
+[pagevars]: /variables/page/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Base Templates and Blocks
+linktitle:
+description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
+godocref: https://golang.org/pkg/text/template/#example_Template_block
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates,fundamentals]
+keywords: [blocks,base]
+menu:
+ docs:
+ parent: "templates"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
+toc: true
+---
+
+The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
+
+{{< youtube QVOMCYitLEc >}}
+
+## Base Template Lookup Order
+
+The [lookup order][lookup] for base templates is as follows:
+
+1. `/layouts/section/<TYPE>-baseof.html`
+2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
+3. `/layouts/<TYPE>/baseof.html`
+4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/<THEME>/layouts/section/baseof.html`
+7. `/layouts/_default/<TYPE>-baseof.html`
+8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/<THEME>/layouts/_default/baseof.html`
+
+Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
+
+### Example Base Template Lookup Order
+
+As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
+
+Here is the lookup order for the `post` base template:
+
+1. `/layouts/section/post-baseof.html`
+2. `/themes/mytheme/layouts/section/post-baseof.html`
+3. `/layouts/post/baseof.html`
+4. `/themes/mytheme/layouts/post/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/mytheme/layouts/section/baseof.html`
+7. `/layouts/_default/post-baseof.html`
+8. `/themes/mytheme/layouts/_default/post-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/mytheme/layouts/_default/baseof.html`
+
+## Define the Base Template
+
+The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
+
+{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title>{{ block "title" . }}
+ <!-- Blocks may include default content. -->
+ {{ .Site.Title }}
+ {{ end }}</title>
+ </head>
+ <body>
+ <!-- Code that all your templates share, like a header -->
+ {{ block "main" . }}
+ <!-- The part of the page that begins to differ between templates -->
+ {{ end }}
+ {{ block "footer" . }}
+ <!-- More shared code, perhaps a footer but that can be overridden if need be in -->
+ {{ end }}
+ </body>
+</html>
+{{< /code >}}
+
+## Override the Base Template
+
+From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
+
+{{< code file="layouts/_default/list.html" download="list.html" >}}
+{{ define "main" }}
+ <h1>Posts</h1>
++ {{ range .Pages }}
+ <article>
+ <h2>{{ .Title }}</h2>
+ {{ .Content }}
+ </article>
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
+
+{{% warning %}}
+Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
+
+```
+<!-- Seemingly harmless HTML comment..that will break your layout at build -->
+{{ define "main" }}
+...your code here
+{{ end }}
+```
+[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
+{{% /warning %}}
+
+The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
+
+{{< code file="layouts/_default/single.html" download="single.html" >}}
+{{ define "title" }}
+ <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
+ {{ .Title }} – {{ .Site.Title }}
+{{ end }}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+[hugolists]: /templates/lists
+[lookup]: /templates/lookup-order/
+[rendering the section]: /templates/section-templates/
+[singletemplate]: /templates/single-page-templates/
--- /dev/null
- ## `.Data.Pages` on the Homepage
+---
+title: Homepage Template
+linktitle: Homepage Template
+description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [homepage]
+menu:
+ docs:
+ parent: "templates"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/layout/homepage/,/templates/homepage-template/]
+toc: true
+---
+
+Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
+
+{{% note "The Only Required Template" %}}
+The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
+{{% /note %}}
+
+{{< youtube ut1xtRZ1QOA >}}
+
+## Homepage Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Add Content and Front Matter to the Homepage
+
+The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file.
+
+See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
+
- In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Data.Pages`.
++## `.Pages` on the Homepage
+
- <!-- Note that .Data.Pages is the equivalent of .Site.Pages on the homepage template. -->
- {{ range first 10 .Data.Pages }}
++In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Pages`.
+
+## Example Homepage Template
+
+The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
+
+{{< code file="layouts/index.html" download="index.html" >}}
+{{ define "main" }}
+ <main aria-role="main">
+ <header class="homepage-header">
+ <h1>{{.Title}}</h1>
+ {{ with .Params.subtitle }}
+ <span class="subtitle">{{.}}</span>
+ {{ end }}
+ </header>
+ <div class="homepage-content">
+ <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
+ {{.Content}}
+ </div>
+ <div>
++ <!-- Note that .Pages is the same as .Site.RegularPages on the homepage template. -->
++ {{ range first 10 .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+ </main>
+{{ end }}
+{{< /code >}}
+
+[base]: /templates/base/
+[contentorg]: /content-management/organization/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[sitevars]: /variables/site/
--- /dev/null
- {{ range where .Data.Pages.ByDate "Section" "events" }}
+---
+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
+
+Go templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go template variables and functions are accessible within `{{ }}`.
+
+### Access a Predefined Variable
+
+```
+{{ 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 [Go template documentation](http://golang.org/pkg/text/template/#hdr-Functions).
+{{% /note %}}
+
+## Includes
+
+When including another template, you will need to pass it the data that it would
+need to access.
+
+{{% note %}}
+To pass along the current context, please remember to include a trailing **dot**.
+{{% /note %}}
+
+The templates location will always be starting at the `layouts/` directory
+within Hugo.
+
+### Partial
+
+The [`partial`][partials] function is used to include *partial* templates using
+the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
+
+Example:
+
+```
+{{ 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]:
+
+```
+{{ 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-toggle file="config" >}}
+params:
+ copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
+ twitteruser: "spf13"
+ sidebarrecentlimit: 5
+{{< /code >}}
+
+Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
+
+```
+{{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 .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 Go's html templating"
+[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Go'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
- {{ range .Data.Pages }}
+---
+title: Lists of Content in Hugo
+linktitle: List Page Templates
+description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,rss,taxonomies,terms]
+menu:
+ docs:
+ parent: "templates"
+ weight: 22
+weight: 22
+sections_weight: 22
+draft: false
+aliases: [/templates/list/,/layout/indexes/]
+toc: true
+---
+
+## What is a List Page Template?
+
+{{< youtube 8b2YTSMdMps >}}
+
+A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage].
+
+Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
+
+* [Taxonomy terms pages][taxterms]
+* [Taxonomy list pages][taxlists]
+* [Section list pages][sectiontemps]
+* [RSS][rss]
+
+For template lookup order, see [Template Lookup](/templates/lookup-order/).
+
+The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
+
+
+
+## List Defaults
+
+### Default Templates
+
+Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes/<THEME>/layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`:
+
+See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
+
+## Add Content and Front Matter to List Pages
+
+Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content.
+
+This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars].
+
+{{% note %}}
+It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/).
+{{% /note %}}
+
+### Example Project Directory
+
+The following is an example of a typical Hugo project directory's content:
+
+```
+.
+...
+├── content
+| ├── post
+| | ├── _index.md
+| | ├── post-01.md
+| | └── post-02.md
+| └── quote
+| | ├── quote-01.md
+| | └── quote-02.md
+...
+```
+
+Using the above example, let's assume you have the following in `content/post/_index.md`:
+
+{{< code file="content/post/_index.md" >}}
+---
+title: My Go Journey
+date: 2017-03-23
+publishdate: 2017-03-24
+---
+
+I decided to start learning Go in March 2017.
+
+Follow my journey through this new blog.
+{{< /code >}}
+
+You can now access this `_index.md`'s' content in your list template:
+
+{{< code file="layouts/_default/list.html" download="list.html" >}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ </header>
+ <!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
+ {{.Content}}
+ </article>
+ <ul>
+ <!-- Ranges through content/post/*.md -->
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ <li>
+ <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
+ </li>
+ {{ end }}
+ </ul>
+</main>
+{{ end }}
+{{< /code >}}
+
+This above will output the following HTML:
+
+{{< code file="example.com/post/index.html" copy="false" >}}
+<!--top of your baseof code-->
+<main>
+ <article>
+ <header>
+ <h1>My Go Journey</h1>
+ </header>
+ <p>I decided to start learning Go in March 2017.</p>
+ <p>Follow my journey through this new blog.</p>
+ </article>
+ <ul>
+ <li><a href="/post/post-01/">Post 1</a></li>
+ <li><a href="/post/post-02/">Post 2</a></li>
+ </ul>
+</main>
+<!--bottom of your baseof-->
+{{< /code >}}
+
+### List Pages Without `_index.md`
+
+You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc.
+
+Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
+
+{{< code file="example.com/quote/index.html" copy="false" >}}
+<!--baseof-->
+<main>
+ <article>
+ <header>
+ <!-- Hugo assumes that .Title is the name of the section since there is no _index.md content file from which to pull a "title:" field -->
+ <h1>Quotes</h1>
+ </header>
+ </article>
+ <ul>
+ <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
+ <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
+ </ul>
+</main>
+<!--baseof-->
+{{< /code >}}
+
+{{% note %}}
+The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
+{{% /note %}}
+
+## Example List Templates
+
+### Section Template
+
+This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base] The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
+
+{{< code file="layouts/section/post.html" >}}
+{{ partial "header.html" . }}
+{{ partial "subheader.html" . }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <ul>
+ <!-- Renders the li.html content view for each content/post/*.md -->
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "li"}}
+ {{ end }}
+ </ul>
+ </div>
+</main>
+{{ partial "footer.html" . }}
+{{< /code >}}
+
+### Taxonomy Template
+
+{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}}
+{{ define "main" }}
+<main>
+ <div>
+ <h1>{{ .Title }}</h1>
+ <!-- ranges through each of the content files associated with a particular taxonomy term and renders the summary.html content view -->
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</main>
+{{ end }}
+{{< /code >}}
+
+## Order Content
+
+Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
+
+### Default: Weight > Date > LinkTitle > FilePath
+
+{{< code file="layouts/partials/default-order.html" >}}
+<ul>
- {{ range .Data.Pages.ByWeight }}
++ {{ range .Pages }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Weight
+
+Lower weight gets higher precedence. So content with lower weight will come first.
+
+{{< code file="layouts/partials/by-weight.html" >}}
+<ul>
- {{ range .Data.Pages.ByDate }}
++ {{ range .Pages.ByWeight }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Date
+
+{{< code file="layouts/partials/by-date.html" >}}
+<ul>
+ <!-- orders content according to the "date" field in front matter -->
- {{ range .Data.Pages.ByPublishDate }}
++ {{ range .Pages.ByDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Publish Date
+
+{{< code file="layouts/partials/by-publish-date.html" >}}
+<ul>
+ <!-- orders content according to the "publishdate" field in front matter -->
- {{ range .Data.Pages.ByExpiryDate }}
++ {{ range .Pages.ByPublishDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Expiration Date
+
+{{< code file="layouts/partials/by-expiry-date.html" >}}
+<ul>
- {{ range .Data.Pages.ByLastmod }}
++ {{ range .Pages.ByExpiryDate }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Last Modified Date
+
+{{< code file="layouts/partials/by-last-mod.html" >}}
+<ul>
+ <!-- orders content according to the "lastmod" field in front matter -->
- {{ range .Data.Pages.ByLength }}
++ {{ range .Pages.ByLastmod }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Length
+
+{{< code file="layouts/partials/by-length.html" >}}
+<ul>
+ <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
- {{ range .Data.Pages.ByTitle }}
++ {{ range .Pages.ByLength }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Title
+
+{{< code file="layouts/partials/by-title.html" >}}
+<ul>
+ <!-- ranges through content in ascending order according to the "title" field set in front matter -->
- {{ range .Data.Pages.ByLinkTitle }}
++ {{ range .Pages.ByTitle }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Link Title
+
+{{< code file="layouts/partials/by-link-title.html" >}}
+<ul>
+ <!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
- {{ range (.Data.Pages.ByParam "rating") }}
++ {{ range .Pages.ByLinkTitle }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Parameter
+
+Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
+
+{{< code file="layouts/partials/by-rating.html" >}}
+<!-- Ranges through content according to the "rating" field set in front matter -->
- {{ range (.Data.Pages.ByParam "author.last_name") }}
++{{ range (.Pages.ByParam "rating") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+If the targeted front matter field is nested beneath another field, you can access the field using dot notation.
+
+{{< code file="layouts/partials/by-nested-param.html" >}}
- {{ range .Data.Pages.ByDate.Reverse }}
++{{ range (.Pages.ByParam "author.last_name") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+### Reverse Order
+
+Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
+
+{{< code file="layouts/partials/by-date-reverse.html" >}}
+<ul>
- {{ range .Data.Pages.GroupBy "Section" }}
++ {{ range .Pages.ByDate.Reverse }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+## Group Content
+
+Hugo provides some functions for grouping pages by Section, Type, Date, etc.
+
+### By Page Field
+
+{{< code file="layouts/partials/by-page-field.html" >}}
+<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
- {{ range .Data.Pages.GroupBy "Section" }}
++{{ range .Pages.GroupBy "Section" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
+
+{{< code file="layouts/partials/by-page-field.html" >}}
+<!-- Groups content according to content section.-->
- {{ range .Data.Pages.GroupByDate "2006-01" }}
++{{ range .Pages.GroupBy "Section" }}
+<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
+{{ with $.Site.GetPage "section" .Key }}
+<h3>{{.Title}}</h3>
+{{ else }}
+<!-- If no _index.md is available, ".Key" defaults to the section title and filters to title casing -->
+<h3>{{ .Key | title }}</h3>
+{{ end }}
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Date
+
+{{< code file="layouts/partials/by-page-date.html" >}}
+<!-- Groups content by month according to the "date" field in front matter -->
- {{ range .Data.Pages.GroupByPublishDate "2006-01" }}
++{{ range .Pages.GroupByDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Publish Date
+
+{{< code file="layouts/partials/by-page-publish-date.html" >}}
+<!-- Groups content by month according to the "publishdate" field in front matter -->
- {{ range .Data.Pages.GroupByParam "param_key" }}
++{{ range .Pages.GroupByPublishDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page Parameter
+
+{{< code file="layouts/partials/by-page-param.html" >}}
+<!-- Groups content according to the "param_key" field in front matter -->
- {{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
++{{ range .Pages.GroupByParam "param_key" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page Parameter in Date Format
+
+The following template takes grouping by `date` a step further and uses Go's layout string. See the [`Format` function][] for more examples of how to use Go's layout string to format dates in Hugo.
+
+{{< code file="layouts/partials/by-page-param-as-date.html" >}}
+<!-- Groups content by month according to the "param_key" field in front matter -->
- {{ range (.Data.Pages.GroupBy "Section").Reverse }}
++{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### Reverse Key Order
+
+Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates.
+
+While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way.
+
+#### 1. Adding the Reverse Method
+
+```
- {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
++{{ range (.Pages.GroupBy "Section").Reverse }}
+```
+
+```
- {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
++{{ range (.Pages.GroupByDate "2006-01").Reverse }}
+```
+
+#### 2. Providing the Alternate Direction
+
+```
- {{ range .Data.Pages.GroupBy "Section" "desc" }}
++{{ range .Pages.GroupByDate "2006-01" "asc" }}
+```
+
+```
- {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
++{{ range .Pages.GroupBy "Section" "desc" }}
+```
+
+### Order Within Groups
+
+Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available.
+
+Here is the ordering for the example that follows:
+
+1. Content is grouped by month according to the `date` field in front matter.
+2. Groups are listed in ascending order (i.e., the oldest groups first)
+3. Pages within each respective group are ordered alphabetically according to the `title`.
+
+{{< code file="layouts/partials/by-group-by-page.html" >}}
- {{< code file="layouts/_default/.html" >}}
- {{ range where .Data.Pages "Section" "post" }}
++{{ range .Pages.GroupByDate "2006-01" "asc" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages.ByTitle }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+## Filter and Limiting Lists
+
+Sometimes you only want to list a subset of the available content. A common is to only display “Posts” on blog's homepage. You can accomplish this with the `where` function.
+
+### `where`
+
+`where` works in a similar manner to the [`where` keyword in SQL][wherekeyword]. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
+
+1. `array` *or* `slice of maps or structs`
+2. `key` *or* `field name`
+3. `match value`
+
- {{ range first 10 .Data.Pages }}
++{{< code file="layouts/_default/index.html" >}}
++{{ range where .Pages "Section" "post" }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+You can see more examples in the [functions documentation for `where`][wherefunction].
+
+### `first`
+
+`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
+
+1. `array` *or* `slice of maps or structs`
+2. `number of elements`
+
+{{< code file="layout/_default/section.html" >}}
- {{ range first 5 (where .Data.Pages "Section" "post").ByTitle }}
++{{ range first 10 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+{{< /code >}}
+
+### `first` and `where` Together
+
+Using `first` and `where` together can be very powerful:
+
+{{< code file="first-and-where-together.html" >}}
+<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts -->
++{{ range first 5 (where .Pages "Section" "post").ByTitle }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+[base]: /templates/base/
+[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
+[directorystructure]: /getting-started/directory-structure/
+[`Format` function]: /functions/format/
+[front matter]: /content-management/front-matter/
+[getpage]: /functions/getpage/
+[homepage]: /templates/homepage/
+[homepage]: /templates/homepage/
+[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
+[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
+[rss]: /templates/rss/
+[sections]: /content-management/sections/
+[sectiontemps]: /templates/section-templates/
+[sitevars]: /variables/site/
+[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates/
+[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates/
+[taxvars]: /variables/taxonomy/
+[views]: /templates/views/
+[wherefunction]: /functions/where/
+[wherekeyword]: https://www.techonthenet.com/sql/where.php
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Ordere and Grouping Hugo Lists
+linktitle: List Ordering and Grouping
+description: You can group or order your content in both your templating and content front matter.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: []
+menu:
+ docs:
+ parent: "templates"
+ weight: 27
+weight: 27
+sections_weight: 27
+draft: true
+aliases: [/templates/ordering/,/templates/grouping/]
+toc: true
+notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12.
+---
+
+In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page.
+
+## Example List Templates
+
+### Section Template
+
+This list template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary."
+
+{{< code file="layouts/section/post.html" >}}
+{{ partial "header.html" . }}
+{{ partial "subheader.html" . }}
+
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ <ul id="list">
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "li"}}
+ {{ end }}
+ </ul>
+ </div>
+</section>
+{{ partial "footer.html" . }}
+{{< /code >}}
+
+### Taxonomy Template
+
+{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
+{{ define "main" }}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
- {{ range .Data.Pages }}
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{ end }}
+{{< /code >}}
+
+## Order Content
+
+Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/)..
+
+Here are a variety of different ways you can order the content items in
+your list templates:
+
+### Default: Weight > Date
+
+{{< code file="layouts/partials/order-default.html" >}}
+<ul class="pages">
- {{ range .Data.Pages.ByWeight }}
++ {{ range .Pages }}
+ <li>
+ <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
+ <time>{{ .Date.Format "Mon, Jan 2, 2006" }}</time>
+ </li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+### By Weight
+
+{{< code file="layouts/partials/by-weight.html" >}}
- {{ range .Data.Pages.ByDate }}
++{{ range .Pages.ByWeight }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Date
+
+{{< code file="layouts/partials/by-date.html" >}}
- {{ range .Data.Pages.ByPublishDate }}
++{{ range .Pages.ByDate }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Publish Date
+
+{{< code file="layouts/partials/by-publish-date.html" >}}
- {{ range .Data.Pages.ByExpiryDate }}
++{{ range .Pages.ByPublishDate }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Expiration Date
+
+{{< code file="layouts/partials/by-expiry-date.html" >}}
- {{ range .Data.Pages.ByLastmod }}
++{{ range .Pages.ByExpiryDate }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Last Modified Date
+
+{{< code file="layouts/partials/by-last-mod.html" >}}
- {{ range .Data.Pages.ByLength }}
++{{ range .Pages.ByLastmod }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Length
+
+{{< code file="layouts/partials/by-length.html" >}}
- {{ range .Data.Pages.ByTitle }}
++{{ range .Pages.ByLength }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+
+### By Title
+
+{{< code file="layouts/partials/by-title.html" >}}
- {{ range .Data.Pages.ByLinkTitle }}
++{{ range .Pages.ByTitle }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Link Title
+
+{{< code file="layouts/partials/by-link-title.html" >}}
- {{ range (.Data.Pages.ByParam "rating") }}
++{{ range .Pages.ByLinkTitle }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+{{ end }}
+{{< /code >}}
+
+### By Parameter
+
+Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
+
+The below example sorts a list of posts by their rating.
+
+{{< code file="layouts/partials/by-rating.html" >}}
- {{ range (.Data.Pages.ByParam "author.last_name") }}
++{{ range (.Pages.ByParam "rating") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+If the front matter field of interest is nested beneath another field, you can
+also get it:
+
+{{< code file="layouts/partials/by-nested-param.html" >}}
- {{ range .Data.Pages.ByDate.Reverse }}
++{{ range (.Pages.ByParam "author.last_name") }}
+ <!-- ... -->
+{{ end }}
+{{< /code >}}
+
+### Reverse Order
+
+Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
+
+{{< code file="layouts/partials/by-date-reverse.html" >}}
- {{ range .Data.Pages.GroupBy "Section" }}
++{{ range .Pages.ByDate.Reverse }}
+<li>
+<a href="{{ .Permalink }}">{{ .Title }}</a>
+<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+</li>
+{{ end }}
+{{< /code >}}
+
+## Group Content
+
+Hugo provides some functions for grouping pages by Section, Type, Date, etc.
+
+### By Page Field
+
+{{< code file="layouts/partials/by-page-field.html" >}}
- {{ range .Data.Pages.GroupByDate "2006-01" }}
++{{ range .Pages.GroupBy "Section" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page date
+
+{{< code file="layouts/partials/by-page-date.html" >}}
- {{ range .Data.Pages.GroupByPublishDate "2006-01" }}
++{{ range .Pages.GroupByDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page publish date
+
+{{< code file="layouts/partials/by-page-publish-date.html" >}}
- {{ range .Data.Pages.GroupByParam "param_key" }}
++{{ range .Pages.GroupByPublishDate "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page Param
+
+{{< code file="layouts/partials/by-page-param.html" >}}
- {{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
++{{ range .Pages.GroupByParam "param_key" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### By Page Param in Date Format
+
+{{< code file="layouts/partials/by-page-param-as-date.html" >}}
- {{ range (.Data.Pages.GroupBy "Section").Reverse }}
++{{ range .Pages.GroupByParamDate "param_key" "2006-01" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### Reverse Key Order
+
+The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates.
+
+While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax.
+
+#### Reverse Method
+
+```
- {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
++{{ range (.Pages.GroupBy "Section").Reverse }}
+```
+
+```
- {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
++{{ range (.Pages.GroupByDate "2006-01").Reverse }}
+```
+
+
+#### Provide the Alternate Direction
+
+```
- {{ range .Data.Pages.GroupBy "Section" "desc" }}
++{{ range .Pages.GroupByDate "2006-01" "asc" }}
+```
+
+```
- {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
++{{ range .Pages.GroupBy "Section" "desc" }}
+```
+
+### Order Within Groups
+
+Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available.
+
+In the following example, groups are ordered chronologically and then content
+within each group is ordered alphabetically by title.
+
+{{< code file="layouts/partials/by-group-by-page.html" >}}
- {{< code file="layouts/_default/.html" >}}
- {{ range where .Data.Pages "Section" "post" }}
++{{ range .Pages.GroupByDate "2006-01" "asc" }}
+<h3>{{ .Key }}</h3>
+<ul>
+ {{ range .Pages.ByTitle }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+## Filter and Limiting Lists
+
+Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function.
+
+### `where`
+
+`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments:
+
+1. `array` or a `slice of maps or structs`
+2. `key` or `field name`
+3. `match value`
+
- {{ range first 10 .Data.Pages }}
++{{< code file="layouts/_default/index.html" >}}
++{{ range where .Pages "Section" "post" }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+### `first`
+
+`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments:
+
+1. `array` or `slice of maps or structs`
+2. `number of elements`
+
+{{< code file="layout/_default/section.html" >}}
- {{ range first 5 (where .Data.Pages "Section" "post") }}
++{{ range first 10 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+{{< /code >}}
+
+### `first` and `where` Together
+
+Using `first` and `where` together can be very powerful:
+
+{{< code file="first-and-where-together.html" >}}
++{{ range first 5 (where .Pages "Section" "post") }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+
+[views]: /templates/views/
--- /dev/null
- 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 }}`.
+---
+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*.
- * `{{ $paginator := .Paginate (where .Data.Pages "Type" "post") 5 }}`
++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 .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 }}`
- {{ range (.Paginate (.Data.Pages.GroupByDate "2006")).PageGroups }}
++* `{{ $paginator := .Paginate (where .Pages "Type" "post") 5 }}`
+
+It is also possible to use the `GroupBy` functions in combination with pagination:
+
+```
- {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
++{{ range (.Paginate (.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 .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
+
+`URL`
+: The relative URL to the current pager
+
+`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
- {{range .Data.Pages}}
+---
+title: Robots.txt File
+linktitle: Robots.txt
+description: Hugo can generate a customized robots.txt in the same way as any other template.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [robots,search engines]
+menu:
+ docs:
+ parent: "templates"
+ weight: 165
+weight: 165
+sections_weight: 165
+draft: false
+aliases: [/extras/robots-txt/]
+toc: false
+---
+
+To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything:
+
+```
+User-agent: *
+```
+
+## Robots.txt Template Lookup Order
+
+The [lookup order][lookup] for the `robots.txt` template is as follows:
+
+* `/layouts/robots.txt`
+* `/themes/<THEME>/layouts/robots.txt`
+
+{{% note %}}
+If you do not want Hugo to create a default `robots.txt` or leverage the `robots.txt` template, you can hand code your own and place the file in `static`. Remember that everything in the [static directory](/getting-started/directory-structure/) is copied over as-is when Hugo builds your site.
+{{% /note %}}
+
+## Robots.txt Template Example
+
+The following is an example `robots.txt` layout:
+
+{{< code file="layouts/robots.txt" download="robots.txt" >}}
+User-agent: *
+
++{{range .Pages}}
+Disallow: {{.RelPermalink}}
+{{end}}
+{{< /code >}}
+
+This template disallows all the pages of the site by creating one `Disallow` entry for each page.
+
+[config]: /getting-started/configuration/
+[lookup]: /templates/lookup-order/
+[robots]: http://www.robotstxt.org/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: RSS Templates
+linktitle: RSS Templates
+description: Hugo ships with its own RSS 2.0 template that requires almost no configuration, or you can create your own RSS templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [rss, xml, templates]
+categories: [templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 150
+weight: 150
+sections_weight: 150
+draft: false
+aliases: [/templates/rss/]
+toc: true
+---
+
+## RSS Template Lookup Order
+
+See [Template Lookup Order](/templates/lookup-order/) for the complete reference.
+
+{{% note "Hugo Ships with an RSS Template" %}}
+Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml). The embedded template will be sufficient for most use cases.
+{{% /note %}}
+
+RSS pages are of the type `Page` and have all the [page variables](/variables/page/) available to use in the templates.
+
+### Section RSS
+
+A [section’s][section] RSS will be rendered at `/<SECTION>/index.xml` (e.g., http://spf13.com/project/index.xml).
+
+Hugo provides the ability for you to define any RSS type you wish and can have different RSS files for each section and taxonomy.
+
+## Lookup Order for RSS Templates
+
+The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`).
+
+{{< datatable-filtered "output" "layouts" "OutputFormat == RSS" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+## Configure RSS
+
+By default, Hugo will create an unlimited number of RSS entries. You can limit the number of articles included in the built-in RSS templates by assigning a numeric value to `rssLimit:` field in your project's [`config` file][config].
+
+The following values will also be included in the RSS output if specified in your site’s configuration:
+
+```toml
+languageCode = "en-us"
+copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License."
+
+[author]
+ name = "My Name Here"
+```
+
+## The Embedded rss.xml
+
+This is the default RSS template that ships with Hugo. It adheres to the [RSS 2.0 Specification][RSS 2.0].
+
+```xml
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>{{ if eq .Title .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
+ <link>{{ .Permalink }}</link>
+ <description>Recent content {{ if ne .Title .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
+ <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
+ <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
+ <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
+ <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
+ <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
+ <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
+ {{ with .OutputFormats.Get "RSS" }}
+ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
+ {{ end }}
++ {{ range .Pages }}
+ <item>
+ <title>{{ .Title }}</title>
+ <link>{{ .Permalink }}</link>
+ <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
+ {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
+ <guid>{{ .Permalink }}</guid>
+ <description>{{ .Summary | html }}</description>
+ </item>
+ {{ end }}
+ </channel>
+</rss>
+```
+
+{{% warning "XML Header" %}}
+Hugo will automatically add the following header line to this file on render. Please do *not* include this in the template as it's not valid HTML.
+```
+<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
+```
+{{% /warning %}}
+
+## Reference your RSS Feed in `<head>`
+
+In your `header.html` template, you can specify your RSS feed in your `<head></head>` tag using Hugo's [Output Formats][Output Formats] like this:
+
+```go-html-template
+{{ range .AlternativeOutputFormats -}}
+ {{ printf `<link rel="%s" type="%s+%s" href="%s" title="%s" />` .Rel .MediaType.Type .MediaType.Suffix .Permalink $.Site.Title | safeHTML }}
+{{ end -}}
+```
+
+If you only want the RSS link, you can query the formats:
+
+```go-html-template
+{{ with .OutputFormats.Get "rss" -}}
+ {{ printf `<link rel="%s" type="%s+%s" href="%s" title="%s" />` .Rel .MediaType.Type .MediaType.Suffix .Permalink $.Site.Title | safeHTML }}
+{{ end -}}
+```
+
+Either of the two snippets above will generate the below `link` tag on the site homepage for RSS output:
+
+```html
+<link rel="alternate" type="application/rss+xml" href="https://example.com/index.xml" title="Site Title">
+```
+
+_We are assuming `BaseURL` to be `https://example.com/` and `$.Site.Title` to be `"Site Title"` in this example._
+
+[config]: /getting-started/configuration/
+[embedded]: #the-embedded-rss-xml
+[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
+[section]: /content-management/sections/
+[Output Formats]: /templates/output-formats/#link-to-output-formats
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Sitemap Template
+# linktitle: Sitemap
+description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [sitemap, xml, templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 160
+weight: 160
+sections_weight: 160
+draft: false
+aliases: [/layout/sitemap/,/templates/sitemap/]
+toc: false
+---
+
+A single Sitemap template is used to generate the `sitemap.xml` file.
+Hugo automatically comes with this template file. *No work is needed on
+the users' part unless they want to customize `sitemap.xml`.*
+
+A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones:
+
+`.Sitemap.ChangeFreq`
+: The page change frequency
+
+`.Sitemap.Priority`
+: The priority of the page
+
+`.Sitemap.Filename`
+: The sitemap filename
+
+If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo.
+
+## Hugo’s sitemap.xml
+
+This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html).
+
+```
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
- [pagevars]: /variables/page/
++ {{ range .Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>{{ if not .Lastmod.IsZero }}
+ <lastmod>{{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ end }}{{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }}
+ <priority>{{ .Sitemap.Priority }}</priority>{{ end }}
+ </url>
+ {{ end }}
+</urlset>
+```
+
+{{% note %}}
+Hugo will automatically add the following header line to this file
+on render. Please don't include this in the template as it's not valid HTML.
+
+`<?xml version="1.0" encoding="utf-8" standalone="yes" ?>`
+{{% /note %}}
+
+## Configure `sitemap.xml`
+
+Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.:
+
+{{< code-toggle file="config" >}}
+[sitemap]
+ changefreq = "monthly"
+ priority = 0.5
+ filename = "sitemap.xml"
+{{</ code-toggle >}}
+
+The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time.
+
++[pagevars]: /variables/page/
--- /dev/null
- If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Data.Pages` as such:
+---
+title: Taxonomy Templates
+# linktitle:
+description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [taxonomies,metadata,front matter,terms,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 50
+weight: 50
+sections_weight: 50
+draft: false
+aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
+toc: true
+---
+
+<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND
+https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.-->
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
+
+Hugo provides multiple ways to use taxonomies throughout your project templates:
+
+* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template)
+* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template)
+* List a single content's taxonomy terms within a [single page template][]
+
+## Taxonomy List Templates
+
+Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
+
+### Taxonomy List Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Taxonomy Terms Template
+
+### Taxonomy Terms Templates Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+### Taxonomy Methods
+
+A Taxonomy is a `map[string]WeightedPages`.
+
+.Get(term)
+: Returns the WeightedPages for a term.
+
+.Count(term)
+: The number of pieces of content assigned to this term.
+
+.Alphabetical
+: Returns an OrderedTaxonomy (slice) ordered by Term.
+
+.ByCount
+: Returns an OrderedTaxonomy (slice) ordered by number of entries.
+
+.Reverse
+: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.
+
+### OrderedTaxonomy
+
+Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
+
+```
+[]struct {
+ Name string
+ WeightedPages WeightedPages
+}
+```
+
+Each element of the slice has:
+
+.Term
+: The Term used.
+
+.WeightedPages
+: A slice of Weighted Pages.
+
+.Count
+: The number of pieces of content assigned to this term.
+
+.Pages
+: All Pages assigned to this term. All [list methods][renderlists] are available to this.
+
+## WeightedPages
+
+WeightedPages is simply a slice of WeightedPage.
+
+```
+type WeightedPages []WeightedPage
+```
+
+.Count(term)
+: The number of pieces of content assigned to this term.
+
+.Pages
+: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
+
+## Displaying custom metadata in Taxonomy Terms Templates
+
- {{ range .Data.Pages }}
++If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
+
+```
+<ul>
++ {{ range .Pages }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ {{ .Params.wikipedia }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+<!-- Begin /taxonomies/ordering/ -->
+
+## Order Taxonomies
+
+Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
+
+### Order Alphabetically Example
+
+```
+<ul>
+ {{ $data := .Data }}
+ {{ range $key, $value := .Data.Terms.Alphabetical }}
+ <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
+ {{ end }}
+</ul>
+```
+
+### Order by Popularity Example
+
+```
+<ul>
+ {{ $data := .Data }}
+ {{ range $key, $value := .Data.Terms.ByCount }}
+ <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
+ {{ end }}
+</ul>
+```
+
+### Order by Least Popular Example
+
+```
+<ul>
+ {{ $data := .Data }}
+ {{ range $key, $value := .Data.Terms.ByCount.Reverse }}
+ <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
+ {{ end }}
+</ul>
+```
+
+<!-- [See Also Taxonomy Lists](/templates/list/) -->
+
+## Order Content within Taxonomies
+
+Hugo uses both `date` and `weight` to order content within taxonomies.
+
+Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
+
+When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
+
+### Assign Weight
+
+Content can be assigned weight for each taxonomy that it's assigned to.
+
+```
++++
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+title = "foo"
+categories_weight = 44
++++
+Front Matter with weighted tags and categories
+```
+
+The convention is `taxonomyname_weight`.
+
+In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
+
+It has also been assigned the weight of 44 when rendering the 'd' category.
+
+With this the same piece of content can appear in different positions in different taxonomies.
+
+Currently taxonomies only support the default ordering of content which is weight -> date.
+
+<!-- Begin /taxonomies/templates/ -->
+
+There are two different templates that the use of taxonomies will require you to provide.
+
+Both templates are covered in detail in the templates section.
+
+A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
+
+A [taxonomy terms template](/templates/terms/) is a template used to
+generate the list of terms for a given template.
+
+<!-- Begin /taxonomies/displaying/ -->
+
+There are four common ways you can display the data in your
+taxonomies in addition to the automatic taxonomy pages created by hugo
+using the [list templates](/templates/list/):
+
+1. For a given piece of content, you can list the terms attached
+2. For a given piece of content, you can list other content with the same
+ term
+3. You can list all terms for a taxonomy
+4. You can list all taxonomies (with their terms)
+
+## Display a Single Piece of Content's Taxonomies
+
+Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.
+
+Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`).
+
+### Example: List Tags in a Single Page Template
+
+```
+<ul id="tags">
+ {{ range .Params.tags }}
+ <li><a href="{{ "/tags/" | relLangURL }}{{ . | urlize }}">{{ . }}</a> </li>
+ {{ end }}
+</ul>
+```
+
+If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
+
+To list such taxonomies, use the following:
+
+### Example: Comma-delimit Tags in a Single Page Template
+
+```
+{{ if .Params.directors }}
+ <strong>Director{{ if gt (len .Params.directors) 1 }}s{{ end }}:</strong>
+ {{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}<a href="{{ "directors/" | relURL }}{{ . | urlize }}">{{ . }}</a>{{ end }}
+{{ end }}
+```
+
+Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
+
+## List Content with the Same Taxonomy Term
+
+If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
+
+### Example: Showing Content in Same Series
+
+```
+<ul>
+ {{ range .Site.Taxonomies.series.golang }}
+ <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+## List All content in a Given taxonomy
+
+This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
+
+### Example: Grouping "Featured" Content
+
+```
+<section id="menu">
+ <ul>
+ {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
+ <li> {{ $key }} </li>
+ <ul>
+ {{ range $taxonomy.Pages }}
+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+</section>
+```
+
+## Render a Site's Taxonomies
+
+If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
+
+This may take the form of a tag cloud, a menu, or simply a list.
+
+The following example displays all terms in a site's tags taxonomy:
+
+### Example: List All Site Tags
+
+```
+<ul id="all-tags">
+ {{ range $name, $taxonomy := .Site.Taxonomies.tags }}
+ <li><a href="{{ "/tags/" | relLangURL }}{{ $name | urlize }}">{{ $name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+### Example: List All Taxonomies, Terms, and Assigned Content
+
+This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
+
+{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
+<section>
+ <ul id="all-taxonomies">
+ {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
+ <li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
+ <ul>
+ {{ range $key, $value := $taxonomy }}
+ <li> {{ $key }} </li>
+ <ul>
+ {{ range $value.Pages }}
+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+ </li>
+ {{ end }}
+ </ul>
+</section>
+{{< /code >}}
+
+## `.Site.GetPage` for Taxonomies
+
+Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above:
+
+{{< code file="links-to-all-tags" >}}
+<ul class="tags">
+ {{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }}
+ <li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
+ {{ end }}
+</ul>
+{{< /code >}}
+
+<!--### `.Site.GetPage` Taxonomy List Example
+
+### `.Site.GetPage` Taxonomy Terms Example -->
+
+
+[delimit]: /functions/delimit/
+[getpage]: /functions/getpage/
+[lists]: /templates/lists/
+[renderlists]: /templates/lists/
+[single page template]: /templates/single-page-templates/
+[sitevars]: /variables/site/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Template Debugging
+# linktitle: Template Debugging
+description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts.
+godocref: http://golang.org/pkg/fmt/
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [debugging,troubleshooting]
+menu:
+ docs:
+ parent: "templates"
+ weight: 180
+weight: 180
+sections_weight: 180
+draft: false
+aliases: []
+toc: false
+---
+
+Here are some snippets you can add to your template to answer some common questions.
+
+These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](http://golang.org/pkg/fmt/).
+
+## What Variables are Available in this Context?
+
+You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`.
+
+```
+{{ printf "%#v" $.Site }}
+```
+
+This will print out the value of `.Permalink`:
+
+
+```
+{{ printf "%#v" .Permalink }}
+```
+
+
+This will print out a list of all the variables scoped to the current context
+(`.`, aka ["the dot"][tempintro]).
+
+
+```
+{{ printf "%#v" . }}
+```
+
+
+When developing a [homepage][], what does one of the pages you're looping through look like?
+
+```
- {{% note "`.Data.Pages` on the Homepage" %}}
- `.Data.Pages` on the homepage is equivalent to `.Site.Pages`.
++{{ range .Pages }}
+ {{/* The context, ".", is now each one of the pages as it goes through the loop */}}
+ {{ printf "%#v" . }}
+{{ end }}
+```
+
- [tempintro]: /templates/introduction/
++{{% note "`.Pages` on the Homepage" %}}
++`.Pages` on the homepage is equivalent to `.Site.RegularPages`.
+{{% /note %}}
+
+## Why Am I Showing No Defined Variables?
+
+Check that you are passing variables in the `partial` function:
+
+```
+{{ partial "header" }}
+```
+
+This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro].
+
+```
+{{ partial "header" . }}
+```
+
+The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro].
+
+[homepage]: /templates/homepage/
++[tempintro]: /templates/introduction/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Content View Templates
+# linktitle: Content Views
+description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [views]
+menu:
+ docs:
+ parent: "templates"
+ weight: 70
+weight: 70
+sections_weight: 70
+draft: false
+aliases: []
+toc: true
+---
+
+These alternative **content views** are especially useful in [list templates][lists].
+
+The following are common use cases for content views:
+
+* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
+* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
+
+## Create a Content View
+
+To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
+
+```
+ ▾ layouts/
+ ▾ post/
+ li.html
+ single.html
+ summary.html
+ ▾ project/
+ li.html
+ single.html
+ summary.html
+```
+
+Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
+
+
+```
+▾ layouts/
+ ▾ _default/
+ li.html
+ single.html
+ summary.html
+```
+
+## Which Template Will be Rendered?
+
+The following is the [lookup order][lookup] for content views:
+
+1. `/layouts/<TYPE>/<VIEW>.html`
+2. `/layouts/_default/<VIEW>.html`
+3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
+4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
+
+## Example: Content View Inside a List
+
+The following example demonstrates how to use content views inside of your [list templates][lists].
+
+### `list.html`
+
+In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
+
+{{< code file="layouts/_default/list.html" download="list.html" >}}
+<main id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
++ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</main>
+{{< /code >}}
+
+### `summary.html`
+
+Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
+
+{{< code file="layouts/_default/summary.html" download="summary.html" >}}
+<article class="post">
+ <header>
+ <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
+ <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
+ </header>
+ {{ .Summary }}
+ <footer>
+ <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
+ </footer>
+</article>
+{{< /code >}}
+
+### `li.html`
+
+Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
+
+{{< code file="layouts/_default/li.html" download="li.html" >}}
+<li>
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+</li>
+{{< /code >}}
+
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[pagevars]: /variables/page/
+[render]: /functions/render/
+[single]: /templates/single-page-templates/
+[spf]: http://spf13.com
+[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
+[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
+[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
+[summaries]: /content-management/summaries/
+[taxonomylists]: /templates/taxonomy-templates/
--- /dev/null
- title: Menu Variables
- linktitle: Menu Variables
- description: A menu entry in a menu template has specific variables and functions to make menu management easier.
+---
- The [menu template][] has the following properties:
++title: Menu Entry Properties
++linktitle: Menu Entry Properties
++description: A menu entry in a menu-template has specific variables and functions to make menu management easier.
+date: 2017-03-12
+publishdate: 2017-03-12
+lastmod: 2017-03-12
+categories: [variables and params]
+keywords: [menus]
+draft: false
+menu:
+ docs:
+ title: "variables defined by a menu entry"
+ parent: "variables"
+ weight: 50
+weight: 50
+sections_weight: 50
+aliases: [/variables/menu/]
+toc: false
+---
+
- .URL
- : string
-
- .Name
- : string
++A **menu entry** has the following properties available that can be used in a
++[menu template][menu-template].
+
- .Title
- : string
++## Menu Entry Variables
+
- This is a link title, meant to be used in `title`-Attributes of the menu's `<a>`-tags.
- By default it returns `.Page.LinkTitle`, as long as the menu entry was created
- through the page's front matter and not through the site config.
- Setting it explicitly in the site config or the page's front matter overrides this behaviour.
++.Menu
++: _string_ <br />
++Name of the **menu** that contains this **menu entry**.
+
- : [Page Object](/variables/page/)
++.URL
++: _string_ <br />
++URL that the menu entry points to. The `url` key, if set for the menu entry,
++sets this value. If that key is not set, and if the menu entry is set in a page
++front-matter, this value defaults to the page's `.RelPermalink`.
+
+.Page
- The `.Page` variable holds a reference to the page.
- It's only set when the menu entry is created from the page's front matter,
- not when it's created from the site config.
-
-
- .Menu
- : string
++: _\*Page_ <br />
++Reference to the [page object][page-object] associated with the menu entry. This
++will be non-nil if the menu entry is set via a page's front-matter and not via
++the site config.
+
- : string
++.Name
++: _string_ <br />
++Name of the menu entry. The `name` key, if set for the menu entry, sets
++this value. If that key is not set, and if the menu entry is set in a page
++front-matter, this value defaults to the page's `.LinkTitle`.
+
+.Identifier
- : template.HTML
++: _string_ <br />
++Value of the `identifier` key if set for the menu entry. This value must be
++unique for each menu entry. **It is necessary to set a unique identifier
++manually if two or more menu entries have the same `.Name`.**
+
+.Pre
- : template.HTML
++: _template.HTML_ <br />
++Value of the `pre` key if set for the menu entry. This value typically contains
++a string representing HTML.
+
+.Post
- : int
++: _template.HTML_ <br />
++Value of the `post` key if set for the menu entry. This value typically contains
++a string representing HTML.
+
+.Weight
- : string
++: _int_ <br />
++Value of the `weight` key if set for the menu entry. If that key is not set,
++and if the menu entry is set in a page front-matter, this value defaults to the
++page's `.Weight`.
+
+.Parent
- : Menu
++: _string_ <br />
++Name (or Identifier if present) of this menu entry's parent **menu entry**. The
++`parent` key, if set for the menu entry, sets this value. If this key is set,
++this menu entry nests under that parent entry, else it nests directly under the
++`.Menu`.
+
+.Children
- [menu template]: /templates/menu-templates/
++: _Menu_ <br />
++This value is auto-populated by Hugo. It is a collection of children menu
++entries, if any, under the current menu entry.
++
++## Menu Entry Functions
++
++Menus also have the following functions available:
++
++[.HasChildren](/functions/haschildren/)
++: _boolean_ <br />
++Returns `true` if `.Children` is non-nil.
++
++.KeyName
++: _string_ <br />
++Returns the `.Identifier` if present, else returns the `.Name`.
++
++.IsEqual
++: _boolean_ <br />
++Returns `true` if the two compared menu entries represent the same menu entry.
++
++.IsSameResource
++: _boolean_ <br />
++Returns `true` if the two compared menu entries have the same `.URL`.
++
++.Title
++: _string_ <br />
++Link title, meant to be used in the `title` attribute of a menu entry's
++`<a>`-tags. Returns the menu entry's `title` key if set. Else, if the menu
++entry was created through a page's front-matter, it returns the page's
++`.LinkTitle`. Else, it just returns an empty string.
++
++## Other Menu-related Functions
++
++Additionally, here are some relevant methods available to menus on a page:
++
++.IsMenuCurrent
++: _(menu string, menuEntry *MenuEntry ) boolean_ <br />
++See [`.IsMenuCurrent` method](/functions/ismenucurrent/).
++
++.HasMenuCurrent
++: _(menu string, menuEntry *MenuEntry) boolean_ <br />
++See [`.HasMenuCurrent` method](/functions/hasmenucurrent/).
++
+
++[menu-template]: /templates/menu-templates/
++[page-object]: /variables/page/
--- /dev/null
- : a collection of associated pages. This value will be `nil` for regular content pages. `.Pages` is an alias for `.Data.Pages`.
+---
+title: Page Variables
+linktitle:
+description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [variables and params]
+keywords: [pages]
+draft: false
+menu:
+ docs:
+ title: "variables defined by a page"
+ parent: "variables"
+ weight: 20
+weight: 20
+sections_weight: 20
+aliases: [/variables/page/]
+toc: true
+---
+
+The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself.
+
+{{% note "`.Scratch`" %}}
+See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
+{{% /note %}}
+
+## Page Variables
+
+.AlternativeOutputFormats
+: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's `<head>`. (See [Output Formats](/templates/output-formats/).)
+
+.Content
+: the content itself, defined below the front matter.
+
+.Data
+: the data specific to this type of page.
+
+.Date
+: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`.
+
+.Description
+: the description for the page.
+
+.Dir
+: the path of the folder containing this content file. The path is relative to the `content` folder.
+
+.Draft
+: a boolean, `true` if the content is marked as a draft in the front matter.
+
+.ExpiryDate
+: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`.
+
+.File
+: filesystem-related data for this content file. See also [File Variables][].
+
+.FuzzyWordCount
+: the approximate number of words in the content.
+
+.Hugo
+: see [Hugo Variables](/variables/hugo/).
+
+.IsHome
+: `true` in the context of the [homepage](/templates/homepage/).
+
+.IsNode
+: always `false` for regular content pages.
+
+.IsPage
+: always `true` for regular content pages.
+
+.IsTranslated
+: `true` if there are translations to display.
+
+.Keywords
+: the meta keywords for the content.
+
+.Kind
+: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
+
+.Lang
+: language taken from the language extension notation.
+
+.Language
+: a language object that points to the language's definition in the site
+`config`.
+
+.Lastmod
+: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter.
+
+ - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used.
+ - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead.
+
+See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
+
+.LinkTitle
+: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
+
+.Next
+: pointer to the following content (based on the `publishdate` field in front matter).
+
+.NextInSection
+: pointer to the following content within the same section (based on `publishdate` field in front matter).
+
+.OutputFormats
+: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)
+
+.Pages
++: a collection of associated pages. `.Pages` is an alias for
++ `.Data.Pages`. This value will be `nil` within the context of
++ regular content pages.
+
+.Permalink
+: the Permanent link for this page; see [Permalinks](/content-management/urls/)
+
+.Plain
+: the Page content stripped of HTML tags and presented as a string.
+
+.PlainWords
+: the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice.
+
+.Prev
+: Pointer to the previous content (based on `publishdate` in front matter).
+
+.PrevInSection
+: Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`.
+
+.PublishDate
+: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`.
+
+.RSSLink
+: link to the taxonomies' RSS link.
+
+.RawContent
+: raw markdown content without the front matter. Useful with [remarkjs.com](
+http://remarkjs.com)
+
+.ReadingTime
+: the estimated time, in minutes, it takes to read the content.
+
+.Ref
+: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
+
+.RelPermalink
+: the relative permanent link for this page.
+
+.RelRef
+: returns the relative permalink for a given reference (e.g., `RelRef
+"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
+
+.Site
+: see [Site Variables](/variables/site/).
+
+.Summary
+: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code><!--more--></code> at the appropriate place in the content page. See [Content Summaries](/content-management/summaries/) for more details.
+
+.TableOfContents
+: the rendered [table of contents](/content-management/toc/) for the page.
+
+.Title
+: the title for this page.
+
+.Translations
+: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
+
+.Truncated
+: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information.
+
+.Type
+: the [content type](/content-management/types/) of the content (e.g., `post`).
+
+.URL
+: the URL for the page relative to the web root. Note that a `url` set directly in front matter overrides the default relative URL for the rendered page.
+
+.UniqueID
+: the MD5-checksum of the content file's path.
+
+.Weight
+: assigned weight (in the front matter) to this content, used in sorting.
+
+.WordCount
+: the number of words in the content.
+
+## Section Variables and Methods
+
+Also see [Sections](/content-management/sections/).
+
+{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
+
+## Page-level Params
+
+Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
+
+```
+---
+title: My First Post
+date: 2017-02-20T15:26:23-06:00
+categories: [one]
+tags: [two,three,four]
+```
+
+With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
+
+* `.Params.tags`
+* `.Params.categories`
+
+{{% note "Casing of Params" %}}
+Page-level `.Params` are *only* accessible in lowercase.
+{{% /note %}}
+
+The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
+
+```
+---
+...
+affiliatelink: "http://www.my-book-link.here"
+recommendedby: "My Mother"
+...
+---
+```
+
+These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
+
+Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
+
+{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
+<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
+<p>It was recommended by {{ .Params.recommendedby }}.</p>
+{{< /code >}}
+
+This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
+
+{{< output file="yourbaseurl/review/book01/index.html" >}}
+<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
+<p>It was recommended by my Mother.</p>
+{{< /output >}}
+
+{{% note %}}
+See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
+{{% /note %}}
+
+### The `.Param` Method
+
+In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image):
+
+```
+{{ $.Param "header_image" }}
+```
+
+The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`).
+
+### Access Nested Fields in Front Matter
+
+When front matter contains nested fields like the following:
+
+```
+---
+author:
+ given_name: John
+ family_name: Feminella
+ display_name: John Feminella
+---
+```
+`.Param` can access these fields by concatenating the field names together with a dot:
+
+```
+{{ $.Param "author.display_name" }}
+```
+
+If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case:
+
+```
+---
+favorites.flavor: vanilla
+favorites:
+ flavor: chocolate
+---
+```
+
+The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`:
+
+```
+{{ $.Param "favorites.flavor" }}
+=> vanilla
+```
+
+[gitinfo]: /variables/git/
+[File Variables]: /variables/files/
--- /dev/null
- {{ range .Data.Pages }}
+---
+title: Base 模板 and Blocks
+linktitle:
+description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
+godocref: https://golang.org/pkg/text/template/#example_Template_block
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates,fundamentals]
+keywords: [blocks,base]
+menu:
+ docs:
+ parent: "templates"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
+toc: true
+---
+
+The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
+
+{{< youtube QVOMCYitLEc >}}
+
+## Base Template Lookup Order
+
+The [lookup order][lookup] for base templates is as follows:
+
+1. `/layouts/section/<TYPE>-baseof.html`
+2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
+3. `/layouts/<TYPE>/baseof.html`
+4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/<THEME>/layouts/section/baseof.html`
+7. `/layouts/_default/<TYPE>-baseof.html`
+8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/<THEME>/layouts/_default/baseof.html`
+
+Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
+
+### Example Base Template Lookup Order
+
+As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
+
+Here is the lookup order for the `post` base template:
+
+1. `/layouts/section/post-baseof.html`
+2. `/themes/mytheme/layouts/section/post-baseof.html`
+3. `/layouts/post/baseof.html`
+4. `/themes/mytheme/layouts/post/baseof.html`
+5. `/layouts/section/baseof.html`
+6. `/themes/mytheme/layouts/section/baseof.html`
+7. `/layouts/_default/post-baseof.html`
+8. `/themes/mytheme/layouts/_default/post-baseof.html`
+9. `/layouts/_default/baseof.html`
+10. `/themes/mytheme/layouts/_default/baseof.html`
+
+## Define the Base Template
+
+The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
+
+{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
+<!DOCTYPE html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title>{{ block "title" . }}
+ <!-- Blocks may include default content. -->
+ {{ .Site.Title }}
+ {{ end }}</title>
+ </head>
+ <body>
+ <!-- Code that all your templates share, like a header -->
+ {{ block "main" . }}
+ <!-- The part of the page that begins to differ between templates -->
+ {{ end }}
+ {{ block "footer" . }}
+ <!-- More shared code, perhaps a footer but that can be overridden if need be in -->
+ {{ end }}
+ </body>
+</html>
+{{< /code >}}
+
+## Override the Base Template
+
+From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
+
+{{< code file="layouts/_default/list.html" download="list.html" >}}
+{{ define "main" }}
+ <h1>Posts</h1>
++ {{ range .Pages }}
+ <article>
+ <h2>{{ .Title }}</h2>
+ {{ .Content }}
+ </article>
+ {{ end }}
+{{ end }}
+{{< /code >}}
+
+This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
+
+{{% warning %}}
+Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
+
+```
+<!-- Seemingly harmless HTML comment..that will break your layout at build -->
+{{ define "main" }}
+...your code here
+{{ end }}
+```
+[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
+{{% /warning %}}
+
+The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
+
+{{< code file="layouts/_default/single.html" download="single.html" >}}
+{{ define "title" }}
+ <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
+ {{ .Title }} – {{ .Site.Title }}
+{{ end }}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+[hugolists]: /templates/lists
+[lookup]: /templates/lookup-order/
+[rendering the section]: /templates/section-templates/
+[singletemplate]: /templates/single-page-templates/
--- /dev/null
- HUGO_VERSION = "0.42.2"
+[build]
+publish = "public"
+command = "hugo"
+
+[context.production.environment]
- HUGO_VERSION = "0.42.2"
++HUGO_VERSION = "0.44"
+HUGO_ENV = "production"
+HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
+command = "hugo --enableGitInfo"
+
+[context.split1.environment]
- HUGO_VERSION = "0.42.2"
++HUGO_VERSION = "0.44"
+HUGO_ENV = "production"
+
+[context.deploy-preview]
+command = "hugo --buildFuture -b $DEPLOY_PRIME_URL"
+
+[context.deploy-preview.environment]
- HUGO_VERSION = "0.42.2"
++HUGO_VERSION = "0.44"
+
+[context.branch-deploy]
+command = "hugo -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy.environment]
++HUGO_VERSION = "0.44"
+
+[context.next.environment]
+HUGO_ENABLEGITINFO = "true"
+
--- /dev/null
- Theme for gohugo.io sites. More info to come.
++# GoHugo Sites Theme
++
++Theme for gohugo.io sites:
++* [https://gohugo.io/](https://gohugo.io/)
++* [https://themes.gohugo.io/](https://themes.gohugo.io/)
++
++More info to come.
--- /dev/null
- {{ $section_to_display := .Data.Pages }}
+{{ define "main" }}
++ {{ $section_to_display := .Pages }}
+ {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }}
+{{ end }}
--- /dev/null
- {{ $section_to_display := .Data.Pages }}
+{{/* {{ define "header" }}{{ partial "page-header" . }}{{ end }} */}}
+{{ define "main" }}
++{{ $section_to_display := .Pages }}
+<div class="w-100 ph4 pb5 pb6-ns pt1 pt3-ns">
+
+ <div class="flex">
+ <div class="dn db-l w-20">
+ {{ partial "nav-links-docs.html" . }}
+ </div>
+
+ <div class="w-100 w-80-l ph0 ph4-l">
+ <article class="w-100 nested-copy-line-height nested-links nested-img">
+ <h1 class="primary-color-dark f2">
+ {{ .Title }}
+ </h1>
+ </article>
+ <div class="pa3 pa4-ns w-100 v-top column-count-3-l column-gap-1-l">
+ {{ range $key, $value := .Data.Terms }}
+ <div class="break-inside-avoid-l nested-copy-line-height mb5">
+ <h2 class="f3">
+ <a href="{{ "/" | relLangURL }}{{ $.Data.Plural | urlize }}/{{ $key | urlize }}" class="link black hover-blue">
+ {{ $key }} <span class="f6 gray"> ↗</span>
+ </a>
+ </h2>
+ {{ range $value.Pages }}
+ <h3>
+ <a href="{{ .Permalink }}" class="link blue">
+ {{ .Title }}
+ </a>
+ </h3>
+ {{ end }}
+ </div>
+
+ {{ end }}
+
+ </div>
+
+
+
+
+ </div>
+
+ </div>
+
+
+
+
+</div>
+{{ end }}
--- /dev/null
- {{ range first 4 ( sort (where .Data.Pages "Section" "news") "Date" "desc" ) }}
+<section class="relative w-100 bg-black white">
+ <div class="flex flex-wrap w-90-l center center mw9">
+ <!-- <a href="/news/" class="link accent-color tr-ns f6 w-100 w-50-m w-10-l bg-animate hover-bg-accent-color hover-white pv3 pv4-l ph3 ph4-l dib">
+ Latest News:
+ </a> -->
++ {{ range first 4 ( sort (where .Pages "Section" "news") "Date" "desc" ) }}
+ <!-- only show 2 boxes on mobile -->
+ {{ $.Scratch.Add "i" 1 }}{{ $i := $.Scratch.Get "i" }}
+ <a href="{{ .URL }}" class="link lh-copy light-gray f6 w-100 w-50-m w-25-l bg-animate hover-bg-accent-color hover-white pv3 pv4-ns ph3 ph4-ns{{ if ge $i 3 }} dn dib-l{{ else }} dib{{ end }}">
+ <span class="f6 gray pb1 db">
+ {{ .Date.Format "January 2, 2006" }}
+ </span>
+ {{ .Params.description | markdownify | truncate 100 "…"}}
+ </a>
+ {{ end }}
+
+ </div>
+</section>
projects / brevno-suite / hugo / commitdiff
