ref: def5f10183833f9e081c3cf6089d7a19b2207559
parent: dff86cb22cef661ef9e5c2d425784d9a255b7f8d
author: spf13 <[email protected]>
date: Fri Aug 2 23:29:49 EDT 2013
Including documentation on indexes
--- /dev/null
+++ b/docs/content/doc/indexes.md
@@ -1,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>
+
--- a/docs/layouts/chrome/menu.html
+++ b/docs/layouts/chrome/menu.html
@@ -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>
\ No newline at end of file
+ </ul>