From 2ff108fcb7059dd9b73526b1bfce42b43579fc25 Mon Sep 17 00:00:00 2001 From: spf13 Date: Fri, 10 Jan 2014 21:19:19 -0500 Subject: [PATCH] Add highlighting of code in documentation and clean up a bunch of the docs. --- docs/content/community/hall-of-fame.md | 10 +- docs/content/community/mailing-list.md | 10 +- docs/content/content/example.md | 44 +++++---- docs/content/content/front-matter.md | 91 ++++++++++-------- docs/content/content/ordering.md | 72 ++++++++------ docs/content/content/organization.md | 64 ++++++------- docs/content/content/sections.md | 10 +- docs/content/content/types.md | 8 +- docs/content/extras/aliases.md | 13 +-- docs/content/extras/shortcodes.md | 102 ++++++++++++++------ docs/content/indexes/category.md | 60 ++++++------ docs/content/indexes/displaying.md | 128 +++++++++++++------------ docs/content/indexes/lists.md | 68 ++++++------- docs/content/indexes/ordering.md | 28 +++--- docs/content/indexes/overview.md | 58 +++++------ docs/content/indexes/templates.md | 32 +++---- docs/content/layout/chrome.md | 75 ++++++++------- docs/content/layout/homepage.md | 50 +++++----- docs/content/layout/indexes.md | 93 +++++++++--------- docs/content/layout/rss.md | 43 +++++---- docs/content/layout/templates.md | 12 +-- docs/content/layout/views.md | 50 +++++----- docs/content/meta/license.md | 13 +-- docs/content/meta/release-notes.md | 14 ++- docs/content/overview/configuration.md | 80 ++++++++-------- 25 files changed, 670 insertions(+), 558 deletions(-) diff --git a/docs/content/community/hall-of-fame.md b/docs/content/community/hall-of-fame.md index 6950b5c7e..df272a7b2 100644 --- a/docs/content/community/hall-of-fame.md +++ b/docs/content/community/hall-of-fame.md @@ -11,8 +11,8 @@ If you want to be added to this page please send a [pull request](https://github -| **Site** | **Source** | **License** | -| -------------------------------------------- | ----------------------------------------------------- | -----------: | -| [hugo](http://hugo.spf13.com) | [source](http://github.com/spf13/hugo/docs) | SIMPL | -| [spf13](http://spf13.com) | [source](http://github.com/spf13/spf13.com) | MIT | -| [Chimera Art Space](http://chimeraarts.org) | [source](https://github.com/chimera/chimeraarts.org) | CC-SA | +| **Site** | **Source** | **License** | +| ------------------------------------------------ | ----------------------------------------------------- | -----------: | +| [hugo](http://hugo.spf13.com) | [source](http://github.com/spf13/hugo/docs) | SIMPL | +| [spf13](http://spf13.com) | [source](http://github.com/spf13/spf13.com) | MIT | +| [Chimera Art Space](http://chimeraarts.org) | [source](https://github.com/chimera/chimeraarts.org) | CC-SA | diff --git a/docs/content/community/mailing-list.md b/docs/content/community/mailing-list.md index 23767bb47..c3867b856 100644 --- a/docs/content/community/mailing-list.md +++ b/docs/content/community/mailing-list.md @@ -7,28 +7,28 @@ groups_weight: 10 Hugo has two mailing lists: -### Announcements +## Announcements Very low traffic. Only releases will be emailed here. https://groups.google.com/forum/#!forum/hugo-announce -### Discussion +## Discussion For all questions and discussions: https://groups.google.com/forum/#!forum/hugo-discuss # Other Resources -### GoNuts +## GoNuts For general go questions or discussion please refer to the go mailing list. https://groups.google.com/forum/#!forum/golang-nuts -### Github Issues +## Github Issues https://github.com/spf13/hugo/issues -### Twitter +## Twitter Hugo doesn't have it's own twitter handle, but feel free to tweet [@spf13](http://twitter.com/spf13). diff --git a/docs/content/content/example.md b/docs/content/content/example.md index 82a086f52..01300d45c 100644 --- a/docs/content/content/example.md +++ b/docs/content/content/example.md @@ -11,34 +11,36 @@ Somethings are better shown than explained. The following is a very basic exampl **mysite/project/nitro.md <- http://mysite.com/project/nitro.html** - --- - Title: "Nitro : A quick and simple profiler for golang" - Description: "" - Keywords: [ "Development", "golang", "profiling" ] - Tags: [ "Development", "golang", "profiling" ] - date: "2013-06-19" - Topics: [ "Development", "GoLang" ] - Slug: "nitro" - project_url: "http://github.com/spf13/nitro" - --- +{{% highlight yaml %}} +--- +Title: "Nitro : A quick and simple profiler for golang" +Description: "" +Keywords: [ "Development", "golang", "profiling" ] +Tags: [ "Development", "golang", "profiling" ] +date: "2013-06-19" +Topics: [ "Development", "GoLang" ] +Slug: "nitro" +project_url: "http://github.com/spf13/nitro" +--- - # Nitro +# Nitro - Quick and easy performance analyzer library for golang. +Quick and easy performance analyzer library for golang. - ## Overview +## Overview - Nitro is a quick and easy performance analyzer library for golang. - It is useful for comparing A/B against different drafts of functions - or different functions. +Nitro is a quick and easy performance analyzer library for golang. +It is useful for comparing A/B against different drafts of functions +or different functions. - ## Implementing Nitro +## Implementing Nitro - Using Nitro is simple. First use go get to install the latest version - of the library. +Using Nitro is simple. First use go get to install the latest version +of the library. - $ go get github.com/spf13/nitro + $ go get github.com/spf13/nitro - Next include nitro in your application. +Next include nitro in your application. +{{% /highlight %}} diff --git a/docs/content/content/front-matter.md b/docs/content/content/front-matter.md index b70cf4ad9..22b0a40df 100644 --- a/docs/content/content/front-matter.md +++ b/docs/content/content/front-matter.md @@ -17,36 +17,41 @@ Supported formats:
### YAML Example - --- - title: "spf13-vim 3.0 release and new website" - description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." - tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] - date: "2012-04-06" - categories: - - "Development" - - "VIM" - slug: "spf13-vim-3-0-release-and-new-website" - --- - Content of the file goes Here +{{% highlight yaml %}} +--- +title: "spf13-vim 3.0 release and new website" +description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date: "2012-04-06" +categories: + - "Development" + - "VIM" +slug: "spf13-vim-3-0-release-and-new-website" +--- +Content of the file goes Here +{{% /highlight %}} ### TOML Example - +++ - title = "spf13-vim 3.0 release and new website" - description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." - tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] - date = "2012-04-06" - categories = [ - "Development", - "VIM" - ] - slug = "spf13-vim-3-0-release-and-new-website" - +++ - Content of the file goes Here +{{% highlight yaml %}} ++++ +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" ++++ +Content of the file goes Here +{{% /highlight %}} ### JSON Example - { +{{% highlight json %}} +{ "title": "spf13-vim 3.0 release and new website", "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], @@ -56,31 +61,33 @@ Supported formats:
"VIM" ], "slug": "spf13-vim-3-0-release-and-new-website", - } - Content of the file goes Here +} +Content of the file goes Here +{{% /highlight %}} -### Variables +## Variables There are a few predefined variables that Hugo is aware of and utilizes. The user can also create any variable they want to. These will be placed into the `.Params` variable available to the templates. **Field names are case insensitive.** -#### Required +### Required -**title** The title for the content.
-**description** The description for the content.
-**date** The date the content will be sorted by.
-**indexes** These will use the field name of the plural form of the index (see tags and categories above) +* **title** The title for the content +* **description** The description for the content +* **date** The date the content will be sorted by +* **indexes** These will use the field name of the plural form of the index (see tags and categories above) -#### Optional +### Optional -**redirect** Mark the post as a redirect post
-**draft** If true the content will not be rendered unless `hugo` is called with -d
-**type** The type of the content (will be derived from the directory automatically if unset).
-**markup** (Experimental) Specify "rst" for reStructuredText (requires - `rst2html`,) or "md" (default) for the Markdown.
-**slug** The token to appear in the tail of the url.
- *or*
-**url** The full path to the content from the web root.
-*If neither is present the filename will be used.* +* **redirect** Mark the post as a redirect post +* **draft** If true the content will not be rendered unless hugo is called with --build-drafts +* **type** The type of the content (will be derived from the directory automatically if unset) +* **markup** (Experimental) Specify "rst" for reStructuredText (requires + `rst2html`,) or "md" (default) for the Markdown +* **slug** The token to appear in the tail of the url + *or*
+* **url** The full path to the content from the web root.
+ +*If neither slug or url is present the filename will be used.* diff --git a/docs/content/content/ordering.md b/docs/content/content/ordering.md index 9379c6f50..c6f48fff7 100644 --- a/docs/content/content/ordering.md +++ b/docs/content/content/ordering.md @@ -10,7 +10,7 @@ In Hugo you have a good degree of control of how your content can be ordered. By default, content is ordered by weight, then by date with the most recent date first. -_Both the date and weight fields are optional._ +_Both the date and weight fields are optional._ Unweighted pages appear at the end of the list. If no weights are provided (or if weights are the same) date will be used to sort. If neither are provided @@ -29,50 +29,60 @@ Alternative sorting is also available to order content by date (ignoring weight) ## Order by Weight -> Date (default) - {{ range .Data.Pages }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +{{% highlight html %}} +{{ range .Data.Pages }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +{{% /highlight %}} ## Order by Weight -> Date - {{ range .Data.Pages.ByWeight }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +{{% highlight html %}} +{{ range .Data.Pages.ByWeight }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +{{% /highlight %}} ## Order by Date - {{ range .Data.Pages.ByDate }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +{{% highlight html %}} +{{ range .Data.Pages.ByDate }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +{{% /highlight %}} ## Order by Length - {{ range .Data.Pages.ByLength }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +{{% highlight html %}} +{{ range .Data.Pages.ByLength }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +{{% /highlight %}} ## Reverse Order Can be applied to any of the above. Using Date for an example. - {{ range .Data.Pages.ByDate.Reverse }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +{{% highlight html %}} +{{ range .Data.Pages.ByDate.Reverse }} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{ end }} +{{% /highlight %}} ## Ordering Content Within Indexes diff --git a/docs/content/content/organization.md b/docs/content/content/organization.md index eda63283e..61ea0a0a4 100644 --- a/docs/content/content/organization.md +++ b/docs/content/content/organization.md @@ -20,26 +20,26 @@ content nested at any level. The top level is special in Hugo and is used as the . └── content ├── post - | ├── firstpost.md // <- http://site.com/post/firstpost/ + | ├── firstpost.md // <- http://1.com/post/firstpost/ | ├── happy - | | └── happiness.md // <- http://site.com/post/happy/happiness/ - | └── secondpost.md // <- http://site.com/post/secondpost/ + | | └── ness.md // <- http://1.com/post/happy/ness/ + | └── secondpost.md // <- http://1.com/post/secondpost/ └── quote - ├── first.md // <- http://site.com/quote/first/ - └── second.md // <- http://site.com/quote/second/ + ├── first.md // <- http://1.com/quote/first/ + └── second.md // <- http://1.com/quote/second/ **Here's the same organization run with hugo -\-uglyurls** . └── content ├── post - | ├── firstpost.md // <- http://site.com/post/firstpost.html + | ├── firstpost.md // <- http://1.com/post/firstpost.html | ├── happy - | | └── happiness.md // <- http://site.com/post/happy/happiness.html - | └── secondpost.md // <- http://site.com/post/secondpost.html + | | └── ness.md // <- http://1.com/post/happy/ness.html + | └── secondpost.md // <- http://1.com/post/secondpost.html └── quote - ├── first.md // <- http://site.com/quote/first.html - └── second.md // <- http://site.com/quote/second.html + ├── first.md // <- http://1.com/quote/first.html + └── second.md // <- http://1.com/quote/second.html ## Destinations @@ -55,28 +55,28 @@ determine the destination of a specific piece of content. The following items are defined in order, latter items in the list will override earlier settings. -#### filename +### filename This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination. -#### slug +### slug Defined in the front matter, the slug can take the place of the filename for the destination. -#### filepath +### filepath The actual path to the file on disk. Destination will create the destination with the same path. Includes [section](/content/sections). -#### section +### section section can be provided in the front matter overriding the section derived from the source content location on disk. See [section](/content/sections). -#### path +### path path can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path. Includes [section](/content/sections). -#### url +### url A complete url can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseurl (starting with a "/"). When a url is provided it will be used exactly. Using url will ignore the @@ -135,23 +135,23 @@ When a url is provided it will be used exactly. Using url will ignore the -section = which type the content is by default - based on content location - front matter overrides +**section** = which type the content is by default + +* based on content location +* front matter overrides + +**slug** = name.ext or name/ + +* based on content-name.md +* front matter overrides + +**path** = section + path to file exluding slug + +* based on path to content location -slug = name.ext or name/ - based on content-name.md - front matter overrides - - -path = section + path to file exluding slug - based on path to content location - - -url = relative url - defined in front matter - overrides all the above - +**url** = relative url +* defined in front matter +* overrides all the above diff --git a/docs/content/content/sections.md b/docs/content/content/sections.md index a01c7b5eb..a2fc155fa 100644 --- a/docs/content/content/sections.md +++ b/docs/content/content/sections.md @@ -15,13 +15,13 @@ The following example site uses two sections, "post" and "quote". . └── content ├── post - | ├── firstpost.md // <- http://site.com/post/firstpost/ + | ├── firstpost.md // <- http://1.com/post/firstpost/ | ├── happy - | | └── happiness.md // <- http://site.com/post/happy/happiness/ - | └── secondpost.md // <- http://site.com/post/secondpost/ + | | └── ness.md // <- http://1.com/post/happy/ness/ + | └── secondpost.md // <- http://1.com/post/secondpost/ └── quote - ├── first.md // <- http://site.com/quote/first/ - └── second.md // <- http://site.com/quote/second/ + ├── first.md // <- http://1.com/quote/first/ + └── second.md // <- http://1.com/quote/second/ ## Sections and Types diff --git a/docs/content/content/types.md b/docs/content/content/types.md index e6f3ec50c..0011a577a 100644 --- a/docs/content/content/types.md +++ b/docs/content/content/types.md @@ -20,16 +20,16 @@ templates that the new type will use. It is essential to provide the single render view template as well as a list view template. -**Step 1:** +### Step 1: Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*. -**Step 2:** +### Step 2: Create a file called single.html inside your directory. *Eg /layouts/post/single.html*. -**Step 3:** +### Step 3: Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/indexes/post.html*. -**Step 4:** +### Step 4: Many sites support rendering content in a few different ways, for instance a single page view and a summary view to be used when displaying a list of contents on a single page. Hugo makes no assumptions here about how you want diff --git a/docs/content/extras/aliases.md b/docs/content/extras/aliases.md index e42e4d76e..fc1390ba7 100644 --- a/docs/content/extras/aliases.md +++ b/docs/content/extras/aliases.md @@ -16,12 +16,13 @@ Luckily, this can be handled easily with aliases in Hugo. ## Example **content/posts/my-awesome-blog-post.md** - - --- - aliases: - - /posts/my-original-url/ - - /2010/even-earlier-url.html - --- +{{% highlight yaml %}} +--- +aliases: + - /posts/my-original-url/ + - /2010/even-earlier-url.html +--- +{{% /highlight %}} Now when you go to any of the aliases locations they will redirect to the page. diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md index 6ddab4088..ed7384d9f 100644 --- a/docs/content/extras/shortcodes.md +++ b/docs/content/extras/shortcodes.md @@ -6,32 +6,72 @@ groups: ["extras"] groups_weight: 10 --- -Because Hugo uses markdown for its content format, it was clear that there's a lot of things that -markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it. +Because Hugo uses markdown for its simple content format, however there's a lot of things that +markdown doesn't support well. -However we cannot accept being constrained by our simple format. Also unacceptable is writing raw +We are unwilling to accept being constrained by our simple format. Also unacceptable is writing raw html in our markdown every time we want to include unsupported content such as a video. To do so is in complete opposition to the intent of using a bare bones format for our content and utilizing templates to apply styling for display. -To avoid both of these limitations Hugo has full support for shortcodes. +To avoid both of these limitations Hugo created shortcodes. -### What is a shortcode? -A shortcode is a simple snippet inside a markdown file that Hugo will render using a template. +## What is a shortcode? +A shortcode is a simple snippet inside a markdown file that Hugo will render using a predefined template. -Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively. -Short codes are space delimited. The first word is always the name of the shortcode. Following the -name are the parameters. The author of the shortcode can choose if the short code -will use positional parameters or named parameters (but not both). A good rule of thumb is that if a -short code has a single required value in the case of the youtube example below then positional -works very well. For more complex layouts with optional parameters named parameters work best. +An example of a shortcode would be `{{% video http://urlToVideo %}}` + +Shortcodes are created by placing a template file in `layouts/shortcodes/`. The +name of the file becomes the name of the shortcode (without the extension). + +In your content files a shortcode can be called by using '{{% name parameters +%}}' respectively. Shortcodes are space delimited (parameters with spaces +can be quoted). + +The first word is always the name of the shortcode. Following +the name are the parameters. + +The author of the shortcode can choose if the short code will use positional +parameters or named parameters (but not both). A good rule of thumb is that if +a short code has a single required value in the case of the youtube example +below then positional works very well. For more complex layouts with optional +parameters named parameters work best. The format for named parameters models that of html with the format name="value" -### Example: youtube -*Example has an extra space so Hugo doesn't actually render it* +Lastly like HTML, shortcodes can be singular or paired. An example of a paired +shortcode would be: - {{ % youtube 09jf3ow9jfw %}} + {{% code_highlight %}} A bunch of code here {{% /code_highlight %}} + +Shortcodes are paired with an opening shortcode identical to a single shortcode +and a closing shortcode. + +## Creating a shortcode + +All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory. + +The template name will be the name of the shortcode. + +**Inside the template** + +To access a parameter by either position or name the index method can be used. + + {{ index .Params 0 }} + or + {{ index .Params "class" }} + +To check if a parameter has been provided use the isset method provided by Hugo. + + {{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }} + +For paired shortcodes the variable .Inner is available which contains all of +the content between the opening and closing shortcodes. **Simply using this +variable is the only difference between single and paired shortcodes.** + +## Single Positional Example: youtube + + {{% youtube 09jf3ow9jfw %}} Would load the template /layouts/shortcodes/youtube.html @@ -50,7 +90,7 @@ This would be rendered as -### Example: image with caption +## Single Named Example: image with caption *Example has an extra space so Hugo doesn't actually render it* {{ % img src="/media/spf13.jpg" title="Steve Francia" %}} @@ -85,23 +125,29 @@ Would be rendered as: +## Paired Example: Highlight +*Hugo already ships with the highlight shortcode* -### Creating a shortcode +*Example has an extra space so Hugo doesn't actually render it*. -All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory. + {{% highlight html %}} + + This HTML + + {{% /highlight %}} -The template name will be the name of the shortcode. +The template for this utilizes the following code (already include in hugo) -**Inside the template** + {{ $lang := index .Params 0 }}{{ highlight .Inner $lang }} -To access a parameter by either position or name the index method can be used. +And will be rendered as: - {{ index .Params 0 }} - or - {{ index .Params "class" }} - -To check if a parameter has been provided use the isset method provided by Hugo. - - {{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }} + 
    <html>
