Updating / Rewriting / Adding all of the documentation in preparation for the next release

This commit is contained in:
spf13 2014-05-27 18:32:57 -04:00
parent aeb06c7bcc
commit a87f171bd4
64 changed files with 2092 additions and 982 deletions

View file

@ -1,27 +1,46 @@
baseurl = "http://hugo.spf13.com"
MetaDataFormat = "yaml"
[indexes]
tag = "tags"
group = "groups"
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
weight = -110
identifier = "about"
[[menu.main]]
name = "getting started"
pre = "<i class='fa fa-road'></i>"
weight = -100
[[menu.main]]
name = "content"
pre = "<i class='fa fa-file-text'></i>"
weight = -90
[[menu.main]]
name = "layout"
name = "themes"
pre = "<i class='fa fa-desktop'></i>"
weight = -85
[[menu.main]]
name = "templates"
identifier = "layout"
pre = "<i class='fa fa-columns'></i>"
weight = -80
[[menu.main]]
name = "taxonomy"
name = "taxonomies"
identifier = "taxonomy"
pre = "<i class='fa fa-tags'></i>"
weight = -70
[[menu.main]]
name = "extras"
pre = "<i class='fa fa-gift'></i>"
weight = -60
[[menu.main]]
name = "community"
pre = "<i class='fa fa-group'></i>"
weight = -50
[[menu.main]]
name = "tutorials"
pre = "<i class='fa fa-book'></i>"
weight = -40

View file

