From: Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
Date: Tue, 5 Sep 2017 16:09:40 +0000 (+0200)
Subject: docs: Merge commit '7d63a23b0c68d9cd7c7c09c2755619237bc03485'
X-Git-Tag: v0.27~12
X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=16c9127663951ace1a3901cf669c49cc72780ced;p=brevno-suite%2Fhugo

docs: Merge commit '7d63a23b0c68d9cd7c7c09c2755619237bc03485'
---

16c9127663951ace1a3901cf669c49cc72780ced
diff --cc docs/content/content-management/formats.md
index c2837ffc,00000000..1ff0784a
mode 100644,000000..100644
--- a/docs/content/content-management/formats.md
+++ b/docs/content/content-management/formats.md
@@@ -1,241 -1,0 +1,241 @@@
 +---
 +title: Supported Content Formats
 +linktitle: Supported Content Formats
 +description: Markdown and Emacs Org-Mode have native support, and additional formats (e.g. Asciidoc) come via external helpers.
 +date: 2017-01-10
 +publishdate: 2017-01-10
 +lastmod: 2017-04-06
 +categories: [content management]
 +#tags: [markdown,asciidoc,mmark,content format]
 +menu:
 +  docs:
 +    parent: "content-management"
 +    weight: 20
 +weight: 20	#rem
 +draft: false
 +aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/,/tutorials/mathjax/]
 +toc: true
 +---
 +
 +**Markdown is the main content format** and comes in two flavours:  The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in front matter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in front matter), both very fast markdown engines written in Go.
 +
 +For Emacs users, [goorgeous](https://github.com/chaseadamsio/goorgeous) provides built-in native support for Org-mode  (name your files `*.org` or set `markup = "org"` in front matter) 
 +
 +{{% note "Deeply Nested Lists" %}}
 +Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., <kbd>tab</kbd>) rather than 2-space indentations.
 +{{% /note %}}
 +
 +## Configure BlackFriday Markdown Rendering
 +
 +You can configure multiple aspects of Blackfriday as show in the following list. See the docs on [Configuration][config] for the full list of explicit directions you can give to Hugo when rendering your site.
 +
 +{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}}
 +
 +## Extend Markdown
 +
 +Hugo provides some convenient methods for extending markdown.
 +
 +### Task Lists
 +
 +Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.
 +
 +#### Example Task List Input
 +
 +{{< code file="content/my-to-do-list.md" >}}
 +- [ ] a task list item
 +- [ ] list syntax required
 +- [ ] incomplete
 +- [x] completed
 +{{< /code >}}
 +
 +#### Example Task List Output
 +
 +The preceding markdown produces the following HTML in your rendered website:
 +
 +```
 +<ul class="task-list">
 +    <li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
 +    <li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
 +    <li><input type="checkbox" disabled="" class="task-list-item"> incomplete</li>
 +    <li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
 +</ul>
 +```
 +
 +#### Example Task List Display
 +
 +The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to [the Hugo Docs stylesheet][hugocss].
 +
 +- [ ] a task list item
 +- [ ] list syntax required
 +- [ ] incomplete
 +- [x] completed
 +
 +### Emojis
 +
 +To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][].
 +
 +For a full list of emojis, see the [Emoji cheat sheet][emojis].
 +
 +### Shortcodes
 +
 +If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly.
 +
 +See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own.
 +
 +### Code Blocks
 +
 +Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` nested shortcode][hlsc] to render syntax highlighting via [Pygments][]. For usage examples and a complete explanation, see the [syntax highlighting documentation][hl] in [developer tools][].
 +
 +## Mmark
 +
 +Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmarkgh] or the full syntax on [Miek Gieben's website][].
 +
 +### Use Mmark
 +
 +As Hugo ships with Mmark, using the syntax is as easy as changing the extension of your content files from `.md` to `.mmark`.
 +
 +In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content's front matter:
 +
 +```
 +---
 +title: My Post
 +date: 2017-04-01
 +markup: mmark
 +---
 +```
 +
 +{{% warning %}}
 +Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/gohugoio/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/gohugoio/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/gohugoio/hugo/issues/2270)) are not fully supported. Contributions are welcome.
 +{{% /warning %}}
 +
 +## MathJax with Hugo
 +
 +[MathJax](http://www.mathjax.org/) is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.
 +
 +This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.
 +
 +### Enable MathJax
 +
 +The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a `<script>` tag for the officially recommended secure CDN ([cdn.js.com](https://cdnjs.com)):
 +
 +{{< code file="add-mathjax-to-page.html" >}}
 +<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
 +</script>
 +{{< /code >}}
 +
 +One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
 +
 +### Options and Features
 +
 +MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](http://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options).
 +
 +### Issues with Markdown
 +
 +{{% note %}}
 +The following issues with Markdown assume you are using `.md` for content and BlackFriday for parsing. Using [Mmark](#mmark) as your content format will obviate the need for the following workarounds.
 +
 +When using Mmark with MathJax, use `displayMath: [['$$','$$'], ['\\[','\\]']]`. See the [Mmark `README.md`](https://github.com/miekg/mmark/wiki/Syntax#math-blocks) for more information. In addition to MathJax, Mmark has been shown to work well with [KaTeX](https://github.com/Khan/KaTeX). See this [related blog post from a Hugo user](http://nosubstance.me/post/a-great-toolset-for-static-blogging/).
 +{{% /note %}}
 +
 +After enabling MathJax, any math entered between proper markers (see the [MathJax documentation][mathjaxdocs]) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior.
 +
 +### Solution
 +
 +There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts.
 +
 +Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author).
 +
 +{{< code file="mathjax-markdown-solution.html" >}}
 +<script type="text/x-mathjax-config">
 +MathJax.Hub.Config({
 +  tex2jax: {
 +    inlineMath: [['$','$'], ['\\(','\\)']],
 +    displayMath: [['$$','$$'], ['\[','\]']],
 +    processEscapes: true,
 +    processEnvironments: true,
 +    skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
 +    TeX: { equationNumbers: { autoNumber: "AMS" },
 +         extensions: ["AMSmath.js", "AMSsymbols.js"] }
 +  }
 +});
 +</script>
 +
 +<script type="text/x-mathjax-config">
 +  MathJax.Hub.Queue(function() {
 +    // Fix <code> tags after MathJax finishes running. This is a
 +    // hack to overcome a shortcoming of Markdown. Discussion at
 +    // https://github.com/mojombo/jekyll/issues/199
 +    var all = MathJax.Hub.getAllJax(), i;
 +    for(i = 0; i < all.length; i += 1) {
 +        all[i].SourceElement().parentNode.className += ' has-jax';
 +    }
 +});
 +</script>
 +{{< /code >}}
 +
 +
 +
 +As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.
 +
 +{{< code file="mathjax-style.css" >}}
 +code.has-jax {
 +    font: inherit;
 +    font-size: 100%;
 +    background: inherit;
 +    border: inherit;
 +    color: #515151;
 +}
 +{{< /code >}}
 +
 +In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
 +
 +### Usage
 +
 +With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!
 +
 +## Additional Formats Through External Helpers
 +
 +Hugo has new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].)
 +
 +For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](http://asciidoctor.org/docs/install-toolchain/)).
 +
 +To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files.
 +
 +{{% warning "Performance of External Helpers" %}}
 +Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
 +{{% /warning %}}
 +
 +## Learn Markdown
 +
 +Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running:
 +
 +* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
 +* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
 +* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
 +
 +[`emojify` function]: /functions/emojify/
- [ascii]: http://asciidoc.org/
++[ascii]: http://asciidoctor.org/
 +[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering
 +[blackfriday]: https://github.com/russross/blackfriday
 +[mmark]: https://github.com/miekg/mmark
 +[config]: /getting-started/configuration/
 +[developer tools]: /tools/
 +[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/
 +[fireball]: https://daringfireball.net/projects/markdown/
 +[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
 +[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
 +[hl]: /tools/syntax-highlighting/
 +[hlsc]: /content-management/shortcodes/#highlight
 +[hugocss]: /css/style.css
 +[ietf]: https://tools.ietf.org/html/
 +[mathjaxdocs]: https://docs.mathjax.org/en/latest/
 +[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
 +[mdtutorial]: http://www.markdowntutorial.com/
 +[Miek Gieben's website]: https://miek.nl/2016/March/05/mmark-syntax-document/
 +[mmark]: https://github.com/miekg/mmark
 +[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
 +[org]: http://orgmode.org/
 +[Pygments]: http://pygments.org/
 +[rest]: http://docutils.sourceforge.net/rst.html
 +[sc]: /content-management/shortcodes/
 +[sct]: /templates/shortcode-templates/
diff --cc docs/content/content-management/urls.md
index 29cd66e8,00000000..f6f8df11
mode 100644,000000..100644
--- a/docs/content/content-management/urls.md
+++ b/docs/content/content-management/urls.md
@@@ -1,277 -1,0 +1,277 @@@
 +---
 +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
 +#tags: [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., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
++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/2013/11/sample-entry/`.
 +
 +### 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
 +
 +`: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 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.
++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/
diff --cc docs/content/functions/NumFmt.md
index 6300c8e9,00000000..9940c47b
mode 100644,000000..100644
--- a/docs/content/functions/NumFmt.md
+++ b/docs/content/functions/NumFmt.md
@@@ -1,34 -1,0 +1,35 @@@
 +---
 +title: lang.NumFmt
- description: "Formats a number with a given precision using the requested `decimal`, `grouping`, and `negative` characters."
++description: "Formats a number with a given precision using the requested `negative`, `decimal`, and `grouping` options. The `options` parameter is a string consisting of `<negative> <decimal> <grouping>`."
 +godocref: ""
 +workson: []
 +date: 2017-02-01
 +publishdate: 2017-02-01
- lastmod: 2017-02-01
++lastmod: 2017-08-21
 +categories: [functions]
 +#tags: [numbers]
 +menu:
 +  docs:
 +    parent: "functions"
 +toc: false
- signature: ["lang.NumFmt <decimal> <grouping> <negative> <precision> <number>"]
++signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS]"]
 +workson: []
 +hugoversion:
 +relatedfuncs: []
 +deprecated: false
 +draft: false
 +aliases: []
 +comments:
 +---
 +
 +The default options value is `- . ,`.
 +
 +Numbers greater than or equal to 5 are rounded up. For example, if precision is set to `0`, `1.5` becomes `2`, and `1.4` becomes `1`.
 +
 +```
