--- /dev/null
- title: "{{ replace .TranslationBaseName "-" " " | title }}"
- date: {{ .Date }}
+---
- keywords: []
++linktitle: ""
+description: ""
++godocref: ""
++publishdate: ""
++lastmod: ""
+categories: []
- draft: true
- ---
++tags: []
++weight: 00
+slug: ""
+aliases: []
+toc: false
++---
--- /dev/null
--- /dev/null
++---
++linktitle: ""
++description: ""
++godocref: ""
++publishdate: ""
++lastmod: ""
++categories: [functions]
++tags: []
++ns: ""
++signature: []
++workson: []
++hugoversion: ""
++aliases: []
++relatedfuncs: []
++toc: false
++deprecated: false
++---
--- /dev/null
- hrefTargetBlank = true
+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 = "friendly"
+
+[outputs]
+home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
+section = [ "HTML", "RSS"]
+
+[mediaTypes]
+[mediaTypes."text/netlify"]
+suffix = ""
+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.35-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
+
+## 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/"
+
+ # 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"
--- /dev/null
- See what's coming next in the [Hugo roadmap][].
+---
+title: Hugo Features
+linktitle: Hugo Features
+description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+menu:
+ docs:
+ parent: "about"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/about/features]
+toc: true
+---
+
+## General
+
+* [Extremely fast][] build times (< 1 ms per page)
+* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
+* Renders changes on the fly with [LiveReload][] as you develop
+* [Powerful theming][]
+* [Host your site anywhere][hostanywhere]
+
+## Organization
+
+* Straightforward [organization for your projects][], including website sections
+* Customizable [URLs][]
+* Support for configurable [taxonomies][], including categories and tags
+* [Sort content][] as you desire through powerful template [functions][]
+* Automatic [table of contents][] generation
+* [Dynamic menu][] creation
+* [Pretty URLs][] support
+* [Permalink][] pattern support
+* Redirects via [aliases][]
+
+## Content
+
+* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
+* TOML, YAML, and JSON metadata support in [front matter][]
+* Customizable [homepage][]
+* Multiple [content types][]
+* Automatic and user defined [content summaries][]
+* [Shortcodes][] to enable rich content inside of Markdown
+* ["Minutes to Read"][pagevars] functionality
+* ["Wordcount"][pagevars] functionality
+
+## Additional Features
+
+* Integrated [Disqus][] comment support
+* Integrated [Google Analytics][] support
+* Automatic [RSS][] creation
+* Support for [Go][], [Amber], and [Ace][] HTML templates
+* [Syntax highlighting][] powered by [Pygments][]
+
- [Hugo roadmap]: /about/roadmap
+
+[Ace]: /templates/alternatives/
+[aliases]: /content-management/urls/#aliases
+[Amber]: https://github.com/eknkc/amber
+[content summaries]: /content-management/summaries/
+[content types]: /content-management/types/
+[Disqus]: https://disqus.com/
+[Dynamic menu]: /templates/menus/
+[Extremely fast]: https://github.com/bep/hugo-benchmark
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[Go]: http://golang.org/pkg/html/template/
+[Google Analytics]: https://google-analytics.com/
+[homepage]: /templates/homepage/
+[hostanywhere]: /hosting-and-deployment/
+[install]: /getting-started/installing/
+[LiveReload]: /getting-started/usage/
+[organization for your projects]: /getting-started/directory-structure/
+[pagevars]: /variables/page/
+[Permalink]: /content-management/urls/#permalinks
+[Powerful theming]: /themes/
+[Pretty URLs]: /content-management/urls/
+[Pygments]: http://pygments.org/
+[RSS]: /templates/rss/
+[Shortcodes]: /content-management/shortcodes/
+[sort content]: /templates/
+[supported formats]: /content-management/formats/
+[Syntax highlighting]: /tools/syntax-highlighting/
+[table of contents]: /content-management/toc/
+[taxonomies]: /content-management/taxonomies/
+[URLs]: /content-management/urls/
--- /dev/null
- {{< imgproc sunset Resize "300x" >}}
+---
+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:
+
+* http://hugotest.bep.is/
+* 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
+
+```html
+{{ 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
+
+```html
+{{ 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
+
+```html
+{{ $logo := .Resources.GetByPrefix "logo" }}
+{{ with $logo }}
+{{ end }}
+```
+
+#### Include Page Resource Content
+
+```html
+{{ 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 Fill "90x120 left" >}}
++{{< imgproc sunset Resize "300x" />}}
+
- {{< imgproc sunset Fill "90x120 right" >}}
++{{< imgproc sunset Fill "90x120 left" />}}
+
- {{< imgproc sunset Fit "90x90" >}}
++{{< imgproc sunset Fill "90x120 right" />}}
+
- {{< imgproc sunset Resize "300x q10" >}}
++{{< 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:
+
+```html
+{{</* 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
- Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub 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.
+---
+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:
+ main:
+ 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.
+
- [GitLab]: https://about.gitlab.com
++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/
+[Amazon S3]: http://aws.amazon.com/s3/
+[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/
+[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
+[contributing to it]: https://github.com/gohugoio/hugo
+[DreamHost]: http://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"
+[Google Cloud Storage]: http://cloud.google.com/storage/
+[Heroku]: https://www.heroku.com/
+[Jekyll]: http://jekyllrb.com/
+[Jekyll]: https://jekyllrb.com/
+[Middleman]: https://middlemanapp.com/
+[Middleman]: https://middlemanapp.com/
+[Nanoc]: http://nanoc.ws/
+[Nanoc]: https://nanoc.ws/
+[Netlify]: https://netlify.com
+[rackspace]: https://www.rackspace.com/cloud/files
+[static site generator]: /about/benefits/
+[Rackspace]: https://www.rackspace.com/cloud/files
+[static site generator]: /about/benefits/
+[Surge]: https://surge.sh
--- /dev/null
- {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}}
+---
+title: Archetypes
+linktitle: Archetypes
+description: Archetypes allow you to create new instances of content types and set default parameters from the command line.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [archetypes,generators,metadata,front matter]
+categories: ["content management"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 70
+ quicklinks:
+weight: 70 #rem
+draft: false
+aliases: [/content/archetypes/]
+toc: true
+---
+
+{{% note %}}
+This section is outdated, see https://github.com/gohugoio/hugoDocs/issues/11
+{{% /note %}}
+{{% todo %}}
+See above
+{{% /todo %}}
+
+## What are Archetypes?
+
+**Archetypes** are content files in the [archetypes directory][] of your project that contain preconfigured [front matter][] for your website's [content types][]. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the `hugo new` command.
+
+{{< youtube bcme8AzVh6o >}}
+
+The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
+
+```
+hugo new <content-section>/<file-name.md>
+```
+
+We can use this pattern to create a new `.md` file in the `posts` section:
+
+{{< code file="archetype-example.sh" >}}
+hugo new posts/my-first-post.md
+{{< /code >}}
+
+{{% note "Override Content Type in a New File" %}}
+To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
+{{% /note %}}
+
+Running this command in a new site that does not have default or custom archetypes will create the following file:
+
+{{< output file="content/posts/my-first-post.md" >}}
++++
+date = "2017-02-01T19:20:04-07:00"
+title = "my first post"
+draft = true
++++
+{{< /output >}}
+
+{{% note %}}
+In this example, if you do not already have a `content/posts` directory, Hugo will create both `content/posts/` and `content/posts/my-first-post.md` for you.
+{{% /note %}}
+
+The auto-populated fields are worth examining:
+
+* `title` is generated from the new content's filename (i.e. in this case, `my-first-post` becomes `"my first post"`)
+* `date` and `title` are the variables that ship with Hugo and are therefore included in *all* content files created with the Hugo CLI. `date` is generated in [RFC 3339 format][] by way of Go's [`now()`][] function, which returns the current time.
+* The third variable, `draft = true`, is *not* inherited by your default or custom archetypes but is included in Hugo's automatically scaffolded `default.md` archetype for convenience.
+
+Three variables per content file are often not enough for effective content management of larger websites. Luckily, Hugo provides a simple mechanism for extending the number of variables through custom archetypes, as well as default archetypes to keep content creation DRY.
+
+## Lookup Order for Archetypes
+
+Similar to the [lookup order for templates][lookup] in your `layouts` directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for `content/posts/my-first-post.md` in the following order:
+
+1. `archetypes/posts.md`
+2. `archetypes/default.md`
+3. `themes/<THEME>/archetypes/posts.md`
+4. `themes/<THEME>/archetypes/default.md` (Auto-generated with `hugo new site`)
+
+{{% note "Using a Theme Archetype" %}}
+If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/getting-started/configuration/).
+{{% /note %}}
+
+## Choose Your Archetype's Front Matter Format
+
+By default, `hugo new` content files include front matter in the TOML format regardless of the format used in `archetypes/*.md`.
+
+You can specify a different default format in your site [configuration file][] file using the `metaDataFormat` directive. Possible values are `toml`, `yaml`, and `json`.
+
+## Default Archetypes
+
+Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][sections].
+
+### Create the Default Archetype
+
+When you create a new Hugo project using `hugo new site`, you'll notice that Hugo has already scaffolded a file at `archetypes/default.md`.
+
+The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
+
+{{< code file="archetypes/default.md" >}}
++++
+tags = ["golang", "hugo"]
+categories = ["web development"]
++++
+{{< /code >}}
+
+{{% warning "EOL Characters in Text Editors"%}}
+If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
+{{% /warning %}}
+
+### Use the Default Archetype
+
+With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
+
+{{< code file="new-post-from-default.sh" >}}
+$ hugo new posts/my-new-post.md
+{{< /code >}}
+
+Hugo then creates a new markdown file with the following front matter:
+
+{{< output file="content/posts/my-new-post.md" >}}
++++
+categories = ["web development"]
+date = "2017-02-01T19:20:04-07:00"
+tags = ["golang", "hugo"]
+title = "my new post"
++++
+{{< /output >}}
+
+We see that the `title` and `date` key-values have been added in addition to the `tags` and `categories` key-values from `archetypes/default.md`.
+
+{{% note "Ordering of Front Matter" %}}
+You may notice that content files created with `hugo new` do not respect the order of the key-values specified in your archetype files. This is a [known issue](https://github.com/gohugoio/hugo/issues/452).
+{{% /note %}}
+
+## Custom Archetypes
+
+Suppose your site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. You can create a custom archetype for your posts at `archetypes/posts.md` that includes the full set of front matter to be added to the two default archetypes fields.
+
+### Create a Custom Archetype
+
+{{< code file="archetypes/posts.md">}}
++++
+description = ""
+tags = ""
+categories = ""
++++
+{{< /code >}}
+
+### Use a Custom Archetype
+
+With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
+
+{{< code file="new-post-from-custom.sh" >}}
+$ hugo new posts/post-from-custom.md
+{{< /code >}}
+
+This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
+
+{{< output file="content/posts/post-from-custom-archetype.md" >}}
++++
+categories = ""
+date = 2017-02-13T17:24:43-08:00
+description = ""
+tags = ""
+title = "post from custom archetype"
++++
+{{< /output >}}
+
+### Hugo Docs Custom Archetype
+
+As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
+
+{{< code file="archetypes/functions.md" >}}
++{{< readfile file="/archetypes/functions.md" >}}
+{{< /code >}}
+
+{{% note %}}
+The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
+{{% /note %}}
+
+[archetypes directory]: /getting-started/directory-structure/
+[`now()`]: http://golang.org/pkg/time/#Now
+[configuration file]: /getting-started/configuration/
+[sections]: /content-management/sections/
+[content types]: /content-management/types/
+[front matter]: /content-management/front-matter/
+[RFC 3339 format]: https://www.ietf.org/rfc/rfc3339.txt
+[taxonomies]: /content-management/taxonomies/
+[lookup]: /templates/lookup/
+[templates]: /templates/
--- /dev/null
+---
+title: Front Matter
+linktitle:
+description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+date: 2017-01-09
+publishdate: 2017-01-09
+lastmod: 2017-02-24
+categories: [content management]
+keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 30
+weight: 30 #rem
+draft: false
+aliases: [/content/front-matter/]
+toc: true
+---
+
+**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+
+{{< youtube Yh2xKRJGff4 >}}
+
+## Front Matter Formats
+
+Hugo supports three formats for front matter, each with their own identifying tokens.
+
+TOML
+: identified by opening and closing `+++`.
+
+YAML
+: identified by opening and closing `---`.
+
+JSON
+: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+
+### TOML Example
+
+```
++++
+title = "spf13-vim 3.0 release and new website"
+description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+date = "2012-04-06"
+categories = [
+ "Development",
+ "VIM"
+]
+slug = "spf13-vim-3-0-release-and-new-website"
++++
+```
+
+### YAML Example
+
+```
+---
+title: "spf13-vim 3.0 release and new website"
+description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+lastmod: 2015-12-23
+date: "2012-04-06"
+categories:
+ - "Development"
+ - "VIM"
+slug: "spf13-vim-3-0-release-and-new-website"
+---
+```
+
+### JSON Example
+
+```
+{
+ "title": "spf13-vim 3.0 release and new website",
+ "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
+ "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
+ "date": "2012-04-06",
+ "categories": [
+ "Development",
+ "VIM"
+ ],
+ "slug": "spf13-vim-3-0-release-and-new-website"
+}
+```
+
+## Front Matter Variables
+
+### Predefined
+
+There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+
+`aliases`
+: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+
+`date`
+: the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][].
+
+`description`
+: the description for the content.
+
+`draft`
+: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+
+`expiryDate`
+: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+
++`headless`
++: if `true`, sets a leaf bundle to be [headless][headless-bundle].
++
+`isCJKLanguage`
+: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+
+`keywords`
+: the meta keywords for the content.
+
+`layout`
+: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype]
+
+`lastmod`
+: the datetime at which the content was last modified.
+
+`linkTitle`
+: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
+
+`markup`
+: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+
+`outputs`
+: allows you to specify output formats specific to the content. See [output formats][outputs].
+
+`publishDate`
+: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+
++`resources`
++: used for configuring page bundle resources. See [Page Resources][page-resources].
++
+`slug`
+: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
+
+`taxonomies`
+: these will use the field name of the plural form of the index; see the `tags` and `categories` in the above front matter examples.
+
+`title`
+: the title for the content.
+
+`type`
+: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
+
+`url`
+: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of
+the multilingual feature.
+
+`weight`
+: used for [ordering your content in lists][ordering].
+
+{{% note "Hugo's Default URL Destinations" %}}
+If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
+{{% /note %}}
+
+### User-Defined
+
+You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+
+The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+```
+include_toc: true
+show_comments: false
+```
+
+These two user-defined fields can then be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][variables] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+
+## Order Content Through Front Matter
+
+You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+
+## Override Global Markdown Configuration
+
+It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config].
+
+## Front Matter Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[variables]: /variables/
+[aliases]: /content-management/urls/#aliases/
+[archetype]: /content-management/archetypes/
+[bylinktitle]: /templates/lists/#by-link-title
+[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
+[content type]: /content-management/types/
+[contentorg]: /content-management/organization/
+[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
++[headless-bundle]: /content-management/page-bundles/#headless-bundle
+[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
+[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
+[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
+[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
+[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
++[page-resources]: /content-management/page-resources/
+[pagevars]: /variables/page/
+[section]: /content-management/sections/
+[taxweight]: /content-management/taxonomies/
+[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
+[urls]: /content-management/urls/
+[variables]: /variables/
+[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
--- /dev/null
--- /dev/null
++---
++title: "Image Processing"
++description: "Image Page resources can be resized and cropped."
++date: 2018-01-24T13:10:00-05:00
++lastmod: 2018-01-26T15:59:07-05:00
++linktitle: "Image Processing"
++categories: ["content management"]
++keywords: [bundle,content,resources,images]
++weight: 4004
++draft: false
++toc: true
++menu:
++ docs:
++ parent: "content-management"
++ weight: 32
++---
++
++## The Image Page Resource
++
++The `image` is a [Page Resource]({{< relref "content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder.
++
++
++To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}):
++
++
++```html
++{{ with .Resources.ByType "image" }}
++{{ end }}
++
++```
++
++## Image Processing Methods
++
++
++The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options.
++
++Resize
++: Resizes the image to the specified width and height.
++
++```go
++// Resize to a width of 600px and preserve ratio
++{{ $image := $resource.Resize "600x" }}
++
++// Resize to a height of 400px and preserve ratio
++{{ $image := $resource.Resize "x400" }}
++
++// Resize to a width 600px and a height of 400px
++{{ $image := $resource.Resize "600x400" }}
++```
++
++Fit
++: Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required.
++
++```go
++{{ $image := $resource.Fit "600x400" }}
++```
++
++Fill
++: Resize and crop the image to match the given dimensions. Both height and width are required.
++
++```go
++{{ $image := $resource.Fill "600x400" }}
++```
++
++
++{{% 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 Options
++
++In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options.
++
++
++JPEG Quality
++: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75.
++
++```go
++{{ $image.Resize "600x q50" }}
++```
++
++Rotate
++: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. 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.
++
++```go
++{{ $image.Resize "600x r90" }}
++```
++
++Anchor
++: Only relevant for the `Fill` method. 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`.
++
++```go
++{{ $image.Fill "300x200 BottomLeft" }}
++```
++
++Resample Filter
++: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling.
++
++Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`.
++
++See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test.
++
++```go
++{{ $image.Resize "600x400 Gaussian" }}
++```
++
++### 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:
++
++```html
++{{</* imgproc sunset Resize "300x" /*/>}}
++```
++
++
++{{% note %}}
++**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**.
++{{% /note %}}
--- /dev/null
- You should define the available languages in a `Languages` section in your site configuration.
+---
+title: Multilingual Mode
+linktitle: Multilingual and i18n
+description: Hugo supports the creation of websites with multiple languages side by side.
+date: 2017-01-10
+publishdate: 2017-01-10
+lastmod: 2017-01-10
+categories: [content management]
+keywords: [multilingual,i18n, internationalization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 150
+weight: 150 #rem
+draft: false
+aliases: [/content/multilingual/,/content-management/multilingual/,/tutorials/create-a-multilingual-site/]
+toc: true
+---
+
- [Languages]
- [Languages.en]
++You should define the available languages in a `languages` section in your site configuration.
+
+## Configure Languages
+
+The following is an example of a TOML site configuration for a multilingual Hugo project:
+
+{{< code file="config.toml" download="config.toml" >}}
+DefaultContentLanguage = "en"
+copyright = "Everything is mine"
+
+[params.navigation]
+help = "Help"
+
- [Languages.fr]
++[languages]
++[languages.en]
+title = "My blog"
+weight = 1
+linkedin = "english-link"
+
- [Languages.fr.navigation]
++[languages.fr]
+copyright = "Tout est à moi"
+title = "Mon blog"
+weight = 2
+linkedin = "lien-francais"
- Anything not defined in a `[Languages]` block will fall back to the global
++
++# skip params key for front matter
++[languages.fr.navigation]
+help = "Aide"
+{{< /code >}}
+
- [Languages]
- [Languages.en]
++Anything not defined in a `[languages]` block will fall back to the global
+value for that key (e.g., `copyright` for the English [`en`] language).
+
+With the configuration above, all content, sitemap, RSS feeds, paginations,
+and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
+
+When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
+
+If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`.
+
+Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
+
+## Configure Multilingual Multihost
+
+From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
+
+This means that you can now configure a `baseURL` per `language`:
+
+
+> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different.
+
+Example:
+
+```bash
+[languages]
+[languages.no]
+baseURL = "https://example.no"
+languageName = "Norsk"
+weight = 1
+title = "På norsk"
+
+[languages.en]
+baseURL = "https://example.com"
+languageName = "English"
+weight = 2
+title = "In English"
+```
+
+With the above, the two sites will be generated into `public` with their own root:
+
+```bash
+public
+├── en
+└── no
+```
+
+**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.**
+
+When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console:
+
+```bash
+Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1)
+Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
+Press Ctrl+C to stop
+```
+
+Live reload and `--navigateToChanged` between the servers work as expected.
+
+## Taxonomies and Blackfriday
+
+Taxonomies and [Blackfriday configuration][config] can also be set per language:
+
+
+{{< code file="bf-config.toml" >}}
+[Taxonomies]
+tag = "tags"
+
+[blackfriday]
+angledQuotes = true
+hrefTargetBlank = true
+
- [Languages.en.blackfriday]
++[languages]
++[languages.en]
+weight = 1
+title = "English"
- [Languages.fr]
++[languages.en.blackfriday]
+angledQuotes = false
+
- [Languages.fr.Taxonomies]
++[languages.fr]
+weight = 2
+title = "Français"
- The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language.
++[languages.fr.Taxonomies]
+plaque = "plaques"
+{{< /code >}}
+
+## Translate Your Content
+
+Translated articles are identified by the name of the content file.
+
+### Examples of Translated Articles
+
+1. `/content/about.en.md`
+2. `/content/about.fr.md`
+
+In this example, the `about.md` will be assigned the configured `defaultContentLanguage`.
+
+1. `/content/about.md`
+2. `/content/about.fr.md`
+
+This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`.
+
+By having the same **directory and base filename**, the content pieces are linked together as translated pieces.
+
+You can also set the key used to link the translations explicitly in front matter:
+
+```yaml
+translationKey: "my-story"
+```
+
+
+{{% note %}}
+**Before Hugo 0.31**, the file's directory was not considered when looking for translations. This did not work when you named all of your content files, say, `index.md`. Now we use the full content path.
+{{% /note %}}
+
+If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
+
+```yaml
+slug: "a-propos"
+
+```
+
+At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages.
+
+
+## Link to Translated Content
+
+To create a list of links to translated content, use a template similar to the following:
+
+{{< code file="layouts/partials/i18nlist.html" >}}
+{{ if .IsTranslated }}
+<h4>{{ i18n "translations" }}</h4>
+<ul>
+ {{ range .Translations }}
+ <li>
+ <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+ </li>
+ {{ end}}
+</ul>
+{{ end }}
+{{< /code >}}
+
++The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page.
+
+The above also uses the [`i18n` function][i18func] described in the next section.
+
+## List All Available Languages
+
+`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator:
+
+
+{{< code file="layouts/partials/allLanguages.html" >}}
+<ul>
+{{ range $.Site.Home.AllTranslations }}
+<li><a href="{{ .}}">{{ .Language.LanguageName }}</a></li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+## Translation of Strings
+
+Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows.
+
+Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc.
+
+{{% note %}}
+From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything.
+
+See https://github.com/gohugoio/hugo/issues/3564
+
+{{% /note %}}
+
+From within your templates, use the `i18n` function like this:
+
+```
+{{ i18n "home" }}
+```
+
+This uses a definition like this one in `i18n/en-US.toml`:
+
+```
+[home]
+other = "Home"
+```
+
+Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`:
+
+```
+{{ i18n "wordCount" . }}
+```
+
+This uses a definition like this one in `i18n/en-US.toml`:
+
+```
+[wordCount]
+other = "This article has {{ .WordCount }} words."
+```
+An example of singular and plural form:
+
+```
+[readingTime]
+one = "One minute read"
+other = "{{.Count}} minutes read"
+```
+And then in the template:
+
+```
+{{ i18n "readingTime" .ReadingTime }}
+```
+To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
+
+```
+ hugo --i18n-warnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Customize Dates
+
+At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content:
+
+~~~yaml
+1: "janvier"
+2: "février"
+3: "mars"
+4: "avril"
+5: "mai"
+6: "juin"
+7: "juillet"
+8: "août"
+9: "septembre"
+10: "octobre"
+11: "novembre"
+12: "décembre"
+~~~
+
+... then index the non-English date names in your templates like so:
+
+~~~html
+<time class="post-date" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" | safeHTML }}">
+ Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
+</time>
+~~~
+
+This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file.
+
+## Menus
+
+You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
+
+```
+defaultContentLanguage = "en"
+
+[languages.en]
+weight = 0
+languageName = "English"
+
+[[languages.en.menu.main]]
+url = "/"
+name = "Home"
+weight = 0
+
+
+[languages.de]
+weight = 10
+languageName = "Deutsch"
+
+[[languages.de.menu.main]]
+url = "/"
+name = "Startseite"
+weight = 0
+```
+
+The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory.
+
+```
+<ul>
+ {{- $currentPage := . -}}
+ {{ range .Site.Menus.main -}}
+ <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
+ <a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
+ </li>
+ {{- end }}
+</ul>
+
+```
+
+## Missing translations
+
+If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
+
+While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
+
+{{% note %}}
+Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments.
+{{% /note %}}
+
+## Multilingual Themes support
+
+To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
+
+* Come from the built-in `.Permalink` or `.URL`
+* Be constructed with
+ * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR**
+ * Prefixed with `{{ .LanguagePrefix }}`
+
+If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites.
+
+[abslangurl]: /functions/abslangurl
+[config]: /getting-started/configuration/
+[contenttemplate]: /templates/single-page-templates/
+[go-i18n-source]: https://github.com/nicksnyder/go-i18n
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[homepage]: /templates/homepage/
+[i18func]: /functions/i18n/
+[menus]: /content-management/menus/
+[rellangurl]: /functions/rellangurl
+[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[singles]: /templates/single-page-templates/
--- /dev/null
--- /dev/null
++---
++title: Content Organization
++linktitle: Organization
++description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.
++date: 2017-02-01
++publishdate: 2017-02-01
++lastmod: 2017-02-01
++categories: [content management,fundamentals]
++keywords: [sections,content,organization,bundle,resources]
++menu:
++ docs:
++ parent: "content-management"
++ weight: 10
++weight: 10 #rem
++draft: false
++aliases: [/content/sections/]
++toc: true
++---
++
++## Page Bundles
++
++Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
++
++These terms are connected, and you also need to read about [Page Resources]({{< relref "content-management/page-resources" >}}) and [Image Processing]({{< relref "content-management/image-processing" >}}) to get the full picture.
++
++{{% imgproc 1-featured Resize "300x" %}}
++The illustration shows 3 bundles. Note that the home page bundle cannot contain other content pages, but other files (images etc.) are fine.
++{{% /imgproc %}}
++
++
++{{% note %}}
++The bundle docuementation is **work in progress**. We will publish more comprehensive docs about this soon.
++{{% /note %}}
++
++
++# Organization of Content Source
++
++
++In Hugo, your content should be organized in a manner that reflects the rendered website.
++
++While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][].
++
++Without any additional configuration, the following will just work:
++
++```
++.
++└── content
++ └── about
++ | └── _index.md // <- https://example.com/about/
++ ├── post
++ | ├── firstpost.md // <- https://example.com/post/firstpost/
++ | ├── happy
++ | | └── ness.md // <- https://example.com/post/happy/ness/
++ | └── secondpost.md // <- https://example.com/post/secondpost/
++ └── quote
++ ├── first.md // <- https://example.com/quote/first/
++ └── second.md // <- https://example.com/quote/second/
++```
++
++## Path Breakdown in Hugo
++
++
++The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "https://example.com"` in your [site's configuration file][config].
++
++### Index Pages: `_index.md`
++
++`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][].
++
++{{% note %}}
++**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/).
++{{% /note %}}
++
++You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
++
++
++```
++. url
++. ⊢--^-⊣
++. path slug
++. ⊢--^-⊣⊢---^---⊣
++. filepath
++. ⊢------^------⊣
++content/posts/_index.md
++```
++
++At build, this will output to the following destination with the associated values:
++
++```
++
++ url ("/posts/")
++ ⊢-^-⊣
++ baseurl section ("posts")
++⊢--------^---------⊣⊢-^-⊣
++ permalink
++⊢----------^-------------⊣
++https://example.com/posts/index.html
++```
++
++The [sections][] can be nested as deeply as you need. The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (i.e. `_index.md`).
++
++
++### Single Pages in Sections
++
++Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
++
++
++```
++ path ("posts/my-first-hugo-post.md")
++. ⊢-----------^------------⊣
++. section slug
++. ⊢-^-⊣⊢--------^----------⊣
++content/posts/my-first-hugo-post.md
++```
++
++At the time Hugo builds your site, the content will be output to the following destination:
++
++```
++
++ url ("/posts/my-first-hugo-post/")
++ ⊢------------^----------⊣
++ baseurl section slug
++⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
++ permalink
++⊢--------------------^---------------------⊣
++https://example.com/posts/my-first-hugo-post/index.html
++```
++
++
++## Paths Explained
++
++The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website.
++
++### `section`
++
++A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter.
++
++### `slug`
++
++A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
++
++* the name of the content file (e.g., `lollapalooza.md`) OR
++* front matter overrides
++
++### `path`
++
++A content's `path` is determined by the section's path to the file. The file `path`
++
++* is based on the path to the content's location AND
++* does not include the slug
++
++### `url`
++
++The `url` is the relative URL for the piece of content. The `url`
++
++* is based on the content's location within the directory structure OR
++* is defined in front matter and *overrides all the above*
++
++## Override Destination Paths via Front Matter
++
++Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination.
++
++There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content.
++
++The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter:
++
++### `filename`
++
++This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
++
++### `slug`
++
++When defined in the front matter, the `slug` can take the place of the filename for the destination.
++
++{{< code file="content/posts/old-post.md" >}}
++---
++title: New Post
++slug: "new-post"
++---
++{{< /code >}}
++
++This will render to the following destination according to Hugo's default behavior:
++
++```
++example.com/posts/new-post/
++```
++
++### `section`
++
++`section` is determined by a content's location on disk and *cannot* be specified in the front matter. See [sections][] for more information.
++
++### `type`
++
++A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
++
++{{< code file="content/posts/my-post.md" >}}
++---
++title: My Post
++type: new
++layout: mylayout
++---
++{{< /code >}}
++<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
++<!-- ### `path`-->
++
++<!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. -->
++
++### `url`
++
++A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration:
++
++{{< code file="content/posts/old-url.md" >}}
++---
++title: Old URL
++url: /blog/new-url/
++---
++{{< /code >}}
++
++Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
++
++```
++https://example.com/blog/new-url/
++```
++
++You can see more information on how to control output paths in [URL Management][urls].
++
++[config]: /getting-started/configuration/
++[formats]: /content-management/formats/
++[front matter]: /content-management/front-matter/
++[getpage]: /functions/getpage/
++[homepage template]: /templates/homepage/
++[homepage]: /templates/homepage/
++[lists]: /templates/lists/
++[pretty]: /content-management/urls/#pretty-urls
++[section templates]: /templates/section-templates/
++[sections]: /content-management/sections/
++[singles]: /templates/single-page-templates/
++[taxonomy templates]: /templates/taxonomy-templates/
++[taxonomy terms templates]: /templates/taxonomy-templates/
++[types]: /content-management/types/
++[urls]: /content-management/urls/
--- /dev/null
--- /dev/null
++---
++title : "Page Bundles"
++description : "Content organization using Page Bundles"
++date : 2018-01-24T13:09:00-05:00
++lastmod : 2018-01-28T22:26:40-05:00
++linktitle : "Page Bundles"
++keywords : ["page", "bundle", "leaf", "branch"]
++categories : ["content management"]
++draft : true
++toc : true
++menu :
++ docs:
++ identifier : "page-bundles"
++ parent : "content-management"
++ weight : 11
++---
++
++Page Bundles are a way to organize the content files. It's useful for
++cases where a page or section's content needs to be split into
++multiple content pages for convenience or has associated attachments
++like documents or images.
++
++A Page Bundle can be one of two types:
++
++- Leaf Bundle
++- Branch Bundle
++
++| | Leaf Bundle | Branch Bundle |
++|-----------------|--------------------------------------------------------|---------------------------------------------------------|
++| Usage | Collection of content and attachments for single pages | Collection of content and attachments for section pages |
++| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
++| Layout type | `single` | `list` |
++| Nesting | Doesn't allow nesting of more bundles under it | Allows nesting of leaf/branch bundles under it |
++| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
++
++
++## Leaf Bundles {#leaf-bundles}
++
++A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
++directory, that contains at least an **`index.md`** file.
++
++{{% note %}}
++Here `md` (markdown) is used just as an example. You can use any file
++type as a content resource as long as it is a 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.
++{{% /note %}}
++
++
++### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
++
++```text
++content/
++├── about
++│ ├── index.md
++├── posts
++│ ├── my-post
++│ │ ├── content1.md
++│ │ ├── content2.md
++│ │ ├── image1.jpg
++│ │ ├── image2.png
++│ │ └── index.md
++│ └── my-another-post
++│ └── index.md
++│
++└── another-section
++ ├── ..
++ └── not-a-leaf-bundle
++ ├── ..
++ └── another-leaf-bundle
++ └── index.md
++```
++
++In the above example `content/` directory, there are four leaf
++bundles:
++
++about
++: This leaf bundle is at the root level (directly under
++ `content` directory) and has only the `index.md`.
++
++my-post
++: This leaf bundle has the `index.md`, two other content
++ Markdown files and two image files.
++
++my-another-post
++: This leaf bundle has only the `index.md`.
++
++another-leaf-bundle
++: This leaf bundle is nested under couple of
++ directories. This bundle also has only the `index.md`.
++
++{{% note %}}
++The hierarchy depth at which a leaf bundle is created does not matter,
++as long as it is not inside another **leaf** bundle.
++{{% /note %}}
++
++
++### Headless Bundle {#headless-bundle}
++
++A headless bundle is a bundle that is configured to not get published
++anywhere:
++
++- It will have no `Permalink` and no rendered HTML in `public/`.
++- It will not be part of `.Site.RegularPages`, etc.
++
++But you can get it by `.Site.GetPage`. Here is an example:
++
++```html
++{{ $headless := .Site.GetPage "page" "some-headless-bundle" }}
++{{ $reusablePages := $headless.Resources.Match "author*" }}
++<h2>Authors</h2>
++{{ range $reusablePages }}
++ <h3>{{ .Title }}</h3>
++ {{ .Content }}
++{{ end }}
++```
++
++A leaf bundle can be made headless by adding below in the Front Matter
++(in the `index.md`):
++
++```toml
++headless = true
++```
++
++{{% note %}}
++Only leaf bundles can be made headless.
++{{% /note %}}
++
++There are many use cases of such headless page bundles:
++
++- Shared media galleries
++- Reusable page content "snippets"
++
++
++## Branch Bundles {#branch-bundles}
++
++A _Branch Bundle_ is any directory at any hierarchy within the
++`content/` directory, that contains at least an **`_index.md`** file.
++
++This `_index.md` can also be directly under the `content/` directory.
++
++{{% note %}}
++Here `md` (markdown) is used just as an example. You can use any file
++type as a content resource as long as it is a 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.
++{{% /note %}}
++
++
++### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization}
++
++```text
++content/
++├── branch-bundle-1
++│ ├── branch-content1.md
++│ ├── branch-content2.md
++│ ├── image1.jpg
++│ ├── image2.png
++│ └── _index.md
++└── branch-bundle-2
++ ├── _index.md
++ └── a-leaf-bundle
++ └── index.md
++```
++
++In the above example `content/` directory, there are two branch
++bundles (and a leaf bundle):
++
++`branch-bundle-1`
++: This branch bundle has the `_index.md`, two
++ other content Markdown files and two image files.
++
++`branch-bundle-2`
++: This branch bundle has the `_index.md` and a
++ nested leaf bundle.
++
++{{% note %}}
++The hierarchy depth at which a branch bundle is created does not
++matter.
++{{% /note %}}
++
++[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type.
--- /dev/null
--- /dev/null
++---
++title : "Page Resources"
++description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata."
++date: 2018-01-24
++categories: ["content management"]
++keywords: [bundle,content,resources]
++weight: 4003
++draft: false
++toc: true
++linktitle: "Page Resources"
++menu:
++ docs:
++ parent: "content-management"
++ weight: 31
++---
++
++## Properties
++
++ResourceType
++: The main type of the resource. For example, a file of MIME type `image/jpg` has for ResourceType `image`.
++
++Name
++: Default value is the filename (relative to the owning page). Can be set in front matter.
++
++Title
++: Default blank. Can be set in front matter.
++
++Permalink
++: The absolute URL to the resource. Resources of type `page` will have no value.
++
++RelPermalink
++: The relative URL to the resource. Resources of type `page` will have no value.
++
++## Methods
++ByType
++: Returns the page resources of the given type.
++
++```go
++{{ .Resources.ByType "image" }}
++```
++Match
++: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
++
++```go
++{{ .Resources.Match "images/*" }}
++```
++
++GetMatch
++: Same as `Match` but will return the first match.
++
++### Pattern Matching
++```go
++// Using Match/GetMatch to find this images/sunset.jpg ?
++.Resources.Match "images/sun*" ✅
++.Resources.Match "**/Sunset.jpg" ✅
++.Resources.Match "images/*.jpg" ✅
++.Resources.Match "**.jpg" ✅
++.Resources.Match "*" 🚫
++.Resources.Match "sunset.jpg" 🚫
++.Resources.Match "*sunset.jpg" 🚫
++
++```
++
++## Page Resources Metadata
++
++Page Resources' metadata is managed from their page's front matter with an array/table parameter named `resources`. You can batch assign values using a [wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
++
++{{% note %}}
++Resources of type `page` get `Title` etc. from their own front matter.
++{{% /note %}}
++
++name
++: Sets the value returned in `Name`.
++
++{{% warning %}}
++The methods `Match` and `GetMatch` use `Name` to match the resources.
++{{%/ warning %}}
++
++title
++: Sets the value returned in `Title`
++
++params
++: A map of custom key/values.
++
++
++### Resources metadata: YAML Example
++
++~~~yaml
++title: Application
++date : 2018-01-25
++resources :
++- src : "images/sunset.jpg"
++ name : "header"
++- src : "documents/photo_specs.pdf"
++ title : "Photo Specifications"
++ params:
++ icon : "photo"
++- src : "documents/guide.pdf"
++ title : "Instruction Guide"
++- src : "documents/checklist.pdf"
++ title : "Document Checklist"
++- src : "documents/payment.docx"
++ title : "Proof of Payment"
++- src : "**.pdf"
++ name : "pdf-file-:counter"
++ params :
++ icon : "pdf"
++- src : "**.docx"
++ params :
++ icon : "word"
++~~~
++
++### Resources metadata: TOML Example
++
++~~~toml
++title = Application
++date : 2018-01-25
++[[resources]]
++ src = "images/sunset.jpg"
++ name = "header"
++[[resources]]
++ src = "documents/photo_specs.pdf"
++ title = "Photo Specifications"
++ [resources.params]
++ icon = "photo"
++[[resources]]
++ src = "documents/guide.pdf"
++ title = "Instruction Guide"
++[[resources]]
++ src = "documents/checklist.pdf"
++ title = "Document Checklist"
++[[resources]]
++ src = "documents/payment.docx"
++ title = "Proof of Payment"
++[[resources]]
++ src = "**.pdf"
++ name = "pdf-file-:counter"
++ [resources.params]
++ icon = "pdf"
++[[resources]]
++ src = "**.docx"
++ [resources.params]
++ icon = "word"
++~~~
++
++
++From the example above:
++
++- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
++- `documents/photo_specs.pdf` will get the `photo` icon.
++- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
++- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
++- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#counter), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
++- Every docx in the bundle will receive the `word` icon.
++
++{{% warning %}}
++The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. For example, in the above example, `.Params.icon` is already first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
++{{%/ warning %}}
++
++### The `:counter` placeholder in `name` and `title`
++
++The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
++
++The counter starts at 1 the first time they are used in either `name` or `title`.
++
++For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
++
++~~~toml
++[[resources]]
++ src = "*specs.pdf"
++ title = "Specification #:counter"
++[[resources]]
++ src = "**.pdf"
++ name = "pdf-file-:counter"
++~~~
++
++the `Name` and `Title` will be assigned to the resource files as follows:
++
++| Resource file | `Name` | `Title` |
++|-------------------|-------------------|-----------------------|
++| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
++| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
++| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
++| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
--- /dev/null
- You can later use your custom metadata as shown in the [Taxonomy Terms Templates documentation](/templates/taxonomy-templates/#displaying-custom-meta-data-in-taxonomy-terms-templates).
+---
+title: Taxonomies
+linktitle:
+description: Hugo includes support for user-defined taxonomies to help you demonstrate logical relationships between content for the end users of your website.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [taxonomies,metadata,front matter,terms]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 80
+weight: 80 #rem
+draft: false
+aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
+toc: true
+---
+
+## What is a Taxonomy?
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
+
+### Definitions
+
+Taxonomy
+: a categorization that can be used to classify content
+
+Term
+: a key within the taxonomy
+
+Value
+: a piece of content assigned to a term
+
+{{< youtube pCPCQgqC8RA >}}
+
+## Example Taxonomy: Movie Website
+
+Let's assume you are making a website about movies. You may want to include the following taxonomies:
+
+* Actors
+* Directors
+* Studios
+* Genre
+* Year
+* Awards
+
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the [front matter][] of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+
+### Movie Taxonomy Organization
+
+To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
+
+```
+Actor <- Taxonomy
+ Bruce Willis <- Term
+ The Sixth Sense <- Value
+ Unbreakable <- Value
+ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
+ Unbreakable <- Value
+ The Avengers <- Value
+ xXx <- Value
+```
+
+From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
+
+```
+Unbreakable <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Samuel L. Jackson <- Term
+ Director <- Taxonomy
+ M. Night Shyamalan <- Term
+ ...
+Moonrise Kingdom <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Bill Murray <- Term
+ Director <- Taxonomy
+ Wes Anderson <- Term
+ ...
+```
+
+## Hugo Taxonomy Defaults
+
+Hugo natively supports taxonomies.
+
+Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following:
+
+```
+disableKinds = ["taxonomy","taxonomyTerm"]
+```
+
+### Default Destinations
+
+When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+
+* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
+* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
+
+## Configure Taxonomies
+
+Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
+
+### Example: TOML Taxonomy Configuration
+
+```
+[taxonomies]
+ tag = "tags"
+ category = "categories"
+ series = "series"
+```
+
+### Example: YAML Taxonomy Configuration
+
+```
+taxonomies:
+ tag: "tags"
+ category: "categories"
+ series: "series"
+```
+
+### Preserve Taxonomy Values
+
+By default, taxonomy names are normalized.
+
+Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site configuration][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs.
+
+Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][].
+
+{{% note %}}
+You can add content and front matter to your taxonomy list and taxonomy terms pages. See [Content Organization](/content-management/organization/) for more information on how to add an `_index.md` for this purpose.
+
+Much like regular pages, taxonomy list [permalinks](/content-management/urls/) are configurable, but taxonomy term page permalinks are not.
+{{% /note %}}
+
+## Add Taxonomies to Content
+
+Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of [content type][] or [content section][].
+
+Assigning content to a taxonomy is done in the [front matter][]. Simply create a variable with the *plural* name of the taxonomy and assign all terms you want to apply to the instance of the content type.
+
+{{% note %}}
+If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
+{{% /note %}}
+
+### Example: TOML Front Matter with Taxonomies
+
+```
++++
+title = "Hugo: A fast and flexible static site generator"
+tags = [ "Development", "Go", "fast", "Blogging" ]
+categories = [ "Development" ]
+series = [ "Go Web Dev" ]
+slug = "hugo"
+project_url = "https://github.com/gohugoio/hugo"
++++
+```
+
+### Example: YAML Front Matter with Taxonomies
+
+```
+---
+title: "Hugo: A fast and flexible static site generator"
+tags: ["Development", "Go", "fast", "Blogging"]
+categories: ["Development"]
+series: ["Go Web Dev"]
+slug: "hugo"
+project_url: "https://github.com/gohugoio/hugo"
+---
+```
+
+### Example: JSON Front Matter with Taxonomies
+
+```
+{
+ "title": "Hugo: A fast and flexible static site generator",
+ "tags": [
+ "Development",
+ "Go",
+ "fast",
+ "Blogging"
+ ],
+ "categories" : [
+ "Development"
+ ],
+ "series" : [
+ "Go Web Dev"
+ ],
+ "slug": "hugo",
+ "project_url": "https://github.com/gohugoio/hugo"
+}
+```
+
+## Order Taxonomies
+
+A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in [taxonomy list templates][] and is declared in a content file's [front matter][]. The convention for declaring taxonomic weight is `taxonomyname_weight`.
+
+The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
+
+### Example: TOML Taxonomic `weight`
+
+```
++++
+title = "foo"
+tags = [ "a", "b", "c" ]
+tags_weight = 22
+categories = ["d"]
+categories_weight = 44
++++
+```
+
+### Example: YAML Taxonomic `weight`
+
+```
+---
+title: foo
+tags: [ "a", "b", "c" ]
+tags_weight: 22
+categories: ["d"]
+categories_weight: 44
+---
+```
+
+By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.
+
+{{% note "Limits to Ordering Taxonomies" %}}
+Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
+{{% /note %}}
+
+## Add custom metadata to a Taxonomy Term
+
+If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a wikipedia page link to each actor. Your terms pages would be something like this:
+
+{{< code file="/content/actors/bruce-willis/_index.md" >}}
+ ---
+ title: "Bruce Willis"
+ wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
+ ---
+{{< /code >}}
+
++You can later use your custom metadata as shown in the [Taxonomy Terms Templates documentation](/templates/taxonomy-templates/#displaying-custom-metadata-in-taxonomy-terms-templates).
+
+[`urlize` template function]: /functions/urlize/
+[content section]: /content-management/sections/
+[content type]: /content-management/types/
+[documentation on archetypes]: /content-management/archetypes/
+[front matter]: /content-management/front-matter/
+[taxonomy list templates]: /templates/taxonomy-templates/#taxonomy-page-templates
+[taxonomy templates]: /templates/taxonomy-templates/
+[terms within the taxonomy]: /templates/taxonomy-templates/#taxonomy-terms-templates "See how to order terms associated with a taxonomy"
+[config]: /getting-started/configuration/
--- /dev/null
- The archetype for `functions` according to the Hugo theme is as follows:
+---
+title: Contribute to the Hugo Docs
+linktitle: Documentation
+description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [contribute]
+keywords: [docs,documentation,community, contribute]
+menu:
+ docs:
+ parent: "contribute"
+ weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/contribute/docs/]
+toc: true
+---
+
+## Create Your Fork
+
+It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
+
+You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
+
+```
+git checkout -b jon-doe-showcase-addition
+```
+
+## Add New Content
+
+The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content sections in Hugo documentation have an assigned archetype.
+
+Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
+
+```
+hugo new <DOCS-SECTION>/<new-content-lowercase>.md
+```
+
+### Add a New Function
+
+Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase.
+
+```
+hugo new functions/newfunction.md
+```
+
- {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md">}}
++The archetype for `functions` according to the Hugo docs is as follows:
+
+{{< code file="archetypes/functions.md" >}}
++{{< readfile file="/archetypes/functions.md">}}
+{{< /code >}}
+
+#### New Function Required Fields
+
+Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
+
+***`title`***
+: this will be auto-populated in all lowercase when you use `hugo new` generator.
+
+***`linktitle`***
+: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
+
+***`description`***
+: a brief description used to populate the [Functions Quick Reference](/functions/).
+
+`categories`
+: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
+
+`tags`
+: only if you think it will help end users find other related functions
+
+`signature`
+: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
+
+`workson`
+: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.
+
+`hugoversion`
+: the version of Hugo that will ship with this new function.
+
+`relatedfuncs`
+: other [templating functions][] you feel are related to your new function to help fellow Hugo users.
+
+`{{.Content}}`
+: an extended description of the new function; examples are not only welcomed but encouraged.
+
+In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#adding-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
+
+## Add Code Blocks
+
+Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.
+
+### Standard Syntax
+
+Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages.
+
+Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`.
+
+```
+```
+<h1>Hello world!</h1>
+```
+```
+
+### Code Block Shortcode
+
+The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.
+
+{{% note %}}
+With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs.
+{{% /note %}}
+
+### `code`
+
+`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
+
+```
+{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
+```
+A whole bunch of coding going on up in here!
+```
+{{%/* /code */%}}
+```
+
+The following are the arguments passed into `code`:
+
+***`file`***
+: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
+
+`download`
+: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
+
+`copy`
+: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`.
+
+#### Example `code` Input
+
+This example HTML code block tells Hugo users the following:
+
+1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
+2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
+
+```
+{{</* code file="layouts/_default/single.html" download="single.html" */>}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ {{with .Params.subtitle}}
+ <span>{{.}}</span>
+ </header>
+ <div>
+ {{.Content}}
+ </div>
+ <aside>
+ {{.TableOfContents}}
+ </aside>
+ </article>
+</main>
+{{ end }}
+{{</* /code */>}}
+```
+
+##### Example 'code' Display
+
+The output of this example will render to the Hugo docs as follows:
+
+{{< code file="layouts/_default/single.html" download="single.html" >}}
+{{ define "main" }}
+<main>
+ <article>
+ <header>
+ <h1>{{.Title}}</h1>
+ {{with .Params.subtitle}}
+ <span>{{.}}</span>
+ </header>
+ <div>
+ {{.Content}}
+ </div>
+ <aside>
+ {{.TableOfContents}}
+ </aside>
+ </article>
+</main>
+{{ end }}
+{{< /code >}}
+
+<!-- #### Output Code Block
+
+The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
+
+```
+{{%/* output file="post/my-first-post/index.html" */%}}
+```
+<h1>This is my First Hugo Blog Post</h1>
+<p>I am excited to be using Hugo.</p>
+```
+{{%/* /output */%}}
+```
+
+The preceding `output` example will render as follows to the Hugo docs:
+
+{{< output file="post/my-first-post/index.html" >}}
+<h1>This is my First Hugo Blog Post</h1>
+<p>I am excited to be using Hugo.</p>
+{{< /output >}} -->
+
+## Blockquotes
+
+Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
+
+```
+> Without the threat of punishment, there is no joy in flight.
+```
+
+The preceding blockquote will render as follows in the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight.
+
+However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
+
+```
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
+```
+
+Which will render as follows in the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]
+
+{{% note "Blockquotes `!=` Admonitions" %}}
+Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
+{{% /note %}}
+
+## Admonitions
+
+**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation:
+
+> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
+
+The Hugo docs contain three admonitions: `note`, `tip`, and `warning`.
+
+### `note` Admonition
+
+Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.
+
+#### Example `note` Input
+
+{{< code file="note-with-heading.md" >}}
+{{%/* note */%}}
+Here is a piece of information I would like to draw your **attention** to.
+{{%/* /note */%}}
+{{< /code >}}
+
+#### Example `note` Output
+
+{{< output file="note-with-heading.html" >}}
+{{% note %}}
+Here is a piece of information I would like to draw your **attention** to.
+{{% /note %}}
+{{< /output >}}
+
+#### Example `note` Display
+
+{{% note %}}
+Here is a piece of information I would like to draw your **attention** to.
+{{% /note %}}
+
+### `tip` Admonition
+
+Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`.
+
+#### Example `tip` Input
+
+{{< code file="using-tip.md" >}}
+{{%/* tip */%}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{%/* /tip */%}}
+{{< /code >}}
+
+#### Example `tip` Output
+
+{{< output file="tip-output.html" >}}
+{{% tip %}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{% /tip %}}
+{{< /output >}}
+
+#### Example `tip` Display
+
+{{% tip %}}
+Here's a bit of advice to improve your productivity with Hugo.
+{{% /tip %}}
+
+### `warning` Admonition
+
+Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."
+
+#### Example `warning` Input
+
+{{< code file="warning-admonition-input.md" >}}
+{{%/* warning */%}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{%/* /warning */%}}
+{{< /code >}}
+
+#### Example `warning` Output
+
+{{< output file="warning-admonition-output.html" >}}
+{{% warning %}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{% /warning %}}
+{{< /output >}}
+
+#### Example `warning` Display
+
+{{% warning %}}
+This is a warning, which should be reserved for *important* information like breaking changes.
+{{% /warning %}}
+
+{{% note "Pull Requests and Branches" %}}
+Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
+{{% /note %}}
+
+[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
+[archetypes]: /content-management/archetypes/
+[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
+[charcount]: http://www.lettercount.com/
+[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
+[ghforking]: https://help.github.com/articles/fork-a-repo/
+[hugodev]: /contribute/development/
+[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
+[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+[templating function]: /functions/
--- /dev/null
--- /dev/null
++---
++title: "cond"
++date: 2017-09-08
++description: "Return one of two arguments, depending on the value of a third argument."
++categories: [functions]
++menu:
++ docs:
++ parent: "functions"
++signature: ["cond CONTROL VAR1 VAR2"]
++aliases: [/functions/cond/]
++hugoversion: 0.27
++relatedfuncs: [default]
++toc: false
++draft: false
++needsexamples: false
++---
++
++`cond` returns *VAR1* if *CONTROL* is true, or *VAR2* if it is not.
++
++Example:
++
++```
++{{ cond (eq (len $geese) 1) "goose" "geese" }}
++```
++
++Would emit "goose" if the `$geese` array has exactly 1 item, or "geese" otherwise.
--- /dev/null
+---
+title: int
+linktitle: int
+description: Creates an `int` from the argument passed into the function.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [strings,integers]
+signature: ["int INPUT"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
+Useful for turning strings into numbers.
+
+```
+{{ int "123" }} → 123
+```
++
++{{% note "Usage Note" %}}
++If the input string is supposed to represent a decimal number, and if it has
++leading 0's, then those 0's will have to be removed before passing the string
++to the `int` function, else that string will be tried to be parsed as an octal
++number representation.
++
++The [`strings.TrimLeft` function](/functions/strings.trimleft/) can be used for
++this purpose.
++
++```
++{{ int ("0987" | strings.TrimLeft "0") }}
++{{ int ("00987" | strings.TrimLeft "0") }}
++```
++
++**Explanation**
++
++The `int` function eventually calls the `ParseInt` function from the Go library
++`strconv`.
++
++From its [documentation](https://golang.org/pkg/strconv/#ParseInt):
++
++> the base is implied by the string's prefix: base 16 for "0x", base 8 for "0",
++> and base 10 otherwise.
++{{% /note %}}
--- /dev/null
- defaultExtension: "html"
+---
+title: Configure Hugo
+linktitle: Configuration
+description: Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.
+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
+---
+
+The [directory structure][] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to generate a finished website.
+
+Because of Hugo's sensible defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns.
+
+## Configuration Lookup Order
+
+Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
+
+1. `./config.toml`
+2. `./config.yaml`
+3. `./config.json`
+
+In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
+
+## YAML Configuration
+
+The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
+
+{{< code file="config.yml">}}
+baseURL: "https://yoursite.example.com/"
+title: "My Hugo Site"
+footnoteReturnLinkContents: "↩"
+permalinks:
+ post: /:year/:month/:title/
+params:
+ Subtitle: "Hugo is Absurdly Fast!"
+ AuthorName: "Jon Doe"
+ GitHubUser: "spf13"
+ ListOfFoo:
+ - "foo1"
+ - "foo2"
+ SidebarRecentLimit: 5
+{{< /code >}}
+
+### All Variables, YAML
+
+The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
+
+{{< code file="config.yml" download="config.yml" >}}
+archetypeDir: "archetypes"
+# hostname (and path) to the root, e.g. http://spf13.com/
+baseURL: ""
+# include content marked as draft
+buildDrafts: false
+# include content with publishdate in the future
+buildFuture: false
+# include content already expired
+buildExpired: false
+# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See the "URL Management" page
+relativeURLs: false
+canonifyURLs: false
+# config file (default is path/config.yaml|json|toml)
+config: "config.toml"
+contentDir: "content"
+dataDir: "data"
- defaultExtension = "html"
+defaultLayout: "post"
+# Missing translations will default to this content language
+defaultContentLanguage: "en"
+# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
+defaultContentLanguageInSubdir: false
+disableLiveReload: false
+# Do not build RSS files
+disableRSS: false
+# Do not build Sitemap file
+disableSitemap: false
+# Enable GitInfo feature
+enableGitInfo: false
+# Build robots.txt file
+enableRobotsTXT: false
+# Do not render 404 page
+disable404: false
+# Do not inject generator meta tag on homepage
+disableHugoGeneratorInject: false
+# Allows you to disable all page types and will render nothing related to 'kind';
+# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
+disableKinds: []
+# Do not make the url/path to lowercase
+disablePathToLower: false ""
+# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
+enableEmoji: false
+# Show a placeholder instead of the default value or an empty string if a translation is missing
+enableMissingTranslationPlaceholders: false
+footnoteAnchorPrefix: ""
+footnoteReturnLinkContents: ""
+# google analytics tracking id
+googleAnalytics: ""
+# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
+hasCJKLanguage: false
+languageCode: ""
+# the length of text to show in a .Summary
+summaryLength: 70
+layoutDir: "layouts"
+# Enable Logging
+log: false
+# Log File path (if set, logging enabled automatically)
+logFile: ""
+# "toml","yaml", or "json"
+metaDataFormat: "toml"
+newContentEditor: ""
+# Don't sync permission mode of files
+noChmod: false
+# Don't sync modification time of files
+noTimes: false
+# Pagination
+paginate: 10
+paginatePath: "page"
+# See "content-management/permalinks"
+permalinks:
+# Pluralize titles in lists using inflect
+pluralizeListTitles: true
+# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
+preserveTaxonomyNames: false
+# filesystem path to write files to
+publishDir: "public"
+# enables syntax guessing for code fences without specified language
+pygmentsCodeFencesGuessSyntax: false
+# color-codes for highlighting derived from this style
+pygmentsStyle: "monokai"
+# true use pygments-css or false will color code directly
+pygmentsUseClasses: false
+# maximum number of items in the RSS feed
+rssLimit: 15
+# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
+SectionPagesMenu: ""
+# default sitemap configuration map
+sitemap:
+# filesystem path to read files relative from
+source: ""
+staticDir: "static"
+# display memory and timing of different steps of the program
+stepAnalysis: false
+# display metrics about template executions
+templateMetrics: false
+# theme to use (located by default in /themes/THEMENAME/)
+themesDir: "themes"
+theme: ""
+title: ""
+# Title Case style guide for the title func and other automatic title casing in Hugo.
+// Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1).
+// See https://www.apstylebook.com/ and http://www.chicagomanualofstyle.org/home.html
+titleCaseStyle: "AP"
+# if true, use /filename.html instead of /filename/
+uglyURLs: false
+# verbose output
+verbose: false
+# verbose logging
+verboseLog: false
+# watch filesystem for changes and recreate as needed
+watch: true
+taxonomies:
+ - category: "categories"
+ - tag: "tags"
+{{< /code >}}
+
+## TOML Configuration
+
+The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
+
+{{< code file="config.toml">}}
+contentDir = "content"
+layoutDir = "layouts"
+publishDir = "public"
+buildDrafts = false
+baseURL = "https://yoursite.example.com/"
+canonifyURLs = true
+title = "My Hugo Site"
+
+[taxonomies]
+ category = "categories"
+ tag = "tags"
+
+[params]
+ subtitle = "Hugo is Absurdly Fast!"
+ author = "John Doe"
+{{< /code >}}
+
+### All Variables, TOML
+
+The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.
+
+{{< code file="config.toml" download="config.toml">}}
+archetypeDir = "archetypes"
+# hostname (and path) to the root, e.g. http://spf13.com/
+baseURL = ""
+# include content marked as draft
+buildDrafts = false
+# include content with publishdate in the future
+buildFuture = false
+# include content already expired
+buildExpired = false
+# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
+relativeURLs = false
+canonifyURLs = false
+# config file (default is path/config.yaml|json|toml)
+config = "config.toml"
+contentDir = "content"
+dataDir = "data"
+defaultLayout = "post"
+# Missing translations will default to this content language
+defaultContentLanguage = "en"
+# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
+defaultContentLanguageInSubdir = false
+disableLiveReload = false
+# Do not build RSS files
+disableRSS = false
+# Do not build Sitemap file
+disableSitemap = false
+# Enable GitInfo feature
+enableGitInfo = false
+# Build robots.txt file
+enableRobotsTXT = false
+# Do not render 404 page
+disable404 = false
+# Do not inject generator meta tag on homepage
+disableHugoGeneratorInject = false
+# Allows you to disable all page types and will render nothing related to 'kind';
+# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
+disableKinds = []
+# Do not make the url/path to lowercase
+disablePathToLower = false
+# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
+enableEmoji = false
+# Show a placeholder instead of the default value or an empty string if a translation is missing
+enableMissingTranslationPlaceholders = false
+footnoteAnchorPrefix = ""
+footnoteReturnLinkContents = ""
+# google analytics tracking id
+googleAnalytics = ""
+# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
+hasCJKLanguage = false
+languageCode = ""
+# the length of text to show in a .Summary
+summaryLength = 70
+layoutDir = "layouts"
+# Enable Logging
+log = false
+# Log File path (if set, logging enabled automatically)
+logFile =
+# maximum number of items in the RSS feed
+rssLimit = 15
+# "toml","yaml", or "json"
+metaDataFormat = "toml"
+newContentEditor = ""
+# Don't sync permission mode of files
+noChmod = false
+# Don't sync modification time of files
+noTimes = false
+# Pagination
+paginate = 10
+paginatePath = "page"
+# See "content-management/permalinks"
+permalinks =
+# Pluralize titles in lists using inflect
+pluralizeListTitles = true
+# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
+preserveTaxonomyNames = false
+# filesystem path to write files to
+publishDir = "public"
+# enables syntax guessing for code fences without specified language
+pygmentsCodeFencesGuessSyntax = false
+# color-codes for highlighting derived from this style
+pygmentsStyle = "monokai"
+# true: use pygments-css or false: color-codes directly
+pygmentsUseClasses = false
+# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
+SectionPagesMenu =
+# default sitemap configuration map
+sitemap =
+# filesystem path to read static files relative from
+staticDir = "static"
+# display memory and timing of different steps of the program
+stepAnalysis = false
+# theme to use (located by default in /themes/THEMENAME/)
+themesDir = "themes"
+theme = ""
+title = ""
+# if true, use /filename.html instead of /filename/
+uglyURLs = false
+# verbose output
+verbose = false
+# verbose logging
+verboseLog = false
+# watch filesystem for changes and recreate as needed
+watch = true
+[taxonomies]
+ category = "categories"
+ tag = "tags"
+{{< /code >}}
+
+{{% 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 %}}
+
+## Environmental 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
+```
+
+{{% 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 %}}
+
+## 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 Blackfriday
+
+[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.
+
+Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well.
+
+However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)).
+
+{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}}
+
+{{% note %}}
+1. Blackfriday flags are *case sensitive* as of Hugo v0.15.
+2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
+{{% /note %}}
+
+{{< code file="bf-config.toml" >}}
+[blackfriday]
+ angledQuotes = true
+ fractions = false
+ plainIDAnchors = true
+ extensions = ["hardLineBreak"]
+{{< /code >}}
+
+{{< code file="bf-config.yml" >}}
+blackfriday:
+ angledQuotes: true
+ fractions: false
+ plainIDAnchors: true
+ extensions:
+ - hardLineBreak
+{{< /code >}}
+
+## Configure Additional Output Formats
+
+Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file.
+
+## Configuration Format Specs
+
+* [TOML Spec][toml]
+* [YAML Spec][yaml]
+* [JSON Spec][json]
+
+[`.Site.Params`]: /variables/site/
+[directory structure]: /getting-started/directory-structure
+[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
+[lookup order]: /templates/lookup-order/
+[Output Formats]: /templates/output-formats/
+[templates]: /templates/
+[toml]: https://github.com/toml-lang/toml
+[yaml]: http://yaml.org/spec/
--- /dev/null
- lastmod: 2017-02-20
+---
+title: Install Hugo
+linktitle: Install Hugo
+description: Install Hugo on macOS, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run.
+date: 2016-11-01
+publishdate: 2016-11-01
- ### Fedora, CentOS, and Red Hat
++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
+* 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]
+* [govendor][]
+
+#### Vendored Dependencies
+
+Hugo uses [govendor][] 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. *You must use `govendor` to fetch Hugo's dependencies.*
+
+#### Fetch from GitHub
+
+{{< code file="from-gh.sh" >}}
+go get github.com/kardianos/govendor
+govendor get github.com/gohugoio/hugo
+go install github.com/gohugoio/hugo
+{{< /code >}}
+
+`govendor get` will fetch Hugo and all its dependent libraries to `$GOPATH/src/github.com/gohugoio/hugo`, and `go install` compiles everything into a final `hugo` (or `hugo.exe`) executable inside `$GOPATH/bin/`.
+
+{{% 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 apt-get 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 -Sy 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].
+
+## 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
+[govendor]: https://github.com/kardianos/govendor
+[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
- wget https://github.com/gohugoio/hugo/releases/download/v0.25.1/hugo_0.25.1_Linux-64bit.tar.gz
- tar -xzf hugo_0.25.1_Linux-64bit.tar.gz
+---
+title: Host-Agnostic Deploys with Nanobox
+linktitle: Host-Agnostic Deploys with Nanobox
+description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more...
+date: 2017-08-24
+publishdate: 2017-08-24
+lastmod: 2017-08-24
+categories: [hosting and deployment]
+keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode]
+authors: [Steve Domino]
+menu:
+ docs:
+ parent: "hosting-and-deployment"
+ weight: 05
+weight: 05
+sections_weight: 05
+draft: false
+aliases: [/tutorials/deployment-with-nanobox/]
+toc: true
+---
+
+
+
+Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application.
+
+{{% note %}}
+If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox)
+{{% /note %}}
+
+
+## What You'll Need
+
+With Nanobox you don't need to worry about having Golang or Hugo installed. They'll be installed as part of the development environment created for you.
+
+To get started you'll just need the following three items:
+
+* [A Nanobox Account](https://nanobox.io) - Signup is free
+* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool
+* An account with a hosting provider such as:
+ - [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/)
+ - [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/)
+ - [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/)
+ - [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/)
+ - [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/)
+ - [More...](https://docs.nanobox.io/providers/hosting-accounts/)
+ - [Roll Your Own](https://docs.nanobox.io/providers/create/)
+
+### Before You Begin
+
+There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application.
+
+#### Connect a Host Account
+
+Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/).
+
+#### Launch a New Application on Nanobox
+
+[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region.
+
+With those out of the way you're ready to get started!
+
+
+## Getting Started
+
+{{% note %}}
+If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox)
+{{% /note %}}
+
+To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it:
+
+`mkdir path/to/project && cd path/to/project`
+
+### Configure Hugo to run with Nanobox
+
+Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`:
+
+{{< code file="boxfile.yml" >}}
+run.config:
+
+ # use the static engine
+ engine: static
+ engine.config:
+
+ # tell the engine where to serve static assets from
+ rel_dir: public
+
+ # enable file watching for live reload
+ fs_watch: true
+
+ # install hugo
+ extra_steps:
+ - bash ./install.sh
+
+deploy.config:
+
+ # generate site on deploy
+ extra_steps:
+ - hugo
+
+{{< /code >}}
+
+{{% note %}}
+If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox).
+{{% /note %}}
+
+### Installing Hugo
+
+Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available.
+
+Do this by adding a custom install script at the root of your project that will install Hugo automatically for you:
+
+{{< code file="install.sh" >}}
+
+#!/bin/bash
+
+if [[ ! -f /data/bin/hugo ]]; then
+ cd /tmp
++ wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz
++ tar -xzf hugo_0.31.1_Linux-64bit.tar.gz
+ mv hugo /data/bin/hugo
+ cd -
+ rm -rf /tmp/*
+fi
+
+{{< /code >}}
+
+{{% note %}}
+If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh`
+{{% /note %}}
++{{% note %}}
++Make sure to check the version of Hugo you have installed and update the install script to match.
++{{% /note %}}
+
+### Generating a New Hugo App
+
+You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Golang or Hugo installed).
+
+Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted:
+
+```
+nanobox run
+```
+
+
+
+Once inside the console use the following steps to create a new Hugo application:
+
+```
+# cd into the /tmp dir to create an app
+cd /tmp
+
+# generate the hugo app
+hugo new site app
+
+# cd back into the /app dir
+cd -
+
+# copy the generated app into the project
+shopt -s dotglob
+cp -a /tmp/app/* .
+```
+
+### Install a theme
+
+`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo:
+
+```
+cd themes
+git clone https://github.com/sdomino/nanobox-hugo-theme
+```
+
+To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml`
+
+```
+# copy the config.toml that comes with the theme
+cp ./themes/nanobox-hugo-theme/config.toml config.toml
+
+# or, add it to your existing config.toml
+theme = "nanobox-hugo-theme"
+```
+
+{{% note %}}
+It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced.
+{{% /note %}}
+
+### View Your App
+
+To view your application simply run the following command from a Nanobox console:
+
+```
+hugo server --bind="0.0.0.0" --baseUrl=$APP_IP
+```
+
+
+
+With that you should be able to visit your app at the given IP:1313 address
+
+{{% note %}}
+You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313)
+{{% /note %}}
+
+### Develop, Develop, Develop
+
+{{% note %}}
+IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox.
+{{% /note %}}
+
+With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy!
+
+
+## Deploying Hugo with Nanobox
+
+{{% note %}}
+If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard.
+{{% /note %}}
+
+To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command:
+
+```
+nanobox remote add <your-app-name>
+```
+
+{{% note %}}
+You may be prompted to login using your ***Nanobox credentials*** at this time
+{{% /note %}}
+
+### Stage Your Application (optional)
+
+Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to!
+
+To stage your app simply run:
+
+```
+nanobox deploy dry-run
+```
+
+Now visit your application with the IP address provided.
+
+
+
+### Deploy Your Application
+
+Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run:
+
+```
+nanobox deploy
+```
+
+Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it!
--- /dev/null
- If you are working within an Organization account or want to set up a User website on GitHub and would like more information, refer to the [GitHub Pages documentation][ghorgs].
+---
+title: Host on GitHub
+linktitle: Host on GitHub
+description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
+date: 2014-03-21
+publishdate: 2014-03-21
+lastmod: 2017-03-30
+categories: [hosting and deployment]
+keywords: [github,git,deployment,hosting]
+authors: [Spencer Lyon, Gunnar Morling]
+menu:
+ docs:
+ parent: "hosting-and-deployment"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+toc: true
+aliases: [/tutorials/github-pages-blog/]
+---
+
+GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][].
+
+## Assumptions
+
+1. You have Git 2.5 or greater [installed on your machine][installgit].
+2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
+3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
+
- Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `username.github.io/myprojectname/`) and not a custom domain.
++## Types of GitHub Pages
++
++There are 2 types of GitHub Pages:
++
++- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
++- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
++
++Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use.
++
++To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below.
++
++To create a Project Pages site, choose a method from the *Project Pages* section below.
++
++## GitHub User or Organization Pages
++
++As mentioned [the GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
++
++1. You must use a `<USERNAME>.github.io` to host your **generated** content
++2. Content from the `master` branch will be used to publish your GitHub Pages site
++
++This is a much simpler setup as your Hugo files and generated content are published into two different repositories.
++
++### Step-by-step Instructions
++
++1. Create a `<YOUR-PROJECT>` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files.
++2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
++3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
++4. Make your website work locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
++5. Once you are happy with the results:
++ * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
++ * `rm -rf public` to completely remove the `public` directory
++6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script.
++
++### Put it Into a Script
++
++You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`.
++
++The following are the contents of the `deploy.sh` script:
++
++```
++#!/bin/bash
++
++echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
++
++# Build the project.
++hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
++
++# Go To Public folder
++cd public
++# Add changes to git.
++git add .
++
++# Commit changes.
++msg="rebuilding site `date`"
++if [ $# -eq 1 ]
++ then msg="$1"
++fi
++git commit -m "$msg"
++
++# Push source and build repos.
++git push origin master
++
++# Come Back up to the Project Root
++cd ..
++```
++
++
++You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
++
++That's it! Your personal page should be up and running at `https://<USERNAME>.github.io` within a couple minutes.
++
++## GitHub Project Pages
+
+{{% note %}}
- ## Deployment via `/docs` Folder on Master Branch
++Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `<USERNAME>.github.io/<PROJECT>/`) and not a custom domain.
+{{% /note %}}
+
- ## Deployment From Your `gh-pages` Branch
++### Deployment of Project Pages from `/docs` folder on `master` branch
+
+[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
+
+```
+publishDir = "docs"
+```
+```
+publishDir: docs
+```
+
+After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
+
+1. Go to **Settings** → **GitHub Pages**
+2. From **Source**, select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
+
+{{% note %}}
+The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
+{{% /note %}}
+
- ### Preparations for `gh-pages` Branch
++### Deployment of Project Pages From Your `gh-pages` branch
+
+You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
+
+* It keeps your source and generated website in different branches and therefore maintains version control history for both.
+* Unlike the preceding `docs/` option, it uses the default `public` folder.
+
- #### Add the Public Folder
++#### Preparations for `gh-pages` Branch
+
+These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`:
+
- #### Initialize Your `gh-pages` Branch
++##### Add the `public` Folder
+
+First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
+
+```
+echo "public" >> .gitignore
+```
+
- ### Build and Deployment
++##### Initialize Your `gh-pages` Branch
+
+You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
+
+```
+git checkout --orphan gh-pages
+git reset --hard
+git commit --allow-empty -m "Initializing gh-pages branch"
+git push upstream gh-pages
+git checkout master
+```
+
- #### Set `gh-pages` as Your Publish Branch
++#### Build and Deployment
+
+Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
+
+```
+rm -rf public
+git worktree add -B gh-pages public upstream/gh-pages
+```
+
+Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
+
+{{< code file="commit-gh-pages-files.sh">}}
+hugo
+cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
+{{< /code >}}
+
+If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
+
+```
+git push upstream gh-pages
+```
+
- ### Put it Into a Script
++##### Set `gh-pages` as Your Publish Branch
+
+In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project:
+
+1. Go to **Settings** → **GitHub Pages**
+2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub.
+
+After a short while, you'll see the updated contents on your GitHub Pages site.
+
- ## Deployment From Your `master` Branch
++#### Put it Into a Script
+
+To automate these steps, you can create a script with the following contents:
+
+{{< code file="publish_to_ghpages.sh" >}}
+#!/bin/sh
+
+DIR=$(dirname "$0")
+
+cd $DIR/..
+
+if [[ $(git status -s) ]]
+then
+ echo "The working directory is dirty. Please commit any pending changes."
+ exit 1;
+fi
+
+echo "Deleting old publication"
+rm -rf public
+mkdir public
+git worktree prune
+rm -rf .git/worktrees/public/
+
+echo "Checking out gh-pages branch into public"
+git worktree add -B gh-pages public upstream/gh-pages
+
+echo "Removing existing files"
+rm -rf public/*
+
+echo "Generating site"
+hugo
+
+echo "Updating gh-pages branch"
+cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
+{{< /code >}}
+
+This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
+
- ## Host GitHub User or Organization Pages
-
- As mentioned [in this GitHub Help article](https://help.github.com/articles/user-organization-and-project-pages/), you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
-
- 1. You must use the `<USERNAME>.github.io` naming scheme for your GitHub repo.
- 2. Content from the `master` branch will be used to publish your GitHub Pages site.
-
- It becomes much simpler in this case: we'll create two separate repos, one for Hugo's content, and a git submodule with the `public` folder's content in it.
-
- ### Step-by-step Instructions
-
- 1. Create a `<YOUR-PROJECT>` git repository on GitHub. This repository will contain Hugo's content and other source files.
- 2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
- 3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
- 4. Make your website work locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
- 5. Once you are happy with the results:
- * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
- * `rm -rf public` to completely remove the `public` directory if there
- 6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script.
-
- #### Put it Into a Script
-
- You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`.
-
- The following are the contents of the `deploy.sh` script:
-
- ```
- #!/bin/bash
-
- echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
-
- # Build the project.
- hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
-
- # Go To Public folder
- cd public
- # Add changes to git.
- git add .
-
- # Commit changes.
- msg="rebuilding site `date`"
- if [ $# -eq 1 ]
- then msg="$1"
- fi
- git commit -m "$msg"
-
- # Push source and build repos.
- git push origin master
-
- # Come Back up to the Project Root
- cd ..
- ```
-
-
- You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
-
- That's it! Your personal page should be up and running at `https://yourusername.github.io` within a couple minutes.
-
++### Deployment of Project Pages from Your `master` Branch
+
+To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
+
+You will also need to set `master` as your publishable branch from within the GitHub UI:
+
+1. Go to **Settings** → **GitHub Pages**
+2. From **Source**, select "master branch" and then **Save**.
+
+## Use a Custom Domain
+
+If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages.
+
+Refer to the [official documentation for custom domains][domains] for further information.
+
+[config]: /getting-started/configuration/
+[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
+[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
+[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
+[ghsignup]: https://github.com/join
+[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
+[installgit]: https://git-scm.com/downloads
+[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt
+[Quick Start]: /getting-started/quick-start/
+[submodule]: https://github.com/blog/2104-working-with-submodules
+[worktree feature]: https://git-scm.com/docs/git-worktree
--- /dev/null
- [hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L166
+---
+title: Host on Netlify
+linktitle: Host on Netlify
+description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-11
+categories: [hosting and deployment]
+keywords: [netlify,hosting,deployment]
+authors: [Ryan Watters, Seth MacLeod]
+menu:
+ docs:
+ parent: "hosting-and-deployment"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: []
+toc: true
+---
+
+[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website.
+
+## Assumptions
+
+* You have an account with GitHub, GitLab, or Bitbucket.
+* You have completed the [Quick Start][] or have Hugo website you are ready to deploy and share with the world.
+* You do not already have a Netlify account.
+
+## Create a Netlify account
+
+Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address.
+
+The following examples use GitHub, but other git providers will follow a similar process.
+
+
+
+Selecting GitHub will bring up a typical modal you've seen through other application that use GitHub for authentication. Select "Authorize application."
+
+
+
+## Create a New Site with Continuous Deployment
+
+You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git."
+
+
+
+Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories.
+
+
+
+And then again with the GitHub authorization modal:
+
+
+
+Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search:
+
+
+
+Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
+
+### Build with a Specific Hugo Version
+
+Setting the build command to `hugo` will build your site according to the current default Hugo version used by Netlify. You can see the full list of [available Hugo versions in Netlify's Docker file][hugoversions].
+
+If you want to tell Netlify to build with a specific version (hugo <= 0.20), you can append an underscore followed by the version number to the build command:
+
+```
+hugo_0.19
+```
+
+Your simple configuration should now look similar to the following:
+
+
+
+For version hugo > 0.20 you have to [specify version hugo for testing and production](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
+
+For production:
+
+```
+[context.production.environment]
+ HUGO_VERSION = "0.26"
+```
+
+For testing:
+
+```
+[context.deploy-preview.environment]
+ HUGO_VERSION = "0.26"
+```
+
+Selecting "Deploy site" will immediately take you to a terminal for your build:.
+
+
+
+Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings."
+
+
+
+
+
+[Visit the live site][visit].
+
+Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site.
+
+## Use Hugo Themes with Netlify
+
+The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme.
+
+A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`:
+
+```
+cd themes
+git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
+```
+
+It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory.
+
+Switch to the theme's directory and list all available versions:
+
+```
+cd themes/<theme>
+git tag
+# exit with q
+```
+
+You can checkout a specific version as follows:
+
+```
+git checkout tags/<version-name>
+```
+
+## Next Steps
+
+You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation:
+
+1. [Using a Custom Domain][]
+2. [Setting up HTTPS on Custom Domains][httpscustom]
+3. [Redirects and Rewrite Rules][]
+
+
+[app.netlify.com]: https://app.netlify.com
+[build command]: /getting-started/usage/#the-hugo-command
+[config]: /getting-started/configuration/
+[ghsm]: https://github.com/blog/2104-working-with-submodules
+[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[httpscustom]: https://www.netlify.com/docs/ssl/
++[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216
+[installthemes]: /themes/installing/
+[netlify]: https://www.netlify.com/
+[netlifysignup]: https://app.netlify.com/signup
+[Quick Start]: /getting-started/quick-start/
+[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/
+[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/
+[visit]: https://hugo-netlify-example.netlify.com
--- /dev/null
- title: "0.33"
- description: "0.33"
- slug: "0.33"
+
+---
+date: 2018-01-18
++title: "Hugo 0.33: The New Kinder Surprise!"
++description: "Hugo 0.33 comes with resource (images etc.) metadata, `type` and `layout` for all page types, `url` in front matter for list pages …"
++slug: "0.33-relnotes"
+categories: ["Releases"]
++images:
++- images/blog/hugo-33-poster.png
++
+---
+
+ Hugo `0.33` is the first main Hugo release of the new year, and it is safe to say that [@bep](https://github.com/bep) has turned off his lazy Christmas mode :smiley:
+
+This is a full makeover of the layout selection logic with full custom `layout` and `type` support (many have asked for this). Also, Hugo now respects the `url` value in front matter for all page types, including sections. Also, you can now configure `uglyURLs` per section.
+
+But this release is also a follow-up to the `0.32` release which was all about bundles with resources and powerful image processing. With this release it is now simple to add metadata to your images and other bundle resources.
+
+[@bep](https://github.com/bep) has added a section with examples of both `resources` configuration in both `YAML` and `TOML` front matter in his [test site](http://hugotest.bep.is/resourcemeta/). The example below shows a sample of how it would look like in `YAML`:
+
+```yaml
+date: 2017-01-17
+title: My Bundle With YAML Resource Metadata
+resources:
+- src: "image-4.png"
+ title: "The Fourth Image"
+- src: "*.png"
+ name: "my-cool-image-:counter"
+ title: "The Image #:counter"
+ params:
+ byline: "bep"
+```
+
+This release represents **41 contributions by 3 contributors** to the main Hugo code base.
+
+Hugo now has:
+
+* 22553+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 448+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 197+ [themes](http://themes.gohugo.io/)
+
+## Notes
+* We have re-implemented and unified the template layout lookup logic. This has made it more powerful and much simpler to understand. We don't expect any sites to break because of this. We have tested lots of Hugo sites, including the 200 [themes](http://themes.gohugo.io/).
+* The `indexes` type is removed from template lookup. It's not in the documentation, and is a legacy term inherited from very old Hugo versions.
++* If you have sub-dirs in your shiny new bundles (e.g. `my-bundle/images`) and use the `*Prefix*` methods to find them, we have made an unintended change that affects you. See [this issue](https://github.com/gohugoio/hugo/issues/4295).
+
+## Enhancements
+
+### Templates
+
+* Respect `Type` and `Layout` for list template selection [51dd462c](https://github.com/gohugoio/hugo/commit/51dd462c3958f7cf032b06503f1f200a6aceebb9) [@bep](https://github.com/bep) [#3005](https://github.com/gohugoio/hugo/issues/3005)[#3245](https://github.com/gohugoio/hugo/issues/3245)
+
+### Core
+
+* Allow `url` in front matter for list type pages [8a409894](https://github.com/gohugoio/hugo/commit/8a409894bdb0972e152a2eccc47a2738568e1cfc) [@bep](https://github.com/bep) [#4263](https://github.com/gohugoio/hugo/issues/4263)
+* Improve `.Site.GetPage` for regular translated pages. Before this change it was not possible to say "get me the current language edition of the given content page if possible." Now you can do that by doing a lookup without any extensions: `.Site.GetPage "page" "post/mypost"` [9409bc0f](https://github.com/gohugoio/hugo/commit/9409bc0f799a8057836a14ccdf2833a55902175e) [@bep](https://github.com/bep) [#4285](https://github.com/gohugoio/hugo/issues/4285)
+* Add front matter metadata to `Resource` [20c9b6ec](https://github.com/gohugoio/hugo/commit/20c9b6ec81171d1c586ea31d5d08b40b0edaffc6) [@bep](https://github.com/bep) [#4244](https://github.com/gohugoio/hugo/issues/4244)
+* Implement `Resources.ByPrefix` [46db900d](https://github.com/gohugoio/hugo/commit/46db900dab9c0e6fcd9d227f10a32fb24f5c8bd9) [@bep](https://github.com/bep) [#4266](https://github.com/gohugoio/hugo/issues/4266)
+* Make `GetByPrefix` work for Page resources [60c9f3b1](https://github.com/gohugoio/hugo/commit/60c9f3b1c34b69771e25a66906f150f460d73223) [@bep](https://github.com/bep) [#4264](https://github.com/gohugoio/hugo/issues/4264)
+* Make `Resources.GetByPrefix` case insensitive [db85e834](https://github.com/gohugoio/hugo/commit/db85e83403913cff4b8737b138932b28e5bf6160) [@bep](https://github.com/bep) [#4258](https://github.com/gohugoio/hugo/issues/4258)
+* Update `Chroma` and other third-party deps [64f0e9d1](https://github.com/gohugoio/hugo/commit/64f0e9d1c1d4ff2249fd9cf9749e70485002b36d) [@bep](https://github.com/bep) [#4267](https://github.com/gohugoio/hugo/issues/4267)
+* Remove superflous `BuildDate` logic [13d53b31](https://github.com/gohugoio/hugo/commit/13d53b31f19240879122d6b7e4aaeb60b5130a3c) [@bep](https://github.com/bep) [#4272](https://github.com/gohugoio/hugo/issues/4272)
+* Run benchmarks 3 times [b6ea6d07](https://github.com/gohugoio/hugo/commit/b6ea6d07d0b072d850fb066c78976acd6c2f5e81) [@bep](https://github.com/bep)
+* Support `uglyURLs` per section [57e10f17](https://github.com/gohugoio/hugo/commit/57e10f174e51cc5e1cf5f37eed30a0f3b153dd64) [@bep](https://github.com/bep) [#4256](https://github.com/gohugoio/hugo/issues/4256)
+* Update CONTRIBUTING.md [1046e936](https://github.com/gohugoio/hugo/commit/1046e9363f2e382fd0b4aac838735ae4cbbebe5a) [@vassudanagunta](https://github.com/vassudanagunta)
+* Support offline builds [d5803da1](https://github.com/gohugoio/hugo/commit/d5803da1befba5446d1b2c1ad16f6467dc7b3991) [@vassudanagunta](https://github.com/vassudanagunta)
+
+## Fixes
+
+* Fix handling of mixed-case taxonomy folders with content file [2d3189b2](https://github.com/gohugoio/hugo/commit/2d3189b22760e0a8995dae082a6bc5480f770bfe) [@bep](https://github.com/bep) [#4238](https://github.com/gohugoio/hugo/issues/4238)
+* Fix handling of very long image file names [ecaf1451](https://github.com/gohugoio/hugo/commit/ecaf14514e06321823bdd10235cf23e7d654ba77) [@bep](https://github.com/bep) [#4261](https://github.com/gohugoio/hugo/issues/4261)
+* Update `Afero` to avoid panic on "file name is too long" [f8a119b6](https://github.com/gohugoio/hugo/commit/f8a119b606d55aa4f31f16e5a3cadc929c99e4f8) [@bep](https://github.com/bep) [#4240](https://github.com/gohugoio/hugo/issues/4240)
+* And now really fix the server watch logic [d4f8f88e](https://github.com/gohugoio/hugo/commit/d4f8f88e67f958b8010f90cb9b9854114e52dac2) [@bep](https://github.com/bep) [#4275](https://github.com/gohugoio/hugo/issues/4275)
+* Fix server without watch [4e524ffc](https://github.com/gohugoio/hugo/commit/4e524ffcfff48c017717e261c6067416aa56410f) [@bep](https://github.com/bep) [#4275](https://github.com/gohugoio/hugo/issues/4275)
+
+
+
+
+
+
--- /dev/null
- title: "0.34"
- description: "0.34"
- slug: "0.34"
+
+---
+date: 2018-01-22
- Hugo `0.33` is a small release. It contains a few smaller bug-fixes, but more important is an overhaul of the API used to find your images and other resources in your page bundles.
++title: "Hugo 0.34: Pattern matching to filter images and other resources"
++description: "Hugo 0.34 adds full glob with super-asterisk support, for example `*.jpg`."
++slug: "0.34-relnotes"
+categories: ["Releases"]
++images:
++- images/blog/hugo-34-poster.png
+---
+
+
- * When filtering bundles pages in sub-folders, you need to include the sub-folder when matching. This was a bug introduced in `0.32` and gets it in line with images and other resources.
++Hugo `0.34` is a small release. It contains a few smaller bug-fixes, but more important is an overhaul of the API used to find images and other resources in your page bundles.
+
+We have added two simple methods on the `Resources` object:
+
+* `.Match` finds every resource matching a pattern. Examples: `.Match "images/*.jpg"` finds every JPEG image in `images` and `.Match "**.jpg"` finds every JPEG image in the bundle.
+* `.GetMatch` finds the first resource matching the pattern given.
+
+**Note: The path separators used are Unix-style forward slashes, even on Windows.**
+
+It uses [standard wildcard syntax](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) with the addition of the `**`, aka super-asterisk, which matches across path boundaries.
+
+Thanks to [@gobwas](https://github.com/gobwas/glob) for a fast and easy-to-use Glob library.
+
+This release represents **5 contributions by 1 contributors** to the main Hugo code base.
+
+Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs),
+which has received **25 contributions by 16 contributors**. A special thanks to [@bep](https://github.com/bep), [@rmetzler](https://github.com/rmetzler), [@chris-rudmin](https://github.com/chris-rudmin), and [@stkevintan](https://github.com/stkevintan) for their work on the documentation site.
+
+
+Hugo now has:
+
+* 22689+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 448+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 197+ [themes](http://themes.gohugo.io/)
+
+## Notes
+* `Resources.GetByPrefix` and `Resources.ByPrefix` are depracated. They still work, but will eventually be removed. Use `Resources.Match` (many) and `Resources.GetMatch` (one).
++* When filtering bundles pages in sub-folders, you need to include the sub-folder when matching. This was a bug introduced in `0.33` and gets it in line with images and other resources.
+
+## Enhancements
+
+* Add `Resources.Match` and `Resources.GetMatch` [94213801](https://github.com/gohugoio/hugo/commit/9421380168f66620cb73203e1267814b3086d805) [@bep](https://github.com/bep) [#4301](https://github.com/gohugoio/hugo/issues/4301)
+
+## Fixes
+* Add validation for `defaultContentLanguage` [4d5e4f37](https://github.com/gohugoio/hugo/commit/4d5e4f379a890a3c6cbc11ddb40d77a90f14c015) [@bep](https://github.com/bep) [#4298](https://github.com/gohugoio/hugo/issues/4298)
+* Fix lookup of pages bundled in sub-folders in `ByPrefix` etc. [5d030869](https://github.com/gohugoio/hugo/commit/5d03086981b4a7d4bc450269a6a2e0fd22dbeed7) [@bep](https://github.com/bep) [#4295](https://github.com/gohugoio/hugo/issues/4295)
+
+
+
+
+
--- /dev/null
- The [lookup order][lookup] for the homepage template is as follows:
-
- 1. `/layouts/index.html`
- 2. `/layouts/_default/list.html`
- 3. `/themes/<THEME>/layouts/index.html`
- 4. `/themes/<THEME>/layouts/_default/list.html`
+---
+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.
+
+## `.Data.Pages` on the Homepage
+
+In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Data.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 .Data.Pages is the equivalent of .Site.Pages on the homepage template. -->
+ {{ range first 10 .Data.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
+---
+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`:
+
+#### Default Section Templates
+
+1. `layouts/_default/section.html`
+2. `layouts/_default/list.html`
+
+#### Default Taxonomy List Templates
+
+1. `layouts/_default/taxonomy.html`
+2. `themes/<THEME>/layouts/_default/taxonomy.html`
+
+## 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 Golang Journey
+date: 2017-03-23
+publishdate: 2017-03-24
+---
+
+I decided to start learning Golang 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 }}
+ <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 Golang Journey</h1>
+ </header>
+ <p>I decided to start learning Golang 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 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 }}
+ {{ .Render "li"}}
+ {{ end }}
+ </ul>
+ </div>
+</main>
+{{ partial "footer.html" . }}
+{{< /code >}}
+
+### Taxonomy Template
+
+{{< code file="layouts/_default/taxonomies.html" download="taxonomies.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 }}
+ {{ .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 }}
+ <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" >}}
+<ul>
+ {{ range .Data.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.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.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.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.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.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.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.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 "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.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.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" }}
+<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.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.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.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.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 Golang's layout string. See the [`Format` function][] for more examples of how to use Golang'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.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.GroupBy "Section").Reverse }}
+```
+
+```
+{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
+```
+
+#### 2. Providing the Alternate Direction
+
+```
+{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
+```
+
+```
+{{ range .Data.Pages.GroupBy "Section" "desc" }}
+```
+
+### Order Within Groups
+
+Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available.
+
+Here is the ordering for the example that follows:
+
+1. Content is grouped by month according to the `date` field in front matter.
+2. Groups are listed in ascending order (i.e., the oldest groups first)
+3. Pages within each respective group are ordered alphabetically according to the `title`.
+
+{{< code file="layouts/partials/by-group-by-page.html" >}}
+{{ range .Data.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`
+
+{{< code file="layouts/_default/.html" >}}
+{{ range where .Data.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 10 .Data.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 .Data.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
- description: The lookup order is a prioritized list used by Hugo as it traverses your files looking for the appropriate corresponding file to render your content.
+---
+title: Hugo's Lookup Order
+linktitle: Template Lookup Order
- keywords: [lookup]
++description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-05-25
+categories: [templates,fundamentals]
- Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
++keywords: [templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 15
+ quicklinks:
+weight: 15
+sections_weight: 15
+draft: false
+aliases: [/templates/lookup/]
+toc: true
+---
+
- Hugo uses a prioritized list called the **lookup order** as it traverses your `layouts` folder in your Hugo project *looking* for the appropriate template to render your content.
++## Hugo Layouts Lookup Rules
+
- The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `_default/` directory for your project or theme. In many ways, the lookup order is similar to the programming concept of a [switch statement without fallthrough][switch].
++Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
+
- The power of the lookup order is that it enables you to craft specific layouts and keep your templating [DRY][].
+
- {{% note %}}
- Most Hugo websites will only need the default template files at the end of the lookup order (i.e. `_default/*.html`).
- {{% /note %}}
-
- ## Lookup Orders
++Kind
++: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML).
+
- The respective lookup order for each of Hugo's templates has been defined throughout the Hugo docs:
++Output Format
++: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates.
+
- * [Homepage Template][home]
- * [Base Templates][base]
- * [Section Page Templates][sectionlookup]
- * [Taxonomy List Templates][taxonomylookup]
- * [Taxonomy Terms Templates][termslookup]
- * [Single Page Templates][singlelookup]
- * [RSS Templates][rsslookup]
- * [Shortcode Templates][sclookup]
++Language
++: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but we will `index.amp.html` will be chosen before `index.fr.html`.
+
- ## Template Lookup Examples
++Layout
++: Can be set in page front matter.
+
- The lookup order is best illustrated through examples. The following shows you the process Hugo uses for finding the appropriate template to render your [single page templates][], but the concept holds true for all templates in Hugo.
++Type
++: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). If will always have a value, so if not set, the value is "page".
+
- 1. The project is using the theme `mytheme` (specified in the project's [configuration][config]).
- 2. The layouts and content directories for the project are as follows:
-
- ```
- .
- ├── content
- │ ├── events
- │ │ ├── _index.md
- │ │ └── my-first-event.md
- │ └── posts
- │ ├── my-first-post.md
- │ └── my-second-post.md
- ├── layouts
- │ ├── _default
- │ │ └── single.html
- │ ├── posts
- │ │ └── single.html
- │ └── reviews
- │ └── reviewarticle.html
- └── themes
- └── mytheme
- └── layouts
- ├── _default
- │ ├── list.html
- │ └── single.html
- └── posts
- ├── list.html
- └── single.html
++Section
++: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types.
+
-
-
- Now we can look at the front matter for the three content (i.e.`.md`) files.
-
- {{% note %}}
- Only three of the four markdown files in the above project are subject to the *single* page lookup order. `_index.md` is a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are used to add content and front matter to [list pages](/templates/lists/). In this example, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
++{{% note %}}
++**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates:
++
++```bash
++├── _default
++│ ├── baseof.html
++│ ├── list.html
++│ └── single.html
++└── index.html
+```
- ### Example: `my-first-post.md`
+{{% /note %}}
+
- {{< code file="content/posts/my-first-post.md" copy="false" >}}
- ---
- title: My First Post
- date: 2017-02-19
- description: This is my first post.
- ---
- {{< /code >}}
+
- When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`:
++## Hugo Layouts Lookup Rules With Theme
+
- 1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
- 2. ~~`/layouts/posts/UNSPECIFIED.html`~~
- 3. ~~`/layouts/UNSPECIFIED/single.html`~~
- 4. <span class="yes">`/layouts/posts/single.html`</span>
- <br><span class="break">BREAK</span>
- 5. <span class="na">`/layouts/_default/single.html`</span>
- 6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
- 7. <span class="na">`/themes/<THEME>/layouts/posts/UNSPECIFIED.html`</span>
- 8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
- 9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
- 10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
++In Hugo, layouts can live in either the project's or theme's layout folder, and the most specific layout will be chosen. Hugo will interleave the lookups:
+
- Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][sections].)
+
- `my-first-post.md` also does not specify a `layout` in its front matter. Therefore, Hugo assumes that `my-first-post.md`, which is of type `page` and a *single* piece of content, should default to the next occurrence of a `single.html` template in the lookup (#4).
++1. layouts/page/index.html
++2. demoTheme/layouts/page/index.html
++3. layouts/...
+
- ### Example: `my-second-post.md`
++This way it is possible to override specific templates from the theme.
+
- {{< code file="content/posts/my-second-post.md" copy="false" >}}
- ---
- title: My Second Post
- date: 2017-02-21
- description: This is my second post.
- type: review
- layout: reviewarticle
- ---
- {{< /code >}}
++## Examples: Layout Lookup for Regular Pages
+
- Here is the way Hugo traverses the single-page lookup order for `my-second-post.md`:
++{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
- 1. <span class="yes">`/layouts/review/reviewarticle.html`</span>
- <br><span class="break">BREAK</span>
- 2. <span class="na">`/layouts/posts/reviewarticle.html`</span>
- 3. <span class="na">`/layouts/review/single.html`</span>
- 4. <span class="na">`/layouts/posts/single.html`</span>
- 5. <span class="na">`/layouts/_default/single.html`</span>
- 6. <span class="na">`/themes/<THEME>/layouts/review/reviewarticle.html`</span>
- 7. <span class="na">`/themes/<THEME>/layouts/posts/reviewarticle.html`</span>
- 8. <span class="na">`/themes/<THEME>/layouts/review/single.html`</span>
- 9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
- 10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
++## Examples: Layout Lookup for Home Page
+
- The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
++{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
- {{% note "Type and not Types" %}}
- Notice that the directory for the template for `my-second-post.md` is `review` and not `reviews`. This is because *type is always singular when defined in front matter*.
- {{% /note%}}
++## Examples: Layout Lookup for Section Pages
+
- ### Example: `my-first-event.md`
++{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
- {{< code file="content/events/my-first-event.md" copy="false" >}}
- ---
- title: My First
- date: 2017-02-21
- description: This is an upcoming event..
- ---
- {{< /code >}}
++## Examples: Layout Lookup for Taxonomy List Pages
+
- Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:
++{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
- 1. ~~`/layouts/UNSPECIFIED/UNSPECIFIED.html`~~
- 2. ~~`/layouts/events/UNSPECIFIED.html`~~
- 3. ~~`/layouts/UNSPECIFIED/single.html`~~
- 4. ~~`/layouts/events/single.html`~~
- 5. <span class="yes">`/layouts/_default/single.html`</span>
- <br><span class="break">BREAK</span>
- 6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
- 7. <span class="na">`/themes/<THEME>/layouts/events/UNSPECIFIED.html`</span>
- 8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
- 9. <span class="na">`/themes/<THEME>/layouts/events/single.html`</span>
- 10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
++## Examples: Layout Lookup for Taxonomy Terms Pages
++
++{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
- {{% note %}}
- `my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream.
- {{% /note %}}
+
+
- [base]: /templates/base/#base-template-lookup-order
- [config]: /getting-started/configuration/
- [directory structure]: /getting-started/directory-structure/
- [DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
- [home]: /templates/homepage/#homepage-template-lookup-order
- [rsslookup]: /templates/rss/#rss-template-lookup-order
- [sclookup]: /templates/shortcode-templates/#shortcode-template-lookup-order
- [sections]: /content-management/sections/
- [sectionlookup]: /templates/section-templates/#section-template-lookup-order
- [single page templates]: /templates/single-page-templates/
- [singlelookup]: /templates/single-page-templates/#single-page-template-lookup-order
- [switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
- [taxonomylookup]: /templates/taxonomy-templates/#taxonomy-list-template-lookup-order
- [termslookup]: /templates/taxonomy-templates/#taxonomy-terms-template-lookup-order
+
--- /dev/null
- <div id="sidebar" class="nav-collapse">
- <!-- sidebar menu start-->
- <ul class="sidebar-menu">
- {{ $currentPage := . }}
- {{ range .Site.Menus.main }}
- {{ if .HasChildren }}
-
- <li class="sub-menu{{if $currentPage.HasMenuCurrent "main" . }} active{{end}}">
- <a href="javascript:;" class="">
- {{ .Pre }}
- <span>{{ .Name }}</span>
- <span class="menu-arrow arrow_carrot-right"></span>
- </a>
- <ul class="sub">
- {{ range .Children }}
- <li{{if $currentPage.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.URL}}"> {{ .Name }} </a> </li>
- {{ end }}
- </ul>
- {{else}}
- <li>
- <a href="{{.URL}}">
- {{ .Pre }}
- <span>{{ .Name }}</span>
- </a>
- {{end}}
- </li>
- {{end}}
- <li> <a href="https://github.com/gohugoio/hugo/issues" target="blank">Questions and Issues</a> </li>
- <li> <a href="#" target="blank">Edit this Page</a> </li>
- </ul>
- <!-- sidebar menu end-->
- </div>
+---
+title: Menu Templates
+linktitle: Menu Templates
+description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [lists,sections,menus]
+menu:
+ docs:
++ title: "how to use menus in templates"
+ parent: "templates"
+ weight: 130
+weight: 130
+sections_weight: 130
+draft: false
+aliases: [/templates/menus/]
+toc: false
+---
+
+Hugo makes no assumptions about how your rendered HTML will be
+structured. Instead, it provides all of the functions you will need to be
+able to build your menu however you want.
+
+The following is an example:
+
+{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
+<!-- sidebar start -->
+<aside>
- <!--sidebar end-->
++ <ul>
++ {{ $currentPage := . }}
++ {{ range .Site.Menus.main }}
++ {{ if .HasChildren }}
++ <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
++ <a href="#">
++ {{ .Pre }}
++ <span>{{ .Name }}</span>
++ </a>
++ <ul class="sub-menu">
++ {{ range .Children }}
++ <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
++ <a href="{{ .URL }}">{{ .Name }}</a>
++ {{ end }}
++ </ul>
++ {{else}}
++ <li>
++ <a href="{{.URL}}">
++ {{ .Pre }}
++ <span>{{ .Name }}</span>
++ </a>
++ {{end}}
++ {{end}}
++ <li>
++ <a href="#" target="blank">Hardcoded Link 1</a>
++ <li>
++ <a href="#" target="blank">Hardcoded Link 2</a>
++ </ul>
+</aside>
- <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{.URL}}">{{ .Name }}</a>
+{{< /code >}}
+
+{{% note "`absLangURL` and `relLangURL`" %}}
+Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url.
+{{% /note %}}
+
+## Section Menu for Lazy Bloggers
+
+To enable this menu, configure `sectionPagesMenu` in your site `config`:
+
+```
+sectionPagesMenu = "main"
+```
+
+The menu name can be anything, but take a note of what it is.
+
+This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
+
+```
+<nav class="sidebar-nav">
+ {{ $currentPage := . }}
+ {{ range .Site.Menus.main }}
- The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
++ <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a>
+ {{ end }}
+</nav>
+```
+
+In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
+
++
++## Site Config menus
++
++The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config, i.e. `config.toml`:
+
+```
+[[menu.main]]
+ name = "This is the blog section"
++ title = "blog section"
+ weight = -110
+ identifier = "blog"
+ url = "/blog/"
+```
+
+{{% note %}}
+The `identifier` *must* match the section name.
+{{% /note %}}
++
++## Menu Entries from the Page's front matter
++
++It's also possible to create menu entries from the page (i.e. the `.md`-file).
++
++Here is a `yaml` example:
++
++```
++---
++title: Menu Templates
++linktitle: Menu Templates
++menu:
++ docs:
++ title: "how to use menus in templates"
++ parent: "templates"
++ weight: 130
++---
++...
++```
++
++{{% note %}}
++You can define more than one menu. It also doesn't have to be a complex value,
++`menu` can also be a string, an array of strings, or an array of complex values
++like in the example above.
++{{% /note %}}
++
++### Using .Page in Menus
++
++If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable.
++This allows to use every variable that's reachable from the [page variable](/variables/page/).
++
++This variable is only set when the menu entry is defined in the page's front matter.
++Menu entries from the site config don't know anything about `.Page`.
++
++That's why you have to use the go template's `with` keyword or something similar in your templating language.
++
++Here's an example:
++
++```
++<nav class="sidebar-nav">
++ {{ range .Site.Menus.main }}
++ <a href="{{ .URL }}" title="{{ .Title }}">
++ {{- .Name -}}
++ {{- with .Page -}}
++ <span class="date">
++ {{- dateFormat " (2006-01-02)" .Date -}}
++ </span>
++ {{- end -}}
++ </a>
++ {{ end }}
++</nav>
++```
--- /dev/null
- keywords: [rss, xml]
+---
+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
- You can use a single RSS template to generate all of your RSS feeds or create a specific template for each individual feed.
-
- 1. `/layouts/section/<section>.rss.xml`
- 2. `/layouts/_default/rss.xml`
- 3. `/themes/<theme>/layouts/section/<section>.rss.xml`
- 4. `/themes/<theme>/layouts/_default/rss.xml`
++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](/templates/lookup-order/).
+
+{{% 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
+
+### Main RSS
+
+1. `/layouts/rss.xml`
+2. `/layouts/_default/rss.xml`
+3. Embedded rss.xml
+
+### Section RSS
+
+1. `/layouts/section/<SECTION>.rss.xml`
+2. `/layouts/_default/rss.xml`
+3. `/themes/<THEME>/layouts/section/<SECTION>.rss.xml`
+4. `/themes/<THEME>/layouts/_default/rss.xml`
+5. Embedded rss.xml
+
+### Taxonomy RSS
+
+1. `/layouts/taxonomy/<SINGULAR>.rss.xml`
+2. `/layouts/_default/rss.xml`
+3. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.rss.xml`
+4. `/themes/<THEME>/layouts/_default/rss.xml`
+5. Embedded rss.xml
+
+## 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:
+
+```
+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].
+
+```
+<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 .Data.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 like this:
+
+```
+{{ if .RSSLink }}
+ <link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
+ <link href="{{ .RSSLink }}" rel="feed" type="application/rss+xml" title="{{ .Site.Title }}" />
+{{ end }}
+```
+
+...with the auto-discovery link specified by the line with `rel="alternate"`.
+
+The `.RSSLink` will render the appropriate RSS feed URL for the section, whether it's everything, posts in a section, or a taxonomy.
+
+If you reference your RSS link, be sure to specify the MIME type with `type="application/rss+xml"`.
+
+```
+<a href="{{ .URL }}" type="application/rss+xml" target="_blank">{{ .SomeText }}</a>
+```
+
+[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/
--- /dev/null
- keywords: [lists,sections]
+---
+title: Section Page Templates
+linktitle: Section Templates
+description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
- The [lookup order][lookup] for section templates is as follows:
-
- 1. `/layouts/section/<SECTION>.html`
- 2. `/layouts/<SECTION>/list.html`
- 3. `/layouts/_default/section.html`
- 4. `/layouts/_default/list.html`
- 5. `/themes/<THEME>/layouts/section/<SECTION>.html`
- 6. `/themes/<THEME>/layouts/<SECTION>/list.html`
- 7. `/themes/<THEME>/layouts/_default/section.html`
- 8. `/themes/<THEME>/layouts/_default/list.html`
-
- {{< youtube jrMClsB3VsY >}}
++keywords: [lists,sections,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 40
+weight: 40
+sections_weight: 40
+draft: false
+aliases: [/templates/sections/]
+toc: true
+---
+
+## Add Content and Front Matter to Section Templates
+
+To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages.
+
+## Section Template Lookup Order
+
++See [Template Lookup](/templates/lookup-order/).
+
+## `.Site.GetPage` with Sections
+
+Every `Page` in Hugo has a `.Kind` attribute. `Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path.
+
+The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`.
+
+{{% note %}}
+`.GetPage` is not currently supported to grab single content files but *may* be supported in the future.
+{{% /note %}}
+
+You can call `.Site.GetPage` with two arguments: `kind` and `kind value`.
+
+These are the valid values for 'kind':
+
+1. `home`
+2. `section`
+3. `taxonomy`
+4. `taxonomyTerm`
+
+
+## Example: Creating a Default Section Template
+
+{{< code file="layouts/_default/section.html" download="section.html" >}}
+{{ define "main" }}
+ <main>
+ {{ .Content }}
+ <ul class="contents">
+ {{ range .Paginator.Pages }}
+ <li>{{.Title}}
+ <div>
+ {{ partial "summary.html" . }}
+ </div>
+ </li>
+ {{ end }}
+ </ul>
+ {{ partial "pagination.html" . }}
+ </main>
+{{ end }}
+{{< /code >}}
+
+### Example: Using `.Site.GetPage`
+
+The `.Site.GetPage` example that follows assumes the following project directory structure:
+
+```
+.
+└── content
+ ├── blog
+ │ ├── _index.md # "title: My Hugo Blog" in the front matter
+ │ ├── post-1.md
+ │ ├── post-2.md
+ │ └── post-3.md
+ └── events #Note there is no _index.md file in "events"
+ ├── event-1.md
+ └── event-2.md
+```
+
+`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
+
+```
+<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
+```
+
+Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
+
+```
+<h1>My Hugo Blog</h1>
+```
+
+If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
+
+```
+<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
+```
+
+Which then returns the following:
+
+```
+<h1>Events</h1>
+```
+
+
+[contentorg]: /content-management/organization/
+[getpage]: /functions/getpage/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[where]: /functions/where/
--- /dev/null
- keywords: [shortcodes]
+---
+title: Create Your Own Shortcodes
+linktitle: Shortcode Templates
+description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
++keywords: [shortcodes,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 100
+weight: 100
+sections_weight: 100
+draft: false
+aliases: []
+toc: true
+---
+
+Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][].
+
+{{% note %}}
+Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
+{{% /note %}}
+
+## Create Custom Shortcodes
+
+Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
+
+{{< youtube Eu4zSaKOY4A >}}
+
+### File Placement
+
+To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
+
+### Shortcode Template Lookup Order
+
+Shortcode templates have a simple [lookup order][]:
+
+1. `/layouts/shortcodes/<SHORTCODE>.html`
+2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
+
+### Positional vs Named Parameters
+
+You can create shortcodes using the following types of parameters:
+
+* Positional parameters
+* Named parameters
+* Positional *or* named parameters (i.e, "flexible")
+
+In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
+
+For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
+
+Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
+
+### Access Parameters
+
+All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
+
+To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
+
+```
+{{ .Get "class" }}
+```
+
+To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
+
+```
+{{ .Get 0 }}
+```
+
+`with` is great when the output depends on a parameter being set:
+
+```
+{{ with .Get "class"}} class="{{.}}"{{ end }}
+```
+
+`.Get` can also be used to check if a parameter has been provided. This is
+most helpful when the condition depends on either of the values, or both:
+
+```
+{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
+```
+
+#### `.Inner`
+
+If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence.
+
+A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax:
+
+```
+{{</* innershortcode /*/>}}
+```
+
+#### `.Params`
+
+The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
+
+`$.Params`
+: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
+
+`$.Page.Params`
+: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
+
+`$.Page.Site.Params`
+: refers to global variables as defined in your [site's configuration file][config].
+
+#### `.IsNamedParams`
+
+The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
+
+For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
+
+```
+{{</* image src="images/my-image.jpg"*/>}}
+```
+
+You could then include the following as part of your shortcode templating:
+
+```
+{{ if .IsNamedParams }}
+<img src="{{.Get "src" }}" alt="">
+{{ else }}
+<img src="{{.Get 0}}" alt="">
+{{ end }}
+```
+
+See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
+
+{{% warning %}}
+While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
+{{% /warning %}}
+
+You can also use the variable `.Page` to access all the normal [page variables][pagevars].
+
+A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
+
++### Checking for Existence
++
++You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
++
+## Custom Shortcode Examples
+
+The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`.
+
+### Single-word Example: `year`
+
+Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows:
+
+```
+{{</* year */>}}
+```
+
+{{< code file="/layouts/shortcodes/year.html" >}}
+{{ now.Format "2006" }}
+{{< /code >}}
+
+### Single Positional Example: `youtube`
+
+Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
+
+```
+{{</* youtube 09jf3ow9jfw */>}}
+```
+
+Would load the template at `/layouts/shortcodes/youtube.html`:
+
+{{< code file="/layouts/shortcodes/youtube.html" >}}
+<div class="embed video-player">
+<iframe class="youtube-player" type="text/html" width="640" height="385" src="http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
+</iframe>
+</div>
+{{< /code >}}
+
+{{< code file="youtube-embed.html" copy="false" >}}
+<div class="embed video-player">
+ <iframe class="youtube-player" type="text/html"
+ width="640" height="385"
+ src="http://www.youtube.com/embed/09jf3ow9jfw"
+ allowfullscreen frameborder="0">
+ </iframe>
+</div>
+{{< /code >}}
+
+### Single Named Example: `image`
+
+Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
+
+{{< code file="content-image.md" >}}
+{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
+
+{{< code file="/layouts/shortcodes/img.html" >}}
+<!-- image -->
+<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
+ {{ with .Get "link"}}<a href="{{.}}">{{ end }}
+ <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
+ {{ if .Get "link"}}</a>{{ end }}
+ {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
+ <figcaption>{{ if isset .Params "title" }}
+ <h4>{{ .Get "title" }}</h4>{{ end }}
+ {{ if or (.Get "caption") (.Get "attr")}}<p>
+ {{ .Get "caption" }}
+ {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
+ {{ .Get "attr" }}
+ {{ if .Get "attrlink"}}</a> {{ end }}
+ </p> {{ end }}
+ </figcaption>
+ {{ end }}
+</figure>
+<!-- image -->
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="img-output.html" copy="false" >}}
+<figure >
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /code >}}
+
+### Single Flexible Example: `vimeo`
+
+```
+{{</* vimeo 49718712 */>}}
+{{</* vimeo id="49718712" class="flex-video" */>}}
+```
+
+Would load the template found at `/layouts/shortcodes/vimeo.html`:
+
+{{< code file="/layouts/shortcodes/vimeo.html" >}}
+{{ if .IsNamedParams }}
+ <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="//player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
+ </div>
+{{ else }}
+ <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
+ <iframe src="//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="vimeo-iframes.html" copy="false" >}}
+<div class="vimeo-container">
+ <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+<div class="flex-video">
+ <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+{{< /code >}}
+
+### Paired Example: `highlight`
+
+The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
+
+{{< code file="highlight-example.md" >}}
+{{</* highlight html */>}}
+ <html>
+ <body> This HTML </body>
+ </html>
+{{</* /highlight */>}}
+{{< /code >}}
+
+The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
+
+```
+{{ .Get 0 | highlight .Inner }}
+```
+
+The rendered output of the HTML example code block will be as follows:
+
+{{< code file="syntax-highlighted.html" copy="false" >}}
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
+ <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
+<span style="color: #f92672"></html></span>
+</pre></div>
+{{< /code >}}
+
+{{% note %}}
+The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information.
+{{% /note %}}
+
+### Nested Shortcode: Image Gallery
+
+Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
+
+The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
+
+{{< code file="layouts/shortcodes/gallery.html" >}}
+<div class="{{.Get "class"}}">
+ {{.Inner}}
+</div>
+{{< /code >}}
+
+You also have an `image` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes so that the parent defines the context of each `image`:
+
+{{< code file="layouts/shortcodes/image.html" >}}
+{{- $src := .Get "src" -}}
+{{- with .Parent -}}
+ <img src="{{$src}}" class="{{.Get "class"}}-image">
+{{- else -}}
+ <img src="{{$src}}">
+{{- end }}
+{{< /code >}}
+
+You can then call your shortcode in your content as follows:
+
+```
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `image` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `image` only uses `src`:
+
+```
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+## More Shortcode Examples
+
+More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
+
+[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
+[built-in shortcode]: /content-management/shortcodes/
+[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website."
+[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files."
+[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
+[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
+[figure]: /content-management/shortcodes/#figure
+[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
+[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time"
+[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates."
+[parent]: /variables/shortcodes/
+[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
+[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
+[templates]: /templates/ "The templates section of the Hugo docs."
+[vimeoexample]: #single-flexible-example-vimeo
+[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
--- /dev/null
- keywords: [page]
+---
+title: Single Page Templates
+linktitle:
+description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-04-06
+categories: [templates]
- You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]).
-
- Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.
-
- 1. `/layouts/<TYPE>/<LAYOUT>.html`
- 2. `/layouts/<SECTION>/<LAYOUT>.html`
- 3. `/layouts/<TYPE>/single.html`
- 4. `/layouts/<SECTION>/single.html`
- 5. `/layouts/_default/single.html`
- 6. `/themes/<THEME>/layouts/<TYPE>/<LAYOUT>.html`
- 7. `/themes/<THEME>/layouts/<SECTION>/<LAYOUT>.html`
- 8. `/themes/<THEME>/layouts/<TYPE>/single.html`
- 9. `/themes/<THEME>/layouts/<SECTION>/single.html`
- 10. `/themes/<THEME>/layouts/_default/single.html`
-
- {{< youtube ZYQ5k0RQzmo >}}
++keywords: [page,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: [/layout/content/]
+toc: true
+---
+
+## Single Page Template Lookup Order
+
++See [Template Lookup](/templates/lookup-order/).
+
+## Example Single Page Templates
+
+Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
+
+### `post/single.html`
+
+This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
+
+{{< code file="layouts/post/single.html" download="single.html" >}}
+{{ define "main" }}
+<section id="main">
+ <h1 id="title">{{ .Title }}</h1>
+ <div>
+ <article id="content">
+ {{ .Content }}
+ </article>
+ </div>
+</section>
+<aside id="meta">
+ <div>
+ <section>
+ <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
+ <h5 id="wordcount"> {{ .WordCount }} Words </h5>
+ </section>
+ {{ with .Params.topics }}
+ <ul id="topics">
+ {{ range . }}
+ <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ {{ with .Params.tags }}
+ <ul id="tags">
+ {{ range . }}
+ <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </div>
+ <div>
+ {{ with .PrevInSection }}
+ <a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
+ {{ end }}
+ {{ with .NextInSection }}
+ <a class="next" href="{{.Permalink}}"> {{.Title}}</a>
+ {{ end }}
+ </div>
+</aside>
+{{ end }}
+{{< /code >}}
+
+To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
+
+[archetypes]: /content-management/archetypes/
+[base templates]: /templates/base/
+[config]: /getting-started/configuration/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+[`.Format` function]: /functions/format/
+[front matter]: /content-management/front-matter/
+[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[section]: /content-management/sections/
+[site variables]: /variables/site/
+[spf13]: http://spf13.com/
+[`with`]: /functions/with/
--- /dev/null
- keywords: [sitemap, xml]
+---
+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">
+ {{ range .Data.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.:
+
+```
+[sitemap]
+ changefreq = "monthly"
+ priority = 0.5
+ filename = "sitemap.xml"
+```
+
+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
- keywords: [taxonomies,metadata,front matter,terms]
+---
+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]
- A taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g., http://spf13.com/topics/golang/) according to the following lookup order:
-
- 1. `/layouts/taxonomy/<SINGULAR>.html`
- 2. `/layouts/_default/taxonomy.html`
- 3. `/layouts/_default/list.html`
- 4. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.html`
- 5. `/themes/<THEME>/layouts/_default/taxonomy.html`
- 6. `/themes/<THEME>/layouts/_default/list.html`
++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
+
- A taxonomy terms page will be rendered at `example.com/<PLURALTAXONOMYNAME>`/ (e.g., http://spf13.com/topics/) according to the following lookup order:
-
- 1. `/layouts/taxonomy/<SINGULAR>.terms.html`
- 2. `/layouts/_default/terms.html`
- 3. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.terms.html`
- 4. `/themes/<THEME>/layouts/_default/terms.html`
-
- {{% warning "The Taxonomy Terms Template has a Unique Lookup Order" %}}
- If Hugo does not find a terms template in `layout/` or `/themes/<THEME>/layouts/`, Hugo will *not* render a taxonomy terms page.
- {{% /warning %}}
-
- <!-- Begin /taxonomies/methods/ -->
- Hugo makes a set of values and methods available on the various Taxonomy structures.
++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
+
+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:
+
+```
+<ul>
+ {{ range .Data.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
- * [hugo.el](https://github.com/yewton/hugo.el). Some helper functions for creating a Website with Hugo. Note that Hugo also supports [Org-mode][formats].
+---
+title: Editor Plug-ins for Hugo
+linktitle: Editor Plug-ins
+description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [developer tools]
+keywords: [editor, plug-ins]
+menu:
+ docs:
+ parent: "tools"
+ weight: 50
+weight: 50
+sections_weight: 50
+draft: false
+aliases: []
+toc: false
+---
+
+The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow.
+
+## Sublime Text
+
+* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
+
+## Visual Studio Code
+
+* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
+
+## Emacs
+
++* [emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo). Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
+* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org sub-trees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+
+## Vim
+
+* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo.
+
+## Atom
+
+* [Hugofy](https://atom.io/packages/hugofy). A Hugo Static Website Generator package for Atom.
+* [language-hugo](https://atom.io/packages/language-hugo). Adds syntax highlighting to Hugo files.
+
+[formats]: /content-management/formats/
--- /dev/null
+---
+title: Migrate to Hugo
+linktitle: Migrations
+description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful]
+menu:
+ docs:
+ parent: "tools"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/developer-tools/migrations/,/developer-tools/migrated/]
+toc: true
+---
+
+This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started.
+
+{{% note %}}
+Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugo/pulls) on GitHub if you think it should be added.
+{{% /note %}}
+
+Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats.
+
+## Jekyll
+
+Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/).
+
+- [JekyllToHugo](https://github.com/SenjinDarashiva/JekyllToHugo) - A Small script for converting Jekyll blog posts to a Hugo site.
+- [ConvertToHugo](https://github.com/coderzh/ConvertToHugo) - Convert your blog from Jekyll to Hugo.
+
+## Ghost
+
+- [ghostToHugo](https://github.com/jbarone/ghostToHugo) - Convert Ghost blog posts and export them to Hugo.
+
+## Octopress
+
+- [octohug](https://github.com/codebrane/octohug) - Octopress to Hugo migrator.
+
+## DokuWiki
+
+- [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) - Migrates your dokuwiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory.
+
+## WordPress
+
+- [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) - A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.)
+
+## Tumblr
+
+- [tumblr-importr](https://github.com/carlmjohnson/tumblr-importr) - An importer that uses the Tumblr API to create a Hugo static site.
+- [tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown) - Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
+- [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) - A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections.
+
+## Drupal
+
+- [drupal2hugo](https://github.com/danapsimer/drupal2hugo) - Convert a Drupal site to Hugo.
+
+## Joomla
+
+- [hugojoomla](https://github.com/davetcc/hugojoomla) - This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
+
+## Blogger
+
+- [blogimport](https://github.com/natefinch/blogimport) - A tool to import from Blogger posts to Hugo.
++- [blogger-to-hugo](https://bitbucket.org/petraszd/blogger-to-hugo) - Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
+
+## Contentful
+
+- [contentful2hugo](https://github.com/ArnoNuyts/contentful2hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
--- /dev/null
- * [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
+---
+title: Search for your Hugo Website
+linktitle: Search
+description: See some of the open-source and commercial search options for your newly created Hugo website.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-26
+categories: [developer tools]
+keywords: [search,tools]
+menu:
+ docs:
+ parent: "tools"
+ weight: 60
+weight: 60
+sections_weight: 60
+draft: false
+aliases: []
+toc: true
+---
+
+A static website with a dynamic search function? Yes. As alternatives to embeddable scripts from Google or other search engines, you can provide your visitors a custom search by indexing your content files directly.
+
+* [Hugoidx](https://github.com/blevesearch/hugoidx) is an experimental application to create a search index. It's built on top of [Bleve](http://www.blevesearch.com/).
+* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results.
+* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project.
++* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you seperate the Chinese keywords.
+
+## Commercial Search Services
+
++* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
--- /dev/null
- [menu template]: /templates/menu-templates/
+---
+title: Menu Variables
+linktitle: Menu Variables
+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
+---
+
+The [menu template][] has the following properties:
+
+.URL
+: string
+
+.Name
+: string
+
++.Title
++: string
++
++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.
++
++.Page
++: [Page Object](/variables/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
+
+.Identifier
+: string
+
+.Pre
+: template.HTML
+
+.Post
+: template.HTML
+
+.Weight
+: int
+
+.Parent
+: string
+
+.Children
+: Menu
+
++[menu template]: /templates/menu-templates/
--- /dev/null
+---
+title: Page Variables
+linktitle:
+description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [variables and params]
+keywords: [pages]
+draft: false
+menu:
+ docs:
++ title: "variables defined by a page"
+ parent: "variables"
+ weight: 20
+weight: 20
+sections_weight: 20
+aliases: [/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. This value will be `nil` for regular content pages. `.Pages` is an alias for `.Data.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/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
- "Example": "AMP home, with theme \"demoTheme\".",
+{
+ "media": {
+ "types": [
+ {
+ "type": "application/javascript",
+ "string": "application/javascript+js",
+ "mainType": "application",
+ "subType": "javascript",
+ "suffix": "js",
+ "delimiter": "."
+ },
+ {
+ "type": "application/json",
+ "string": "application/json+json",
+ "mainType": "application",
+ "subType": "json",
+ "suffix": "json",
+ "delimiter": "."
+ },
+ {
+ "type": "application/rss",
+ "string": "application/rss+xml",
+ "mainType": "application",
+ "subType": "rss",
+ "suffix": "xml",
+ "delimiter": "."
+ },
+ {
+ "type": "application/xml",
+ "string": "application/xml+xml",
+ "mainType": "application",
+ "subType": "xml",
+ "suffix": "xml",
+ "delimiter": "."
+ },
+ {
+ "type": "text/calendar",
+ "string": "text/calendar+ics",
+ "mainType": "text",
+ "subType": "calendar",
+ "suffix": "ics",
+ "delimiter": "."
+ },
+ {
+ "type": "text/css",
+ "string": "text/css+css",
+ "mainType": "text",
+ "subType": "css",
+ "suffix": "css",
+ "delimiter": "."
+ },
+ {
+ "type": "text/csv",
+ "string": "text/csv+csv",
+ "mainType": "text",
+ "subType": "csv",
+ "suffix": "csv",
+ "delimiter": "."
+ },
+ {
+ "type": "text/html",
+ "string": "text/html+html",
+ "mainType": "text",
+ "subType": "html",
+ "suffix": "html",
+ "delimiter": "."
+ },
+ {
+ "type": "text/plain",
+ "string": "text/plain+txt",
+ "mainType": "text",
+ "subType": "plain",
+ "suffix": "txt",
+ "delimiter": "."
+ }
+ ]
+ },
+ "output": {
+ "formats": [
+ {
+ "MediaType": "text/html+html",
+ "name": "AMP",
+ "mediaType": {
+ "type": "text/html",
+ "string": "text/html+html",
+ "mainType": "text",
+ "subType": "html",
+ "suffix": "html",
+ "delimiter": "."
+ },
+ "path": "amp",
+ "baseName": "index",
+ "rel": "amphtml",
+ "protocol": "",
+ "isPlainText": false,
+ "isHTML": true,
+ "noUgly": false,
+ "notAlternative": false
+ },
+ {
+ "MediaType": "text/css+css",
+ "name": "CSS",
+ "mediaType": {
+ "type": "text/css",
+ "string": "text/css+css",
+ "mainType": "text",
+ "subType": "css",
+ "suffix": "css",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "styles",
+ "rel": "stylesheet",
+ "protocol": "",
+ "isPlainText": true,
+ "isHTML": false,
+ "noUgly": false,
+ "notAlternative": true
+ },
+ {
+ "MediaType": "text/csv+csv",
+ "name": "CSV",
+ "mediaType": {
+ "type": "text/csv",
+ "string": "text/csv+csv",
+ "mainType": "text",
+ "subType": "csv",
+ "suffix": "csv",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "index",
+ "rel": "alternate",
+ "protocol": "",
+ "isPlainText": true,
+ "isHTML": false,
+ "noUgly": false,
+ "notAlternative": false
+ },
+ {
+ "MediaType": "text/calendar+ics",
+ "name": "Calendar",
+ "mediaType": {
+ "type": "text/calendar",
+ "string": "text/calendar+ics",
+ "mainType": "text",
+ "subType": "calendar",
+ "suffix": "ics",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "index",
+ "rel": "alternate",
+ "protocol": "webcal://",
+ "isPlainText": true,
+ "isHTML": false,
+ "noUgly": false,
+ "notAlternative": false
+ },
+ {
+ "MediaType": "text/html+html",
+ "name": "HTML",
+ "mediaType": {
+ "type": "text/html",
+ "string": "text/html+html",
+ "mainType": "text",
+ "subType": "html",
+ "suffix": "html",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "index",
+ "rel": "canonical",
+ "protocol": "",
+ "isPlainText": false,
+ "isHTML": true,
+ "noUgly": false,
+ "notAlternative": false
+ },
+ {
+ "MediaType": "application/json+json",
+ "name": "JSON",
+ "mediaType": {
+ "type": "application/json",
+ "string": "application/json+json",
+ "mainType": "application",
+ "subType": "json",
+ "suffix": "json",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "index",
+ "rel": "alternate",
+ "protocol": "",
+ "isPlainText": true,
+ "isHTML": false,
+ "noUgly": false,
+ "notAlternative": false
+ },
+ {
+ "MediaType": "application/rss+xml",
+ "name": "RSS",
+ "mediaType": {
+ "type": "application/rss",
+ "string": "application/rss+xml",
+ "mainType": "application",
+ "subType": "rss",
+ "suffix": "xml",
+ "delimiter": "."
+ },
+ "path": "",
+ "baseName": "index",
+ "rel": "alternate",
+ "protocol": "",
+ "isPlainText": false,
+ "isHTML": false,
+ "noUgly": true,
+ "notAlternative": false
+ }
+ ],
+ "layouts": [
+ {
- "layouts/index.amp.html",
++ "Example": "Single page in \"posts\" section",
++ "Kind": "page",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/posts/single.html.html",
++ "layouts/posts/single.html",
++ "layouts/_default/single.html.html",
++ "layouts/_default/single.html"
++ ]
++ },
++ {
++ "Example": "Single page in \"posts\" section with layout set",
++ "Kind": "page",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/posts/demolayout.html.html",
++ "layouts/posts/single.html.html",
++ "layouts/posts/demolayout.html",
++ "layouts/posts/single.html",
++ "layouts/_default/demolayout.html.html",
++ "layouts/_default/single.html.html",
++ "layouts/_default/demolayout.html",
++ "layouts/_default/single.html"
++ ]
++ },
++ {
++ "Example": "Single page in \"posts\" section with theme",
++ "Kind": "page",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/posts/single.html.html",
++ "demoTheme/layouts/posts/single.html.html",
++ "layouts/posts/single.html",
++ "demoTheme/layouts/posts/single.html",
++ "layouts/_default/single.html.html",
++ "demoTheme/layouts/_default/single.html.html",
++ "layouts/_default/single.html",
++ "demoTheme/layouts/_default/single.html"
++ ]
++ },
++ {
++ "Example": "AMP single page",
++ "Kind": "page",
+ "OutputFormat": "AMP",
+ "Suffix": "html",
+ "Template Lookup Order": [
- "layouts/_default/list.amp.html",
- "layouts/_default/list.html",
- "demoTheme/layouts/index.amp.html",
++ "layouts/posts/single.amp.html",
++ "layouts/posts/single.html",
++ "layouts/_default/single.amp.html",
++ "layouts/_default/single.html"
++ ]
++ },
++ {
++ "Example": "AMP single page, French language",
++ "Kind": "page",
++ "OutputFormat": "AMP",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/posts/single.fr.amp.html",
++ "layouts/posts/single.amp.html",
++ "layouts/posts/single.fr.html",
++ "layouts/posts/single.html",
++ "layouts/_default/single.fr.amp.html",
++ "layouts/_default/single.amp.html",
++ "layouts/_default/single.fr.html",
++ "layouts/_default/single.html"
++ ]
++ },
++ {
++ "Example": "Home page",
++ "Kind": "home",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/page/index.html.html",
++ "layouts/page/home.html.html",
++ "layouts/page/list.html.html",
++ "layouts/page/index.html",
++ "layouts/page/home.html",
++ "layouts/page/list.html",
++ "layouts/index.html.html",
++ "layouts/home.html.html",
++ "layouts/list.html.html",
++ "layouts/index.html",
++ "layouts/home.html",
++ "layouts/list.html",
++ "layouts/_default/index.html.html",
++ "layouts/_default/home.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/index.html",
++ "layouts/_default/home.html",
++ "layouts/_default/list.html"
++ ]
++ },
++ {
++ "Example": "Home page with type set",
++ "Kind": "home",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/demotype/index.html.html",
++ "layouts/demotype/home.html.html",
++ "layouts/demotype/list.html.html",
++ "layouts/demotype/index.html",
++ "layouts/demotype/home.html",
++ "layouts/demotype/list.html",
++ "layouts/index.html.html",
++ "layouts/home.html.html",
++ "layouts/list.html.html",
++ "layouts/index.html",
++ "layouts/home.html",
++ "layouts/list.html",
++ "layouts/_default/index.html.html",
++ "layouts/_default/home.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/index.html",
++ "layouts/_default/home.html",
++ "layouts/_default/list.html"
++ ]
++ },
++ {
++ "Example": "Home page with layout set",
++ "Kind": "home",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/page/demolayout.html.html",
++ "layouts/page/index.html.html",
++ "layouts/page/home.html.html",
++ "layouts/page/list.html.html",
++ "layouts/page/demolayout.html",
++ "layouts/page/index.html",
++ "layouts/page/home.html",
++ "layouts/page/list.html",
++ "layouts/demolayout.html.html",
++ "layouts/index.html.html",
++ "layouts/home.html.html",
++ "layouts/list.html.html",
++ "layouts/demolayout.html",
++ "layouts/index.html",
++ "layouts/home.html",
++ "layouts/list.html",
++ "layouts/_default/demolayout.html.html",
++ "layouts/_default/index.html.html",
++ "layouts/_default/home.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/demolayout.html",
++ "layouts/_default/index.html",
++ "layouts/_default/home.html",
++ "layouts/_default/list.html"
++ ]
++ },
++ {
++ "Example": "Home page with theme",
++ "Kind": "home",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
++ "Template Lookup Order": [
++ "layouts/page/index.html.html",
++ "demoTheme/layouts/page/index.html.html",
++ "layouts/page/home.html.html",
++ "demoTheme/layouts/page/home.html.html",
++ "layouts/page/list.html.html",
++ "demoTheme/layouts/page/list.html.html",
++ "layouts/page/index.html",
++ "demoTheme/layouts/page/index.html",
++ "layouts/page/home.html",
++ "demoTheme/layouts/page/home.html",
++ "layouts/page/list.html",
++ "demoTheme/layouts/page/list.html",
++ "layouts/index.html.html",
++ "demoTheme/layouts/index.html.html",
++ "layouts/home.html.html",
++ "demoTheme/layouts/home.html.html",
++ "layouts/list.html.html",
++ "demoTheme/layouts/list.html.html",
+ "layouts/index.html",
- "demoTheme/layouts/_default/list.amp.html",
+ "demoTheme/layouts/index.html",
- "Example": "AMP home, French language\".",
++ "layouts/home.html",
++ "demoTheme/layouts/home.html",
++ "layouts/list.html",
++ "demoTheme/layouts/list.html",
++ "layouts/_default/index.html.html",
++ "demoTheme/layouts/_default/index.html.html",
++ "layouts/_default/home.html.html",
++ "demoTheme/layouts/_default/home.html.html",
++ "layouts/_default/list.html.html",
++ "demoTheme/layouts/_default/list.html.html",
++ "layouts/_default/index.html",
++ "demoTheme/layouts/_default/index.html",
++ "layouts/_default/home.html",
++ "demoTheme/layouts/_default/home.html",
++ "layouts/_default/list.html",
+ "demoTheme/layouts/_default/list.html"
+ ]
+ },
+ {
- "Example": "RSS home, no theme.",
- "OutputFormat": "RSS",
- "Suffix": "xml",
- "Template Lookup Order": [
- "layouts/rss.xml",
- "layouts/_default/rss.xml",
- "layouts/_internal/_default/rss.xml"
- ]
- },
- {
- "Example": "JSON home, no theme.",
++ "Example": "AMP home, French language\"",
++ "Kind": "home",
+ "OutputFormat": "AMP",
+ "Suffix": "html",
+ "Template Lookup Order": [
++ "layouts/page/index.fr.amp.html",
++ "layouts/page/home.fr.amp.html",
++ "layouts/page/list.fr.amp.html",
++ "layouts/page/index.amp.html",
++ "layouts/page/home.amp.html",
++ "layouts/page/list.amp.html",
++ "layouts/page/index.fr.html",
++ "layouts/page/home.fr.html",
++ "layouts/page/list.fr.html",
++ "layouts/page/index.html",
++ "layouts/page/home.html",
++ "layouts/page/list.html",
+ "layouts/index.fr.amp.html",
++ "layouts/home.fr.amp.html",
++ "layouts/list.fr.amp.html",
+ "layouts/index.amp.html",
++ "layouts/home.amp.html",
++ "layouts/list.amp.html",
+ "layouts/index.fr.html",
++ "layouts/home.fr.html",
++ "layouts/list.fr.html",
+ "layouts/index.html",
++ "layouts/home.html",
++ "layouts/list.html",
++ "layouts/_default/index.fr.amp.html",
++ "layouts/_default/home.fr.amp.html",
+ "layouts/_default/list.fr.amp.html",
++ "layouts/_default/index.amp.html",
++ "layouts/_default/home.amp.html",
+ "layouts/_default/list.amp.html",
++ "layouts/_default/index.fr.html",
++ "layouts/_default/home.fr.html",
+ "layouts/_default/list.fr.html",
++ "layouts/_default/index.html",
++ "layouts/_default/home.html",
+ "layouts/_default/list.html"
+ ]
+ },
+ {
- "Example": "CSV regular, \"layout: demolayout\" in front matter.",
- "OutputFormat": "CSV",
- "Suffix": "csv",
- "Template Lookup Order": [
- "layouts/_default/demolayout.csv.csv",
- "layouts/_default/demolayout.csv"
- ]
- },
- {
- "Example": "JSON regular, \"type: demotype\" in front matter.",
- "OutputFormat": "JSON",
- "Suffix": "json",
++ "Example": "JSON home",
++ "Kind": "home",
+ "OutputFormat": "JSON",
+ "Suffix": "json",
+ "Template Lookup Order": [
++ "layouts/page/index.json.json",
++ "layouts/page/home.json.json",
++ "layouts/page/list.json.json",
++ "layouts/page/index.json",
++ "layouts/page/home.json",
++ "layouts/page/list.json",
+ "layouts/index.json.json",
++ "layouts/home.json.json",
++ "layouts/list.json.json",
+ "layouts/index.json",
++ "layouts/home.json",
++ "layouts/list.json",
++ "layouts/_default/index.json.json",
++ "layouts/_default/home.json.json",
+ "layouts/_default/list.json.json",
++ "layouts/_default/index.json",
++ "layouts/_default/home.json",
+ "layouts/_default/list.json"
+ ]
+ },
+ {
- "layouts/demotype/single.json.json",
- "layouts/demotype/single.json",
- "layouts/_default/single.json.json",
- "layouts/_default/single.json"
++ "Example": "RSS home",
++ "Kind": "home",
++ "OutputFormat": "RSS",
++ "Suffix": "xml",
+ "Template Lookup Order": [
- "Example": "HTML regular.",
++ "layouts/page/index.rss.xml",
++ "layouts/page/home.rss.xml",
++ "layouts/page/rss.xml",
++ "layouts/page/list.rss.xml",
++ "layouts/page/index.xml",
++ "layouts/page/home.xml",
++ "layouts/page/list.xml",
++ "layouts/index.rss.xml",
++ "layouts/home.rss.xml",
++ "layouts/rss.xml",
++ "layouts/list.rss.xml",
++ "layouts/index.xml",
++ "layouts/home.xml",
++ "layouts/list.xml",
++ "layouts/_default/index.rss.xml",
++ "layouts/_default/home.rss.xml",
++ "layouts/_default/rss.xml",
++ "layouts/_default/list.rss.xml",
++ "layouts/_default/index.xml",
++ "layouts/_default/home.xml",
++ "layouts/_default/list.xml",
++ "layouts/_internal/_default/rss.xml"
+ ]
+ },
+ {
- "layouts/_default/single.html.html",
- "layouts/_default/single.html"
++ "Example": "Section list for \"posts\" section",
++ "Kind": "section",
+ "OutputFormat": "HTML",
+ "Suffix": "html",
+ "Template Lookup Order": [
- "Example": "AMP regular.",
- "OutputFormat": "AMP",
++ "layouts/posts/posts.html.html",
++ "layouts/posts/section.html.html",
++ "layouts/posts/list.html.html",
++ "layouts/posts/posts.html",
++ "layouts/posts/section.html",
++ "layouts/posts/list.html",
++ "layouts/section/posts.html.html",
++ "layouts/section/section.html.html",
++ "layouts/section/list.html.html",
++ "layouts/section/posts.html",
++ "layouts/section/section.html",
++ "layouts/section/list.html",
++ "layouts/_default/posts.html.html",
++ "layouts/_default/section.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/posts.html",
++ "layouts/_default/section.html",
++ "layouts/_default/list.html"
+ ]
+ },
+ {
- "layouts/_default/single.amp.html",
- "layouts/_default/single.html"
++ "Example": "Section list for \"posts\" section with type set to \"blog\"",
++ "Kind": "section",
++ "OutputFormat": "HTML",
+ "Suffix": "html",
+ "Template Lookup Order": [
- "Example": "Calendar blog section.",
- "OutputFormat": "Calendar",
- "Suffix": "ics",
++ "layouts/blog/posts.html.html",
++ "layouts/blog/section.html.html",
++ "layouts/blog/list.html.html",
++ "layouts/blog/posts.html",
++ "layouts/blog/section.html",
++ "layouts/blog/list.html",
++ "layouts/posts/posts.html.html",
++ "layouts/posts/section.html.html",
++ "layouts/posts/list.html.html",
++ "layouts/posts/posts.html",
++ "layouts/posts/section.html",
++ "layouts/posts/list.html",
++ "layouts/section/posts.html.html",
++ "layouts/section/section.html.html",
++ "layouts/section/list.html.html",
++ "layouts/section/posts.html",
++ "layouts/section/section.html",
++ "layouts/section/list.html",
++ "layouts/_default/posts.html.html",
++ "layouts/_default/section.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/posts.html",
++ "layouts/_default/section.html",
++ "layouts/_default/list.html"
+ ]
+ },
+ {
- "layouts/section/blog.calendar.ics",
- "layouts/section/blog.ics",
- "layouts/blog/list.calendar.ics",
- "layouts/blog/list.ics",
- "layouts/_default/section.calendar.ics",
- "layouts/_default/section.ics",
- "layouts/_default/list.calendar.ics",
- "layouts/_default/list.ics"
++ "Example": "Section list for \"posts\" section with layout set to \"demoLayout\"",
++ "Kind": "section",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
+ "Template Lookup Order": [
- "Example": "Calendar taxonomy list.",
- "OutputFormat": "Calendar",
- "Suffix": "ics",
++ "layouts/posts/demolayout.html.html",
++ "layouts/posts/posts.html.html",
++ "layouts/posts/section.html.html",
++ "layouts/posts/list.html.html",
++ "layouts/posts/demolayout.html",
++ "layouts/posts/posts.html",
++ "layouts/posts/section.html",
++ "layouts/posts/list.html",
++ "layouts/section/demolayout.html.html",
++ "layouts/section/posts.html.html",
++ "layouts/section/section.html.html",
++ "layouts/section/list.html.html",
++ "layouts/section/demolayout.html",
++ "layouts/section/posts.html",
++ "layouts/section/section.html",
++ "layouts/section/list.html",
++ "layouts/_default/demolayout.html.html",
++ "layouts/_default/posts.html.html",
++ "layouts/_default/section.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/demolayout.html",
++ "layouts/_default/posts.html",
++ "layouts/_default/section.html",
++ "layouts/_default/list.html"
+ ]
+ },
+ {
- "layouts/taxonomy/tag.calendar.ics",
- "layouts/taxonomy/tag.ics",
- "layouts/_default/taxonomy.calendar.ics",
- "layouts/_default/taxonomy.ics",
- "layouts/_default/list.calendar.ics",
- "layouts/_default/list.ics"
++ "Example": "Taxonomy list in categories",
++ "Kind": "taxonomy",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
+ "Template Lookup Order": [
- "Example": "Calendar taxonomy term.",
- "OutputFormat": "Calendar",
- "Suffix": "ics",
++ "layouts/categories/category.html.html",
++ "layouts/categories/taxonomy.html.html",
++ "layouts/categories/list.html.html",
++ "layouts/categories/category.html",
++ "layouts/categories/taxonomy.html",
++ "layouts/categories/list.html",
++ "layouts/taxonomy/category.html.html",
++ "layouts/taxonomy/taxonomy.html.html",
++ "layouts/taxonomy/list.html.html",
++ "layouts/taxonomy/category.html",
++ "layouts/taxonomy/taxonomy.html",
++ "layouts/taxonomy/list.html",
++ "layouts/category/category.html.html",
++ "layouts/category/taxonomy.html.html",
++ "layouts/category/list.html.html",
++ "layouts/category/category.html",
++ "layouts/category/taxonomy.html",
++ "layouts/category/list.html",
++ "layouts/_default/category.html.html",
++ "layouts/_default/taxonomy.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/category.html",
++ "layouts/_default/taxonomy.html",
++ "layouts/_default/list.html"
+ ]
+ },
+ {
- "layouts/taxonomy/tag.terms.calendar.ics",
- "layouts/taxonomy/tag.terms.ics",
- "layouts/_default/terms.calendar.ics",
- "layouts/_default/terms.ics"
++ "Example": "Taxonomy term in categories",
++ "Kind": "taxonomyTerm",
++ "OutputFormat": "HTML",
++ "Suffix": "html",
+ "Template Lookup Order": [
- "{{chomp \"\u003cp\u003eBlockhead\u003c/p\u003e\\n\" }}",
++ "layouts/categories/category.terms.html.html",
++ "layouts/categories/terms.html.html",
++ "layouts/categories/list.html.html",
++ "layouts/categories/category.terms.html",
++ "layouts/categories/terms.html",
++ "layouts/categories/list.html",
++ "layouts/taxonomy/category.terms.html.html",
++ "layouts/taxonomy/terms.html.html",
++ "layouts/taxonomy/list.html.html",
++ "layouts/taxonomy/category.terms.html",
++ "layouts/taxonomy/terms.html",
++ "layouts/taxonomy/list.html",
++ "layouts/category/category.terms.html.html",
++ "layouts/category/terms.html.html",
++ "layouts/category/list.html.html",
++ "layouts/category/category.terms.html",
++ "layouts/category/terms.html",
++ "layouts/category/list.html",
++ "layouts/_default/category.terms.html.html",
++ "layouts/_default/terms.html.html",
++ "layouts/_default/list.html.html",
++ "layouts/_default/category.terms.html",
++ "layouts/_default/terms.html",
++ "layouts/_default/list.html"
+ ]
+ }
+ ]
+ },
+ "tpl": {
+ "funcs": {
+ "cast": {
+ "ToFloat": {
+ "Description": "ToFloat converts the given value to a float.",
+ "Args": [
+ "v"
+ ],
+ "Aliases": [
+ "float"
+ ],
+ "Examples": [
+ [
+ "{{ \"1234\" | float | printf \"%T\" }}",
+ "float64"
+ ]
+ ]
+ },
+ "ToInt": {
+ "Description": "ToInt converts the given value to an int.",
+ "Args": [
+ "v"
+ ],
+ "Aliases": [
+ "int"
+ ],
+ "Examples": [
+ [
+ "{{ \"1234\" | int | printf \"%T\" }}",
+ "int"
+ ]
+ ]
+ },
+ "ToString": {
+ "Description": "ToString converts the given value to a string.",
+ "Args": [
+ "v"
+ ],
+ "Aliases": [
+ "string"
+ ],
+ "Examples": [
+ [
+ "{{ 1234 | string | printf \"%T\" }}",
+ "string"
+ ]
+ ]
+ }
+ },
+ "compare": {
+ "Conditional": {
+ "Description": "Conditional can be used as a ternary operator.\nIt returns a if condition, else b.",
+ "Args": [
+ "condition",
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "cond"
+ ],
+ "Examples": [
+ [
+ "{{ cond (eq (add 2 2) 4) \"2+2 is 4\" \"what?\" | safeHTML }}",
+ "2+2 is 4"
+ ]
+ ]
+ },
+ "Default": {
+ "Description": "Default checks whether a given value is set and returns a default value if it\nis not. \"Set\" in this context means non-zero for numeric types and times;\nnon-zero length for strings, arrays, slices, and maps;\nany boolean or struct value; or non-nil for any other types.",
+ "Args": [
+ "dflt",
+ "given"
+ ],
+ "Aliases": [
+ "default"
+ ],
+ "Examples": [
+ [
+ "{{ \"Hugo Rocks!\" | default \"Hugo Rules!\" }}",
+ "Hugo Rocks!"
+ ],
+ [
+ "{{ \"\" | default \"Hugo Rules!\" }}",
+ "Hugo Rules!"
+ ]
+ ]
+ },
+ "Eq": {
+ "Description": "Eq returns the boolean truth of arg1 == arg2.",
+ "Args": [
+ "x",
+ "y"
+ ],
+ "Aliases": [
+ "eq"
+ ],
+ "Examples": [
+ [
+ "{{ if eq .Section \"blog\" }}current{{ end }}",
+ "current"
+ ]
+ ]
+ },
+ "Ge": {
+ "Description": "Ge returns the boolean truth of arg1 \u003e= arg2.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "ge"
+ ],
+ "Examples": []
+ },
+ "Gt": {
+ "Description": "Gt returns the boolean truth of arg1 \u003e arg2.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "gt"
+ ],
+ "Examples": []
+ },
+ "Le": {
+ "Description": "Le returns the boolean truth of arg1 \u003c= arg2.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "le"
+ ],
+ "Examples": []
+ },
+ "Lt": {
+ "Description": "Lt returns the boolean truth of arg1 \u003c arg2.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "lt"
+ ],
+ "Examples": []
+ },
+ "Ne": {
+ "Description": "Ne returns the boolean truth of arg1 != arg2.",
+ "Args": [
+ "x",
+ "y"
+ ],
+ "Aliases": [
+ "ne"
+ ],
+ "Examples": []
+ }
+ },
+ "collections": {
+ "After": {
+ "Description": "After returns all the items after the first N in a rangeable list.",
+ "Args": [
+ "index",
+ "seq"
+ ],
+ "Aliases": [
+ "after"
+ ],
+ "Examples": []
+ },
+ "Apply": {
+ "Description": "Apply takes a map, array, or slice and returns a new slice with the function fname applied over it.",
+ "Args": [
+ "seq",
+ "fname",
+ "args"
+ ],
+ "Aliases": [
+ "apply"
+ ],
+ "Examples": []
+ },
+ "Delimit": {
+ "Description": "Delimit takes a given sequence and returns a delimited HTML string.\nIf last is passed to the function, it will be used as the final delimiter.",
+ "Args": [
+ "seq",
+ "delimiter",
+ "last"
+ ],
+ "Aliases": [
+ "delimit"
+ ],
+ "Examples": [
+ [
+ "{{ delimit (slice \"A\" \"B\" \"C\") \", \" \" and \" }}",
+ "A, B and C"
+ ]
+ ]
+ },
+ "Dictionary": {
+ "Description": "Dictionary creates a map[string]interface{} from the given parameters by\nwalking the parameters and treating them as key-value pairs. The number\nof parameters must be even.",
+ "Args": [
+ "values"
+ ],
+ "Aliases": [
+ "dict"
+ ],
+ "Examples": []
+ },
+ "EchoParam": {
+ "Description": "EchoParam returns a given value if it is set; otherwise, it returns an\nempty string.",
+ "Args": [
+ "a",
+ "key"
+ ],
+ "Aliases": [
+ "echoParam"
+ ],
+ "Examples": [
+ [
+ "{{ echoParam .Params \"langCode\" }}",
+ "en"
+ ]
+ ]
+ },
+ "First": {
+ "Description": "First returns the first N items in a rangeable list.",
+ "Args": [
+ "limit",
+ "seq"
+ ],
+ "Aliases": [
+ "first"
+ ],
+ "Examples": []
+ },
+ "In": {
+ "Description": "In returns whether v is in the set l. l may be an array or slice.",
+ "Args": [
+ "l",
+ "v"
+ ],
+ "Aliases": [
+ "in"
+ ],
+ "Examples": [
+ [
+ "{{ if in \"this string contains a substring\" \"substring\" }}Substring found!{{ end }}",
+ "Substring found!"
+ ]
+ ]
+ },
+ "Index": {
+ "Description": "Index returns the result of indexing its first argument by the following\narguments. Thus \"index x 1 2 3\" is, in Go syntax, x[1][2][3]. Each\nindexed item must be a map, slice, or array.\n\nCopied from Go stdlib src/text/template/funcs.go.\n\nWe deviate from the stdlib due to https://github.com/golang/go/issues/14751.\n\nTODO(moorereason): merge upstream changes.",
+ "Args": [
+ "item",
+ "indices"
+ ],
+ "Aliases": [
+ "index"
+ ],
+ "Examples": []
+ },
+ "Intersect": {
+ "Description": "Intersect returns the common elements in the given sets, l1 and l2. l1 and\nl2 must be of the same type and may be either arrays or slices.",
+ "Args": [
+ "l1",
+ "l2"
+ ],
+ "Aliases": [
+ "intersect"
+ ],
+ "Examples": []
+ },
+ "IsSet": {
+ "Description": "IsSet returns whether a given array, channel, slice, or map has a key\ndefined.",
+ "Args": [
+ "a",
+ "key"
+ ],
+ "Aliases": [
+ "isSet",
+ "isset"
+ ],
+ "Examples": []
+ },
+ "KeyVals": {
+ "Description": "KeyVals creates a key and values wrapper.",
+ "Args": [
+ "key",
+ "vals"
+ ],
+ "Aliases": [
+ "keyVals"
+ ],
+ "Examples": [
+ [
+ "{{ keyVals \"key\" \"a\" \"b\" }}",
+ "key: [a b]"
+ ]
+ ]
+ },
+ "Last": {
+ "Description": "Last returns the last N items in a rangeable list.",
+ "Args": [
+ "limit",
+ "seq"
+ ],
+ "Aliases": [
+ "last"
+ ],
+ "Examples": []
+ },
+ "Querify": {
+ "Description": "Querify encodes the given parameters in URL-encoded form (\"bar=baz\u0026foo=quux\") sorted by key.",
+ "Args": [
+ "params"
+ ],
+ "Aliases": [
+ "querify"
+ ],
+ "Examples": [
+ [
+ "{{ (querify \"foo\" 1 \"bar\" 2 \"baz\" \"with spaces\" \"qux\" \"this\u0026that=those\") | safeHTML }}",
+ "bar=2\u0026baz=with+spaces\u0026foo=1\u0026qux=this%26that%3Dthose"
+ ],
+ [
+ "\u003ca href=\"https://www.google.com?{{ (querify \"q\" \"test\" \"page\" 3) | safeURL }}\"\u003eSearch\u003c/a\u003e",
+ "\u003ca href=\"https://www.google.com?page=3\u0026amp;q=test\"\u003eSearch\u003c/a\u003e"
+ ]
+ ]
+ },
+ "Seq": {
+ "Description": "Seq creates a sequence of integers. It's named and used as GNU's seq.\n\nExamples:\n 3 =\u003e 1, 2, 3\n 1 2 4 =\u003e 1, 3\n -3 =\u003e -1, -2, -3\n 1 4 =\u003e 1, 2, 3, 4\n 1 -2 =\u003e 1, 0, -1, -2",
+ "Args": [
+ "args"
+ ],
+ "Aliases": [
+ "seq"
+ ],
+ "Examples": [
+ [
+ "{{ seq 3 }}",
+ "[1 2 3]"
+ ]
+ ]
+ },
+ "Shuffle": {
+ "Description": "Shuffle returns the given rangeable list in a randomised order.",
+ "Args": [
+ "seq"
+ ],
+ "Aliases": [
+ "shuffle"
+ ],
+ "Examples": []
+ },
+ "Slice": {
+ "Description": "Slice returns a slice of all passed arguments.",
+ "Args": [
+ "args"
+ ],
+ "Aliases": [
+ "slice"
+ ],
+ "Examples": [
+ [
+ "{{ slice \"B\" \"C\" \"A\" | sort }}",
+ "[A B C]"
+ ]
+ ]
+ },
+ "Sort": {
+ "Description": "Sort returns a sorted sequence.",
+ "Args": [
+ "seq",
+ "args"
+ ],
+ "Aliases": [
+ "sort"
+ ],
+ "Examples": []
+ },
+ "Union": {
+ "Description": "Union returns the union of the given sets, l1 and l2. l1 and\nl2 must be of the same type and may be either arrays or slices.\nIf l1 and l2 aren't of the same type then l1 will be returned.\nIf either l1 or l2 is nil then the non-nil list will be returned.",
+ "Args": [
+ "l1",
+ "l2"
+ ],
+ "Aliases": [
+ "union"
+ ],
+ "Examples": [
+ [
+ "{{ union (slice 1 2 3) (slice 3 4 5) }}",
+ "[1 2 3 4 5]"
+ ]
+ ]
+ },
+ "Uniq": {
+ "Description": "Uniq takes in a slice or array and returns a slice with subsequent\nduplicate elements removed.",
+ "Args": [
+ "l"
+ ],
+ "Aliases": [
+ "uniq"
+ ],
+ "Examples": [
+ [
+ "{{ slice 1 2 3 2 | uniq }}",
+ "[1 2 3]"
+ ]
+ ]
+ },
+ "Where": {
+ "Description": "Where returns a filtered subset of a given data type.",
+ "Args": [
+ "seq",
+ "key",
+ "args"
+ ],
+ "Aliases": [
+ "where"
+ ],
+ "Examples": []
+ }
+ },
+ "crypto": {
+ "MD5": {
+ "Description": "MD5 hashes the given input and returns its MD5 checksum.",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "md5"
+ ],
+ "Examples": [
+ [
+ "{{ md5 \"Hello world, gophers!\" }}",
+ "b3029f756f98f79e7f1b7f1d1f0dd53b"
+ ],
+ [
+ "{{ crypto.MD5 \"Hello world, gophers!\" }}",
+ "b3029f756f98f79e7f1b7f1d1f0dd53b"
+ ]
+ ]
+ },
+ "SHA1": {
+ "Description": "SHA1 hashes the given input and returns its SHA1 checksum.",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "sha1"
+ ],
+ "Examples": [
+ [
+ "{{ sha1 \"Hello world, gophers!\" }}",
+ "c8b5b0e33d408246e30f53e32b8f7627a7a649d4"
+ ]
+ ]
+ },
+ "SHA256": {
+ "Description": "SHA256 hashes the given input and returns its SHA256 checksum.",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "sha256"
+ ],
+ "Examples": [
+ [
+ "{{ sha256 \"Hello world, gophers!\" }}",
+ "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46"
+ ]
+ ]
+ }
+ },
+ "data": {
+ "GetCSV": {
+ "Description": "GetCSV expects a data separator and one or n-parts of a URL to a resource which\ncan either be a local or a remote one.\nThe data separator can be a comma, semi-colon, pipe, etc, but only one character.\nIf you provide multiple parts for the URL they will be joined together to the final URL.\nGetCSV returns nil or a slice slice to use in a short code.",
+ "Args": [
+ "sep",
+ "urlParts"
+ ],
+ "Aliases": [
+ "getCSV"
+ ],
+ "Examples": []
+ },
+ "GetJSON": {
+ "Description": "GetJSON expects one or n-parts of a URL to a resource which can either be a local or a remote one.\nIf you provide multiple parts they will be joined together to the final URL.\nGetJSON returns nil or parsed JSON to use in a short code.",
+ "Args": [
+ "urlParts"
+ ],
+ "Aliases": [
+ "getJSON"
+ ],
+ "Examples": []
+ }
+ },
+ "encoding": {
+ "Base64Decode": {
+ "Description": "Base64Decode returns the base64 decoding of the given content.",
+ "Args": [
+ "content"
+ ],
+ "Aliases": [
+ "base64Decode"
+ ],
+ "Examples": [
+ [
+ "{{ \"SGVsbG8gd29ybGQ=\" | base64Decode }}",
+ "Hello world"
+ ],
+ [
+ "{{ 42 | base64Encode | base64Decode }}",
+ "42"
+ ]
+ ]
+ },
+ "Base64Encode": {
+ "Description": "Base64Encode returns the base64 encoding of the given content.",
+ "Args": [
+ "content"
+ ],
+ "Aliases": [
+ "base64Encode"
+ ],
+ "Examples": [
+ [
+ "{{ \"Hello world\" | base64Encode }}",
+ "SGVsbG8gd29ybGQ="
+ ]
+ ]
+ },
+ "Jsonify": {
+ "Description": "Jsonify encodes a given object to JSON.",
+ "Args": [
+ "v"
+ ],
+ "Aliases": [
+ "jsonify"
+ ],
+ "Examples": [
+ [
+ "{{ (slice \"A\" \"B\" \"C\") | jsonify }}",
+ "[\"A\",\"B\",\"C\"]"
+ ]
+ ]
+ }
+ },
+ "fmt": {
+ "Errorf": {
+ "Description": "",
+ "Args": [
+ "format",
+ "a"
+ ],
+ "Aliases": [
+ "errorf"
+ ],
+ "Examples": [
+ [
+ "{{ errorf \"%s.\" \"failed\" }}",
+ "failed."
+ ]
+ ]
+ },
+ "Print": {
+ "Description": "Print returns string representation of the passed arguments.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "print"
+ ],
+ "Examples": [
+ [
+ "{{ print \"works!\" }}",
+ "works!"
+ ]
+ ]
+ },
+ "Printf": {
+ "Description": "Printf returns a formatted string representation of the passed arguments.",
+ "Args": [
+ "format",
+ "a"
+ ],
+ "Aliases": [
+ "printf"
+ ],
+ "Examples": [
+ [
+ "{{ printf \"%s!\" \"works\" }}",
+ "works!"
+ ]
+ ]
+ },
+ "Println": {
+ "Description": "Println returns string representation of the passed arguments ending with a newline.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "println"
+ ],
+ "Examples": [
+ [
+ "{{ println \"works!\" }}",
+ "works!\n"
+ ]
+ ]
+ }
+ },
+ "images": {
+ "Config": {
+ "Description": "Config returns the image.Config for the specified path relative to the\nworking directory.",
+ "Args": [
+ "path"
+ ],
+ "Aliases": [
+ "imageConfig"
+ ],
+ "Examples": []
+ }
+ },
+ "inflect": {
+ "Humanize": {
+ "Description": "Humanize returns the humanized form of a single parameter.\n\nIf the parameter is either an integer or a string containing an integer\nvalue, the behavior is to add the appropriate ordinal.\n\n Example: \"my-first-post\" -\u003e \"My first post\"\n Example: \"103\" -\u003e \"103rd\"\n Example: 52 -\u003e \"52nd\"",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "humanize"
+ ],
+ "Examples": [
+ [
+ "{{ humanize \"my-first-post\" }}",
+ "My first post"
+ ],
+ [
+ "{{ humanize \"myCamelPost\" }}",
+ "My camel post"
+ ],
+ [
+ "{{ humanize \"52\" }}",
+ "52nd"
+ ],
+ [
+ "{{ humanize 103 }}",
+ "103rd"
+ ]
+ ]
+ },
+ "Pluralize": {
+ "Description": "Pluralize returns the plural form of a single word.",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "pluralize"
+ ],
+ "Examples": [
+ [
+ "{{ \"cat\" | pluralize }}",
+ "cats"
+ ]
+ ]
+ },
+ "Singularize": {
+ "Description": "Singularize returns the singular form of a single word.",
+ "Args": [
+ "in"
+ ],
+ "Aliases": [
+ "singularize"
+ ],
+ "Examples": [
+ [
+ "{{ \"cats\" | singularize }}",
+ "cat"
+ ]
+ ]
+ }
+ },
+ "lang": {
+ "NumFmt": {
+ "Description": "NumFmt formats a number with the given precision using the\nnegative, decimal, and grouping options. The `options`\nparameter is a string consisting of `\u003cnegative\u003e \u003cdecimal\u003e \u003cgrouping\u003e`. The\ndefault `options` value is `- . ,`.\n\nNote that numbers are rounded up at 5 or greater.\nSo, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.",
+ "Args": [
+ "precision",
+ "number",
+ "options"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ lang.NumFmt 2 12345.6789 }}",
+ "12,345.68"
+ ],
+ [
+ "{{ lang.NumFmt 2 12345.6789 \"- , .\" }}",
+ "12.345,68"
+ ],
+ [
+ "{{ lang.NumFmt 6 -12345.6789 \"- .\" }}",
+ "-12345.678900"
+ ],
+ [
+ "{{ lang.NumFmt 0 -12345.6789 \"- . ,\" }}",
+ "-12,346"
+ ],
+ [
+ "{{ -98765.4321 | lang.NumFmt 2 }}",
+ "-98,765.43"
+ ]
+ ]
+ },
+ "Translate": {
+ "Description": "Translate ...",
+ "Args": [
+ "id",
+ "args"
+ ],
+ "Aliases": [
+ "i18n",
+ "T"
+ ],
+ "Examples": []
+ }
+ },
+ "math": {
+ "Add": {
+ "Description": "Add adds two numbers.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "add"
+ ],
+ "Examples": [
+ [
+ "{{add 1 2}}",
+ "3"
+ ]
+ ]
+ },
+ "Ceil": {
+ "Description": "Ceil returns the least integer value greater than or equal to x.",
+ "Args": [
+ "x"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{math.Ceil 2.1}}",
+ "3"
+ ]
+ ]
+ },
+ "Div": {
+ "Description": "Div divides two numbers.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "div"
+ ],
+ "Examples": [
+ [
+ "{{div 6 3}}",
+ "2"
+ ]
+ ]
+ },
+ "Floor": {
+ "Description": "Floor returns the greatest integer value less than or equal to x.",
+ "Args": [
+ "x"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{math.Floor 1.9}}",
+ "1"
+ ]
+ ]
+ },
+ "Log": {
+ "Description": "Log returns the natural logarithm of a number.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{math.Log 1}}",
+ "0"
+ ]
+ ]
+ },
+ "Mod": {
+ "Description": "Mod returns a % b.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "mod"
+ ],
+ "Examples": [
+ [
+ "{{mod 15 3}}",
+ "0"
+ ]
+ ]
+ },
+ "ModBool": {
+ "Description": "ModBool returns the boolean of a % b. If a % b == 0, return true.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "modBool"
+ ],
+ "Examples": [
+ [
+ "{{modBool 15 3}}",
+ "true"
+ ]
+ ]
+ },
+ "Mul": {
+ "Description": "Mul multiplies two numbers.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "mul"
+ ],
+ "Examples": [
+ [
+ "{{mul 2 3}}",
+ "6"
+ ]
+ ]
+ },
+ "Round": {
+ "Description": "Round returns the nearest integer, rounding half away from zero.",
+ "Args": [
+ "x"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{math.Round 1.5}}",
+ "2"
+ ]
+ ]
+ },
+ "Sub": {
+ "Description": "Sub subtracts two numbers.",
+ "Args": [
+ "a",
+ "b"
+ ],
+ "Aliases": [
+ "sub"
+ ],
+ "Examples": [
+ [
+ "{{sub 3 2}}",
+ "1"
+ ]
+ ]
+ }
+ },
+ "os": {
+ "FileExists": {
+ "Description": "FileExists checks whether a file exists under the given path.",
+ "Args": [
+ "i"
+ ],
+ "Aliases": [
+ "fileExists"
+ ],
+ "Examples": [
+ [
+ "{{ fileExists \"foo.txt\" }}",
+ "false"
+ ]
+ ]
+ },
+ "Getenv": {
+ "Description": "Getenv retrieves the value of the environment variable named by the key.\nIt returns the value, which will be empty if the variable is not present.",
+ "Args": [
+ "key"
+ ],
+ "Aliases": [
+ "getenv"
+ ],
+ "Examples": []
+ },
+ "ReadDir": {
+ "Description": "ReadDir lists the directory contents relative to the configured WorkingDir.",
+ "Args": [
+ "i"
+ ],
+ "Aliases": [
+ "readDir"
+ ],
+ "Examples": [
+ [
+ "{{ range (readDir \".\") }}{{ .Name }}{{ end }}",
+ "README.txt"
+ ]
+ ]
+ },
+ "ReadFile": {
+ "Description": "ReadFile reads the file named by filename relative to the configured WorkingDir.\nIt returns the contents as a string.\nThere is an upper size limit set at 1 megabytes.",
+ "Args": [
+ "i"
+ ],
+ "Aliases": [
+ "readFile"
+ ],
+ "Examples": [
+ [
+ "{{ readFile \"README.txt\" }}",
+ "Hugo Rocks!"
+ ]
+ ]
+ }
+ },
+ "partials": {
+ "Include": {
+ "Description": "Include executes the named partial and returns either a string,\nwhen the partial is a text/template, or template.HTML when html/template.",
+ "Args": [
+ "name",
+ "contextList"
+ ],
+ "Aliases": [
+ "partial"
+ ],
+ "Examples": [
+ [
+ "{{ partial \"header.html\" . }}",
+ "\u003ctitle\u003eHugo Rocks!\u003c/title\u003e"
+ ]
+ ]
+ },
+ "IncludeCached": {
+ "Description": "IncludeCached executes and caches partial templates. An optional variant\nstring parameter (a string slice actually, but be only use a variadic\nargument to make it optional) can be passed so that a given partial can have\nmultiple uses. The cache is created with name+variant as the key.",
+ "Args": [
+ "name",
+ "context",
+ "variant"
+ ],
+ "Aliases": [
+ "partialCached"
+ ],
+ "Examples": []
+ }
+ },
+ "safe": {
+ "CSS": {
+ "Description": "CSS returns a given string as html/template CSS content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeCSS"
+ ],
+ "Examples": [
+ [
+ "{{ \"Bat\u0026Man\" | safeCSS | safeCSS }}",
+ "Bat\u0026amp;Man"
+ ]
+ ]
+ },
+ "HTML": {
+ "Description": "HTML returns a given string as html/template HTML content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeHTML"
+ ],
+ "Examples": [
+ [
+ "{{ \"Bat\u0026Man\" | safeHTML | safeHTML }}",
+ "Bat\u0026Man"
+ ],
+ [
+ "{{ \"Bat\u0026Man\" | safeHTML }}",
+ "Bat\u0026Man"
+ ]
+ ]
+ },
+ "HTMLAttr": {
+ "Description": "HTMLAttr returns a given string as html/template HTMLAttr content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeHTMLAttr"
+ ],
+ "Examples": []
+ },
+ "JS": {
+ "Description": "JS returns the given string as a html/template JS content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeJS"
+ ],
+ "Examples": [
+ [
+ "{{ \"(1*2)\" | safeJS | safeJS }}",
+ "(1*2)"
+ ]
+ ]
+ },
+ "JSStr": {
+ "Description": "JSStr returns the given string as a html/template JSStr content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeJSStr"
+ ],
+ "Examples": []
+ },
+ "SanitizeURL": {
+ "Description": "SanitizeURL returns a given string as html/template URL content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "sanitizeURL",
+ "sanitizeurl"
+ ],
+ "Examples": []
+ },
+ "URL": {
+ "Description": "URL returns a given string as html/template URL content.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "safeURL"
+ ],
+ "Examples": [
+ [
+ "{{ \"http://gohugo.io\" | safeURL | safeURL }}",
+ "http://gohugo.io"
+ ]
+ ]
+ }
+ },
+ "strings": {
+ "Chomp": {
+ "Description": "Chomp returns a copy of s with all trailing newline characters removed.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "chomp"
+ ],
+ "Examples": [
+ [
++ "{{chomp \"\u003cp\u003eBlockhead\u003c/p\u003e\\n\" | safeHTML }}",
+ "\u003cp\u003eBlockhead\u003c/p\u003e"
+ ]
+ ]
+ },
+ "Contains": {
+ "Description": "",
+ "Args": null,
+ "Aliases": null,
+ "Examples": null
+ },
+ "ContainsAny": {
+ "Description": "",
+ "Args": null,
+ "Aliases": null,
+ "Examples": null
+ },
+ "CountRunes": {
+ "Description": "CountRunes returns the number of runes in s, excluding whitepace.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "countrunes"
+ ],
+ "Examples": []
+ },
+ "CountWords": {
+ "Description": "CountWords returns the approximate word count in s.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "countwords"
+ ],
+ "Examples": []
+ },
+ "FindRE": {
+ "Description": "FindRE returns a list of strings that match the regular expression. By default all matches\nwill be included. The number of matches can be limited with an optional third parameter.",
+ "Args": [
+ "expr",
+ "content",
+ "limit"
+ ],
+ "Aliases": [
+ "findRE"
+ ],
+ "Examples": [
+ [
+ "{{ findRE \"[G|g]o\" \"Hugo is a static side generator written in Go.\" \"1\" }}",
+ "[go]"
+ ]
+ ]
+ },
+ "HasPrefix": {
+ "Description": "HasPrefix tests whether the input s begins with prefix.",
+ "Args": [
+ "s",
+ "prefix"
+ ],
+ "Aliases": [
+ "hasPrefix"
+ ],
+ "Examples": [
+ [
+ "{{ hasPrefix \"Hugo\" \"Hu\" }}",
+ "true"
+ ],
+ [
+ "{{ hasPrefix \"Hugo\" \"Fu\" }}",
+ "false"
+ ]
+ ]
+ },
+ "HasSuffix": {
+ "Description": "",
+ "Args": null,
+ "Aliases": null,
+ "Examples": null
+ },
+ "Replace": {
+ "Description": "Replace returns a copy of the string s with all occurrences of old replaced\nwith new.",
+ "Args": [
+ "s",
+ "old",
+ "new"
+ ],
+ "Aliases": [
+ "replace"
+ ],
+ "Examples": [
+ [
+ "{{ replace \"Batman and Robin\" \"Robin\" \"Catwoman\" }}",
+ "Batman and Catwoman"
+ ]
+ ]
+ },
+ "ReplaceRE": {
+ "Description": "ReplaceRE returns a copy of s, replacing all matches of the regular\nexpression pattern with the replacement text repl.",
+ "Args": [
+ "pattern",
+ "repl",
+ "s"
+ ],
+ "Aliases": [
+ "replaceRE"
+ ],
+ "Examples": []
+ },
+ "SliceString": {
+ "Description": "SliceString slices a string by specifying a half-open range with\ntwo indices, start and end. 1 and 4 creates a slice including elements 1 through 3.\nThe end index can be omitted, it defaults to the string's length.",
+ "Args": [
+ "a",
+ "startEnd"
+ ],
+ "Aliases": [
+ "slicestr"
+ ],
+ "Examples": [
+ [
+ "{{slicestr \"BatMan\" 0 3}}",
+ "Bat"
+ ],
+ [
+ "{{slicestr \"BatMan\" 3}}",
+ "Man"
+ ]
+ ]
+ },
+ "Split": {
+ "Description": "Split slices an input string into all substrings separated by delimiter.",
+ "Args": [
+ "a",
+ "delimiter"
+ ],
+ "Aliases": [
+ "split"
+ ],
+ "Examples": []
+ },
+ "Substr": {
+ "Description": "Substr extracts parts of a string, beginning at the character at the specified\nposition, and returns the specified number of characters.\n\nIt normally takes two parameters: start and length.\nIt can also take one parameter: start, i.e. length is omitted, in which case\nthe substring starting from start until the end of the string will be returned.\n\nTo extract characters from the end of the string, use a negative start number.\n\nIn addition, borrowing from the extended behavior described at http://php.net/substr,\nif length is given and is negative, then that many characters will be omitted from\nthe end of string.",
+ "Args": [
+ "a",
+ "nums"
+ ],
+ "Aliases": [
+ "substr"
+ ],
+ "Examples": [
+ [
+ "{{substr \"BatMan\" 0 -3}}",
+ "Bat"
+ ],
+ [
+ "{{substr \"BatMan\" 3 3}}",
+ "Man"
+ ]
+ ]
+ },
+ "Title": {
+ "Description": "Title returns a copy of the input s with all Unicode letters that begin words\nmapped to their title case.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "title"
+ ],
+ "Examples": [
+ [
+ "{{title \"Bat man\"}}",
+ "Bat Man"
+ ],
+ [
+ "{{title \"somewhere over the rainbow\"}}",
+ "Somewhere Over the Rainbow"
+ ]
+ ]
+ },
+ "ToLower": {
+ "Description": "ToLower returns a copy of the input s with all Unicode letters mapped to their\nlower case.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "lower"
+ ],
+ "Examples": [
+ [
+ "{{lower \"BatMan\"}}",
+ "batman"
+ ]
+ ]
+ },
+ "ToUpper": {
+ "Description": "ToUpper returns a copy of the input s with all Unicode letters mapped to their\nupper case.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "upper"
+ ],
+ "Examples": [
+ [
+ "{{upper \"BatMan\"}}",
+ "BATMAN"
+ ]
+ ]
+ },
+ "Trim": {
+ "Description": "Trim returns a string with all leading and trailing characters defined\ncontained in cutset removed.",
+ "Args": [
+ "s",
+ "cutset"
+ ],
+ "Aliases": [
+ "trim"
+ ],
+ "Examples": [
+ [
+ "{{ trim \"++Batman--\" \"+-\" }}",
+ "Batman"
+ ]
+ ]
+ },
+ "TrimLeft": {
+ "Description": "TrimLeft returns a slice of the string s with all leading characters\ncontained in cutset removed.",
+ "Args": [
+ "cutset",
+ "s"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ \"aabbaa\" | strings.TrimLeft \"a\" }}",
+ "bbaa"
+ ]
+ ]
+ },
+ "TrimPrefix": {
+ "Description": "TrimPrefix returns s without the provided leading prefix string. If s doesn't\nstart with prefix, s is returned unchanged.",
+ "Args": [
+ "prefix",
+ "s"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ \"aabbaa\" | strings.TrimPrefix \"a\" }}",
+ "abbaa"
+ ],
+ [
+ "{{ \"aabbaa\" | strings.TrimPrefix \"aa\" }}",
+ "bbaa"
+ ]
+ ]
+ },
+ "TrimRight": {
+ "Description": "TrimRight returns a slice of the string s with all trailing characters\ncontained in cutset removed.",
+ "Args": [
+ "cutset",
+ "s"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ \"aabbaa\" | strings.TrimRight \"a\" }}",
+ "aabb"
+ ]
+ ]
+ },
+ "TrimSuffix": {
+ "Description": "TrimSuffix returns s without the provided trailing suffix string. If s\ndoesn't end with suffix, s is returned unchanged.",
+ "Args": [
+ "suffix",
+ "s"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ \"aabbaa\" | strings.TrimSuffix \"a\" }}",
+ "aabba"
+ ],
+ [
+ "{{ \"aabbaa\" | strings.TrimSuffix \"aa\" }}",
+ "aabb"
+ ]
+ ]
+ },
+ "Truncate": {
+ "Description": "Truncate truncates a given string to the specified length.",
+ "Args": [
+ "a",
+ "options"
+ ],
+ "Aliases": [
+ "truncate"
+ ],
+ "Examples": [
+ [
+ "{{ \"this is a very long text\" | truncate 10 \" ...\" }}",
+ "this is a ..."
+ ],
+ [
+ "{{ \"With [Markdown](/markdown) inside.\" | markdownify | truncate 14 }}",
+ "With \u003ca href=\"/markdown\"\u003eMarkdown …\u003c/a\u003e"
+ ]
+ ]
+ }
+ },
+ "time": {
+ "AsTime": {
+ "Description": "AsTime converts the textual representation of the datetime string into\na time.Time interface.",
+ "Args": [
+ "v"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ (time \"2015-01-21\").Year }}",
+ "2015"
+ ]
+ ]
+ },
+ "Duration": {
+ "Description": "Duration converts the given number to a time.Duration.\nUnit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.",
+ "Args": [
+ "unit",
+ "number"
+ ],
+ "Aliases": [
+ "duration"
+ ],
+ "Examples": [
+ [
+ "{{ mul 60 60 | duration \"second\" }}",
+ "1h0m0s"
+ ]
+ ]
+ },
+ "Format": {
+ "Description": "Format converts the textual representation of the datetime string into\nthe other form or returns it of the time.Time value. These are formatted\nwith the layout string",
+ "Args": [
+ "layout",
+ "v"
+ ],
+ "Aliases": [
+ "dateFormat"
+ ],
+ "Examples": [
+ [
+ "dateFormat: {{ dateFormat \"Monday, Jan 2, 2006\" \"2015-01-21\" }}",
+ "dateFormat: Wednesday, Jan 21, 2015"
+ ]
+ ]
+ },
+ "Now": {
+ "Description": "Now returns the current local time.",
+ "Args": null,
+ "Aliases": [
+ "now"
+ ],
+ "Examples": []
+ },
+ "ParseDuration": {
+ "Description": "ParseDuration parses a duration string.\nA duration string is a possibly signed sequence of\ndecimal numbers, each with optional fraction and a unit suffix,\nsuch as \"300ms\", \"-1.5h\" or \"2h45m\".\nValid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\".\nSee https://golang.org/pkg/time/#ParseDuration",
+ "Args": [
+ "in"
+ ],
+ "Aliases": null,
+ "Examples": [
+ [
+ "{{ \"1h12m10s\" | time.ParseDuration }}",
+ "1h12m10s"
+ ]
+ ]
+ }
+ },
+ "transform": {
+ "Emojify": {
+ "Description": "Emojify returns a copy of s with all emoji codes replaced with actual emojis.\n\nSee http://www.emoji-cheat-sheet.com/",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "emojify"
+ ],
+ "Examples": [
+ [
+ "{{ \"I :heart: Hugo\" | emojify }}",
+ "I ❤️ Hugo"
+ ]
+ ]
+ },
+ "HTMLEscape": {
+ "Description": "HTMLEscape returns a copy of s with reserved HTML characters escaped.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "htmlEscape"
+ ],
+ "Examples": [
+ [
+ "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\" | safeHTML}}",
+ "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;"
+ ],
+ [
+ "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\"}}",
+ "Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;"
+ ],
+ [
+ "{{ htmlEscape \"Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e\" | htmlUnescape | safeHTML }}",
+ "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e"
+ ]
+ ]
+ },
+ "HTMLUnescape": {
+ "Description": "HTMLUnescape returns a copy of with HTML escape requences converted to plain\ntext.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "htmlUnescape"
+ ],
+ "Examples": [
+ [
+ "{{ htmlUnescape \"Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;\" | safeHTML}}",
+ "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e"
+ ],
+ [
+ "{{\"Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;\" | htmlUnescape | htmlUnescape | safeHTML}}",
+ "Cathal Garvey \u0026 The Sunshine Band \u003ccathal@foo.bar\u003e"
+ ],
+ [
+ "{{\"Cathal Garvey \u0026amp;amp; The Sunshine Band \u0026amp;lt;cathal@foo.bar\u0026amp;gt;\" | htmlUnescape | htmlUnescape }}",
+ "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;"
+ ],
+ [
+ "{{ htmlUnescape \"Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;\" | htmlEscape | safeHTML }}",
+ "Cathal Garvey \u0026amp; The Sunshine Band \u0026lt;cathal@foo.bar\u0026gt;"
+ ]
+ ]
+ },
+ "Highlight": {
+ "Description": "Highlight returns a copy of s as an HTML string with syntax\nhighlighting applied.",
+ "Args": [
+ "s",
+ "lang",
+ "opts"
+ ],
+ "Aliases": [
+ "highlight"
+ ],
+ "Examples": []
+ },
+ "Markdownify": {
+ "Description": "Markdownify renders a given input from Markdown to HTML.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "markdownify"
+ ],
+ "Examples": [
+ [
+ "{{ .Title | markdownify}}",
+ "\u003cstrong\u003eBatMan\u003c/strong\u003e"
+ ]
+ ]
+ },
+ "Plainify": {
+ "Description": "Plainify returns a copy of s with all HTML tags removed.",
+ "Args": [
+ "s"
+ ],
+ "Aliases": [
+ "plainify"
+ ],
+ "Examples": [
+ [
+ "{{ plainify \"Hello \u003cstrong\u003eworld\u003c/strong\u003e, gophers!\" }}",
+ "Hello world, gophers!"
+ ]
+ ]
+ }
+ },
+ "urls": {
+ "AbsLangURL": {
+ "Description": "AbsLangURL takes a given string and converts it to an absolute URL according\nto a page's position in the project directory structure and the current\nlanguage.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "absLangURL"
+ ],
+ "Examples": []
+ },
+ "AbsURL": {
+ "Description": "AbsURL takes a given string and converts it to an absolute URL.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "absURL"
+ ],
+ "Examples": []
+ },
+ "Parse": {
+ "Description": "",
+ "Args": null,
+ "Aliases": null,
+ "Examples": null
+ },
+ "Ref": {
+ "Description": "Ref returns the absolute URL path to a given content item.",
+ "Args": [
+ "in",
+ "refs"
+ ],
+ "Aliases": [
+ "ref"
+ ],
+ "Examples": []
+ },
+ "RelLangURL": {
+ "Description": "RelLangURL takes a given string and prepends the relative path according to a\npage's position in the project directory structure and the current language.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "relLangURL"
+ ],
+ "Examples": []
+ },
+ "RelRef": {
+ "Description": "RelRef returns the relative URL path to a given content item.",
+ "Args": [
+ "in",
+ "refs"
+ ],
+ "Aliases": [
+ "relref"
+ ],
+ "Examples": []
+ },
+ "RelURL": {
+ "Description": "RelURL takes a given string and prepends the relative path according to a\npage's position in the project directory structure.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "relURL"
+ ],
+ "Examples": []
+ },
+ "URLize": {
+ "Description": "URLize returns the given argument formatted as URL.",
+ "Args": [
+ "a"
+ ],
+ "Aliases": [
+ "urlize"
+ ],
+ "Examples": []
+ }
+ }
+ }
+ }
+}
--- /dev/null
--- /dev/null
++{{ $package := (index .Params 0) }}
++{{ $listname := (index .Params 1) }}
++{{ $filter := split (index .Params 2) " " }}
++{{ $filter1 := index $filter 0 }}
++{{ $filter2 := index $filter 1 }}
++{{ $filter3 := index $filter 2 }}
++
++{{ $list := (index (index .Site.Data.docs $package) $listname) }}
++{{ $fields := after 3 .Params }}
++{{ $list := where $list $filter1 $filter2 $filter3 }}
++
++<table class="table table-bordered">
++ <tr>
++ {{ range $fields }}
++ <th>{{ . }}</th>
++ {{ end }}
++ </tr>
++ {{ range $list }}
++ <tr>
++ {{ range $k, $v := . }}
++ {{ $.Scratch.Set $k $v }}
++ {{ end }}
++ {{ range $fields }}
++ <td>{{ $.Scratch.Get . }}</td>
++ {{ end }}
++ </tr>
++ {{ end }}
++</table>
--- /dev/null
- {{ $original := .Page.Resources.GetByPrefix (.Get 0) }}
++{{ $original := .Page.Resources.GetMatch (printf "%s*" (.Get 0)) }}
+{{ $command := .Get 1 }}
+{{ $options := .Get 2 }}
+{{ if eq $command "Fit"}}
+{{ .Scratch.Set "image" ($original.Fit $options) }}
+{{ else if eq $command "Resize"}}
+{{ .Scratch.Set "image" ($original.Resize $options) }}
+{{ else if eq $command "Fill"}}
+{{ .Scratch.Set "image" ($original.Fill $options) }}
+{{ else }}
+{{ errorf "Invalid image processing command: Must be one of Fit, Fill or Resize."}}
+{{ end }}
+{{ $image := .Scratch.Get "image" }}
+<figure style="width: {{ add $image.Width 3 }}px; padding: 3px; background-color: #cccc">
+ <img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
+ <figcaption>
- <small>.{{ $command }} "{{ $options }}"</small>
++ <small>
++ {{ with .Inner }}
++ {{ . }}
++ {{ else }}
++ .{{ $command }} "{{ $options }}"
++ {{ end }}
++ </small>
+ </figcaption>
+</figure>
--- /dev/null
- HUGO_VERSION = "0.32.4"
+[build]
+ publish = "public"
+ command = "hugo"
+
+[context.production.environment]
- HUGO_VERSION = "0.32.4"
++ HUGO_VERSION = "0.34"
+ HUGO_ENV = "production"
+ HUGO_ENABLEGITINFO = "true"
+
+[context.deploy-preview.environment]
- HUGO_VERSION = "0.32.4"
++ HUGO_VERSION = "0.34"
+
+[context.branch-deploy.environment]
++ HUGO_VERSION = "0.34"
+
+[context.next.environment]
+ HUGO_BASEURL = "https://next--gohugoio.netlify.com/"
+ HUGO_ENABLEGITINFO = "true"
--- /dev/null
- <title>{{ block "title" . }}{{ .Site.Title }} {{ with .Title }} | {{ . }}{{ end }}{{ end }}</title>
+<!DOCTYPE html>
+<html class="no-js" lang="{{ with $.Site.LanguageCode }}{{ . }}{{ else }}en-us{{ end }}">
+ <head>
+ <meta charset="utf-8">
+ {{/* https://www.zachleat.com/web/preload/ */}}
+ <link rel="preload" href="{{ "files/muli-latin-200.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
+ <link rel="preload" href="{{ "files/muli-latin-400.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
+ <link rel="preload" href="{{ "files/muli-latin-800.woff2" | absURL }}" as="font" type="font/woff2" crossorigin>
+
+ <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+ {{/* NOTE: the Site's title, and if there is a page title, that is set too */}}
- {{- partial "twitter_cards.html" . -}}
++ <title>{{ block "title" . }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
+ <meta name="HandheldFriendly" content="True">
+ <meta name="MobileOptimized" content="320">
+
+ <meta name="viewport" content="width=device-width,minimum-scale=1">
+ {{ .Hugo.Generator }}
+
+ {{ if eq (getenv "HUGO_ENV") "production" | or (eq .Site.Params.env "production") }}
+ <META NAME="ROBOTS" CONTENT="INDEX, FOLLOW">
+ {{ else }}
+ <META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
+ {{ end }}
+
+ <link href='{{ "dist/main.css" | relURL }}' rel='stylesheet' type="text/css" />
+ {{- partial "head-additions.html" . -}}
+ {{- template "_internal/opengraph.html" . -}}
+ {{- template "_internal/google_news.html" . -}}
+ {{- template "_internal/schema.html" . -}}
++ {{- template "_internal/twitter_cards.html" . -}}
+
+ {{ if eq (getenv "HUGO_ENV") "production" | or (eq .Site.Params.env "production") }}
+ {{ template "_internal/google_analytics_async.html" . }}
+ {{ end }}
+
+
+
+
+ </head>
+ <body class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }} {{ . }}{{ end }}">
+ {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }}
+ {{ block "header" . }}{{ end }}
+ <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns">
+ {{ block "main" . }}{{ end }}
+ </main>
+
+ {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }}
+ {{ block "scripts" . }}{{- partial "site-scripts.html" . -}}{{ end }}
+
+ </body>
+</html>
projects / brevno-suite / hugo / commitdiff
