--- /dev/null
- * `height`
+---
+title: Shortcodes
+linktitle:
+description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-03-31
+menu:
+ docs:
+ parent: "content-management"
+ weight: 35
+weight: 35 #rem
+categories: [content management]
+keywords: [markdown,content,shortcodes]
+draft: false
+aliases: [/extras/shortcodes/]
+toc: true
+---
+
+## What a Shortcode is
+
+Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframes>`) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+
+Hugo created **shortcodes** to circumvent these limitations.
+
+A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+
+In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+
+## Use Shortcodes
+
+{{< youtube 2xkNJL4gJ9E >}}
+
+In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+
+The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
+
+Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+
+Here are two examples of paired shortcodes:
+
+```
+{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```
+
+```
+{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+```
+
+The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+
+### Shortcodes with Markdown
+
+The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
+
+```
+{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
+```
+
+### Shortcodes Without Markdown
+
+The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
+
+```
+{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
+```
+
+### Nested Shortcodes
+
+You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+
+## Use Hugo's Built-in Shortcodes
+
+Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
+
+### `figure`
+
+`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
+
+The `figure` shortcode can use the following named parameters:
+
+* `src`
+* `link`
+* `title`
+* `caption`
+* `class`
+* `attr` (i.e., attribution)
+* `attrlink`
+* `alt`
++* `width`
+
+#### Example `figure` Input
+
+{{< code file="figure-input-example.md" >}}
+{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+#### Example `figure` Output
+
+{{< output file="figure-output-example.html" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /output >}}
+
+### `gist`
+
+Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
+
+```
+https://gist.github.com/spf13/7896402
+```
+
+We can embed the gist in our content via username and gist ID pulled from the URL:
+
+```
+{{</* gist spf13 7896402 */>}}
+```
+
+#### Example `gist` Input
+
+If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
+
+{{< code file="gist-input.md" >}}
+{{</* gist spf13 7896402 "img.html" */>}}
+{{< /code >}}
+
+#### Example `gist` Output
+
+{{< output file="gist-output.html" >}}
+{{< gist spf13 7896402 >}}
+{{< /output >}}
+
+#### Example `gist` Display
+
+To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< gist spf13 7896402 >}}
+
+### `highlight`
+
+This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+
+#### Example `highlight` Input
+
+{{< code file="content/tutorials/learn-html.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Data.Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+#### Example `highlight` Output
+
+The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+
+{{< output file="tutorials/learn-html/index.html" >}}
+<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
+ <span style="color: #f92672"><div></span>
+ <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
+ {{ range .Data.Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ <span style="color: #f92672"></div></span>
+<span style="color: #f92672"></section></span>
+{{< /output >}}
+
+{{% note "More on Syntax Highlighting" %}}
+To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
+{{% /note %}}
+
+### `instagram`
+
+If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
+
+```
+https://www.instagram.com/p/BWNjjyYFxVx/
+```
+
+#### Example `instagram` Input
+
+{{< code file="instagram-input.md" >}}
+{{</* instagram BWNjjyYFxVx */>}}
+{{< /code >}}
+
+You also have the option to hide the caption:
+
+{{< code file="instagram-input-hide-caption.md" >}}
+{{</* instagram BWNjjyYFxVx hidecaption */>}}
+{{< /code >}}
+
+#### Example `instagram` Output
+
+By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="instagram-hide-caption-output.html" >}}
+{{< instagram BWNjjyYFxVx hidecaption >}}
+{{< /output >}}
+
+#### Example `instagram` Display
+
+Using the preceding `instagram` with hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< instagram BWNjjyYFxVx hidecaption >}}
+
+
+### `ref` and `relref`
+
+These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
+
+`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+
+{{% note "More on Cross References" %}}
+Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+{{% /note %}}
+
+`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+
+#### Example `ref` and `relref` Input
+
+```
+[Neat]({{</* ref "blog/neat.md" */>}})
+[Who]({{</* relref "about.md#who" */>}})
+```
+
+#### Example `ref` and `relref` Output
+
+Assuming that standard Hugo pretty URLs are turned on.
+
+```
+<a href="/blog/neat">Neat</a>
+<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
+```
+
+### `speakerdeck`
+
+To embed slides from [Speaker Deck][], click on "< /> Embed" (under Share right next to the template on Speaker Deck) and copy the URL:
+
+```
+<script async class="speakerdeck-embed" data-id="4e8126e72d853c0060001f97" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
+```
+
+#### `speakerdeck` Example Input
+
+Extract the value from the field `data-id` and pass it to the shortcode:
+
+{{< code file="speakerdeck-example-input.md" >}}
+{{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
+{{< /code >}}
+
+#### `speakerdeck` Example Output
+
+{{< output file="speakerdeck-example-input.md" >}}
+{{< speakerdeck 4e8126e72d853c0060001f97 >}}
+{{< /output >}}
+
+#### `speakerdeck` Example Display
+
+For the preceding `speakerdeck` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< speakerdeck 4e8126e72d853c0060001f97 >}}
+
+### `tweet`
+
+You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
+
+```
+https://twitter.com/spf13/status/877500564405444608
+```
+
+#### Example `tweet` Input
+
+Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
+
+{{< code file="example-tweet-input.md" >}}
+{{</* tweet 877500564405444608 */>}}
+{{< /code >}}
+
+#### Example `tweet` Output
+
+Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-tweet-output.html" >}}
+{{< tweet 877500564405444608 >}}
+{{< /output >}}
+
+#### Example `tweet` Display
+
+Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< tweet 877500564405444608 >}}
+
+### `vimeo`
+
+Adding a video from [Vimeo][] is equivalent to the YouTube shortcode above.
+
+```
+https://vimeo.com/channels/staffpicks/146022717
+```
+
+#### Example `vimeo` Input
+
+Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
+
+{{< code file="example-vimeo-input.md" >}}
+{{</* vimeo 146022717 */>}}
+{{< /code >}}
+
+#### Example `vimeo` Output
+
+Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-vimeo-output.html" >}}
+{{< vimeo 146022717 >}}
+{{< /output >}}
+
+{{% tip %}}
+If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well.
+
+```
+{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" */>}}
+```
+{{% /tip %}}
+
+#### Example `vimeo` Display
+
+Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< vimeo 146022717 >}}
+
+### `youtube`
+
+The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
+
+```
+https://www.youtube.com/watch?v=w7Ft2ymGmfc
+```
+
+
+#### Example `youtube` Input
+
+Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
+
+{{< code file="example-youtube-input.md" >}}
+{{</* youtube w7Ft2ymGmfc */>}}
+{{< /code >}}
+
+Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named an unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
+
+
+{{< code file="example-youtube-input-with-autoplay.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
+{{< /code >}}
+
+#### Example `youtube` Output
+
+Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
+
+{{< code file="example-youtube-output.html" >}}
+{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
+{{< /code >}}
+
+#### Example `youtube` Display
+
+Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
+
+{{< youtube w7Ft2ymGmfc >}}
+
+## Create Custom Shortcodes
+
+To learn more about creating custom shortcodes, see the [shortcode template documentation][].
+
+[`figure` shortcode]: #figure
+[contentmanagementsection]: /content-management/formats/
+[examplegist]: https://gist.github.com/spf13/7896402
+[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
+[Instagram]: https://www.instagram.com/
+[pagevariables]: /variables/page/
+[partials]: /templates/partials/
+[Pygments]: http://pygments.org/
+[quickstart]: /getting-started/quick-start/
+[sctemps]: /templates/shortcode-templates/
+[scvars]: /variables/shortcodes/
+[shortcode template documentation]: /templates/shortcode-templates/
+[Speaker Deck]: https://speakerdeck.com/
+[templatessection]: /templates/
+[Vimeo]: https://vimeo.com/
+[YouTube Videos]: https://www.youtube.com/
--- /dev/null
- The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments Documentation](http://pygments.org/) for details.
+---
+title: Syntax Highlighting
+description: Hugo comes with reallly fast syntax highlighting from Chroma.
+date: 2017-02-01
+publishdate: 2017-02-01
+keywords: [highlighting,pygments,chroma,code blocks,syntax]
+categories: [content management]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 300
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
+toc: true
+---
+
+From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.
+
+If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
+
+The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)).
+
+* `linenos=inline` or `linenos=table` (`table` will give copy-and-paste friendly code blocks) turns on line numbers.
+* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
+* `linenostart=199` starts the line number count from 199.
+
+With that, this:
+
+```
+{{</* highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" */>}}
+// ... code
+{{</* / highlight */>}}
+```
+
+Gives this:
+
+{{< highlight go "linenos=table,hl_lines=8 15-17,linenostart=199" >}}
+// GetTitleFunc returns a func that can be used to transform a string to
+// title case.
+//
+// The supported styles are
+//
+// - "Go" (strings.Title)
+// - "AP" (see https://www.apstylebook.com/)
+// - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)
+//
+// If an unknown or empty style is provided, AP style is what you get.
+func GetTitleFunc(style string) func(s string) string {
+ switch strings.ToLower(style) {
+ case "go":
+ return strings.Title
+ case "chicago":
+ tc := transform.NewTitleConverter(transform.ChicagoStyle)
+ return tc.Title
+ default:
+ tc := transform.NewTitleConverter(transform.APStyle)
+ return tc.Title
+ }
+}
+{{< / highlight >}}
+
+
+## Configure Syntax Hightlighter
+To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
+
+pygmentsOptions
+: A comma separated list of options. See below for a full list.
+
+pygmentsCodefences
+: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
+
+pygmentsStyle
+: The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set.
+
+pygmentsUseClasses
+: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
+
+pygmentsCodefencesGuessSyntax
+: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
+
+pygmentsUseClassic
+: Set to true to use Pygments instead of the much faster Chroma.
+
+### Options
+
+`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
+
+noclasses
+: Use inline style.
+
+linenos
+: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
+
+linenostart
+: Start the line numbers from this value (default is 1).
+
+
+hl_lines
+: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
+
+
++The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments HTML Formatter Documentation](http://pygments.org/docs/formatters/#HtmlFormatter) for details.
+
+
+## Generate Syntax Highlighter CSS
+
+If you run with `pygmentsUseClasses=true` in your site config, you need a style sheet.
+
+You can generate one with Hugo:
+
+```bash
+hugo gen chromastyles --style=monokai > syntax.css
+```
+
+Run `hugo gen chromastyles -h` for more options. See https://help.farbox.com/pygments.html for a gallery of available styles.
+
+
+## Highlight Shortcode
+
+Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
+
+### Example `highlight` Shortcode
+
+{{< code file="example-highlight-shortcode-input.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Data.Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+
+
+## Highlight Template Func
+
+See [Highlight](/functions/highlight/).
+
+## Highlight in Code Fences
+
+It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
+
+````
+```html
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Data.Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+```
+````
+
+
+## Highlight with Pygments Classic
+
+If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path.
+
+{{% note "Disclaimers on Pygments" %}}
+* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
+* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
+* The languages available for highlighting depend on your Pygments installation.
+{{% /note %}}
+
+If you have never worked with Pygments before, here is a brief primer:
+
++ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
++ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
+
+On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
+
+
+
+[Prism]: http://prismjs.com
+[prismdownload]: http://prismjs.com/download.html
+[Highlight.js]: http://highlightjs.org/
+[Rainbow]: http://craig.is/making/rainbows
+[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
+[Google Prettify]: https://github.com/google/code-prettify
+[Yandex]: http://yandex.ru/
--- /dev/null
- The Sixth Sense <- Content
- Unbreakable <- Content
- Moonrise Kingdom <- Content
+---
+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
- Unbreakable <- Content
- The Avengers <- Content
- xXx <- Content
++ The Sixth Sense <- Value
++ Unbreakable <- Value
++ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
- Unbreakable <- Content
++ 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:
+
+```
- Moonrise Kingdom <- Content
++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-meta-data-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
- 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/2013/11/sample-entry/`.
+---
+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-blog-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 they 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/index.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
- 2. Only `theme.toml` is accepted; ie. not `theme.yaml` andnot `theme.json`.
+---
+title: Add Your Hugo Theme to the Showcase
+linktitle: Themes
+description: If you've built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-27
+categories: [contribute]
+keywords: [contribute,themes,design]
+authors: [digitalcraftsman]
+menu:
+ docs:
+ parent: "contribute"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/contribute/theme/]
+wip: true
+toc: true
+---
+
+A collection of all themes created by the Hugo community, including screenshots and demos, can be found at <https://themes.gohugo.io>. Every theme in this list will automatically be added to the theme site. Theme updates aren't scheduled but usually happen at least once a week.
+
+## tl;dr
+
+1. Create your theme using `hugo new theme <THEMENAME>`;
+2. Test your theme against <https://github.com/spf13/HugoBasicExample> \*
+3. Add a `theme.toml` file to the root of the theme with all required metadata
+4. Add a descriptive `README.md` to the root of the theme source
+5. Add `/images/screenshot.png` and `/images/tn.png`
+
+\* If your theme doesn't fit into the `Hugo Basic Example` site, we encourage theme authors to supply a self-contained Hugo site in `/exampleSite`.
+
+{{% note %}}
+The folder name here---`exampleSite`---is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets, and a `config` file with preset values.
+{{% /note %}}
+
+See the [Hugo Artist theme's exampleSite][artistexample] for a good example.
+
+{{% note %}}
+Please make your example site's content is as neutral as possible. We hope this goes without saying.
+{{% /note %}}
+
+## Theme Requirements
+
+In order to add your theme to the Hugo Themes Showcase, the following requirements need to be met:
+
+1. `theme.toml` with all required fields
+2. Images for thumbnail and screenshot
+3. A good README file instructions for users
+4. Addition to the hugoThemes GitHub repository
+
+### Add Your Theme to the Repo
+
+The easiest way to add your theme is to [open up a new issue in the theme repository][themeissuenew] with a link to the theme's repository on GitHub.
+
+### Create a `theme.toml` File
+
+`theme.toml` contains metadata about the theme and its creator and should be created automatically when running the `hugo new theme`. The auto-generated file is provided here as well for easy downloading:
+
+{{< code file="theme.toml" download="theme.toml" >}}
+name = ""
+license = "MIT"
+licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
+description = ""
+homepage = "https://example.com/"
+tags = []
+features = []
+min_version = 0.19
+
+[author]
+ name = ""
+ homepage = ""
+
+# If porting an existing theme
+[original]
+ name = ""
+ homepage = ""
+ repo = ""
+{{< /code >}}
+
+The following fields are required:
+
+```
+name = "Hyde"
+license = "MIT"
+licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
+description = "An elegant open source and mobile first theme"
+homepage = "http://siteforthistheme.com/"
+tags = ["blog", "company"]
+features = ["blog"]
+min_version = 0.13
+
+[author]
+ name = "spf13"
+ homepage = "http://spf13.com/"
+
+# If porting an existing theme
+[original]
+ author = "mdo"
+ homepage = "http://hyde.getpoole.com/"
+ repo = "https://www.github.com/mdo/hyde"
+```
+
+{{% note %}}
+1. This is different from the `theme.toml` file created by `hugo new theme` in Hugo versions before v0.14.
- [themeissuenew]: https://github.com/gohugoio/hugoThemes/issues/new
++2. Only `theme.toml` is accepted; ie. not `theme.yaml` and `theme.json`.
+{{% /note %}}
+
+### Images
+
+Screenshots are used for previews in the Hugo Theme Gallery. Make sure that they have the right dimensions:
+
+* Thumbnail should be 900px × 600px
+* Screenshot should be 1500px × 1000px
+* Media must be located in
+ * <THEMEDIR>/images/screenshot.png</code>
+ * <THEMEDIR>/images/tn.png</code>
+
+Additional media may be provided in the same directory.
+
+### Create a README File
+
+Your theme's README file should be written in markdown and saved at the root of your theme's directory structure. Your `README.md` serves as
+
+1. Content for your theme's details page at <https://themes.gohugo.io>
+2. General information about the theme in your GitHub repository (i.e., it's usual purpose)
+
+#### Example `README.md`
+
+You can download the following `README.md` as an outline:
+
+{{< code file="README.md" download="README.md" >}}
+
+# Theme Title
+
+**Need input from @digitalcraftsman on what could be added to this file.**
+
+
+
+
+{{< /code >}}
+
+{{% note "Screenshots in your `README.md`"%}}
+If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
+{{% /note %}}
+
+[artistexample]: https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite
++[themeissuenew]: https://github.com/gohugoio/hugoThemes/issues/new
--- /dev/null
- summaryLength: 70
+---
+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"
+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 =
+# 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 files relative from
+source = ""
+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
- * <https://copr.fedorainfracloud.org/coprs/spf13/Hugo/> (updated to Hugo v0.16)
- * <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/> (updated to Hugo v0.22); usually released a few days after the official Hugo release.
+---
+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
+lastmod: 2017-02-20
+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 1.5+][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
+```
+
+{{% 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).
+{{% /note %}}
+
+### 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.
+
+### 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, 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
- ## Before You Begin
-
+---
+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
+---
+
+
+
- - [AWS](https://aws.amazon.com/)
- - [DigitalOcean](https://www.digitalocean.com/)
- - [Linode](https://www.linode.com/)
- - Azure (coming)
- - Google (coming)
+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:
- ### Before We Begin
++ - [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/)
+
- [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 select a host and region.
++### 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
+
- To get started, all you'll need an empty project directory. Create a directory wherever you want your application to live and `cd` into it:
++[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 %}}
+
- If you already have a functioning Hugo app, which should now be configured, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox).
++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 %}}
- Do this by add a custom install script at the root of your project that will install Hugo automatically for you:
++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.
+
- You'll generate your new application from inside a Nanobox console (this is why you don't need to worry about having Golang or Hugo installed).
++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.25.1/hugo_0.25.1_Linux-64bit.tar.gz
+ tar -xzf hugo_0.25.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 %}}
+
+### Generating a New Hugo App
+
- Once inside here use the following steps to create a new Hugo application:
++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
+---
+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#L166
+[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
- Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but much wants more. So we added **Fast Render Mode**. It is hard to explain, so start the Hugo development server with `hugo server` and start editing. Live reloads just got so much faster! The "how and what" is discussed in lenghts [other places](https://github.com/gohugoio/hugo/pull/3959), but the short version is that we now re-render only the parts of the site that you are working on.
+
+---
+date: 2017-10-16
+title: "Hugo 0.30: Race Car Edition!"
+description: "Fast Render Mode boosts live reloading!"
+categories: ["Releases"]
+slug: "0.30-relnotes"
+images:
+- images/blog/hugo-30-poster.png
+---
+
+
- The second performance related feature is a follow up to the Template Metrics added in Hugo `0.29`. Now, if you add the flag `--templateMetricsHints`, we will calculate a score for how your partials can be cached (with the `partialCached` template func).
++Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but much wants more. So we added **Fast Render Mode**. It is hard to explain, so start the Hugo development server with `hugo server` and start editing. Live reloads just got so much faster! The "how and what" is discussed at length in [other places](https://github.com/gohugoio/hugo/pull/3959), but the short version is that we now re-render only the parts of the site that you are working on.
+
- [@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@digitalcraftsman](https://github.com/digitalcraftsman), and [@bmon](https://github.com/bmon) for their ongoing contributions.
++The second performance-related feature is a follow-up to the Template Metrics added in Hugo `0.29`. Now, if you add the flag `--templateMetricsHints`, we will calculate a score for how your partials can be cached (with the `partialCached` template func).
+
+This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most noteable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier.
+
+This release represents **31 contributions by 10 contributors** to the main Hugo code base.
- * There have been several fixes and enhancements in the Chroma highlighter. One is that it now creates Pygments compatible CSS classes, which means that you may want ot re-generate the stylesheet. See the [Syntax Highlighting Doc](https://gohugo.io/content-management/syntax-highlighting/).
++[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contribution, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@digitalcraftsman](https://github.com/digitalcraftsman), and [@bmon](https://github.com/bmon) for their ongoing contributions.
+And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition.
+
+Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs),
+which has received **26 contributions by 15 contributors**. A special thanks to [@bep](https://github.com/bep), [@digitalcraftsman](https://github.com/digitalcraftsman), [@moorereason](https://github.com/moorereason), and [@kaushalmodi](https://github.com/kaushalmodi) for their work on the documentation site.
+
+Hugo now has:
+
+* 20195+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 454+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 180+ [themes](http://themes.gohugo.io/)
+
+## Notes
+
+* Running `hugo server` will now run with the new "Fast Render Mode" default on. To turn it off, run `hugo server --disableFastRender` or set `disableFastRender=true` in your site config.
- * Make sure `Date` and `PublishDate` is always set to a value if one is available [6a30874f](https://github.com/gohugoio/hugo/commit/6a30874f19610a38e846e120aac03c68e12f9b7b) [@bep](https://github.com/bep) [#3854](https://github.com/gohugoio/hugo/issues/3854)
++* There have been several fixes and enhancements in the Chroma highlighter. One is that it now creates Pygments compatible CSS classes, which means that you may want to re-generate the stylesheet. See the [Syntax Highlighting Doc](https://gohugo.io/content-management/syntax-highlighting/).
+
+## Enhancements
+
+### Performance
+* Only re-render the view(s) you're working on [60bd332c](https://github.com/gohugoio/hugo/commit/60bd332c1f68e49e6ac439047e7c660865189380) [@bep](https://github.com/bep) [#3962](https://github.com/gohugoio/hugo/issues/3962)
+* Detect `partialCached` candidates [5800a20a](https://github.com/gohugoio/hugo/commit/5800a20a258378440e203a6c4a4343f5077755df) [@bep](https://github.com/bep)
+* Move metrics output to the end of the site build [b277cb33](https://github.com/gohugoio/hugo/commit/b277cb33e4dfa7440fca3b7888026944ce056154) [@moorereason](https://github.com/moorereason)
+
+### Templates
+
+* Output `xmlns:xhtml` only if there are translations available [0859d9df](https://github.com/gohugoio/hugo/commit/0859d9dfe647db3b8a192da38ad7efb5480a29a1) [@jamieconnolly](https://github.com/jamieconnolly)
+* Add `errorf` template function [4fc67fe4](https://github.com/gohugoio/hugo/commit/4fc67fe44a3c65fc7faaed21d5fa5bb5f87edf2c) [@bmon](https://github.com/bmon) [#3817](https://github.com/gohugoio/hugo/issues/3817)
+* Add `os.FileExists` template function [28188789](https://github.com/gohugoio/hugo/commit/2818878994e906c292cbe00cb2a83f1531a21f32) [@digitalcraftsman](https://github.com/digitalcraftsman) [#3839](https://github.com/gohugoio/hugo/issues/3839)
+* Add `float` template function [57adc539](https://github.com/gohugoio/hugo/commit/57adc539fc98dcb6fba8070b9611b8bd545f6f7f) [@x3ro](https://github.com/x3ro) [#3307](https://github.com/gohugoio/hugo/issues/3307)
+* Rework the partial test and benchmarks [e2e8bcbe](https://github.com/gohugoio/hugo/commit/e2e8bcbec34702a27047b91b6b007a15f1fc0797) [@bep](https://github.com/bep)
+
+### Other
+
+* Change `SummaryLength` to be configurable (#3924) [8717a60c](https://github.com/gohugoio/hugo/commit/8717a60cc030f4310c1779c0cdd51db37ad636cd) [@bmon](https://github.com/bmon) [#3734](https://github.com/gohugoio/hugo/issues/3734)
+* Replace `make` with `mage` in CircleCI build [fe71cb6f](https://github.com/gohugoio/hugo/commit/fe71cb6f5f83cdc8374cf1fc35a6d48102bd4b12) [@bep](https://github.com/bep) [#3969](https://github.com/gohugoio/hugo/issues/3969)
+* Add table `linenos` support for Chroma highlighter [7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)
+* Replace `make` with `mage` [8d2580f0](https://github.com/gohugoio/hugo/commit/8d2580f07c0253e12524a4b5c13165f876d00b21) [@bep](https://github.com/bep) [#3937](https://github.com/gohugoio/hugo/issues/3937)
+* Create `magefile` from `Makefile` [384a6ac4](https://github.com/gohugoio/hugo/commit/384a6ac4bd2de16fcd6a1c952e7ca41b66023a12) [@natefinch](https://github.com/natefinch)
+* Clean up lint in various packages [47fdfd51](https://github.com/gohugoio/hugo/commit/47fdfd5196cd24a23b30afe1d88969ffb413ab59) [@moorereason](https://github.com/moorereason)
+
+## Fixes
+
++* Make sure `Date` and `PublishDate` are always set to a value if one is available [6a30874f](https://github.com/gohugoio/hugo/commit/6a30874f19610a38e846e120aac03c68e12f9b7b) [@bep](https://github.com/bep) [#3854](https://github.com/gohugoio/hugo/issues/3854)
+* Add correct config file name to verbose server log [15ec031d](https://github.com/gohugoio/hugo/commit/15ec031d9818d239bfbff525c00cd99cc3118a96) [@mdhender](https://github.com/mdhender)
--- /dev/null
- date: 2017-10-19
- title: "0.30.1"
- description: "0.30.1"
+
+---
++date: 2017-10-19T00:00:00+02:00
++title: "0.30.1: Two Important Bugfixes!"
++description: "Fixes `hugo -w` and validator-broken Sitemap."
+categories: ["Releases"]
++slug: 0.30.1-relnotes
++images:
++- images/blog/hugo-bug-poster.png
+---
+
+
+
+This is a bug-fix release with two important fixes.
+
+* Fix hugo -w [fa53b13c](https://github.com/gohugoio/hugo/commit/fa53b13ca0ffb1db6ed20f5353661d3f8a5fd455) [@bep](https://github.com/bep) [#3980](https://github.com/gohugoio/hugo/issues/3980)
+* Revert sitemap template change to make the Google validator happy [5109ed520](https://github.com/gohugoio/hugo/commit/5109ed520f2ddde815d50e7b31acbbfc57ce7719) [@bep](https://github.com/bep) [#3978](https://github.com/gohugoio/hugo/issues/3978)
+
+
+Hugo now has:
+
+* 20285+ [stars](https://github.com/gohugoio/hugo/stargazers)
+* 454+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors)
+* 180+ [themes](http://themes.gohugo.io/)
--- /dev/null
- date: 2017-10-19
- title: "0.30.2"
- description: "0.30.2"
+
+---
-
++date: 2017-10-19T12:00:00+02:00
++title: "0.30.2: One More Bugfix"
++description: "Fixes Fast Render mode when having sub-path in `baseURL`."
+slug: "0.30.2"
+categories: ["Releases"]
+images:
+- images/blog/hugo-bug-poster.png
-
- This release fixes Fast Render mode with sub-path in baseURL [31641033](https://github.com/gohugoio/hugo/commit/3164103310fbca1211cfa9ce4a5eb7437854b6ad) [@bep](https://github.com/bep) [#3981](https://github.com/gohugoio/hugo/issues/3981).
+---
++This release fixes Fast Render mode with sub-path in baseURL [31641033](https://github.com/gohugoio/hugo/commit/3164103310fbca1211cfa9ce4a5eb7437854b6ad) [@bep](https://github.com/bep) [#3981](https://github.com/gohugoio/hugo/issues/3981).
+
+
+
+
--- /dev/null
- Blackfriday flag: **`EXTENSION_*`** <br>
- Purpose: Enable one or more Blackfriday's Markdown extensions (if they aren't Hugo defaults). <br>
+## Blackfriday Options
+
+`taskLists`
+: default: **`true`**<br>
+ Blackfriday flag: <br>
+ Purpose: `false` turns off GitHub-style automatic task/TODO list generation.
+
+`smartypants`
+: default: **`true`** <br>
+ Blackfriday flag: **`HTML_USE_SMARTYPANTS`** <br>
+ Purpose: `false` disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If `true`, it may be fine-tuned with the `angledQuotes`, `fractions`, `smartDashes`, and `latexDashes` flags (see below).
+
+`smartypantsQuotesNBSP`
+: default: **`false`** <br>
+ Blackfriday flag: **`HTML_SMARTYPANTS_QUOTES_NBSP`** <br>
+ Purpose: `true` enables French style Guillemets with non-breaking space inside the quotes.
+
+`angledQuotes`
+: default: **`false`**<br>
+ Blackfriday flag: **`HTML_SMARTYPANTS_ANGLED_QUOTES`**<br>
+ Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to «Hugo» instead of “Hugo”.
+
+`fractions`
+: default: **`true`**<br>
+ Blackfriday flag: **`HTML_SMARTYPANTS_FRACTIONS`** <br>
+ Purpose: <code>false</code> disables smart fractions.<br>
+ Example: `5/12` renders to <sup>5</sup>⁄<sub>12</sub>(<code><sup>5</sup>&frasl;<sub>12</sub></code>).<br> <strong>Caveat:</strong> Even with <code>fractions = false</code>, Blackfriday still converts `1/2`, `1/4`, and `3/4` respectively to ½ (<code>&frac12;</code>), ¼ (<code>&frac14;</code>) and ¾ (<code>&frac34;</code>), but only these three.</small>
+
+`smartDashes`
+: default: **`true`** <br>
+ Blackfriday flag: **`HTML_SMARTY_DASHES`** <br>
+ Purpose: `false` disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If `true`, its behavior can be modified with the `latexDashes` flag below.
+
+`latexDashes`
+: default: **`true`** <br>
+ Blackfriday flag: **`HTML_SMARTYPANTS_LATEX_DASHES`** <br>
+ Purpose: `false` disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming `smartDashes`: <br>
+ If `true`, `--` is translated into – (`–`), whereas `---` is translated into — (`—`). <br>
+ However, *spaced* single hyphen between two words is translated into an en dash— e.g., "`12 June - 3 July`" becomes `12 June – 3 July` upon rendering.
+
+`hrefTargetBlank`
+: default: **`false`** <br>
+ Blackfriday flag: **`HTML_HREF_TARGET_BLANK`** <br>
+ Purpose: `true` opens external links in a new window or tab.
+
+`plainIDAnchors`
+: default **`true`** <br>
+ Blackfriday flag: **`FootnoteAnchorPrefix` and `HeaderIDSuffix`** <br>
+ Purpose: `true` renders any heading and footnote IDs without the document ID. <br>
+ Example: renders `#my-heading` instead of `#my-heading:bec3ed8ba720b970`
+
+`extensions`
+: default: **`[]`** <br>
- *See [Blackfriday extensions](#blackfriday-extensions) section for more information.*
++ Purpose: Enable one or more Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
+ Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINK_BREAK`. <br>
- Blackfriday flag: **`EXTENSION_*`** <br>
- Purpose: Enable one or more of Blackfriday's Markdown extensions (if they aren't Hugo defaults). <br>
++ *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
+
+`extensionsmask`
+: default: **`[]`** <br>
- *See [Blackfriday extensions](#blackfriday-extensions) section for more information.*
++ Purpose: Disable one or more of Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
+ Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`. <br>
++ *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
+
+## Blackfriday extensions
+
+`noIntraEmphasis`
+: default: *enabled* <br>
+ Purpose: The "\_" character is commonly used inside words when discussing
+ code, so having Markdown interpret it as an emphasis command is usually the
+ wrong thing. When enabled, Blackfriday lets you treat all emphasis markers
+ as normal characters when they occur inside a word.
+
+`tables`
+: default: *enabled* <br>
+ Purpose: When enabled, tables can be created by drawing them in the input
+ using the below syntax:
+ Example:
+
+ Name | Age
+ --------|------
+ Bob | 27
+ Alice | 23
+
+`fencedCode`
+: default: *enabled* <br>
+ Purpose: When enabled, in addition to the normal 4-space indentation to mark
+ code blocks, you can explicitly mark them and supply a language (to make
+ syntax highlighting simple).
+
+ You can use 3 or more backticks to mark the beginning of the block, and the
+ same number to mark the end of the block.
+
+ Example:
+
+ ```md
+ # Heading Level 1
+ Some test
+ ## Heading Level 2
+ Some more test
+ ```
+
+`autolink`
+: default: *enabled* <br>
+ Purpose: When enabled, URLs that have not been explicitly marked as links
+ will be converted into links.
+
+`strikethrough`
+: default: *enabled* <br>
+ Purpose: When enabled, text wrapped with two tildes will be crossed out. <br>
+ Example: `~~crossed-out~~`
+
+`laxHtmlBlocks`
+: default: *disabled* <br>
+ Purpose: When enabled, loosen up HTML block parsing rules.
+
+`spaceHeaders`
+: default: *enabled* <br>
+ Purpose: When enabled, be strict about prefix header rules.
+
+`hardLineBreak`
+: default: *disabled* <br>
+ Purpose: When enabled, newlines in the input translate into line breaks in
+ the output.
+
+
+`tabSizeEight`
+: default: *disabled* <br>
+ Purpose: When enabled, expand tabs to eight spaces instead of four.
+
+`footnotes`
+: default: *enabled* <br>
+ Purpose: When enabled, Pandoc-style footnotes will be supported. The
+ footnote marker in the text that will become a superscript text; the
+ footnote definition will be placed in a list of footnotes at the end of the
+ document. <br>
+ Example:
+
+ This is a footnote.[^1]
+
+ [^1]: the footnote text.
+
+`noEmptyLineBeforeBlock`
+: default: *disabled* <br>
+ Purpose: When enabled, no need to insert an empty line to start a (code,
+ quote, ordered list, unordered list) block.
+
+
+`headerIds`
+: default: *enabled* <br>
+ Purpose: When enabled, allow specifying header IDs with `{#id}`.
+
+`titleblock`
+: default: *disabled* <br>
+ Purpose: When enabled, support [Pandoc-style title blocks][1].
+
+`autoHeaderIds`
+: default: *enabled* <br>
+ Purpose: When enabled, auto-create the header ID's from the headline text.
+
+`backslashLineBreak`
+: default: *enabled* <br>
+ Purpose: When enabled, translate trailing backslashes into line breaks.
+
+`definitionLists`
+: default: *enabled* <br>
+ Purpose: When enabled, a simple definition list is made of a single-line
+ term followed by a colon and the definition for that term. <br>
+ Example:
+
+ Cat
+ : Fluffy animal everyone likes
+
+ Internet
+ : Vector of transmission for pictures of cats
+
+ Terms must be separated from the previous definition by a blank line.
+
+`joinLines`
+: default: *enabled* <br>
+ Purpose: When enabled, delete newlines and join the lines.
+
+[1]: http://pandoc.org/MANUAL.html#extension-pandoc_title_block
--- /dev/null
- {{ end }}.
+---
+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]
+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="">
- {{ .Page.Now.Year }}
++{{ 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.
+
+## 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
+---
+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:
+ 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.
+
++`.CurrentSection`
++: the page's current section. The value can be the page itself if it is a section or the homepage.
++
+`.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/).
+
+`.Section`
+: the [section](/content-management/sections/) this content belongs to.
+
++`.Sections`
++: the [sections](/content-management/sections/) below this content.
++
+`.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.
+
+## 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: 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
- HUGO_VERSION = "0.30"
+[build]
+ publish = "public"
+ command = "hugo"
+
+[context.production.environment]
- HUGO_VERSION = "0.30"
++ HUGO_VERSION = "0.30.2"
+ HUGO_ENV = "production"
+ HUGO_ENABLEGITINFO = "true"
+
+[context.deploy-preview.environment]
- HUGO_VERSION = "0.30"
++ HUGO_VERSION = "0.30.2"
+
+[context.branch-deploy.environment]
++ HUGO_VERSION = "0.30.2"
+
+[context.next.environment]
+ HUGO_BASEURL = "https://next--gohugoio.netlify.com/"
+ HUGO_ENABLEGITINFO = "true"
projects / brevno-suite / hugo / commitdiff