description = "Documentation of Hugo, a fast and flexible static site generator built with love by spf13 and friends in Go"
author = "Steve Francia (spf13) and friends"
-[indexes]
+[taxonomies]
tag = "tags"
group = "groups"
baseurl = "http://yoursite.example.com/"
canonifyurls = true
- [indexes]
+ [taxonomies]
category = "categories"
tag = "tags"
This directory structure tells us a lot about this site:
-1. The website intends to have two different types of content: posts and quotes.
-2. It will also apply two different indexes to that content: categories and tags.
+1. The website intends to have two different types of content: *posts* and *quotes*.
+2. It will also apply two different taxonomies to that content: *categories* and *tags*.
3. It will be displaying content in 3 different views: a list, a summary and a full page view.
## 4. Rendering a Site's Taxonomies
-If you wish to display the list of all keys for an taxonomy, you can find retrieve
+If you wish to display the list of all keys for a taxonomy, you can find retrieve
them from the `.Site` variable which is available on every page.
This may take the form of a tag cloud, a menu or simply a list.
Hugo provides the ability to both:
- 1. Order the way the keys for an taxonomy are displayed
+ 1. Order the way the keys for a taxonomy are displayed
2. Order the way taxonomyed content appears
---
Hugo includes support for user-defined groupings of content called
-taxonomies. Taxonomies give us a way to classify our content so we can
+taxonomies.[^1] Taxonomies give us a way to classify our content so we can
demonstrate relationships in a variety of logical ways.
-The default taxonomies for Hugo are tags and categories. These
+[^1]: Taxonomies were called *indexes* in Hugo prior to v0.11.
+
+The default taxonomies for Hugo are *tags* and *categories*. These
taxonomies are common to many website systems (e.g. WordPress, Drupal,
Jekyll). Unlike all of those systems, Hugo makes it trivial to customize
the taxonomies you will be using for your site however you wish. Another
good use for taxonomies is to group a set of posts into a series. Other
-common uses would include categories, tags, groups, series and many
+common uses would include *categories*, *tags*, *groups*, *series* and many
more.
When taxonomies are used (and templates are provided), Hugo will
used throughout the site. You need to provide both the plural and
singular labels for each taxonomy.
-Here is an example configuration in YAML that specifies three taxonomies
-(the default two, plus `series`).
+Here is an example configuration in TOML and YAML
+that specifies three taxonomies (the default two, plus `series`).
-Notice the format is **singular key** : *plural value*.
-### config.yaml
+Notice the format is <code><strong>singular key</strong> = "<em>plural value</em>"</code> for TOML,
+or <code><strong>singular key</strong>: "<em>plural value</em>"</code> for YAML:
- ---
- Taxonomies:
- tag: "tags"
- category: "categories"
- series: "series"
- ---
+<table class="table">
+<thead>
+<tr>
+<th>config.toml excerpt:</th><th>config.yaml excerpt:</th>
+</tr>
+</thead>
+<tbody>
+<tr valign="top">
+<td><pre><code>[taxonomies]
+ tag = "tags"
+ category = "categories"
+ series = "series"
+</code></pre></td>
+<td><pre><code class="language-yaml">taxonomies:
+ tag: "tags"
+ category: "categories"
+ series: "series"
+</code></pre></td>
+</tr>
+</tbody>
+</table>
## Assigning taxonomy values to content
### Section Lists
-A Section will be rendered at /`SECTION`/
+A Section will be rendered at /`SECTION`/ (e.g. http://spf13.com/project/)
* /layouts/section/`SECTION`.html
* /layouts/\_default/section.html
### Taxonomy Lists
-A Taxonomy will be rendered at /`PLURAL`/`TERM`/
+A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g. http://spf13.com/topics/golang/) from:
-* /layouts/taxonomy/`SINGULAR`.html
+* /layouts/taxonomy/`SINGULAR`.html (e.g. `/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
### Section RSS
-A Section’s RSS will be rendered at /`SECTION`/index.xml
+A Section’s RSS will be rendered at /`SECTION`/index.xml (e.g. http://spf13.com/project/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
### Taxonomy RSS
-A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml
+A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml (e.g. http://spf13.com/topics/golang/index.xml)
*Hugo ships with its own [RSS 2.0][] template. In most cases this will
be sufficient, and an RSS template will not need to be provided by the
A unique template is needed to create a list of the terms for a given
taxonomy. This is different from the [list template](/templates/list/)
-as that template is a list of content, where this is a list of meta data.
+as that template is a list of content, whereas this is a list of meta data.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
-Hugo will use the following prioritized list. If a file isn’t present,
+A Taxonomy Terms List will be rendered at /`PLURAL`/
+(e.g. http://spf13.com/topics/)
+from the following prioritized list:
+
+* /layouts/taxonomy/`SINGULAR`.terms.html (e.g. `/layouts/taxonomy/topic.terms.html`)
+* /layouts/\_default/terms.html
+
+If a file isn’t present,
then the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
than necessary. For most sites, only the `_default` file at the end of
the list will be needed.
-A Taxonomy Terms List will be rendered at /`PLURAL`/
-
-* /layouts/taxonomy/`SINGLE`.terms.html
-* /layouts/\_default/terms.html
-
If that neither file is found in either the /layouts or /theme/layouts
directory, then Hugo will not render the taxonomy terms pages. It is also
common for people to render taxonomy terms lists on other pages such as
available to use in the templates.
This content template is used for [spf13.com](http://spf13.com/).
-It makes use of [partial templates](/templates/partials/). The list of indexes
+It makes use of [partial templates](/templates/partials/). The list of taxonomy
templates cannot use a [content view](/templates/views/) as they don't display the content, but
rather information about the content.
**.Permalink** The Permanent link for this page.<br>
**.RelPermalink** The Relative permanent link for this page.<br>
**.LinkTitle** Access when creating links to this content. Will use `linktitle` if set in front matter, else `title`.<br>
-**.Taxonomies** These will use the field name of the plural form of the index (see tags and categories above).<br>
-**.RSSLink** Link to the indexes' RSS link.<br>
+**.Taxonomies** These will use the field name of the plural form of the taxonomy (see tags and categories below).<br>
+**.RSSLink** Link to the taxonomies' RSS link.<br>
**.TableOfContents** The rendered table of contents for this content.<br>
**.Prev** Pointer to the previous content (based on pub date).<br>
**.Next** Pointer to the following content (based on pub date).<br>
## Page Params
-Any other value defined in the front matter, including indexes will be made available under `.Params`.
-Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
+Any other value defined in the front matter, including taxonomies, will be made available under `.Params`.
+Take for example I'm using *tags* and *categories* as my taxonomies. The following would be how I would access them:
* **.Params.tags**
* **.Params.categories**
## Node Variables
In Hugo, a node is any page not rendered directly by a content file. This
-includes indexes, lists and the homepage.
+includes taxonomies, lists and the homepage.
**.Title** The title for the content.<br>
**.Date** The date the content is published on.<br>
**.Url** The relative URL for this node.<br>
**.Ref(ref)** Returns the permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br>
**.RelRef(ref)** Returns the relative permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.<br>
-**.RSSLink** Link to the indexes' RSS link.<br>
+**.RSSLink** Link to the taxonomies' RSS link.<br>
**.Data** The data specific to this type of node.<br>
**.IsNode** Always true for nodes.<br>
**.IsPage** Always false for nodes.<br>
Also available is `.Site` which has the following:
**.Site.BaseUrl** The base URL for the site as defined in the site configuration file.<br>
-**.Site.Taxonomies** The indexes for the entire site.<br>
+**.Site.Taxonomies** The [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11.<br>
**.Site.LastChange** The date of the last change of the most recent content.<br>
-**.Site.Recent** Array of all content ordered by Date, newest first.<br>
+**.Site.Pages** Array of all content ordered by Date, newest first. Replaces the now-deprecated `.Site.Recent` starting v0.13.<br>
**.Site.Params** A container holding the values from the `params` section of your site configuration file. For example, a TOML config file might look like this:
baseurl = "http://yoursite.example.com/"
baseurl = ""
-[indexes]
+[taxonomies]
tag = "tags"
group = "groups"
menu = "menu"
projects / brevno-suite / hugo / commitdiff