doc: Merge commit '2c0d1ccdcd95de0bddeb39dca2e4d08f0d8056d7'

docs/README.md

@@ -2,12 +2,37 @@
 
 Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang.
 
-## Branches
+## Contributing
 
-* The `master` branch is the **current Hugo version** and will be auto-deployed to [gohugo.io/](https://gohugo.io/).
-* Anything not relevant to the current Hugo version goes into the `dev` branch.
-* Changes in [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs) will, in general, be merged once every release, but can be manually merged/cherry picked if needed. This goes both ways.
-* All contributions that is not tightly coupled with code changes, should be made directly to `hugoDocs`.
-* But we also merge PRs into  [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs), but preferably changes that is related to the code in the PR itself
+We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. 
 
-To summarize, we have two branches in this repository: `master` (current Hugo) and `dev` (next Hugo).
+Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. 
+
+*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
+
+
+## Build
+
+To view the documentation site locally, you need to clone this repository with submodules:
+
+```bash
+git clone --recursive https://github.com/gohugoio/hugoDocs.git
+```
+
+Or if you already have a clone locally:
+
+```bash
+git submodule update --init
+```
+Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo).
+
+Then to view the docs in your browser, run Hugo and open up the link:
+```bash
+hugo serve
+Started building sites ...
+.
+.
+Serving pages from memory
+Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
+Press Ctrl+C to stop
+```

docs/config.toml

@@ -16,8 +16,17 @@ pluralizeListTitles = false
 # We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
 disableAliases = true
 
+
+# Highlighting config (Pygments)
+# It is (currently) not in use, but you can do ```go in a content file if you want to.
+pygmentsCodeFences = true
+
+# See https://help.farbox.com/pygments.html
+pygmentsStyle = "friendly"
+
 [outputs]
 home = [ "HTML", "RSS", "REDIR" ]
+section = [ "HTML", "RSS"]
 
 [mediaTypes]
 [mediaTypes."text/netlify"]

docs/content/_index.md

@@ -29,7 +29,7 @@ features:
 
   - heading: Custom Outputs
     image_path: /images/icon-custom-outputs.svg
-    tagline: HTML not Enough?
+    tagline: HTML not enough?
     copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own.
 sections:
   - heading: "100s of Themes"

docs/content/about/license.md

@@ -148,8 +148,7 @@ _END OF TERMS AND CONDITIONS_
 
 To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
 
-{{% code file="apache-notice.txt" download="apache-notice.txt" %}}
-```
+{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
 Copyright [yyyy] [name of copyright owner]
 
 Licensed under the Apache License, Version 2.0 (the "License");
@@ -163,5 +162,4 @@ distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-```
-{{% /code %}}
+{{< /code >}}

docs/content/content-management/archetypes.md

@@ -31,17 +31,15 @@ See above
 
 The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
 
-```bash
+```
 hugo new <content-section>/<file-name.md>
 ```
 
 We can use this pattern to create a new `.md` file in the `posts` section:
 
-{{% code file="archetype-example.sh" %}}
-```bash
+{{< code file="archetype-example.sh" >}}
 hugo new posts/my-first-post.md
-```
-{{% /code %}}
+{{< /code >}}
 
 {{% note "Override Content Type in a New File" %}}
 To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
@@ -50,7 +48,7 @@ To override the content type Hugo infers from `[content-section]`, add the `--ki
 Running this command in a new site that does not have default or custom archetypes will create the following file:
 
 {{% output file="content/posts/my-first-post.md" %}}
-```toml
+```
 +++
 date = "2017-02-01T19:20:04-07:00"
 title = "my first post"
@@ -100,14 +98,12 @@ When you create a new Hugo project using `hugo new site`, you'll notice that Hug
 
 The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
 
-{{% code file="archetypes/default.md" %}}
-```toml
+{{< code file="archetypes/default.md" >}}
 +++
 tags = ["golang", "hugo"]
 categories = ["web development"]
 +++
-```
-{{% /code %}}
+{{< /code >}}
 
 {{% warning "EOL Characters in Text Editors"%}}
 If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
@@ -117,16 +113,14 @@ If you get an `EOF error` when using `hugo new`, add a carriage return after the
 
 With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
 
-{{% code file="new-post-from-default.sh" %}}
-```bash
+{{< code file="new-post-from-default.sh" >}}
 $ hugo new posts/my-new-post.md
-```
-{{% /code %}}
+{{< /code >}}
 
 Hugo then creates a new markdown file with the following front matter:
 
 {{% output file="content/posts/my-new-post.md" %}}
