Update multilingual page

2026-08-24 15:28:54 +00:00 · 2017-02-26 19:27:05 -06:00
parent 495d88ef9b
commit 6cf783469e
74 changed files with 985 additions and 462 deletions
@@ -1,5 +1,5 @@
 ---
-linktitle:
+linktitle: ""
 description: ""
 godocref: ""
 publishdate: ""
@@ -11,5 +11,5 @@ draft: true
 slug: ""
 aliases: []
 toc: false
-z_notesforauthors: "Go to gohugo.io/docscontrib for info on req fields"
+z_notesforauthors: "Go to gohugo.io/contribute/documentation for more info on using this archetype."
 ---
@@ -12,5 +12,5 @@ tags: []
 toc: false
 draft: false
 aliases: []
-z_notesforauthors: "Go to gohugo.io/docscontrib for info on req fields"
+z_notesforauthors: "Go to gohugo.io/contribute/documentation for more info on using this archetype."
 ---
@@ -9,5 +9,5 @@ categories: [showcase]
 tags: []
 image: "yourimage.jpg"
 toc: false
-z_notesforauthors: "Go to gohugo.io/docscontrib for info on req fields"
+z_notesforauthors: "Go to gohugo.io/contribute/documentation for more info on using this archetype."
 ---
@@ -11,6 +11,6 @@ authorurl: ""
 originalurl: ""
 draft: false
 aliases: []
-z_notesforauthors: "Go to gohugo.io/docscontrib for info on required fields"
+z_notesforauthors: "Go to gohugo.io/contribute/documentation for more info on using this archetype."
 ---

@@ -82,7 +82,7 @@ See what's coming next in the [Hugo roadmap][].
 [sort content]: /templates/
 [supported formats]: /content-management/formats/
 [Syntax highlighting]: /developer-tools/syntax-highlighting/
-[table of contents]: /content-management/table-of-contents/
+[table of contents]: /content-management/toc/
 [taxonomies]: /content-management/taxonomies/
 [URLs]: /content-management/urls/
 [Windows]: /getting-started/install-on-linux/
@@ -15,7 +15,7 @@ toc: true

 {{% note %}}
 Hugo v0.15 and later are released under the Apache 2.0 license.
-Earlier version of Hugo were released under the Simple Public License.
+Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/licenses/Simple-2.0).
 {{% /note %}}

 _Version 2.0, January 2004_ <br>
@@ -13,41 +13,40 @@ aliases: []
 toc: true
 ---

-## Strategy, Tactics, and Requirements
-
-{{% warning "Disclaimer" %}}
-WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document.
-{{% /warning %}}
-
 ### Introduction

 The claims made in this strategic document are largely *empirical* and pulled from two major sources:

-* My experience starting 18 months ago as a new user.
+* My experience starting 18 months ago as a new Hugo user.
 * Conversations with fellow Hugo users and noted trends within the [Discussion Forum][forum].

-Ideally,
+{{% warning "Disclaimer" %}}
+WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document. It'll get better. I promise.
+{{% /warning %}}
+
+## Strategy, Tactics, and Requirements

 ### Assumptions

-* The current documentation
-    * is confusing for new users
-    * is a common complaint in the Hugo forums ([example discussion 1][ex1], [example discussion 2][ex2])
-    * lacks structure and is therefore
-        * unscalable, as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown
-        * inconsistent in its terminology, style, and (sometimes) layout
-        * limited in effective use of Alogolia's document search (i.e., because of redundant content grouping, headings, etc)
-        * difficult to optimize external search engines (SEO)
-    * does not leverage Hugo's more powerful feature (e.g., there is only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
-    * assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development. An prime example is the sparsity of basic and advanced code samples through the templating functions, some of which are still wholly undocumented.
+The current Hugo documentation
+
+* is confusing for new users
+* is a common complaint in the Hugo forums ([forum discussion 1][ex1], [forum discussion 2][ex2])
+* lacks structure and is therefore
+    * unscalable, as demonstrated by patch pages (e.g. [here][patch1] and [here][patch2]) that seem out of place, require unnecessary drilldown, or duplicate content in other areas of the docs, thus requiring duplicative efforts to update
+    * inconsistent in its terminology, style, and (sometimes) layout
+    * limited in effective use of Alogolia's document search (i.e., because of redundant content grouping, headings, etc)
+    * difficult to optimize for external search engines (SEO)
+* does not leverage Hugo's more powerful feature (e.g., there is only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
+* assumes a higher level of Golang proficiency than is realistic for newcomers to static site generators or general web development. A prime example is the sparsity of basic and advanced code samples for templating functions, some of which may still be wholly undocumented.

 ### Goals

 New Hugo documentation should...

-* reduce confusion surrounding Hugo concepts; e.g., `list`, `section`, `page`, and `content type` with the intention of
+* reduce confusion surrounding Hugo concepts; e.g., `list`, `section`, `page`, `kind`, and `content type` with the intention of
    * making it easier for new users to get up and running
