github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-07 20:30:36 -05:00
Code Issues Projects Releases Packages Wiki Activity

Complete overhaul of the docs

Browse source
This commit is contained in:
spf13 2013-08-17 08:34:25 -04:00
parent b76b80c564
commit 8c0ab4def1
35 changed files with 971 additions and 151 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
docs/content/doc/example.md → docs/content/content/example.md
View file

@ -1,6 +1,7 @@
---
title: "Example Content File"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/example/"]
---
Somethings are better shown than explained. The following is a very basic example of a content file:
@ -12,7 +13,7 @@ Somethings are better shown than explained. The following is a very basic exampl
Description": ""
Keywords": [ "Development", "golang", "profiling" ]
Tags": [ "Development", "golang", "profiling" ]
Pubdate": "2013-06-19"
date": "2013-06-19"
Topics": [ "Development", "GoLang" ]
Slug": "nitro"
project_url": "http://github.com/spf13/nitro"

5
docs/content/doc/front-matter.md → docs/content/content/front-matter.md
View file

@ -1,6 +1,7 @@
+++
title = "Front Matter"
date = "2013-07-01"
aliases = ["/doc/front-matter/"]
+++
The front matter is one of the features that gives Hugo it's strength. It enables
@ -18,7 +19,7 @@ Supported formats: <br>
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" ]
pubdate: "2012-04-06"
date: "2012-04-06"
categories:
- "Development"
- "VIM"
@ -32,7 +33,7 @@ Supported formats: <br>
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" ]
Pubdate = "2012-04-06"
date = "2012-04-06"
categories = [
"Development",
"VIM"

154
docs/content/content/organization.md Normal file
View file

@ -0,0 +1,154 @@
---
title: "Content Organization"
date: "2013-07-01"
aliases: ["/doc/organization/"]
---
Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization
that you provide for your content to minimize any extra configuration, though this can be overridden
by additional configuration in the front matter.
## Organization
In Hugo the content should be arranged in the same way they are intended for the rendered website.
Without any additional configuration the following will just work. Hugo supports
content nested at any level. The top level is special in Hugo and is used as the
[section](/content/sections).
.
└── content
├── post
| ├── firstpost.md // <- http://site.com/post/firstpost/
| ├── happy
| | └── happiness.md // <- http://site.com/happy/happiness/
| └── secondpost.md // <- http://site.com/post/secondpost/
└── quote
├── first.md // <- http://site.com/quote/first/
└── second.md // <- http://site.com/quote/second/
**Here's the same organization run with hugo -\-uglyurls**
.
└── content
├── post
| ├── firstpost.md // <- http://site.com/post/firstpost.html
| ├── happy
| | └── happiness.md // <- http://site.com/happy/happiness.html
| └── secondpost.md // <- http://site.com/post/secondpost.html
└── quote
├── first.md // <- http://site.com/quote/first.html
└── second.md // <- http://site.com/quote/second.html
## Destinations
Hugo thinks that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site. As displayed above, the organization of the source content will be
mirrored in the destination.
There are times when one would need more control over their content. In these
cases there are a variety of things that can be specified in the front matter to
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
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
Defined in the front matter, the slug can take the place of the filename for the
destination.
#### filepath
The actual path to the file on disk. Destination will create the destination
with the same path. Includes [section](/content/sections).
#### 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 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
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
-\-uglyurls setting.
## Path breakdown in hugo
### Content
. path slug
. ⊢-------^----⊣ ⊢------^-------⊣
content/extras/indexes/category-example/index.html
. section slug
. ⊢--^--⊣ ⊢------^-------⊣
content/extras/indexes/category-example/index.html
. section slug
. ⊢--^--⊣⊢--^--⊣
content/extras/indexes/index.html
### Destination
permalink
⊢--------------^-------------⊣
http://spf13.com/projects/hugo
baseUrl section slug
⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣
http://spf13.com/projects/hugo
baseUrl section slug
⊢-----^--------⊣ ⊢--^--⊣ ⊢--^--⊣
http://spf13.com/extras/indexes/example
baseUrl path slug
⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣
http://spf13.com/extras/indexes/example
baseUrl url
⊢-----^--------⊣ ⊢-----^-----⊣
http://spf13.com/projects/hugo
baseUrl url
⊢-----^--------⊣ ⊢--------^-----------⊣
http://spf13.com/extras/indexes/example
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
url = relative url
defined in front matter
overrides all the above

43
docs/content/content/sections.md Normal file
View file

@ -0,0 +1,43 @@
---
title: "Sections"
date: "2013-07-01"
---
Hugo thinks that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site ( [see organization](/content/organization) ). Following this pattern Hugo
uses the top level of your content organization as **the Section**.
The following example site uses two sections, "post" and "quote".
.
└── content
├── post
| ├── firstpost.md // <- http://site.com/post/firstpost/
| ├── happy
| | └── happiness.md // <- http://site.com/happy/happiness/
| └── secondpost.md // <- http://site.com/post/secondpost/
└── quote
├── first.md // <- http://site.com/quote/first/
└── second.md // <- http://site.com/quote/second/
*Regardless of location on disk, the section can be provided in the front matter
which will affect the destination location*.
## Sections and Types
By default everything created within a section will use the content type
that matches the section name.
Section defined in the front matter have the same impact.
To change the type of a given piece of content simply define the type
in the front matter.
If a layout for a given type hasn't been provided a default type template will
be used instead provided is exists.

49
docs/content/content/types.md Normal file
View file

@ -0,0 +1,49 @@
---
title: "Content Types"
date: "2013-07-01"
---
Hugo has full support for multiple content types each with it's own set
of meta data and template. A good example of when multiple types are
needed is to look a tumblr. A piece of content could be a photo, quote
or post, each with different meta data and rendered differently.
## Defining a content type
Creating a new content type is easy in Hugo. You simply provide the
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:**
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
**Step 2:**
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
**Step 3:**
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
**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
to display your content, and will support as many different views of a content
type as your site requires. All that is required for these additional views is
that a template exists in each layout/type directory with the same name.
For these, reviewing this example site will be very helpful in order to understand how these types work.
## Assigning a content type
Hugo assumes that your site will be organized into [sections](/content/sections)
and each section will use the corresponding type. If you are taking advantage of
this then each new piece of content you place into a section will automatically
inherit the type.
Alternatively you can set the type in the meta data under the key "type".

9
docs/content/doc/contributors.md
View file

@ -1,9 +0,0 @@
---
title: "Contributors"
date: "2013-07-01"
---
Hugo was built with love and golang by:
* [spf13](https://github.com/spf13)

22
docs/content/doc/organization.md
View file

@ -1,22 +0,0 @@
---
title: "Organization"
Pubdate: "2013-07-01"
---
Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization
that you provide for your content to minimize any extra configuration, though this can be overridden
by additional configuration in the front matter.
## Organization
In Hugo the content should be arranged in the same way they are intended for the rendered website.
Without any additional configuration the following will just work.
.
└── content
├── post
| ├── firstpost.md // <- http://site.com/post/firstpost.html
| └── secondpost.md // <- http://site.com/post/secondpost.html
└── quote
├── first.md // <- http://site.com/quote/first.html
└── second.md // <- http://site.com/quote/second.html

66
docs/content/doc/templates.md
View file

@ -1,66 +0,0 @@
---
title: "Templates"
Pubdate: "2013-07-01"
---
Hugo uses the excellent golang html/template library for it's template engine. It is an extremely
lightweight engine that provides a very small amount of logic. In our
experience that it is just the right amount of logic to be able to create a good static website
This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/)
provide a good introduction.
### Template roles
There are 5 different kinds of templates that Hugo works with.
#### index.html
This file must exist in the layouts directory. It is the template used to render the
homepage of your site.
#### rss.xml
This file must exist in the layouts directory. It will be used to render all rss documents.
The one provided in the example application will generate an ATOM format.
*Important: Hugo will automatically add the following header line to this file.*
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
#### Indexes
An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
pages are good examples of indexes.
#### Content Type(s)
Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability
to render content in a variety of ways as determined by the type.
#### Chrome
Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice
it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may
likely find beneficial. As you create the rest of your templates you will include templates from the
/layout/chrome directory. I've found it helpful to include a header and footer template
in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html).
### Adding a new content type
Adding a type is easy.
**Step 1:**
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
**Step 2:**
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
**Step 3:**
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
**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 to display your content, and will support as many different views of a content
type as your site requires. All that is required for these additional views is that a template
exists in each layout/type directory with the same name.
For these, reviewing this example site will be very helpful in order to understand how these types work.