-```toml
+```
 +++
 categories = ["web development"]
 date = "2017-02-01T19:20:04-07:00"
@@ -148,30 +142,26 @@ Suppose your site's `posts` section requires more sophisticated front matter tha
 
 ### Create a Custom Archetype
 
-{{% code file="archetypes/posts.md"%}}
-```toml
+{{< code file="archetypes/posts.md">}}
 +++
 description = ""
 tags = ""
 categories = ""
 +++
-```
-{{% /code %}}
+{{< /code >}}
 
 ### Use a Custom Archetype
 
 With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
 
-{{% code file="new-post-from-custom.sh" %}}
-```bash
+{{< code file="new-post-from-custom.sh" >}}
 $ hugo new posts/post-from-custom.md
-```
-{{% /code %}}
+{{< /code >}}
 
 This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
 
 {{% output file="content/posts/post-from-custom-archetype.md" %}}
-```toml
+```
 +++
 categories = ""
 date = 2017-02-13T17:24:43-08:00
@@ -186,11 +176,9 @@ title = "post from custom archetype"
 
 As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
 
-{{% code file="archetypes/functions.md" %}}
-```yaml
+{{< code file="archetypes/functions.md" >}}
 {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}}
-```
-{{% /code %}}
+{{< /code >}}
 
 {{% note %}}
 The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).

docs/content/content-management/authors.md

@@ -30,8 +30,7 @@ You can create a profile containing metadata for each author on your website. Th
 
 Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML:
 
-{{% code  file="data/_authors/alice.toml" %}}
-```toml
+{{< code  file="data/_authors/alice.toml" >}}
 givenName      = "Alice"   # or firstName as alias
 familyName     = "Allison" # or lastName as alias
 displayName    = "Alice Allison"
@@ -50,8 +49,7 @@ weight         = 10
 
 [params]
     random     = "whatever you want"
-```
-{{% /code %}}
+{{< /code >}}
 
 All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
 
@@ -67,7 +65,7 @@ The `params` section can contain arbitrary data much like the same-named section
 
 Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively.
 
-```yaml
+```
 ---
 title: Why Hugo is so Awesome
 date: 2016-08-22T14:27:502:00
@@ -77,7 +75,7 @@ authors: ["alice"]
 Nothing to read here. Move along...
 ```
 
-```toml
+```
 +++
 title = Why Hugo is so Awesome
 date = "2016-08-22T14:27:502:00"
@@ -116,8 +114,7 @@ This is can be done with the `.Social.URL` function. Its only parameter is the n
 
 Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks:
 
-{{% code file="layouts/partials/author-info.html" download="author-info.html" %}}
-```html
+{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
 {{ with .Author }}
     <h3>{{ .DisplayName }}</h3>
     <img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
@@ -128,21 +125,20 @@ Most articles feature a small section with information about the author at the e
     {{ end }}
     </ul>
 {{ end }}
-```
-{{% /code %}}
+{{< /code >}}
 
 ## Who Published What?
 
 That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right?
 
 In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively:
 
-```yaml
+```
 taxonomies:
     author: authors
 ```
 
-```toml
+```
 [taxonomies]
     author = "authors"
 ```
@@ -152,8 +148,7 @@ taxonomies:
 
 In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy.
 
-{{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}}
-```html
+{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
 <ul>
 {{ range $author, $v := .Data.Terms }}
     {{ $profile := $.Authors.Get $author }}
@@ -164,8 +159,7 @@ In the next step we can create a template to list all authors of your website. L
     </li>
 {{ end }}
 </ul>
-```
-{{% /code %}}
+{{< /code >}}
 
 `.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
 
@@ -175,15 +169,13 @@ Last but not least, we have to create the second list that contains all publicat
 
 The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
 
-{{% code file="layouts/taxonomy/author.html" download="author.html" %}}
-```html
+{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
 {{ range .Data.Pages }}
     <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
     <span>written by {{ .Author.DisplayName }}</span>
     {{ .Summary }}
 {{ end }}
-```
-{{% /code %}}
+{{< /code >}}
 
 The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
 

docs/content/content-management/comments.md

@@ -29,11 +29,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
 
 Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively:
 
-```toml
+```
 disqusShortname = "yourdiscussshortname"
 ```
 
-```yaml
+```
 disqusShortname: "yourdiscussshortname"
 ```