--- /dev/null
- <input type="search" id="search-input" class="needs-js bg-left bn f5 input-reset lh-solid mt3 mt0-ns pl4 pv2 w5 white" placeholder="Search the Docs" name="search-input" value="" style="background: transparent url('/images/icon-search.png') no-repeat 0 8px /16px 16px;">
+<form id="site-search-form" action="" role="search">
+ <fieldset class="bn ma0 pa0">
+ <label class="clip" for="search-input">Search</label>
- </form>
++ <input type="search" id="search-input" class="needs-js bg-left bn f5 input-reset lh-solid mt3 mt0-ns pl4 pv2 w5 white" placeholder="Search the Docs" name="search-input" value="" style="background: url('/images/icon-search.png') 5px 11px/16px 16px no-repeat; background-color: rgba(255,255,255,0);">
+ </fieldset>
++</form>
--- /dev/null
- ["Static Site Generators", O'Reilly]: https://www.oreilly.com/web-platform/free/files/static-site-generators.pdf
+---
+title: The Benefits of Static Site Generators
+linktitle: The Benefits of Static
+description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+keywords: [ssg,static,performance,security]
+menu:
+ docs:
+ parent: "about"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: []
+toc: false
+---
+
+The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.
+
+Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.
+
+Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.
+
+This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.
+
+## More on Static Site Generators
+
+* ["An Introduction to Static Site Generators", David Walsh][]
+* ["Hugo vs. WordPress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
+* ["Static Site Generators", O'Reilly][]
+* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][]
+* ["Top 10 Static Website Generators", Netlify blog][]
+* ["The Resurgence of Static", dotCMS][dotcms]
+
+
+["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
++["Static Site Generators", O'Reilly]: https://github.com/gohugoio/hugoDocs/files/1242701/static-site-generators.pdf
+["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
+[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
+[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
+[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static
--- /dev/null
- Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration abve with the weight of `80`.
+---
+title: Related Content
+description: List related content in "See Also" sections.
+date: 2017-09-05
+categories: [content management]
+keywords: [content]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 40
+weight: 30
+draft: false
+aliases: [/content/related/,/related/]
+toc: true
+---
+
+
+Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
+
+## List Related Content
+
+
+To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template:
+
+{{< code file="layouts/partials/related.html" >}}
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+<h3>See Also</h3>
+<ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+</ul>
+{{ end }}
+{{< /code >}}
+
+### Methods
+
+Here is the list of "Related" methods available on a page collection such `.RegularPages`.
+
+#### .Related PAGE
+Returns a collection of pages related the given one.
+
+```
+{{ $related := .Site.RegularPages.Related . }}
+```
+
+#### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
+Returns a collection of pages related to a given one restricted to a list of indices.
+
+```
+{{ $related := .Site.RegularPages.RelatedIndices . "tags" "date" }}
+```
+
+#### .RelatedTo KEYVALS [KEYVALS2 ...]
+Returns a collection of pages related together by a set of indices and their match.
+
+In order to build those set and pass them as argument, one must use the `keyVals` function where the first argument would be the `indice` and the consecutive ones its potential `matches`.
+
+```
+{{ $related := .Site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
+```
+
+{{% note %}}
+Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
+{{% /note %}}
+
+## Configure Related Content
+Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
+
+### Default configuration
+
+Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
+
+{{< code-toggle file="config" >}}
+related:
+ threshold: 80
+ includeNewer: false
+ toLower: false
+ indices:
+ - name: keywords
+ weight: 100
+ - name: date
+ weight: 10
+{{< /code-toggle >}}
+
++Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration above with the weight of `80`.
+
+Custom configuration should be set using the same syntax.
+
+{{% note %}}
+If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
+{{% /note %}}
+
+### Top Level Config Options
+
+threshold
+: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
+
+includeNewer
+: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
+
+toLower
+: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
+
+### Config Options per Index
+
+name
+: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
+
+weight
+: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
+
+pattern
+: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
+
+toLower
+: See above.
+
+## Performance Considerations
+
+**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
+
+This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
+
+{{< tweet 898398437527363585 >}}
+
+Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
+
+He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
+
+* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
+* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
+
+{{% note %}}
+We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
+{{% /note %}}
--- /dev/null
- {{< new-in "0.81" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
+---
+title: Configure Markup
+description: How to handle Markdown and other markup related configuration.
+date: 2019-11-15
+categories: [getting started,fundamentals]
+keywords: [configuration,highlighting]
+weight: 65
+sections_weight: 65
+slug: configuration-markup
+toc: true
+---
+
+## Configure Markup
+
+{{< new-in "0.60.0" >}}
+
+See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo.
+
+Below are all markup related configuration in Hugo with their default settings:
+
+{{< code-toggle config="markup" />}}
+
+**See each section below for details.**
+
+### Goldmark
+
+[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. Note that the feature set of Goldmark vs Blackfriday isn't the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions.
+
+This is the default configuration:
+
+{{< code-toggle config="markup.goldmark" />}}
+
+For details on the extensions, refer to [this section](https://github.com/yuin/goldmark/#built-in-extensions) of the Goldmark documentation
+
+Some settings explained:
+
+unsafe
+: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
+
+typographer
+: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/).
+
+attribute
+: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
+
++{{< new-in "0.81.0" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.
+
+A blockquote with a CSS class:
+
+```md
+> foo
+> bar
+{.myclass}
+```
+
+There are some current limitations: For tables you can currently only apply it to the full table, and for lists the `ul`/`ol`-nodes only, e.g.:
+
+```md
+* Fruit
+ * Apple
+ * Orange
+ * Banana
+ {.fruits}
+* Dairy
+ * Milk
+ * Cheese
+ {.dairies}
+{.list}
+```
+
+Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.:
+
+````
+```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// ... code
+```
+````
+
+autoHeadingIDType ("github") {{< new-in "0.62.2" >}}
+: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs work as with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func.
+
+### Blackfriday
+
+
+[Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set `defaultMarkdownHandler` to `blackfriday` in your top level `markup` config.
+
+This is the default config:
+
+{{< code-toggle config="markup.blackFriday" />}}
+
+### Highlight
+
+This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/).
+
+{{< code-toggle config="markup.highlight" />}}
+
+For `style`, see these galleries:
+
+* [Short snippets](https://xyproto.github.io/splash/docs/all.html)
+* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html)
+
+For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css).
+
+### Table Of Contents
+
+{{< code-toggle config="markup.tableOfContents" />}}
+
+These settings only works for the Goldmark renderer:
+
+startLevel
+: The heading level, values starting at 1 (`h1`), to start render the table of contents.
+
+endLevel
+: The heading level, inclusive, to stop render the table of contents.
+
+ordered
+: Whether or not to generate an ordered list instead of an unordered list.
+
+
+## Markdown Render Hooks
+
+{{< new-in "0.62.0" >}}
+
+Note that this is only supported with the [Goldmark](#goldmark) renderer.
+
+Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names `render-{feature}` in `layouts/_default/_markup`.
+
+You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}}
+
+The features currently supported are:
+
+* `image`
+* `link`
+* `heading` {{< new-in "0.71.0" >}}
+
+You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
+
+```bash
+layouts
+└── _default
+ └── _markup
+ ├── render-image.html
+ ├── render-image.rss.xml
+ └── render-link.html
+```
+
+Some use cases for the above:
+
+* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
+* Add `target=_blank` to external links.
+* Resolve and [process](/content-management/image-processing/) images.
+* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
+
+### Render Hook Templates
+
+The `render-link` and `render-image` templates will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Destination
+: The URL.
+
+Title
+: The title attribute.
+
+Text
+: The rendered (HTML) link text.
+
+PlainText
+: The plain variant of the above.
+
+The `render-heading` template will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Level
+: The header level (1--6)
+
+Anchor
+: An auto-generated html id unique to the header within the page
+
+Text
+: The rendered (HTML) text.
+
+PlainText
+: The plain variant of the above.
+
+Attributes (map) {{< new-in "0.82.0" >}}
+: A map of attributes (e.g. `id`, `class`)
+
+#### Link with title Markdown example:
+
+```md
+[Text](https://www.gohugo.io "Title")
+```
+
+Here is a code example for how the render-link.html template could look:
+
+{{< code file="layouts/_default/_markup/render-link.html" >}}
+<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
+{{< /code >}}
+
+#### Image Markdown example:
+
+```md
+
+```
+
+Here is a code example for how the render-image.html template could look:
+
+{{< code file="layouts/_default/_markup/render-image.html" >}}
+<p class="md__image">
+ <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
+</p>
+{{< /code >}}
+
+#### Heading link example
+
+Given this template file
+
+{{< code file="layouts/_default/_markup/render-heading.html" >}}
+<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
+{{< /code >}}
+
+And this markdown
+
+```md
+### Section A
+```
+
+The rendered html will be
+
+```html
+<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>
+```
--- /dev/null
- {{< code-toggle file="netlify" >}}
+---
+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 a 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 an authorization modal 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.
+
+## Configure Hugo Version in Netlify
+
+You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
+
+For production:
+
- HUGO_VERSION = "0.53"
- {{< /code-toggle >}}
++{{< code file="netlify.toml" codeLang="toml" >}}
+[context.production.environment]
- ```
++ HUGO_VERSION = "0.82.1"
++{{< /code >}}
+
+For testing:
+
- HUGO_VERSION = "0.53"
- ```
++{{< code file="netlify.toml" codeLang="toml" >}}
+[context.deploy-preview.environment]
++ HUGO_VERSION = "0.82.1"
++{{< /code >}}
+
+The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
+
+{{< code file="netlify.toml" nocode="true" >}}
+{{< readfile file="netlify.toml" highlight="toml" >}}
+{{< /code >}}
+
+## Build and Deploy Site
+
+In the Netlify console, 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.
+
+See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
+
+## 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>
+```
+
+You can update a theme to the latest version by executing the following command in the *root* directory of your project:
+
+```
+git submodule update --rebase --remote
+```
+
+## 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
- `if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{ end }}`.
+---
+title: Introduction to Hugo Templating
+linktitle: Introduction
+description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
+godocref: https://golang.org/pkg/html/template/
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-25
+categories: [templates,fundamentals]
+keywords: [go]
+menu:
+ docs:
+ parent: "templates"
+ weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
+toc: true
+---
+
+{{% note %}}
+The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/).
+{{% /note %}}
+
+Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
+
+## Basic Syntax
+
+Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`.
+
+### Access a Predefined Variable
+
+A _predefined variable_ could be a variable already existing in the
+current scope (like the `.Title` example in the [Variables]({{< relref
+"#variables" >}}) section below) or a custom variable (like the
+`$address` example in that same section).
+
+
+```go-html-template
+{{ .Title }}
+{{ $address }}
+```
+
+Parameters for functions are separated using spaces. The general syntax is:
+
+```
+{{ FUNCTION ARG1 ARG2 .. }}
+```
+
+The following example calls the `add` function with inputs of `1` and `2`:
+
+```go-html-template
+{{ add 1 2 }}
+```
+
+#### Methods and Fields are Accessed via dot Notation
+
+Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
+
+```go-html-template
+{{ .Params.bar }}
+```
+
+#### Parentheses Can be Used to Group Items Together
+
+```go-html-template
+{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
+```
+
+## Variables {#variables}
+
+Each Go Template gets a data object. In Hugo, each template is passed
+a `Page`. In the below example, `.Title` is one of the elements
+accessible in that [`Page` variable][pagevars].
+
+With the `Page` being the default scope of a template, the `Title`
+element in current scope (`.` -- "the **dot**") is accessible simply
+by the dot-prefix (`.Title`):
+
+```go-html-template
+<title>{{ .Title }}</title>
+```
+
+Values can also be stored in custom variables and referenced later:
+
+{{% note %}}
+The custom variables need to be prefixed with `$`.
+{{% /note %}}
+
+```go-html-template
+{{ $address := "123 Main St." }}
+{{ $address }}
+```
+
+{{% warning %}}
+For Hugo v0.47 and older versions, variables defined inside `if`
+conditionals and similar are not visible on the outside.
+See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608).
+
+Hugo has created a workaround for this issue in [Scratch](/functions/scratch).
+{{% /warning %}}
+
+For **Hugo v0.48** and newer, variables can be re-defined using the
+new `=` operator (new in Go 1.11).
+
+Below example will work only in these newer Hugo versions. The example
+prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on
+all other pages:
+
+```go-html-template
+{{ $var := "Hugo Page" }}
+{{ if .IsHome }}
+ {{ $var = "Hugo Home" }}
+{{ end }}
+Var is {{ $var }}
+```
+
+## Functions
+
+Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
+
+[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
+
+### Example 1: Adding Numbers
+
+```go-html-template
+{{ add 1 2 }}
+<!-- prints 3 -->
+```
+
+### Example 2: Comparing Numbers
+
+```go-html-template
+{{ lt 1 2 }}
+<!-- prints true (i.e., since 1 is less than 2) -->
+```
+
+Note that both examples make use of Go Template's [math functions][].
+
+{{% note "Additional Boolean Operators" %}}
+There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions).
+{{% /note %}}
+
+## Includes
+
+When including another template, you will need to pass it the data that it would
+need to access.
+
+{{% note %}}
+To pass along the current context, please remember to include a trailing **dot**.
+{{% /note %}}
+
+The templates location will always be starting at the `layouts/` directory
+within Hugo.
+
+### Partial
+
+The [`partial`][partials] function is used to include *partial* templates using
+the syntax `{{ partial "<PATH>/<PARTIAL>.<EXTENSION>" . }}`.
+
+Example of including a `layouts/partials/header.html` partial:
+
+```go-html-template
+{{ partial "header.html" . }}
+```
+
+### Template
+
+The `template` function was used to include *partial* templates
+in much older Hugo versions. Now it's useful only for calling
+[*internal* templates][internal_templates]. The syntax is `{{ template
+"_internal/<TEMPLATE>.<EXTENSION>" . }}`.
+
+{{% note %}}
+The available **internal** templates can be found
+[here](https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates).
+{{% /note %}}
+
+Example of including the internal `opengraph.html` template:
+
+```go-html-template
+{{ template "_internal/opengraph.html" . }}
+```
+
+## Logic
+
+Go Templates provide the most basic iteration and conditional logic.
+
+### Iteration
+
+The Go Templates make heavy use of `range` to iterate over a _map_,
+_array_, or _slice_. The following are different examples of how to
+use `range`.
+
+#### Example 1: Using Context (`.`)
+
+```go-html-template
+{{ range $array }}
+ {{ . }} <!-- The . represents an element in $array -->
+{{ end }}
+```
+
+#### Example 2: Declaring a variable name for an array element's value
+
+```go-html-template
+{{ range $elem_val := $array }}
+ {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 3: Declaring variable names for an array element's index _and_ value
+
+For an array or slice, the first declared variable will map to each
+element's index.
+
+```go-html-template
+{{ range $elem_index, $elem_val := $array }}
+ {{ $elem_index }} -- {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 4: Declaring variable names for a map element's key _and_ value
+
+For a map, the first declared variable will map to each map element's
+key.
+
+```go-html-template
+{{ range $elem_key, $elem_val := $map }}
+ {{ $elem_key }} -- {{ $elem_val }}
+{{ end }}
+```
+
+#### Example 5: Conditional on empty _map_, _array_, or _slice_.
+
+If the _map_, _array_, or _slice_ passed into the range is zero-length then the else statement is evaluated.
+
+```go-html-template
+{{ range $array }}
+ {{ . }}
+{{else}}
+ <!-- This is only evaluated if $array is empty -->
+{{ end }}
+```
+
+### Conditionals
+
++`if`, `else`, `with`, `or`, `and` and `not` provide the framework for handling conditional logic in Go Templates. Like `range`, `if` and `with` statements are closed with an `{{ end }}`.
+
+Go Templates treat the following values as **false**:
+
+- `false` (boolean)
+- 0 (integer)
+- any zero-length array, slice, map, or string
+
+#### Example 1: `with`
+
+It is common to write "if something exists, do this" kind of
+statements using `with`.
+
+{{% note %}}
+`with` rebinds the context `.` within its scope (just like in `range`).
+{{% /note %}}
+
+It skips the block if the variable is absent, or if it evaluates to
+"false" as explained above.
+
+```go-html-template
+{{ with .Params.title }}
+ <h4>{{ . }}</h4>
+{{ end }}
+```
+
+#### Example 2: `with` .. `else`
+
+Below snippet uses the "description" front-matter parameter's value if
+set, else uses the default `.Summary` [Page variable][pagevars]:
+
+
+```go-html-template
+{{ with .Param "description" }}
+ {{ . }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+See the [`.Param` function][param].
+
+#### Example 3: `if`
+
+An alternative (and a more verbose) way of writing `with` is using
+`if`. Here, the `.` does not get rebinded.
+
+Below example is "Example 1" rewritten using `if`:
+
+```go-html-template
+{{ if isset .Params "title" }}
+ <h4>{{ index .Params "title" }}</h4>
+{{ end }}
+```
+
+#### Example 4: `if` .. `else`
+
+Below example is "Example 2" rewritten using `if` .. `else`, and using
+[`isset` function][isset] + `.Params` variable (different from the
+[`.Param` **function**][param]) instead:
+
+```go-html-template
+{{ if (isset .Params "description") }}
+ {{ index .Params "description" }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+#### Example 5: `if` .. `else if` .. `else`
+
+Unlike `with`, `if` can contain `else if` clauses too.
+
+```go-html-template
+{{ if (isset .Params "description") }}
+ {{ index .Params "description" }}
+{{ else if (isset .Params "summary") }}
+ {{ index .Params "summary" }}
+{{ else }}
+ {{ .Summary }}
+{{ end }}
+```
+
+#### Example 6: `and` & `or`
+
+```go-html-template
+{{ if (and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")) }}
+```
+
+## Pipes
+
+One of the most powerful components of Go Templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
+
+Because of the very simple syntax of Go Templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
+
+A few simple examples should help convey how to use the pipe.
+
+### Example 1: `shuffle`
+
+The following two examples are functionally the same:
+
+```go-html-template
+{{ shuffle (seq 1 5) }}
+```
+
+
+```go-html-template
+{{ (seq 1 5) | shuffle }}
+```
+
+### Example 2: `index`
+
+The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function](/functions/index-function/), which is built into Go Templates:
+
+```go-html-template
+{{ index .Params "disqus_url" | html }}
+```
+
+### Example 3: `or` with `isset`
+
+```go-html-template
+{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
+Stuff Here
+{{ end }}
+```
+
+Could be rewritten as
+
+```go-html-template
+{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
+Stuff Here
+{{ end }}
+```
+
+### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments}
+
+By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
+
+```go-html-template
+{{ "<!--[if lt IE 9]>" | safeHTML }}
+ <script src="html5shiv.js"></script>
+{{ "<![endif]-->" | safeHTML }}
+```
+
+Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](https://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation:
+
+```go-html-template
+{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }}
+```
+
+## Context (aka "the dot") {#the-dot}
+
+The most easily overlooked concept to understand about Go Templates is
+that `{{ . }}` always refers to the **current context**.
+
+- In the top level of your template, this will be the data set made
+ available to it.
+- Inside of an iteration, however, it will have the value of the
+ current item in the loop; i.e., `{{ . }}` will no longer refer to
+ the data available to the entire page.
+
+If you need to access page-level data (e.g., page params set in front
+matter) from within the loop, you will likely want to do one of the
+following:
+
+### 1. Define a Variable Independent of Context
+
+The following shows how to define a variable independent of the context.
+
+{{< code file="tags-range-with-page-variable.html" >}}
+{{ $title := .Site.Title }}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% note %}}
+Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
+{{% /note %}}
+
+### 2. Use `$.` to Access the Global Context
+
+`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
+
+{{< code file="range-through-tags-w-global.html" >}}
+<ul>
+{{ range .Params.tags }}
+ <li>
+ <a href="/tags/{{ . | urlize }}">{{ . }}</a>
+ - {{ $.Site.Title }}
+ </li>
+{{ end }}
+</ul>
+{{< /code >}}
+
+{{% warning "Don't Redefine the Dot" %}}
+The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
+{{% /warning %}}
+
+## Whitespace
+
+Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
+
+For instance, the following Go Template will include the newlines and horizontal tab in its HTML output:
+
+```go-html-template
+<div>
+ {{ .Title }}
+</div>
+```
+
+Which will output:
+
+```html
+<div>
+ Hello, World!
+</div>
+```
+
+Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
+
+```go-html-template
+<div>
+ {{- .Title -}}
+</div>
+```
+
+Which then outputs:
+
+```html
+<div>Hello, World!</div>
+```
+
+Go considers the following characters _whitespace_:
+
+* <kbd>space</kbd>
+* horizontal <kbd>tab</kbd>
+* carriage <kbd>return</kbd>
+* newline
+
+## Comments
+
+In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo.
+
+### Go Templates comments
+
+Go Templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered.
+
+For example:
+
+```go-html-template
+Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott.
+```
+
+Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block.
+
+### HTML comments
+
+If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example:
+
+```go-html-template
+{{ printf "<!-- Our website is named: %s -->" .Site.Title | safeHTML }}
+```
+
+#### HTML comments containing Go Templates
+
+HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process.
+
+{{% note %}}
+Do **not** try to comment out Go Template code using HTML comments.
+{{% /note %}}
+
+```go-html-template
+<!-- {{ $author := "Emma Goldman" }} was a great woman. -->
+{{ $author }}
+```
+
+The templating engine will strip the content within the HTML comment, but will first evaluate any Go Template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error.
+
+## Hugo Parameters
+
+Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the [front matter format]({{< ref "front-matter.md#front-matter-formats" >}}).
+
+## Use Content (`Page`) Parameters
+
+You can provide variables to be used by templates in individual content's [front matter][].
+
+An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
+
+Here is the example front matter (YAML):
+
+```
+---
+title: Roadmap
+lastmod: 2017-03-05
+date: 2013-11-18
+notoc: true
+---
+```
+
+Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
+
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
+{{ if not .Params.notoc }}
+<aside>
+ <header>
+ <a href="#{{.Title | urlize}}">
+ <h3>{{.Title}}</h3>
+ </a>
+ </header>
+ {{.TableOfContents}}
+</aside>
+<a href="#" id="toc-toggle"></a>
+{{ end }}
+{{< /code >}}
+
+We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
+
+## Use Site Configuration Parameters
+
+You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
+
+For instance, you might declare the following:
+
+{{< code-toggle file="config" >}}
+params:
+ copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
+ twitteruser: "spf13"
+ sidebarrecentlimit: 5
+{{< /code >}}
+
+Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
+
+```go-html-template
+{{ if .Site.Params.copyrighthtml }}
+ <footer>
+ <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
+ </footer>
+{{ end }}
+```
+
+An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
+
+{{< code file="layouts/partials/twitter.html" >}}
+{{ with .Site.Params.twitteruser }}
+ <div>
+ <a href="https://twitter.com/{{.}}" rel="author">
+ <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
+
+```go-html-template
+<nav>
+ <h1>Recent Posts</h1>
+ <ul>
+ {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
+ <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
+ {{- end -}}
+ </ul>
+</nav>
+```
+
+## Example: Show Only Upcoming Events
+
+Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
+
+{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
+<h4>Upcoming Events</h4>
+<ul class="upcoming-events">
+{{ range where .Pages.ByDate "Section" "events" }}
+ {{ if ge .Date.Unix now.Unix }}
+ <li>
+ <!-- add span for event type -->
+ <span>{{ .Type | title }} —</span>
+ {{ .Title }} on
+ <!-- add span for event date -->
+ <span>{{ .Date.Format "2 January at 3:04pm" }}</span>
+ at {{ .Params.place }}
+ </li>
+ {{ end }}
+{{ end }}
+</ul>
+{{< /code >}}
+
+
+[`where` function]: /functions/where/
+[config]: /getting-started/configuration/
+[dotdoc]: https://golang.org/pkg/text/template/#hdr-Variables
+[first]: /functions/first/
+[front matter]: /content-management/front-matter/
+[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples."
+[Go html/template]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating"
+[gohtmltemplate]: https://golang.org/pkg/html/template/ "Godocs references for Go's html templating"
+[index]: /functions/index-function/
+[math functions]: /functions/math/
+[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs"
+[internal_templates]: /templates/internal/
+[relpermalink]: /variables/page/
+[safehtml]: /functions/safehtml/
+[sitevars]: /variables/site/
+[pagevars]: /variables/page/
+[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
+[where]: /functions/where/
+[with]: /functions/with/
+[godocsindex]: https://golang.org/pkg/text/template/ "Godocs page for index function"
+[param]: /functions/param/
+[isset]: /functions/isset/
--- /dev/null
- {{ with $suffix }}
+{{ $file := .Get "file" }}
+{{ $codeLang := "" }}
+{{ $suffix := findRE "(\\.[^.]+)$" $file 1 }}
- {{ if eq $codeLang "html"}}
++{{ with $suffix }}
+{{ $codeLang = (index . 0 | strings.TrimPrefix ".") }}
+{{ end }}
+{{ with .Get "codeLang" }}{{ $codeLang = . }}{{ end }}
- <div class="code relative" id="{{ $file | urlize}}">
++{{ if eq $codeLang "html" }}
+{{ $codeLang = "go-html-template" }}
+{{ end }}
- <div class="filename san-serif f6 dib lh-solid pl2 pv2">{{.}}</div>
++<div class="code relative" id="{{ $file | urlize }}">
+ {{- with $file -}}
- {{end}}
- <div class="code-copy-content nt3" {{with .Get "download"}}id="{{.}}"{{end}}>
- {{ if .Get "nocode" }}{{ $.Inner }}{{ else }}{{ with $codeLang }}{{- highlight $.Inner . "" | -}}{{ else }}<pre><code>{{- .Inner | string -}}</code></pre>{{ end }}{{ end }}
++ <div class="filename san-serif f6 dib lh-solid pl2 pv2">{{ . }}</div>
+ {{- end -}}
+
+ {{ if ne (.Get "copy") "false" }}
+ <button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button">
+ </button>
+ {{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}}
++ {{ end }}
++ <div class="code-copy-content nt3" {{ with .Get "download" }}id="{{ . }}"{{ end }}>
++ {{ $inner := trim .Inner "\n" | safeHTML }}
++ {{ if .Get "nocode" }}{{ $inner }}{{ else }}{{ with $codeLang }}{{ highlight $inner . "" }}{{ else }}<pre><code>{{ $inner }}</code></pre>{{ end }}{{ end }}
+ </div>
+
+</div>
projects / brevno-suite / hugo / commitdiff