HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
Star

What's on this Page

  • What is a Taxonomy?
  • Example Taxonomy: Movie Website
  • Hugo Taxonomy Defaults
  • Configure Taxonomies
  • Add Taxonomies to Content
  • Order Taxonomies
  • Add custom metadata to a Taxonomy or Term
CONTENT MANAGEMENT

Taxonomies

Hugo includes support for user-defined taxonomies.

What is a Taxonomy?

Hugo includes support for user-defined groupings of content called taxonomies. Taxonomies are classifications of logical relationships between content.

Definitions

Taxonomy
a categorization that can be used to classify content
Term
a key within the taxonomy
Value
a piece of content assigned to a term

Example Taxonomy: Movie Website

Let’s assume you are making a website about movies. You may want to include the following taxonomies:

  • Actors
  • Directors
  • Studios
  • Genre
  • Year
  • Awards

Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the front matter of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.

Movie Taxonomy Organization

To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:

Actor                    <- Taxonomy
    Bruce Willis         <- Term
        The Sixth Sense  <- Value
        Unbreakable      <- Value
        Moonrise Kingdom <- Value
    Samuel L. Jackson    <- Term
        Unbreakable      <- Value
        The Avengers     <- Value
        xXx              <- Value

From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:

Unbreakable                 <- Value
    Actors                  <- Taxonomy
        Bruce Willis        <- Term
        Samuel L. Jackson   <- Term
    Director                <- Taxonomy
        M. Night Shyamalan  <- Term
    ...
Moonrise Kingdom            <- Value
    Actors                  <- Taxonomy
        Bruce Willis        <- Term
        Bill Murray         <- Term
    Director                <- Taxonomy
        Wes Anderson        <- Term
    ...

Hugo Taxonomy Defaults

Hugo natively supports taxonomies.

Without adding a single line to your site config file, Hugo will automatically create taxonomies for tags and categories. That would be the same as manually configuring your taxonomies as below:

     
taxonomies:
  category: categories
  tag: tags
[taxonomies]
  category = 'categories'
  tag = 'tags'

{
   "taxonomies": {
      "category": "categories",
      "tag": "tags"
   }
}

If you do not want Hugo to create any taxonomies, set disableKinds in your site config to the following:

     
disableKinds:
- taxonomy
- term
disableKinds = ['taxonomy', 'term']
{
   "disableKinds": [
      "taxonomy",
      "term"
   ]
}

We have fixed the before confusing page kinds used for taxonomies (see the listing below) to be in line with the terms used when we talk about taxonomies. We have been careful to avoid site breakage, and you should get an ERROR in the console if you need to adjust your disableKinds section.

Kind Description Example
home The landing page for the home page /index.html
page The landing page for a given page my-post page (/posts/my-post/index.html)
section The landing page of a given section posts section (/posts/index.html)
taxonomy The landing page for a taxonomy tags taxonomy (/tags/index.html)
term The landing page for one taxonomy’s term term awesome in tags taxonomy (/tags/awesome/index.html)

Default Destinations

When taxonomies are used—and taxonomy templates are provided—Hugo will automatically create both a page listing all the taxonomy’s terms and individual pages with lists of content associated with each term. For example, a categories taxonomy declared in your configuration and used in your content front matter will create the following pages:

  • A single page at example.com/categories/ that lists all the terms within the taxonomy
  • Individual taxonomy list pages (e.g., /categories/development/) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file’s front matter

Configure Taxonomies

Custom taxonomies other than the defaults must be defined in your site config before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, singular key = "plural value" for TOML and singular key: "plural value" for YAML.

Example: Adding a custom taxonomy named “series”

While adding custom taxonomies, you need to put in the default taxonomies too, if you want to keep them.

     
taxonomies:
  category: categories
  series: series
  tag: tags
[taxonomies]
  category = 'categories'
  series = 'series'
  tag = 'tags'

{
   "taxonomies": {
      "category": "categories",
      "series": "series",
      "tag": "tags"
   }
}

Example: Removing default taxonomies

If you want to have just the default tags taxonomy, and remove the categories taxonomy for your site, you can do so by modifying the taxonomies value in your site config.

     
taxonomies:
  tag: tags
[taxonomies]
  tag = 'tags'

{
   "taxonomies": {
      "tag": "tags"
   }
}

If you want to disable all taxonomies altogether, see the use of disableKinds in Hugo Taxonomy Defaults.

You can add content and front matter to your taxonomy list and taxonomy terms pages. See Content Organization for more information on how to add an _index.md for this purpose.

Much like regular pages, taxonomy list permalinks are configurable, but taxonomy term page permalinks are not.

The configuration option preserveTaxonomyNames was removed in Hugo 0.55.

You can now use .Page.Title on the relevant taxonomy node to get the original value.

Add Taxonomies to Content

Once a taxonomy is defined at the site level, any piece of content can be assigned to it, regardless of content type or content section.

Assigning content to a taxonomy is done in the front matter. Simply create a variable with the plural name of the taxonomy and assign all terms you want to apply to the instance of the content type.

If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on Hugo archetypes.

