mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Updating / Rewriting / Adding all of the documentation in preparation for the next release
This commit is contained in:
spf13
parent
aeb06c7bcc
commit
a87f171bd4
64 changed files with 2092 additions and 982 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ weight: 10
|
|||
menu:
|
||||
main:
|
||||
parent: 'community'
|
||||
prev: "/extras/urls"
|
||||
next: "/community/press"
|
||||
---
|
||||
|
||||
Hugo has two mailing lists:
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
+++
|
||||
|
|
|
|||
76
docs/content/content/archetypes.md
Normal file
76
docs/content/content/archetypes.md
Normal 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.
|
||||
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
60
docs/content/extras/builders.md
Normal file
60
docs/content/extras/builders.md
Normal 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.
|
||||
|
||||
|
||||
67
docs/content/extras/comments.md
Normal file
67
docs/content/extras/comments.md
Normal 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
|
||||
doesn’t 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 doesn’t 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) (Hugo’s 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.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
61
docs/content/extras/livereload.md
Normal file
61
docs/content/extras/livereload.md
Normal 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 it’s the first to do it right.
|
||||
|
||||
The combination of Hugo’s 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, we’ve made it easy to disable the
|
||||
live reload functionality.
|
||||
|
||||
hugo server --watch --disableLiveReload
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
162
docs/content/extras/menus.md
Normal file
162
docs/content/extras/menus.md
Normal 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 aren’t attached to a piece of
|
||||
content. This takes place in the site wide config file.
|
||||
|
||||
Here’s 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-->
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" . }}
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" }}
|
||||
|
|
@ -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" }}
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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" ?>
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
...
|
||||
|
||||
|
|
|
|||
|
|
@ -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 you’ve
|
||||
placed in your path.
|
||||
|
||||
|
||||
## Installing from source
|
||||
|
||||
### Dependencies
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
|
|
|
|||
|
|
@ -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 doesn’t 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, let’s 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 it’s 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.
|
||||
|
||||
It’s especially productive to leave a browser open on a second monitor
|
||||
and just glance at it whenever you save. You don’t 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
|
||||
|
|
@ -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. It’s 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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
Let’s 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
|
||||
...
|
||||
|
||||
|
|
|
|||
|
|
@ -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" }}
|
||||
|
|
|
|||
60
docs/content/taxonomies/usage.md
Normal file
60
docs/content/taxonomies/usage.md
Normal 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"
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
@ -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 isn’t 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 file’s 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).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
77
docs/content/templates/homepage.md
Normal file
77
docs/content/templates/homepage.md
Normal 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 isn’t 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" }}
|
||||
216
docs/content/templates/list.md
Normal file
216
docs/content/templates/list.md
Normal 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 isn’t 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 Section’s RSS will be rendered at /`SECTION`/index.xml
|
||||
|
||||
*Hugo ships with it’s 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 Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml
|
||||
|
||||
*Hugo ships with it’s 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 }}
|
||||
69
docs/content/templates/overview.md
Normal file
69
docs/content/templates/overview.md
Normal 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 don’t 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 go’s 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
|
||||
|
||||
|
||||
|
|
@ -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)**
|
||||
99
docs/content/templates/rss.md
Normal file
99
docs/content/templates/rss.md
Normal 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 it’s 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 isn’t 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 site’s 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" ?>
|
||||
|
|
@ -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
|
||||
## Hugo’s sitemap.xml
|
||||
|
||||
This template respects the version 0.9 of the [Sitemap
|
||||
Protocol](http://www.sitemaps.org/protocol.html).
|
||||
131
docs/content/templates/terms.md
Normal file
131
docs/content/templates/terms.md
Normal 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 isn’t 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" }}
|
||||
|
||||
|
|
@ -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
|
||||
126
docs/content/templates/views.md
Normal file
126
docs/content/templates/views.md
Normal 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 isn’t 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>
|
||||
|
||||
|
||||
65
docs/content/themes/creation.md
Normal file
65
docs/content/themes/creation.md
Normal 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).
|
||||
|
||||
54
docs/content/themes/customizing.md
Normal file
54
docs/content/themes/customizing.md
Normal 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 won’t 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) doesn’t 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.
|
||||
29
docs/content/themes/installing.md
Normal file
29
docs/content/themes/installing.md
Normal 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
|
||||
32
docs/content/themes/overview.md
Normal file
32
docs/content/themes/overview.md
Normal 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 doesn’t 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.
|
||||
23
docs/content/themes/usage.md
Normal file
23
docs/content/themes/usage.md
Normal 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)
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ author: "Spencer Lyon"
|
|||
menu:
|
||||
main:
|
||||
parent: 'tutorials'
|
||||
prev: "/tutorials/github_pages_blog"
|
||||
next: "/tutorials/migrate-from-jekyll"
|
||||
---
|
||||
|
||||
## What is MathJax?
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue