From 1d0d280e2080c30f83b6cff8914b63fadc1b1901 Mon Sep 17 00:00:00 2001 From: spf13 Date: Thu, 31 Oct 2013 09:51:13 -0400 Subject: [PATCH] Addition of an indexes section to the docs. Updated most of the existing index content. --- docs/content/extras/indexes.md | 222 ------------------ docs/content/{extras => }/indexes/category.md | 9 +- docs/content/indexes/displaying.md | 109 +++++++++ docs/content/indexes/lists.md | 74 ++++++ docs/content/indexes/overview.md | 75 ++++++ docs/content/indexes/templates.md | 55 +++++ docs/content/layout/go-templates.md | 3 +- docs/layouts/chrome/menu.html | 8 + 8 files changed, 328 insertions(+), 227 deletions(-) delete mode 100644 docs/content/extras/indexes.md rename docs/content/{extras => }/indexes/category.md (86%) create mode 100644 docs/content/indexes/displaying.md create mode 100644 docs/content/indexes/lists.md create mode 100644 docs/content/indexes/overview.md create mode 100644 docs/content/indexes/templates.md diff --git a/docs/content/extras/indexes.md b/docs/content/extras/indexes.md deleted file mode 100644 index d604aefcf..000000000 --- a/docs/content/extras/indexes.md +++ /dev/null @@ -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.
-**.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 - - - -If you wish to display the list of all indexes, the index can -be retrieved from the `.Site` variable. - -#### 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 }}

-
    - {{ $data := .Data }} - {{ range $key, $value := .Data.Index }} -
  • {{ $key }} {{ len $value }}
    • - {{ end }} -
-
-
- - {{ template "chrome/footer.html" }} - - -#### Example indexes.html file (ordered) - - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} - -
-
-

{{ .Title }}

-
    - {{ range $data.OrderedIndex }} -
  • {{ .Name }} {{ .Count }}
    • - {{ end }} -
-
-
- - {{ 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
- -## 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 - - - diff --git a/docs/content/extras/indexes/category.md b/docs/content/indexes/category.md similarity index 86% rename from docs/content/extras/indexes/category.md rename to docs/content/indexes/category.md index 1d9a1ad54..991598914 100644 --- a/docs/content/extras/indexes/category.md +++ b/docs/content/indexes/category.md @@ -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. diff --git a/docs/content/indexes/displaying.md b/docs/content/indexes/displaying.md new file mode 100644 index 000000000..1622cef54 --- /dev/null +++ b/docs/content/indexes/displaying.md @@ -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 + + + +# 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 + + + +## 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 + + + + +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 + + + +Or order the keys by Popularity +#### Example menu.html file using a single index + diff --git a/docs/content/indexes/lists.md b/docs/content/indexes/lists.md new file mode 100644 index 000000000..c3da35102 --- /dev/null +++ b/docs/content/indexes/lists.md @@ -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" . }} + +
+
+

{{ .Title }}

+
    + {{ $data := .Data }} + {{ range $key, $value := .Data.Index.Alphabetical }} +
  • {{ $value.Name }} {{ $value.Count }}
    • + {{ end }} +
+
+
+ + {{ template "chrome/footer.html" }} + + +#### Example indexes.html file (ordered) + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+
    + {{ $data := .Data }} + {{ range $key, $value := .Data.Index.ByCount }} +
  • {{ $value.Name }} {{ $value.Count }}
    • + {{ end }} +
+
+
+ + {{ template "chrome/footer.html" }} + +### Variables available to list 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 Index itself
+**.Data.Index.Alphabetical** The Index alphabetized
+**.Data.Index.ByCount** The Index ordered by popularity
diff --git a/docs/content/indexes/overview.md b/docs/content/indexes/overview.md new file mode 100644 index 000000000..1c8193a01 --- /dev/null +++ b/docs/content/indexes/overview.md @@ -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" + } + diff --git a/docs/content/indexes/templates.md b/docs/content/indexes/templates.md new file mode 100644 index 000000000..89cc64101 --- /dev/null +++ b/docs/content/indexes/templates.md @@ -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.
+**.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" }} + diff --git a/docs/content/layout/go-templates.md b/docs/content/layout/go-templates.md index 403bfdd64..b9a8f5838 100644 --- 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. diff --git a/docs/layouts/chrome/menu.html b/docs/layouts/chrome/menu.html index 2260df4d9..178265fbd 100644 --- a/docs/layouts/chrome/menu.html +++ b/docs/layouts/chrome/menu.html @@ -37,6 +37,14 @@ {{ end }} +
  • + Indexes + +
  • Extras