From d397bc4f43e474529476c8f177e3be4fcd69d593 Mon Sep 17 00:00:00 2001 From: Anthony Fok Date: Thu, 29 Jan 2015 12:34:56 -0700 Subject: [PATCH] [Docs] Complete the transition from "indexes" to "taxonomies" (almost) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also mention `.Site.Indexes` → `.Site.Taxonomies` as well as the upcoming `.Site.Recent` → `.Site.Pages` transitions. --- docs/config.toml | 2 +- docs/content/overview/configuration.md | 2 +- docs/content/overview/source-directory.md | 4 +-- docs/content/taxonomies/displaying.md | 2 +- docs/content/taxonomies/ordering.md | 2 +- docs/content/taxonomies/overview.md | 8 ++++-- docs/content/taxonomies/usage.md | 35 ++++++++++++++++------- docs/content/templates/list.md | 10 +++---- docs/content/templates/terms.md | 18 ++++++------ docs/content/templates/variables.md | 16 +++++------ examples/multilingual/config.toml | 2 +- 11 files changed, 60 insertions(+), 41 deletions(-) diff --git a/docs/config.toml b/docs/config.toml index a9560d2aa..81fc277b6 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -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" diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md index ef677db63..0fa5b57f8 100644 --- a/docs/content/overview/configuration.md +++ b/docs/content/overview/configuration.md @@ -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" diff --git a/docs/content/overview/source-directory.md b/docs/content/overview/source-directory.md index fedfd0295..c4ff3e544 100644 --- a/docs/content/overview/source-directory.md +++ b/docs/content/overview/source-directory.md @@ -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. diff --git a/docs/content/taxonomies/displaying.md b/docs/content/taxonomies/displaying.md index 574d4dd1b..d56b9b396 100644 --- a/docs/content/taxonomies/displaying.md +++ b/docs/content/taxonomies/displaying.md @@ -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. diff --git a/docs/content/taxonomies/ordering.md b/docs/content/taxonomies/ordering.md index 150f1945b..7dfaf405b 100644 --- a/docs/content/taxonomies/ordering.md +++ b/docs/content/taxonomies/ordering.md @@ -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 diff --git a/docs/content/taxonomies/overview.md b/docs/content/taxonomies/overview.md index 8789c417d..ed5d287c3 100644 --- a/docs/content/taxonomies/overview.md +++ b/docs/content/taxonomies/overview.md @@ -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 diff --git a/docs/content/taxonomies/usage.md b/docs/content/taxonomies/usage.md index 3e8f6373f..ce717f3fc 100644 --- a/docs/content/taxonomies/usage.md +++ b/docs/content/taxonomies/usage.md @@ -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 singular key = "plural value" for TOML, +or singular key: "plural value" for YAML: - --- - Taxonomies: - tag: "tags" - category: "categories" - series: "series" - --- + + + + + + + + + + + + +
config.toml excerpt:config.yaml excerpt:
[taxonomies]
+  tag = "tags"
+  category = "categories"
+  series = "series"
+
taxonomies:
+  tag: "tags"
+  category: "categories"
+  series: "series"
+
## Assigning taxonomy values to content diff --git a/docs/content/templates/list.md b/docs/content/templates/list.md index e39abbd17..e66f86bd2 100644 --- a/docs/content/templates/list.md +++ b/docs/content/templates/list.md @@ -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. 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. 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 @@ -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. 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. 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 diff --git a/docs/content/templates/terms.md b/docs/content/templates/terms.md index 6522cf014..5bb91b84b 100644 --- a/docs/content/templates/terms.md +++ b/docs/content/templates/terms.md @@ -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. diff --git a/docs/content/templates/variables.md b/docs/content/templates/variables.md index 0d50dc0fd..db6268c3e 100644 --- a/docs/content/templates/variables.md +++ b/docs/content/templates/variables.md @@ -35,8 +35,8 @@ matter, content or derived from file location. **.Permalink** The Permanent link for this page.
**.RelPermalink** The Relative permanent link for this page.
**.LinkTitle** Access when creating links to this content. Will use `linktitle` if set in front matter, else `title`.
-**.Taxonomies** These will use the field name of the plural form of the index (see tags and categories above).
-**.RSSLink** Link to the indexes' RSS link.
+**.Taxonomies** These will use the field name of the plural form of the taxonomy (see tags and categories below).
+**.RSSLink** Link to the taxonomies' RSS link.
**.TableOfContents** The rendered table of contents for this content.
**.Prev** Pointer to the previous content (based on pub date).
**.Next** Pointer to the following content (based on pub date).
@@ -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.
**.Date** The date the content is published on.
@@ -71,7 +71,7 @@ includes indexes, lists and the homepage. **.Url** The relative URL for this node.
**.Ref(ref)** Returns the permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.
**.RelRef(ref)** Returns the relative permalink for `ref`. See [cross-references]({{% ref "extras/crossreferences.md" %}}). Does not handle in-page fragments correctly.
-**.RSSLink** Link to the indexes' RSS link.
+**.RSSLink** Link to the taxonomies' RSS link.
**.Data** The data specific to this type of node.
**.IsNode** Always true for nodes.
**.IsPage** Always false for nodes.
@@ -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.
-**.Site.Taxonomies** The indexes for the entire site.
+**.Site.Taxonomies** The [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11.
**.Site.LastChange** The date of the last change of the most recent content.
-**.Site.Recent** Array of all content ordered by Date, newest first.
+**.Site.Pages** Array of all content ordered by Date, newest first. Replaces the now-deprecated `.Site.Recent` starting v0.13.
**.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/" diff --git a/examples/multilingual/config.toml b/examples/multilingual/config.toml index 094b09b29..4285f302d 100644 --- a/examples/multilingual/config.toml +++ b/examples/multilingual/config.toml @@ -1,6 +1,6 @@ baseurl = "" -[indexes] +[taxonomies] tag = "tags" group = "groups" menu = "menu"