5
docs/content/doc/aliases.md → docs/content/extras/aliases.md
View file

@ -1,9 +1,10 @@
---
title: "Aliases"
Pubdate: "2013-07-09"
Aliases:
date: "2013-07-09"
aliases:
- /doc/redirects/
- /doc/alias/
- /doc/aliases/
---
For people migrating existing published content to Hugo theres a good chance

11
docs/content/doc/indexes.md → docs/content/extras/indexes.md
View file

@ -1,6 +1,7 @@
---
title: "Indexes"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/indexes/"]
---
Hugo includes support for user defined indexes of content. In our
@ -70,8 +71,6 @@ The following variables are available to the index template:
</div>
</section>
<aside id="meta"> </aside>
{{ template "chrome/footer.html" }}
@ -88,13 +87,13 @@ and assign all keys you want this content to match against.
#### Example
{
"Title": "Hugo: A fast and flexible static site generator",
"Tags": [
"title": "Hugo: A fast and flexible static site generator",
"tags": [
"Development",
"golang",
"Blogging"
],
"Slug": "hugo",
"slug": "hugo",
"project_url": "http://github.com/spf13/hugo"
}

54
docs/content/extras/indexes/category.md Normal file
View file

@ -0,0 +1,54 @@
---
title: "Index Category Example"
date: "2013-07-01"
---
This page demonstrates an example of using indexes to provide categories for your site.
### config.yaml
First step is to define the index in your config file.
*Because we use both the singular and plural name of the index in our rendering it's
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"
---
### /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/.
{{ 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
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"
}

0
docs/content/extras/indexes/series.md Normal file
View file

3
docs/content/doc/shortcodes.md → docs/content/extras/shortcodes.md
View file

@ -1,6 +1,7 @@
---
title: "Shortcodes"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/shortcodes/"]
---
Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that

80
docs/content/layout/chrome.md Normal file
View file

@ -0,0 +1,80 @@
---
title: "Chrome Templates"
date: "2013-07-01"
---
Chrome is a convention to create templates that are used by the other templates
throughout the site. There is nothing special about the name "chrome", feel free
to provide and use your own.
It's not a requirement to have this, but in practice it's very convenient. Hugo doesn't
know anything about Chrome, it's simply a convention that you may likely find
beneficial. As you create the rest of your templates you will include templates
from the /layout/chrome directory.
I've found it helpful to include a header and footer template in Chrome so I can
include those in the other full page layouts (index.html, indexes/
type/single.html). There is nothing special about header.html and footer.html
other than they seem like good names to use for inclusion in your other
templates.
▾ layouts/
▾ chrome/
header.html
footer.html
By ensuring that we only reference [variables](/layout/variables/) variables
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).
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
<meta charset="utf-8">
{{ template "chrome/meta.html" . }}
<base href="{{ .Site.BaseUrl }}">
<title> {{ .Title }} : spf13.com </title>
<link rel="canonical" href="{{ .Permalink }}">
{{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
{{ template "chrome/head_includes.html" . }}
</head>
<body lang="en">
## example footer.html
This header template is used for [spf13.com](http://spf13.com).
<footer>
<div>
<p>
&copy; 2013 Steve Francia.
<a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
</p>
</div>
</footer>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</body>
</html>
**For examples of referencing these templates, see [content
templates](/layout/content/) and [homepage templates](/layout/homepage/)**

125
docs/content/layout/content.md Normal file
View file

@ -0,0 +1,125 @@
---
title: "Content Templates"
date: "2013-07-01"
---
Content templates are created in a directory matching the name of the content.
Content pages are of the type "page" and have all the [page
variables](/layout/variables/) available to use in the templates.
In the following examples we have created two different content types as well as
a default content type.
▾ layouts/
▾ post/
single.html
▾ project/
single.html
Hugo also has support for a default content template to be used in the event
that a specific template has not been provided for that type. The default type
works the same as the other types but the directory must be called "_default".
[Content views](/layout/views) can also be defined in the "_default" directory.
▾ layouts/
▾ _default/
single.html
## post/single.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseurl }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
</div>
<div>
<a class="previous" href="{{.Prev.Permalink}}"> {{.Prev.Title}}</a>
<a class="next" href="{{.Next.Permalink}}"> {{.Next.Title}}</a>
</div>
</aside>
{{ template "chrome/disqus.html" . }}
{{ template "chrome/footer.html" . }}
## project/single.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
<article id="content">
{{ .Content }}
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseurl }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
</div>
</aside>
{{if isset .Params "project_url" }}
<div id="ribbon">
<a href="{{ index .Params "project_url" }}" rel="me">Fork me on GitHub</a>
</div>
{{ end }}
{{ template "chrome/footer.html" }}
Notice how the project/single.html template uses an additional parameter unique
to this template. This doesn't need to be defined ahead of time. If the key is
present in the front matter than it can be used in the template.

15
docs/content/layout/go-templates.md Normal file
View file

@ -0,0 +1,15 @@
---
title: "Go Templates"
date: "2013-07-01"
---
Hugo uses the excellent golang html/template library for it's template engine.
It is an extremely lightweight engine that provides a very small amount of
logic. In our experience that it is just the right amount of logic to be able to
create a good static website.
This is a brief primer on using go templates. The [golang
docs](http://golang.org/pkg/html/template/) provide more details.

50
docs/content/layout/homepage.md Normal file
View file

@ -0,0 +1,50 @@
---
title: "Homepage Templates"
date: "2013-07-01"
---
Home pages are of the type "node" and have all the [node
variables](/layout/variables/) available to use in the templates.
*This is the only required template for building a site and useful when
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
▾ layouts/
index.html
## example index.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome)
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
<meta charset="utf-8">
{{ template "chrome/meta.html" . }}
<base href="{{ .Site.BaseUrl }}">
<title>{{ .Site.Title }}</title>
<link rel="canonical" href="{{ .Permalink }}">
<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
{{ template "chrome/head_includes.html" . }}
</head>
<body lang="en">
{{ template "chrome/subheader.html" . }}
<section id="main">
<div>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "chrome/footer.html" }}

122
docs/content/layout/index.md Normal file
View file

@ -0,0 +1,122 @@
---
title: "Index Templates"
date: "2013-07-01"
---
An index template is any template that will be used to render multiple pieces of
content (with the exception of the [homepage](/layout/homepage) which has a
dedicated template).
We are using the term index in it's truest sense, a sequential arrangement of
material, especially in alphabetical or numerical order. In the case of Hugo
each index will render the content in newest first order based on the date
provided in the [front matter](/content/front-matter).
index pages are of the type "node" and have all the [node
variables](/layout/variables/) available to use in the templates.
All index templates live in the layouts/indexes directory. There are 3 different
kinds of indexes that Hugo can produce.
1. A listing of all the content for a given [section](/content/sections)
2. A listing of all the content for a given [index](/extras/indexes)
3. A listing of listings... [meta index](/extras/indexes)
It's critical that the name of the index template matches either:
1. The section name
2. The index singular name
3. "indexes"
The following illustrates the location of one of each of these types.
▾ layouts/
▾ indexes/
indexes.html
post.html
tag.html
## Example section template (post.html)
This content template is used for [spf13.com](http://spf13.com).
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" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul id="list">
{{ range .Data.Pages }}
{{ .Render "li"}}
{{ end }}
</ul>
</div>
</section>
{{ template "chrome/footer.html" }}
## Example index template (tag.html)
This content template is used for [spf13.com](http://spf13.com).
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" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "chrome/footer.html" }}
## Example listing of indexes template (indexes.html)
This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome). The list of indexes
templates cannot use a [content view](/layout/views) as they don't display the content, but
rather information about the content.
This particular template lists all of the Tags used on
[spf13.com](http://spf13.com) and provides a count for the number of pieces of
content tagged with each tag.
This example demonstrates two different approaches. The first uses .Data.Index and
the latter uses .Data.OrderedIndex. .Data.Index is alphabetical by key name, while
.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" . }}
<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>
<ul>
{{ range $data.OrderedIndex }}
<li><a href="{{ $data.Plural }}/{{ .Name | urlize }}"> {{ .Name }} </a> {{ .Count }} </li>
{{ end }}
</ul>
</section>
{{ template "chrome/footer.html" }}

47
docs/content/layout/rss.md Normal file
View file

@ -0,0 +1,47 @@
---
title: "RSS (feed) Templates"
date: "2013-07-01"
---
A single RSS template is used to generate all of the RSS content for the entire
site.
RSS pages are of the type "node" and have all the [node
variables](/layout/variables/) available to use in the templates.
In addition to the standard node variables, the homepage has access to
all site content accessible from .Data.Pages
▾ layouts/
rss.xml
## rss.xml
This rss template is used for [spf13.com](http://spf13.com). It adheres to the
ATOM 2.0 Spec.
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>{{ .Title }} on {{ .Site.Title }} </title>
<link>{{ .Permalink }}</link>
<language>en-us</language>
<author>Steve Francia</author>
<rights>Copyright (c) 2008 - 2013, Steve Francia; all rights reserved.</rights>
<updated>{{ .Date }}</updated>
{{ range .Data.Pages }}
<item>
<title>{{ .Title }}</title>
<link>{{ .Permalink }}</link>
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</pubDate>
<author>Steve Francia</author>
<guid>{{ .Permalink }}</guid>
<description>{{ .Content | html }}</description>
</item>
{{ end }}
</channel>
</rss>
*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.*
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>

35
docs/content/layout/templates.md Normal file
View file

@ -0,0 +1,35 @@
---
title: "Templates"
date: "2013-07-01"
aliases: ["/doc/templates/"]
---
Hugo uses the excellent golang html/template library for it's template engine.
It is an extremely lightweight engine that provides a very small amount of
logic. In our experience that it is just the right amount of logic to be able
to create a good static website
If you are new to go's templates the [go template primer](/layout/go-templates)
is a great place to start.
## Template roles
There are 6 different kinds of templates that Hugo works with.
### [Homepage](/layout/homepage/)
The homepage of your site.
### [RSS](/layout/rss/)
Used to render all rss documents.
### [Indexes](/layout/indexes)
Page that list multiple pieces of content.
### [Content](/layout/content)
Templates to render a single piece of content.
### [Views](/layout/views)
Different ways of rendering each content type
### [Chrome](/layout/chrome)
Simply the decoration of your site.

27
docs/content/doc/variables.md → docs/content/layout/variables.md
View file

@ -1,11 +1,14 @@
---
title: "Variables"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/variables/"]
---
Hugo makes a set of values available to the templates. Go templates are context based. The following
are available in the context for the templates.
## Page Variables
**.Title** The title for the content.<br>
**.Description** The description for the content.<br>
**.Keywords** The meta keywords for this content.<br>
@ -16,13 +19,28 @@ are available in the context for the templates.
**.RSSLink** Link to the indexes' rss link <br>
**.Prev** Pointer to the previous content (based on pub date)<br>
**.Next** Pointer to the following content (based on pub date)<br>
**.Site** See site variables below<br>
**.Content** The content itself, defined below the front matter.<br>
Any value defined in the front matter, including indexes will be made available under `.Params`.
Any value defined in the front matter, including indexes will be made available under `.Params`.
Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
**.Params.Tags** <br>
**.Params.Categories** <br>
**.Params.Tags** <br>
**.Params.Categories** <br>
## Node Variables
In Hugo a node is any page not rendered directly by a content file. This
includes indexes, lists and the homepage.
**.Title** The title for the content.<br>
**.Date** The date the content is published on.<br>
**.Data** The data specific to this type of node.<br>
**.Permalink** The Permanent link for this node<br>
**.Url** The relative url for this node.<br>
**.RSSLink** Link to the indexes' rss link <br>
**.Site** See site variables below<br>
## Site Variables
Also available is `.Site` which has the following:
@ -30,3 +48,4 @@ Also available is `.Site` which has the following:
**.Site.Indexes** The names of the indexes of the site.<br>
**.Site.LastChange** The date of the last change of the most recent content.<br>
**.Site.Recent** Array of all content ordered by Date, newest first<br>

79
docs/content/layout/views.md Normal file
View file

@ -0,0 +1,79 @@
---
title: "Content Views"
date: "2013-07-01"
---
In addition to the [single content view](/layout/content/), Hugo can render alternative views of
your content. These are especially useful in [index](/layout/index) templates.
To create a new view simple create a template in each of your different content
type directories with the view name. In the following example we have created a
"li" view and a "summary" view for our two content types of post and project. As
you can see these sit next to the [single content view](/layout/content)
template "single.html"
▾ layouts/
▾ post/
li.html
single.html
summary.html
▾ project/
li.html
single.html
summary.html
Hugo also has support for a default content template to be used in the event
that a specific template has not been provided for that type. The default type
works the same as the other types but the directory must be called "_default".
Content views can also be defined in the "_default" directory.
▾ layouts/
▾ _default/
li.html
single.html
summary.html
Hugo will pass the entire page object to the view template. See [page
variables](/layout/variables) for a complete list.
## Example li.html
This content template is used for [spf13.com](http://spf13.com).
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
## Example summary.html
This content template is used for [spf13.com](http://spf13.com).
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
</header>
{{ .Summary }}
<footer>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer>
</article>
## Example render of view
Using the summary view inside of another ([index](/layout/index)) template.
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
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
a content which tells the content to render itself with the provided view template.

15
docs/content/doc/contributing.md → docs/content/meta/contributing.md
View file

@ -1,15 +1,16 @@
---
title: "Contributing to Hugo"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/contributing/"]
---
We welcome all contributions. If you want to contribute, all
that is needed is simply fork Hugo, make changes and submit
We welcome all contributions. If you want to contribute, all
that is needed is simply fork Hugo, make changes and submit
a pull request. If you prefer, pick something from the roadmap
or contact [spf13](http://spf13.com) about what may make sense
or contact [spf13](http://spf13.com) about what may make sense
to do next.
## Overview
## Overview
1. Fork it from https://github.com/spf13/hugo
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
@ -23,8 +24,8 @@ to do next.
cd hugo
go get
Because go expects all of your libraries to be found in either
$GOROOT or $GOPATH, it's helpful to symlink the project to one
Because go expects all of your libraries to be found in either
$GOROOT or $GOPATH, it's helpful to symlink the project to one
of the following paths:
* ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo

12
docs/content/meta/contributors.md Normal file
View file

@ -0,0 +1,12 @@
---
title: "Contributors"
date: "2013-07-01"
aliases: ["/doc/contributors/"]
---
Hugo was built with love and golang by:
* Steve Francia - [spf13](https://github.com/spf13)
* Noah Campbell - [noahcampbell](https://github.com/noahcampbell)
* [Many more](http://github.com/spf13/hugo/graphs/contributors)

3
docs/content/doc/license.md → docs/content/meta/license.md
View file

@ -1,6 +1,7 @@
---
title: "License"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/license/", "/license/"]
---
Hugo is released under the Simple Public License.

11
docs/content/doc/release-notes.md → docs/content/meta/release-notes.md
View file

@ -1,10 +1,17 @@
---
title: "Release Notes"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/release-notes/"]
---
* **0.9.0**
* **0.9.0** HEAD
* Added support for aliases (redirects)
* Cleanup of how content organization is handled
* Support for top level pages (other than homepage)
* Loads of unit and performance tests
* Integration with travis ci
* Complete overhaul of the documentation site
* Full Windows support
* **0.8.0** August 2, 2013
* Added support for pretty urls (filename/index.html vs filename.html)
* Hugo supports a destination directory

3
docs/content/doc/roadmap.md → docs/content/meta/roadmap.md
View file

@ -1,6 +1,7 @@
---
title: "Roadmap"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/roadmap/"]
---
In no particular order, here is what we are working on:

10
docs/content/doc/configuration.md → docs/content/overview/configuration.md
View file

@ -1,6 +1,7 @@
---
title: "Configuring Hugo"
pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/configuration/"]
---
The directory structure and templates provide the majority of the
@ -15,7 +16,7 @@ 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:
The following is an example of a yaml config file with the default values:
---
contentdir: "content"
@ -29,7 +30,7 @@ The following is an example of a yaml config file with the default values:
...
The following is an example of a json config file with the default values:
The following is an example of a json config file with the default values:
{
"contentdir": "content",
@ -44,7 +45,7 @@ The following is an example of a json config file with the default values:
}
The following is an example of a toml config file with the default values:
The following is an example of a toml config file with the default values:
contentdir = "content"
layoutdir = "layouts"
@ -55,4 +56,3 @@ The following is an example of a toml config file with the default values:
category = "categories"
tag = "tags"

3
docs/content/doc/installing.md → docs/content/overview/installing.md
View file

@ -1,6 +1,7 @@
---
title: "Installing Hugo"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/installing/"]
---
Hugo is written in GoLang with support for Windows, Linux, FreeBSD and OSX.

3
docs/content/doc/source-directory.md → docs/content/overview/source-directory.md
View file

@ -1,6 +1,7 @@
---
title: "Source Directory Organization"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/source-directory/"]
---
Hugo takes a single directory and uses it as the input for creating a complete website.

3
docs/content/doc/usage.md → docs/content/overview/usage.md
View file

@ -1,6 +1,7 @@
---
title: "Using Hugo"
Pubdate: "2013-07-01"
date: "2013-07-01"
aliases: ["/doc/usage/"]
---
Make sure either hugo is in your path or provide a path to it.

0
docs/layouts/doc/single.html → docs/layouts/_default/single.html
View file

5
docs/layouts/chrome/header.html
View file

@ -13,7 +13,10 @@
<div class="span3">
<div class="well" style="background-color: #222; color: #ccc;">
<h1>Hugo</h1>
<p>A Fast and Flexible Static Site Generator built with love by <a href="http://spf13.com">spf13</a> in Go</p>
<p>A Fast and Flexible Static Site Generator
built with love by <a href="http://spf13.com">spf13</a> and <a
href="http://github.com/spf13/hugo/graphs/contributors">friends</a>
in Go</p>
</div>
{{ template "chrome/menu.html" . }}
</div>

45
docs/layouts/chrome/menu.html
View file

@ -2,29 +2,40 @@
<li> <a href="/">Home</a></li>
<li class="divider"></li>
<li class="nav-header">Getting Started</li>
<li> <a href="/doc/installing">Installing Hugo</a></li>
<li> <a href="/doc/usage">Usage</a> </li>
<li> <a href="/doc/configuration">Configuration</a></li>
<li> <a href="/doc/source-directory">Input Directory Layout</a></li>
<li> <a href="/overview/installing">Installing Hugo</a></li>
<li> <a href="/overview/usage">Usage</a> </li>
<li> <a href="/overview/configuration">Configuration</a></li>
<li> <a href="/overview/source-directory">Source Directory Layout</a></li>
<li class="divider"></li>
<li class="nav-header">Layout</li>
<li> <a href="/doc/templates">Templates</a></li>
<li> <a href="/doc/variables">Variables</a></li>
<li> <a href="/layout/templates">Overview</a></li>
<!--<li> <a href="/layout/go-templates">Go Templates</a></li>-->
<li> <a href="/layout/variables">Variables</a></li>
<li> <a href="/layout/homepage">Homepage</a></li>
<li> <a href="/layout/rss">RSS</a></li>
<li> <a href="/layout/index">Index</a></li>
<li> <a href="/layout/content">Content</a></li>
<li> <a href="/layout/views">Content Views</a></li>
<li> <a href="/layout/chrome">Chrome</a></li>
<li class="divider"></li>
<li class="nav-header">Content</li>
<li> <a href="/doc/organization">Organization</a></li>
<li> <a href="/doc/front-matter">Front Matter</a></li>
<li> <a href="/doc/example">Example</a></li>
<li> <a href="/content/organization">Organization</a></li>
<li> <a href="/content/sections">Sections</a></li>
<li> <a href="/content/types">Types</a></li>
<li> <a href="/content/front-matter">Front Matter</a></li>
<li> <a href="/content/example">Example</a></li>
<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> <a href="/doc/aliases">Aliases</a></li>
<li> <a href="/extras/shortcodes">ShortCodes</a></li>
<li> <a href="/extras/aliases">Aliases</a></li>
<li> <a href="/extras/indexes">Indexes</a></li>
<li> <a href="/extras/indexes/category">Example Index - Category</a></li>
<!--<li> <a href="/extras/indexes/series">Example Index - Series</a></li>-->
<li class="divider"></li>
<li class="nav-header">Meta</li>
<li> <a href="/doc/release-notes">Release Notes</a></li>
<li> <a href="/doc/roadmap">Roadmap</a> </li>
<li> <a href="/doc/contributing">Contributing</a></li>
<li> <a href="/doc/contributors">Contributors</a></li>
<li> <a href="/doc/license">License</a></li>
<li> <a href="/meta/release-notes">Release Notes</a></li>
<li> <a href="/meta/roadmap">Roadmap</a> </li>
<li> <a href="/meta/contributing">Contributing</a></li>
<li> <a href="/meta/contributors">Contributors</a></li>
<li> <a href="/meta/license">License</a></li>
</ul>

3
docs/layouts/index.html
View file

@ -51,4 +51,7 @@
focus on writing great content.</p>
</div>
</div>
{{ range $key, $val := .Site.Recent }}
{{ $val.Title}}
{{ end }}
{{ template "chrome/footer.html" }}