- {{ lang.NumFmt "," "." "-" 2 12345.6789 }} → 12.345,68
- {{ lang.NumFmt "." "" "-" 6 -12345.6789 }} → -12345.678900
- {{ lang.NumFmt "." "," "-" 0 -12345.6789 }} → -12,346
- {{ -98765.4321 | lang.NumFmt "." "," "-" 2 }} → -98,765.43
++{{ lang.NumFmt 2 12345.6789 }} → 12,345.68
++{{ lang.NumFmt 2 12345.6789 "- , ." }} → 12.345,68
++{{ lang.NumFmt 0 -12345.6789 "- . ," }} → -12,346
++{{ lang.NumFmt 6 -12345.6789 "- ." }} → -12345.678900
++{{ -98765.4321 | lang.NumFmt 2 }} → -98,765.43
 +```
diff --cc docs/content/functions/countrunes.md
index bcb136f8,00000000..8e72602b
mode 100644,000000..100644
--- a/docs/content/functions/countrunes.md
+++ b/docs/content/functions/countrunes.md
@@@ -1,28 -1,0 +1,28 @@@
 +---
 +title: countrunes
 +description: Determines the number of runes in a string excluding any whitespace.
 +godocref:
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [functions]
 +menu:
 +  docs:
 +    parent: "functions"
 +#tags: [counting, word count]
 +signature: ["countrunes INPUT"]
 +workson: []
 +hugoversion:
 +relatedfuncs: []
 +deprecated: false
- aliases: [/functions/countrunes/,/functions/countwords/]
++aliases: [/functions/countrunes/]
 +---
 +
 +In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
 +
 +```
 +{{ "Hello, 世界" | countrunes }}
 +<!-- outputs a content length of 8 runes. -->
 +```
 +
 +[pagevars]: /variables/page/
diff --cc docs/content/functions/math.md
index 6375ad73,00000000..9a53473e
mode 100644,000000..100644
--- a/docs/content/functions/math.md
+++ b/docs/content/functions/math.md
@@@ -1,65 -1,0 +1,33 @@@
 +---
 +title: Math
 +description: Hugo provides six mathematical operators in templates.
 +godocref:
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +#tags: [math, operators]
 +categories: [functions]
 +menu:
 +  docs:
 +    parent: "functions"
 +toc:
 +signature: []
 +workson: []
 +hugoversion:
 +relatedfuncs: []
 +deprecated: false
 +draft: false
 +aliases: []
 +---
 +
 +There are 6 basic mathematical operators that can be used in Hugo templates:
 +
 +| Function | Description              | Example                       |
 +| -------- | ------------------------ | ----------------------------- |
 +| `add`    | Adds two integers.       | `{{add 1 2}}` &rarr; 3        |
 +| `div`    | Divides two integers.    | `{{div 6 3}}` &rarr; 2        |
 +| `mod`    | Modulus of two integers. | `{{mod 15 3}}` &rarr; 0       |
 +| `modBool`| Boolean of modulus of two integers. Evaluates to `true` if = 0. | `{{modBool 15 3}}` &rarr; true |
 +| `mul`    | Multiplies two integers. | `{{mul 2 3}}` &rarr; 6        |
 +| `sub`    | Subtracts two integers.  | `{{sub 3 2}}` &rarr; 1        |
 +
- ## Use `add` with Strings
- 
- You can also use the `add` function with strings. You may like this functionality in many use cases, including creating new variables by combining page- or site-level variables with other strings.
- 
- For example, social media sharing with [Twitter Cards][cards] requires the following `meta` link in your site's `<head>` to display Twitter's ["Summary Card with Large Image"][twtsummary]:
- 
- ```
- <meta name="twitter:image" content="https://example.com/images/my-twitter-image.jpg">
- ```
- 
- Let's assume you have an `image` field in the front matter of each of your content files:
- 
- ```
- ---
- title: My Post
- image: my-post-image.jpg
- ---
- ```
- 
- You can then concatenate the `image` value (string) with the path to your `images` directory in `static` and leverage a URL-related templating function for increased flexibility:
- 
- {{< code file="partials/head/twitter-card.html" >}}
- {{$socialimage := add "images/" .Params.image}}
- <meta name="twitter:image" content="{{ $socialimage | absURL }}">
- {{< /code >}}
- 
- {{% note %}}
- The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` and its relative companion `relURL` is the recommended way to construct URLs in Hugo.
- {{% /note %}}
- 
- [cards]: https://dev.twitter.com/cards/overview
- [twtsummary]: https://dev.twitter.com/cards/types/summary-large-image
diff --cc docs/content/getting-started/installing.md
index 46cad2a2,00000000..6485de4e
mode 100644,000000..100644
--- a/docs/content/getting-started/installing.md
+++ b/docs/content/getting-started/installing.md
@@@ -1,490 -1,0 +1,490 @@@
 +---
 +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"]
 +#tags: [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&nbsp;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
 +
 +#### 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.
 +
 +### 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>&nbsp;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&gt;cd example.com
- C:\Hugo\Sites\example.com&gt;dir
- &nbsp;Directory of C:\hugo\sites\example.com
- &nbsp;
++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/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.
 +
 +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`.
++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]: https://pygments.org
++[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/
diff --cc docs/content/hosting-and-deployment/deployment-with-nanobox.md
index 00000000,00000000..c318155f
new file mode 100644
--- /dev/null
+++ b/docs/content/hosting-and-deployment/deployment-with-nanobox.md
@@@ -1,0 -1,0 +1,247 @@@
++---
++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]
++#tags: [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
++---
++
++![hugo with nanobox](/images/hosting-and-deployment/deployment-with-nanobox/hugo-with-nanobox.png)
++
++## Before You Begin
++
++Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application.
++
++{{% note %}}
++If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox)
++{{% /note %}}
++
++
++## What You'll Need
++
++With Nanobox you don't need to worry about having Golang or Hugo installed. They'll be installed as part of the development environment created for you.
++
++To get started you'll just need the following three items:
++
++* [A Nanobox Account](https://nanobox.io) - Signup is free
++* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool
++* An account with a hosting provider such as:
++  - [AWS](https://aws.amazon.com/)
++  - [DigitalOcean](https://www.digitalocean.com/)
++  - [Linode](https://www.linode.com/)
++  - Azure (coming)
++  - Google (coming)
++  - [Roll Your Own](https://docs.nanobox.io/providers/create/)
++
++### Before We Begin
++
++There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application.
++
++#### Connect a Host Account
++
++Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/).
++
++#### Launch a New Application on Nanobox
++
++[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and select a host and region.
++
++With those out of the way you're ready to get started!
++
++
++## Getting Started
++
++{{% note %}}
++If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox)
++{{% /note %}}
++
++To get started, all you'll need an empty project directory. Create a directory wherever you want your application to live and `cd` into it:
++
++`mkdir path/to/project && cd path/to/project`
++
++### Configure Hugo to run with Nanobox
++
++Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`:
++
++{{< code file="boxfile.yml" >}}
++run.config:
++
++  # use the static engine
++  engine: static
++  engine.config:
++
++    # tell the engine where to serve static assets from
++    rel_dir: public
++
++  # enable file watching for live reload
++  fs_watch: true
++
++  # install hugo
++  extra_steps:
++    - bash ./install.sh
++
++deploy.config:
++
++  # generate site on deploy
++  extra_steps:
++    - hugo
++
++{{< /code >}}
++
++{{% note %}}
++If you already have a functioning Hugo app, which should now be configured, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox).
++{{% /note %}}
++
++### Installing Hugo
++
++Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available.
++
++Do this by add 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
++
++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).
++
++Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted:
++
++```
++nanobox run
++```
++
++![nanobox run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-run.png)
++
++Once inside here 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
++```
++
++![hugo server](/images/hosting-and-deployment/deployment-with-nanobox/hugo-server.png)
++
++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.
++
++![nanobox deploy dry-run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-deploy-dry-run.png)
++
++### 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!
diff --cc docs/content/hosting-and-deployment/deployment-with-rsync.md
index 0d18da71,00000000..509949c2
mode 100644,000000..100644
--- a/docs/content/hosting-and-deployment/deployment-with-rsync.md
+++ b/docs/content/hosting-and-deployment/deployment-with-rsync.md
@@@ -1,137 -1,0 +1,137 @@@
 +---
- title: Deployment with Rysnc
- linktitle: Deployment with Rysnc
++title: Deployment with Rsync
++linktitle: Deployment with Rsync
 +description: If you have access to your web host with SSH, you can use a simple rsync one-liner to incrementally deploy your entire Hugo website.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [hosting and deployment]
- #tags: [rysnc,deployment]
++#tags: [rsync,deployment]
 +authors: [Adrien Poupin]
 +menu:
 +  docs:
 +    parent: "hosting-and-deployment"
 +    weight: 70
 +weight: 70
 +sections_weight: 70
 +draft: false
 +aliases: [/tutorials/deployment-with-rsync/]
 +toc: true
 +notesforauthors:
 +---
 +
 +## Assumptions
 +
 +* Access to your web host with SSH
 +* A functional static website built with Hugo
 +
 +The spoiler is that you can deploy your entire website with a command that looks like the following:
 +
 +```
 +hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
 +```
 +
 +As you will see, we put it in a shell script file, which makes building and deployment as easy as executing `./deploy`.
 +
 +## Install SSH Key
 +
 +If it is not done yet, we will make an automated way to SSH to your server. If you have already installed an SSH key, switch to the next section.
 +
 +First, install the ssh client. On Debian/Ubuntu/derivates, use the following command:
 +
 +{{< code file="install-openssh.sh" >}}
 +sudo apt-get install openssh-client
 +{{< /code >}}
 +
 +Then generate your ssh key by entering the following commands:
 +
 +```
 +~$ cd && mkdir .ssh & cd .ssh
 +~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id
 +~/.ssh/$ cat >> config <<EOF
 +Host HOST
 +     Hostname HOST
 +     Port 22
 +     User USER
 +     IdentityFile ~/.ssh/rsa_id
 +EOF
 +```
 +
 +Don't forget to replace the `HOST` and `USER` values with your own ones. Then copy your ssh public key to the remote server:
 +
 +```
 +~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
 +```
 +
 +Now you can easily connect to the remote server:
 +
 +```
 +~$ ssh user@host
 +Enter passphrase for key '/home/mylogin/.ssh/rsa_id':
 +```
 +
 +And you've done it!
 +
 +## Shell Script
 +
 +We will put the first command in a script at the root of your Hugo tree:
 +
 +```
 +~/websites/topologix.fr$ editor deploy
 +```
 +
 +Here you put the following content. Replace the `USER`, `HOST`, and `DIR` values with your own:
 +
 +```
 +#!/bin/sh
 +USER=my-user
 +HOST=my-server.com
 +DIR=my/directory/to/topologix.fr/   # might sometimes be empty!
 +
 +hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR}
 +
 +exit 0
 +```
 +
 +Note that `DIR` is the relative path from the remote user's home. If you have to specify a full path (for instance `/var/www/mysite/`) you must change `~/${DIR}` to `${DIR}` inside the command line. For most cases you should not have to.
 +
 +Save and close, and make the `deploy` file executable:
 +
 +```
 +~/websites/topologix.fr$ chmod +x deploy
 +```
 +
 +Now you only have to enter the following command to deploy and update your website:
 +
 +```
 +~/websites/topologix.fr$ ./deploy
 +Started building sites ...
 +Built site for language en:
 +0 draft content
 +0 future content
 +0 expired content
 +5 pages created
 +0 non-page files copied
 +0 paginator pages created
 +0 tags created
 +0 categories created
 +total in 56 ms
 +sending incremental file list
 +404.html
 +index.html
 +index.xml
 +sitemap.xml
 +cours-versailles/index.html
 +exercices/index.html
 +exercices/index.xml
 +exercices/barycentre-et-carres-des-distances/index.html
 +post/
 +post/index.html
 +sujets/index.html
 +sujets/index.xml
 +sujets/2016-09_supelec-jp/index.html
 +tarifs-contact/index.html
 +
 +sent 9,550 bytes  received 1,708 bytes  7,505.33 bytes/sec
 +total size is 966,557  speedup is 85.86
 +```
diff --cc docs/content/hosting-and-deployment/hosting-on-github.md
index bd930b3f,00000000..59433a9e
mode 100644,000000..100644
--- a/docs/content/hosting-and-deployment/hosting-on-github.md
+++ b/docs/content/hosting-and-deployment/hosting-on-github.md
@@@ -1,240 -1,0 +1,239 @@@
 +---
 +title: Host on GitHub
 +linktitle: Host on GitHub
 +description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
 +date: 2014-03-21
 +publishdate: 2014-03-21
 +lastmod: 2017-03-30
 +categories: [hosting and deployment]
 +#tags: [github,git,deployment,hosting]
 +authors: [Spencer Lyon, Gunnar Morling]
 +menu:
 +  docs:
 +    parent: "hosting-and-deployment"
 +    weight: 30
 +weight: 30
 +sections_weight: 30
 +draft: false
 +toc: true
 +aliases: [/tutorials/github-pages-blog/]
 +---
 +
 +GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][].
 +
 +## Assumptions
 +
 +1. You have Git 2.5 or greater [installed on your machine][installgit].
 +2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
 +3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
 +
 +If you are working within an Organization account or want to set up a User website on GitHub and would like more information, refer to the [GitHub Pages documentation][ghorgs].
 +
 +{{% note %}}
 +Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `username.github.io/myprojectname/`) and not a custom domain.
 +{{% /note %}}
 +
 +## Deployment via `/docs` Folder on Master Branch
 +
 +[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
 +
 +```
