Merge commit '3886fc1fef6ac19d58b9ba1bb642d0c6c9a54031'

26 files changed, 277 insertions, 90 deletions

diff --git a/docs/content/content-management/menus.md b/docs/content/content-management/menus.md
index 26c1eafad..1353ce0e2 100644
--- a/docs/content/content-management/menus.md
+++ b/docs/content/content-management/menus.md
@@ -151,7 +151,7 @@ menu:
 {{< /code >}}
 
 {{% note %}}
-The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
+The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
 {{% /note %}}
 
 ## Nesting
diff --git a/docs/content/content-management/multilingual.md b/docs/content/content-management/multilingual.md
index f9c7a9ba3..eba196c39 100644
--- a/docs/content/content-management/multilingual.md
+++ b/docs/content/content-management/multilingual.md
@@ -59,6 +59,28 @@ If you want all of the languages to be put below their respective language code,
 
 Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
 
+## Disable a Language
+
+You can disable one or more languages. This can be useful when working on a new translation.
+
+```toml
+disableLanguages = ["fr", "jp"]
+```
+
+Note that you cannot disable the default content language.
+
+We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables):
+
+```bash
+HUGO_DISABLELANGUAGES="fr jp" hugo
+```
+If you have already a list of disabled languages in `config.toml`, you can enable them in development like this:
+
+```bash
+HUGO_DISABLELANGUAGES=" " hugo server
+```
+
+
 ## Configure Multilingual Multihost
 
 From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.
diff --git a/docs/content/content-management/page-bundles.md b/docs/content/content-management/page-bundles.md
index fbb9025ca..f497a59b2 100644
--- a/docs/content/content-management/page-bundles.md
+++ b/docs/content/content-management/page-bundles.md
@@ -129,9 +129,7 @@ This `_index.md` can also be directly under the `content/` directory.
 
 {{% note %}}
 Here `md` (markdown) is used just as an example. You can use any file
-type as a content resource as long as it is a MIME type recognized by
-Hugo (`json` files will, as one example, work fine). If you want to
-get exotic, you can define your own media type.
+type as a content resource as long as it is a content type recognized by Hugo.
 {{% /note %}}
 
 
diff --git a/docs/content/content-management/sections.md b/docs/content/content-management/sections.md
index 0e167d143..e53e0feb7 100644
--- a/docs/content/content-management/sections.md
+++ b/docs/content/content-management/sections.md
@@ -17,36 +17,50 @@ aliases: [/content/sections/]
 toc: true
 ---
 
+A **Section** is a collection of pages that gets defined based on the
+organization structure under the `content/` directory.
+
+By default, all the **first-level** directories under `content/` form their own
+sections (**root sections**).
+
+If a user needs to define a section `foo` at a deeper level, they need to create
+a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
+for more information).
+
+
+{{% note %}}
+A **section** cannot be defined or overridden by a front matter parameter -- it
+is strictly derived from the content organization structure.
+{{% /note %}}
 
 ## Nested Sections
 
 The sections can be nested as deeply as you need.
 
 ```bash
-blog
-├── funny-cats
-│   └── kittens
-│       └── _index.md
-└── tech
-    └── _index.md
+content
+└── blog        <-- Section, because first-level dir under content/
+    ├── funny-cats
+    │   ├── mypost.md
+    │   └── kittens         <-- Section, because contains _index.md
+    │       └── _index.md
+    └── tech                <-- Section, because contains _index.md
+        └── _index.md
 ```
 
-
-**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** 
-
+**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
 
 {{% note %}}
-When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`). 
+When we talk about a **section** in correlation with template selection, it is
+currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
 
 If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
 {{% /note %}}
 
-
 ## Example: Breadcrumb Navigation
 
 With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
 
-
 {{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
 <ol  class="nav navbar-nav">
   {{ template "breadcrumbnav" (dict "p1" . "p2" .) }}
@@ -71,15 +85,14 @@ Also see [Page Variables](/variables/page/).
 
 ## Content Section Lists
 
-Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
+Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered.
 
 ## Content *Section* vs Content *Type*
 
-By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
+By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`.
 
 [archetype]: /content-management/archetypes/
 [content type]: /content-management/types/
 [directory structure]: /getting-started/directory-structure/
 [section templates]: /templates/section-templates/
