diff --git a/docs/content/doc/indexes.md b/docs/content/doc/indexes.md new file mode 100644 index 000000000..de9bb78ad --- /dev/null +++ b/docs/content/doc/indexes.md @@ -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.
+**.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" . }} + +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ + + + {{ 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 + + + +## 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" . }} + +
+
+

{{ .Title }}

+ +
+
+ + {{ template "chrome/footer.html" }} + + +#### Example indexes.html file (ordered) + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+ +
+
+ + {{ 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
+ diff --git a/docs/layouts/chrome/menu.html b/docs/layouts/chrome/menu.html index 6ea0c37c0..e0eaf7b23 100644 --- a/docs/layouts/chrome/menu.html +++ b/docs/layouts/chrome/menu.html @@ -18,6 +18,7 @@
  • ShortCodes
  • +
  • Indexes
  • Release Notes
  • @@ -25,4 +26,4 @@
  • Contributing
  • Contributors
  • License
  • - \ No newline at end of file +