- publishDir: docs
++publishDir = "docs"
 +```
- 
 +```
- publishDir = "docs"
++publishDir: docs
 +```
 +
 +After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
 +
 +1. Go to **Settings** &rarr; **GitHub Pages**
 +2. From **Source**,  select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
 +
 +{{% note %}}
 +The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
 +{{% /note %}}
 +
 +## Deployment From Your `gh-pages` Branch
 +
 +You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
 +
 +* It keeps your source and generated website in different branches and therefore maintains version control history for both.
 +* Unlike the preceding `docs/` option, it uses the default `public` folder.
 +
 +### Preparations for `gh-pages` Branch
 +
 +These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`:
 +
 +#### Add the Public Folder
 +
 +First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
 +
 +```
 +echo "public" >> .gitignore
 +```
 +
 +#### Initialize Your `gh-pages` Branch
 +
 +You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
 +
 +```
 +git checkout --orphan gh-pages
 +git reset --hard
 +git commit --allow-empty -m "Initializing gh-pages branch"
 +git push upstream gh-pages
 +git checkout master
 +```
 +
 +### Build and Deployment
 +
 +Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
 +
 +```
 +rm -rf public
 +git worktree add -B gh-pages public upstream/gh-pages
 +```
 +
 +Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
 +
 +{{< code file="commit-gh-pages-files.sh">}}
 +hugo
 +cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
 +{{< /code >}}
 +
 +If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
 +
 +```
 +git push upstream gh-pages
 +```
 +
 +#### Set `gh-pages` as Your Publish Branch
 +
 +In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project:
 +
 +1. Go to **Settings** &rarr; **GitHub Pages**
 +2. From **Source**,  select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub.
 +
 +After a short while, you'll see the updated contents on your GitHub Pages site.
 +
 +### Put it Into a Script
 +
 +To automate these steps, you can create a script with the following contents:
 +
 +{{< code file="publish_to_ghpages.sh" >}}
 +#!/bin/sh
 +
 +DIR=$(dirname "$0")
 +
 +cd $DIR/..
 +
 +if [[ $(git status -s) ]]
 +then
 +    echo "The working directory is dirty. Please commit any pending changes."
 +    exit 1;
 +fi
 +
 +echo "Deleting old publication"
 +rm -rf public
 +mkdir public
 +git worktree prune
 +rm -rf .git/worktrees/public/
 +
 +echo "Checking out gh-pages branch into public"
 +git worktree add -B gh-pages public upstream/gh-pages
 +
 +echo "Removing existing files"
 +rm -rf public/*
 +
 +echo "Generating site"
 +hugo
 +
 +echo "Updating gh-pages branch"
 +cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
 +{{< /code >}}
 +
 +This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
 +
 +## Deployment From Your `master` Branch
 +
 +To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
 +
 +You will also need to set `master` as your publishable branch from within the GitHub UI:
 +
 +1. Go to **Settings** &rarr; **GitHub Pages**
 +2. From **Source**,  select "master branch" and then **Save**.
 +
 +## Host GitHub User or Organization Pages
 +
 +As mentioned [in this GitHub Help article](https://help.github.com/articles/user-organization-and-project-pages/), you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
 +
 +1. You must use the `<USERNAME>.github.io` naming scheme for your GitHub repo.
 +2. Content from the `master` branch will be used to publish your GitHub Pages site.
 +
 +It becomes much simpler in this case: we'll create two separate repos, one for Hugo's content, and a git submodule with the `public` folder's content in it.
 +
 +### Step-by-step Instructions
 +
 +1. Create a `<YOUR-PROJECT>` git repository on GitHub. This repository will contain Hugo's content and other source files.
 +2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
 +3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
 +4. Make your website work locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
 +5. Once you are happy with the results:
 +    * Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
 +    * `rm -rf public` to completely remove the `public` directory if there
 +6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script.
 +
 +#### Put it Into a Script
 +
 +You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`.
 +
 +The following are the contents of the `deploy.sh` script:
 +
 +```
 +#!/bin/bash
 +
 +echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
 +
 +# Build the project.
 +hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
 +
 +# Go To Public folder
 +cd public
 +# Add changes to git.
 +git add .
 +
 +# Commit changes.
 +msg="rebuilding site `date`"
 +if [ $# -eq 1 ]
 +  then msg="$1"
 +fi
 +git commit -m "$msg"
 +
 +# Push source and build repos.
 +git push origin master
 +
 +# Come Back up to the Project Root
 +cd ..
 +```
 +
 +
- You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECDT>` repository as well.
++You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
 +
 +That's it! Your personal page should be up and running at `https://yourusername.github.io` within a couple minutes.
 +
 +## Use a Custom Domain
 +
 +If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages.
 +
 +Refer to the [official documentation for custom domains][domains] for further information.
 +
 +[config]: /getting-started/configuration/
 +[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
 +[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
 +[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
 +[ghsignup]: https://github.com/join
 +[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
 +[installgit]: https://git-scm.com/downloads
 +[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt
 +[Quick Start]: /getting-started/quick-start/
 +[submodule]: https://github.com/blog/2104-working-with-submodules
 +[worktree feature]: https://git-scm.com/docs/git-worktree
diff --cc docs/content/hosting-and-deployment/hosting-on-gitlab.md
index 0b852dde,00000000..00f2cd18
mode 100644,000000..100644
--- a/docs/content/hosting-and-deployment/hosting-on-gitlab.md
+++ b/docs/content/hosting-and-deployment/hosting-on-gitlab.md
@@@ -1,81 -1,0 +1,85 @@@
 +---
 +title: Host on GitLab
 +linktitle: Host on GitLab
 +description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
 +date: 2016-06-23
 +publishdate: 2016-06-23
 +lastmod: 2016-06-23
 +categories: [hosting and deployment]
 +#tags: [hosting,deployment,git,gitlab]
 +authors: [Riku-Pekka Silvola]
 +menu:
 +  docs:
 +    parent: "hosting-and-deployment"
 +    weight: 40
 +weight: 40
 +sections_weight: 40
 +draft: false
 +toc: true
 +wip: false
 +aliases: [/tutorials/hosting-on-gitlab/]
 +---
 +
 +[GitLab](https://gitlab.com/) makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides [native support for Hugo, as well as numerous other static site generators](https://gitlab.com/pages/hugo).
 +
 +## Assumptions
 +
 +* Working familiarity with Git for version control
 +* Completion of the Hugo [Quick Start][]
 +* A [GitLab account](https://gitlab.com/users/sign_in)
 +* A Hugo website on your local machine that you are ready to publish
 +
 +## Create .gitlab-ci.yml
 +
 +```
 +cd your-hugo-site
 +```
 +
 +In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
 +
 +{{< code file="gitlab-ci.yml" >}}
- image: publysher/hugo
++image: monachus/hugo
++
++before_script:
++  - git submodule init
++  - git submodule update --force
 +
 +pages:
 +  script:
 +  - hugo
 +  artifacts:
 +    paths:
 +    - public
 +  only:
 +  - master
 +{{< /code >}}
 +
 +## Push Your Hugo Website to GitLab
 +
 +Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
 +
 +```
 +# initialize new git repository
 +git init
 +
 +# add /public directory to our .gitignore file
 +echo "/public" >> .gitignore
 +
 +# commit and push code to master branch
 +git add .
 +git commit -m "Initial commit"
 +git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
 +git push -u origin master
 +```
 +
 +## Wait for Your Page to Build
 +
- That's it! You can now follow the CI agent building your page at https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines.
++That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
 +
 +After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
 +
 +## Next Steps
 +
 +GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
 +
 +[Quick Start]: /getting-started/quick-start/
diff --cc docs/content/hosting-and-deployment/hosting-on-netlify.md
index 012c45d2,00000000..ce10c4a5
mode 100644,000000..100644
--- a/docs/content/hosting-and-deployment/hosting-on-netlify.md
+++ b/docs/content/hosting-and-deployment/hosting-on-netlify.md
@@@ -1,123 -1,0 +1,139 @@@
 +---
 +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]
 +#tags: [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.
 +
 +![Screenshot of the homepage for app.netlify.com, containing links to the most popular hosted git solutions.](/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg)
 +
 +Selecting GitHub will bring up a typical modal you've seen through other application that use GitHub for authentication. Select "Authorize application."
 +
 +![Screenshot of the authorization popup for Netlify and GitHub.](/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg)
 +
 +## 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."
 +
 +![Screenshot of the blank Netlify admin panel with no sites and highlighted 'add new site' button'](/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg)
 +
 +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.
 +
 +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg)
 +
 +And then again with the GitHub authorization modal:
 +
 +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg)
 +
 +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:
 +
 +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg)
 +
 +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, you can append an underscore followed by the version number to the build command:
++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:
 +
 +![Screenshot of 3-step, basic continuous deployment setup with a new Hugo site on Netlify](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg)
 +
++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:.
 +
 +![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif)
 +
 +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."
 +
 +![Screenshot of successful deploy badge at the top of a deployments screen from within the Netlify admin.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg)
 +
 +![Screenshot of homepage to https://hugo-netlify-example.netlify.com, which is mostly dummy text](/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg)
 +
 +[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>
 +```
 +
 +## 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
diff --cc docs/content/news/http2-server-push-in-hugo.md
index 76c39094,00000000..369d0b22
mode 100644,000000..100644
--- a/docs/content/news/http2-server-push-in-hugo.md
+++ b/docs/content/news/http2-server-push-in-hugo.md
@@@ -1,79 -1,0 +1,79 @@@
 +---
 +title: "HTTP/2 Server Push in Hugo"
 +date: 2017-07-24T18:36:00+02:00
 +description: >
 +    As every page in Hugo can be output to multiple formats, it is easy to create Netlify's _redirects and _headers files on the fly.
 +categories: [blog]
 +#tags: []
 +slug: "http2-server-push-in-hugo"
 +aliases: []
 +author: bep
 +images:
 +- images/gohugoio-card-1.png
 +---
 +
 +**Netlify** recently announced support for [HTTP/2 server push](https://www.netlify.com/blog/2017/07/18/http/2-server-push-on-netlify/), and we have now added it to the **gohugo.io** sites for the main `CSS` and `JS` bundles, along with server-side 301 redirect support. 
 +
 +If you navigate to https://gohugo.io and look in the Chrome developer network console, you should now see `Push` as the new source ("Initiator") for the `CSS` and `JSS`:
 +
 +{{< figure src="/images/blog/hugo-http2-push.png" caption="Network log for https://gohugo.io" >}}
 +
 +**Setting up this in Hugo was easy:**
 +
 +## 1. Configure Netlify Output Formats
 +
 +Add a new custom media type and two new output formats to `config.toml`. For more on output formats in Hugo, see [Custom Output Formats](/templates/output-formats/).
 +```bash
 +[outputs]
 +home = [ "HTML", "RSS", "REDIR", "HEADERS" ]
 +
 +[mediaTypes]
 +[mediaTypes."text/netlify"]
 +suffix = ""
 +delimiter = ""
 +
 +[outputFormats]
 +[outputFormats.REDIR]
 +mediatype = "text/netlify"
 +baseName = "_redirects"
 +isPlainText = true
 +notAlternative = true
 +[outputFormats.HEADERS]
 +mediatype = "text/netlify"
 +baseName = "_headers"
 +isPlainText = true
 +notAlternative = true
 +```
 +## 2. Add Template For the _headers File 
 +
 +Add `layouts/index.headers`:
 +
 +```bash
 +/*
 +  X-Frame-Options: DENY
 +  X-XSS-Protection: 1; mode=block
 +  X-Content-Type-Options: nosniff
 +  Referrer-Policy: origin-when-cross-origin
 +*/
 +  Link: <{{ "dist/app.bundle.js" | relURL }}>; rel=preload; as=script
 +  Link: <{{ "dist/main.css" | relURL }}>; rel=preload; as=style
 +```
 +The template above creates both a security header definition and a HTTP/2 server push configuration.
 +
 +Also note that this is a template for the home page, so the full `Page` with its `Site` and many variables are available. You can also use `partial` to include other templates.
 +
 +
 +
 +
 +## 3. Add Template For the _redirects File 
- Add `layouts/index.redirects`:
++Add `layouts/index.redir`:
 +```bash
 +# Netlify redirects. See https://www.netlify.com/docs/redirects/
 +{{  range $p := .Site.Pages -}}
 +{{ range .Aliases }}
 +{{  . | printf "%-35s" }}	{{ $p.RelPermalink -}}
 +{{ end -}}
 +{{- end -}}
 +```
 +The template above creates 301 redirects for your [aliases](/content-management/urls/#aliases), so you will probably want to turn off aliases in your `config.toml`: `disableAliases = true`.
 +
diff --cc docs/content/templates/base.md
index b27b1a33,00000000..9433dc9f
mode 100644,000000..100644
--- a/docs/content/templates/base.md
+++ b/docs/content/templates/base.md
@@@ -1,130 -1,0 +1,130 @@@
 +---
 +title: Base Templates and Blocks
 +linktitle:
 +description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).
 +godocref: https://golang.org/pkg/text/template/#example_Template_block
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [templates,fundamentals]
 +#tags: [blocks,base]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 20
 +weight: 20
 +sections_weight: 20
 +draft: false
 +aliases: [/templates/blocks/,/templates/base-templates-and-blocks/]
 +toc: true
 +---
 +
 +The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary.
 +
 +## Base Template Lookup Order
 +
 +The [lookup order][lookup] for base templates is as follows:
 +
 +1. `/layouts/section/<TYPE>-baseof.html`
 +2. `/themes/<THEME>/layouts/section/<TYPE>-baseof.html`
 +3. `/layouts/<TYPE>/baseof.html`
 +4. `/themes/<THEME>/layouts/<TYPE>/baseof.html`
 +5. `/layouts/section/baseof.html`
 +6. `/themes/<THEME>/layouts/section/baseof.html`
- 7. `/layouts/_default/post-baseof.html`
- 8. `/themes/<THEME>/layouts/_default/post-baseof.html`
++7. `/layouts/_default/<TYPE>-baseof.html`
++8. `/themes/<THEME>/layouts/_default/<TYPE>-baseof.html`
 +9. `/layouts/_default/baseof.html`
 +10. `/themes/<THEME>/layouts/_default/baseof.html`
 +
 +Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified.
 +
 +### Example Base Template Lookup Order
 +
 +As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template.
 +
 +Here is the lookup order for the `post` base template:
 +
 +1. `/layouts/section/post-baseof.html`
 +2. `/themes/mytheme/layouts/section/post-baseof.html`
 +3. `/layouts/post/baseof.html`
 +4. `/themes/mytheme/layouts/post/baseof.html`
 +5. `/layouts/section/baseof.html`
 +6. `/themes/mytheme/layouts/section/baseof.html`
 +7. `/layouts/_default/post-baseof.html`
 +8. `/themes/mytheme/layouts/_default/post-baseof.html`
 +9. `/layouts/_default/baseof.html`
 +10. `/themes/mytheme/layouts/_default/baseof.html`
 +
 +## Define the Base Template
 +
 +The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
 +
 +{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
 +<!DOCTYPE html>
 +<html>
 +  <head>
 +    <meta charset="utf-8">
 +    <title>{{ block "title" . }}
 +      <!-- Blocks may include default content. -->
 +      {{ .Site.Title }}
 +    {{ end }}</title>
 +  </head>
 +  <body>
 +    <!-- Code that all your templates share, like a header -->
 +    {{ block "main" . }}
 +      <!-- The part of the page that begins to differ between templates -->
 +    {{ end }}
 +    {{ block "footer" . }}
 +    <!-- More shared code, perhaps a footer but that can be overridden if need be in  -->
 +    {{ end }}
 +  </body>
 +</html>
 +{{< /code >}}
 +
 +## Override the Base Template
 +
 +From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
 +
 +{{< code file="layouts/_default/list.html" download="list.html" >}}
 +{{ define "main" }}
 +  <h1>Posts</h1>
 +  {{ range .Data.Pages }}
 +    <article>
 +      <h2>{{ .Title }}</h2>
 +      {{ .Content }}
 +    </article>
 +  {{ end }}
 +{{ end }}
 +{{< /code >}}
 +
 +This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
 +
 +{{% warning %}}
 +Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
 +
 +```
 +<!-- Seemingly harmless HTML comment..that will break your layout at build -->
 +{{ define "main" }}
 +...your code here
 +{{ end }}
 +```
 +[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
 +{{% /warning %}}
 +
 +The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
 +
 +{{< code file="layouts/_default/single.html" download="single.html" >}}
 +{{ define "title" }}
 +  <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
 +  {{ .Title }} &ndash; {{ .Site.Title }}
 +{{ end }}
 +{{ define "main" }}
 +  <h1>{{ .Title }}</h1>
 +  {{ .Content }}
 +{{ end }}
 +{{< /code >}}
 +
 +[hugolists]: /templates/lists
 +[lookup]: /templates/lookup-order/
 +[rendering the section]: /templates/section-templates/
 +[singletemplate]: /templates/single-page-templates/
diff --cc docs/content/templates/internal.md
index 022e95c3,00000000..3d43913d
mode 100644,000000..100644
--- a/docs/content/templates/internal.md
+++ b/docs/content/templates/internal.md
@@@ -1,135 -1,0 +1,131 @@@
 +---
 +title: Internal Templates
 +linktitle: Internal Templates
 +description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites.
 +date: 2017-03-06
 +publishdate: 2017-03-06
 +lastmod: 2017-03-06
 +categories: [templates]
 +#tags: [internal, analytics,]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 168
 +weight: 168
 +sections_weight: 168
 +draft: false
 +aliases: []
 +toc: true
 +wip: true
 +---
 +<!-- reference: https://discourse.gohugo.io/t/lookup-order-for-partials/5705/6
 +code: https://github.com/gohugoio/hugo/blob/e445c35d6a0c7f5fc2f90f31226cd1d46e048bbc/tpl/template_embedded.go#L147 -->
 +
 +{{% warning %}}
 +While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order.
 +{{% /warning %}}
 +
 +## Google Analytics
 +
 +Hugo ships with internal templates for Google Analytics tracking, including both synchronous and asynchronous tracking codes.
 +
 +### Configure Google Analytics
 +
 +Provide your tracking id in your configuration file:
 +
 +```
 +googleAnalytics = "UA-123-45"
 +```
 +
 +```
 +googleAnalytics: "UA-123-45"
 +```
 +
 +### Use the Google Analytics Template
 +
 +You can then include the Google Analytics internal template:
 +
 +```
 +{{ template "_internal/google_analytics.html" . }}
 +```
 +
 +
 +```
 +{{ template "_internal/google_analytics_async.html" . }}
 +```
 +
 +## Disqus
 +
 +Hugo also ships with an internal template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. In order to effectively use Disqus, you will need to secure a Disqus "shortname" by [signing up for the free service][disqussignup].
 +
 +### Configure Disqus
 +
 +To use Hugo's Disqus template, you first need to set a single value in your site's `config.toml` or `config.yml`:
 +
 +```
 +disqusShortname = "yourdiscussshortname"
 +```
 +
 +```
 +disqusShortname: "yourdiscussshortname"
 +```
 +
 +You also have the option to set the following in the front matter for a given piece of content:
 +
 +* `disqus_identifier`
 +* `disqus_title`
 +* `disqus_url`
 +
 +### Use the Disqus Template
 +
 +To add Disqus, include the following line in templates where you want your comments to appear:
 +
 +```
 +{{ template "_internal/disqus.html" . }}
 +```
 +
 +### Conditional Loading of Disqus Comments
 +
 +Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account.
 +
 +You can create the following `layouts/partials/disqus.html`:
 +
 +{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
 +<div id="disqus_thread"></div>
 +<script type="text/javascript">
 +
 +(function() {
 +    // Don't ever inject Disqus on localhost--it creates unwanted
 +    // discussions from 'localhost:1313' on your Disqus account...
 +    if (window.location.hostname == "localhost")
 +        return;
 +
 +    var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
 +    var disqus_shortname = '{{ .Site.DisqusShortname }}';
 +    dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
 +    (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
 +})();
 +</script>
 +<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
 +<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
 +{{< /code >}}
 +
 +The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
 +
 +You can then render your custom Disqus partial template as follows:
 +
 +```
 +{{ partial "disqus.html" . }}
 +```
 +
- ```
- _internal/_default/robots.txt
- _internal/_default/rss.xml
- _internal/_default/sitemap.xml
- _internal/_default/sitemapindex.xml
++## The Internal Templates
++
++* `_internal/disqus.html`
++* `_internal/google_news.html`
++* `_internal/google_analytics.html`
++* `_internal/google_analytics_async.html`
++* `_internal/opengraph.html`
++* `_internal/pagination.html`
++* `_internal/schema.html`
++* `_internal/twitter_cards.html`
 +
