Squashed 'docs/' changes from 715741f73..4e7e1815b

4e7e1815b Fix some typos
d23d8f5c4 Remove 'fundamentals' category from function pages
52fa65e15 Mention Chroma as the preferred syntax highlighter
64ca535db Merge commit '8762aee8afe30bec6f1fbc9560749983dc44d60b'
8762aee8a Squashed 'themes/gohugoioTheme/' changes from 396b859f..6f3a8bf5
03f0673a9 Move the gopher to the theme
320e268cd Spelling
e45b640f7 More layout lookup work
fe0ad9d9d Sync the YAML config menu example with TOML's
b9505fc70 Remove template reference to ordinal numbers
0fa2532d3 Remove deprecated Hugoidx, add native hugo solution
2152b907c Fix a link in the last commit
47614f416 Manually specifying heading anchors in Markdown content
9d6770d2a Release notes 0.37.1
e1eed8b27 Remove some unused images
e960046f5 releaser: Prepare repository for 0.38-DEV
4fa83a4ee releaser: Add release notes to /docs for release of 0.37.1
46c879995 releaser: Bump versions for release of 0.37.1
fb3ac5a3e releaser: Prepare repository for 0.38-DEV
4870c8e7b Update archetypes.md
232c0b578 Merge commit '2b18014fd0aa99e9f1a5610ba875101351a90de3'
2b18014fd Squashed 'themes/gohugoioTheme/' changes from fe71e360..396b859f
62567e9aa Add some "writing guidelines"
7cfd530d2 Revise the archetype docs
5d4c3c03c Update data-templates.md
e5fee3099 Update page-bundles.md
ca7f03c8d Update page-bundles.md
2a7fdc269 Fix typo 'vailable' to 'available' line 53
999b75201 LastMod should be Lastmod?
099f46ca5 Fix spacing in content-management/types.md
6bcdc58ef Word choice improvements
20e8a21f6 update rss linking docs
7ef44d262 Add some missing configuration entries
f1c7aa568 Sort config list
5cb8ceade Create a proper definition list for the configuration settings
25dffe4ac Send custom dimensions in GA
55df01a34 Fix broken gtag
6c8772aad Add site to GA config
e63acb894 Remove conflicting release note for 0.35
f30083a23 Add branch to GA config
99caedb96 Set the small-multiples to draft
4a33c70ab Polish the Small Multiples showcase
7b2f1ea2e Add small multiples showcase
e78e96bae Add new sponsor
c42943041 updated to new Forestry logo
e07eda273 Add OS env to faq
414f0dbc6 Release Hugo 0.37
85f0cc324 Merge branch 'temp37'
1e6da9497 Rebuild images
75e97adfc releaser: Add release notes to /docs for release of 0.37
50b887cb0 releaser: Bump versions for release of 0.37
7acf73ba3 Merge commit '900b5f6cfe5a377ef369d26cd700201be4cf6b06'
819d02c30 Merge commit '374d184e6747678364fd61f5faf328ec9205eb6b'
c7eacf018 Fix typos in development contribution doc

git-subtree-dir: docs
git-subtree-split: 4e7e1815b742659dec1c8f59a1896a3396c7b6e9

README.md

@@ -10,6 +10,12 @@ Note that this repository contains solely the documentation for Hugo. For contri
 
 *Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
 
+Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had these in mind when writing:
+
+* Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …".
+* For examples, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great, but don't list long and similar examples just so people can use them on their sites.
+* Hugo has users from all over the world, so an easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good.
+
 ## Branches
 
 * The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version.

config.toml

@@ -71,7 +71,7 @@ twitter = "GoHugoIO"
 [params]
   description = "The world’s fastest framework for building websites"
   ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable)
-  release = "0.36.1"
+  release = "0.37.1"
   ## Setting this to true will add a "noindex" to *EVERY* page on the site
   removefromexternalsearch = false
   ## Gh repo for site footer (include trailing slash)

content/content-management/archetypes.md

@@ -1,10 +1,9 @@
 ---
 title: Archetypes
 linktitle: Archetypes
