mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
Addition of an indexes section to the docs. Updated most of the existing index content.
This commit is contained in:
spf13
parent
a7dae30a8f
commit
1d0d280e20
8 changed files with 328 additions and 227 deletions
|
|
@ -1,222 +0,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>
|
||||
|
||||
|
|
@ -1,12 +1,13 @@
|
|||
---
|
||||
title: "Index Category Example"
|
||||
title: "Example Index - Category"
|
||||
date: "2013-07-01"
|
||||
linktitle: "Example - Categories"
|
||||
groups: ["extras"]
|
||||
groups_weight: 40
|
||||
aliases: ["/extras/indexes/category"]
|
||||
groups: ["indexes"]
|
||||
groups_weight: 60
|
||||
---
|
||||
|
||||
This page demonstrates an example of using indexes to provide categories for your site.
|
||||
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.
|
||||
109
docs/content/indexes/displaying.md
Normal file
109
docs/content/indexes/displaying.md
Normal file
|
|
@ -0,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>
|
||||
74
docs/content/indexes/lists.md
Normal file
74
docs/content/indexes/lists.md
Normal file
|
|
@ -0,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>
|
||||
75
docs/content/indexes/overview.md
Normal file
75
docs/content/indexes/overview.md
Normal file
|
|
@ -0,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"
|
||||
}
|
||||
|
||||
55
docs/content/indexes/templates.md
Normal file
55
docs/content/indexes/templates.md
Normal file
|
|
@ -0,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" }}
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -37,6 +37,14 @@
|
|||
{{ end }}
|
||||
</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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue