hugo/docs/content/extras/indexes.md

title	date	aliases
Indexes	2013-07-01	/doc/indexes/

Hugo includes support for user defined indexes of content. In our terminology an index is best thought of as tags applied to content but they can be used for far more than just tags. Other common uses would include categories, groups, series. For the purpose of this document we will just use tags for our example. For a more complete example see spf13.com-hugo.

Defining Indexes for a site

Indexes must be defined in the site configuration, before they can be used throughout the site.

Here is an example configuration in YAML that specifies two indexes. Notice the format is singular key : plural value. While we could use an inflection library to pluralize this, they currently support only a few languages, so instead we've opted for user defined pluralization.

config.yaml

---
indexes:
    tag: "tags"
    topic: "topics"
baseurl: "http://spf13.com/"
title: "Steve Francia is spf13.com"
---

Creating index templates

For each index type a template needs to be provided to render the index page. In the case of tags, this will render the content for /tags/TAGNAME/.

The template must be called the singular name of the index and placed in layouts/indexes

.
└── layouts
    └── indexes
        └── category.html

The template will be provided Data about the index.

Variables

The following variables are available to the index template:

.Title The title for the content.
.Date The date the content is published on.
.Permalink The Permanent link for this page.
.RSSLink Link to the indexes' rss link.
.Data.Pages The content that is assigned this index.
.Data.singular The index itself.

Example

{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Data.Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>

{{ template "chrome/footer.html" }}

Assigning indexes to content

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

Assigning content to an index is done in the front matter. Simply create a variable with the plural name of the index and assign all keys you want this content to match against.

Index values are case insensitive

Example

{
    "title": "Hugo: A fast and flexible static site generator",
    "tags": [
        "Development",
        "golang",
        "Blogging"
    ],
    "slug": "hugo",
    "project_url": "http://github.com/spf13/hugo"
}

Displaying indexes within content

Within your content templates you may wish to display the indexes that that piece of content is assigned to.

Because we are leveraging the front matter system to define indexes for content, the indexes assigned to each content piece are located in the usual place (.Params.plural)

Example

<ul id="tags">
  {{ range .Params.tags }}
    <li><a href="tags/{{ . | urlize }}">{{ . }}</a> </li>
  {{ end }}
</ul>

If you wish to display the list of all indexes, the index can be retrieved from the .Site variable.

Example

<ul id="all-tags">
  {{ range .Site.Indexes.tags }}  
    <li><a href="/tags/{{ .Name | urlize }}">{{ .Name }}</a></li>  
  {{ end }}
</ul>

Creating Indexes of Indexes

Hugo also supports creating pages that list your values for each index along with the number of content items associated with the index key.

This may take the form of a tag cloud or simply a list.

To have hugo create these indexes of indexes pages, simply create a template in indexes called indexes.html

Hugo provides two different versions of the index. One alphabetically sorted, the other sorted by most popular. It's important to recognize that the data structure of the two is different.

Example indexes.html file (alphabetical)

{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
   <ul>
   {{ $data := .Data }}
    {{ range $key, $value := .Data.Index }}
    <li><a href="{{ $data.Plural }}/{{ $key | urlize }}"> {{ $key }} </a> {{ len $value }} </li>
    {{ end }}
   </ul>
  </div>
</section>

{{ template "chrome/footer.html" }}

Example indexes.html file (ordered)

{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
   <ul>
    {{ range $data.OrderedIndex }}
    <li><a href="{{ $data.Plural }}/{{ .Name | urlize }}"> {{ .Name }} </a> {{ .Count }} </li>
    {{ end }}
   </ul>
  </div>
</section>

{{ template "chrome/footer.html" }}

Variables available to indexes of indexes pages.

.Title The title for the content.
.Date The date the content is published on.
.Permalink The Permanent link for this page.
.RSSLink Link to the indexes' rss link.
.Data.Singular The singular name of the index
.Data.Plural The plural name of the index
.Data.Index The Alphabetical index
.Data.OrderedIndex The popular index

Creating a menu based on indexes

Hugo can generate menus based on indexes by iterating and nesting the index keys. This can be used to build a hierarchy of content within your site.

To have hugo create the menu, simply create a template in chome called menu.html, then include it using the {{ template "chrome/menu.html" . }} syntax.

Example menu.html file

<section id="menu">
  <ul>
    {{ range $indexname, $index := .Site.Indexes }}
      <li><a href="/{{ $indexname | urlize }}">{{ $indexname }}</a> 
        <ul> 
          {{ range $index }}
            <li><a href="/{{ $indexname | urlize }}/{{ .Name | urlize }}">{{ .Name }}</a></li>
          {{ end }}
        </ul>
      </li> 
    {{ end }}
  </ul>
</section>