github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-07 20:30:36 -05:00
Code Issues Projects Releases Packages Wiki Activity

[Docs] Complete the transition from "indexes" to "taxonomies" (almost)

Browse source 
Also mention `.Site.Indexes` → `.Site.Taxonomies` as well as
the upcoming `.Site.Recent` → `.Site.Pages` transitions.
This commit is contained in:
Anthony Fok 2015-01-29 12:34:56 -07:00
parent ba44e860a3
commit d397bc4f43
11 changed files with 60 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/config.toml
View file

@ -5,7 +5,7 @@ MetaDataFormat = "yaml"
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"

2
docs/content/overview/configuration.md
View file

@ -41,7 +41,7 @@ The following is an example of a toml config file with some of the default value
baseurl = "http://yoursite.example.com/"
canonifyurls = true
[indexes]
[taxonomies]
category = "categories"
tag = "tags"

4
docs/content/overview/source-directory.md
View file

@ -85,6 +85,6 @@ An example directory may look like:
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.

2
docs/content/taxonomies/displaying.md
View file

@ -80,7 +80,7 @@ different terms to the content.
## 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.

2
docs/content/taxonomies/ordering.md
View file

@ -15,7 +15,7 @@ weight: 60
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

8
docs/content/taxonomies/overview.md
View file

@ -16,15 +16,17 @@ weight: 10
---
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

35
docs/content/taxonomies/usage.md
View file

@ -16,18 +16,33 @@ Taxonomies must be defined in the site configuration before they can be
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> = &quot;<em>plural value</em>&quot;</code> for TOML,
or <code><strong>singular key</strong>: &quot;<em>plural value</em>&quot;</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

10
docs/content/templates/list.md
View file

@ -35,7 +35,7 @@ the list will be needed.
### Section Lists
A Section will be rendered at /`SECTION`/
A Section will be rendered at /`SECTION`/ (e.g.&nbsp;http://spf13.com/project/)
* /layouts/section/`SECTION`.html
* /layouts/\_default/section.html
@ -47,9 +47,9 @@ A Section will be rendered at /`SECTION`/
### Taxonomy Lists
A Taxonomy will be rendered at /`PLURAL`/`TERM`/
A Taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g.&nbsp;http://spf13.com/topics/golang/) from:
* /layouts/taxonomy/`SINGULAR`.html
* /layouts/taxonomy/`SINGULAR`.html (e.g.&nbsp;`/layouts/taxonomy/topic.html`)
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
@ -58,7 +58,7 @@ A Taxonomy will be rendered at /`PLURAL`/`TERM`/
### 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.&nbsp;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
@ -74,7 +74,7 @@ can have different RSS files for each section and taxonomy.
### 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.&nbsp;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

18
docs/content/templates/terms.md
View file

@ -16,23 +16,25 @@ weight: 60
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
@ -63,7 +65,7 @@ List pages are of the type "node" and have all the
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.

16
docs/content/templates/variables.md
View file

@ -35,8 +35,8 @@ matter, content or derived from file location.
**.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>
@ -53,8 +53,8 @@ matter, content or derived from file location.
## 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**
@ -63,7 +63,7 @@ Take for example I'm using tags and categories as my indexes. The following woul
## 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>
@ -71,7 +71,7 @@ includes indexes, lists and the homepage.
**.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>
@ -83,9 +83,9 @@ includes indexes, lists and the homepage.
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/"

2
examples/multilingual/config.toml
View file

@ -1,6 +1,6 @@
baseurl = ""
[indexes]
[taxonomies]
tag = "tags"
group = "groups"
menu = "menu"