Example: Front Matter with Taxonomies

     
categories:
- Development
project_url: https://github.com/gohugoio/hugo
series:
- Go Web Dev
slug: hugo
tags:
- Development
- Go
- fast
- Blogging
title: 'Hugo: A fast and flexible static site generator'
categories = ['Development']
project_url = 'https://github.com/gohugoio/hugo'
series = ['Go Web Dev']
slug = 'hugo'
tags = ['Development', 'Go', 'fast', 'Blogging']
title = 'Hugo: A fast and flexible static site generator'
{
   "categories": [
      "Development"
   ],
   "project_url": "https://github.com/gohugoio/hugo",
   "series": [
      "Go Web Dev"
   ],
   "slug": "hugo",
   "tags": [
      "Development",
      "Go",
      "fast",
      "Blogging"
   ],
   "title": "Hugo: A fast and flexible static site generator"
}

Order Taxonomies

A content file can assign weight for each of its associate taxonomies. Taxonomic weight can be used for sorting or ordering content in taxonomy list templates and is declared in a content file’s front matter. The convention for declaring taxonomic weight is taxonomyname_weight.

The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the “a”, “b” and “c” values of the tags taxonomy. It has also been assigned the weight of 44 when rendering the “d” category page.

Example: Taxonomic weight

     
categories:
- d
categories_weight: 44
tags:
- a
- b
- c
tags_weight: 22
title: foo
categories = ['d']
categories_weight = 44
tags = ['a', 'b', 'c']
tags_weight = 22
title = 'foo'
{
   "categories": [
      "d"
   ],
   "categories_weight": 44,
   "tags": [
      "a",
      "b",
      "c"
   ],
   "tags_weight": 22,
   "title": "foo"
}

By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.

Currently taxonomies only support the default weight => date ordering of list content. For more information, see the documentation on taxonomy templates.

Add custom metadata to a Taxonomy or Term

If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at /content/<TAXONOMY>/<TERM>/_index.md and add your metadata in it’s front matter. Continuing with our ‘Actors’ example, let’s say you want to add a Wikipedia page link to each actor. Your terms pages would be something like this:

/content/actors/bruce-willis/_index.md
---
title: "Bruce Willis"
wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
---

See Also

  • Taxonomy Templates
  • Archetypes
  • Lists of Content in Hugo
  • Taxonomy Variables
  • Front Matter
  • About Hugo
    • Overview
    • Hugo's Security Model
    • Hugo and GDPR
    • What is Hugo
    • Hugo Features
    • The Benefits of Static
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
    • External Learning Resources
  • Hugo Modules
    • Hugo Modules Overview
    • Configure Modules
    • Use Hugo Modules
    • Theme Components
  • Content Management
    • Content Management Overview
    • Organization
    • Page Bundles
    • Content Formats
    • Front Matter
    • Build Options
    • Page Resources
    • Image Processing
    • Shortcodes
    • Related Content
    • Sections
    • Content Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Static Files
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .HasMenuCurrent
    • .IsMenuCurrent
    • .Param
    • .Render
    • .RenderString
    • .Scratch
    • .Unix
    • absLangURL
    • absURL
    • after
    • anchorize
    • append
    • apply
    • base64
    • chomp
    • complement
    • cond
    • countrunes
    • countwords
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • errorf and warnf
    • fileExists
    • findRE
    • first
    • float
    • ge
    • getenv
    • group
    • gt
    • hasPrefix
    • highlight
    • hmac
    • htmlEscape
    • htmlUnescape
    • hugo
    • humanize
    • i18n
    • Image Functions
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang
    • lang.Merge
    • last
    • le
    • len
    • lower
    • lt
    • markdownify
    • Math
    • md5
    • merge
    • ne
    • now
    • os.Stat
    • partialCached
    • path.Base
    • path.Dir
    • path.Ext
    • path.Join
    • path.Split
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • reflect.IsMap
    • reflect.IsSlice
    • relLangURL
    • relref
    • relURL
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • site
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.Count
    • strings.HasSuffix
    • strings.Repeat
    • strings.RuneCount
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • symdiff
    • templates.Exists
    • time
    • time.Format
    • title
    • transform.Unmarshal
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Pages Methods
    • Taxonomy Variables
    • File Variables
    • Menu Entry Properties
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • Hugo Pipes
    • Hugo Pipes Overview
    • Hugo Pipes Introduction
    • SASS / SCSS
    • PostProcess
    • PostCSS
    • JavaScript Building
    • Babel
    • Asset minification
    • Asset bundling
    • Fingerprinting and SRI
    • Resource from Template
    • Resource from String
  • CLI
  • Troubleshooting
    • Troubleshoot
    • FAQ
    • Build Performance
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Hugo Deploy
    • Host-Agnostic Deploys with Nanobox
    • Host on AWS Amplify
    • Host on Netlify
    • Host on Render
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Hosting on KeyCDN
    • Host on Bitbucket
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
  • Maintenance
“Taxonomies” was last updated: June 27, 2021: 初始提交 (9b77574)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • Discuss Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 
 

Hugo Sponsors

Logo for Linode
Logo for eSolia
Logo for Brave
 

The Hugo logos are copyright © Steve Francia 2013–2021.

The Hugo Gopher is based on an original work by Renée French.

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Hugo Modules
  • Content Management
  • Templates
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute
  • Maintenance