-    * creating better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io](http://themes.gohugo.io))
+    * creating better consistency and scalability for Hugo-dependent projects (viz., [themes.gohugo.io][hugothemes])
    * reducing the frequency of beginner-level questions in the [Hugo Discussion Forum][forum]
 * not require, or assume, any degree of Golang proficiency from end users;
    * that said, Hugo can&mdash;and *should*&mdash;act as a bridge for users interested in learning Golang. A implementationn example of this strategy point is the inclusion of `godocref:` as a default front matter field for all function and template pages. See [`archetypes/functions.md`][functionarchetype].
@@ -155,8 +154,8 @@ The following are high-level requirements for the documentation site.

 ## Author Experience (AX)

- [X] Easy scaffolding of content types (CLI)
- [X] Type-based content storage model and scope (archetypes)
+- [X] Easy scaffolding of content types (i.e., via Hugo CLI [`hugo new`])
+- [X] Type-based content storage model and scope (i.e, via archetypes)

 ## Analytics/Metrics

@@ -165,10 +164,10 @@ The following are high-level requirements for the documentation site.
 - [ ] Automated reports (GA)

 {{% note %}}
-These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
+The preceding analytics and metrics are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
 {{% /note %}}

-## Visual Design
+## Visual Design and Front-end Development

 - [X] Clean typography with open-source font
    - [X] Optimal line length (50-80 characters)
@@ -184,10 +183,9 @@ These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc
    - [X] Abstracted typefaces (multiple open-source fonts available)


-
 ## Content Changes

-The following is an *abbreviated* listing of *substantive* changes to content organization. Everything is ordered according to the current docs site navigation. The changes I delimit here do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.
+The following is an *abbreviated* listing of *substantive* changes made to the current documentation's source content and organization. Sections here are ordered according to the current site navigation. The changes delimited here do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.

 ### Download Hugo

@@ -195,7 +193,9 @@ This is no longer a site navigation link and is instead a button along with "Fil

 ### Site Showcase

-* Site showcase has stayed more or less as is, including styling, etc. However, I did clean up the templating and all currently submitted showcase files. (E.g., changing "thumbnail" to "image" and not requiring a full path.) This will also be updated in the ["docs" page of the contribute section](/contribute/documentation/)
+Site showcase has stayed more or less as is, including styling, etc. However...
+ * The showcase archetype has changed for simplicity.
+ * To keep compatibility, all [showcase content files][showcasefiles] have been edited to reflect the new content type. This will also be updated in the ["docs" page of the contribute section](/contribute/documentation/)

 ### Press & Articles

@@ -370,19 +370,24 @@ Apache License - 60

 ## Proposed Schedule for Hugo Docs Release

+If the Hugo Team finds the improvements to the Hugo documentation acceptable, I've proposed the following schedule for leveraging the new Hugo documentation.

-1. **2017-02-26** Release to Gitter Channel for Review
-2. **2017-03-01** Post in Discussion Forum for Feedback
-3. **2017-??-??** Add to Hugo repo for release with v19
-
-[^1]: As this point, the URL structure has changed considerably. I've been fastidious about adding aliases wherever possible, but I'm not sure what negative effect this approach is going to take with our current search relevancy. The [current list of aliases is quite large](/contribute/documentation/#be-mindful-of-aliases).
+1. **2017-02-26** Release to Gitter Channel for dev review
+2. **2017-03-05** Post in Discussion Forum for Hugo user feedback
+3. **2017-03-6** Pull request/add to Hugo Rep
+3. **2017-??-??** Add to Hugo repo for release with v19?

+[^1]: As this point, the URL structure has changed considerably. I've been fastidious about adding aliases wherever possible and trying to retain URLs for related content on the current site if applicable. That said, the [current list of aliases is quite large](/contribute/documentation/#be-mindful-of-aliases).

 [admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
 [designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
-[forum]: https://discuss.gohugo.io
 [ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
 [ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
+[forum]: https://discuss.gohugo.io
 [functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md
-[tagspage]: https://hugodocsconcept.netlify.com/tags/
-[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
+[hugothemes]: http://themes.gohugo.io
+[patch1]: http://gohugo.io/taxonomies/templates/
+[patch2]: https://github.com/spf13/hugo/commit/eaabecf586fd0375585e27c752e05dd8cb4c72b4
+[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
+[showcasefiles]:
+[tagspage]: https://hugodocsconcept.netlify.com/tags/
@@ -9,7 +9,7 @@ tags: [archetypes,generators,metadata,front matter]
 categories: ["content management"]
 weight: 70
 draft: false
-aliases: [/content/archetypes/,/content-management/content-archetypes/]
+aliases: [/content/archetypes/]
 toc: true
 notesforauthors:
 ---
@@ -16,23 +16,17 @@ notesforauthors:

 ## Markdown

-Markdown is the native content format for Hugo and is rendered using the excellent [Blackfriday project][], a blazingly fast parser written in Golang.
+Markdown is the native content format for Hugo and is rendered using the excellent [Blackfriday project][blackfriday], a blazingly fast parser written in Golang.

 {{% 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 to delimit nesting of lists in your content.
 {{% /note %}}

-## Additional Content Formats
+## Configuring Markdown Rendering

-Since 0.14, Hugo has defined a new concept called _external helpers_. This means you can write your content using [Asciidoc][], [reStructuredText][], or [Org-mode][]. If you have files with associated extensions, Hugo will call external commands to generate the content ([see Hugo source code][]). The exception is Org-mode, which is parsed natively.
+You can configure multiple aspects of Blackfriday. For more information, see [how to configure your Hugo projects][config]:

-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.
-
-To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files.
-
-{{% note "Performance of External Helpers" %}}
-Because these are external commands, generation performance for your preferred content format will heavily depend on the performance of the external tool used. As this feature is still in its infancy, feedback is especially welcome.
-{{% /note %}}
+{{< bfconfig >}}

 ## Extending Markdown

@@ -40,26 +34,24 @@ Hugo provides some convenient methods for extending markdown.

 ### Task Lists

-Hugo supports GitHub styled task lists (TODO lists) for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in the See [Blackfriday config](/overview/configuration/#configure-blackfriday-rendering) for how to turn it off.
+Hugo supports GitHub-styled task lists (i.e., TODO lists) for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration.

-#### Task List
+#### Example Task List Input

+{{% code file="content/my-to-do-list.md" %}}
 ```markdown
 - [ ] a task list item
 - [ ] list syntax required
 - [ ] incomplete
 - [x] completed
 ```
+{{% /code %}}

-Renders as:
+#### Example Task List Output

- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
-
-And produces this HTML:
+The preceding markdown produces the following HTML in your rendered website:

+{{% output file="my-to-do-list.html" %}}
 ```html
 <ul class="task-list">
    <li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
@@ -68,29 +60,61 @@ And produces this HTML:
    <li><input type="checkbox" checked="" disabled="" class="task-list-item"> completed</li>
 </ul>
 ```
+{{% /output %}}
+
+#### 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

 ### Shortcodes

-If you write in markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in [shortcodes][] functionality to act as the intermediary between your content and templating.
+If you write in markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality to act as the intermediary between your content and templating. This is one of the most powerful features in Hugo and allows you to essentially 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][] to render syntax highlighting via [Pygments][]. For usage examples and a complete explanation, see the [syntax highlighting documentation][] in [developer tools][].
+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][].

 ## Markdown Learning Resources

-* [Markdown Tutorial][]
-* [Daring Fireball: Markdown, John Gruber][]
+If you are unfamiliar with markdown syntax, it can easily be learned within a single sitting. The following are excellent resources to get you up and running:

-[`highlight` nested shortcode]: /content-management/shortcodes/#highlight
-[AsciiDoc]: http://asciidoc.org/
-[Blackfriday project]: https://github.com/russross/blackfriday
-[Daring Fireball: Markdown, John Gruber]: https://daringfireball.net/projects/markdown/
+* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball]
+* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet]
+* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial]
+
+## Additional Content Formats
+
+Since 0.14, Hugo has defined a new concept called _external helpers_. This means you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [Org-mode][org]. 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]). The exception is Org-mode, which is parsed natively.
+
+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 format are external commands---with the exception of org mode---generation performance will rely heavily on the performance of the external tool used. As this feature is still in its infancy, feedback is especially welcome.
+{{% /warning %}}
+
+[ascii]: http://asciidoc.org/
+[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering
+[blackfriday]: https://github.com/russross/blackfriday
+[config]: /getting-started/configuration/
 [developer tools]: /developer-tools/
-[Markdown Tutorial]: http://www.markdowntutorial.com/
-[Org-mode]: http://orgmode.org/
+[fireball]: https://daringfireball.net/projects/markdown/
+[helperssource]: https://github.com/spf13/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
+[hl]: /developer-tools/syntax-highlighting/
+[hlsc]: /content-management/shortcodes/#highlight
+[hugocss]: /css/style.min.css
+[mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
+[mdtutorial]: http://www.markdowntutorial.com/
+[org]: http://orgmode.org/
 [Pygments]: http://pygments.org/
-[reStructuredText]: http://docutils.sourceforge.net/rst.html
-[see Hugo source code]: https://github.com/spf13/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
-[shortcodes]: /content-management/shortcodes/
-[syntax highlighting documentation]: /developer-tools/syntax-highlighting/
+[rest]: http://docutils.sourceforge.net/rst.html
+[sc]: /content-management/shortcodes/
+[sct]: /templates/shortcode-templates/
@@ -1,12 +1,12 @@
 ---
 title: Multilingual Mode
-linktitle:
+linktitle: Multilingual and i18n
 description: As of v0.17, Hugo supports the creation of websites with multiple languages side by side.
 date: 2017-01-10
 publishdate: 2017-01-10
 lastmod: 2017-01-10
 categories: [content management]
-tags: [multilingual,i18n]
+tags: [multilingual,i18n, internationalization]
 weight: 150
 draft: false
 aliases: [/content/multilingual/,/content-management/multilingual/]
@@ -16,9 +16,12 @@ needsreview: true

 Hugo supports multiple languages side-by-side (added in `Hugo 0.17`). Define the available languages in a `Languages` section in your top-level `config.toml` (or equivalent).

-Example:
+## Configuring Multilingual Mode

-```
+The following is an example of a TOML site configuration for a multilingual Hugo project:
+
+{{% code file="config.toml" download="config.toml" %}}
+```toml
 DefaultContentLanguage = "en"
 copyright = "Everything is mine"

@@ -40,21 +43,23 @@ weight = 2
 linkedin = "lien-francais"
 [Languages.fr.navigation]
 help  = "Aide"
-
 ```
+{{% /code %}}

 Anything not defined in a `[Languages]` block will fall back to the global
 value for that key (e.g., `copyright` for the English [`en`] language).

-With the config above, all content, sitemap, RSS feeds, paginations,
-and taxonomy pages will be rendered below `/` in English (your default content language), and below `/fr` in French.
+With the configuration above, all content, sitemap, RSS feeds, paginations,
+and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.

-When working with params in front matter pages, omit the `params` in the key for the translation.
+When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.

-If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true` in your configuration.
+If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`.

 Only the obvious non-global options can be overridden per language. Examples of global options are `BaseURL`, `BuildDrafts`, etc.

+## Taxonomies and Blackfriday
+
 Taxonomies and [Blackfriday configuration][hugoconfig] can also be set per language:

 ```toml
@@ -119,15 +124,15 @@ To create a list of links to translated content, use a template similar to this:
 ```
 {{% /code %}}

-The above can be put in a `partial` (`./layouts/partials/`) and included in any template, be it for a [content page][contenttemplate] or the [home page][homepagetemplte]. It will not print anything if there are no translations for a given page, or if it is---in the case of the home page, section listing, etc.---a site with only one language.
+The above can be put in a `partial` (`./layouts/partials/`) and included in any template, be it for a [content page][contenttemplate] or the [homepage][]]. It will not print anything if there are no translations for a given page, or if there is---in the case of the homepage, section listing, etc.---a site with only one language.

-The above also uses the `i18n` func described in the next section.
+The above also uses the [`i18n` function][i18func] described in the next section.

 ## Translation of Strings

 Hugo uses [go-i18n](https://github.com/nicksnyder/go-i18n) to support string translations. [See the project's source repository](https://github.com/nicksnyder/go-i18n) to find tools that will help you manage your translation workflows.

-Translations are collected from the `themes/[name]/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project.  In the `i18n`, the translations will be merged and take precedence over what is in the theme folder.  Language files should be named according to RFC 5646  with names such as `en-US.yaml`, `fr.yaml`, etc.
+Translations are collected from the `themes/<THEME>/i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.yaml`, `fr.yaml`, etc.

 From within your templates, use the `i18n` function like this:

@@ -229,11 +234,18 @@ Hugo will generate your website with these placeholders. It might not be suited

 To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must

-* come from the built-in `.Permalink` or `.URL`
-* be constructed with `relLangURL` or `absLangURL` template funcs **or** prefixed with `{{.LanguagePrefix }}`
+* Come from the built-in `.Permalink` or `.URL`
+* Be constructed with
+    * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] template functions **OR**
+    * Prefixed with `{{.LanguagePrefix }}`

 If there is more than one language defined, the`LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites.

+[abslangurl]: /functions/abslangurl
 [contenttemplate]: /templates/single-page-template/
-[homepagetemplate]: /templates/homepage-template/
-[hugoconfig]: /getting-started/configuration/
+[homepage]: /templates/homepage-template/
+[hugoconfig]: /getting-started/configuration/
+[i18func]: /functions/i18n/
+[RFC 5646]: https://tools.ietf.org/html/rfc5646
+[singles]: /templates/single-page-templates/
+[rellangurl]: /functions/rellangurl
@@ -5,8 +5,8 @@ description: Hugo assumes that the same structure that works to organize your so
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-categories: [project organization]
-tags: [sections,content,organization, fundamentals]
+categories: [content management]
+tags: [sections,content,organization,fundamentals]
 weight: 10
 draft: false
 aliases: [/content-management/sections,/content/sections/]
@@ -16,9 +16,9 @@ needsreview: true

 ## Introduction

-Hugo uses files (see [Supported Content Formats][]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][].
+Hugo uses files (see [Hugo's supported content formats][formats]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][urls].

-## Organizing Source Content
+## Organizing Content Source

 In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/<directories>*``) is special in Hugo and is considered the content [section][].

@@ -121,29 +121,37 @@ http://spf13.com/projects/hugo
 http://spf13.com/extras/indexes/example
 ```

-**section** = which type the content is by default
+#### `section`

-* based on content location
+A section is the content type the piece of content is assigned to by default. `section` is determined by the following:
+
+* content location within the project's directory structure
 * front matter overrides

-**slug** = name.ext or name/
+#### `slug`

-* based on `content-name.md`
+A content's `slug` is either `name.extension` or `name/`. `slug` is determined by the following:
+
+* the name of the content file (e.g., `content-name.md`)
 * front matter overrides

-**path** = section  path to file, excluding slug
+## `path`

-* based on path to content location
+A content's `path` is determined by the section's path to the file. `path`

+* is based on the path to the content's location
+* excludes the slug

-**url** = relative URL
+## `url`

-* defined in front matter
+The `url` is the relative URL for the piece of content. The `url`
+
+* is defined in front matter
 * overrides all the above

-## \_index.md and 'Everything is a Page'
+## \_index.md and "Everything is a Page"

-As of version v0.18 Hugo now treats '[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)'. This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomies][taxonomytemplates], [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Homepage](/templates/homepage/).
+As of version v0.18, Hugo now treats "[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)". This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomy list pages][taxonomytemplates], [taxonomy terms pages](/templates/terms/) and even to potential "special case" pages like the [homepage][].

 In order to take advantage of this behaviour you need to do a few things.

@@ -173,7 +181,7 @@ Now that you've got a handle on templates lets recap some Hugo basics to underst

 Let's put all this information together:

-> **\_index.md files used in List pages, Terms pages or the Homepage are NOT rendered as single pages or with Single Content templates.**
+* `_index.md` file are used in List pages, terms pages or the homepage and are NOT rendered as single pages or with [single page templates][singles].

 > **All pages, including List pages, can have front matter and front matter can have markdown content - meaning \_index.md files are the way to _provide_ front matter and content to the respective List/Terms/Homepage.**

@@ -251,6 +259,8 @@ An `_index.md` file has also been added in the top level 'content' directory.
 Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the homepage.

 [front matter]: /content-management/front-matter/
+[homepage]: /templates/homepage-template/
 [section]: /content-management/section/
-[supported content formats]: /content-management/formats/
-[URL management]: /content-management/urls/
+[formats]: /content-management/formats/
+[singles]: /templates/single-page-templates/
+[urls]: /content-management/urls/
@@ -146,8 +146,8 @@ This shortcode will convert the source code provided into syntax-highlighted HTM

 #### Example `highlight` Input

-{{% code file="highlight-shortcode.md" %}}
-```golang
+{{% code file="content/tutorials/learn-html.md" %}}
+```html
 {{</* highlight html */>}}
 <section id="main">
  <div>
@@ -163,7 +163,9 @@ This shortcode will convert the source code provided into syntax-highlighted HTM

 #### Example `highlight` Output

-{{% output file="syntax-highlighted.html" %}}
+The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+
+{{% output file="tutorials/learn-html/index.html" %}}
 ```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>
@@ -176,8 +178,8 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
 ```
 {{% /output %}}

-{{% note "Syntax Highlighting" %}}
-For more information on your options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting](/developer-tools/syntax-highlighting/).
+{{% note "More on Syntax Highlighting" %}}
+To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting](/developer-tools/syntax-highlighting/) in Developer Tools.
 {{% /note %}}

 ### `instagram`
@@ -145,7 +145,7 @@ taxonomies:

 By default, taxonomy names are hyphenated, lower-cased, normalized, and then fixed and title-ized within.

-However, if you want to have a taxonomy value with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, you need to set the value for `preserveTaxonomyNames` in your [site configuration][] to `true`. Hugo will then preserve special characters in taxonomy values but will still titleize the values for titles and normalize them in URLs.
+Therefore, if you want to have a taxonomy value with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, you need to set the value for `preserveTaxonomyNames` in your [site configuration][] to `true`. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs.

 Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][].

@@ -18,26 +18,28 @@ notesforauthors:

 ## Introduction

-Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][], and we need your help to make Hugo even more awesome.
+Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome.

 ## Assumptions