@ -6,11 +6,16 @@ weight: 30
menu:
main:
parent: 'community'
prev: "/community/press"
next: "/community/contributors"
---
We welcome all contributions. Feel free to pick something from the roadmap
All contributions to Hugo are welcome. Whether you want to scratch an itch, or simply contribute to the project. Feel free to pick something from the roadmap
or contact [spf13](http://spf13.com) about what may make sense
to do next. Go ahead and fork the project and make your changes. *We encourage pull requests to discuss code changes.*
to do next.
You should fork the project and make your changes. *We encourage pull requests to discuss code changes.*
When you're ready to create a pull request, be sure to:

View file

@ -7,11 +7,12 @@ notoc: true
menu:
main:
parent: 'community'
prev: "/community/contributing"
next: "/tutorials/github_pages_blog"
---
Hugo was built with love and Go by:
* Steve Francia - [spf13](https://github.com/spf13)
* Noah Campbell - [noahcampbell](https://github.com/noahcampbell)
* [Many more](http://github.com/spf13/hugo/graphs/contributors)

View file

@ -5,6 +5,8 @@ weight: 10
menu:
main:
parent: 'community'
prev: "/extras/urls"
next: "/community/press"
---
Hugo has two mailing lists:

View file

@ -4,6 +4,8 @@ date = 2014-03-24T20:00:00Z
linktitle = "Press"
weight = 20
notoc = true
prev = "/community/mailing-list"
next = "/community/contributing"
[menu.main]
parent = "community"
+++

View file

@ -0,0 +1,76 @@
+++
title = "Archetypes"
date = 2014-05-14T02:13:50Z
weight = 50
prev = "/content/types"
next = "/content/ordering"
[menu]
[menu.main]
parent = "content"
+++
Hugo v0.11 introduced the concept of a content builder. Using the
command: `hugo new [relative new content path]` you can start a content file
with the date and title automatically set. This is a welcome feature, but
active writers need more.
Hugo presents the concept of archetypes which are archetypal content files.
## Example archetype
In this example scenario I have a blog with a single content type (blog post).
I use tags and categories for my taxonomies.
### archetypes/default.md
+++
tags = ["x", "y"]
categories = ["x", "y"]
+++
## using archetypes
If I wanted to create a new post in the `posts` section I would run the following command...
`hugo new posts/my-new-post.md`
Hugo would create the file with the following contents:
### contents/posts/my-new-post.md
+++
title = "my new post"
date = 2014-05-14T02:13:50Z
tags = ["x", "y"]
categories = ["x", "y"]
+++
## Using a different front matter format
By default the front matter will be created in the TOML format
regardless of what format the archetype is using.
You can specify a different default format in your config file using
the `MetaDataFormat` directive. Possible values are `toml`, `yaml` and `json`.
## Which archtype is being used
The following rules apply:
* If an archetype with a filename that matches the content type being created it will be used.
* If no match is found `archetypes/default.md` will be used.
* If neither are present and a theme is in use then within the theme...
* If an archetype with a filename that matches the content type being created it will be used.
* If no match is found `archetypes/default.md` will be used.
* If no archetype files are present then the one that ships with hugo will be used.
Hugo provides a simple archetype which sets the title (based on the
file name) and the date based on now().
Content type is automatically detected based on the path. You are welcome to declare which
type to create using the `--kind` flag during creation.

View file

@ -6,8 +6,10 @@ linktitle: "Example"
menu:
main:
parent: 'content'
weight: 50
weight: 70
notoc: true
prev: '/content/ordering'
next: '/themes/overview'
---
Somethings are better shown than explained. The following is a very basic example of a content file:

View file

@ -2,10 +2,13 @@
title = "Front Matter"
date = "2013-07-01"
aliases = ["/doc/front-matter/"]
weight = 40
weight = 20
prev = "/content/organization"
next = "/content/sections"
[menu.main]
parent = "content"
+++
The front matter is one of the features that gives Hugo its strength. It enables

View file

@ -6,12 +6,16 @@ menu:
main:
parent: "content"
weight: 60
prev: '/content/archetypes'
next: '/content/example'
---
In Hugo you have a good degree of control of how your content can be ordered.
Hugo provides you with all the flexibility you need to organize how your content is ordered.
By default, content is ordered by weight, then by date with the most recent
date first, but alternative sorting (by title and linktitle) is also available.
By default, content is ordered by weight, then by date with the most
recent date first, but alternative sorting (by title and linktitle) is
also available. The order the content will appear will be specified in
the [list template](/templates/list).
_Both the date and weight fields are optional._
@ -29,71 +33,7 @@ guaranteed.
+++
Front Matter with Ordered Pages 3
## Order by Weight -> Date (default)
{{ range .Data.Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Ordering Content Within Taxonomies
## Order by Weight -> Date
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Order by Date
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Order by Length
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Reverse Order
Can be applied to any of the above. Using Date for an example.
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Order by Title
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Order by LinkTitle
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
## Ordering Content Within Indexes
Please see the [Index Ordering Documentation](/indexes/ordering/)
Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/)

View file

@ -7,17 +7,21 @@ weight: 10
menu:
main:
parent: 'content'
prev: '/overview/source-directory'
next: '/content/front-matter'
---
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.
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).
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

View file

@ -4,8 +4,10 @@ date: "2013-07-01"
menu:
main:
parent: 'content'
weight: 20
weight: 30
notoc: true
prev: '/content/front-matter'
next: '/content/types'
---
Hugo thinks that you organize your content with a purpose. The same structure
@ -26,6 +28,13 @@ The following example site uses two sections, "post" and "quote".
├── first.md // <- http://1.com/quote/first/
└── second.md // <- http://1.com/quote/second/
## Section Lists
Hugo will automatically create pages for each section root that list all
of the content in that section. See [List Templates](/templates/list)
for details on customizing the way they appear.
## Sections and Types
By default everything created within a section will use the content type
@ -40,5 +49,3 @@ If a layout for a given type hasn't been provided a default type template will
be used instead provided is exists.

View file

@ -5,40 +5,18 @@ linktitle: "Types"
menu:
main:
parent: 'content'
weight: 30
weight: 40
prev: '/content/sections'
next: '/content/archetypes'
---
Hugo has full support for multiple content types each with its own set
of meta data and template. A good example of when multiple types are
needed is to look at Tumblr. A piece of content could be a photo, quote
or post, each with different meta data and rendered differently.
Hugo has full support for different types of content. A content type can have a
unique set of meta data, template and can be automatically created by the new
command through using content [archetypes](/content/archetypes).
## 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 Type Directory
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
### Step 2: Create template
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
### Step 3: Create list template
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/indexes/post.html*.
### Step 4: Create views
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.
A good example of when multiple types are needed is to look at Tumblr. A piece
of content could be a photo, quote or post, each with different meta data and
rendered differently.
## Assigning a content type
@ -48,3 +26,51 @@ 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".
## Creating new content of a specific type
Hugo has the ability to create a new content file and populate the front matter
with the data set corresponding to that type. Hugo does this by utilizing
[archetypes](/content/archetypes).
To create a new piece of content use:
hugo new relative/path/to/content.md
For example if I wanted to create a new post inside the post section I would type:
hugo new post/my-newest-post.md
## Defining a content type
Creating a new content type is easy in Hugo. You simply provide the templates and archetype
that the new type will use. You only need to define the templates, archetypes and/or views
unique to that content type. Hugo will fall back to using the general templates and default archetype
whenever a specific file is not present.
*Remember, all of the following are optional:*
### Create Type Directory
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
### Create single template
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
### Create list template
Create a file called list.html inside your directory *Eg /layouts/post/list.html*.
### Create views
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.
### Create a corresponding archetype
Create a file called `type`.md in the /archetypes directory *Eg /archetypes/post.md*.
More details about archetypes can be found at the [archetypes docs](/content/archetypes)

View file

@ -5,10 +5,12 @@ aliases:
- /doc/redirects/
- /doc/alias/
- /doc/aliases/
weight: 20
weight: 10
menu:
main:
parent: 'extras'
prev: "/taxonomies/ordering"
next: "/extras/builders"
---
For people migrating existing published content to Hugo theres a good chance

View file

@ -0,0 +1,60 @@
---
title: "Hugo Builders"
linktitle: "Builders"
date: "2014-05-26"
weight: 12
menu:
main:
parent: 'extras'
prev: "/extras/aliases"
next: "/extras/comments"
---
Hugo provides the functionality to quickly get a site, theme or page
started.
## New Site
Want to get a site built quickly?.
hugo new site /path/to/site
Hugo will create all the needed directories and files to get started
quickly.
Hugo will only touch the files and create the directories (in the right
places), [configuration](/overview/configuration) and content are up to
you... but luckily we have builders for content (see below).
## New Theme
Want to design a new theme?
hugo new theme `THEME_NAME`
Run from your working directory, this will create a new theme with all
the needed files in your themes directory. Hugo will provide you with a
license and theme.toml file with most of the work done for you.
Follow the [Theme Creation Guide](/themes/creation) once the builder is
done.
## New Content
You will use this builder the most of all. Every time you want to create
a new piece of content, the content builder will get you started right.
Leveraging [content archetypes](/content/archetypes) the content builder
will not only insert the current date and appropriate metadata, but it
will pre-populate values based on the content type.
hugo new relative/path/to/content
This assumes it is being run from your working directory and the content
path starts from your content directory.
I typically keep two different terminals open, one to run `hugo server
--watch`, and another to use the builders to create new content.

View file

@ -0,0 +1,67 @@
---
title: "Comments in Hugo"
linktitle: "Comments"
date: "2014-05-26"
weight: 14
menu:
main:
parent: 'extras'
prev: "/extras/builders"
next: "/extras/livereload"
---
As Hugo is a static site generator, the content produced is static and
doesnt interact with the users. The most common interaction people ask
for is comment capability.
Hugo ships with support for [disqus](http://disqus.com), a third party
service that provides comment and community capabilities to website via
javascript.
Your theme may already support disqus, but even it if doesnt it is easy
to add.
# Disqus Support
## Adding Disqus to a template
Hugo comes with all the code you would need to include load disqus.
Simply include the following line where you want your comments to appear
{{ template "_internal/disqus.html" . }}
## Configuring Disqus
That template requires you to set a single value in your site config file, eg. config.yaml.
disqusShortname = "XYW"
Additionally you can optionally set the following in the front matter
for a given piece of content
* **disqus_identifier**
* **disqus_title**
* **disqus_url**
# Alternatives
A few alternatives exist to Disqus.
* [Intense Debate](http://intensedebate.com/)
* [LiveFyre](http://livefyre.com/)
* [Moot](http://muut.com)
* [Kaiju](http://github.com/spf13/kaiju)
[Kaiju](http://github.com/spf13/kaiju) is a open source project started
by [spf13](http://spf13.com) (Hugos author) to bring easy and fast real
time discussions to the web.
Written using Go, Socket.io and MongoDB it is very fast and easy to
deploy.
It is in early development but shows promise.. If you have interest
please help by contributing whether via a pull request, an issue or even
just a tweet. Everything helps.

View file

@ -1,10 +1,12 @@
---
title: "Highlighting"
title: "Syntax Highlighting"
date: "2013-07-01"
weight: 15
weight: 50
menu:
main:
parent: 'extras'
prev: "/extras/shortcodes"
next: "/extras/toc"
---
Hugo provides the ability for you to highlight source code in two different

View file

@ -0,0 +1,61 @@
---
title: "Live Reload"
date: "2014-05-26"
weight: 15
menu:
main:
parent: 'extras'
prev: "/extras/comments"
next: "/extras/menus"
---
Hugo may not be the first static site generator to utilize live reload
technology, but its the first to do it right.
The combination of Hugos insane build speed and live reload make
crafting your content pure joy. Virtually instantly after you hit save
your rebuilt content will appear in your browser.
## Using livereload
Hugo comes with livereload built in. There are no additional packages to
install. A common way to use hugo while developing a site is to have
hugo run a server and watch for changes.
hugo server --watch
This will run a full functioning web server while simultaneously
watching your file system for additions, deletions or changes within
your:
* static files
* content
* layouts
* current theme
Whenever anything changes Hugo will rebuild the site, continue to serve
the content and as soon as the build is finished it will tell the
browser and silently reload the page. Because most hugo builds are so
fast they are barely noticeable, you merely need to glance at your open
browser and you will see the change already there.
This means that keeping the site open on a second monitor (or another
half of your current monitor), allows you to see exactly what your
content looks like without even leaving your text editor.
## Disabling livereload
Live reload accomplishes this by injecting javascript into the pages it
creates that creates a web socket client to the hugo web socket server.
Awesome for development, but not something you would want to do in
production. Since many people use `hugo server --watch` in production to
instantly display any updated content, weve made it easy to disable the
live reload functionality.
hugo server --watch --disableLiveReload

View file

@ -0,0 +1,162 @@
+++
title = "Menus"
weight = 20
prev = "/extras/livereload"
next = "/extras/permalinks"
date = 2014-05-14T02:36:37Z
[menu]
[menu.main]
parent = "extras"
+++
Hugo has a simple yet powerful menu system that permits content to be
placed in menus with a good degree of control without a lot of work.
Some of the features of Hugo Menus:
* Place content in one or many menus
* Handle nested menus with unlimited depth
* Create menu entries without being attached to any content
* Distinguish active element (and active branch)
## What is a menu?
A menus is a named array of menu entries accessible on the site under
.Site.Menus by name. For example if I have a menu called `main` I would
access it via .Site.Menus.main.
A menu entry has the following properties:
* **Url** string
* **Name** string
* **Menu** string
* **Identifier** string
* **Pre** template.HTML
* **Post** template.HTML
* **Weight** int
* **Parent** string
* **Children** Menu
Additionally there are some relevant functions available on the page:
* **HasChildren** bool
* **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool
* **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool
## Adding content to menus
Hugo supports a couple of different methods of adding a piece of content
to the front matter.
### Simple
If all you need to do is add an entry to a menu, the simple form works
well.
**A single menu:**
---
menu: "main"
---
**Multiple menus:**
---
menu: ["main", "footer"]
---
### Advanced
If more control is required, then the advanced approach gives you the
control you want. All of the menu entry properties listed above are
available.
---
menu:
main:
parent: 'extras'
weight: 20
---
## Adding (non-content) entries to a menu
You can also add entries to menus that arent attached to a piece of
content. This takes place in the site wide config file.
Heres an example (in toml):
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
weight = -110
identifier = "about"
[[menu.main]]
name = "getting started"
pre = "<i class='fa fa-road'></i>"
weight = -100
## Nesting
All nesting of content is done via the `parent` field.
The parent of an entry should be the identifier of another entry.
Identifier should be unique (within a menu).
The following order is used to determine identity Identifier > Name >
LinkTitle > Title. This means that the title will be used unless
linktitle is present, etc. In practice Name and Identifier are never
displayed and only used to structure relationships.
In this example, the top level of the menu is defined in the config file
and all content entries are attached to one of these entries via the
`parent` field.
## Rendering menus
Hugo makes no assumptions about how your rendered HTML will be
structured, instead it provides all of the functions you will need to be
able to build your menu however you want.
The following is an example:
<!--sidebar start-->
<aside>
<div id="sidebar" class="nav-collapse ">
<!-- sidebar menu start-->
<ul class="sidebar-menu">
{{ $currentNode := . }}
{{ range .Site.Menus.main }}
{{ if .HasChildren }}
<li class="sub-menu{{if $currentNode.HasMenuCurrent "main" . }} active{{end}}">
<a href="javascript:;" class="">
{{ .Pre }}
<span>{{ .Name }}</span>
<span class="menu-arrow arrow_carrot-right"></span>
</a>
<ul class="sub">
{{ range .Children }}
<li{{if $currentNode.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.Url}}"> {{ .Name }} </a> </li>
{{ end }}
</ul>
{{else}}
<li>
<a class="" href="{{.Url}}">
{{ .Pre }}
<span>{{ .Name }}</span>
</a>
{{end}}
</li>
{{end}}
<li> <a href="https://github.com/spf13/hugo/issues" target="blank">Questions and Issues</a> </li>
<li> <a href="#" target="blank">Edit this Page</a> </li>
</ul>
<!-- sidebar menu end-->
</div>
</aside>
<!--sidebar end-->

View file

@ -8,6 +8,8 @@ notoc: true
menu:
main:
parent: 'extras'
prev: "/extras/menus"
next: "/extras/shortcodes"
---
By default, content is laid out into the target `publishdir` (public)

View file

@ -2,10 +2,12 @@
title: "Shortcodes"
date: "2013-07-01"
aliases: ["/doc/shortcodes/"]
weight: 10
weight: 40
menu:
main:
parent: 'extras'
prev: "/extras/permalinks"
next: "/extras/highlighting"
---
Because Hugo uses markdown for its simple content format, however there's a lot

View file

@ -1,10 +1,12 @@
---
title: "Table of Contents"
date: "2013-07-09"
weight: 70
weight: 60
menu:
main:
parent: 'extras'
prev: "/extras/highlighting"
next: "/extras/urls"
---
Hugo will automatically parse the markdown for your content and create
@ -24,12 +26,12 @@ Hugo will take this markdown and create a table of contents stored in the
This is example code of a [single.html template](/layout/content).
{{ template "chrome/header.html" . }}
{{ template "partials/header.html" . }}
<div id="toc" class="well col-md-4 col-sm-6">
{{ .TableOfContents }}
</div>
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ template "chrome/footer.html" . }}
{{ template "partials/footer.html" . }}

View file

@ -3,11 +3,13 @@ title: "URLs"
date: "2014-01-03"
aliases:
- "/doc/urls/"
weight: 40
weight: 70
notoc: true
menu:
main:
parent: 'extras'
prev: "/extras/toc"
next: "/community/mailing-list"
---
## Pretty Urls

View file

@ -1,57 +0,0 @@
---
title: "Homepage Templates"
date: "2013-07-01"
weight: 30
notoc: true
menu:
main:
parent: 'layout'
---
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 . Details on how to use this
list of pages can be found in [Lists](/indexes/lists/)
▾ 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) and uses a [List](/indexes/lists/)
<!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 first 10 .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "chrome/footer.html" }}

View file

@ -1,125 +0,0 @@
---
title: "Index Templates"
date: "2013-07-01"
weight: 50
menu:
main:
parent: 'layout'
---
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 its 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" }}

View file

@ -1,51 +0,0 @@
---
title: "RSS (feed) Templates"
date: "2013-07-01"
weight: 40
notoc: "one"
menu:
main:
parent: 'layout'
---
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" ?>

View file

@ -1,40 +0,0 @@
---
title: "Hugo Templates"
date: "2013-07-01"
aliases: ["/doc/templates/"]
linktitle: "Overview"
weight: 10
menu:
main:
parent: 'layout'
---
Hugo uses the excellent go html/template library for its 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
### [Index](/layout/indexes)
Page that list multiple pieces of content
### [Content](/layout/content)
Render a single piece of content
### [Views](/layout/views)
Different view of a single piece of content type
### [Chrome](/layout/chrome)
Support for the above templates

View file

@ -1,83 +0,0 @@
---
title: "Content Views"
date: "2013-07-01"
weight: 70
menu:
main:
parent: 'layout'
---
In addition to the [single content view](/layout/content/), Hugo can render alternative views of
your content. These are especially useful in [index](/layout/indexes) 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.

View file

@ -1,11 +1,11 @@
---
title: "License"
date: "2013-07-01"
aliases: ["/doc/license/", "/license/"]
aliases: ["/doc/license/", "/license/", "/meta/license/"]
weight: 50
menu:
right:
parent: 'meta'
main:
parent: 'about'
---
Hugo is released under the Simple Public License.

View file

@ -1,12 +1,30 @@
---
title: "Release Notes"
date: "2013-07-01"
aliases: ["/doc/release-notes/"]
aliases: ["/doc/release-notes/", "/meta/release-notes/"]
weight: 10
menu:
right:
parent: 'meta'
main:
parent: 'about'
---
## **0.11.0** May 27, 2014
* Considerably faster... about 3 - 4x faster on average
* Live Reload... Hugo will automatically reload the browser when the build is complete
* Theme engine w/[Theme Repository](http://github.com/spf13/hugoThemes)
* Menu system with support for active page
* Builders to quickly create a new site, content or theme
* XML sitemap generation
* Integrated Disqus support
* Streamlined template organization
* Brand new docs site
* More sort options
* Logging support
* Much better error handling
* More informative verbose output
* Renamed Indexes > Taxonomies
* Renamed Chrome > Partials
## **0.10.0** March 1, 2014
* [Syntax highlighting](/extras/highlighting) powered by pygments (**slow**)
* Ability to [sort content](/content/ordering) many more ways

View file

@ -1,27 +1,23 @@
---
title: "Roadmap"
title: "Hugo Roadmap"
date: "2013-07-01"
aliases: ["/doc/roadmap/"]
groups: ["meta"]
groups_weight: 20
aliases: ["/doc/roadmap/","/meta/roadmap/"]
weight: 20
notoc: true
menu:
right:
parent: 'meta'
main:
parent: 'about'
---
In no particular order, here is what we are working on:
* Pagination
* Better error handling
* Related Posts
* Support for other formats
* Full theming support
* Ability to automatically import from other website systems (wordpress, jekyll)
* Ship with a few default themes
* Intelligently Related Posts
* Even easier deployment to S3, SSH, Github, rsync
* Import from other website systems (wordpress, jekyll)
* An interactive web based editor
* Easy deployment to S3, SSH, Github, rsync
* Live preview (auto refresh in browser)
* Additional Themes
* Dynamic image resizing via shortcodes
* Support for additional formats
* Pagination
* Your best ideas

View file

@ -8,50 +8,30 @@ notoc: true
menu:
main:
parent: 'getting started'
prev: '/overview/usage'
next: '/overview/source-directory'
---
The directory structure and templates provide the majority of the
configuration for a site. In fact a config file isn't even needed for many
websites since the defaults used follow commonly used patterns.
websites since the defaults follow commonly used patterns.
Hugo expects to find the config file in the root of the source directory and
will look there first for a `config.yaml` file. If none is present it will
then look for a `config.json` file, followed by a `config.toml` file.
will look there first for a `config.toml` file. If none is present it will
then look for a `config.yaml` file, followed by a `config.json` file.
**Please note the field names must be all lowercase**
The config file is a site-wide config. The config file provides directions to
hugo on how to build the site as well as site-wide parameters and menus.
## Examples
The following is an example of a yaml config file with the default values:
The following is an example of a typical yaml config file:
---
contentdir: "content"
layoutdir: "layouts"
publishdir: "public"
builddrafts: false
indexes:
category: "categories"
tag: "tags"
baseurl: "http://yoursite.example.com/"
canonifyurls: true
...
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/",
"canonifyurls": true
}
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 some of the default values:
contentdir = "content"
layoutdir = "layouts"
@ -79,3 +59,4 @@ Here is a yaml configuration file which sets a few more options
- "foo2"
SidebarRecentLimit: 5
...

View file

@ -6,6 +6,10 @@ weight: 20
menu:
main:
parent: 'getting started'
prev: '/overview/quickstart'
next: '/overview/usage'
---
Hugo is written in Go with support for Windows, Linux, FreeBSD and OSX.
@ -25,13 +29,19 @@ where you don't have a privileged account.
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
is the most probable location.
The Hugo executable has one *optional* external dependency for source code highlighting (pygments).
### Installing pygments (optional)
### Installing pygments
The Hugo executable has one *optional* external dependency for source code highlighting (pygments).
If you want to have source code highlighting using the [highlight shortcode](/extras/highlighting)
you need to install the python-based pygments program. The procedure is outlined on the [pygments home page](http://pygments.org).
## Upgrading Hugo
Upgrading hugo is as easy as downloading and replacing the executable youve
placed in your path.
## Installing from source
### Dependencies

View file

@ -6,6 +6,7 @@ weight: 5
menu:
main:
parent: 'getting started'
next: '/overview/quickstart'
---
## What is Hugo?
@ -36,35 +37,47 @@ templates and uses these as input to create a complete website.
Hugo boasts the following features:
### General
* Extremely fast built times (~1ms per page)
* Runs on Mac OSX, Linux and Windows
* Content written in [Markdown](/content/example)
* Completely cross platform: Runs on Mac OSX, Linux and Windows
* Easy [installation](/overview/installing)
* Straightforward website [organization](/content/organization)
* Completely [customizable homepage](/layout/homepage)
* Support for multiple [content types](/content/types)
* Render changes [on the fly](/overview/usage) with [live reload](#) as you develop
* Complete theme support
* Host your site anywhere
### Organization
* Straightforward [organization](/content/organization)
* Support for [website sections](/content/sections)
* Completely customizable [urls](/extras/urls)
* Render changes [on the fly](/overview/usage) as you develop
* Host your site anywhere
* Support for disqus comments
* Dynamic menu creation
* Support for TOML, YAML and JSON metadata in [frontmatter](/content/front-matter)
* [permalink](/extras/permalinks) pattern support
* [pretty urls](/extras/urls) support
* [shortcodes](/extras/shortcodes)
* [Aliases](/extras/aliases) (redirects)
* Automatic [RSS](/layout/rss) creation
* Support for go and amber templates
* Support for [categories](/indexes/category) and tags
* Support for configurable [indexes](/indexes/overview) to create your own organization
* Syntax [highlighting](/extras/highlighting) powered by pygments
* Support for configurable [taxonomies](/indexes/overview) to create your own organization
* Ability to [sort content](/content/ordering) as you desire
* Automatic [table of contents](/extras/toc) generation
* Dynamic menu creation
* [pretty urls](/extras/urls) support
* [permalink](/extras/permalinks) pattern support
* [Aliases](/extras/aliases) (redirects)
### Content
* Content written in [Markdown](/content/example)
* Support for TOML, YAML and JSON metadata in [frontmatter](/content/front-matter)
* Completely [customizable homepage](/layout/homepage)
* Support for multiple [content types](/content/types)
* Automatic and user defined [summaries](/content/summaries)
* [shortcodes](/extras/shortcodes) to enable rich content inside of markdown
* ["Minutes to Read"](/layout/variables) functionality
* ["Wordcount"](/layout/variables) functionality
### Additional Features
* Integrated Disqus comment support
* Automatic [RSS](/layout/rss) creation
* Support for go and amber templates
* Syntax [highlighting](/extras/highlighting) powered by pygments
See what's coming next in the [roadmap](/meta/roadmap)
## Who should use Hugo?

View file

@ -6,8 +6,14 @@ weight: 10
menu:
main:
parent: 'getting started'
prev: '/overview/introduction'
next: '/overview/installing'
---
_This quickstart depends on features introduced in hugo v0.11. If you
have an earlier version of hugo you will need to [upgrade](/overview/installing/) before
proceeding._
## Step 1. Install Hugo
Goto [hugo releases](https://github.com/spf13/hugo/releases) and download the
@ -17,67 +23,128 @@ Save it somewhere specific as we will be using it in the next step.
More complete instructions are available at [installing hugo](/overview/installing/)
## Step 2. Build the Docs
## Step 2. Have Hugo Create a site for you
Hugo has its own example site which happens to also be the documentation site
you are reading right now.
Hugo has the ability to create a skeleton site.
Follow the following steps:
hugo new site /path/to/site
1. Clone the [hugo repository](http://github.com/spf13/hugo)
2. Go into the repo
3. Run hugo in server mode and build the docs
4. Open your browser to http://localhost:1313
For the rest of the operations we will be executing all commands from within the site directory
Corresponding pseudo commands:
cd /path/to/site
git clone https://github.com/spf13/hugo
cd hugo
/path/to/where/you/installed/hugo server --source=./docs
> 29 pages created
> 0 tags index created
> in 27 ms
> Web Server is available at http://localhost:1313
> Press ctrl+c to stop
The new site will have the following structure
Once you've gotten here, follow along the rest of this page on your local build.
▸ archetypes/
▸ content/
▸ layouts/
▸ static/
config.toml
## Step 3. Change the docs site
Currently the site doesnt have any content, nor is it configured.
Stop the Hugo process by hitting ctrl+c.
## Step 3. Create Some Content
Now we are going to run hugo again, but this time with hugo in watch mode.
Hugo also has the ability to create content for you.
/path/to/hugo/from/step/1/hugo server --source=./docs --watch
> 29 pages created
> 0 tags index created
> in 27 ms
> Web Server is available at http://localhost:1313
> Watching for changes in /Users/spf13/Code/hugo/docs/content
> Press ctrl+c to stop
hugo new about.md
A new file is now created in `content/` with the following contents
+++
draft = true
title = "about"
date = 2014-05-20T10:04:31Z
+++
Notice the date is automatically set to the moment you created the content.
Place some content in this file below the `+++` in the markdown format.
For example you could put this
## A headline
Some Content
For fun, lets create another piece of content and place some markdown in it as well.
hugo new post/first.md
The new file is located at `content/post/first.md`
We still lack any templates to tell us how to display the content.
## Step 4. Install some themes
Hugo has rich theme support and a growing set of themes to choose from.
git clone --recursive https://github.com/spf13/hugoThemes themes
Open your [favorite editor](http://vim.spf13.com) and change one of the source
content pages. How about changing this very file to *fix the typo*. How about changing this very file to *fix the typo*.
## Step 5. Run Hugo
Hugo contains its own high performance web server. Simply run `hugo
server` and Hugo will find an available port and run a server with
your content
hugo server --theme=hyde --buildDrafts
2 pages created
0 tags created
0 categories created
in 5 ms
Serving pages from exampleHugoSite/public
Web Server is available at http://localhost:1313
Press ctrl+c to stop
We specified two options here.
* --theme to pick which theme.
* --buildDrafts because we want to display our content, both set to draft status
To learn about what other options hugo has run
hugo help
To learn about the server options
hugo help server
## Step 6. Edit Content
Not only can Hugo run a server, but it can also watch your files for
changes and automatically rebuild your site. Hugo will then
communicate with your browser and automatically reload any open page.
This even works in mobile browsers.
Stop the Hugo process by hitting ctrl+c. Then run the following:
hugo server --theme=hyde --buildDrafts --watch
2 pages created
0 tags created
0 categories created
in 5 ms
Watching for changes in exampleHugoSite/content
Serving pages from exampleHugoSite/public
Web Server is available at http://localhost:1313
Press ctrl+c to stop
Open your [favorite editor](http://vim.spf13.com), edit and save your content and watch as Hugo rebuilds and reloads automatically.
Its especially productive to leave a browser open on a second monitor
and just glance at it whenever you save. You dont even need to tab to
your browser. Hugo is so fast, that the new site will be there before
you can look at the browser in most cases.
Content files are found in `docs/content/`. Unless otherwise specified, files
are located at the same relative location as the url, in our case
`docs/content/overview/quickstart.md`.
Change and save this file.. Notice what happened in your terminal.
> Change detected, rebuilding site
Change detected, rebuilding site
> 29 pages created
> 0 tags index created
> in 26 ms
2 pages created
0 tags created
0 categories created
in 5 ms
Refresh the browser and observe that the typo is now fixed.
Notice how quick that was. Try to refresh the site before it's finished building.. I double dare you.
Having nearly instant feedback enables you to have your creativity flow without waiting for long builds.
## Step 4. Have fun
## Step 7. Have fun
The best way to learn something is to play with it.

View file

@ -1,5 +1,5 @@
---
title: "Source Directory Organization"
title: "Source Organization"
date: "2013-07-01"
aliases: ["/doc/source-directory/"]
weight: 50
@ -7,18 +7,41 @@ notoc: true
menu:
main:
parent: 'getting started'
prev: '/overview/configuration'
next: '/content/organization'
---
Hugo takes a single directory and uses it as the input for creating a complete website.
Hugo takes a single directory and uses it as the input for creating a complete
website.
Hugo has a very small amount of configuration, while remaining highly customizable.
It accomplishes by assuming that you will only provide templates with the intent of
using them.
The top level of a source directory will typically have the following elements:
▸ archetypes/
▸ content/
▸ layouts/
▸ static/
▸ themes/
config.toml
Learn more about the different directories and what their purpose is
* [config](/overview/configuration)
* [archetypes](/content/archetypes)
* [content](/content/organization)
* [layouts](/layout/overview)
* [static]()
* [themes](/themes/overview)
## Example
An example directory may look like:
.
├── config.yaml
├── config.toml
├── archetypes
| └── default.md
├── content
| ├── post
| | ├── firstpost.md
@ -27,10 +50,13 @@ An example directory may look like:
| | ├── first.md
| | └── second.md
├── layouts
| ├── chrome
| ├── _default
| | ├── single.html
| | └── list.html
| ├── partials
| | ├── header.html
| | └── footer.html
| ├── indexes
| ├── taxonomies
| | ├── category.html
| | ├── post.html
| | ├── quote.html
@ -48,14 +74,16 @@ An example directory may look like:
| | ├── vimeo.html
| | └── youtube.html
| ├── index.html
| ├── rss.xml
| └── sitemap.xml
├── themes
| ├── hyde
| └── doc
└── static
├── css
└── js
This directory structure tells us a lot about this site:
1. the website intends to have two different types of content, posts and quotes.
2. It will also apply two different indexes to that content, categories and tags.
3. It will be displaying content in 3 different views, a list, a summary and a full page view.
Included with the repository is this example site ready to be rendered.

View file

@ -7,10 +7,14 @@ notoc: true
menu:
main:
parent: 'getting started'
prev: '/overview/installing'
next: '/overview/configuration'
---
Make sure either hugo is in your path or provide a path to it.
$ hugo help
A Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.
@ -22,23 +26,28 @@ Make sure either hugo is in your path or provide a path to it.
hugo [command]
Available Commands:
server :: Hugo runs it's own a webserver to render the files
version :: Print the version number of Hugo
check :: Check content in the source directory
benchmark :: Benchmark hugo by building a site a number of times
help [command] :: Help about any command
server :: Hugo runs it's own a webserver to render the files
version :: Print the version number of Hugo
check :: Check content in the source directory
benchmark :: Benchmark hugo by building a site a number of times
new [path] :: Create new content for your site
help [command] :: Help about any command
Available Flags:
-b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
-D, --build-drafts=false: include content marked as draft
-b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/
-D, --buildDrafts=false: include content marked as draft
--config="": config file (default is path/config.yaml|json|toml)
-d, --destination="": filesystem path to write files to
--disableRSS=false: Do not build RSS files
--disableSitemap=false: Do not build Sitemap file
--log=false: Enable Logging
--logfile="": Log File path (if set, logging enabled automatically)
--logFile="": Log File path (if set, logging enabled automatically)
-s, --source="": filesystem path to read files relative from
--uglyurls=false: if true, use /filename.html instead of /filename/
--stepAnalysis=false: display memory and timing of different steps of the program
-t, --theme="": theme to use (located in /themes/THEMENAME/)
--uglyUrls=false: if true, use /filename.html instead of /filename/
-v, --verbose=false: verbose output
--verboselog=false: verbose logging
--verboseLog=false: verbose logging
-w, --watch=false: watch filesystem for changes and recreate as needed
Use "hugo help [command]" for more information about that command.
@ -48,26 +57,25 @@ Make sure either hugo is in your path or provide a path to it.
The most common use is probably to run hugo with your current
directory being the input directory.
$ hugo
> X pages created
> Y indexes created
in 8 ms
If you are working on things and want to see the changes
immediately, tell Hugo to watch for changes. **It will
recreate the site faster than you can tab over to
your browser to view the changes.**
immediately, tell Hugo to watch for changes.
Hugo will watch the filesystem for changes, rebuild your site as soon as a file
is saved.
$ hugo -s ~/mysite --watch
28 pages created
0 tags index created
in 18 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content
Press ctrl+c to stop
Hugo can even run a server and create your site at the same time!
Hugo can even run a server and create your site at the same time! Hugo
implements live reload technology to automatically reload any open pages in
all browsers (including mobile).
$ hugo server -ws ~/mysite
Watching for changes in /Users/spf13/Code/hugo/docs/content

View file

@ -1,57 +0,0 @@
---
title: "Example Index - Category"
date: "2013-07-01"
linktitle: "Example - Categories"
aliases: ["/extras/indexes/category"]
groups: ["indexes"]
groups_weight: 60
---
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.
*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",
"Go",
"Blogging"
],
"slug": "hugo"
}

View file

@ -1,5 +1,5 @@
---
title: "Rendering Taxonomies"
title: "Displaying Taxonomies"
date: "2013-07-01"
linktitle: "Displaying"
aliases: ["/indexes/displaying/"]
@ -7,15 +7,27 @@ weight: 20
menu:
main:
parent: 'taxonomy'
prev: "/taxonomies/usage"
next: "/taxonomies/templates"
---
## Rendering index values assigned to this content
There are four common ways you can display the data in your
taxonomies in addition to the automatic taxonomy pages created by hugo
using the [list templates](/templates/list).
1. For a given piece of content you can list the terms attached
2. For a given piece of content you can list other content with the same
term
3. You can list all terms for a taxonomy
4. You can list all taxonomies (with their terms)
## 1. Displaying taxonomy terms assigned to this content
Within your content templates you may wish to display
the indexes that that piece of content is assigned to.
the taxonomies 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
define taxonomies for content, the taxonomies assigned to
each content piece are located in the usual place
(.Params.`plural`)
@ -27,9 +39,47 @@ each content piece are located in the usual place
{{ end }}
</ul>
## Rendering a Site's Indexes
## 2. Listing content with the same taxonomy term
If you wish to display the list of all keys for an index you can find retrieve
First you may be asking why you would use this. If you are using a
taxonomy for something like a series of posts, this is exactly how you
would do it. Its also an quick and dirty way to show some related
content.
### Example
<ul>
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Url }}">{{ .Name }}</a></li>
{{ end }}
</ul>
## 3. Listing all content in a given taxonomy
This would be very useful in a sidebar as “featured content”. You could
even have different sections of “featured content” by assigning
different terms to the content.
### Example
<section id="menu">
<ul>
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
<li> {{ $key }} </li>
<ul>
{{ range $taxonomy.Pages }}
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</section>
## 4. Rendering a Site's Taxonomies
If you wish to display the list of all keys for an taxonomy 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.
@ -39,32 +89,20 @@ The following example displays all tag keys:
### Example
<ul id="all-tags">
{{ range .Site.Indexes.tags }}
{{ range .Site.Taxonomies.tags }}
<li><a href="/tags/{{ .Name | urlize }}">{{ .Name }}</a></li>
{{ end }}
</ul>
## Creating a menu based on indexes
### Complete Example
This example will list all taxonomies, each of their keys and all the content assigned to each key.
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.
### Example complete menu.html file
This example will list all indexes, each of their keys and all the content assigned to each key.
<section id="menu">
<section>
<ul>
{{ range $indexname, $index := .Site.Indexes }}
<li><a href="/{{ $indexname | urlize }}">{{ $indexname }}</a>
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
<li><a href="/{{ $taxonomyname | urlize }}">{{ $taxonomyname }}</a>
<ul>
{{ range $key, $value := $index }}
{{ range $key, $value := $taxonomy }}
<li> {{ $key }} </li>
<ul>
{{ range $value.Pages }}
@ -78,35 +116,3 @@ This example will list all indexes, each of their keys and all the content assig
</ul>
</section>
### 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.
<section id="menu">
<ul>
{{ range $key, $index := .Site.Indexes.groups }}
<li> {{ $key }} </li>
<ul>
{{ range $index.Pages }}
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</section>
### menu.html using a single index ordered by Popularity
<section id="menu">
<ul>
{{ range .Site.Indexes.groups.ByCount }}
<li> {{ .Name }} </li>
<ul>
{{ range .Pages }}
<li hugo-nav="{{ .RelPermalink}}"><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a> </li>
{{ end }}
</ul>
{{ end }}
</ul>
</section>

View file

@ -1,74 +0,0 @@
---
title: "Taxonomy Lists"
date: "2013-07-01"
aliases: ["/indexes/lists/","/doc/indexes/", "/extras/indexes"]
linktitle: "Lists"
weight: 40
menu:
main:
parent: 'taxonomy'
---
An index list is a list of all the keys that are contained in the index. When a
template is present, this will be rendered at `/IndexPlural/`
Hugo also supports creating pages that list your values for each index along
with the number of content items associated with the index key. These are
global pages, not attached to any specific content, but rather display the meta
data in aggregate.
To have hugo create these list of indexes pages, simply create a template in
/layouts/indexes/ called indexes.html
Hugo can order the meta data in two different ways. It can be ordered by the
number of content assigned to that key or alphabetically.
## Example indexes.html file (alphabetical)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Index.Alphabetical }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
</div>
</section>
{{ template "chrome/footer.html" }}
## Example indexes.html file (ordered)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Index.ByCount }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
</div>
</section>
{{ template "chrome/footer.html" }}
## Variables available to list of indexes pages.
**.Title** The title for the content. <br>
**.Date** The date the content is published on.<br>
**.Permalink** The Permanent link for this page.<br>
**.RSSLink** Link to the indexes' rss link. <br>
**.Data.Singular** The singular name of the index <br>
**.Data.Plural** The plural name of the index<br>
**.Data.Index** The Index itself<br>
**.Data.Index.Alphabetical** The Index alphabetized<br>
**.Data.Index.ByCount** The Index ordered by popularity<br>

View file

@ -8,22 +8,24 @@ menu:
main:
identifier: "Ordering Taxonomies"
parent: 'taxonomy'
prev: "/taxonomies/templates"
next: "/extras/aliases"
---
Hugo provides the ability to both:
1. Order the way the keys for an index are displayed
2. Order the way indexed content appears
1. Order the way the keys for an taxonomy are displayed
2. Order the way taxonomyed content appears
## Ordering Indexes
Indexes can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
## Ordering Taxonomies
Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
### Order Alphabetically Example:
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Index.Alphabetical }}
{{ range $key, $value := .Data.Taxonomy.Alphabetical }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
@ -32,26 +34,26 @@ Indexes can be ordered by either alphabetical key or by the number of content pi
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Index.ByCount }}
{{ range $key, $value := .Data.Taxonomy.ByCount }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
[See Also Index Lists](/indexes/lists/)
[See Also Taxonomy Lists](/taxonomies/lists/)
## Ordering Content within Indexes
## Ordering Content within Taxonomies
Hugo uses both **Date** and **Weight** to order content within indexes.
Hugo uses both **Date** and **Weight** to order content within taxonomies.
Each piece of content in Hugo can optionally be assigned a date.
It can also be assigned a weight for each index it is assigned to.
It can also be assigned a weight for each taxonomy it is assigned to.
When iterating over content within indexes the default sort is first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
When iterating over content within taxonomies the default sort is first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0.
### Assigning Weight
Content can be assigned weight for each index that it's assigned to.
Content can be assigned weight for each taxonomy that it's assigned to.
+++
tags = [ "a", "b", "c" ]
@ -63,12 +65,12 @@ Content can be assigned weight for each index that it's assigned to.
Front Matter with weighted tags and categories
The convention is `indexname_weight`.
The convention is `taxonomyname_weight`.
In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' index.
In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.
It has also been assigned the weight of 44 when rendering the 'd' category.
With this the same piece of content can appear in different positions in different indexes.
With this the same piece of content can appear in different positions in different taxonomies.
Currently indexes only support the default ordering of content which is weight -> date.
Currently taxonomies only support the default ordering of content which is weight -> date.

View file

@ -1,76 +1,89 @@
---
title: "Taxonomy Overview"
linktitle: "Overview"
date: "2013-07-01"
aliases: ["/indexes/overview/","/doc/indexes/", "/extras/indexes"]
weight: 10
menu:
main:
parent: 'taxonomy'
identifier: 'taxonomy overview'
prev: "/templates/404"
next: "/taxonomies/usage"
---
Hugo includes support for user defined groupings of content called indexes.
Hugo includes support for user defined groupings of content called
taxonomies. Taxonomies give us a way to classify our content so we can
demonstrate relationships in a variety of logical ways.
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.
The default taxonomies for Hugo are tags and categories. These
taxonomies are common to many websites systems (Wordpress, Drupal,
Jekyll). Unlike all of those Systems, Hugo makes it trivial to customize
the taxonomies you will be using for your site however you wish. Another
good use for taxonomies is to group a set of posts into a series. Other
common uses would include categories, tags, groups, series and many
more.
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.
When taxonomies are used (and templates are provided) Hugo will
automatically create pages listing all of the taxonomies, their terms
and all of the content attached to those terms.
In the hugo internals this is stored as `Site.Indexes[Plural][key][]pages`.
For example all the content tagged with Go would be found at
`Site.Indexes["tags"]["Go"]`.
## Definitions
For a
more complete example see the source of [this docs site](http://github.com/spf13/hugo/docs/).
**Taxonomy:** A categorization that can be used to classify content
## Defining Indexes for a site
**Term:** A key within that taxonomy
Indexes must be defined in the site configuration, before they
can be used throughout the site.
**Value:** A piece of content assigned to that Term
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.
## Example
### config.yaml
For example if I was writing about movies I may want the following
taxonomies:
---
indexes:
tag: "tags"
category: "categories"
baseurl: "http://spf13.com/"
title: "Steve Francia is spf13.com"
---
* Actors
* Directors
* Studios
* Genre
* Year
* Awards
## Assigning index values to content
I would then specify in each movies front-matter the specific terms for
each of those taxonomies. Hugo would then automatically create pages for
each Actor, Director, Studio, Genre, Year and Award listing all of the
Movies that matched that specific Actor, Director, etc.
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.
### Taxonomy Organization
**Index values are case insensitive**
Lets use an example to demonstrate the different labels in action.
From the perspective of the taxonomy it could be visualized as:
### Example
Actor <- Taxonomy
Bruce Willis <- Term
The Six Sense <- Content
Unbreakable <- Content
Moonrise Kingdom <- Content
Samuel L. Jackson <- Term
Unbreakable <- Content
The Avengers <- Content
xXx <- Content
{
"title": "Hugo: A fast and flexible static site generator",
"tags": [
"Development",
"Go",
"fast",
"Blogging"
],
"categories" : [
"Development"
]
"slug": "hugo",
"project_url": "http://github.com/spf13/hugo"
}
From the perspective of the content if would appear differently, though
the data and labels used are the same:
Unbreakable <- Content
Actors <- Taxonomy
Bruce Willis <- Term
Samuel L. Jackson <- Term
Director <- Taxonomy
M. Night Shyamalan <- Term
...
Moonrise Kingdom <- Content
Actors <- Taxonomy
Bruce Willis <- Term
Bill Murray <- Term
Director <- Taxonomy
Wes Anderson <- Term
...

View file

@ -7,50 +7,18 @@ weight: 30
menu:
main:
parent: 'taxonomy'
prev: "/templates/displaying"
next: "/taxonomies/ordering"
---
There are two different templates that the use of indexes will require you to provide.
There are two different templates that the use of taxonomies 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.
Both templates are covered in detail in the templates section.
## 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/`.
A [list template](/templates/list/) is any template that will be used to render multiple pieces of
content in a single html page. This template will be used to generate
all the automatically created taxonomy pages.
The template must be called the singular name of the index and placed in
layouts/indexes
A [taxonomy terms template](/templates/terms/) is a template used to
generate the list of terms for a given template.
.
└── layouts
└── indexes
└── category.html
The template will be provided Data about the index.
## Variables
The following variables are available to the index template:
**.Title** The title for the content. <br>
**.Date** The date the content is published on.<br>
**.Permalink** The Permanent link for this page.<br>
**.RSSLink** Link to the indexes' rss link. <br>
**.Data.Pages** The content that is assigned this index.<br>
**.Data.`singular`** The index itself.<br>
## Example
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "chrome/footer.html" }}

View file

@ -0,0 +1,60 @@
---
title: "Using Taxonomies"
linktitle: "Usage"
date: "2014-05-26"
weight: 15
menu:
main:
parent: 'taxonomy'
prev: "/taxonomies/overview"
next: "/taxonomies/displaying"
---
## Defining taxonomies for a site
Taxonomies must be defined in the site configuration, before they can be
used throughout the site. You need to provide both the plural and
singular labels for each taxonomy.
Here is an example configuration in YAML that specifies two taxonomies.
Notice the format is **singular key** : *plural value*.
### config.yaml
---
taxonomies:
tag: "tags"
category: "categories"
series: "series"
---
## Assigning taxonomy values to content
Once an taxonomy 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 taxonomy is done in the front matter.
Simply create a variable with the *plural* name of the taxonomy
and assign all terms you want to apply to this content.
**taxonomy values are case insensitive**
### Front Matter Example (in JSON)
{
"title": "Hugo: A fast and flexible static site generator",
"tags": [
"Development",
"Go",
"fast",
"Blogging"
],
"categories" : [
"Development"
],
"series" : [
"Go Web Dev"
],
"slug": "hugo",
"project_url": "http://github.com/spf13/hugo"
}

View file

@ -1,10 +1,15 @@
---
title: "404.html Templates"
linktitle: "404"
date: "2013-08-21"
notoc: true
weight: 100
menu:
main:
parent: 'layout'
aliases: ["/layout/404/"]
prev: "/templates/sitemap"
next: "/taxonomies/overview"
---
When using Hugo with [github pages](http://pages.github.com/) you can provide

View file

@ -1,44 +1,71 @@
---
title: "Content Templates"
title: "Single Content Template"
linktitle: "Single"
date: "2013-07-01"
weight: 30
menu:
main:
parent: 'layout'
aliases: ["/layout/functions/"]
prev: "/templates/variables"
next: "/templates/list"
---
Content templates are created in a directory matching the name of the content.
The primary view of content in hugo is the single view. Hugo for every
markdown file provided hugo will render it with a single template.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
Users can specify the `type` and `layout` in the [front-matter](/content/front-matter). `Section`
is determined based on the content files location. If `type` is provide
it will be used instead of `section`.
### Single
* /layouts/`TYPE` or `SECTION`/`LAYOUT`.html
* /layouts/`TYPE` or `SECTION`/single.html
* /layouts/\_default/single.html
* /themes/`THEME`/layouts/`TYPE` or `SECTION`/`LAYOUT`.html
* /themes/`THEME`/layouts/`TYPE` or `SECTION`/single.html
* /themes/`THEME`/layouts/\_default/single.html
## Example Single Template File
Content pages are of the type "page" and have all the [page
variables](/layout/variables/) available to use in the templates.
variables](/layout/variables/) and [site
variables](/templates/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.
The 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".
▾ layouts/
▾ _default/
single.html
▾ 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)
It makes use of [partial templates](/layout/partials)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
@ -77,17 +104,17 @@ It makes use of [chrome templates](/layout/chrome)
</div>
</aside>
{{ template "chrome/disqus.html" . }}
{{ template "chrome/footer.html" . }}
{{ template "partials/disqus.html" . }}
{{ template "partials/footer.html" . }}
## project/single.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome)
It makes use of [partial templates](/layout/partials)
{{ template "chrome/header.html" . }}
{{ template "chrome/subheader.html" . }}
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
{{ $baseurl := .Site.BaseUrl }}
<section id="main">
@ -124,9 +151,10 @@ It makes use of [chrome templates](/layout/chrome)
</div>
{{ end }}
{{ template "chrome/footer.html" }}
{{ template "partials/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.
present in the front matter than it can be used in the template. To
easily generate new content of this type with these keys ready use
[content archetypes](/content/archetypes).

View file

@ -1,11 +1,14 @@
---
title: "Template Functions"
title: "Hugo Template Functions"
date: "2013-07-01"
linktitle: "Template Functions"
weight: 70
linktitle: "Functions"
aliases: ["/layout/functions/"]
weight: 20
menu:
main:
parent: 'layout'
prev: "/templates/go-templates"
next: "/templates/variables"
---
Hugo uses the excellent go html/template library for its template engine.

View file

@ -1,10 +1,13 @@
---
title: "Using Go Templates"
title: "Go Template Primer"
date: "2013-07-01"
aliases: ["/layout/go-templates/"]
weight: 15
menu:
main:
parent: 'layout'
prev: "/templates/overview"
next: "/templates/functions"
---
Hugo uses the excellent [go][] [html/template][gohtmltemplate] library for

View file

@ -0,0 +1,77 @@
---
title: "Homepage"
date: "2013-07-01"
weight: 50
notoc: true
menu:
main:
parent: 'layout'
aliases: ["/layout/homepage/"]
prev: "/templates/list"
next: "/templates/terms"
---
The home page of a website is often formatted differently than the other
pages. In Hugo you can define your own homepage template.
Homepage is of the type "node" and have all the [node
variables](/templates/variables/) and [site
variables](/templates/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. It is also the only required
template when using a single page site.*
In addition to the standard node variables, the homepage has access to
all site content accessible from .Data.Pages . Details on how to use the
list of pages can be found in the [Lists Template](/templates/list/)
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
* /layouts/index.html
* /layouts/\_default/list.html
* /layouts/\_default/single.html
* /themes/`THEME`/layouts/index.html
* /themes/`THEME`/layouts/\_default/list.html
* /themes/`THEME`/layouts/\_default/single.html
## example index.html
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/templates/partials) and uses a similar approach as a [List](/templates/list/).
<!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 "partials/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 "partials/head_includes.html" . }}
</head>
<body lang="en">
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
{{ range first 10 .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "partials/footer.html" }}

View file

@ -0,0 +1,216 @@
---
title: "Content List Template"
linktitle: "List"
date: "2013-07-01"
weight: 40
menu:
main:
parent: 'layout'
aliases: ["/layout/indexes/"]
prev: "/templates/content"
next: "/templates/homepage"
---
A list template is any template that will be used to render multiple pieces of
content in a single html page (with the exception of the [homepage](/layout/homepage) which has a
dedicated template).
We are using the term list in its truest sense, a sequential arrangement
of material, especially in alphabetical or numerical order. Hugo uses
list templates to render anyplace where content is being listed such as
taxonomies and sections.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
### Section Lists
A Section will be rendered at /`SECTION`/
* /layouts/section/`SECTION`.html
* /layouts/\_default/section.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/section/`SECTION`.html
* /themes/`THEME`/\_default/section.html
* /themes/`THEME`/layouts/\_default/list.html
### Taxonomy Lists
A Taxonomy will be rendered at /`PLURAL`/`TERM`/
* /layouts/taxonomy/`SINGULAR`.html
* /layouts/\_default/taxonomy.html
* /layouts/\_default/list.html
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.html
* /themes/`THEME`/\_default/taxonomy.html
* /themes/`THEME`/layouts/\_default/list.html
### Section RSS
A Sections RSS will be rendered at /`SECTION`/index.xml
*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will
be sufficient and an RSS template will not need to be provided by the
user.*
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
### Taxonomy RSS
A Taxonomys RSS will be rendered at /`PLURAL`/`TERM`/index.xml
*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will
be sufficient and an RSS template will not need to be provided by the
user.*
Hugo provides the ability for you to define any RSS type you wish, and
can have different RSS files for each section and taxonomy.
* /layouts/taxonomy/`SINGULAR`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
## Variables
List pages are of the type "node" and have all the [node
variables](/templates/variables/) and [site
variables](/templates/variables/) available to use in the templates.
Taxonomy pages will additionally have:
**.Data.`singular`** The taxonomy itself.<br>
## Example List Template Pages
### Example section template (post.html)
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/templates/partials). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul id="list">
{{ range .Data.Pages }}
{{ .Render "li"}}
{{ end }}
</ul>
</div>
</section>
{{ template "partials/footer.html" }}
### Example taxonomy template (tag.html)
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/templates/partials). All examples use a
[view](/templates/views/) called either "li" or "summary" which this example site
defined.
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{ template "partials/footer.html" }}
## Ordering Content
In the case of Hugo each list will render the content based on metadata provided in the [front
matter](/content/front-matter). See [ordering content](/content/ordering) for more information.
Here are a variety of different ways you can order the content items in
your list templates:
### Order by Weight -> Date (default)
{{ range .Data.Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Weight -> Date
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Date
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Length
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by Title
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Order by LinkTitle
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
### Reverse Order
Can be applied to any of the above. Using Date for an example.
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}

View file

@ -0,0 +1,69 @@
---
title: "Hugo Templates"
date: "2013-07-01"
aliases: ["/doc/templates/", "/layout/templates/"]
linktitle: "Overview"
weight: 10
menu:
main:
parent: 'layout'
prev: "/themes/creation"
next: "/templates/go-templates"
---
Hugo uses the excellent go html/template library for its 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.
While Hugo has a number of different template roles, most complete
websites can be built using just a small number of template files.
Please dont be afraid of the variety of different template roles. They
are enable Hugo to build very complicated sites. Most sites will only
need to create a [/layouts/\_default/single.html](/templates/content) & [/layouts/\_default/list.html](/templates/list)
If you are new to go's templates the [go template primer](/layout/go-templates)
is a great place to start.
If you are familiar with gos templates, Hugo provides some [additional
template functions](/templates/functions) and [variables](/templates/variables) you will want to be familiar
with.
## Primary Template roles
There are 3 primary kinds of templates that Hugo works with.
### [Single](/templates/content)
Render a single piece of content
### [List](/templates/list)
Page that list multiple pieces of content
### [Homepage](/templates/homepage/)
The homepage of your site
## Supporting Template Roles (optional)
Hugo also has additional kinds of templates all of which are optional
### [Partial Templates](/templates/partials)
Common page parts to be included in the above mentioned templates
### [Content Views](/templates/views)
Different ways of rendering a (single) content type
### [Taxonomy Terms](/templates/terms)
A list of the terms used for a specific taxonomy eg. a Tag cloud
## Other Templates (generally unncessary)
### [RSS](/templates/rss/)
Used to render all rss documents
### [Sitemap](/templates/sitemap/)
Used to render the XML sitemap
### [404](/templates/404)
This template will create a 404.html page used when hosting on github pages

View file

@ -1,33 +1,35 @@
---
title: "Chrome Templates"
title: "Partial Templates"
date: "2013-07-01"
weight: 80
menu:
main:
parent: 'layout'
aliases: ["/layout/chrome/"]
prev: "/templates/views"
next: "/templates/rss"
---
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.
It's not a requirement to have this, but in practice it's very
convenient to split out common template portions into a partial template
that can be included anywhere. As you create the rest of your templates
you will include templates from the /layout/partials directory. Hugo
doesn't know anything about partials, it's simply a convention that you
may likely find beneficial.
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.
I've found it helpful to include a header and footer template in
partials so I can include those in all the full page layouts. 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/
partials/
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.
By ensuring that we only reference [variables](/layout/variables/)
used for both nodes and pages we can use the same partials for both.
## example header.html
This header template is used for [spf13.com](http://spf13.com).
@ -37,14 +39,14 @@ This header template is used for [spf13.com](http://spf13.com).
<head>
<meta charset="utf-8">
{{ template "chrome/meta.html" . }}
{{ template "partials/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" . }}
{{ template "partials/head_includes.html" . }}
</head>
<body lang="en">
@ -78,5 +80,5 @@ This header template is used for [spf13.com](http://spf13.com).
</body>
</html>
**For examples of referencing these templates, see [content
templates](/layout/content/) and [homepage templates](/layout/homepage/)**
**For examples of referencing these templates, see [single content
templates](/templates/content), [list templates](/templates/list) and [homepage templates](/templates/homepage)**

View file

@ -0,0 +1,99 @@
---
title: "RSS (feed) Templates"
linktitle: "RSS"
date: "2013-07-01"
weight: 90
notoc: "one"
menu:
main:
parent: 'layout'
aliases: ["/layout/rss/"]
prev: "/templates/partials"
next: "/templates/sitemap"
---
Like all other templates, you can use a single RSS template to generate
all of your RSS feeds or you can create a specific template for each
individual feed. Unlinke other templates, *Hugo ships with its own ATOM
2.0 RSS template. In most cases this will be sufficient and an RSS
template will not need to be provided by the user.*
RSS pages are of the type "node" and have all the [node
variables](/layout/variables/) available to use in the templates.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
### Main RSS
* /layouts/rss.xml
* /layouts/\_default/rss.xml
* \__internal/rss.xml
### Section RSS
* /layouts/section/`SECTION`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/section/`SECTION`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* \__internal/rss.xml
### Taxonomy RSS
* /layouts/taxonomy/`SINGULAR`.rss.xml
* /layouts/\_default/rss.xml
* /themes/`THEME`/layouts/taxonomy/`SINGULAR`.rss.xml
* /themes/`THEME`/layouts/\_default/rss.xml
* \__internal/rss.xml
## Configuring RSS
If the following are provided in the sites config file then then they
will be included in the RSS output. Example values are provided.
languageCode = "en-us"
copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License."
[author]
name = "My Name Here"
## The Embedded rss.xml
This is the RSS template that ships with Hugo. 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>
<generator uri="https://hugo.spf13.com">Hugo</generator>
<link>{{ .Permalink }}</link>
{{ with .Site.LanguageCode }}<language>{{.}}</language>{{end}}
{{ with .Site.Author.name }}<author>{{.}}</author>{{end}}
{{ with .Site.Copyright }}<copyright>{{.}}</copyright>{{end}}
<updated>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</updated>
{{ range first 15 .Data.Pages }}
<item>
<title>{{ .Title }}</title>
<link>{{ .Permalink }}</link>
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</pubDate>
{{with .Site.Author.name}}<author>{{.}}</author>{{end}}
<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" ?>

View file

@ -1,14 +1,20 @@
---
title: "Sitemap Template"
linktitle: "Sitemap"
date: "2014-05-07"
weight: 45
weight: 95
notoc: true
menu:
main:
parent: 'layout'
aliases: ["/layout/sitemap/"]
prev: "/templates/rss"
next: "/templates/404"
---
A single Sitemap template is used to generate the `sitemap.xml` file.
Hugo Automatically comes with this template file. **No work is needed on
the users part unless they want to customize the sitemap.xml.**
This page is of the type "node" and have all the [node
variables](/layout/variables/) available to use in this template
@ -20,10 +26,10 @@ along with Sitemap-specific ones:
In addition to the standard node variables, the homepage has access to all
site pages through `.Data.Pages`.
▾ layouts/
sitemap.xml
If provided Hugo will use /layouts/sitemap.xml instead of the internal
one.
## sitemap.xml
## Hugos sitemap.xml
This template respects the version 0.9 of the [Sitemap
Protocol](http://www.sitemaps.org/protocol.html).

View file

@ -0,0 +1,131 @@
---
title: "Taxonomy Terms Template"
linktitle: "Taxonomy Terms"
date: "2014-05-21"
weight: 60
aliases: ["/indexes/lists/","/doc/indexes/", "/extras/indexes"]
menu:
main:
parent: 'layout'
prev: "/templates/homepage"
next: "/templates/views"
---
A unique template is needed to create a list of the terms for a given
taxonomy. This is different from the [list template](/templates/list/)
as that template is a list of content, where this is a list of meta data.
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
A Taxonomy Terms List will be rendered at /`PLURAL`/
* /layouts/taxonomy/`SINGLE`.terms.html
* /layouts/\_default/terms.html
If that neither file is found in either the /layouts or /theme/layouts
directory than hugo will not render the taxonomy terms pages. It is also
common for people to render taxonomy terms lists on other pages such as
the homepage or the sidebar (such as a tag cloud) and not have a
dedicated page for the terms.
## Variables
Taxonomy Terms pages are of the type "node" and have all the [node
variables](/templates/variables/) and [site
variables](/templates/variables/) available to use in the templates.
Taxonomy Terms pages will additionally have:
**.Data.Singular** The singular name of the taxonomy <br>
**.Data.Plural** The plural name of the taxonomy<br>
**.Data.Terms** The taxonomy itself<br>
**.Data.Terms.Alphabetical** The Terms alphabetized<br>
**.Data.Terms.ByCount** The Terms ordered by popularity<br>
## Example terms.html file
List pages are of the type "node" and have all the [node
variables](/templates/variables/) and [site
variables](/templates/variables/) available to use in the templates.
This content template is used for [spf13.com](http://spf13.com).
It makes use of [partial templates](/templates/partials). The list of indexes
templates cannot use a [content view](/templates/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.
.Data.Terms is an map of terms => [contents]
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Terms }}
<li><a href="{{ $data.Plural }}/{{ $key | urlize }}"> {{ $key }} </a> {{ len $value }} </li>
{{ end }}
</ul>
</div>
</section>
{{ template "partials/footer.html" }}
## Ordering
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 "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Terms.Alphabetical }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
</div>
</section>
{{ template "partials/footer.html" }}
## Example indexes.html file (ordered)
{{ template "partials/header.html" . }}
{{ template "partials/subheader.html" . }}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Terms.ByCount }}
<li><a href="{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
{{ end }}
</ul>
</div>
</section>
{{ template "partials/footer.html" }}

View file

@ -1,11 +1,14 @@
---
title: "Variables"
title: "Template Variables"
linktitle: "Variables"
date: "2013-07-01"
aliases: ["/doc/variables/"]
aliases: ["/doc/variables/","/layout/variables/"]
weight: 20
menu:
main:
parent: 'layout'
prev: "/templates/functions"
next: "/templates/content"
---
Hugo makes a set of values available to the templates. Go templates are context based. The following

View file

@ -0,0 +1,126 @@
---
title: "Content Views"
date: "2013-07-01"
weight: 70
menu:
main:
parent: 'layout'
aliases: ["/templates/views/"]
prev: "/templates/terms"
next: "/templates/partials"
---
In addition to the [single content template](/templates/content/), Hugo can render alternative views of
your content. These are especially useful in [list templates](/templates/list).
For example you may want content of every type to be shown on the
homepage, but only a summary view of it there. Perhaps on a taxonomy
list page you would only want a bulleted list of your content. Views
make this very straightforward by delegating the rendering of each
different type of content to the content itself.
## Creating a content view
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](/templates/content) template "single.html". You can even
provide a specific view for a given type and continue to use the
\_default/single.html for the primary view.
▾ 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
## Which Template will be rendered?
Hugo uses a set of rules to figure out which template to use when
rendering a specific page.
Hugo will use the following prioritized list. If a file isnt present
than the next one in the list will be used. This enables you to craft
specific layouts when you want to without creating more templates
then necessary. For most sites only the \_default file at the end of
the list will be needed.
* /layouts/`TYPE`/`VIEW`.html
* /layouts/\_default/`VIEW`.html
* /themes/`THEME`/layouts/`TYPE`/`VIEW`.html
* /themes/`THEME`/layouts/\_default/`view`.html
## Example using views
### rendering view inside of a list
Using the summary view (defined below) inside of a ([list
templates](/templates/list)).
<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.
In this example we are not using the li view. To use this we would
change the render line to `{{ .Render "li" }}`.
### li.html
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables) for a complete list.
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>
### summary.html
Hugo will pass the entire page object to the view template. See [page
variables](/templates/variables) for a complete list.
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>

View file

@ -0,0 +1,65 @@
+++
title = "Creating a Theme"
weight = 50
date = 2014-05-12T10:09:17Z
prev = "/themes/customizing"
next = "/templates/overview"
[menu]
[menu.main]
parent = "themes"
+++
Hugo has the ability to create a new theme in your themes directory for you
using the `hugo new` command.
`hugo new theme [name]`
This command will initialize all of the files and directories a basic theme
would need. Hugo themes are written in the go template language. If you are new
to Go, the [go template primer](/templates/primer/) will help you get started.
## Theme Components
A theme consists of templates and static assets such as javascript and css
files. Themes can also optionally provide [archetypes](/content/archetypes)
which are archetypal content types used by the `hugo new` command.
### Layouts
Hugo is built around the concept that things should be as simple as possible.
Fundamentally website content is displayed in two different ways, a single
piece of content and a list of content items. With Hugo a theme layout starts
with the defaults. As additional layouts are defined they are used for the
content type or section they apply to. This keeps layouts simple, but permits
a large amount of flexibility.
### Single Content
The default single file layout is located at `layouts/_default/single.html`.
### List of Contents
The default list file layout is located at `layouts/_default/list.html`
### Static
Everything in the static directory will be copied directly into the final site
when rendered. No structure is provided here to enable complete freedom. It is
common to organize the static content into
/css
/js
/img
The actual structure is entirely up to you, the theme creator, on how you would like to organize your files.
### Archetypes
If your theme makes use of specific keys in the front matter it is a good idea
to provide an archetype for each content type you have. Archetypes follow the
[guidelines provided](/content/archetypes).

View file

@ -0,0 +1,54 @@
+++
title = "Customizing a Theme"
weight = 40
date = 2014-05-12T10:09:34Z
prev = "/themes/usage"
next = "/themes/creation"
[menu]
[menu.main]
parent = "themes"
+++
Hugo themes permit you to supplement or override any template or file
from within your working directory.
## Replacing Static files
If you would like to include a different file than the theme ships
with.. For example you would like to use a more recent version of jquery
then the theme happens to include simply place an identically name file in the same
relative location but in your working directory. For example if the
theme has jquery 1.6 in /themes/themename/static/js/jQuery.min.js, simply place your file
in the same relative path /static/js/jQuery.min.js.
## Replace a single template file
Anytime Hugo looks for a matching template it will first check the
working directory before looking in the theme directory. If you would
like to modify a template simply create that template in your local
layouts directory. In the [template documentation](/templates/overview/)
each different template type explains the rules it uses to determine
which template to use.
**warning.. This only works for templates that Hugo knows about. If the
theme creates partial template files in a creatively named directory
Hugo wont know to look for the local /layouts first**
## Replace an archetype
If the archetype that ships with the theme for a given content type (or
all content types) doesnt fit with how you are using the theme, feel
free to copy it to your /archetypes directory and make modifications as
you see fit.
## Beware of the default
**Default** is a very powerful force in Hugo... Especially as it pertains to
overwriting theme files. If a default is located in the local archetype
directory or /layouts/\_default/ directory it will be used instead of
any of the similar files in the theme.
It is usually better to override specific files rather than using the
default in your working directory.

View file

@ -0,0 +1,29 @@
+++
title = "Installing Themes"
weight = 20
date = 2014-05-12T10:09:49Z
prev = "/themes/overview"
next = "/themes/usage"
[menu]
[menu.main]
parent = "themes"
+++
Hugo themes are located in a centralized github repository. [Hugo Themes
Repo](http://github.com/spf13/hugoThemes) itself is really a meta
repository which contains pointers to set of contributed themes.
## Installing all themes
If you would like to install all of the available hugo themes, simply
clone the entire repository from within your working directory.
git clone --recursive https://github.com/spf13/hugoThemes.git themes
## Installing a specific theme
mkdir themes
cd themes
git clone URL_TO_THEME

View file

@ -0,0 +1,32 @@
+++
title = "Themes Overview"
weight = 10
date = 2014-05-12T10:03:52Z
prev = "/content/example"
next = "/themes/installing"
[menu]
[menu.main]
parent = "themes"
+++
Hugo provides a robust theming system which is simple, yet capable of producing
even the most complicated websites.
The Hugo community has created a set of themes ready for using in your own
site.
Hugo themes have been designed to be the perfect balance between
simplicity and functionality. Hugo themes are powered by the excellent
go template library. If you are new to go templates, see our [primer on
go templates](/layouts/go-templates).
Hugo themes support all modern features you come to expect. They are
structured in such a way to eliminate code duplication. Themes are also
designed to be very easy to customize while retaining the ability to
maintain upgradeability as the upstream theme changes.
Hugo currently doesnt ship with a “default” theme, allowing the user to
pick whichever theme best suits their project.
We hope you will find Hugo themes perfect for your site.

View file

@ -0,0 +1,23 @@
+++
title = "Using a Theme"
weight = 30
date = 2014-05-12T10:09:27Z
prev = "/themes/installing"
next = "/themes/customizing"
[menu]
[menu.main]
parent = "themes"
+++
Please make certain you have installed the themes you want to use in the
/themes directory.
To use a theme for a site:
hugo -t ThemeName
The ThemeName must match the name of the directory inside /themes
Hugo will then apply the theme first, then apply anything that is in the local
directory. To learn more, goto [customizing themes](/themes/customizing)

View file

@ -1,11 +1,14 @@
---
title: "Hosting a Blog on GitHub Pages"
title: "Hosting on GitHub Pages"
linktitle: "Hosting on GitHub"
date: "2014-03-21"
weight: 10
author: "Spencer Lyon"
menu:
main:
parent: 'tutorials'
prev: "/community/contributors"
next: "/tutorials/mathjax"
---
## Intro

View file

@ -6,6 +6,8 @@ author: "Spencer Lyon"
menu:
main:
parent: 'tutorials'
prev: "/tutorials/github_pages_blog"
next: "/tutorials/migrate-from-jekyll"
---
## What is MathJax?

View file

@ -1,10 +1,12 @@
---
title: "Migrate to Hugo from Jekyll"
linktitle: "Migrating from Jekyll"
date: "2014-03-10"
weight: 10
menu:
main:
parent: 'tutorials'
prev: "/tutorials/mathjax"
---
## Move static content to `static`
@ -135,11 +137,11 @@ is written as this Hugo shortcode:
### Usage
I simply changed:
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):
{{% fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" %}}
{{% fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" %}}
As a bonus, the shortcode named parameters are, arguably, more readable.