Including documentation on indexes

This commit is contained in:
spf13 2013-08-03 03:29:49 -04:00
parent dff86cb22c
commit def5f10183
2 changed files with 185 additions and 1 deletions

183
docs/content/doc/indexes.md Normal file
View file

@ -0,0 +1,183 @@
---
title: "Indexes"
Pubdate: "2013-07-01"
---
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](http://github.com/spf13/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. <br>
**.Date** The date the content is published on.<br>
**.Permalink** The Permanent link for this page.<br>
**.RSSLink** Link to the indexes' rss link. <br>
**.Data.Pages** The content that is assigned this index.<br>
**.Data.`singular`** The index itself.<br>
#### 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>
<aside id="meta"> </aside>
{{ 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>
## 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. <br>
**.Date** The date the content is published on.<br>
**.Permalink** The Permanent link for this page.<br>
**.RSSLink** Link to the indexes' rss link. <br>
**.Data.Singular** The singular name of the index <br>
**.Data.Plural** The plural name of the index<br>
**.Data.Index** The Alphabetical index<br>
**.Data.OrderedIndex** The popular index<br>

View file

@ -18,6 +18,7 @@
<li class="divider"></li>
<li class="nav-header">Extras</li>
<li> <a href="/doc/shortcodes">ShortCodes</a></li>
<li> <a href="/doc/indexes">Indexes</a></li>
<li class="divider"></li>
<li class="nav-header">Meta</li>
<li> <a href="/doc/release-notes">Release Notes</a></li>
@ -25,4 +26,4 @@
<li> <a href="/doc/contributing">Contributing</a></li>
<li> <a href="/doc/contributors">Contributors</a></li>
<li> <a href="/doc/license">License</a></li>
</ul>
</ul>