+This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
+
 * You are new to Git or open-source projects in general
 * You are a fan of Hugo and enthusiastic about contributing to the project

-This contribution guide takes a step-by-step approach in hopes of helping newcomers.
-
 {{% note "Additional Questions?" %}}
-If you're struggling at any point in this contribution guide, reach out to Hugo community in [Hugo's Discussion forum](https://discuss.gohugo.io).
+If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discuss.gohugo.io).
 {{% /note %}}

-### Installing Golang
+## Installing Golang

 The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.

-## Installing Go From Source
+If you are having trouble following the installation guides for go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].

-[Download the latest stable version of Go][downloadgo] and follow the official [Golang installation guide][installgo].
+### Installing Go From Source
+
+[Download the latest stable version of Go][godl] and follow the official [Golang installation guide][goinstall].

 Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:

@@ -61,9 +63,15 @@ You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty strin

 ### Installing Go with Homebrew

+If you are a Mac OSX user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:

+{{% code file="install-go.sh" %}}
+```bash
+brew install go
+```
+{{% /code %}}

-### Install Go GVM
+### Install Go via GVM

 More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.

@@ -89,7 +97,7 @@ Finally, check again with `git version` if Git was installed successfully.

 There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Thus, so we will use the command line since the commands are everywhere the same.

