mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
Including documentation on indexes
This commit is contained in:
parent
dff86cb22c
commit
def5f10183
2 changed files with 185 additions and 1 deletions
183
docs/content/doc/indexes.md
Normal file
183
docs/content/doc/indexes.md
Normal 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>
|
||||
|
|
@ -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>
|
||||
|
|
Loading…
Reference in a new issue