2013-07-04 11:34:22 -04:00
|
|
|
# Hugo
|
2013-07-04 11:26:26 -04:00
|
|
|
|
2013-07-04 11:34:22 -04:00
|
|
|
A really fast static site generator written in GoLang.
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
Hugo is a static site generator written in GoLang. It is optimized for
|
2013-07-04 11:34:22 -04:00
|
|
|
speed, easy use and configurability. Hugo takes a directory with content and
|
|
|
|
templates and renders them into a full html website.
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
Hugo makes use of markdown files with front matter for meta data.
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
A typical website of moderate size can be
|
2013-07-04 11:34:22 -04:00
|
|
|
rendered in a fraction of a second. It is written to work well with any
|
2013-07-22 13:32:25 -04:00
|
|
|
kind of website including blogs, tumbles and docs.
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
|
|
|
|
# Getting Started
|
|
|
|
|
|
|
|
## Installing Hugo
|
|
|
|
|
2013-07-05 00:35:11 -04:00
|
|
|
Hugo is written in GoLang with support for Windows, Linux, FreeBSD and OSX.
|
|
|
|
|
2013-07-05 00:37:26 -04:00
|
|
|
The latest release can be found at [hugo releases](https://github.com/spf13/hugo/releases).
|
2013-07-05 00:35:11 -04:00
|
|
|
We currently build for Windows, Linux, FreeBSD and OS X for x64
|
2013-07-22 13:32:25 -04:00
|
|
|
and 386 architectures.
|
2013-07-05 00:35:11 -04:00
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
### Installing Hugo (binary)
|
2013-07-24 11:43:23 -04:00
|
|
|
|
2013-07-04 11:34:22 -04:00
|
|
|
Installation is very easy. Simply download the appropriate version for your
|
2013-07-24 11:43:23 -04:00
|
|
|
platform from [hugo releases](https://github.com/spf13/hugo/releases).
|
|
|
|
Once downloaded it can be run from anywhere. You don't need to install
|
2013-07-05 00:35:11 -04:00
|
|
|
it into a global location. This works well for shared hosts and other systems
|
|
|
|
where you don't have a privileged account.
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-24 11:43:23 -04:00
|
|
|
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
|
2013-07-04 11:34:22 -04:00
|
|
|
is the most probable location.
|
|
|
|
|
2013-07-24 11:43:23 -04:00
|
|
|
*the Hugo executible has no external dependencies.*
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
### Installing from source
|
2013-07-04 13:03:16 -04:00
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
#### Dependencies
|
2013-07-19 01:27:21 -04:00
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
* Git
|
|
|
|
* Go 1.1+
|
|
|
|
* Mercurial
|
2013-07-24 11:27:03 -04:00
|
|
|
* Bazaar
|
2013-07-22 13:32:25 -04:00
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
#### Clone locally (for contributors):
|
2013-07-22 13:32:25 -04:00
|
|
|
|
2013-07-04 13:03:16 -04:00
|
|
|
git clone https://github.com/spf13/hugo
|
|
|
|
cd hugo
|
2013-07-19 01:27:21 -04:00
|
|
|
go get
|
2013-07-04 13:03:16 -04:00
|
|
|
|
2013-07-24 11:43:23 -04:00
|
|
|
Because go expects all of your libraries to be found in either $GOROOT or $GOPATH,
|
|
|
|
it's helpful to symlink the project to one of the following paths:
|
|
|
|
|
|
|
|
* ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo
|
|
|
|
* ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo
|
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
#### Get directly from Github:
|
2013-07-24 11:43:23 -04:00
|
|
|
|
|
|
|
If you don't intend to contribute, it's even easier.
|
2013-07-24 11:27:03 -04:00
|
|
|
|
|
|
|
go get github.com/spf13/hugo
|
2013-07-04 13:03:16 -04:00
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
#### Running Hugo
|
2013-07-19 01:27:21 -04:00
|
|
|
|
2013-07-24 11:43:23 -04:00
|
|
|
cd /path/to/hugo
|
2013-08-02 16:30:26 -04:00
|
|
|
go install github.com/spf13/hugo/hugolibs
|
2013-07-19 01:27:21 -04:00
|
|
|
go run main.go
|
|
|
|
|
2013-07-24 11:47:58 -04:00
|
|
|
#### Building Hugo
|
2013-07-19 01:27:21 -04:00
|
|
|
|
2013-07-24 11:43:23 -04:00
|
|
|
cd /path/to/hugo
|
2013-07-19 01:27:21 -04:00
|
|
|
go build -o hugo main.go
|
2013-07-24 11:43:23 -04:00
|
|
|
mv hugo /usr/local/bin/
|
2013-07-04 13:03:16 -04:00
|
|
|
|
2013-07-04 11:34:22 -04:00
|
|
|
## Source Directory Organization
|
|
|
|
|
|
|
|
Hugo takes a single directory and uses it as the input for creating a complete website.
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
Hugo has a very small amount of configuration, while remaining highly customizable.
|
2013-07-04 11:34:22 -04:00
|
|
|
It accomplishes by assuming that you will only provide templates with the intent of
|
|
|
|
using them.
|
|
|
|
|
|
|
|
An example directory may look like:
|
|
|
|
|
|
|
|
.
|
|
|
|
├── config.json
|
|
|
|
├── content
|
|
|
|
| ├── post
|
|
|
|
| | ├── firstpost.md
|
|
|
|
| | └── secondpost.md
|
|
|
|
| └── quote
|
|
|
|
| | ├── first.md
|
|
|
|
| | └── second.md
|
|
|
|
├── layouts
|
|
|
|
| ├── chrome
|
|
|
|
| | ├── header.html
|
|
|
|
| | └── footer.html
|
|
|
|
| ├── indexes
|
|
|
|
| | ├── category.html
|
|
|
|
| | ├── post.html
|
|
|
|
| | ├── quote.html
|
|
|
|
| | └── tag.html
|
|
|
|
| ├── post
|
|
|
|
| | ├── li.html
|
|
|
|
| | ├── single.html
|
|
|
|
| | └── summary.html
|
|
|
|
| ├── quote
|
|
|
|
| | ├── li.html
|
|
|
|
| | ├── single.html
|
|
|
|
| | └── summary.html
|
|
|
|
| ├── shortcodes
|
|
|
|
| | ├── img.html
|
|
|
|
| | ├── vimeo.html
|
|
|
|
| | └── youtube.html
|
|
|
|
| ├── index.html
|
|
|
|
| └── rss.xml
|
2013-08-02 16:30:26 -04:00
|
|
|
└── static
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
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 an example site ready to be rendered.
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2013-07-11 22:04:57 -04:00
|
|
|
**Please note the field names must be all lowercase**
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-11 22:04:57 -04:00
|
|
|
### Config Examples
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
The following is an example of a yaml config file with the default values:
|
2013-07-11 23:29:14 -04:00
|
|
|
|
2013-07-11 22:04:57 -04:00
|
|
|
---
|
|
|
|
sourcedir: "content"
|
|
|
|
layoutdir: "layouts"
|
|
|
|
publishdir: "public"
|
|
|
|
builddrafts: false
|
|
|
|
indexes:
|
|
|
|
category: "categories"
|
|
|
|
tag: "tags"
|
|
|
|
baseurl: "http://yoursite.com/"
|
|
|
|
...
|
|
|
|
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
The following is an example of a json config file with the default values:
|
2013-07-11 23:29:14 -04:00
|
|
|
|
2013-07-04 11:34:22 -04:00
|
|
|
{
|
2013-07-11 22:04:57 -04:00
|
|
|
"sourcedir": "content",
|
|
|
|
"layoutdir": "layouts",
|
|
|
|
"publishdir": "public",
|
|
|
|
"builddrafts": false,
|
|
|
|
"indexes": {
|
|
|
|
category: "categories",
|
|
|
|
tag: "tags"
|
|
|
|
},
|
|
|
|
"baseurl": "http://yoursite.com/"
|
2013-07-04 11:34:22 -04:00
|
|
|
}
|
|
|
|
|
2013-07-11 22:04:57 -04:00
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
The following is an example of a toml config file with the default values:
|
2013-07-11 22:04:57 -04:00
|
|
|
|
|
|
|
sourcedir = "content"
|
|
|
|
layoutdir = "layouts"
|
|
|
|
publishdir = "public"
|
|
|
|
builddrafts = false
|
|
|
|
baseurl = "http://yoursite.com/"
|
|
|
|
[indexes]
|
|
|
|
category = "categories"
|
|
|
|
tag = "tags"
|
|
|
|
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
## Usage
|
2013-07-04 11:34:22 -04:00
|
|
|
Make sure either hugo is in your path or provide a path to it.
|
|
|
|
|
|
|
|
$ hugo --help
|
|
|
|
usage: hugo [flags] []
|
2013-07-19 03:38:24 -04:00
|
|
|
-b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
|
2013-08-02 16:30:26 -04:00
|
|
|
-D, --build-drafts=false: include content marked as draft
|
2013-07-19 03:38:24 -04:00
|
|
|
--config="": config file (default is path/config.yaml|json|toml)
|
2013-08-02 16:30:26 -04:00
|
|
|
-d, --destination="": filesystem path to write files to
|
2013-07-19 03:38:24 -04:00
|
|
|
-h, --help=false: show this help
|
|
|
|
--port="1313": port to run web server on, default :1313
|
|
|
|
-S, --server=false: run a (very) simple web server
|
|
|
|
-s, --source="": filesystem path to read files relative from
|
|
|
|
--uglyurls=false: use /filename.html instead of /filename/
|
|
|
|
-v, --verbose=false: verbose output
|
|
|
|
--version=false: which version of hugo
|
|
|
|
-w, --watch=false: watch filesystem for changes and recreate as needed
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
The most common use is probably to run hugo with your current
|
2013-07-04 11:34:22 -04:00
|
|
|
directory being the input directory.
|
|
|
|
|
|
|
|
|
|
|
|
$ hugo
|
|
|
|
> X pages created
|
2013-07-05 00:35:11 -04:00
|
|
|
> Y indexes created
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
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
|
2013-07-04 11:34:22 -04:00
|
|
|
your browser to view the changes.**
|
|
|
|
|
2013-07-19 03:38:24 -04:00
|
|
|
$ hugo --source ~/mysite --watch
|
|
|
|
Watching for changes. Press ctrl+c to stop
|
|
|
|
15 pages created
|
|
|
|
0 tags created
|
2013-08-02 16:30:26 -04:00
|
|
|
in 8 ms
|
2013-07-04 11:34:22 -04:00
|
|
|
|
2013-07-19 03:38:24 -04:00
|
|
|
Hugo can even run a server and create your site at the same time!
|
|
|
|
|
|
|
|
$hugo --server -ws ~/mysite
|
|
|
|
Watching for changes. Press ctrl+c to stop
|
|
|
|
15 pages created
|
|
|
|
0 tags created
|
2013-08-02 16:30:26 -04:00
|
|
|
in 8 ms
|
2013-07-19 03:38:24 -04:00
|
|
|
Web Server is available at http://localhost:1313
|
|
|
|
Press ctrl+c to stop
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
# Layout
|
|
|
|
|
|
|
|
Hugo is very flexible about how you organize and structure your content.
|
|
|
|
|
|
|
|
## Templates
|
|
|
|
|
|
|
|
Hugo uses the excellent golang html/template library for it's template engine. It is an extremely
|
2013-07-22 13:32:25 -04:00
|
|
|
lightweight engine that provides a very small amount of logic. In our
|
2013-07-04 11:34:22 -04:00
|
|
|
experience that it is just the right amount of logic to be able to create a good static website
|
|
|
|
|
|
|
|
This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/)
|
|
|
|
provide a good introduction.
|
|
|
|
|
|
|
|
### Template roles
|
|
|
|
|
|
|
|
There are 5 different kinds of templates that Hugo works with.
|
|
|
|
|
|
|
|
#### index.html
|
2013-07-22 13:32:25 -04:00
|
|
|
This file must exist in the layouts directory. It is the template used to render the
|
2013-07-04 11:34:22 -04:00
|
|
|
homepage of your site.
|
|
|
|
|
|
|
|
#### rss.xml
|
|
|
|
This file must exist in the layouts directory. It will be used to render all rss documents.
|
2013-07-22 13:32:25 -04:00
|
|
|
The one provided in the example application will generate an ATOM format.
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
*Important: Hugo will automatically add the following header line to this file.*
|
|
|
|
|
|
|
|
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
|
|
|
|
|
|
|
|
#### Indexes
|
2013-07-22 13:32:25 -04:00
|
|
|
An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
|
2013-07-04 11:34:22 -04:00
|
|
|
pages are good examples of indexes.
|
|
|
|
|
|
|
|
|
|
|
|
#### Content Type(s)
|
|
|
|
Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability
|
|
|
|
to render content in a variety of ways as determined by the type.
|
|
|
|
|
|
|
|
#### Chrome
|
|
|
|
Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice
|
|
|
|
it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may
|
2013-07-22 13:32:25 -04:00
|
|
|
likely find beneficial. As you create the rest of your templates you will include templates from the
|
|
|
|
/layout/chrome directory. I've found it helpful to include a header and footer template
|
2013-07-04 11:34:22 -04:00
|
|
|
in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html).
|
|
|
|
|
|
|
|
### Adding a new content type
|
|
|
|
|
|
|
|
Adding a type is easy.
|
|
|
|
|
|
|
|
**Step 1:**
|
|
|
|
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
|
|
|
|
|
|
|
|
**Step 2:**
|
|
|
|
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
|
|
|
|
|
|
|
|
**Step 3:**
|
|
|
|
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
|
|
|
|
|
|
|
|
**Step 4:**
|
2013-07-22 13:32:25 -04:00
|
|
|
Many sites support rendering content in a few different ways, for instance a single page view and a
|
2013-07-04 11:34:22 -04:00
|
|
|
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 the example site will be very helpful in order to understand how these types work.
|
|
|
|
|
|
|
|
## Variables
|
|
|
|
|
|
|
|
Hugo makes a set of values available to the templates. Go templates are context based. The following
|
|
|
|
are available in the context for the templates.
|
|
|
|
|
|
|
|
**.Title** The title for the content. <br>
|
|
|
|
**.Description** The description for the content.<br>
|
|
|
|
**.Keywords** The meta keywords for this content.<br>
|
|
|
|
**.Date** The date the content is published on.<br>
|
|
|
|
**.Indexes** These will use the field name of the plural form of the index (see tags and categories above)<br>
|
|
|
|
**.Permalink** The Permanent link for this page.<br>
|
|
|
|
**.FuzzyWordCount** The approximate number of words in the content.<br>
|
|
|
|
**.RSSLink** Link to the indexes' rss link <br>
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
Any value defined in the front matter, including indexes will be made available under `.Params`.
|
2013-07-04 11:34:22 -04:00
|
|
|
Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
**.Params.Tags** <br>
|
|
|
|
**.Params.Categories** <br>
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
Also available is `.Site` which has the following:
|
|
|
|
|
|
|
|
**.Site.BaseUrl** The base URL for the site as defined in the config.json file.<br>
|
|
|
|
**.Site.Indexes** The names of the indexes of the site.<br>
|
|
|
|
**.Site.LastChange** The date of the last change of the most recent content.<br>
|
|
|
|
**.Site.Recent** Array of all content ordered by Date, newest first<br>
|
|
|
|
|
|
|
|
# Content
|
|
|
|
Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization
|
|
|
|
that you provide for your content to minimize any extra configuration, though this can be overridden
|
|
|
|
by additional configuration in the front matter.
|
|
|
|
|
|
|
|
## Organization
|
|
|
|
In Hugo the content should be arranged in the same way they are intended for the rendered website.
|
|
|
|
Without any additional configuration the following will just work.
|
|
|
|
|
|
|
|
.
|
|
|
|
└── content
|
|
|
|
├── post
|
|
|
|
| ├── firstpost.md // <- http://site.com/post/firstpost.html
|
|
|
|
| └── secondpost.md // <- http://site.com/post/secondpost.html
|
|
|
|
└── quote
|
|
|
|
├── first.md // <- http://site.com/quote/first.html
|
|
|
|
└── second.md // <- http://site.com/quote/second.html
|
|
|
|
|
|
|
|
|
|
|
|
## Front Matter
|
|
|
|
|
|
|
|
The front matter is one of the features that gives Hugo it's strength. It enables
|
2013-07-22 13:32:25 -04:00
|
|
|
you to include the meta data of the content right with it. Hugo supports a few
|
|
|
|
different formats each with their own identifying tokens.
|
2013-07-08 22:23:54 -04:00
|
|
|
|
|
|
|
Supported formats: <br>
|
|
|
|
**YAML**, identified by '\-\-\-'. <br>
|
|
|
|
**TOML**, indentified with '+++'.<br>
|
|
|
|
**JSON**, a single JSON object which is surrounded by '{' and '}' each on their own line.
|
|
|
|
|
|
|
|
### YAML Example
|
|
|
|
|
|
|
|
---
|
|
|
|
title: "spf13-vim 3.0 release and new website"
|
|
|
|
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
|
|
|
|
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
|
|
|
|
pubdate: "2012-04-06"
|
|
|
|
categories:
|
|
|
|
- "Development"
|
|
|
|
- "VIM"
|
|
|
|
slug: "spf13-vim-3-0-release-and-new-website"
|
|
|
|
---
|
2013-07-22 13:32:25 -04:00
|
|
|
Content of the file goes Here
|
2013-07-08 22:23:54 -04:00
|
|
|
|
|
|
|
### TOML Example
|
|
|
|
|
|
|
|
+++
|
|
|
|
title = "spf13-vim 3.0 release and new website"
|
|
|
|
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
|
|
|
|
tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
|
|
|
|
Pubdate = "2012-04-06"
|
|
|
|
categories = [
|
|
|
|
"Development",
|
|
|
|
"VIM"
|
|
|
|
]
|
|
|
|
slug = "spf13-vim-3-0-release-and-new-website"
|
|
|
|
+++
|
2013-07-22 13:32:25 -04:00
|
|
|
Content of the file goes Here
|
2013-07-08 22:23:54 -04:00
|
|
|
|
|
|
|
### JSON Example
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
{
|
2013-07-08 22:23:54 -04:00
|
|
|
"title": "spf13-vim 3.0 release and new website",
|
|
|
|
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
|
|
|
|
"tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
|
|
|
|
"date": "2012-04-06",
|
|
|
|
"categories": [
|
|
|
|
"Development",
|
|
|
|
"VIM"
|
|
|
|
],
|
|
|
|
"slug": "spf13-vim-3-0-release-and-new-website",
|
2013-07-04 11:34:22 -04:00
|
|
|
}
|
2013-07-22 13:32:25 -04:00
|
|
|
Content of the file goes Here
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
### Variables
|
|
|
|
There are a few predefined variables that Hugo is aware of and utilizes. The user can also create
|
|
|
|
any variable they want to. These will be placed into the `.Params` variable available to the templates.
|
2013-07-08 22:23:54 -04:00
|
|
|
**Field names are case insensitive.**
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
#### Required
|
|
|
|
|
2013-07-08 22:23:54 -04:00
|
|
|
**title** The title for the content. <br>
|
|
|
|
**description** The description for the content.<br>
|
|
|
|
**date** The date the content will be sorted by.<br>
|
|
|
|
**indexes** These will use the field name of the plural form of the index (see tags and categories above)
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
#### Optional
|
|
|
|
|
2013-07-08 22:23:54 -04:00
|
|
|
**draft** If true the content will not be rendered unless `hugo` is called with -d<br>
|
|
|
|
**type** The type of the content (will be derived from the directory automatically if unset).<br>
|
|
|
|
**markup** (Experimental) Specify "rst" for reStructuredText (requires
|
|
|
|
`rst2html`,) or "md" (default) for the Markdown.<br>
|
|
|
|
**slug** The token to appear in the tail of the url.<br>
|
2013-07-04 11:34:22 -04:00
|
|
|
*or*<br>
|
2013-07-08 22:23:54 -04:00
|
|
|
**url** The full path to the content from the web root.<br>
|
2013-07-04 11:34:22 -04:00
|
|
|
*If neither is present the filename will be used.*
|
|
|
|
|
|
|
|
## Example
|
|
|
|
Somethings are better shown than explained. The following is a very basic example of a content file:
|
|
|
|
|
|
|
|
**mysite/project/nitro.md <- http://mysite.com/project/nitro.html**
|
|
|
|
|
2013-07-08 22:23:54 -04:00
|
|
|
---
|
|
|
|
Title: "Nitro : A quick and simple profiler for golang"
|
|
|
|
Description": ""
|
|
|
|
Keywords": [ "Development", "golang", "profiling" ]
|
|
|
|
Tags": [ "Development", "golang", "profiling" ]
|
|
|
|
Pubdate": "2013-06-19"
|
|
|
|
Topics": [ "Development", "GoLang" ]
|
|
|
|
Slug": "nitro"
|
|
|
|
project_url": "http://github.com/spf13/nitro"
|
|
|
|
---
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
# Nitro
|
|
|
|
|
|
|
|
Quick and easy performance analyzer library for golang.
|
|
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
|
|
Nitro is a quick and easy performance analyzer library for golang.
|
|
|
|
It is useful for comparing A/B against different drafts of functions
|
|
|
|
or different functions.
|
|
|
|
|
|
|
|
## Implementing Nitro
|
|
|
|
|
|
|
|
Using Nitro is simple. First use go get to install the latest version
|
|
|
|
of the library.
|
|
|
|
|
|
|
|
$ go get github.com/spf13/nitro
|
|
|
|
|
|
|
|
Next include nitro in your application.
|
|
|
|
|
|
|
|
|
|
|
|
# Extras
|
|
|
|
|
|
|
|
## Shortcodes
|
2013-07-22 13:32:25 -04:00
|
|
|
Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that
|
2013-07-04 11:34:22 -04:00
|
|
|
markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it.
|
|
|
|
|
|
|
|
However we cannot accept being constrained by our simple format. Also unacceptable is writing raw
|
2013-07-22 13:32:25 -04:00
|
|
|
html in our markdown every time we want to include unsupported content such as a video. To do
|
|
|
|
so is in complete opposition to the intent of using a bare bones format for our content and
|
2013-07-04 11:34:22 -04:00
|
|
|
utilizing templates to apply styling for display.
|
|
|
|
|
|
|
|
To avoid both of these limitations Hugo has full support for shortcodes.
|
|
|
|
|
|
|
|
### What is a shortcode?
|
|
|
|
A shortcode is a simple snippet inside a markdown file that Hugo will render using a template.
|
|
|
|
|
|
|
|
Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively.
|
2013-07-22 13:32:25 -04:00
|
|
|
Short codes are space delimited. The first word is always the name of the shortcode. Following the
|
2013-07-04 11:34:22 -04:00
|
|
|
name are the parameters. The author of the shortcode can choose if the short code
|
|
|
|
will use positional parameters or named parameters (but not both). A good rule of thumb is that if a
|
|
|
|
short code has a single required value in the case of the youtube example below then positional
|
|
|
|
works very well. For more complex layouts with optional parameters named parameters work best.
|
|
|
|
|
|
|
|
The format for named parameters models that of html with the format name="value"
|
|
|
|
|
|
|
|
### Example: youtube
|
|
|
|
|
|
|
|
{{% youtube 09jf3ow9jfw %}}
|
|
|
|
|
2013-07-22 13:32:25 -04:00
|
|
|
This would be rendered as
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
<div class="embed video-player">
|
|
|
|
<iframe class="youtube-player" type="text/html"
|
2013-07-22 13:32:25 -04:00
|
|
|
width="640" height="385"
|
2013-07-04 11:34:22 -04:00
|
|
|
src="http://www.youtube.com/embed/09jf3ow9jfw"
|
|
|
|
allowfullscreen frameborder="0">
|
|
|
|
</iframe>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
### Example: image with caption
|
|
|
|
|
|
|
|
{{% img src="/media/spf13.jpg" title="Steve Francia" %}}
|
|
|
|
|
|
|
|
Would be rendered as:
|
|
|
|
|
|
|
|
<figure >
|
|
|
|
<img src="/media/spf13.jpg" />
|
|
|
|
<figcaption>
|
|
|
|
<h4>Steve Francia</h4>
|
|
|
|
</figcaption>
|
|
|
|
</figure>
|
|
|
|
|
|
|
|
|
|
|
|
### Creating a shortcode
|
|
|
|
|
|
|
|
All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory.
|
|
|
|
|
|
|
|
The template name will be the name of the shortcode.
|
|
|
|
|
|
|
|
**Inside the template**
|
|
|
|
|
|
|
|
To access a parameter by either position or name the index method can be used.
|
|
|
|
|
|
|
|
{{ index .Params 0 }}
|
|
|
|
or
|
|
|
|
{{ index .Params "class" }}
|
|
|
|
|
|
|
|
To check if a parameter has been provided use the isset method provided by Hugo.
|
|
|
|
|
|
|
|
{{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }}
|
|
|
|
|
|
|
|
|
|
|
|
# Meta
|
|
|
|
|
|
|
|
## Release Notes
|
|
|
|
|
2013-08-02 16:30:26 -04:00
|
|
|
* **0.8.0** August 1, 2013
|
|
|
|
* Added support for pretty urls (filename/index.html vs filename.html)
|
|
|
|
* Hugo supports a destination directory
|
|
|
|
* Will efficiently sync content in static to destination directory
|
|
|
|
* Cleaned up options.. now with support for short and long options
|
|
|
|
* Added support for TOML
|
|
|
|
* Added support for YAML
|
|
|
|
* Added support for Previous & Next
|
|
|
|
* Support for Series
|
|
|
|
* Adding verbose output
|
|
|
|
* Loads of bugfixes
|
2013-07-04 11:34:22 -04:00
|
|
|
* **0.7.0** July 4, 2013
|
|
|
|
* Hugo now includes a simple server
|
|
|
|
* First public release
|
|
|
|
* **0.6.0** July 2, 2013
|
2013-07-05 00:35:11 -04:00
|
|
|
* Hugo includes an [example documentation site](http://hugo.spf13.com) which it builds
|
2013-07-04 11:34:22 -04:00
|
|
|
* **0.5.0** June 25, 2013
|
2013-07-05 00:35:11 -04:00
|
|
|
* Hugo is quite usable and able to build [spf13.com](http://spf13.com)
|
2013-07-04 11:34:22 -04:00
|
|
|
|
|
|
|
## Roadmap
|
|
|
|
In no particular order, here is what I'm working on:
|
|
|
|
|
|
|
|
* Pagination
|
|
|
|
* Support for top level pages (other than homepage)
|
|
|
|
* Series support
|
|
|
|
* Syntax highlighting
|
|
|
|
* Previous & Next
|
|
|
|
* Related Posts
|
|
|
|
* Support for other formats
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
1. Fork it
|
|
|
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
|
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
|
|
|
4. Push to the branch (`git push origin my-new-feature`)
|
|
|
|
5. Create new Pull Request
|
|
|
|
|
|
|
|
## Contributors
|
|
|
|
|
|
|
|
* [spf13](https://github.com/spf13)
|
|
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
Hugo is released under the Simple Public License. See [LICENSE.md](https://github.com/spf13/hugo/blob/master/LICENSE.md).
|