-### Install Hub on Your System (optional)
+### Install Hub on Your System (Optional)

 Hub is a great tool for working with GitHub. The main site for it is [www.hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.

@@ -112,7 +120,6 @@ git version 2.6.3
 hub version 2.2.2
 ```

-
 ## Set up your working copy

 The working copy is set up locally on your computer. It's what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.
@@ -207,11 +214,13 @@ git checkout -b <BRANCH-NAME>

 You can check on which branch your are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.

-### Contributing to the documentation
+### Contributing to Documentation

-Perhaps you want to start contributing to the docs. Then you can ignore most of the following steps. You can find the documentation within the cloned repository in the subfolder `docs`. Change the directory with `cd docs`. [Install the latest release][releases]. Or read on and build Hugo from source.
+Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.

-You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page if you change its content.
+You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content.
+
+We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.

 ### Building Hugo

@@ -368,26 +377,33 @@ We use the [Travis CI loop](https://travis-ci.org/spf13/hugo) (Linux and OS&nbsp

 Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems.

-If you have questions leave a comment in the pull request. We are willing to assist you.
+If you have questions, leave a comment in the pull request. We are willing to assist you.

 ## Where to start?

-Thank you for reading this tutorial. Hopefully, we see you again on GitHub. There are plenty of [open issues](https://github.com/spf13/hugo/issues) on GitHub. Feel free to open an issue if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
+Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.

-## Additional References for Learning Git
+Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
+
+## Additional References for Learning Git and Golang

 * [Codecademy's Free "Learn Git" Course][codecademy] (Free)
 * [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
 * [The Git Book][gitbook] (Free)
+* [Go Bootcamp][gobootcamp]


 [codecademy]: https://www.codecademy.com/learn/learn-git
 [contributors]: https://github.com/spf13/hugo/graphs/contributors
-[downloadgo]: https://golang.org/dl/
+[docscontrib]: /contribute/documentation/
+[forums]: https://discuss.gohugo.io
 [gitbook]: https://git-scm.com/
+[gobootcamp]: http://www.golangbootcamp.com/book/get_setup
+[godl]: https://golang.org/dl/
+[goinstall]: https://golang.org/doc/install
 [gvm]: https://github.com/moovweb/gvm
-[installgo]: https://golang.org/doc/install
+[issues]: https://github.com/spf13/hugo/issues
+[newissue]: https://github.com/spf13/hugo/issues/new
 [releases]: /getting-started/
 [setupgopath]: https://golang.org/doc/code.html#Workspaces
-[open issues]: https://github.com/spf13/hugo/issues
 [trygit]: https://try.github.io/levels/1/challenges/1
@@ -6,38 +6,46 @@ date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
 categories: [contribute to hugo]
-tags: [docs,documentation,community]
+tags: [docs,documentation,community, contribute]
 weight: 20
 draft: false
-slug:
-aliases: [/docs-contribute/,/docscontrib/]
+aliases: [/contribute/docs/]
 toc: true
 needsreview: true
 ---

-Documentation is a critical component of any open-source project. The Hugo docs were completely reworked in anticipation of the release of v0.19, but there is always room for improvement.
+Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.19, but there is always room for improvement.

 ## Create Your Fork

-First, make sure that you created a [fork](https://help.github.com/articles/fork-a-repo/) of Hugo on Github and cloned the fork locally on your computer. Next, create a separate branch for your additions. Note that you can choose a different descriptive branch name that best fits the type of content you're trying to submit:
+It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of Hugo on GitHub and cloned the repository locally on your computer. For more information, you can use the [GitHub docs for "forking"][ghforking] or see [Hugo's extensive development contribution guide][hugodev].
+
+You can then create a separate branch for your additions. Note that you can choose a different descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:

 ```git
-git checkout -b showcase-addition
+git checkout -b jon-doe-showcase-addition
 ```

-## Adding a New Content Page
+## Adding New Content

-The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetype][] feature to easily scaffold new instances of content types. All [content sections][] in Hugo documentation have an assigned archetypes ([see source][archsource]).
+The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetypes][] feature to easily scaffold new instances of content types. All content sections in Hugo documentation have an assigned archetype ([see the Hugo docs archetype source][archsource]).

+Adding new content follows the same pattern, regardless of the content section:
+
+```
+hugo new <docssection>/<newcontent-all-lowercase.md>
+```
+
+{{% note "`title:`, `date:`, and Field Order" %}}
+`title` and `date` fields are added automatically when using archetypes via `hugo new`. Do not be worried if the order of the new file's front matter fields on your local machine is different than that of the following examples. This is a [known issue (#452)](https://github.com/spf13/hugo/issues/452).
+{{% /note %}}

 ### Adding a New Function

-### Adding a New Tutorial
-
-Once you have cloned the Hugo repository, you can create a new function via the following command. For functions, title the new function in lowercase.
+Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase.

 ```
-hugo new tutorials/newfunction.md
+hugo new functions/newfunction.md
 ```

 The archetype for the `functions` content type is as follows:
@@ -48,13 +56,16 @@ The archetype for the `functions` content type is as follows:
 ```
 {{% /code %}}

+#### Function Required Fields

-### Adding a New Showcase

-Once you have cloned the Hugo repository, you can create add your site as a new showcase content file via the following command. Name the markdown file accordingly:
+
+### Adding to the Showcase
+
+Once you have cloned the Hugo repository, you can add your Hugo website as a new showcase content file via the following command. Name the markdown file accordingly:

 ```
-hugo new tutorials/my-showcase-addition.md
+hugo new tutorials/my-hugo-showcase-website.md
 ```

 The archetype for the `showcase` content type is as follows:
@@ -65,7 +76,21 @@ The archetype for the `showcase` content type is as follows:
 ```
 {{% /code %}}

-Add at least values for `sitelink`, `title`,  `description`, and a path for `image`.
+#### Showcase Required Fields
+
+`sitelink`
+: the *full* URL to your website
+
+`title`
+: the `<title>`` of your website
+
+`description`
+: a general description of your website, preferably < 180 characters.
+
+`image`
+: the image (filename only) you want to associate with your website on the Showcase page. The image should be 600px x 400px.
+
+We also appreciate the addition of the remaining fields, specially `sourcelink` and `license` if you are willing to share your hard work with the open-source community. `tags` is optional, but we recommend adding at least 2 to 3 tags to improve discoverability.

 #### Add an Image for the Showcase

@@ -91,11 +116,11 @@ The archetype for the `tutorials` content type is as follows:
 ```
 {{% /code %}}

-## Adding Code Blocks to Hugo Docs
+## Adding Code Blocks

 Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.

-### Standard Code Block Syntax
+### Standard Syntax

 Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard Github-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) that's been modified for specific Hugo keywords.

@@ -112,12 +137,12 @@ Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd
 The Hugo documentation comes with very robust shortcodes to help you add interactive code snippets.

 {{% note %}}
-With both the `code` and the `output` shortcodes, *you still need to include the triple back ticks and language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the docs. We assume that the triple-back-tick syntax will live longer than the shortcode.
+With both `code` and `output` shortcodes, *you must include triple back ticks and language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs. We assume that the triple-back-tick syntax will live longer than our current, pretty shortcode. {{< emo ":smile:" >}}
 {{% /note %}}

-#### Input Code Block
+#### `code`

-The first shortcode is the one you'll use most often, `code`. `code`, like all code block shortcodes, requires at least a single `file` named parameter. Here is the signature:
+`code` is the code block shortcode you'll use most often. `code` requires at least a single `file` named parameter. Here is the signature:

 ````golang
 {{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
@@ -127,15 +152,23 @@ A whole bunch of coding going on up in here! Boo-yah!
 {{%/* /code */%}}
 ````

-Let's go through each of the three arguments passed into `code`:
+These are the arguments passed into `code`

-1. `file`. This is the only ***required*** argument for this shortcode. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top bar of the text-editor design you've seen throughout the docs. Note that you always want to end the file with an extension, but never use more than a single period in the filename. For example, instead of `./archetypes/default`, use `archetypes/default.md`. The file extension is important for displaying the correct icon.
-2. `download`. If omitted entirely, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
-3. `copy`. All `code` instances add a copy button to the bottom right automatically. However, there are times where you may not want to encourage your end user to copy a code block but still want to keep consistent styling for the filename (e.g., if you adding a "Do not do" code in a tutorial). If you want to turn off the copy functionality of `code`, you can add `copy="false"`.
+`file`
+: the only ***required*** argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top bar of the text-editor. Always end the value with an extension. For example, instead of `./public/section/`, use `public/section/index.html`. The file extension is used to display the icon.

-##### Example of `Code`
+`download`
+: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.

-Here is an HTML code block we want to tell the user lives in the `layouts/_default` directory. We are going to also make the block downloadable because it works as a standalone file:
+`copy`
+: a copy button is added automatically to all `code` (i.e., default value  = `true`). If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), pass the `copy` argument as `copy="false"`.
+
+##### Example `code` Input
+
+Here is an HTML code block in a case where we want to show the user of the Hugo docs the following:
+
+1. This type of file *could* live in `layouts/_default`.
+2. This snippet is complete enough that it might be worth downloading as a standalone file.

 ````html
 {{%/* code file="layouts/_default/single.html" download="single.html" */%}}
@@ -161,6 +194,8 @@ Here is an HTML code block we want to tell the user lives in the `layouts/_defau
 {{%/* /code */%}}
 ````

+##### Example 'code' Display
+
 The output of this example will render to the Hugo docs as follows:

 {{% code file="layouts/_default/single.html" download="single.html" %}}
@@ -185,9 +220,11 @@ The output of this example will render to the Hugo docs as follows:
 ```
 {{% /code %}}

+Cool, right?
+
 #### Output Code Block

-The `output` shortcode is almost identical to the `code` shortcode but doesn't take any more arguments than the required `file`. The purpose is to demonstrate what the output, or *rendered*, HTML will look after Hugo builds its templates:
+The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:

 ````html
 {{%/* output file="post/my-first-post/index.html" */%}}
@@ -209,26 +246,43 @@ The preceding `output` example will render as follows to the Hugo docs:

 ## Blockquotes

-Blockquotes can be
+Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:

+```markdown
+> Without the fear of falling, there is no joy in flight.
+```
+
+The preceding blockquote will render as follows in the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight.
+
+However, you can add a quick and easy `<cite>` element (adding on the client via JavaScript) by separating your main blockquote and the citation with ` - `:
+
+```markdown
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/K%C5%8Db%C5%8D_Abe)
+```
+
+Which will render as follows on the Hugo docs:
+
+> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]

 {{% note "Blockquotes `!=` Admonitions" %}}
-Previous versions of the Hugo documentation used [Markdown `<blockquote>` syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes) to draw attention to content. This is [*not* the intended semantic use of the `<blockquote>` element](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting actual text. To note or warn your user of specific information, use the admonition shortcodes that follow.
+Previous versions of Hugo documentation used blockquotes to draw attention to text. [This is *not* the intended semantic use of the `<blockquote>` element](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
 {{% /note %}}

-## Admonition Short Codes
+## Admonitions

-**Admonitions** are common directives in technical documentation. The most popular is that seen in [reStructuredTex Directives][sourceforge]. From the SourceForge documentation:
+**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredTex Directives][sourceforge]. From the SourceForge documentation:

 > Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]

-Both `note` and `warning` use a single, *optional* argument for the admonition title, which accepts markdown syntax as well. If the title, a [positional parameter][shortcodeparams] in quotes is missing, the default behavior of the `note` and `warning` shortcodes will be to display the text "Note" and "Warning", respectively.
+Both `note` and `warning` use a single, *optional* argument for the admonition title, which accepts markdown syntax as well. If the title, a [positional parameter in quotes][shortcodeparams] is missing, the default behavior of the `note` and `warning` shortcodes will be to display "Note" and "Warning", respectively.

 ### Note Admonition Shortcode

 Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.

-#### `note` Admonition Shortcode Input
+#### Example `note` Input

 {{% code file="note-with-heading.md" %}}
 ```golang
@@ -238,7 +292,7 @@ Here is a piece of information I would like to draw your **attention** to.
 ```
 {{% /code %}}

-#### `note` Admonition Shortcode Output (Code)
+#### Example `note` Output

 {{% output file="note-with-heading.html" %}}
 ```html
@@ -248,7 +302,7 @@ Here is a piece of information I would like to draw your **attention** to.
 ```
 {{% /output %}}

-#### `note` Admonition Shortcode Display
+#### Example `note` Display

 {{% note "Example Note Admonition" %}}
 Here is a piece of information I would like to draw your **attention** to.
@@ -258,7 +312,7 @@ Here is a piece of information I would like to draw your **attention** to.

 Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for announcing breaking changes for Hugo versions, known bugs, or templating gotchas.

-#### `warning` Admonition Shortcode Input
+#### Example `warning` Input

 {{% code file="warning-admonition-input.md" %}}
 ```golang
@@ -268,7 +322,7 @@ This is a warning, which should be reserved for *important* information like bre
 ```
 {{% /code %}}

-#### `warning` Admonition Shortcode Output
+#### Example `warning` Output

 {{% output file="warning-admonition-output.html" %}}
 ```html