-
-
+[branch bundles]: /content-management/page-bundles/#branch-bundles
diff --git a/docs/content/functions/title.md b/docs/content/functions/title.md
index e3a7e9c0b..63a34835f 100644
--- a/docs/content/functions/title.md
+++ b/docs/content/functions/title.md
@@ -24,7 +24,7 @@ aliases: []
 {{title "BatMan"}}` → "Batman"
 ```
 
-Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Intial Caps.
+Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Initial Caps.
 
 ```
 {{ range $name, $items := .Site.Taxonomies.categories }}
diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md
index 8fd72290f..292b3e68b 100644
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -18,10 +18,28 @@ aliases: [/overview/source-directory/,/overview/configuration/]
 toc: true
 ---
 
+Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the
+site root) as the default site config file.
+
+The user can choose to override that default with one or more site config files
+using the command line `--config` switch.
+
+Examples:
+
+```
+hugo --config debugconfig.toml
+hugo --config a.toml,b.toml,c.toml
+```
+
+{{% note %}}
+Multiple site config files can be specified as a comma-separated string to the `--config` switch.
+{{% /note %}}
 
 ## All Configuration Settings
 
-The following is the full list of Hugo-defined variables with its default value in parens.
+The following is the full list of Hugo-defined variables with their default
+value in parentheses. Users may choose to override those values in their site
+config file(s).
 
 archetypeDir ("archetypes")
 : The directory where Hugo finds archetype files (content templates).
@@ -29,6 +47,9 @@ archetypeDir ("archetypes")
 baseURL
 : Hostname (and path) to the root, e.g. http://bep.is/
 
+blackfriday
+: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday)
+
 buildDrafts (false)
 : Include drafts when building.
 
@@ -41,9 +62,6 @@ buildFuture (false)
 canonifyURLs (false)
 : Enable to turn relative URLs into absolute.
 
-config ("config.toml")
-: Config file (default is path/config.yaml|json|toml).
-
 contentDir ("content")
 : The directory from where Hugo reads content files.
 
@@ -54,47 +72,47 @@ defaultContentLanguage ("en")
 : Content without language indicator will default to this language.
 
 defaultContentLanguageInSubdir (false)
-: Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/.
+: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`.
 
 disableHugoGeneratorInject (false)
 : Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise.
 
 disableKinds ([])
-: Allows you to disable all page types and will render nothing related to 'kind'. Allowed values are "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404".
+: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`.
 
 disableLiveReload (false)
-: Turn off automatic live reloading of browser window.
+: Disable automatic live reloading of browser window.
 
 disablePathToLower (false)
-: Do not make the url/path to lowercase.
+: Do not convert the url/path to lowercase.
 
 enableEmoji (false)
-: Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com.
+: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/).
 
 enableGitInfo (false)
-: If the Hugo site is versioned by Git, you will then get a `.GitInfo` object per page, and `Lastmod` will get updated by the last commit date for content.	
+: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file.
 
 enableMissingTranslationPlaceholders (false)
-: Show a placeholder instead of the default value or an empty string if a translation is missing
+: Show a placeholder instead of the default value or an empty string if a translation is missing.
 
 enableRobotsTXT (false)
-: When enabled, Hugo will generate a `robots.txt` file.
+: Enable generation of `robots.txt` file.
 
 frontmatter
 
 : See [Front matter Configuration](#configure-front-matter).
 
 footnoteAnchorPrefix ("")
-: A prefix for your footnote anchors.
+: Prefix for footnote anchors.
 
 footnoteReturnLinkContents ("")
-: A return link for your footnote.
+: Text to display for footnote return links.
 
 googleAnalytics ("")
-: google analytics tracking id
+: Google Analytics tracking ID.
 
 hasCJKLanguage (false)
-: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly in CJK languages.
+: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages.
 
 imaging
 : See [Image Processing Config](/content-management/image-processing/#image-processing-config).
@@ -105,6 +123,9 @@ languages
 languageCode ("")
 : The site's language code.
 
+disableLanguages
+: See [Disable a Language](/content-management/multilingual/#disable-a-language)
+
 layoutDir ("layouts")
 : The directory from where Hugo reads layouts (templates).
 
@@ -118,7 +139,7 @@ menu
 : See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu).
 
 metaDataFormat ("toml")
-: "toml","yaml", or "json"
+: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`.
 
 newContentEditor ("")
 : The editor to use when creating new content.
