--- /dev/null
- 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.
-
+---
+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
+```
+
+
+## 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
- It is currently not possible to add a specific layout for one of the sub-sections.
+---
+title: Content Sections
+linktitle: Sections
+description: "Hugo generates a **section tree** that matches your content."
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [content management]
+keywords: [lists,sections,content types,organization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 50
+weight: 50 #rem
+draft: false
+aliases: [/content/sections/]
+toc: true
+---
+
+
+## Nested Sections
+
+The sections can be nested as deeply as you need.
+
+```bash
+blog
+├── funny-cats
+│ └── kittens
+│ └── _index.md
+└── tech
+ └── _index.md
+```
+
+
+**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
+
+
+{{% note %}}
+When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`).
+
++If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
+{{% /note %}}
+
+
+## Example: Breadcrumb Navigation
+
+With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
+
+
+{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
+<ol class="nav navbar-nav">
+ {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
+</ol>
+{{ define "breadcrumbnav" }}
+{{ if .p1.Parent }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }}
+{{ else if not .p1.IsHome }}
+{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }}
+{{ end }}
+<li{{ if eq .p1 .p2 }} class="active"{{ end }}>
+ <a href="{{ .p1.Permalink }}">{{ .p1.Title }}</a>
+</li>
+{{ end }}
+{{< /code >}}
+
+## Section Page Variables and Methods
+
+Also see [Page Variables](/variables/page/).
+
+{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}}
+
+## Content Section Lists
+
+Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
+
+## Content *Section* vs Content *Type*
+
+By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
+
+[archetype]: /content-management/archetypes/
+[content type]: /content-management/types/
+[directory structure]: /getting-started/directory-structure/
+[section templates]: /templates/section-templates/
+
+
--- /dev/null
- Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/ will contain the following:`
+---
+title: URL Management
+linktitle: URL Management
+description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-09
+keywords: [aliases,redirects,permalinks,urls]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 110
+weight: 110 #rem
+draft: false
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+toc: true
+---
+
+## Permalinks
+
+The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy.
+
+The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
+
+{{% note "Default Publish and Content Folders" %}}
+These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
+{{% /note %}}
+
+For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
+
+### YAML Permalinks Configuration Example
+
+{{< code file="config.yml" copy="false" >}}
+permalinks:
+ post: /:year/:month/:title/
+{{< /code >}}
+
+### TOML Permalinks Configuration Example
+
+{{< code file="config.toml" copy="false" >}}
+[permalinks]
+ post = "/:year/:month/:title/"
+{{< /code >}}
+
+Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.
+
+You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`.
+
+### Permalink Configuration Values
+
+The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date.
+
+`:year`
+: the 4-digit year
+
+`:month`
+: the 2-digit month
+
+`:monthname`
+: the name of the month
+
+`:day`
+: the 2-digit day
+
+`:weekday`
+: the 1-digit day of the week (Sunday = 0)
+
+`:weekdayname`
+: the name of the day of the week
+
+`:yearday`
+: the 1- to 3-digit day of the year
+
+`:section`
+: the content's section
+
+`:sections`
+: the content's sections hierarchy
+
+`:title`
+: the content's title
+
+`:slug`
+: the content's slug (or title if no slug is provided in the front matter)
+
+`:filename`
+: the content's filename (without extension)
+
+## Aliases
+
+For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
+
+Luckily, redirects can be handled easily with **aliases** in Hugo.
+
+### Example: Aliases
+
+Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this filed in TOML and YAML front matter, respectively.
+
+#### TOML Front Matter
+
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
++++
+aliases = [
+ "/posts/my-original-url/",
+ "/2010/01/01/even-earlier-url.html"
+]
++++
+{{< /code >}}
+
+#### YAML Front Matter
+
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
+---
+aliases:
+ - /posts/my-original-url/
+ - /2010/01/01/even-earlier-url.html
+---
+{{< /code >}}
+
+Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`.
+
+### Example: Aliases in Multilingual
+
+On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
+
+In `/posts/my-new-post.es.md`:
+
+```
+---
+aliases:
+ - /es/posts/my-original-post/
+---
+```
+
+### How Hugo Aliases Work
+
+When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
+
+For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
+
+```
+---
+title: My New post
+aliases: [/posts/my-old-url/]
+---
+```
+
++Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following:
+
+```
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>https://example.com/posts/my-intended-url</title>
+ <link rel="canonical" href="https://example.com/posts/my-intended-url"/>
+ <meta name="robots" content="noindex">
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
+ </head>
+</html>
+```
+
+The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name="robots" content="noindex">` lets search engine bots know that they should not crawl and index your new alias page.
+
+### Customize
+You may customize this alias page by creating an `alias.html` template in the
+layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is
+
+`Permalink`
+: the link to the page being aliased
+
+`Page`
+: the Page data for the page being aliased
+
+### Important Behaviors of Aliases
+
+1. Hugo makes no assumptions about aliases. They also do not change based
+on your UglyURLs setting. You need to provide absolute paths to your web root
+and the complete filename or directory.
+2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location.
+
+## Pretty URLs
+
+Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work.
+
+The following demonstrates the concept:
+
+```
+content/posts/_index.md
+=> example.com/posts/index.html
+content/posts/post-1.md
+=> example.com/posts/post-1/
+```
+
+## Ugly URLs
+
+If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`..
+
+If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
+
+See [Content Organization][contentorg] for more details on paths.
+
+```
+.
+└── content
+ └── about
+ | └── _index.md // <- https://example.com/about/
+ ├── 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/
+```
+
+Here's the same organization run with `hugo --uglyURLs`:
+
+```
+.
+└── content
+ └── about
+ | └── _index.md // <- https://example.com/about.html
+ ├── post
+ | ├── firstpost.md // <- https://example.com/post/firstpost.html
+ | ├── happy
+ | | └── ness.md // <- https://example.com/post/happy/ness.html
+ | └── secondpost.md // <- https://example.com/post/secondpost.html
+ └── quote
+ ├── first.md // <- https://example.com/quote/first.html
+ └── second.md // <- https://example.com/quote/second.html
+```
+
+
+## Canonicalization
+
+By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
+
+By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`.
+
+Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
+
+Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
+
+{{% note "`canonifyURLs` default change" %}}
+In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
+{{% /note %}}
+
+To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
+
+```
+hugo config | grep -i canon
+```
+
+Or, if you are on Windows and do not have `grep` installed:
+
+```
+hugo config | FINDSTR /I canon
+```
+
+## Override URLS with Front Matter
+
+In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content.
+
+Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg].
+
+## Relative URLs
+
+By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
+
+Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content.
+
+For example, if your `/post/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`.
+
+[config]: /getting-started/configuration/
+[contentorg]: /content-management/organization/
+[front matter]: /content-management/front-matter/
+[multilingual]: /content-management/multilingual/
+[sections]: /content-management/sections/
+[usage]: /getting-started/usage/
--- /dev/null
- | Function | Description | Example |
- |----------------|-------------------------------------------------------------------------------|----------------------------------|
- | `add` | Adds two integers. | `{{add 1 2}}` → 3 |
- | `div` | Divides two integers. | `{{div 6 3}}` → 2 |
- | `mod` | Modulus of two integers. | `{{mod 15 3}}` → 0 |
- | `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{modBool 15 3}}` → true |
- | `mul` | Multiplies two integers. | `{{mul 2 3}}` → 6 |
- | `sub` | Subtracts two integers. | `{{sub 3 2}}` → 1 |
- | `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{math.Ceil 2.1}}` → 3 |
- | `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{math.Floor 1.9}}` → 1 |
- | `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{math.Round 1.5}}` → 2 |
+---
+title: Math
+description: Hugo provides nine mathematical operators in templates.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [math, operators]
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+toc:
+signature: []
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+draft: false
+aliases: []
+---
+
++| Function | Description | Example |
++|--------------|-----------------------------------------------------------------------------|----------------------------------|
++| `add` | Adds two numbers. | `{{add 1 2}}` → `3` |
++| | *If one of the numbers is a float, the result is a float.* | `{{add 1.1 2}}` → `3.1` |
++| `sub` | Subtracts two numbers. | `{{sub 3 2}}` → `1` |
++| | *If one of the numbers is a float, the result is a float.* | `{{sub 3 2.5}}` → `0.5` |
++| `mul` | Multiplies two numbers. | `{{mul 2 3}}` → `6` |
++| | *If one of the numbers is a float, the result is a float.* | `{{mul 2 3.1}}` → `6.2` |
++| `div` | Divides two numbers. | `{{div 6 3}}` → `2` |
++| | | `{{div 6 4}}` → `1` |
++| | *If one of the numbers is a float, the result is a float.* | `{{div 6 4.0}}` → `1.5` |
++| `mod` | Modulus of two integers. | `{{mod 15 3}}` → `0` |
++| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{modBool 15 3}}` → `true` |
++| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{math.Ceil 2.1}}` → `3` |
++| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{math.Floor 1.9}}` → `1` |
++| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{math.Round 1.5}}` → `2` |
--- /dev/null
+---
+title: where
+# linktitle: where
+description: Filters an array to only the elements containing a matching value for a given field.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [filtering]
+signature: ["where COLLECTION KEY [OPERATOR] MATCH"]
+workson: [lists,taxonomies,terms,groups]
+hugoversion:
+relatedfuncs: [intersect,first,after,last]
+deprecated: false
+toc: true
+needsexample: true
+---
+
+`where` filters an array to only the elements containing a matching value for a given field.
+
+```
+{{ range where .Data.Pages "Section" "post" }}
+ {{ .Content }}
+{{ end }}
+```
+
+It can be used by dot-chaining the second argument to refer to a nested element of a value.
+
+```
++++
+series: golang
++++
+```
+
+```
+{{ range where .Site.Pages "Params.series" "golang" }}
+ {{ .Content }}
+{{ end }}
+```
+
+It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`.
+
+```
+{{ range where .Data.Pages "Section" "!=" "post" }}
+ {{ .Content }}
+{{ end }}
+```
+
+The following logical operators are vailable with `where`:
+
+`=`, `==`, `eq`
+: `true` if a given field value equals a matching value
+
+`!=`, `<>`, `ne`
+: `true` if a given field value doesn't equal a matching value
+
+`>=`, `ge`
+: `true` if a given field value is greater than or equal to a matching value
+
+`>`, `gt`
+: `true` if a given field value is greater than a matching value
+
+`<=`, `le`
+: `true` if a given field value is lesser than or equal to a matching value
+
+`<`, `lt`
+: `true` if a given field value is lesser than a matching value
+
+`in`
+: `true` if a given field value is included in a matching value; a matching value must be an array or a slice
+
+`not in`
+: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice
+
+`intersect`
+: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect].
+
+## Use `where` with `intersect`
+
+```
+{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }}
+ {{ if ne .Permalink $.Permalink }}
+ {{ .Render "summary" }}
+ {{ end }}
+{{ end }}
+```
+
+You can also put the returned value of the `where` clauses into a variable:
+
+{{< code file="where-intersect-variables.html" >}}
+{{ $v1 := where .Site.Pages "Params.a" "v1" }}
+{{ $v2 := where .Site.Pages "Params.b" "v2" }}
+{{ $filtered := $v1 | intersect $v2 }}
+{{ range $filtered }}
+{{ end }}
+{{< /code >}}
+
+## Use `where` with `first`
+
+The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
+
+{{< code file="where-with-first.html" >}}
+{{ range first 5 (where .Data.Pages "Section" "post") }}
+ {{ .Content }}
+{{ end }}
+{{< /code >}}
+
+## Nest `where` Clauses
+
+You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured:
+
+```
+{{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
+```
+
+## Unset Fields
+
+Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`.
+
+This can be useful to filter a small amount of pages from a large pool. Instead of set field on all pages, you can set field on required pages only.
+
+Only the following operators are available for `nil`
+
+* `=`, `==`, `eq`: True if the given field is not set.
+* `!=`, `<>`, `ne`: True if the given field is set.
+
+```
+{{ range where .Data.Pages ".Params.specialpost" "!=" nil }}
+ {{ .Content }}
+{{ end }}
+```
+
++## Portable `where` filters
++
++This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list.
++
++This will, by default, list pages from the _section with the most pages_.
++
++```html
++{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }}
++```
++
++The user can override the default in `config.toml`:
++
++```toml
++[params]
++mainSections = ["blog", "docs"]
++```
++
+[intersect]: /functions/intersect/
--- /dev/null
- : the page's current section. The value can be the page itself if it is a section or the homepage.
+.CurrentSection
- : whether the given page is in the current section. Note that this will always return false for pages that are not either regular, home or section pages.
++: The page's current section. The value can be the page itself if it is a section or the homepage.
+
+.InSection $anotherPage
- : whether the current page is an ancestor of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
++: Whether the given page is in the current section. Note that this will always return false for pages that are not either regular, home or section pages.
+
+.IsAncestor $anotherPage
- : whether the current page is a descendant of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
++: Whether the current page is an ancestor of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.IsDescendant $anotherPage
- : a section's parent section or a page's section.
++: Whether the current page is a descendant of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.Parent
- : the [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
++: A section's parent section or a page's section.
+
+.Section
- : the [sections](/content-management/sections/) below this content.
++: The [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
+
+.Sections
++: The [sections](/content-management/sections/) below this content.
--- /dev/null
--- /dev/null
++
++**1Password** is a password manager that keeps you safe online. It protects your secure information behind the one password only you know.
++
++
++The [1Password Support](https://support.1password.com/) website was built from scratch with **Hugo** and enhanced with **React** and **Elasticsearch** to give us the best of both worlds: The simplicity and performance of a static site, with the richness of a hosted web app.
--- /dev/null
--- /dev/null
++---
++
++title: 1Password Support
++date: 2018-02-22
++description: "Showcase: \"Compiles 400 pages in five languages in the blink of an eye.\""
++siteURL: https://support.1password.com/
++byline: "[Mitch Cohen](https://github.com/mitchchn), Documentation Team Lead"
++aliases: [/showcase/1password/]
++
++---
++
++At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did.
++
++### Not all static site generators are created equal
++
++Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo:
++
++**Hugo is static**. We're a security company, so we swear by static sites and use them wherever possible. We feel much safer pointing customers at HTML files than at a complicated server which needs to be hardened.
++
++**Hugo is Go**. We love the Go programming language at 1Password, and we were delighted to learn that Hugo used the same Go template syntax that our designers and front-end developers had already mastered.
++
++**Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye.
++
++**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and folder structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/).
++
++**Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax.
++
++**Hugo has an amazing developer community**. Hugo updates are frequent and filled to the brim with features and fixes. As we developed the multilingual version of our site, we submitted PRs for features we needed and were helped through the process by [@bep](https://github.com/bep) and others.
++
++**Hugo is simple to deploy**. Hugo has just the right amount of configuration options to fit into our build system without being too complicated.
++
++### Tech specs
++
++* [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016.
++* Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks.
++* Writers build and preview the site on their computers and contribute content using pull requests.
++ * We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages.
++* Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files.
++* The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS.
--- /dev/null
- With Hugo's [`readDir` and `readFile` template functions][reads], you can traverse your website's files on your server.
+---
+title: Local File Templates
+linktitle: Local File Templates
+description: Hugo's `readerDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates.
+godocref: https://golang.org/pkg/os/#FileInfo
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [files,directories]
+menu:
+ docs:
+ parent: "templates"
+ weight: 110
+weight: 110
+sections_weight: 110
+draft: false
+aliases: [/extras/localfiles/,/templates/local-files/]
+toc: true
+---
+
+## Traverse Local Files
+
- The [`readDir` function][reads] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system).
++With Hugo's [`readDir`][readDir] and [`readFile`][readFile] template functions, you can traverse your website's files on your server.
+
+## Use `readDir`
+
- The [`readfile` function][reads] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function.
++The [`readDir` function][readDir] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system).
+
+Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both:
+
+1. The file system root
+2. The current working directory
+
+### `readDir` Example: List Directory Files
+
+This shortcode creates a link to each of the files in a directory---display as the file's basename---along with the file's size in bytes.
+
+{{< code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" >}}
+{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/directoryindex.html" >}}
+{{< /code >}}
+
+You can then call the shortcode as follows inside of your content's markup:
+
+```
+{{</* directoryindex path="/static/css" pathURL="/css" */>}}
+```
+
+The above shortcode [is part of the code for the Hugo docs][dirindex]. Here it lists this site's CSS files:
+
+{{< directoryindex path="/themes/gohugoioTheme/static/dist" pathURL="/css" >}}
+
+{{% note "Slashes are Important" %}}
+The initial slash `/` in `pathURL` is important in the `directoryindex` shortcode. Otherwise, `pathURL` becomes relative to the current web page.
+{{% /note %}}
+
+## Use `readFile`
+
- [reads]: /functions/readfile/
++The [`readfile` function][readFile] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function.
+
+To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*:
+
+```
+{{ readFile "/content/templates/local-file-templates" }}
+```
+
+### `readFile` Example: Add a Project File to Content
+
+As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows:
+
+```
+{{</* readfile file="/path/to/local/file.txt" markdown="true" */>}}
+```
+
+{{% warning %}}
+If you are going to create [custom shortcodes](/templates/shortcode-templates/) with `readFile` for a theme, note that usage of the shortcode will refer to the project root and *not* your `themes` directory.
+{{% /warning %}}
+
+Here is the templating for our new `readfile` shortcode:
+
+{{< code file="layouts/shortcodes/readfile.html" download="readfile.html" >}}
+{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/readfile.html">}}
+{{< /code >}}
+
+This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is [`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows:
+
+```
+{{</* readfile file="/content/readfiles/testing.txt" */>}}
+```
+
+The output "string" for this shortcode declaration will be the following:
+
+```
+{{< readfile file="/content/readfiles/testing.txt" >}}
+```
+
+However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter:
+
+```
+{{</* readfile file="/content/readfiles/testing.txt" markdown="true" */>}}
+```
+
+And here is the result as [called directly in the Hugo docs][] and rendered for display:
+
+{{< readfile file="/content/readfiles/testing.txt" markdown="true">}}
+
+[called directly in the Hugo docs]: https://github.com/gohugoio/hugo/blob/master/docs/content/templates/files.md
+[dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
+[osfileinfo]: https://golang.org/pkg/os/#FileInfo
++[readDir]: /functions/readdir/
++[readFile]: /functions/readfile/
+[sc]: /content-management/shortcodes/
+[sct]: /templates/shortcode-templates/
+[readfilesource]: https://github.com/gohugoio/hugo/blob/master/
+[testfile]: https://github.com/gohugoio/hugo/blob/master/docs/testfile
--- /dev/null
+[build]
+publish = "public"
+command = "hugo"
+
+[context.production.environment]
+HUGO_VERSION = "0.36.1"
+HUGO_ENV = "production"
+HUGO_ENABLEGITINFO = "true"
+
++[context.split1]
++command = "hugo --enableGitInfo"
++
++[context.split1.environment]
++HUGO_VERSION = "0.36.1"
++HUGO_ENV = "production"
++
+[context.deploy-preview]
+command = "hugo -b $DEPLOY_PRIME_URL"
+
+[context.deploy-preview.environment]
+HUGO_VERSION = "0.36.1"
+
+[context.branch-deploy]
+command = "hugo -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy.environment]
+HUGO_VERSION = "0.36.1"
+
+[context.next.environment]
+HUGO_ENABLEGITINFO = "true"
++
projects / brevno-suite / hugo / commitdiff