@@ -278,7 +332,7 @@ This is a warning, which should be reserved for *important* information like bre
 ```
 {{% /output %}}

-#### `warning` Admonition Shortcode Display
+#### Example `warning` Display

 {{% warning "Example Warning Admonition" %}}
 This is a warning, which should be reserved for *important* information like breaking changes.
@@ -301,35 +355,36 @@ The Hugo docs are not especially prescriptive in terms of grammar and usage. We
 1. *Front matter* is two words, *Homepage* is one word, *file system* is two words.
 3. Be sure to add a value to the `godocref` in content files whenever possible. We want to promote Hugo *and* Golang by demonstrating the inseparable wedding of the two.

-## Ask the Community for Code Examples
+## Ask for Code Examples

-Sometimes you want to contribute to the docs but don't have enough time to provide lengthy examples. If you want to flag a piece of content you feel needs more examples to be better understood by Hugo users, you can add the following field to a content file's front matter:
+Sometimes you want to contribute to the docs but don't have enough time to provide lengthy examples. If you want to flag a piece of content as needing more examples, add the following field to your front matter:

 ```
 needsexamples: true
 ```

-## Hugo Docs Examples Needed, Please Help!
+## Please Help! Examples Needed!

-The preceding `needsexamples` field generates the following list of files that we feel could benefit from some community-driven examples. The edit link will take you directly to the edit URL for the file if you're more comfortable making small changes in the GitHub interface rather than in your local text editor.
+The preceding `needsexamples` is used to generate the following table. The edit link will take you directly to the edit URL for the file in GitHub:

 {{< needsexamples >}}

 {{% note "Pull Requests and Branches" %}}
-Similar to [contributing to Hugo development](/contribute/contribute-to-hugo-development), the Hugo team expects you to create a separate branch/fork for your generous contributions to Hugo.
+Similar to [contributing to Hugo development](/contribute/contribute-to-hugo-development), the Hugo team expects you to create a separate branch/fork when you make your generous contributions to the Hugo docs.
 {{% /note %}}

-## Ordering Content in the Hugo Docs
-
-If you're contributing to the Hugo docs, do not worry about weight and ordering, especially in the case of a new content file. All Hugo doc sections have been ordered specifically to keep the docs website scalable and easy to use.
-
 ## Be Mindful of Aliases

-Use aliases sparingly. The following table shows a list of all the aliases currently being used in the Hugo Docs. If you need to use an alias in your new content file's front matter, be sure to check here first to prevent conflicts.
+Use aliases sparingly. The following table shows a list of all the aliases currently being used in the Hugo Docs. Check here first for potential conflicts if you need to use an alias:

 {{< allaliases >}}

+[abe]: https://en.wikipedia.org/wiki/K%C5%8Db%C5%8D_Abe
+[archetypes]: /content-management/archetypes/
 [archsource]: https://github.com/spf13/hugo/tree/master/docs/archetypes
-[archetype]: /content-management/archetypes/
+[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
+[charcount]: http://www.lettercount.com/
+[ghforking]: https://help.github.com/articles/fork-a-repo/
+[hugodev]: /contribute/development/
 [shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
 [sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
@@ -1,16 +1,20 @@
 ---
 title: Developer Tools
 linktitle: Overview
-description: Description for the developer tools section.
-date: 2016-11-01
-publishdate: 2016-11-01
-lastmod: 2016-11-01
+description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers.
+date: 2016-12-05
+publishdate: 2016-12-05
+lastmod: 2017-02-26
+categories: [developer tools]
 tags: []
-categories: []
 weight: 01
 draft: false
-slug:
-aliases: []
-toc:
-notesforauthors:
---
+aliases: [/tools/]
+---
+
+One of Hugo's greatest strengths is it's passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from commercial services and open-source projects developed by Hugo developers just like you.
+
+[See the popularity of Hugo compared with other static site generators.][staticgen]
+
+[staticgen]: https://staticgen.com
+[syntax]: /developer-tools/syntax-highlighting/
@@ -0,0 +1,39 @@
+---
+title: Editor Plug-ins for Hugo
+linktitle: Editor Plug-ins
+description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [developer tools]
+tags: [editor, plug-ins]
+weight: 50
+draft: false
+aliases: []
+toc: false
+needsreview: true
+---
+
+The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow.
+
+## Sublime Text
+
+* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
+
+## Visual Studio Code
+
+* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy) - Hugofy is a plugin for Visual Studio Code to make life easier to use Hugo static site generator. The source code can be found [here](https://github.com/akmittal/hugofy-vscode).
+
+## Emacs
+
+* [hugo.el](https://github.com/yewton/hugo.el). Some helper functions for creating a Website with Hugo. Note that Hugo also supports [Org-mode][formats].
+
+## Vim
+
+* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo.
+
+## Atom
+
+* [Hugofy](https://atom.io/packages/hugofy) - A Hugo Static Website Generator package for Atom.
+
+[formats]: /content-management/formats/
@@ -0,0 +1,31 @@
+---
+title: Frontend Interfaces with Hugo
+linktitle: Frontends
+description: Do you (or your content authors) prefer a graphical user interface over a text editor? Give these frontends a try.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [developer tools]
+tags: [frontend,gui]
+weight: 40
+draft: false
+aliases: []
+toc: false
+---
+
+Do you prefer a graphical user interface over a text editor? Give these frontends a try:
+
+* [rango](https://github.com/stayradiated/rango). Rango is a web frontend for Hugo. It's designed to make it easy to manage a small site, even for people with little computer experience.
+* [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote!
+* [caddy-hugo](https://github.com/hacdias/caddy-hugo). `caddy-hugo` is an add-on for [Caddy](https://caddyserver.com/) that delivers a good UI to edit the content of your Hugo website.
+* [Hugopit](https://github.com/sjardim/Hugopit). Hugopit is a web-based editor for Hugo built on top of [Cockpit CMS](http://www.getcockpit.com/).
+* [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites.
+
+
+## Commercial Services
+
+* [Appernetic.io](https://appernetic.io) is a Hugo Static Site Generator as a Service that is easy to use for non-technical users.
+    * **Features:** inline PageDown editor, visual tree view, image upload and digital asset management with Cloudinary, site preview, continuous integration with GitHub, atomic deploy and hosting, Git and Hugo integration, autosave, custom domain, project syncing, theme cloning and management. Developers have complete control over the source code and can manage it with GitHub’s deceptively simple workflow.
+* [Netlify.com](https://www.netlify.com). Netlify builds, deploys, and hosts your static website or app (Hugo, Jekyll, etc). Netlify offers a drag-and-drop interface and automatic deployments from GitHub or Bitbucket.
+    * **Features:** global CDN, atomic deploys, ultra-fast DNS, instant cache invalidation, high availability, automated hosting, Git integration, form submission hooks, authentication providers, and custom domains. Developers have complete control over the source code and can manage it with GitHub or Bitbucket's deceptively simple workflow.
+* [Forestry.io](https://forestry.io/). Forestry is a simple CMS for Jekyll and Hugo websites with support for GitHub, GitLab, and Bitbucket. Every time an update is made via the CMS, Forestry will commit changes back to your repo and will compile/deploy your website to S3, GitHub Pages, FTP, etc.
@@ -0,0 +1,21 @@
+---
+title: Other Hugo Community Projects
+linktitle: Other Projects
+description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [developer tools]
+tags: [frontend,gui]
+weight: 70
+draft: false
+aliases: []
+toc: false
+---
+
+And for all the other small things around Hugo:
+
+* [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites.
+* [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo.
+* [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
+* [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe.
@@ -0,0 +1,24 @@
+---
+title: Adding Search to your Hugo Website
+linktitle: Search
+description: Search is not a built-in feature of Hugo, but you have plenty of options for adding search to your Hugo-generated website. See some of the open-source and commercial search options for your newly created website.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-26
+categories: [developer tools]
+tags: [search,tools]
+weight: 60
+draft: false
+aliases: []
+toc: true
+---
+
+A static website with a dynamic search function? Yes. As alternatives to embeddable scripts from Google or other search engines, you can provide your visitors a custom search by indexing your content files directly.
+
+* [Hugoidx](https://github.com/blevesearch/hugoidx) is an experimental application to create a search index. It's built on top of [Bleve](http://www.blevesearch.com/).
+* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results.
+* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project.
+
+## Commercial Search Services
+
+* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
@@ -12,12 +12,15 @@ aliases: [/developer-tools/migrations/,/developer-tools/migrated/]
 toc: false
 ---

-Know of a Hugo-related project that isn't mentioned here? [Please add it to the list.][addkit]
+Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to the list.][addkit]

-| Kit                               | Actively Maintained? |
-| --------------------------------- | -------------------- |
-| [Victor Hugo](https://github.com/netlify/victor-hugo) | Yes |
+{{% note "Starter Kits are Not Maintained by the Hugo Team"%}}
+The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s).
+{{% /note %}}

+* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Gulp + Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively.
+* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript.

-
-[addkit]: https://github.com/spf13/hugo/blob/master/docs/content/developer-tools/starter-kits.md
+[addkit]: https://github.com/spf13/hugo/edit/master/docs/content/developer-tools/starter-kits.md
+[Blaupause]: https://github.com/fspoettel/blaupause
+[Victor Hugo]: https://github.com/netlify/victor-hugo
@@ -11,7 +11,6 @@ weight: 20
 draft: false
 aliases: [/extras/highlighting/,/extras/highlight/]
 toc: true
-needsreview:
 ---

 Hugo provides the ability for you to 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.
@@ -2,13 +2,16 @@
 title: Functions Quick Reference
 linktitle: Quick Reference
 description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
+godocref: http://golang.org/pkg/text/template/#hdr-Functions
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
 tags: [functions,templating]
 weight: 01
 draft: false
-slug:
 aliases: [/layout/functions/]
 ---

+Go templates are lightweight but extensible. Go itself supplies built-in functions, including comparison operators and other basic tools. These are listed in the [Go template documentation][gofuncs]. Hugo has added the following functions to the basic template logic.
+
+[gofuncs]: http://golang.org/pkg/text/template/#hdr-Functions
@@ -1,7 +1,7 @@
 ---
 title: abslangurl and rellangurl
 linktitle: absLangURL and relLangURL
-description:
+description: Similar to absURL, but adds the absolute URL with correct language prefix according to site configuration for multilingual and baseURL.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -11,7 +11,7 @@ categories: [functions]
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [relLangURL]
 deprecated: false
 aliases: [/functions/absurl/,/functions/rellangurl/]
 needsexamples: true
@@ -0,0 +1,51 @@
+---
+title: absurl
+linktitle: absURL
+description: Given a string, prepends the full absolute URL according to position in file structure and the configured baseURL.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+tags: [urls]
+signature:
+workson: []
+hugoversion:
+relatedfuncs: [relURL]
+deprecated: false
+aliases: []
+---
+
+Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://yoursite.com/hugo/`:
+
+```golang
+{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
+{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
+{{ "http://gohugo.io/" | relURL }} →  "http://gohugo.io/"
+{{ "http://gohugo.io/" | absURL }} →  "http://gohugo.io/"
+```
+
+The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data (SEO)][jsonld], where some of your images for a piece of content may or may not be hosted locally:
+
+{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
+```html
+<script type="application/ld+json">
+{
+    "@context" : "http://schema.org",
+    "@type" : "BlogPosting",
+    "image" : {{ apply .Params.images "absURL" "." }}
+}
+</script>
+```
+{{% /code %}}
+
+The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
+
+{{% note "Ending Slash" %}}
+`absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
+{{% /note %}}
+
+[apply function]: /functions/apply/
+[configuration]: /getting-started/configuration/
+[jsonld]: https://developers.google.com/search/docs/guides/intro-structured-data
+[safejs]: /functions/safejs
@@ -1,23 +1,27 @@
 ---
 title: after
-linktitle:
-description:
+linktitle: after
+description: Slices an array to only the items after the Nth item.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [iteration]
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [last]
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`after` slices an array to only the items after the *N*th item. Combining `after` with `first` uses both use both halves of an array split at item *N*.

-## Advanced Example
+Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+
+e.g.
+
+    {{ range after 10 .Data.Pages }}
+        {{ .Render "title" }}
+    {{ end }}
@@ -15,13 +15,12 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: []
-needsreview: true
 ---

 Given a map, array, or slice, `apply` returns a new slice with a function applied over it. `apply` expects at least three parameters, depending on the function being applied.

 1. The first parameter is the sequence to operate on
-2. The second parameter is the name of the function as a string, which must be in the [Hugo function map][functions].
+2. The second parameter is the name of the function as a string, which must be the name of a valid [Hugo function][functions].
 3. After that, the parameters to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against.

 Here is an example of a content file with `name:` as a front matter field:
@@ -80,9 +79,9 @@ If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *
 ```
 {{% /code %}}

-This works, but the complexity of `post-tag-list.html` is fairly high: the Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.
+This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.

-This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading; the combined and DRYer version is shown next:
+This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading. The combined and DRYer version is shown next:

 ```html
 {{ with .Params.tags }}
@@ -96,7 +95,7 @@ This first version of `layouts/partials/post-tag-list.html` separates all of the
 {{ end }}
 ```

-Now in the complete version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp][] off stray newlines, and join the tags together in a delimited list for presentation. Here is a DRYer version of the preceding example:
+Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp][] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:

 {{% code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" %}}
 ```html
@@ -113,8 +112,8 @@ Now in the complete version, you can sort the tags, convert the tags to links wi
 `apply` does not work when receiving the sequence as an argument through a pipeline.
 {{% /note %}}

-[chome]: /functions/chomp/
-[delimit]: /functions/delimit/
-[functions]: /functions/
+[chomp]: /functions/chomp/ "See documentation for the chomp function"
+[delimit]: /functions/delimit/ "See documentation for the delimit function"
+[functions]: /functions/ "See the full list of Hugo functions to see what can be passed as an argument to the apply function."
 [partials]: /templates/partials/
-[range]: /functions/range/
+[range]: /functions/range/ "Learn the importance of the range function, a fundamental keyword in both Hugo templates and the Go programming language."
@@ -19,14 +19,14 @@ aliases: []

 `base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes. Let's take a look at an example:

-{{% code "base64-input.html" %}}
+{{% code file="base64-input.html" %}}
 ```html
 <p>Hello world = {{ "Hello world" | base64Encode }}</p>
 <p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
 ```
 {{% /code %}}

-{{% output "base-64-output.html" %}}
+{{% output file="base-64-output.html" %}}
 ```html
 <p>Hello world = SGVsbG8gd29ybGQ=</p>
 <p>SGVsbG8gd29ybGQ = Hello world</p>
@@ -1,21 +0,0 @@
---
-title: count
-linktitle: Count
-description:
-godocref:
-date: 2017-02-01
-publishdate: 2017-02-01
-lastmod: 2017-02-01
-tags: []
-categories: [functions]
-toc:
-signature:
-workson: []
-hugoversion:
-relatedfuncs: []
-deprecated: false
-draft: false
-aliases: []
---
-
-[Link to Taxonomy templates](/templates/taxonomy-templates/)
@@ -1,14 +1,13 @@
 ---
 title: echoparam
 linktitle: echoParam
-description:
+description: Prints a parameter if it is set.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
@@ -18,7 +17,8 @@ draft: false
 aliases: []
 ---

-## Example
-
-## Advanced Example
+`echoParam` prints a parameter if it is set.

+```
+{{ echoParam .Params "project_url" }}
+```
@@ -15,15 +15,15 @@ relatedfuncs: []
 deprecated: false
 ---

-Runs the string through the Emoji emoticons processor. The result will be declared as "safe" to prevent Go templates from filtering it.
+Runs the string through the Emoji emoticons processor. The result will be declared as "safe" to prevent Go templates from filtering it as unsafe HTML.

-See the [Emoji cheat sheet][emojis] for available emoticons. The `emojify` function can be called in your templates but not content.
+See the [Emoji cheat sheet][emojis] for available emoticons.

 ```
 {{ "I :heart: Hugo" | emojify }}
 ```

-However, emojis are most often seen inline. The following is a very simple [partial template][partials] you can use to add emojis directly to your content files. It is also the `emo` shortcode used for the Hugo docs.
+The `emojify` function can be called in your templates but not directly in your content files. However, emojis are most often seen inline. The following is a very simple [shortcode template][sc] you can use to add emojis quickly while you write content. It is also the `emo` shortcode used for the Hugo docs. ([See Hugo Docs Shortcodes Source][scsource].)

 {{% code file="layouts/shortcodes/emo.html" download="emo.html" %}}
 ```golang
@@ -39,9 +39,10 @@ I {{</* emo ":heart:" */>}} Hugo!
 ```
 {{% /code %}}

-The output of which is...
+The preceding use of the `emo` shortcode called in content will display as follows:

 I {{< emo ":heart:" >}} Hugo!

 [emojis]: http://www.emoji-cheat-sheet.com/
-[partials]: /templates/partials/
+[sc]: /templates/shortcode-templates/
+[scsource]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes
@@ -0,0 +1,23 @@
+---
+title: eq
+linktitle: eq
+description: Returns true if the parameters are equal.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+tags: [operators,logic]
+signature:
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
+`eq` returns true if the parameters are equal.
+
+```
+{{ if eq .Section "blog" }}current{{ end }}
+```
@@ -1,24 +1,60 @@
 ---
-title: findRe
-linktitle:
-description:
+title: findre
+linktitle: findRE
+description: Returns a list of strings that match the regular expression.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [regex]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+Returns a list of strings that match the regular expression. By default all matches will be included. The number of matches can be limitted with an optional third parameter.

-## Advanced Example
+The example below returns a list of all second level headers (`<h2>`) in the content:

+```
+{{ findRE "<h2.*?>(.|\n)*?</h2>" .Content }}
+```
+
+You can limit the number of matches in the list with a third parameter. The following example shows how to limit the returned value to just one match (or none, if there are no matched substrings):
+
+```golang
+{{ findRE "<h2.*?>(.|\n)*?</h2>" .Content 1 }}
+    <!-- returns ["<h2 id="#foo">Foo</h2>"] -->
+```
+
+## `findRE` Example: Building a Table of Contents
+
+`findRE` allows us to build an automatically generated table of contents that could be used for a simple scrollspy if you don't want to use [Hugo's native .TableOfContents feature][toc]. The following shows how this could be done in a [partial template][partials]:
+
+{{% code file="layouts/partials/toc.html" download="toc.html" %}}
+```html
+{{ $headers := findRE "<h2.*?>(.|\n)*?</h2>" .Content }}
+{{ if ge (len $headers) 1 }}
+    <ul>
+    {{ range $headers }}
+        <li>
+            <a href="#{{ . | plainify | urlize }}">
+                {{ . | plainify }}
+            </a>
+        </li>
+    {{ end }}
+    </ul>
+{{ end }}
+```
+{{% /code %}}
+
+The preceding snippet tries to find all second-level headers and generate a list where at least one header is found. [`plainify`][] strips the HTML and [`urlize`][] converts the header into a valid URL.
+
+[partials]: /templates/partials/
+[`plainify`]: /functions/plainify/
+[toc]: /content-management/toc/
+[`urlize`]: /functions/urlize
@@ -1,24 +1,26 @@
 ---
 title: first
 linktitle: first
-description:
+description: Slices an array to only the first Nth elements.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [iteration]
 signature:
-workson: []
+workson: [lists,taxonomies,terms,groups]
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [after,last]
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`first` slices an array to only the first _N_th elements.

-## Advanced Example
+```golang
+{{ range first 10 .Data.Pages }}
+    {{ .Render "summary" }}
+{{ end }}
+```

@@ -1,24 +1,28 @@
 ---
 title: getenv
-linktitle:
-description:
+linktitle: getenv
+description: Returns the value of an environment variable.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`getenv` returns the value of an environment variable.

-## Advanced Example
+Takes a string containing the name of the variable as input. Returns
+an empty string if the variable is not set, otherwise returns the
+value of the variable. Note that in Unix-like environments, the
+variable must also be exported in order to be seen by `hugo`.

+```
+{{ getenv "HOME" }}
+```
@@ -1,24 +1,21 @@
 ---
-title: hasPrefix
-linktitle:
-description:
+title: hasprefix
+linktitle: hasPrefix
+description: Tests whether a string begins with prefix.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
-
-## Advanced Example
+`hasPrefix` tests whether a string begins with prefix.

+* `{{ hasPrefix "Hugo" "Hu" }}` → true
@@ -1,24 +1,25 @@
 ---
 title: htmlEscape
 linktitle:
-description:
+description: Returns the given string with the critical reserved HTML codes escaped.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings, html]
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [htmlUnescape]
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`htmlEscape` returns the given string with the critical reserved HTML codes escaped, such that `&` becomes `&amp;` and so on. It escapes only: `<`, `>`, `&`, `'` and `"`.

-## Advanced Example
+Bear in mind that, unless content is passed to `safeHTML`, output strings are escaped usually by the processor anyway.

+```
+{{ htmlEscape "Hugo & Caddy > Wordpress & Apache" }} → "Hugo &amp; Caddy &gt; Wordpress &amp; Apache"
+```
@@ -1,24 +1,25 @@
 ---
 title: htmlUnescape
-linktitle:
-description:
+linktitle: htmlUnescape
+description: Returns the given string with HTML escape codes un-escaped.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [htmlEscape]
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`htmlUnescape` returns the given string with HTML escape codes un-escaped. This un-escapes more codes than `htmlEscape` escapes, including `#` codes and pre-UTF8 escapes for accented characters. It defers completely to the Go `html.UnescapeString` function, so functionality is consistent with that codebase.

-## Advanced Example
+Remember to pass the output of this to `safeHTML` if fully un-escaped characters are desired. Otherwise, the output will be escaped again as normal.

+```
+{{ htmlUnescape "Hugo &amp; Caddy &gt; Wordpress &amp; Apache" }} → "Hugo & Caddy > Wordpress & Apache"
+```
@@ -1,24 +1,28 @@
 ---
 title: humanize
 linktitle:
-description:
+description: Returns the humanized version of an argument with the first letter capitalized.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings,casing]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`humanize` returns the humanized version of an argument with the first letter capitalized. If the input is either an int64 value or the string representation of an integer, humanize returns the number with the proper ordinal appended.

-## Advanced Example
+
+```
+{{humanize "my-first-post"}} → "My first post"
+{{humanize "myCamelPost"}} → "My camel post"
+{{humanize "52"}} → "52nd"
+{{humanize 103}} → "103rd"
+```

@@ -26,4 +26,6 @@ This translates a piece of content based on your `i18n/en-US.yaml` (and friends)
 `T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`.
 {{% /note %}}

-For more information about string translations, see [Translation of strings](/content-management/multilingual/#translation-of-strings).
+For more information about string translations, see [Translation of Strings in Multilingual Mode][multistrings].
+
+[multistrings]: /content-management/multilingual/#translation-of-strings
@@ -1,24 +1,30 @@
 ---
 title: in
 linktitle:
-description:
+description: Checks if an element is in an array or slice--or a substring in a string---and returns a boolean.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`in` checks if an element is in an array (or slice) and returns a corresponding boolean value. The elements supported are strings, integers and floats, although only float64 will match as expected.

-## Advanced Example
+In addition, `in` can also check if a substring exists in a string.

+```
+{{ if in .Params.tags "Git" }}Follow me on GitHub!{{ end }}
+```
+
+
+```
+{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}
+```
@@ -1,24 +1,42 @@
 ---
 title: intersect
 linktitle: intersect
-description:
+description: Returns the common elements of two arrays or slices.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+Given two arrays (or slices), `intersect` returns the common elements. The elements supported are strings, integers and floats (only float64).

-## Advanced Example
+A useful example of `intersect` functionality is a "related posts" block. `isset` allows us to create a list of links to other posts that have tags that intersect with the tags in the current post.

+The following is an example of a "related posts" [partial template][partials] that could be added to a [single page template][single]:
+
+{{% code file="layouts/partials/related-posts.html" download="related-posts.html" %}}
+```html
+<ul>
+{{ $page_link := .Permalink }}
+{{ $tags := .Params.tags }}
+{{ range .Site.Pages }}
+    {{ $page := . }}
+    {{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }}
+    {{ if and $has_common_tags (ne $page_link $page.Permalink) }}
+        <li><a href="{{ $page.Permalink }}">{{ $page.Title }}</a></li>
+    {{ end }}
+{{ end }}
+</ul>
+```
+{{% /code %}}
+
+[partials]: /templates/partials/
+[single]: /templates/single-page-template/
@@ -1,24 +1,25 @@
 ---
 title: isset
 linktitle: isset
-description:
+description: Returns true if the parameter is set.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`isset` returns true if the parameter is set.
+Takes either a slice, array or channel and an index or a map and a key as input.

-## Advanced Example
+```
+{{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}
+```

@@ -1,24 +1,24 @@
 ---
 title: jsonify
-linktitle:
-description:
+linktitle: jsonify
+description: Encodes a given object to JSON.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`jsonify` encodes a given object to JSON.

-## Advanced Example
+```
+{{ dict "title" .Title "content" .Plain | jsonify }}
+```

@@ -1,7 +1,7 @@
 ---
 title: last
 linktitle: last
-description:
+description: Slices an array to only the last Nth elements.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -18,7 +18,13 @@ draft: false
 aliases: []
 ---

-## Example
+`last` slices an array to only the last _N_th elements.

-## Advanced Example
+Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
+
+```
+{{ range last 10 .Data.Pages }}
+    {{ .Render "summary" }}
+{{ end }}
+```

@@ -1,23 +1,23 @@
 ---
 title: lower
 linktitle: lower
-description:
+description: Converts all characters in the provided string to lowercase.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings,casing]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`lower` converts all characters in the provided string to lowercase.

-## Advanced Example
+```
+{{lower "BatMan"}} → "batman"
+```
@@ -1,24 +1,23 @@
 ---
 title: markdownify
 linktitle: markdownify
-description:
+description: Runs the provided string through the Markdown processor.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
 tags: [markdown,content]
 categories: [functions]
-toc:
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
-
-## Advanced Example
+`markdownify` runs the provided string through the Markdown processor. The result will be declared as "safe" so Go/html templates do not filter it.

+```
+{{ .Title | markdownify }}
+```
@@ -1,23 +1,23 @@
 ---
 title: plainify
-linktitle:
-description:
+linktitle: plainify
+description: Strips any HTML and returns the plain text version of the provided string.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`plainify` strips any HTML and returns the plain text version of the provided string.

-## Advanced Example
+```
+{{ "<b>BatMan</b>" | plainify }} → "BatMan"
+```
@@ -1,24 +1,24 @@
 ---
 title: pluralize
-linktitle:
-description:
+linktitle: pluralize
+description: Pluralizes the given word according to a set of common English pluralization rules
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`pluralize` will pluralize the given word according to a set of common English pluralization rules.

-## Advanced Example
+```
+{{ "cat" | pluralize }} → "cats"
+```

@@ -0,0 +1,29 @@
+---
+title: rellangurl
+linktitle: relLangURL
+description: Similar to relURL, but adds the relative URL with correct language prefix according to site configuration for multilingual.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+tags: [multilingual,i18n,urls]
+categories: [functions]
+signature:
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: [/functions/absurl/,/functions/rellangurl/]
+needsexamples: true
+---
+
+`absLangURL` and `relLangURL` functions are similar to their `absURL` and `relURL` relatives but will add the correct language prefix when the site is configured with more than one language. (See [Configuring Multilingual][multiliconfig])
+
+So for a site  `baseURL` set to `http://yoursite.com/hugo/` and the current language is `en`:
+
+```golang
+{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
+{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
+```
+
+[multiliconfig]: /content-management/multilingual/#configuring-multilingual-mode
@@ -1,21 +1,19 @@
 ---
-title: absurl and relurl
-linktitle: absURL and relURL
-description:
+title: relurl
+linktitle: relURL
+description: Given a string, prepends the relative URL according to a page's position in the project directory structure.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: [urls]
 categories: [functions]
-toc:
+tags: [urls]
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [absURL]
 deprecated: false
-draft: false
-aliases: [/functions/relurl/]
+aliases: []
 ---

 Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://yoursite.com/hugo/`:
@@ -41,7 +39,7 @@ The last two examples may look strange but can be very useful. For example, the
 ```
 {{% /code %}}

-The above uses the [apply function][] and also exploits the fact that the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
+The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.

 {{% note "Ending Slash" %}}
 `absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
@@ -1,24 +1,24 @@
 ---
 title: replace
-linktitle:
-description:
+linktitle: replace
+description: Replaces all occurrences of the search string with the replacement string.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`replace` replaces all occurrences of the search string with the replacement string:

-## Advanced Example
+```
+`{{ replace "Batman and Robin" "Robin" "Catwoman" }}` → "Batman and Catwoman"
+```

@@ -0,0 +1,24 @@
+---
+title: replacere
+linktitle: replaceRE
+description: Replaces all occurrences of a regular expression with the replacement pattern.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [functions]
+tags: [regex]
+signature:
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+aliases: []
+---
+
+Replaces all occurrences of a regular expression with the replacement pattern.
+
+```golang
+{{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io"
+{{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io"
+```
@@ -1,24 +1,36 @@
 ---
-title: safeCSS
-linktitle:
-description:
-godocref:
+title: safecss
+linktitle: safeCSS
+description: Declares the provided string as a known "safe" CSS string.
+godocref: https://golang.org/src/html/template/content.go?s=919:929#L15
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
-tags: [style,css,strings]
+lastmod: 2017-02-26
 categories: [functions]
-toc:
+tags: [style,css,strings]
 signature:
 workson: []
 hugoversion:
-relatedfuncs: []
+relatedfuncs: [safeHTML,safeHTMLAttr,]
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`safeCSS` declares the provided string as a known "safe" CSS string so that Go html/templates will not filter it as unsafe.

-## Advanced Example
+In this context, *safe* means CSS content that matches any of the following:
+
+1. The CSS3 stylesheet production, such as `p { color: purple }`.
+2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+3. CSS3 declaration productions, such as `color: red; margin: 2px`.
+4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+
+Example: Given `style = "color: red;"` defined in the front matter of your `.md` file:
+
+* `<p style="{{ .Params.style | safeCSS }}">…</p>` ⇒ `<p style="color: red;">…</p>` (Good!)
+* `<p style="{{ .Params.style }}">…</p>` ⇒ `<p style="ZgotmplZ">…</p>` (Bad!)
+
+{{% note "ZgotmplZ" %}}
+ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context.
+{{% /note %}}

@@ -1,24 +1,32 @@
 ---
 title: safeHTMLAttr
 linktitle: safeHTMLAttr
-description:
-godocref:
+description: Declares the provided string as a "safe" HTML attribute.
+godocref: https://golang.org/src/html/template/content.go?s=1661:1676#L33
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: [strings]
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`safeHTMLAttr` declares the provided string as a "safe" HTML attribute
+from a trusted source (e.g., ` dir="ltr"`) to prevent Go html/template from filtering it as unsafe.

-## Advanced Example
+Example: Given a site-wide `config.toml` that contains this menu entry:
+
+```toml
+[[menu.main]]
+    name = "IRC: #golang at freenode"
+    url = "irc://irc.freenode.net/#golang"
+```
+
+* `<a href="{{ .URL }}">` ⇒ `<a href="#ZgotmplZ">` (Bad!)
+* `<a {{ printf "href=%q" .URL | safeHTMLAttr }}>` ⇒ `<a href="irc://irc.freenode.net/#golang">` (Good!)

@@ -1,14 +1,13 @@
 ---
 title: safeJS
 linktitle:
-description:
-godocref:
+description: Declares the provided string as a known "safe" JavaScript string.
+godocref: https://golang.org/src/html/template/content.go?s=2548:2557#L51
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: [strings]
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
@@ -18,7 +17,14 @@ draft: false
 aliases: []
 ---

-## Example
+`safeJs` declares the provided string as a known "safe" Javascript string so that Go html/templates will not escape it as unsafe.

-## Advanced Example
+In this context, *safe* means the string encapsulates a known safe EcmaScript5 Expression (e.g., `(x + y * z())`).
+
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo:bar() }\n['foo']()`, which is both a valid expression and a valid program with a very different meaning.
+
+Example: Given `hash = "619c16f"` defined in the front matter of your `.md` file:
+
+* `<script>var form_{{ .Params.hash | safeJS }};…</script>` ⇒ `<script>var form_619c16f;…</script>` (Good!)
+* `<script>var form_{{ .Params.hash }};…</script>` ⇒ `<script>var form_"619c16f";…</script>` (Bad!)

@@ -1,14 +1,13 @@
 ---
 title: seq
 linktitle:
-description:
+description: Creates a sequence of integers.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: []
 signature:
 workson: []
 hugoversion:
@@ -18,7 +17,14 @@ draft: false
 aliases: []
 ---

-## Example
+`seq` creates a sequence of integers. It's named and used in the model of [GNU's seq][gnuseq].

-## Advanced Example
+```
+3 → 1, 2, 3
+1 2 4 → 1, 3
+-3 → -1, -2, -3
+1 4 → 1, 2, 3, 4
+1 -2 → 1, 0, -1, -2
+```

+[gnuseq]: http://www.gnu.org/software/coreutils/manual/html_node/seq-invocation.html#seq-invocation
@@ -1,24 +1,22 @@
 ---
 title: singularize
-linktitle:
-description:
+linktitle: singularize
+description: Converts a word according to a set of common English singularization rules.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings,singular]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`singularize` converts a word according to a set of common English singularization rules.

-## Advanced Example
+`{{ "cats" | singularize }}` → "cat"

@@ -1,24 +1,26 @@
 ---
 title: slicestr
 linktitle:
-description:
+description: Creates a slice of a half-open range, including start and end indices.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+Slicing in `slicestr` is done by specifying a half-open range with two indices; i.e., a `start` and and `end`.

-## Advanced Example
+For example, 1 and 4 creates a slice including elements 1 through 3.
+The `end` index can be omitted; it defaults to the string's length.
+
+* `{{slicestr "BatMan" 3}}` → "Man"
+* `{{slicestr "BatMan" 0 3}}` → "Bat"

@@ -1,24 +1,62 @@
 ---
 title: sort
 linktitle: sort
-description:
+description: Sorts maps, arrays, and slices and returns a sorted slice.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: [ordering]
 categories: [functions]
-toc:
+tags: [ordering,sorting,lists]
 signature:
-workson: []
+workson: [lists,taxonomies,terms,groups]
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`sort` sorts maps, arrays, and slices and returns a sorted slice. A sorted array of map values will be returned with the keys eliminated. There are two optional arguments: `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order as its default behavior.

-## Advanced Example
+```toml
+++
+tags: [ "tag3", "tag1", "tag2" ]
+++
+
+// Site config
+++
+[params.authors]
+  [params.authors.Derek]
+    "firstName"  = "Derek"
+    "lastName"   = "Perkins"
+  [params.authors.Joe]
+    "firstName"  = "Joe"
+    "lastName"   = "Bergevin"
+  [params.authors.Tanner]
+    "firstName"  = "Tanner"
+    "lastName"   = "Linsley"
+++
+```
+
+```
+// Use default sort options - sort by key / ascending
+Tags: {{ range sort .Params.tags }}{{ . }} {{ end }}
+
+→ Outputs Tags: tag1 tag2 tag3
+
+// Sort by value / descending
+Tags: {{ range sort .Params.tags "value" "desc" }}{{ . }} {{ end }}
+
+→ Outputs Tags: tag3 tag2 tag1
+
+// Use default sort options - sort by value / descending
+Authors: {{ range sort .Site.Params.authors }}{{ .firstName }} {{ end }}
+
+→ Outputs Authors: Derek Joe Tanner
+
+// Use default sort options - sort by value / descending
+Authors: {{ range sort .Site.Params.authors "lastName" "desc" }}{{ .lastName }} {{ end }}
+
+→ Outputs Authors: Perkins Linsley Bergevin
+```

@@ -1,24 +1,23 @@
 ---
 title: split
-linktitle:
-description:
+linktitle: split
+description: splits a string into substrings separated by a delimiter
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example
+`split` splits a string into substrings separated by a delimiter.
+
+* `{{split "tag1,tag2,tag3" "," }}` → ["tag1" "tag2" "tag3"]

-## Advanced Example

@@ -1,24 +1,22 @@
 ---
 title: string
-linktitle:
-description:
+linktitle: string
+description: Creates a string from the argument passed to the function
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
 categories: [functions]
 tags: [strings]
-draft: false
-aliases: []
-toc:
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
+aliases: []
 ---

-## Example
+`string` creates a string from the argument passed to the function.

-## Advanced Example
+* `{{string "BatMan"}}` → "BatMan"

@@ -1,16 +1,14 @@
 ---
 title: substr
 linktitle:
-description:
+description: Extracts parts of a string from a specified character's position and returns the specified number of characters.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
 categories: [functions]
 tags: [strings]
-draft: false
 aliases: []
-toc:
 signature:
 workson: []
 hugoversion:
@@ -18,7 +16,15 @@ relatedfuncs: []
 deprecated: false
 ---

-## Example
+`substr` extracts parts of a string, beginning at the character at the specified position, and returns the specified number of characters.

-## Advanced Example
+It normally takes two parameters: `start` and `length`. It can also take one parameter: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned.

+To extract characters from the end of the string, use a negative start number.
+
+In addition, borrowing from the extended behavior described at http://php.net substr, if `length` is given and is negative, that number of characters will be omitted from the end of string.
+
+```
+{{substr "BatMan" 0 -3}} → "Bat"
+{{substr "BatMan" 3 3}} → "Man"
+```
@@ -1,24 +1,24 @@
 ---
 title: title
 linktitle:
-description:
+description: Converts all characters in the provided string to title case.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: [fundamentals,strings]
 categories: [functions]
-toc:
+tags: [fundamentals,strings]
 signature:
 workson: []
 hugoversion:
 relatedfuncs: []
 deprecated: false
-draft: false
 aliases: []
 ---

-## Example

-## Advanced Example
+`title` converts all characters in the provided string to title case.

+```
+{{title "BatMan"}}` → "Batman"
+```
@@ -18,4 +18,4 @@ toc: false
 The following sites have been built with {{< emo ":heart:" >}} and Hugo. If you're interested in adding your site to the showcase, [see how to contribute][addshowcase].


-[addshowcase]: /contribute/documentation/
+[addshowcase]: /contribute/documentation/#adding-to-the-showcase
@@ -9,7 +9,7 @@ categories: [templates]
 tags: [lists,sections,partials]
 weight: 90
 draft: false
-aliases: [/templates/partials/,/layout/chrome/,/extras/analytics/]
+aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
 toc: true
 needsreview: true
 ---
@@ -14,10 +14,10 @@ toc: false
 notesforauthors:
 ---

-The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][].
+The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum].




-[Hugo Discussion Forum]: https://discuss.gohugo.io
+[forum]: https://discuss.gohugo.io

@@ -1,7 +1,7 @@
 ---
 title: Accented Characters in URLs
 linktitle: Accented Characters in URLs
-description:
+description: If you're having trouble with special characters in your taxonomies or titles adding odd characters to your URLs.
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
@@ -1,7 +1,7 @@
 ---
 title: EOF Error
 linktitle: EOF Error
-description:
+description: If you find yourself seeing an EOF error in the console whenever you create a new content file from Hugo's archetype feature.
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
@@ -38,7 +38,7 @@ The solution is to add a final newline (i.e., `EOL`) to the end of your default.
 As of v0.13, Hugo's parser has been enhanced to accommodate archetype files without final EOL thanks to the great work by [@tatsushid](https://github.com/tatsushid).
 {{% /note %}}

-## Discussion Forum Threads
+## Discussion Forum References

 * http://discuss.gohugo.io/t/archetypes-not-properly-working-in-0-12/544
 * http://discuss.gohugo.io/t/eol-f-in-archetype-files/554
@@ -127,7 +127,7 @@ http://remarkjs.com)
 : a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Content Summaries](/content-management/content-summaries/) for more details.

 `.TableOfContents`
-: the rendered [table of contents](/content-management/table-of-contents/) for the page.
+: the rendered [table of contents](/content-management/toc/) for the page.

 `.Title`
 : the title for this page.
@@ -1,4 +1,5 @@
 <table class="bf-configuration">
+<!-- NOTE THAT THIS SHORTCODE IS USED ON GETTING-STARTED/CONFIGURATION, /CONTENT/FORMATS/ AND THEREFORE REFERENCES THE MULTILINGUAL MODE AT THE BOTTOM OF THE TABLE -->
    <thead>
        <tr>
            <th>Flag</th>
@@ -191,4 +192,6 @@
        </tbody>
 </table>

+<p>For additional Blackfriday configuration for multilingual sites, see <a href="/content-management/multilingual/#taxonomies-and-blackfriday">Taxonomies and Blackfriday in Multingual Mode.</a></p>
+

@@ -114,3 +114,17 @@ aside {
    }
  }
 }
+
+//for Hugo's native support of Github-flavored task list synax
+.body-copy {
+  .task-list {
+    list-style: none;
+    margin-left: 0px;
+    padding-left: 0px;
+    li {
+      list-style: none;
+      // padding-left:0px;
+      // margin-left:0px;
+    }
+  }
+}