ref: 1d0d280e2080c30f83b6cff8914b63fadc1b1901
parent: a7dae30a8f9373d8536c2e7a3e8bdaa79735719c
author: spf13 <[email protected]>
date: Thu Oct 31 05:51:13 EDT 2013
Addition of an indexes section to the docs. Updated most of the existing index content.
--- a/docs/content/extras/indexes.md
+++ /dev/null
@@ -1,222 +1,0 @@
----
-title: "Indexes"
-date: "2013-07-01"
-aliases: ["/doc/indexes/"]
-groups: ["extras"]
-groups_weight: 30
----
-
-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>
-
- {{ 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. <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>
-
-## 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>
-
--- a/docs/content/extras/indexes/category.md
+++ /dev/null
@@ -1,57 +1,0 @@
----
-title: "Index Category Example"
-date: "2013-07-01"
-linktitle: "Example - Categories"
-groups: ["extras"]
-groups_weight: 40
----
-
-This page demonstrates an example of using indexes to provide categories for your site.
-
-### config.yaml
-First step is to define the index in your config file.
-*Because we use both the singular and plural name of the index in our rendering it's
-important to provide both here. We require this, rather than using inflection in
-effort to support as many languages as possible.*
-
- ---
- indexes:
- category: "categories"
- baseurl: "http://spf13.com/"
- title: "Steve Francia is spf13.com"
- ---
-
-### /layouts/indexes/category.html
-
-For each index type a template needs to be provided to render the index page.
-In the case of categories, this will render the content for /categories/CATEGORYNAME/.
-
- {{ 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
-
-Make sure that the index is set in the front matter:
-
- {- "title": "Hugo: A fast and flexible static site generator",
- "categories": [
- "Development",
- "golang",
- "Blogging"
- ],
- "slug": "hugo"
- }
-
--- /dev/null
+++ b/docs/content/indexes/category.md
@@ -1,0 +1,58 @@
+---
+title: "Example Index - Category"
+date: "2013-07-01"
+linktitle: "Example - Categories"
+aliases: ["/extras/indexes/category"]
+groups: ["indexes"]
+groups_weight: 60
+---
+
+This page demonstrates what would be required to add a new index called "categories" to your site.
+
+### config.yaml
+First step is to define the index in your config file.
+*Because we use both the singular and plural name of the index in our rendering it's
+important to provide both here. We require this, rather than using inflection in
+effort to support as many languages as possible.*
+
+ ---
+ indexes:
+ category: "categories"
+ baseurl: "http://spf13.com/"
+ title: "Steve Francia is spf13.com"
+ ---
+
+### /layouts/indexes/category.html
+
+For each index type a template needs to be provided to render the index page.
+In the case of categories, this will render the content for /categories/CATEGORYNAME/.
+
+ {{ 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
+
+Make sure that the index is set in the front matter:
+
+ {+ "title": "Hugo: A fast and flexible static site generator",
+ "categories": [
+ "Development",
+ "golang",
+ "Blogging"
+ ],
+ "slug": "hugo"
+ }
+
--- /dev/null
+++ b/docs/content/indexes/displaying.md
@@ -1,0 +1,109 @@
+---
+title: "Rendering Indexes"
+date: "2013-07-01"
+linktitle: "Displaying"
+groups: ["indexes"]
+groups_weight: 20
+---
+# For Content
+### Index values assigned to this 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>
+
+# Anywhere
+### Displaying all keys for an index
+
+If you wish to display the list of all keys for an index you can
+find retrieve them from the `.Site` variable.
+
+This may take the form of a tag cloud, a menu or simply a list.
+
+The following example displays all tag keys:
+
+#### Example
+
+ <ul id="all-tags">
+ {{ range .Site.Indexes.tags }}+ <li><a href="/tags/{{ .Name | urlize }}">{{ .Name }}</a></li> + {{ end }}+ </ul>
+
+## 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 chrome
+called menu.html, then include it using the
+`{{ template "chrome/menu.html" . }}` syntax.+
+
+This example will list all indexes, each of their keys and all the content assigned to each key.
+#### Example complete menu.html file
+
+ <section id="menu">
+ <ul>
+ {{ range $indexname, $index := .Site.Indexes }}+ <li><a href="/{{ $indexname | urlize }}">{{ $indexname }}</a> + <ul>
+ {{ range $key, $value := $index }}+ <li> {{ $key }} </li>+ <ul>
+ {{ range $value.Pages }}+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>+ {{ end }}+ </ul>
+ {{ end }}+ </ul>
+ </li>
+ {{ end }}+ </ul>
+ </section>
+
+
+It is more likely that you would want to use a single index for navigation.
+In this example we are using the `groups` index for our menu.
+#### Example menu.html file using a single index
+
+ <section id="menu">
+ <ul>
+ {{ range $key, $index := .Site.Indexes.groups }}+ <li> {{ $key }} </li>+ <ul>
+ {{ range $index.Pages }}+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>+ {{ end }}+ </ul>
+ {{ end }}+ </ul>
+ </section>
+
+Or order the keys by Popularity
+#### Example menu.html file using a single index
+ <section id="menu">
+ <ul>
+ {{ range .Site.Indexes.groups.ByCount }}+ <li> {{ .Name }} </li>+ <ul>
+ {{ range .Pages }}+ <li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>+ {{ end }}+ </ul>
+ {{ end }}+ </ul>
+ </section>
--- /dev/null
+++ b/docs/content/indexes/lists.md
@@ -1,0 +1,74 @@
+---
+title: "Index Lists"
+date: "2013-07-01"
+aliases: ["/doc/indexes/", "/extras/indexes"]
+linktitle: "Lists"
+groups: ["indexes"]
+groups_weight: 40
+---
+
+An index list is a list of all the keys that are contained in the index. When a
+template is present, this will be rendered at /IndexPlural/
+
+Hugo also supports creating pages that list your values for each index along
+with the number of content items associated with the index key. These are
+global pages, not attached to any specific content, but rather display the meta
+data in aggregate.
+
+To have hugo create these list of indexes pages, simply create a template in
+/layouts/indexes/ called indexes.html
+
+Hugo can order the meta data in two different ways. It can be ordered by the
+number of content assigned to that key or alphabetically.
+
+
+#### 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.Alphabetical }}+ <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </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>
+ {{ $data := .Data }}+ {{ range $key, $value := .Data.Index.ByCount }}+ <li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>+ {{ end }}+ </ul>
+ </div>
+ </section>
+
+ {{ template "chrome/footer.html" }}+
+### Variables available to list 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 Index itself<br>
+**.Data.Index.Alphabetical** The Index alphabetized<br>
+**.Data.Index.ByCount** The Index ordered by popularity<br>
--- /dev/null
+++ b/docs/content/indexes/overview.md
@@ -1,0 +1,75 @@
+---
+title: "Index Overview"
+date: "2013-07-01"
+aliases: ["/doc/indexes/", "/extras/indexes"]
+linktitle: "Overview"
+groups: ["indexes"]
+groups_weight: 10
+---
+
+Hugo includes support for user defined groupings of content called indexes.
+
+Indexes can be used to organize content in a variety of ways. For example, if I
+wanted to use a wordpress style organization I would create two indexes called
+"categories" and "tags". Other common uses would include categories, tags, groups,
+navigation, series and many more. Just think of an index as way to organize similar content.
+
+It's important to understand what Indexes do. At it's most basic form an index
+is simply a map of a key to a list of content values.
+
+In the hugo internals this is stored as Site.Indexes[Plural][key][]pages.
+For example all the content tagged with GoLang would be found at
+Site.Indexes["tags"]["golang"].
+
+For a
+more complete example see the source of [this docs site](http://github.com/spf13/hugo/docs/).
+
+## 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"
+ category: "categories"
+ baseurl: "http://spf13.com/"
+ title: "Steve Francia is spf13.com"
+ ---
+
+
+## Assigning index values 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",
+ "fast",
+ "Blogging"
+ ],
+ "categories" : [
+ "Development"
+ ]
+ "slug": "hugo",
+ "project_url": "http://github.com/spf13/hugo"
+ }
+
--- /dev/null
+++ b/docs/content/indexes/templates.md
@@ -1,0 +1,55 @@
+---
+title: "Index Templates"
+date: "2013-07-01"
+linktitle: "Templates"
+groups: ["indexes"]
+groups_weight: 30
+---
+
+There are two different templates that the use of indexes will require you to provide.
+
+The first is a list of all the content assigned to a specific index key. The
+second is a [list](/indexes/lists/) of all keys for that index. This document
+addresses the template used for the first type.
+
+## 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>
+
+ {{ template "chrome/footer.html" }}+
--- a/docs/content/layout/go-templates.md
+++ b/docs/content/layout/go-templates.md
@@ -1,8 +1,9 @@
---
title: "Go Templates"
date: "2013-07-01"
-groups: ["layout---"]
+groups: ["layout"]
groups_weight: 80
+draft: true
---
Hugo uses the excellent golang html/template library for its template engine.
--- a/docs/layouts/chrome/menu.html
+++ b/docs/layouts/chrome/menu.html
@@ -38,6 +38,14 @@
</ul>
</li>
<li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Indexes <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+ {{ range $key, $value := .Site.Indexes.groups.indexes.Pages }}+ <li hugo-nav="{{$value.RelPermalink}}"><a href="{{$value.Permalink}}"> {{ $value.LinkTitle }} </a> </li>+ {{ end }}+ </ul>
+ </li>
+ <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Extras <b class="caret"></b></a>
<ul class="dropdown-menu">
{{ range $key, $value := .Site.Indexes.groups.extras.Pages }}