-description: Archetypes allow you to create new instances of content types and set default parameters from the command line.
+description: Archetypes are templates used when creating new content.
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
 keywords: [archetypes,generators,metadata,front matter]
 categories: ["content management"]
 menu:
@@ -18,175 +17,59 @@ aliases: [/content/archetypes/]
 toc: true
 ---
 
-{{% note %}}
-This section is outdated, see https://github.com/gohugoio/hugoDocs/issues/11
-{{% /note %}}
-{{% todo %}}
-See above
-{{% /todo %}}
-
 ## What are Archetypes?
 
-**Archetypes** are content files in the [archetypes directory][] of your project that contain preconfigured [front matter][] for your website's [content types][]. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the `hugo new` command.
-
-{{< youtube bcme8AzVh6o >}}
-
-The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
+**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`.
 
-```
-hugo new <content-section>/<file-name.md>
-```
 
-We can use this pattern to create a new `.md` file in the `posts` section:
+The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme.
 
 {{< code file="archetype-example.sh" >}}
 hugo new posts/my-first-post.md
 {{< /code >}}
 
-{{% note "Override Content Type in a New File" %}}
-To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
-{{% /note %}}
-
-Running this command in a new site that does not have default or custom archetypes will create the following file:
-
-{{< output file="content/posts/my-first-post.md" >}}
-+++
-date = "2017-02-01T19:20:04-07:00"
-title = "my first post"
-draft = true
-+++
-{{< /output >}}
-
-{{% note %}}
-In this example, if you do not already have a `content/posts` directory, Hugo will create both `content/posts/` and `content/posts/my-first-post.md` for you.
-{{% /note %}}
-
-The  auto-populated fields are worth examining:
-
-* `title` is generated from the new content's filename (i.e. in this case, `my-first-post` becomes `"my first post"`)
-* `date` and `title` are the variables that ship with Hugo and are therefore included in *all* content files created with the Hugo CLI. `date` is generated in [RFC 3339 format][] by way of Go's [`now()`][] function, which returns the current time.
-* The third variable, `draft = true`, is *not* inherited by your default or custom archetypes but is included in Hugo's automatically scaffolded `default.md` archetype for convenience.
-
-Three variables per content file are often not enough for effective content management of larger websites. Luckily, Hugo provides a simple mechanism for extending the number of variables through custom archetypes, as well as default archetypes to keep content creation DRY.
-
-## Lookup Order for Archetypes
-
-Similar to the [lookup order for templates][lookup] in your `layouts` directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for `content/posts/my-first-post.md` in the following order:
+The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these:
 
 1. `archetypes/posts.md`
 2. `archetypes/default.md`
-3. `themes/<THEME>/archetypes/posts.md`
-4. `themes/<THEME>/archetypes/default.md` (Auto-generated with `hugo new site`)
-
-{{% note "Using a Theme Archetype" %}}
-If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/getting-started/configuration/).
-{{% /note %}}
-
-## Choose Your Archetype's Front Matter Format
-
-By default, `hugo new` content files include front matter in the TOML format regardless of the format used in `archetypes/*.md`.
-
-You can specify a different default format in your site [configuration file][] file using the `metaDataFormat` directive. Possible values are `toml`, `yaml`, and `json`.
-
-## Default Archetypes
-
-Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][sections].
+3. `themes/my-theme/posts.md`
+4. `themes/my-theme/default.md`
 
-### Create the Default Archetype
+The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example.
 
-When you create a new Hugo project using `hugo new site`, you'll notice that Hugo has already scaffolded a file at `archetypes/default.md`.
+## Create a New Archetype Template
 
-The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
+A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor.
 
-{{< code file="archetypes/default.md" >}}
-+++
-tags = ["golang", "hugo"]
-categories = ["web development"]
-+++
-{{< /code >}}
-
-{{% warning "EOL Characters in Text Editors"%}}
-If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
-{{% /warning %}}
-
-### Use the Default Archetype
-
-With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
-
-{{< code file="new-post-from-default.sh" >}}
-$ hugo new posts/my-new-post.md
-{{< /code >}}
-
-Hugo then creates a new markdown file with the following front matter:
-
-{{< output file="content/posts/my-new-post.md" >}}
-+++
-categories = ["web development"]
-date = "2017-02-01T19:20:04-07:00"
-tags = ["golang", "hugo"]
-title = "my new post"
-+++
-{{< /output >}}
-
-We see that the `title` and `date` key-values have been added in addition to the `tags` and `categories` key-values from `archetypes/default.md`.
-
-{{% note "Ordering of Front Matter" %}}
-You may notice that content files created with `hugo new` do not respect the order of the key-values specified in your archetype files. This is a [known issue](https://github.com/gohugoio/hugo/issues/452).
-{{% /note %}}
-
-## Custom Archetypes
-
-Suppose your site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. You can create a custom archetype for your posts at `archetypes/posts.md` that includes the full set of front matter to be added to the two default archetypes fields.
-
-### Create a Custom Archetype
-
-{{< code file="archetypes/posts.md">}}
-+++
-description = ""
-tags = ""
-categories = ""
-+++
-{{< /code >}}
+{{< code file="archetypes/newsletter.md" >}}
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
 
-### Use a Custom Archetype
+**Insert Lead paragraph here.**
 
-With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
+## New Cool Posts
 
-{{< code file="new-post-from-custom.sh" >}}
-$ hugo new posts/post-from-custom.md
+{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
+* {{ .Title }}
+{{ end }}
 {{< /code >}}
 
-This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
+When you create a new newsletter with:
 
-{{< output file="content/posts/post-from-custom-archetype.md" >}}
-+++
-categories = ""
-date = 2017-02-13T17:24:43-08:00
-description = ""
-tags = ""
-title = "post from custom archetype"
-+++
-{{< /output >}}
+```bash
+hugo new newsletter/the-latest-cool.stuff.md
+```
 
-### Hugo Docs Custom Archetype
+It will create a new newsletter type of content file based on the archetype template.
 
-As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
+**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites.
 
-{{< code file="archetypes/functions.md" >}}
-{{< readfile file="/archetypes/functions.md" >}}
-{{< /code >}}
+The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo&#39;s template funcs can be used in the archetype file.
 
-{{% note %}}
-The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
-{{% /note %}}
 
 [archetypes directory]: /getting-started/directory-structure/
-[`now()`]: http://golang.org/pkg/time/#Now
-[configuration file]: /getting-started/configuration/
-[sections]: /content-management/sections/
 [content types]: /content-management/types/
 [front matter]: /content-management/front-matter/
-[RFC 3339 format]: https://www.ietf.org/rfc/rfc3339.txt
-[taxonomies]: /content-management/taxonomies/
-[lookup]: /templates/lookup/
-[templates]: /templates/

content/content-management/cross-references.md

@@ -109,8 +109,22 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi
 /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
 ```
 
+### Manually Specifying Anchors
+
+For Markdown content files, if the `headerIds` [Blackfriday extension][bfext] is
+enabled (which it is by default), user can manually specify the anchor for any
+heading.
+
+Few examples:
+
+```
+## Alpha 101 {#alpha}
+
+## Version 1.0 {#version-1-dot-0}
+```
 
 [built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
 [lists]: /templates/lists/
 [output formats]: /templates/output-formats/
 [shortcode]: /content-management/shortcodes/
+[bfext]: /content-management/formats/#blackfriday-extensions

content/content-management/formats.md

@@ -84,7 +84,7 @@ See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that sh
 
 ### Code Blocks
 
-Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` nested shortcode][hlsc] to render syntax highlighting via [Pygments][]. For usage examples and a complete explanation, see the [syntax highlighting documentation][hl] in [developer tools][].
+Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` shortcode][hlsc], and syntax highlights those code blocks natively using *Chroma*. Users also have an option to use *Pygments* instead. See the [Syntax Highlighting][hl] section for details.
 
 ## Mmark
 
@@ -231,7 +231,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
 [fireball]: https://daringfireball.net/projects/markdown/
 [gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax
 [helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65
-[hl]: /tools/syntax-highlighting/
+[hl]: /content-management/syntax-highlighting/
 [hlsc]: /content-management/shortcodes/#highlight
 [hugocss]: /css/style.css
 [ietf]: https://tools.ietf.org/html/

content/content-management/menus.md

@@ -137,19 +137,17 @@ Here’s an example snippet pulled from a `config.toml`:
 Here's the equivalent snippet in a `config.yaml`:
 
 {{< code file="config.yml" >}}
----
 menu:
-  docs:
-      - Name: "about hugo"
-        Pre: "<i class='fa fa-heart'></i>"
-        Weight: -110
-        Identifier: "about"
-        URL: "/about/"
-      - Name: "getting started"
-        Pre: "<i class='fa fa-road'></i>"
-        Weight: -100
-        URL: "/getting-started/"
----
+  main:
+      - name: "about hugo"
+        pre: "<i class='fa fa-heart'></i>"
+        weight: -110
+        identifier: "about"
+        url: "/about/"
+      - name: "getting started"
+        pre: "<i class='fa fa-road'></i>"
+        weight: -100
+        url: "/getting-started/"
 {{< /code >}}
 
 {{% note %}}

content/content-management/page-bundles.md

@@ -6,7 +6,6 @@ lastmod : 2018-01-28T22:26:40-05:00
 linktitle : "Page Bundles"
 keywords : ["page", "bundle", "leaf", "branch"]
 categories : ["content management"]
-draft : true
 toc : true
 menu :
   docs:
@@ -15,19 +14,16 @@ menu :
     weight : 11
 ---
 
-Page Bundles are a way to organize the content files. It's useful for
-cases where a page or section's content needs to be split into
-multiple content pages for convenience or has associated attachments
-like documents or images.
+Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
 
-A Page Bundle can be one of two types:
+A Page Bundle can be one of:
 
--   Leaf Bundle
--   Branch Bundle
+-   Leaf Bundle (leaf means it has no children)
+-   Branch Bundle (home page, section, taxonomy terms, taxonomy list)
 
 |                 | Leaf Bundle                                            | Branch Bundle                                           |
 |-----------------|--------------------------------------------------------|---------------------------------------------------------|
-| Usage           | Collection of content and attachments for single pages | Collection of content and attachments for section pages |
+| Usage           | Collection of resources (pages, images etc.) for single pages    | Collection of non-page resources (images etc.)for list pages |
 | Index file name | `index.md` [^fn:1]                                     | `_index.md` [^fn:1]                                     |
 | Layout type     | `single`                                               | `list`                                                  |
 | Nesting         | Doesn't allow nesting of more bundles under it         | Allows nesting of leaf/branch bundles under it          |
@@ -37,15 +33,7 @@ A Page Bundle can be one of two types:
 ## Leaf Bundles {#leaf-bundles}
 
 A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
-directory, that contains at least an **`index.md`** file.
-
-{{% note %}}
-Here `md` (markdown) is used just as an example. You can use any file
-type as a content resource as long as it is a MIME type recognized by
-Hugo (`json` files will, as one example, work fine). If you want to
-get exotic, you can define your own media type.
-{{% /note %}}
-
+directory, that contains an **`index.md`** file.
 
 ### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
 

content/content-management/types.md

@@ -54,7 +54,7 @@ layout = "birthday"
 +++
 {{< /code >}}
 
-By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/ my-first-event.md` is of type `event` and should render using the `birthday` layout.
+By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/my-first-event.md` is of type `event` and should render using the `birthday` layout.
 
 ### Create a Type Layout Directory
 
@@ -96,4 +96,4 @@ Read [Archetypes][archetypes] for more information on archetype usage with `hugo
 [sectiontemplates]: /templates/section-templates/
 [sections]: /content-management/sections/
 [template]: /templates/
-[Tumblr]: https://www.tumblr.com/
+[Tumblr]: https://www.tumblr.com/