- _internal/disqus.html
- _internal/google_news.html
- _internal/google_analytics.html
- _internal/google_analytics_async.html
- _internal/opengraph.html
- _internal/pagination.html
- _internal/schema.html
- _internal/twitter_cards.html
- ```
diff --cc docs/content/templates/introduction.md
index 647d580c,00000000..08ef0272
mode 100644,000000..100644
--- a/docs/content/templates/introduction.md
+++ b/docs/content/templates/introduction.md
@@@ -1,486 -1,0 +1,486 @@@
 +---
 +title: Introduction to Hugo Templating
 +linktitle: Introduction
 +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating.
 +godocref: https://golang.org/pkg/html/template/
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-25
 +categories: [templates,fundamentals]
 +#tags: [go]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 10
 +weight: 10
 +sections_weight: 10
 +draft: false
 +aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, /templates/go-templates/]
 +toc: true
 +---
 +
 +{{% note %}}
 +The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/).
 +{{% /note %}}
 +
 +Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer.
 +
 +## Basic Syntax
 +
 +Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`.
 +
 +### Access a Predefined Variable
 +
 +```
 +{{ foo }}
 +```
 +
 +Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`:
 +
 +```
 +{{ add 1 2 }}
 +```
 +
 +#### Methods and Fields are Accessed via dot Notation
 +
 +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
 +
 +```
 +{{ .Params.bar }}
 +```
 +
 +#### Parentheses Can be Used to Group Items Together
 +
 +```
 +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
 +```
 +
 +## Variables
 +
 +Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information.
 +
 +This is how you access a `Page` variable from a template:
 +
 +```
 +<title>{{ .Title }}</title>
 +```
 +
 +Values can also be stored in custom variables and referenced later:
 +
 +```
 +{{ $address := "123 Main St."}}
 +{{ $address }}
 +```
 +
 +{{% warning %}}
 +Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608).
 +
 +Hugo has created a workaround for this issue in [Scratch](/functions/scratch).
 +
 +{{% /warning %}}
 +
 +## Functions
 +
 +Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set.
 +
 +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo.
 +
 +### Example 1: Adding Numbers
 +
 +```
 +{{ add 1 2 }}
 +=> 3
 +```
 +
 +### Example 2: Comparing Numbers
 +
 +```
 +{{ lt 1 2 }}
 +=> true (i.e., since 1 is less than 2)
 +```
 +
 +Note that both examples make us of Go template's [math functions][].
 +
 +{{% note "Additional Boolean Operators" %}}
 +There are more boolean operators than those listed in the Hugo docs in the [Golang template documentation](http://golang.org/pkg/text/template/#hdr-Functions).
 +{{% /note %}}
 +
 +## Includes
 +
 +When including another template, you will pass to it the data it will be
 +able to access. To pass along the current context, please remember to
 +include a trailing dot. The templates location will always be starting at
- the `/layout/` directory within Hugo.
++the `/layouts/` directory within Hugo.
 +
 +### Template and Partial Examples
 +
 +```
 +{{ template "partials/header.html" . }}
 +```
 +
 +Starting with Hugo v0.12, you may also use the `partial` call
 +for [partial templates][partials]:
 +
 +```
 +{{ partial "header.html" . }}
 +```
 +
 +## Logic
 +
 +Go templates provide the most basic iteration and conditional logic.
 +
 +### Iteration
 +
 +Just like in Go, the Go templates make heavy use of `range` to iterate over
 +a map, array, or slice. The following are different examples of how to use
 +range.
 +
 +#### Example 1: Using Context
 +
 +```
 +{{ range array }}
 +    {{ . }}
 +{{ end }}
 +```
 +
 +#### Example 2: Declaring Value => Variable name
 +
 +```
 +{{range $element := array}}
 +    {{ $element }}
 +{{ end }}
 +```
 +
 +#### Example 3: Declaring Key-Value Variable Name
 +
 +```
 +{{range $index, $element := array}}
 +   {{ $index }}
 +   {{ $element }}
 +{{ end }}
 +```
 +
 +### Conditionals
 +
 +`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`.
 +
 +Go Templates treat the following values as false:
 +
 +* false
 +* 0
 +* any zero-length array, slice, map, or string
 +
 +#### Example 1: `if`
 +
 +```
 +{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
 +```
 +
 +#### Example 2: `if` … `else`
 +
 +```
 +{{ if isset .Params "alt" }}
 +    {{ index .Params "alt" }}
 +{{else}}
 +    {{ index .Params "caption" }}
 +{{ end }}
 +```
 +
 +#### Example 3: `and` & `or`
 +
 +```
 +{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
 +```
 +
 +#### Example 4: `with`
 +
 +An alternative way of writing "`if`" and then referencing the same value
 +is to use "`with`" instead. `with` rebinds the context `.` within its scope
 +and skips the block if the variable is absent.
 +
 +The first example above could be simplified as:
 +
 +```
 +{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
 +```
 +
 +#### Example 5: `if` … `else if`
 +
 +```
 +{{ if isset .Params "alt" }}
 +    {{ index .Params "alt" }}
 +{{ else if isset .Params "caption" }}
 +    {{ index .Params "caption" }}
 +{{ end }}
 +```
 +
 +## Pipes
 +
 +One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe.
 +
 +Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline.
 +
 +A few simple examples should help convey how to use the pipe.
 +
 +### Example 1: `shuffle`
 +
 +The following two examples are functionally the same:
 +
 +```
 +{{ shuffle (seq 1 5) }}
 +```
 +
 +
 +```
 +{{ (seq 1 5) | shuffle }}
 +```
 +
 +### Example 2: `index`
 +
 +The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates:
 +
 +```
 +{{ index .Params "disqus_url" | html }}
 +```
 +
 +### Example 3: `or` with `isset`
 +
 +```
 +{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
 +Stuff Here
 +{{ end }}
 +```
 +
 +Could be rewritten as
 +
 +```
 +{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
 +Stuff Here
 +{{ end }}
 +```
 +
 +### Example 4: Internet Explorer Conditional Comments
 +
 +By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
 +
 +```
 +{{ "<!--[if lt IE 9]>" | safeHTML }}
 +  <script src="html5shiv.js"></script>
 +{{ "<![endif]-->" | safeHTML }}
 +```
 +
 +Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation:
 +
 +```
 +{{ `<!--[if lt IE 7]><html class="no-js lt-ie9 lt-ie8 lt-ie7"><![endif]-->` | safeHTML }}
 +```
 +
 +## Context (aka "the dot")
 +
 +The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following:
 +
 +### 1. Define a Variable Independent of Context
 +
 +The following shows how to define a variable independent of the context.
 +
 +{{< code file="tags-range-with-page-variable.html" >}}
 +{{ $title := .Site.Title }}
 +<ul>
 +{{ range .Params.tags }}
 +    <li>
 +        <a href="/tags/{{ . | urlize }}">{{ . }}</a>
 +        - {{ $title }}
 +    </li>
 +{{ end }}
 +</ul>
 +{{< /code >}}
 +
 +{{% note %}}
 +Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
 +{{% /note %}}
 +
 +### 2. Use `$.` to Access the Global Context
 +
 +`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
 +
 +{{< code file="range-through-tags-w-global.html" >}}
 +<ul>
 +{{ range .Params.tags }}
 +  <li>
 +    <a href="/tags/{{ . | urlize }}">{{ . }}</a>
 +            - {{ $.Site.Title }}
 +  </li>
 +{{ end }}
 +</ul>
 +{{< /code >}}
 +
 +{{% warning "Don't Redefine the Dot" %}}
 +The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
 +{{% /warning %}}
 +
 +## Whitespace
 +
 +Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter.
 +
 +For instance, the following Go template will include the newlines and horizontal tab in its HTML output:
 +
 +```
 +<div>
 +  {{ .Title }}
 +</div>
 +```
 +
 +Which will output:
 +
 +```
 +<div>
 +  Hello, World!
 +</div>
 +```
 +
 +Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
 +
 +```
 +<div>
 +  {{- .Title -}}
 +</div>
 +```
 +
 +Which then outputs:
 +
 +```
 +<div>Hello, World!</div>
 +```
 +
 +Go considers the following characters whitespace:
 +
 +* <kbd>space</kbd>
 +* horizontal <kbd>tab</kbd>
 +* carriage <kbd>return</kbd>
 +* newline
 +
 +## Hugo Parameters
 +
 +Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file.
 +
 +## Use Content (`Page`) Parameters
 +
 +You can provide variables to be used by templates in individual content's [front matter][].
 +
 +An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`.
 +
 +Here is the example front matter:
 +
 +```
 +---
 +title: Roadmap
 +lastmod: 2017-03-05
 +date: 2013-11-18
 +notoc: true
 +---
 +```
 +
 +Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
 +
 +{{< code file="layouts/partials/toc.html" download="toc.html" >}}
 +{{ if not .Params.notoc }}
 +<aside>
 +  <header>
 +    <a href="#{{.Title | urlize}}">
 +    <h3>{{.Title}}</h3>
 +    </a>
 +  </header>
 +  {{.TableOfContents}}
 +</aside>
 +<a href="#" id="toc-toggle"></a>
 +{{end}}
 +{{< /code >}}
 +
 +We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
 +
 +## Use Site Configuration Parameters
 +
 +You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates.
 +
 +For instance, you might declare the following:
 +
 +{{< code file="config.yaml" >}}
 +params:
 +  copyrighthtml: "Copyright &#xA9; 2017 John Doe. All Rights Reserved."
 +  twitteruser: "spf13"
 +  sidebarrecentlimit: 5
 +{{< /code >}}
 +
 +Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
 +
 +```
 +{{if .Site.Params.copyrighthtml}}<footer>
 +<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
 +</footer>{{end}}
 +```
 +
 +An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
 +
 +{{< code file="layouts/partials/twitter.html" >}}
 +{{with .Site.Params.twitteruser}}
 +<div>
 +  <a href="https://twitter.com/{{.}}" rel="author">
 +  <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
 +</div>
 +{{end}}
 +{{< /code >}}
 +
 +Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
 +
 +```
 +<nav>
 +  <h1>Recent Posts</h1>
 +  <ul>
 +  {{- range first .Site.Params.SidebarRecentLimit .Site.Pages -}}
 +    <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
 +  {{- end -}}
 +  </ul>
 +</nav>
 +```
 +
 +## Example: Show Only Upcoming Events
 +
 +Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
 +
 +{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
 +<h4>Upcoming Events</h4>
 +<ul class="upcoming-events">
 +{{ range where .Data.Pages.ByDate "Section" "events" }}
 +  {{ if ge .Date.Unix .Now.Unix }}
 +    <li>
 +    <!-- add span for event type -->
 +      <span>{{ .Type | title }} —</span>
 +      {{ .Title }} on
 +    <!-- add span for event date -->
 +      <span>{{ .Date.Format "2 January at 3:04pm" }}</span>
 +      at {{ .Params.place }}
 +    </li>
 +  {{ end }}
 +{{ end }}
 +</ul>
 +{{< /code >}}
 +
 +
 +[`where` function]: /functions/where/
 +[config]: /getting-started/configuration/
 +[dotdoc]: http://golang.org/pkg/text/template/#hdr-Variables
 +[first]: /functions/first/
 +[front matter]: /content-management/front-matter/
 +[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples."
 +[Go html/template]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
 +[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
 +[index]: /functions/index/
 +[math functions]: /functions/math/
 +[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs"
 +[relpermalink]: /variables/page/
 +[safehtml]: /functions/safehtml/
 +[sitevars]: /variables/site/
 +[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
 +[where]: /functions/where/
 +[with]: /functions/with/
 +[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function"
diff --cc docs/content/templates/shortcode-templates.md
index 585d538d,00000000..65642ae6
mode 100644,000000..100644
--- a/docs/content/templates/shortcode-templates.md
+++ b/docs/content/templates/shortcode-templates.md
@@@ -1,348 -1,0 +1,348 @@@
 +---
 +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]
 +#tags: [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.
 +
 +### 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].
 +
 +#### `.IsNameParams`
 +
 +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="">
++<img src="{{.Get "src" }}" alt="">
 +{{ else }}
 +<img src="{{.Get 0}}" alt="">
 +{{ end }}.
 +```
 +
 +See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
 +
 +{{% warning %}}
 +While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
 +{{% /warning %}}
 +
 +You can also use the variable `.Page` to access all the normal [page variables][pagevars].
 +
 +A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
 +
 +## 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" >}}
 +{{ .Page.Now.Year }}
 +{{< /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">&lt;html&gt;</span>
 +    <span style="color: #f92672">&lt;body&gt;</span> This HTML <span style="color: #f92672">&lt;/body&gt;</span>
 +<span style="color: #f92672">&lt;/html&gt;</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."
++[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
diff --cc docs/content/templates/single-page-templates.md
index 20942e5d,00000000..cb86b36a
mode 100644,000000..100644
--- a/docs/content/templates/single-page-templates.md
+++ b/docs/content/templates/single-page-templates.md
@@@ -1,105 -1,0 +1,105 @@@
 +---
 +title: Single Page Templates
 +linktitle:
 +description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-04-06
 +categories: [templates]
 +#tags: [page]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 60
 +weight: 60
 +sections_weight: 60
 +draft: false
 +aliases: [/layout/content/]
 +toc: true
 +---
 +
 +## Single Page Template Lookup Order
 +
 +You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]).
 +
 +Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable.
 +
 +1. `/layouts/<TYPE>/<LAYOUT>.html`
- 2. `/layouts/<SECTION>>/<LAYOUT>.html`
++2. `/layouts/<SECTION>/<LAYOUT>.html`
 +3. `/layouts/<TYPE>/single.html`
 +4. `/layouts/<SECTION>/single.html`
 +5. `/layouts/_default/single.html`
 +6. `/themes/<THEME>/layouts/<TYPE>/<LAYOUT>.html`
 +7. `/themes/<THEME>/layouts/<SECTION>/<LAYOUT>.html`
 +8. `/themes/<THEME>/layouts/<TYPE>/single.html`
 +9. `/themes/<THEME>/layouts/<SECTION>/single.html`
 +10. `/themes/<THEME>/layouts/_default/single.html`
 +
 +## Example Single Page Templates
 +
 +Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates.
 +
 +### `post/single.html`
 +
 +This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
 +
 +{{< code file="layouts/post/single.html" download="single.html" >}}
 +{{ define "main" }}
 +<section id="main">
 +  <h1 id="title">{{ .Title }}</h1>
 +  <div>
 +        <article id="content">
 +           {{ .Content }}
 +        </article>
 +  </div>
 +</section>
 +<aside id="meta">
 +    <div>
 +    <section>
 +      <h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
 +      <h5 id="wordcount"> {{ .WordCount }} Words </h5>
 +    </section>
 +    {{ with .Params.topics }}
 +    <ul id="topics">
 +      {{ range . }}
 +        <li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
 +      {{ end }}
 +    </ul>
 +    {{ end }}
 +    {{ with .Params.tags }}
 +    <ul id="tags">
 +      {{ range . }}
 +        <li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
 +      {{ end }}
 +    </ul>
 +    {{ end }}
 +    </div>
 +    <div>
 +        {{ with .PrevInSection }}
 +          <a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
 +        {{ end }}
 +        {{ with .NextInSection }}
 +          <a class="next" href="{{.Permalink}}"> {{.Title}}</a>
 +        {{ end }}
 +    </div>
 +</aside>
 +{{ end }}
 +{{< /code >}}
 +
 +To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
 +
 +[archetypes]: /content-management/archetypes/
 +[base templates]: /templates/base/
 +[config]: /getting-started/configuration/
 +[content type]: /content-management/types/
 +[directory structure]: /getting-started/directory-structure/
 +[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
 +[`.Format` function]: /functions/format/
 +[front matter]: /content-management/front-matter/
 +[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies
 +[pagevars]: /variables/page/
 +[partials]: /templates/partials/
 +[section]: /content-management/sections/
 +[site variables]: /variables/site/
 +[spf13]: http://spf13.com/
- [`with`]: /functions/with/
++[`with`]: /functions/with/
diff --cc docs/content/templates/taxonomy-templates.md
index 6e5b6c40,00000000..5cb0f334
mode 100644,000000..100644
--- a/docs/content/templates/taxonomy-templates.md
+++ b/docs/content/templates/taxonomy-templates.md
@@@ -1,352 -1,0 +1,352 @@@
 +---
 +title: Taxonomy Templates
 +# linktitle:
 +description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [templates]
 +#tags: [taxonomies,metadata,front matter,terms]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 50
 +weight: 50
 +sections_weight: 50
 +draft: false
 +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
 +toc: true
 +---
 +
 +<!-- NOTE! Check on https://github.com/gohugoio/hugo/issues/2826 for shifting of terms' pages to .Data.Pages AND
 +https://discourse.gohugo.io/t/how-to-specify-category-slug/4856/15 for original discussion.-->
 +
 +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature.
 +
 +Hugo provides multiple ways to use taxonomies throughout your project templates:
 +
 +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template)
 +* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template)
 +* List a single content's taxonomy terms within a [single page template][]
 +
 +## Taxonomy List Templates
 +
 +Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
 +
 +### Taxonomy List Template Lookup Order
 +
 +A taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g., http://spf13.com/topics/golang/) according to the following lookup order:
 +
 +1. `/layouts/taxonomy/<SINGULAR>.html`
 +2. `/layouts/_default/taxonomy.html`
 +3. `/layouts/_default/list.html`
 +4. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.html`
 +5. `/themes/<THEME>/layouts/_default/taxonomy.html`
 +6. `/themes/<THEME>/layouts/_default/list.html`
 +
 +## Taxonomy Terms Template
 +
 +### Taxonomy Terms Templates Lookup Order
 +
 +A taxonomy terms page will be rendered at `example.com/<PLURALTAXONOMYNAME>`/ (e.g., http://spf13.com/topics/) according to the following lookup order:
 +
 +1. `/layouts/taxonomy/<SINGULAR>.terms.html`
 +2. `/layouts/_default/terms.html`
 +3. `/themes/<THEME>/layouts/taxonomy/<SINGULAR>.terms.html`
 +4. `/themes/<THEME>/layouts/_default/terms.html`
 +
 +{{% warning "The Taxonomy Terms Template has a Unique Lookup Order" %}}
 +If Hugo does not find a terms template in `layout/` or `/themes/<THEME>/layouts/`, Hugo will *not* render a taxonomy terms page.
 +{{% /warning %}}
 +
 +<!-- Begin /taxonomies/methods/ -->
 +Hugo makes a set of values and methods available on the various Taxonomy structures.
 +
 +### Taxonomy Methods
 +
 +A Taxonomy is a `map[string]WeightedPages`.
 +
 +.Get(term)
 +: Returns the WeightedPages for a term.
 +
 +.Count(term)
 +: The number of pieces of content assigned to this term.
 +
 +.Alphabetical
 +: Returns an OrderedTaxonomy (slice) ordered by Term.
 +
 +.ByCount
 +: Returns an OrderedTaxonomy (slice) ordered by number of entries.
 +
 +### OrderedTaxonomy
 +
 +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
 +
 +```
 +[]struct {
 +    Name          string
 +    WeightedPages WeightedPages
 +}
 +```
 +
 +Each element of the slice has:
 +
 +.Term
 +: The Term used.
 +
 +.WeightedPages
 +: A slice of Weighted Pages.
 +
 +.Count
 +: The number of pieces of content assigned to this term.
 +
 +.Pages
 +: All Pages assigned to this term. All [list methods][renderlists] are available to this.
 +
 +## WeightedPages
 +
 +WeightedPages is simply a slice of WeightedPage.
 +
 +```
 +type WeightedPages []WeightedPage
 +```
 +
 +.Count(term)
 +: The number of pieces of content assigned to this term.
 +
 +.Pages
 +: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
 +
 +## Displaying custom metadata in Taxonomy Terms Templates
 +
 +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Data.Pages` as such:
 +
 +```
 +<ul>
 +  {{ range .Data.Pages }}
 +     <li>
 +       <a href="{{ .Permalink }}">{{ .Title }}</a>
 +       {{ .Params.wikipedia }}
 +     </li>
 +  {{ end }}
 +</ul>
 +```
 +
 +<!-- Begin /taxonomies/ordering/ -->
 +
 +## Order Taxonomies
 +
 +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
 +
 +### Order Alphabetically Example
 +
 +```
 +<ul>
 +  {{ $data := .Data }}
-   {{ range $key, $value := .Data.Taxonomy.Alphabetical }}
++  {{ range $key, $value := .Data.Terms.Alphabetical }}
 +  <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
 +  {{ end }}
 +</ul>
 +```
 +
 +### Order by Popularity Example
 +
 +```
 +<ul>
 +  {{ $data := .Data }}
-   {{ range $key, $value := .Data.Taxonomy.ByCount }}
++  {{ range $key, $value := .Data.Terms.ByCount }}
 +  <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
 +  {{ end }}
 +</ul>
 +```
 +
 +<!-- [See Also Taxonomy Lists](/templates/list/) -->
 +
 +## Order Content within Taxonomies
 +
 +Hugo uses both `date` and `weight` to order content within taxonomies.
 +
 +Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.
 +
 +When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
 +
 +### Assign Weight
 +
 +Content can be assigned weight for each taxonomy that it's assigned to.
 +
 +```
 ++++
 +tags = [ "a", "b", "c" ]
 +tags_weight = 22
 +categories = ["d"]
 +title = "foo"
 +categories_weight = 44
 ++++
 +Front Matter with weighted tags and categories
 +```
 +
 +The convention is `taxonomyname_weight`.
 +
 +In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
 +
 +It has also been assigned the weight of 44 when rendering the 'd' category.
 +
 +With this the same piece of content can appear in different positions in different taxonomies.
 +
 +Currently taxonomies only support the default ordering of content which is weight -> date.
 +
 +<!-- Begin /taxonomies/templates/ -->
 +
 +There are two different templates that the use of taxonomies will require you to provide.
 +
 +Both templates are covered in detail in the templates section.
 +
 +A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.
 +
 +A [taxonomy terms template](/templates/terms/) is a template used to
 +generate the list of terms for a given template.
 +
 +<!-- Begin /taxonomies/displaying/ -->
 +
 +There are four common ways you can display the data in your
 +taxonomies in addition to the automatic taxonomy pages created by hugo
 +using the [list templates](/templates/list/):
 +
 +1. For a given piece of content, you can list the terms attached
 +2. For a given piece of content, you can list other content with the same
 +   term
 +3. You can list all terms for a taxonomy
 +4. You can list all taxonomies (with their terms)
 +
 +## Display a Single Piece of Content's Taxonomies
 +
 +Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.
 +
 +Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`).
 +
 +### Example: List Tags in a Single Page Template
 +
 +```
 +<ul id="tags">
 +  {{ range .Params.tags }}
 +    <li><a href="{{ "/tags/" | relLangURL }}{{ . | urlize }}">{{ . }}</a> </li>
 +  {{ end }}
 +</ul>
 +```
 +
 +If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
 +
 +To list such taxonomies, use the following:
 +
 +### Example: Comma-delimit Tags in a Single Page Template
 +
 +```
 +{{ if .Params.directors }}
 +  <strong>Director{{ if gt (len .Params.directors) 1 }}s{{ end }}:</strong>
 +  {{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}<a href="{{ "directors/" | relURL }}{{ . | urlize }}">{{ . }}</a>{{ end }}
 +{{ end }}
 +```
 +
 +Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
 +
 +## List Content with the Same Taxonomy Term
 +
 +If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
 +
 +### Example: Showing Content in Same Series
 +
 +```
 +<ul>
 +  {{ range .Site.Taxonomies.series.golang }}
 +    <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
 +  {{ end }}
 +</ul>
 +```
 +
 +## List All content in a Given taxonomy
 +
 +This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
 +
 +### Example: Grouping "Featured" Content
 +
 +```
 +<section id="menu">
 +    <ul>
 +        {{ range $key, $taxonomy := .Site.Taxonomies.featured }}
 +        <li> {{ $key }} </li>
 +        <ul>
 +            {{ range $taxonomy.Pages }}
 +            <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
 +            {{ end }}
 +        </ul>
 +        {{ end }}
 +    </ul>
 +</section>
 +```
 +
 +## Render a Site's Taxonomies
 +
 +If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
 +
 +This may take the form of a tag cloud, a menu, or simply a list.
 +
 +The following example displays all terms in a site's tags taxonomy:
 +
 +### Example: List All Site Tags
 +
 +```
 +<ul id="all-tags">
 +  {{ range $name, $taxonomy := .Site.Taxonomies.tags }}
 +    <li><a href="{{ "/tags/" | relLangURL }}{{ $name | urlize }}">{{ $name }}</a></li>
 +  {{ end }}
 +</ul>
 +```
 +
 +### Example: List All Taxonomies, Terms, and Assigned Content
 +
 +This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
 +
 +{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
 +<section>
 +  <ul id="all-taxonomies">
 +    {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
 +      <li><a href="{{ "/" | relLangURL}}{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
 +        <ul>
 +          {{ range $key, $value := $taxonomy }}
 +          <li> {{ $key }} </li>
 +                <ul>
 +                {{ range $value.Pages }}
 +                    <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
 +                {{ end }}
 +                </ul>
 +          {{ end }}
 +        </ul>
 +      </li>
 +    {{ end }}
 +  </ul>
 +</section>
 +{{< /code >}}
 +
 +## `.Site.GetPage` for Taxonomies
 +
 +Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above:
 +
 +{{< code file="links-to-all-tags" >}}
 +<ul class="tags">
 +  {{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }}
 +   <li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
 +  {{ end }}
 +</ul>
 +{{< /code >}}
 +
 +<!--### `.Site.GetPage` Taxonomy List Example
 +
 +### `.Site.GetPage` Taxonomy Terms Example -->
 +
 +
 +[delimit]: /functions/delimit/
 +[getpage]: /functions/getpage/
 +[lists]: /templates/lists/
 +[renderlists]: /templates/lists/
 +[single page template]: /templates/single-page-templates/
 +[sitevars]: /variables/site/
diff --cc docs/content/templates/views.md
index 0383636a,00000000..c8e003bd
mode 100644,000000..100644
--- a/docs/content/templates/views.md
+++ b/docs/content/templates/views.md
@@@ -1,121 -1,0 +1,121 @@@
 +---
 +title: Content View Templates
 +# linktitle: Content Views
 +description: Hugo can render alternative views of your content, which is especially useful in list and summary views.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [templates]
 +#tags: [views]
 +menu:
 +  docs:
 +    parent: "templates"
 +    weight: 70
 +weight: 70
 +sections_weight: 70
 +draft: false
 +aliases: []
 +toc: true
 +---
 +
 +These alternative **content views** are especially useful in [list templates][lists].
 +
 +The following are common use cases for content views:
 +
 +* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
 +* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
 +
 +## Create a Content View
 +
- To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
++To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
 +
 +```
 +  ▾ layouts/
 +    ▾ post/
 +        li.html
 +        single.html
 +        summary.html
 +    ▾ project/
 +        li.html
 +        single.html
 +        summary.html
 +```
 +
 +Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
 +
 +
 +```
 +▾ layouts/
 +  ▾ _default/
 +      li.html
 +      single.html
 +      summary.html
 +```
 +
 +## Which Template Will be Rendered?
 +
 +The following is the [lookup order][lookup] for content views:
 +
 +1. `/layouts/<TYPE>/<VIEW>.html`
 +2. `/layouts/_default/<VIEW>.html`
 +3. `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
 +4. `/themes/<THEME>/layouts/_default/<VIEW>.html`
 +
 +## Example: Content View Inside a List
 +
 +The following example demonstrates how to use content views inside of your [list templates][lists].
 +
 +### `list.html`
 +
 +In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
 +
 +{{< code file="layouts/_default/list.html" download="list.html" >}}
 +<main id="main">
 +  <div>
 +  <h1 id="title">{{ .Title }}</h1>
 +  {{ range .Data.Pages }}
 +    {{ .Render "summary"}}
 +  {{ end }}
 +  </div>
 +</main>
 +{{< /code >}}
 +
 +### `summary.html`
 +
 +Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
 +
 +{{< code file="layouts/_default/summary.html" download="summary.html" >}}
 +<article class="post">
 +  <header>
 +    <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
 +    <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
 +  </header>
 +  {{ .Summary }}
 +  <footer>
 +  <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
 +  </footer>
 +</article>
 +{{< /code >}}
 +
 +### `li.html`
 +
 +Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
 +
 +{{< code file="layouts/_default/li.html" download="li.html" >}}
 +<li>
 +  <a href="{{ .Permalink }}">{{ .Title }}</a>
 +  <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
 +</li>
 +{{< /code >}}
 +
 +[lists]: /templates/lists/
 +[lookup]: /templates/lookup-order/
 +[pagevars]: /variables/page/
 +[render]: /functions/render/
 +[single]: /templates/single-page-templates/
 +[spf]: http://spf13.com
 +[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
 +[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
 +[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
 +[summaries]: /content-management/summaries/
- [taxonomylists]: /templates/taxonomy-templates/
++[taxonomylists]: /templates/taxonomy-templates/
diff --cc docs/content/themes/installing-and-using-themes.md
index 474b7b03,00000000..4d2be5b7
mode 100644,000000..100644
--- a/docs/content/themes/installing-and-using-themes.md
+++ b/docs/content/themes/installing-and-using-themes.md
@@@ -1,112 -1,0 +1,112 @@@
 +---
 +title: Install and Use Themes
 +linktitle: Install and Use Themes
 +description: Install and use a theme from the Hugo theme showcase easily through the CLI.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +categories: [themes]
 +#tags: [install, themes, source, organization, directories,usage]
 +menu:
 +  docs:
 +    parent: "themes"
 +    weight: 10
 +weight: 10
 +sections_weight: 10
 +draft: false
 +aliases: [/themes/usage/,/themes/installing/]
 +toc: true
 +wip: true
 +---
 +
 +{{% note "No Default Theme" %}}
 +Hugo currently doesn’t ship with a “default” theme. This decision is intentional. We leave it up to you to decide which theme best suits your Hugo project.
 +{{% /note %}}
 +
 +## Assumptions
 +
 +1. You have already [installed Hugo on your development machine][install].
 +2. You have git installed on your machine and you are familiar with basic git usage.
 +
 +## Install Themes
 +
 +The community-contributed themes featured on [themes.gohugo.io](//themes.gohugo.io/) are hosted in a [centralized GitHub repository][themesrepo]. The Hugo Themes Repo at <https://github.com/gohugoio/hugoThemes> is really a meta repository that contains pointers to a set of contributed themes.
 +
 +{{% warning "Get `git` First" %}}
 +Without [Git](https://git-scm.com/) installed on your computer, none of the following theme instructions will work. Git tutorials are beyond the scope of the Hugo docs, but [GitHub](https://try.github.io/) and [codecademy](https://www.codecademy.com/learn/learn-git) offer free, interactive courses for beginners.
 +{{% /warning %}}
 +
 +### Install All Themes
 +
 +You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while.
 +
 +```
 +git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
 +```
 +
 +Before you use a theme, remove the .git folder in that theme's root folder. Otherwise, this will cause problem if you deploy using Git.
 +
 +### Install a Single Theme
 +
 +Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository:
 +
 +```
 +cd themes
 +git clone URL_TO_THEME
 +```
 +
 +The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
 +
 +{{< code file="clone-theme.sh" >}}
 +cd themes
 +git clone https://github.com/spf13/hyde
 +{{< /code >}}
 +
 +Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
 +
 +{{% note "Read the `README`" %}}
 +Always review the `README.md` file that is shipped with a theme. Often, these files contain further instructions required for theme setup; e.g., copying values from an example configuration file.
 +{{% /note %}}
 +
 +## Theme Placement
 +
 +Please make certain you have installed the themes you want to use in the
 +`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended.
 +
 +## Use Themes
 +
 +Hugo applies the decided theme first and then applies anything that is in the local directory. This allows for easier customization while retaining compatibility with the upstream version of the theme. To learn more, go to [customizing themes][customizethemes].
 +
 +### Command Line
 +
- There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your
++There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your [site configuration file][config].
 +
 +To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site:
 +
 +```
 +hugo -t themename
 +```
 +
 +Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]:
 +
 +```
 +hugo server -t themename
 +```
 +
 +### `config` File
 +
 +If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]:
 +
 +```
 +theme: themename
 +```
 +
 +{{% note "A Note on `themename`" %}}
 +The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io).
 +{{% /note %}}
 +
 +[customizethemes]: /themes/customizing/
 +[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage."
 +[install]: /getting-started/installing/
 +[config]: /getting-started/configuration/  "Learn how to customize your Hugo website configuration file in yaml, toml, or json."
- [themesrepo]: https://github.com/gohugoio/hugoThemes
++[themesrepo]: https://github.com/gohugoio/hugoThemes
diff --cc docs/content/tools/syntax-highlighting.md
index e6fb4de8,00000000..d927e0bf
mode 100644,000000..100644
--- a/docs/content/tools/syntax-highlighting.md
+++ b/docs/content/tools/syntax-highlighting.md
@@@ -1,237 -1,0 +1,237 @@@
 +---
 +title: Syntax Highlighting
 +linktitle:
 +description: Hugo provides server-side syntax highlighting via Pygments and, like most static site generators, works very well with client-side (JavaScript) syntax highlighting libraries as well.
 +date: 2017-02-01
 +publishdate: 2017-02-01
 +lastmod: 2017-02-01
 +#tags: [highlighting,pygments,code blocks,syntax]
 +categories: [developer tools]
 +menu:
 +  docs:
 +    parent: "tools"
 +    weight: 20
 +weight: 20
 +sections_weight: 20
 +draft: false
 +aliases: [/extras/highlighting/,/extras/highlight/]
 +toc: true
 +---
 +
 +Hugo can highlight source code in _two different ways_&mdash;either pre-processed server side from your content or to defer the processing to the client side, using a JavaScript library.
 +
 +## Server-side
 +
 +For the pre-processed approach, highlighting is performed by an external Python-based program called [Pygments](http://pygments.org/) and is triggered via an embedded Hugo shortcode (see [example](#example-highlight-shortcode-input) below). If Pygments is absent from the path, it will silently simply pass the content along without highlighting.
 +
 +### Server-side Advantages
 +
 +The advantages of server-side syntax highlighting are that it doesn’t depend on a JavaScript library and, consequently, works very well when read from an RSS feed.
 +
 +### Pygments
 +
 +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`.
 +
 +Hugo gives you two options that you can set with the variable `pygmentsuseclasses` (default `false`) in your [site configuration](/getting-started/configuration/).
 +
 +1. Color codes for highlighting keywords are directly inserted if `pygmentsuseclasses = false` (default). The color codes depend on your choice of the `pygmentsstyle` (default = `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code.
 +2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color codes. For class-names to be meaningful, you need to include a `.css` file in your website representing your color scheme. You can either generate this `.css` files according to the [description from the Pygments documentation](http://pygments.org/docs/cmdline/) or download the one of the many pre-built color schemes from [Pygment's GitHub css repository](https://github.com/richleland/pygments-css).
 +
 +### Server-side Usage
 +
 +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 Input
 +
 +{{< 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 >}}
 +
 +### Example `highlight` Shortcode Output
 +
 +{{< output file="example-highlight-shortcode-output.html" >}}
 +<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
 +  <span style="color: #f92672">&lt;div&gt;</span>
 +    <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
 +    {{ range .Data.Pages }}
 +      {{ .Render &quot;summary&quot;}}
 +    {{ end }}
 +  <span style="color: #f92672">&lt;/div&gt;</span>
 +<span style="color: #f92672">&lt;/section&gt;</span>
 +{{< /output >}}
 +
 +### Options
 +
 +Options for controlling highlighting can be added in the second argument as a quoted, comma-separated key-value list. The example below will syntax highlight in `go` with inline line numbers and line numbers 2 and 3 highlighted.
 +
 +```
 +{{</* highlight go "linenos=inline,hl_lines=2 3" */>}}
 +var a string
 +var b string
 +var c string
 +var d string
 +{{</* / highlight */>}}
 +```
 +
 +The `highlight` shortcode includes the following supported keywords:
 +
 +* `style`
 +* `encoding`
 +* `noclasses`
 +* `hl_lines`
 +* `linenos`
 +
 +Note that `style` and `noclasses` will override the similar setting in the [global config](/getting-started/configuration/).
 +
 +The keywords in the `highlight` shortcode mirror those of Pygments from the command line. See the [Pygments documentation](http://pygments.org/docs/) for more information.
 +
 +### 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/);
 +
 +```
 +```
 +<section id="main">
 +  <div>
 +    <h1 id="title">{{ .Title }}</h1>
 +    {{ range .Data.Pages }}
 +      {{ .Render "summary"}}
 +    {{ end }}
 +  </div>
 +</section>
 +```
 +```
 +
 +{{% 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 %}}
 +
 +## Client-side
 +
 +Alternatively, code highlighting can be applied to your code blocks in client-side JavaScript.
 +
 +Client-side syntax highlighting is very simple to add. You'll need to pick
 +a library and a corresponding theme. Some popular libraries are:
 +
 +- [Highlight.js]
 +- [Prism]
 +- [Rainbow]
 +- [Syntax Highlighter]
 +- [Google Prettify]
 +
 +### Client-side Advantages
 +
 +The advantages of client-side syntax highlighting are that it doesn’t cost anything when building your site, and some of the highlighting scripts available cover more languages than Pygments does.
 +
 +### Highlight.js Example
 +
 +This example uses the popular [Highlight.js] library, hosted by [Yandex], a popular Russian search engine.
 +
 +In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your specific theme, there will be a snippet that will be included in every generated HTML page, such as `header.html` or `header.includes.html`. Simply add the css and js to initialize [Highlight.js]:
 +
 +```
 +<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/styles/default.min.css">
 +<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/highlight.min.js"></script>
 +<script>hljs.initHighlightingOnLoad();</script>
 +```
 +
 +### Prism example
 +
 +Prism is another popular highlighter library and is used on some major sites.
 +The [download section of the prism.js website][prismdownload] is simple to use and affords you a high degree of customization to pick only the languages you'll be using on your site.
 +
 +Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages:
 +
 +```
 +...
 +<link href="/css/prism.css" rel="stylesheet" />
 +...
 +```
 +
 +Add `prism.js` near the bottom of your `<body>` tag in whatever Hugo partial template is appropriate for your site or theme.
 +
 +```
 +...
 +<script src="/js/prism.js"></script>
 +</body>
 +```
 +
 +In this example, the local paths indicate that your downloaded copy of these files are being added to the site, typically under `./static/css/` and `./static/js/`, respectively.
 +
 +### Client-side Usage
 +
 +To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` elements with language-specific class attributes. For example, a code block for HTML would have `class="language-html"`.
 +
 +The client-side highlighting script therefore looks for programming language classes according to this convention: `language-go`, `language-html`, `language-css`, `language-bash`, etc. If you look at the page's source, you might see something like the following:
 +
 +```
 +<pre>
 +  <code class="language-css">
 +  body {
 +    font-family: "Noto Sans", sans-serif;
 +  }
 +  </code>
 +</pre>
 +```
 +
 +If you are using markdown, your content pages needs to use the following syntax, with the name of the language to be highlighted entered directly after the first "fence." A fenced code block can be noted by opening and closing triple tilde <kbd>~</kbd> or triple back ticks <kbd>`</kbd>:
 +
 +{{< nohighlight >}}
 +~~~css
 +body {
 +  font-family: "Noto Sans", sans-serif;
 +}
 +~~~
 +{{< /nohighlight >}}
 +
 +Here is the same example but with triple back ticks to denote the fenced code block:
 +
 +{{< nohighlight >}}
- ```
++```css
 +body {
 +  font-family: "Noto Sans", sans-serif;
 +}
 +```
 +{{< /nohighlight >}}
 +
 +Passing the above examples through the highlighter script would yield the following markup:
 +
 +{{< nohighlight >}}
 +&lt;pre&gt;&lt;code class="language-css hljs"&gt;;&lt;span class="hljs-selector-tag"&gt;body&lt;/span&gt; {
 +  &lt;span class="hljs-attribute"&gt;font-family&lt;/span&gt;: &ltspan class="hljs-string"&gt;"Noto Sans"&lt;/span&gt;, sans-serif;
 +}
 +{{< /nohighlight >}}
 +
 +In the case of the coding color scheme used by the Hugo docs, the resulting output would then look like the following to the website's end users:
 +
 +```
 +body {
 +  font-family: "Noto Sans", sans-serif;
 +}
 +```
 +
 +Please see individual libraries' documentation for how to implement each of the JavaScript-based libraries.
 +
 +[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/
++[Yandex]: http://yandex.ru/
diff --cc docs/static/images/hosting-and-deployment/deployment-with-nanobox/hugo-server.png
index 00000000,00000000..b37b2c37
new file mode 100644
Binary files differ
diff --cc docs/static/images/hosting-and-deployment/deployment-with-nanobox/hugo-with-nanobox.png
index 00000000,00000000..8b889b34
new file mode 100644
Binary files differ
diff --cc docs/static/images/hosting-and-deployment/deployment-with-nanobox/nanobox-deploy-dry-run.png
index 00000000,00000000..55c43830
new file mode 100644
Binary files differ
diff --cc docs/static/images/hosting-and-deployment/deployment-with-nanobox/nanobox-run.png
index 00000000,00000000..3432df8c
new file mode 100644
Binary files differ