@@ -127,19 +148,19 @@ noChmod (false)
 : Don't sync permission mode of files.
 
 noTimes (false)
-: Don't sync modification time of files
+: Don't sync modification time of files.
 
 paginate (10)
-: Default number of pages per page in pagination.
+: Default number of pages per page in [pagination](/templates/pagination/).
 
 paginatePath ("page")
-: The path element used during pagination (http://example.com/page/2).
+: The path element used during pagination (https://example.com/page/2).
 
 permalinks
-: See [Content Management](/content-management/urls/#permalinks)
+: See [Content Management](/content-management/urls/#permalinks).
 
 pluralizeListTitles (true)
-: Pluralize titles in lists using inflect.
+: Pluralize titles in lists.
 
 preserveTaxonomyNames (false)
 : Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu").
@@ -148,13 +169,13 @@ publishDir ("public")
 : The directory to where Hugo will write the final static site (the HTML files etc.).
 
 pygmentsCodeFencesGuessSyntax (false)
-: Enables syntax guessing for code fences without specified language.
+: Enable syntax guessing for code fences without specified language.
 
 pygmentsStyle ("monokai")
-: Color-codes for highlighting derived from this style. See https://help.farbox.com/pygments.html
+: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html).
 
 pygmentsUseClasses (false)
-: Enable to use external CSS for code highlighting.
+: Enable using external CSS for syntax highlighting.
 
 related
 : See [Related Content](/content-management/related/#configure-related-content).
@@ -162,14 +183,14 @@ related
 relativeURLs (false)
 : Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
 
-rssLimit (15)
+rssLimit (unlimited)
 : Maximum number of items in the RSS feed.
 
-sectionPagesMenu ("")(
+sectionPagesMenu ("")
 : See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers).
 
 sitemap
-: Default sitemap configuration.
+: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml).
 
 staticDir ("static")
 : Relative directory from where Hugo reads static files.
@@ -178,13 +199,13 @@ stepAnalysis (false)
 : Display memory and timing of different steps of the program.
 
 summaryLength (70)
-: The length of text to show in a `.Summary`.
+: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting).
 
 taxonomies
-: See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies)
+: See [Configure Taxonomies](content-management/taxonomies#configure-taxonomies).
 
 theme ("")
-: Theme to use (located by default in /themes/THEMENAME/)
+: Theme to use (located by default in `/themes/THEMENAME/`).
 
 themesDir ("themes")
 : The directory where Hugo reads the themes from.
@@ -193,7 +214,7 @@ title ("")
 : Site title.
 
 uglyURLs (false)
-: When enabled creates URL on the form `/filename.html` instead of `/filename/`
+: When enabled, creates URL on the form `/filename.html` instead of `/filename/`.
 
 verbose (false)
 : Enable verbose output.
diff --git a/docs/content/getting-started/directory-structure.md b/docs/content/getting-started/directory-structure.md
index f8b4cced6..ebfe6646a 100644
--- a/docs/content/getting-started/directory-structure.md
+++ b/docs/content/getting-started/directory-structure.md
@@ -42,7 +42,7 @@ The following is a high-level overview of each of the directories with links to
 
 [`archetypes`](/content-management/archetypes/)
 : You can create new content files in Hugo using the `hugo new` command.
-By default, hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
+By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
 
 [`config.toml`](/getting-started/configuration/)
 : Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
@@ -58,7 +58,7 @@ used by Hugo when generating your website. You can write these files in YAML, JS
 : Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more.
 
 [`static`][]
-: stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
+: Stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
 
 {{% note %}}
 From **Hugo 0.31** you can have multiple static directories.
diff --git a/docs/content/news/0.30-relnotes-ready.md b/docs/content/news/0.30-relnotes-ready.md
index 06489cb31..7c2632ae6 100644
--- a/docs/content/news/0.30-relnotes-ready.md
+++ b/docs/content/news/0.30-relnotes-ready.md
@@ -14,7 +14,7 @@ Hugo `0.30` is the **Race Car Edition**. Hugo is already very very fast, but muc
 
 The second performance-related feature is a follow-up to the Template Metrics added in Hugo `0.29`. Now, if you add the flag `--templateMetricsHints`, we will calculate a score for how your partials can be cached (with the `partialCached` template func).
 
-This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most noteable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier.
+This release also more or less makes the really fast Chroma highlighter a complete alternative to Pygments. Most notable is the new table `linenos` support ([7c30e2cb](https://github.com/gohugoio/hugo/commit/7c30e2cbb08fdf0e61f80c7f1aa29909aeca4211) [@bep](https://github.com/bep) [#3915](https://github.com/gohugoio/hugo/issues/3915)), which makes copy-and-paste code blocks much easier.
 
 This release represents **31 contributions by 10 contributors** to the main Hugo code base.
 [@bep](https://github.com/bep) leads the Hugo development with a significant amount of contribution, but also a big shoutout to [@moorereason](https://github.com/moorereason), [@digitalcraftsman](https://github.com/digitalcraftsman), and [@bmon](https://github.com/bmon) for their ongoing contributions.
diff --git a/docs/content/news/0.34-relnotes/index.md b/docs/content/news/0.34-relnotes/index.md
index de596fc62..dd5418a77 100644
--- a/docs/content/news/0.34-relnotes/index.md
+++ b/docs/content/news/0.34-relnotes/index.md
@@ -32,7 +32,7 @@ Hugo now has:
 * 197+ [themes](http://themes.gohugo.io/)
 
 ## Notes
-* `Resources.GetByPrefix` and  `Resources.ByPrefix` are depracated. They still work, but will eventually be removed.  Use `Resources.Match` (many) and `Resources.GetMatch`  (one).
+* `Resources.GetByPrefix` and  `Resources.ByPrefix` are deprecated. They still work, but will eventually be removed.  Use `Resources.Match` (many) and `Resources.GetMatch`  (one).
 * When filtering bundles pages in sub-folders, you need to include the sub-folder when matching. This was a bug introduced in `0.33` and gets it in line with images and other resources.
 
 ## Enhancements
diff --git a/docs/content/showcase/forestry/bio.md b/docs/content/showcase/forestry/bio.md
new file mode 100644
index 000000000..767365cc0
--- /dev/null
+++ b/docs/content/showcase/forestry/bio.md
@@ -0,0 +1,5 @@
+
+Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo. 
+
+Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams.
+
diff --git a/docs/content/showcase/forestry/featured.png b/docs/content/showcase/forestry/featured.png
new file mode 100644
index 000000000..1ee315e78
--- /dev/null
+++ b/docs/content/showcase/forestry/featured.png
diff --git a/docs/content/showcase/forestry/index.md b/docs/content/showcase/forestry/index.md
new file mode 100644
index 000000000..ee1ebe07a
--- /dev/null
+++ b/docs/content/showcase/forestry/index.md
@@ -0,0 +1,48 @@
+---
+title: Forestry.io
+date: 2018-03-16
+description: "A Git-backed CMS (content management system) for websites and web products built using static site generators."
+siteURL: https://forestry.io/
+siteSource: https://github.com/forestryio/forestry.io
+---
+
+It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us?
+
+### Why Hugo?
+
+In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast.
+
+We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look:
+
+```bash
+                   | EN   
++------------------+-----+
+  Pages            | 141  
+  Paginator pages  |   4  
+  Non-page files   |   0  
+  Static files     | 537  
+  Processed images |   0  
+  Aliases          |  60  
+  Sitemaps         |   1  
+  Cleaned          |   0  
+
+Total in 739 ms
+```
+
+In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing.
+
+Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website.
+
+### What tools did we use?
+
+* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a des