+        <body> This HTML </body>
+    </html>
+
    +Please notice that this template makes use of a hugo specific template function +called highlight which uses pygments to add the highlighting code. +More shortcode examples can be found at [spf13.com](https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes) diff --git a/docs/content/indexes/category.md b/docs/content/indexes/category.md index 991598914..bfedde572 100644 --- a/docs/content/indexes/category.md +++ b/docs/content/indexes/category.md @@ -15,44 +15,50 @@ First step is to define the index in your config file. 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" - --- +{{% highlight yaml %}} +--- +indexes: +category: "categories" +baseurl: "http://spf13.com/" +title: "Steve Francia is spf13.com" +--- +{{% /highlight %}} ### /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/. +In the case of categories, this will render the content for /categories/`CATEGORYNAME`/. - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    +
    +
    +

    {{ .Title }}

    +{{ range .Data.Pages }} +{{ .Render "summary"}} +{{ end }} +
    +
    - {{ template "chrome/footer.html" }} +{{ template "chrome/footer.html" }} +{{% /highlight %}} ### 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" - } +{{% highlight json %}} +{ + "title": "Hugo: A fast and flexible static site generator", + "categories": [ + "Development", + "golang", + "Blogging" + ], + "slug": "hugo" +} +{{% /highlight %}} diff --git a/docs/content/indexes/displaying.md b/docs/content/indexes/displaying.md index 1622cef54..88596e995 100644 --- a/docs/content/indexes/displaying.md +++ b/docs/content/indexes/displaying.md @@ -5,8 +5,8 @@ linktitle: "Displaying" groups: ["indexes"] groups_weight: 20 --- -# For Content -### Index values assigned to this content + +## Rendering 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. @@ -16,31 +16,34 @@ define indexes for content, the indexes assigned to each content piece are located in the usual place (.Params.`plural`) -#### Example +### Example - +{{% highlight html %}} + +{{% /highlight %}} -# Anywhere -### Displaying all keys for an index +## Rendering a Site's Indexes -If you wish to display the list of all keys for an index you can -find retrieve them from the `.Site` variable. +If you wish to display the list of all keys for an index you can find retrieve +them from the `.Site` variable which is available on every page. This may take the form of a tag cloud, a menu or simply a list. The following example displays all tag keys: -#### Example +### Example - +{{% highlight html %}} + +{{% /highlight %}} ## Creating a menu based on indexes @@ -53,57 +56,64 @@ called menu.html, then include it using the `{{ template "chrome/menu.html" . }}` syntax. + +### Example complete menu.html file This example will list all indexes, each of their keys and all the content assigned to each key. -#### Example complete menu.html file - - +{{% highlight html %}} + +{{% /highlight %}} +### menu.html using a single index 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 - +{{% /highlight %}} -Or order the keys by Popularity -#### Example menu.html file using a single index - +{{% /highlight %}} diff --git a/docs/content/indexes/lists.md b/docs/content/indexes/lists.md index c3da35102..552c71fa9 100644 --- a/docs/content/indexes/lists.md +++ b/docs/content/indexes/lists.md @@ -8,7 +8,7 @@ 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/ +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 @@ -22,44 +22,46 @@ 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) +### Example indexes.html file (alphabetical) - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} -
    -
    -

    {{ .Title }}

    -
      - {{ $data := .Data }} - {{ range $key, $value := .Data.Index.Alphabetical }} -
    • {{ $value.Name }} {{ $value.Count }}
      • - {{ end }} -
    -
    -
    +
    +
    +

    {{ .Title }}

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

    {{ .Title }}

    +
      + {{ $data := .Data }} + {{ range $key, $value := .Data.Index.ByCount }} +
    • {{ $value.Name }} {{ $value.Count }}
      • + {{ end }} +
    +
    +
    - {{ 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" }} +{{ template "chrome/footer.html" }} +{{% /highlight %}} ### Variables available to list of indexes pages. diff --git a/docs/content/indexes/ordering.md b/docs/content/indexes/ordering.md index b1952b4c5..6311e68d8 100644 --- a/docs/content/indexes/ordering.md +++ b/docs/content/indexes/ordering.md @@ -17,21 +17,25 @@ Indexes can be ordered by either alphabetical key or by the number of content pi ### Order Alphabetically Example: - +{{% highlight html %}} + +{{% /highlight %}} ### Order by Popularity Example: - +{{% highlight html %}} + +{{% /highlight %}} [See Also Index Lists](/indexes/lists/) diff --git a/docs/content/indexes/overview.md b/docs/content/indexes/overview.md index 1c8193a01..b72c1c5b6 100644 --- a/docs/content/indexes/overview.md +++ b/docs/content/indexes/overview.md @@ -1,5 +1,5 @@ --- -title: "Index Overview" +title: "Indexes" date: "2013-07-01" aliases: ["/doc/indexes/", "/extras/indexes"] linktitle: "Overview" @@ -17,9 +17,9 @@ navigation, series and many more. Just think of an index as way to organize simi 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. +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"]. +`Site.Indexes["tags"]["golang"]`. For a more complete example see the source of [this docs site](http://github.com/spf13/hugo/docs/). @@ -35,16 +35,17 @@ 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" - --- +### config.yaml +{{% highlight yaml %}} +--- +indexes: + tag: "tags" + category: "categories" +baseurl: "http://spf13.com/" +title: "Steve Francia is spf13.com" +--- +{{% /highlight %}} ## Assigning index values to content @@ -57,19 +58,22 @@ 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" - } +### Example + +{{% highlight json %}} +{ + "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" +} +{{% /highlight %}} diff --git a/docs/content/indexes/templates.md b/docs/content/indexes/templates.md index 89cc64101..6181efb44 100644 --- a/docs/content/indexes/templates.md +++ b/docs/content/indexes/templates.md @@ -14,7 +14,7 @@ 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/. +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 @@ -26,7 +26,7 @@ layouts/indexes The template will be provided Data about the index. -### Variables +## Variables The following variables are available to the index template: @@ -37,19 +37,19 @@ The following variables are available to the index template: **.Data.Pages** The content that is assigned this index.
    **.Data.`singular`** The index itself.
    -#### Example +## Example +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} - -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    - - {{ template "chrome/footer.html" }} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{ template "chrome/footer.html" }} +{{% /highlight %}} diff --git a/docs/content/layout/chrome.md b/docs/content/layout/chrome.md index 70b266bc1..782e03dda 100644 --- a/docs/content/layout/chrome.md +++ b/docs/content/layout/chrome.md @@ -30,53 +30,56 @@ used for both nodes and pages we can use the same chrome for both. ## example header.html This header template is used for [spf13.com](http://spf13.com). - - - - +{{% highlight html %}} + + + + - {{ template "chrome/meta.html" . }} + {{ template "chrome/meta.html" . }} - - {{ .Title }} : spf13.com - - {{ if .RSSlink }}{{ end }} - - {{ template "chrome/head_includes.html" . }} - - + + {{ .Title }} : spf13.com + + {{ if .RSSlink }}{{ end }} + {{ template "chrome/head_includes.html" . }} + + +{{% /highlight %}} ## example footer.html This header template is used for [spf13.com](http://spf13.com). - - - - + + + +{{% /highlight %}} **For examples of referencing these templates, see [content templates](/layout/content/) and [homepage templates](/layout/homepage/)** diff --git a/docs/content/layout/homepage.md b/docs/content/layout/homepage.md index 74eb2192f..c3c0f9b7a 100644 --- a/docs/content/layout/homepage.md +++ b/docs/content/layout/homepage.md @@ -12,7 +12,8 @@ variables](/layout/variables/) available to use in the templates. bootstrapping a new site and template.* In addition to the standard node variables, the homepage has access to -all site content accessible from .Data.Pages +all site content accessible from .Data.Pages . Details on how to use this +list of pages can be found in [Lists](/indexes/lists/) ▾ layouts/ @@ -21,32 +22,35 @@ all site content accessible from .Data.Pages ## example index.html This content template is used for [spf13.com](http://spf13.com). -It makes use of [chrome templates](/layout/chrome) - - - - +It makes use of [chrome templates](/layout/chrome) and uses a [List](/indexes/lists/) - {{ template "chrome/meta.html" . }} +{{% highlight html %}} + + + + - - {{ .Site.Title }} - - + {{ template "chrome/meta.html" . }} - {{ template "chrome/head_includes.html" . }} - - + + {{ .Site.Title }} + + - {{ template "chrome/subheader.html" . }} + {{ template "chrome/head_includes.html" . }} + + -
    -
    - {{ range first 10 .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    +{{ template "chrome/subheader.html" . }} - {{ template "chrome/footer.html" }} +
    +
    + {{ range first 10 .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    + +{{ template "chrome/footer.html" }} +{{% /highlight %}} diff --git a/docs/content/layout/indexes.md b/docs/content/layout/indexes.md index 0301e53e1..6f012cd03 100644 --- a/docs/content/layout/indexes.md +++ b/docs/content/layout/indexes.md @@ -43,21 +43,23 @@ It makes use of [chrome templates](/layout/chrome). All examples use a [view](/layout/views/) called either "li" or "summary" which this example site defined. - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} -
    -
    -

    {{ .Title }}

    -
      - {{ range .Data.Pages }} - {{ .Render "li"}} - {{ end }} -
    -
    -
    +
    +
    +

    {{ .Title }}

    +
      + {{ range .Data.Pages }} + {{ .Render "li"}} + {{ end }} +
    +
    +
    - {{ template "chrome/footer.html" }} +{{ template "chrome/footer.html" }} +{{% /highlight %}} ## Example index template (tag.html) This content template is used for [spf13.com](http://spf13.com). @@ -65,20 +67,21 @@ It makes use of [chrome templates](/layout/chrome). All examples use a [view](/layout/views/) called either "li" or "summary" which this example site defined. - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    - - {{ template "chrome/footer.html" }} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{ template "chrome/footer.html" }} +{{% /highlight %}} ## Example listing of indexes template (indexes.html) This content template is used for [spf13.com](http://spf13.com). @@ -95,29 +98,31 @@ the latter uses .Data.OrderedIndex. .Data.Index is alphabetical by key name, whi .Data.Orderedindex is ordered by the quantity of content assigned to that particular index key. In practice you would only use one of these approaches. - {{ template "chrome/header.html" . }} - {{ template "chrome/subheader.html" . }} +{{% highlight html %}} +{{ template "chrome/header.html" . }} +{{ template "chrome/subheader.html" . }} -
    -
    -

    {{ .Title }}

    +
    +
    +

    {{ .Title }}

    -
      - {{ $data := .Data }} - {{ range $key, $value := .Data.Index }} -
    • {{ $key }} {{ len $value }}
      • - {{ end }} -
    -
    +
      + {{ $data := .Data }} + {{ range $key, $value := .Data.Index }} +
    • {{ $key }} {{ len $value }}
      • + {{ end }} +
    +
    - -
    + + - {{ template "chrome/footer.html" }} +{{ template "chrome/footer.html" }} +{{% /highlight %}} diff --git a/docs/content/layout/rss.md b/docs/content/layout/rss.md index 18330ca92..ea6042c37 100644 --- a/docs/content/layout/rss.md +++ b/docs/content/layout/rss.md @@ -21,27 +21,28 @@ all site content accessible from .Data.Pages This rss template is used for [spf13.com](http://spf13.com). It adheres to the ATOM 2.0 Spec. - - - - {{ .Title }} on {{ .Site.Title }} - {{ .Permalink }} - en-us - Steve Francia - Copyright (c) 2008 - 2013, Steve Francia; all rights reserved. - {{ .Date }} - {{ range .Data.Pages }} - - {{ .Title }} - {{ .Permalink }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }} - Steve Francia - {{ .Permalink }} - {{ .Content | html }} - - {{ end }} - - +{{% highlight xml %}} + + + {{ .Title }} on {{ .Site.Title }} + {{ .Permalink }} + en-us + Steve Francia + Copyright (c) 2008 - 2013, Steve Francia; all rights reserved. + {{ .Date }} + {{ range .Data.Pages }} + + {{ .Title }} + {{ .Permalink }} + {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }} + Steve Francia + {{ .Permalink }} + {{ .Content | html }} + + {{ end }} + + +{{% /highlight %}} *Important: Hugo will automatically add the following header line to this file on render...please don't include this in the template as it's not valid HTML.* diff --git a/docs/content/layout/templates.md b/docs/content/layout/templates.md index c79a67a7f..400e429b9 100644 --- a/docs/content/layout/templates.md +++ b/docs/content/layout/templates.md @@ -20,19 +20,19 @@ is a great place to start. There are 6 different kinds of templates that Hugo works with. ### [Homepage](/layout/homepage/) -The homepage of your site. +The homepage of your site ### [RSS](/layout/rss/) -Used to render all rss documents. +Used to render all rss documents ### [Index](/layout/indexes) -Page that list multiple pieces of content. +Page that list multiple pieces of content ### [Content](/layout/content) -Templates to render a single piece of content. +Render a single piece of content ### [Views](/layout/views) -Different ways of rendering each content type +Different view of a single piece of content type ### [Chrome](/layout/chrome) -Simply the decoration of your site. +Support for the above templates diff --git a/docs/content/layout/views.md b/docs/content/layout/views.md index 67a9b4262..ae22211f9 100644 --- a/docs/content/layout/views.md +++ b/docs/content/layout/views.md @@ -43,38 +43,44 @@ variables](/layout/variables) for a complete list. ## Example li.html This content template is used for [spf13.com](http://spf13.com). -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • +{{% highlight html %}} +
  • +{{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{% /highlight %}} ## Example summary.html This content template is used for [spf13.com](http://spf13.com). -
    -
    -

    {{ .Title }}

    -
    {{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words
    -
    +{{% highlight html %}} + +{{ .Summary }} + +
    +{{% /highlight %}} ## Example render of view Using the summary view inside of another ([index](/layout/index)) template. -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    +{{% highlight html %}} +
    +
    +

    {{ .Title }}

    +{{ range .Data.Pages }} +{{ .Render "summary"}} +{{ end }} +
    +
    +{{% /highlight %}} In the above example you will notice that we have called .Render and passed in which view to render the content with. Render is a special function available on diff --git a/docs/content/meta/license.md b/docs/content/meta/license.md index 482145678..f4bfcccbd 100644 --- a/docs/content/meta/license.md +++ b/docs/content/meta/license.md @@ -8,12 +8,9 @@ groups_weight: 50 Hugo is released under the Simple Public License. +## Simple Public License (SimPL-2.0) -Simple Public License (SimPL-2.0) -================================= - -Preamble --------- +### Preamble This Simple Public License 2.0 (SimPL-2.0 for short) is a plain language implementation of GPL 2.0. The words are different, but the goal is the @@ -22,8 +19,7 @@ software. If anyone wonders about the meaning of the SimPL, they should interpret it as consistent with GPL 2.0. -Simple Public License (SimPL) 2.0 -================================= +## Simple Public License (SimPL) 2.0 The SimPL applies to the software's source and object code and comes with any rights that I have in it (other than trademarks). You agree to @@ -68,8 +64,7 @@ automatically if: - Anyone prevents you from distributing the software under the terms of the SimPL. -License for the License ------------------------ +## License for the License You may do anything that you want with the SimPL text; it's a license form to use in any way that you find helpful. To avoid confusion, diff --git a/docs/content/meta/release-notes.md b/docs/content/meta/release-notes.md index f8d835c83..5ddb5c3b3 100644 --- a/docs/content/meta/release-notes.md +++ b/docs/content/meta/release-notes.md @@ -6,7 +6,7 @@ groups: ["meta"] groups_weight: 10 --- -* **0.9.0** +## **0.9.0** November 15, 2013 * New command based interface similar to git (hugo server -s ./ ) * Amber template support * Aliases (redirects) @@ -38,7 +38,8 @@ groups_weight: 10 * Support for go 1.2 * Support for `first` in templates * Support for site per-section permalink pattern specifications -* **0.8.0** August 2, 2013 + +## **0.8.0** August 2, 2013 * Added support for pretty urls (filename/index.html vs filename.html) * Hugo supports a destination directory * Will efficiently sync content in static to destination directory @@ -51,11 +52,14 @@ groups_weight: 10 * Support for series * Adding verbose output * Loads of bugfixes -* **0.7.0** July 4, 2013 + +## **0.7.0** July 4, 2013 * Hugo now includes a simple server * First public release -* **0.6.0** July 2, 2013 + +## **0.6.0** July 2, 2013 * Hugo includes an example documentation site which it builds -* **0.5.0** June 25, 2013 + +## **0.5.0** June 25, 2013 * Hugo is quite usable and able to build spf13.com diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md index 6ac0035de..5721df133 100644 --- a/docs/content/overview/configuration.md +++ b/docs/content/overview/configuration.md @@ -20,33 +20,34 @@ then look for a `config.json` file, followed by a `config.toml` file. ## Examples The following is an example of a yaml config file with the default values: - - --- - contentdir: "content" - layoutdir: "layouts" - publishdir: "public" - builddrafts: false - indexes: - category: "categories" - tag: "tags" - baseurl: "http://yoursite.example.com/" - ... - +{{% highlight yaml %}} +--- +contentdir: "content" +layoutdir: "layouts" +publishdir: "public" +builddrafts: false +indexes: + category: "categories" + tag: "tags" +baseurl: "http://yoursite.example.com/" +... +{{% /highlight %}} The following is an example of a json config file with the default values: - { - "contentdir": "content", - "layoutdir": "layouts", - "publishdir": "public", - "builddrafts": false, - "indexes": { - "category": "categories", - "tag": "tags" - }, - "baseurl": "http://yoursite.example.com/" - } - +{{% highlight json %}} +{ + "contentdir": "content", + "layoutdir": "layouts", + "publishdir": "public", + "builddrafts": false, + "indexes": { + "category": "categories", + "tag": "tags" + }, + "baseurl": "http://yoursite.example.com/" +} +{{% /highlight %}} The following is an example of a toml config file with the default values: @@ -61,18 +62,19 @@ The following is an example of a toml config file with the default values: Here is a yaml configuration file which sets a few more options - --- - baseurl: "http://yoursite.example.com/" - title: "Yoyodyne Widget Blogging" - permalinks: - post: /:year/:month/:title/ - params: - Subtitle: "Spinning the cogs in the widgets" - AuthorName: "John Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 - ... - +{{% highlight yaml %}} +--- +baseurl: "http://yoursite.example.com/" +title: "Yoyodyne Widget Blogging" +permalinks: + post: /:year/:month/:title/ +params: + Subtitle: "Spinning the cogs in the widgets" + AuthorName: "John Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +... +{{% /highlight %}}