Merge commit 'ec4e6f9df2ab9ffdc62a3f59675369096e0d3f77' as 'docs'

docs/content/themes/_index.md

@@ -0,0 +1,26 @@
+---
+title: Themes
+linktitle: Themes Overview
+description: Install, use, and create Hugo themes.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+menu:
+  docs:
+    parent: "themes"
+    weight: 01
+weight: 01
+sections_weight: 01
+categories: [themes]
+#tags: [themes,introduction,overview]
+draft: false
+aliases: [/themes/overview/]
+toc: false
+---
+
+Hugo provides a robust theming system that is easy to implement yet feature complete. You can view the themes created by the Hugo community on the [Hugo themes website][hugothemes].
+
+Hugo themes are powered by the excellent Go template library and are designed to reduce code duplication. They are easy to both customize and keep in synch with the upstream theme.
+
+[goprimer]: /templates/introduction/
+[hugothemes]: http://themes.gohugo.io/

docs/content/themes/creating.md

@@ -0,0 +1,87 @@
+---
+title: Create a Theme
+linktitle: Create a Theme
+description: The `hugo new theme` command will scaffold the beginnings of a new theme for you to get you on your way.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [themes]
+#tags: [themes, source, organization, directories]
+menu:
+  docs:
+    parent: "themes"
+    weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/themes/creation/,/tutorials/creating-a-new-theme/]
+toc: true
+wip: true
+---
+
+{{% warning "Use Relative Links" %}}
+If you're creating a theme with plans to share it with the community, use relative URLs since users of your theme may not publish from the root of their website. See [relURL](/functions/relurl) and [absURL](/functions/absurl).
+{{% /warning %}}
+
+Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command:
+
+```
+hugo new theme [name]
+```
+
+## Theme Components
+
+A theme consists of templates and static assets such as javascript and css files. Themes can also provide [archetypes][], which are archetypal content types used by the `hugo new` command to scaffold new content files with preconfigured front matter.
+
+
+{{% note "Use the Hugo Generator Tag" %}}
+The [`.Hugo.Generator`](/variables/hugo/) tag is included in all themes featured in the [Hugo Themes Showcase](http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo to help the core team track Hugo's usage and popularity.
+{{% /note %}}
+
+## Layouts
+
+Hugo is built around the concept that things should be as simple as possible.
+Fundamentally, website content is displayed in two different ways, a single
+piece of content and a list of content items. With Hugo, a theme layout starts
+with the defaults. As additional layouts are defined, they are used for the
+content type or section they apply to. This keeps layouts simple, but permits
+a large amount of flexibility.
+
+## Single Content
+
+The default single file layout is located at `layouts/_default/single.html`.
+
+## List of Contents
+
+The default list file layout is located at `layouts/_default/list.html`.
+
+## Partial Templates
+
+Theme creators should liberally use [partial templates](/templates/partials/)
+throughout their theme files. Not only is a good DRY practice to include shared
+code, but partials are a special template type that enables the themes end user
+to be able to overwrite just a small piece of a file or inject code into the
+theme from their local /layouts. These partial templates are perfect for easy
+injection into the theme with minimal maintenance to ensure future
+compatibility.
+
+## Static
+
+Everything in the static directory will be copied directly into the final site
+when rendered. No structure is provided here to enable complete freedom. It is
+common to organize the static content into:
+
+```
+/css
+/js
+/img
+```
+
+The actual structure is entirely up to you, the theme creator, on how you would like to organize your files.
+
+## Archetypes
+
+If your theme makes use of specific keys in the front matter, it is a good idea
+to provide an archetype for each content type you have. [Read more about archetypes][archetypes].
+
+[archetypes]: /content-management/archetypes/

docs/content/themes/customizing.md

@@ -0,0 +1,80 @@
+---
+title: Customize a Theme
+linktitle: Customize a Theme
+description: Customize a theme by overriding theme layouts and static assets in your top-level project directories.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [themes]
+#tags: [themes, source, organization, directories]
+menu:
+  docs:
+    parent: "themes"
+    weight: 20
+weight: 20
+sections_weight: 20
+draft: false
+aliases: [/themes/customize/]
+toc: true
+wip: true
+---
+
+The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement *or* override any theme template or static file with files in your working directory.
+
+{{% note %}}
+When you use a theme cloned from its git repository, do not edit the theme's files directly. Instead, theme customization in Hugo is a matter of *overriding* the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme's upstream.
+{{% /note %}}
+
+## Override Static Files
+
+There are times where you want to include static assets that differ from versions of the same asset that ships with a theme.
+
+For example, a theme may use jQuery 1.8 in the following location:
+
+```
+/themes/<THEME>/static/js/jquery.min.js
+```
+
+You want to replace the version of jQuery that ships with the theme with the newer `jquery-3.1.1.js`. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root. Therefore, change `jquery-3.1.1.js` to `jquery.min.js` so that it is *identical* to the theme's version and place the file here:
+
+```
+/static/js/jquery.min.js
+```
+
+## Override Template Files
+
+Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory.
+
+The [template lookup order][lookup] explains the rules Hugo uses to determine which template to use for a given piece of content. Read and understand these rules carefully.
+
+This is especially helpful when the theme creator used [partial templates][partials]. These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.
+
+For example:
+
+```
+/themes/<THEME>/layouts/_default/single.html
+```
+
+Would be overwritten by
+
+```
+/layouts/_default/single.html
+```
+
+{{% warning %}}
+This only works for templates that Hugo "knows about" (i.e., that follow its convention for folder structure and naming). If a theme imports template files in a creatively named directory, Hugo won’t know to look for the local `/layouts` first.
+{{% /warning %}}
+
+## Override Archetypes
+
+If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit.
+
+{{% warning "Beware of `layouts/_default`" %}}
+The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetypes](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes/<THEME>/archetypes/default.md` or `themes/<THEME>/layout/_defaults/*.html`, respectively).
+
+It is usually better to override specific files; i.e. rather than using `layouts/_default/*.html` in your working directory.
+{{% /warning %}}
+
+[archetypes]: /content-management/archetypes/
+[lookup]: /templates/lookup-order/
+[partials]: /templates/partials/

docs/content/themes/installing-and-using-themes.md

@@ -0,0 +1,112 @@
+---
+title: Install and Use Themes
+linktitle: Install and Use Themes
+description: Install and use a theme from the Hugo theme showcase easily through the CLI.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [themes]
+#tags: [install, themes, source, organization, directories,usage]
+menu:
+  docs:
+    parent: "themes"
+    weight: 10
+weight: 10
+sections_weight: 10
+draft: false
+aliases: [/themes/usage/,/themes/installing/]
+toc: true
+wip: true
+---
+
+{{% note "No Default Theme" %}}
+Hugo currently doesn’t ship with a “default” theme. This decision is intentional. We leave it up to you to decide which theme best suits your Hugo project.
+{{% /note %}}
+
+## Assumptions
+
+1. You have already [installed Hugo on your development machine][install].
+2. You have git installed on your machine and you are familiar with basic git usage.
+
+## Install Themes
+
+The community-contributed themes featured on [themes.gohugo.io](//themes.gohugo.io/) are hosted in a [centralized GitHub repository][themesrepo]. The Hugo Themes Repo at <https://github.com/gohugoio/hugoThemes> is really a meta repository that contains pointers to a set of contributed themes.
+
+{{% warning "Get `git` First" %}}
+Without [Git](https://git-scm.com/) installed on your computer, none of the following theme instructions will work. Git tutorials are beyond the scope of the Hugo docs, but [GitHub](https://try.github.io/) and [codecademy](https://www.codecademy.com/learn/learn-git) offer free, interactive courses for beginners.
+{{% /warning %}}
+
+### Install All Themes
+
+You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while.
+
+```
+git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
+```
+
+Before you use a theme, remove the .git folder in that theme's root folder. Otherwise, this will cause problem if you deploy using Git.
+
+### Install a Single Theme
+
+Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository:
+
+```
+cd themes
+git clone URL_TO_THEME
+```
+
+The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
+
+{{< code file="clone-theme.sh" >}}
+cd themes
+git clone https://github.com/spf13/hyde
+{{< /code >}}
+
+Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
+
+{{% note "Read the `README`" %}}
+Always review the `README.md` file that is shipped with a theme. Often, these files contain further instructions required for theme setup; e.g., copying values from an example configuration file.
+{{% /note %}}
+
+## Theme Placement
+
+Please make certain you have installed the themes you want to use in the
+`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended.
+
+## Use Themes
+
+Hugo applies the decided theme first and then applies anything that is in the local directory. This allows for easier customization while retaining compatibility with the upstream version of the theme. To learn more, go to [customizing themes][customizethemes].
+
+### Command Line
+
+There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your
+
+To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site:
+
+```
+hugo -t themename
+```
+
+Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]:
+
+```
+hugo server -t themename
+```
+
+### `config` File
+
+If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]:
+
+```
+theme: themename
+```
+
+{{% note "A Note on `themename`" %}}
+The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io).
+{{% /note %}}
+
+[customizethemes]: /themes/customizing/
+[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage."
+[install]: /getting-started/installing/
+[config]: /getting-started/configuration/  "Learn how to customize your Hugo website configuration file in yaml, toml, or json."
+[themesrepo]: https://github.com/gohugoio/hugoThemes