Merge branch 'doc-fix' of https://github.com/brandonblack/hugo into brandonblack-doc-fix

Conflicts:
	README.md
This commit is contained in:
spf13 2013-07-24 11:27:03 -04:00
commit 3ad3f2f0e0

View file

@ -4,15 +4,15 @@ A really fast static site generator written in GoLang.
## Overview ## Overview
Hugo is a static site generator written in GoLang. It is optimized for Hugo is a static site generator written in GoLang. It is optimized for
speed, easy use and configurability. Hugo takes a directory with content and speed, easy use and configurability. Hugo takes a directory with content and
templates and renders them into a full html website. templates and renders them into a full html website.
Hugo makes use of markdown files with front matter for meta data. Hugo makes use of markdown files with front matter for meta data.
A typical website of moderate size can be A typical website of moderate size can be
rendered in a fraction of a second. It is written to work well with any rendered in a fraction of a second. It is written to work well with any
kind of website including blogs, tumbles and docs. kind of website including blogs, tumbles and docs.
# Getting Started # Getting Started
@ -23,20 +23,21 @@ Hugo is written in GoLang with support for Windows, Linux, FreeBSD and OSX.
The latest release can be found at [hugo releases](https://github.com/spf13/hugo/releases). The latest release can be found at [hugo releases](https://github.com/spf13/hugo/releases).
We currently build for Windows, Linux, FreeBSD and OS X for x64 We currently build for Windows, Linux, FreeBSD and OS X for x64
and 386 architectures. and 386 architectures.
Installation is very easy. Simply download the appropriate version for your Installation is very easy. Simply download the appropriate version for your
platform. Once downloaded it can be run from anywhere. You don't need to install platform. Once downloaded it can be run from anywhere. You don't need to install
it into a global location. This works well for shared hosts and other systems it into a global location. This works well for shared hosts and other systems
where you don't have a privileged account. where you don't have a privileged account.
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin` Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
is the most probable location. is the most probable location.
*Hugo has no external dependencies.* *Hugo has no external dependencies.*
## Installing from source ## Installing from source
<<<<<<< HEAD
### Dependencies ### Dependencies
Make sure you have a recent version of go installed. Hugo requires go 1.1+. Make sure you have a recent version of go installed. Hugo requires go 1.1+.
@ -45,11 +46,26 @@ Make sure you have a recent version of go installed. Hugo requires go 1.1+.
### Cloning and Installing dependencies ### Cloning and Installing dependencies
Pre-requisites:
* Git
* Go 1.1+
* Mercurial
* Bazaar
### Getting locally (for contributors):
# clone and build
git clone https://github.com/spf13/hugo git clone https://github.com/spf13/hugo
cd hugo cd hugo
go get go get
go build -o hugo main.go go build -o hugo main.go
### Install directly from Github:
go get github.com/spf13/hugo
go build -o hugo main.go
### Running Hugo ### Running Hugo
cd hugo cd hugo
@ -64,7 +80,7 @@ Make sure you have a recent version of go installed. Hugo requires go 1.1+.
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. 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 It accomplishes by assuming that you will only provide templates with the intent of
using them. using them.
@ -122,7 +138,7 @@ since the defaults used follow commonly used patterns.
### Config Examples ### Config Examples
The following is an example of a yaml config file with the default values: The following is an example of a yaml config file with the default values:
--- ---
sourcedir: "content" sourcedir: "content"
@ -136,7 +152,7 @@ The following is an example of a yaml config file with the default values:
... ...
The following is an example of a json config file with the default values: The following is an example of a json config file with the default values:
{ {
"sourcedir": "content", "sourcedir": "content",
@ -151,7 +167,7 @@ The following is an example of a json config file with the default values:
} }
The following is an example of a toml config file with the default values: The following is an example of a toml config file with the default values:
sourcedir = "content" sourcedir = "content"
layoutdir = "layouts" layoutdir = "layouts"
@ -163,7 +179,7 @@ The following is an example of a toml config file with the default values:
tag = "tags" tag = "tags"
## Usage ## Usage
Make sure either hugo is in your path or provide a path to it. Make sure either hugo is in your path or provide a path to it.
$ hugo --help $ hugo --help
@ -180,7 +196,7 @@ Make sure either hugo is in your path or provide a path to it.
--version=false: which version of hugo --version=false: which version of hugo
-w, --watch=false: watch filesystem for changes and recreate as needed -w, --watch=false: watch filesystem for changes and recreate as needed
The most common use is probably to run hugo with your current The most common use is probably to run hugo with your current
directory being the input directory. directory being the input directory.
@ -189,9 +205,9 @@ directory being the input directory.
> Y indexes created > Y indexes created
If you are working on things and want to see the changes If you are working on things and want to see the changes
immediately, tell Hugo to watch for changes. **It will immediately, tell Hugo to watch for changes. **It will
recreate the site faster than you can tab over to recreate the site faster than you can tab over to
your browser to view the changes.** your browser to view the changes.**
$ hugo --source ~/mysite --watch $ hugo --source ~/mysite --watch
@ -215,7 +231,7 @@ Hugo is very flexible about how you organize and structure your content.
## Templates ## Templates
Hugo uses the excellent golang html/template library for it's template engine. It is an extremely Hugo uses the excellent golang html/template library for it's template engine. It is an extremely
lightweight engine that provides a very small amount of logic. In our 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 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/) This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/)
@ -226,19 +242,19 @@ provide a good introduction.
There are 5 different kinds of templates that Hugo works with. There are 5 different kinds of templates that Hugo works with.
#### index.html #### index.html
This file must exist in the layouts directory. It is the template used to render the This file must exist in the layouts directory. It is the template used to render the
homepage of your site. homepage of your site.
#### rss.xml #### rss.xml
This file must exist in the layouts directory. It will be used to render all rss documents. This file must exist in the layouts directory. It will be used to render all rss documents.
The one provided in the example application will generate an ATOM format. The one provided in the example application will generate an ATOM format.
*Important: Hugo will automatically add the following header line to this file.* *Important: Hugo will automatically add the following header line to this file.*
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <?xml version="1.0" encoding="utf-8" standalone="yes" ?>
#### Indexes #### Indexes
An index is a page that list multiple pieces of content. If you think of a typical blog, the tag An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
pages are good examples of indexes. pages are good examples of indexes.
@ -249,8 +265,8 @@ to render content in a variety of ways as determined by the type.
#### Chrome #### Chrome
Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice 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 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 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 /layout/chrome directory. I've found it helpful to include a header and footer template
in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html). 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 new content type
@ -267,7 +283,7 @@ Create a file called single.html inside your directory. *Eg /layouts/post/single
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*. Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
**Step 4:** **Step 4:**
Many sites support rendering content in a few different ways, for instance a single page view and a 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 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 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 type as your site requires. All that is required for these additional views is that a template
@ -289,11 +305,11 @@ are available in the context for the templates.
**.FuzzyWordCount** The approximate number of words in the content.<br> **.FuzzyWordCount** The approximate number of words in the content.<br>
**.RSSLink** Link to the indexes' rss link <br> **.RSSLink** Link to the indexes' rss link <br>
Any value defined in the front matter, including indexes will be made available under `.Params`. Any value defined in the front matter, including indexes will be made available under `.Params`.
Take for example I'm using tags and categories as my indexes. The following would be how I would access them: Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
**.Params.Tags** <br> **.Params.Tags** <br>
**.Params.Categories** <br> **.Params.Categories** <br>
Also available is `.Site` which has the following: Also available is `.Site` which has the following:
@ -324,8 +340,8 @@ Without any additional configuration the following will just work.
## Front Matter ## Front Matter
The front matter is one of the features that gives Hugo it's strength. It enables The front matter is one of the features that gives Hugo it's strength. It enables
you to include the meta data of the content right with it. Hugo supports a few you to include the meta data of the content right with it. Hugo supports a few
different formats each with their own identifying tokens. different formats each with their own identifying tokens.
Supported formats: <br> Supported formats: <br>
**YAML**, identified by '\-\-\-'. <br> **YAML**, identified by '\-\-\-'. <br>
@ -344,7 +360,7 @@ Supported formats: <br>
- "VIM" - "VIM"
slug: "spf13-vim-3-0-release-and-new-website" slug: "spf13-vim-3-0-release-and-new-website"
--- ---
Content of the file goes Here Content of the file goes Here
### TOML Example ### TOML Example
@ -359,7 +375,7 @@ Supported formats: <br>
] ]
slug = "spf13-vim-3-0-release-and-new-website" slug = "spf13-vim-3-0-release-and-new-website"
+++ +++
Content of the file goes Here Content of the file goes Here
### JSON Example ### JSON Example
@ -374,7 +390,7 @@ Supported formats: <br>
], ],
"slug": "spf13-vim-3-0-release-and-new-website", "slug": "spf13-vim-3-0-release-and-new-website",
} }
Content of the file goes Here Content of the file goes Here
### Variables ### Variables
There are a few predefined variables that Hugo is aware of and utilizes. The user can also create There are a few predefined variables that Hugo is aware of and utilizes. The user can also create
@ -438,12 +454,12 @@ Somethings are better shown than explained. The following is a very basic exampl
# Extras # Extras
## Shortcodes ## Shortcodes
Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that
markdown doesn't support well. This is good, the simple nature of markdown is exactly why we chose it. 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 However we cannot accept being constrained by our simple format. Also unacceptable is writing raw
html in our markdown every time we want to include unsupported content such as a video. To do 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 so is in complete opposition to the intent of using a bare bones format for our content and
utilizing templates to apply styling for display. utilizing templates to apply styling for display.
To avoid both of these limitations Hugo has full support for shortcodes. To avoid both of these limitations Hugo has full support for shortcodes.
@ -452,7 +468,7 @@ To avoid both of these limitations Hugo has full support for shortcodes.
A shortcode is a simple snippet inside a markdown file that Hugo will render using a template. 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. Short codes are designated by the opening and closing characters of '{{%' and '%}}' respectively.
Short codes are space delimited. The first word is always the name of the shortcode. Following the Short codes are space delimited. The first word is always the name of the shortcode. Following the
name are the parameters. The author of the shortcode can choose if the short code 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 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 short code has a single required value in the case of the youtube example below then positional
@ -464,11 +480,11 @@ The format for named parameters models that of html with the format name="value"
{{% youtube 09jf3ow9jfw %}} {{% youtube 09jf3ow9jfw %}}
This would be rendered as This would be rendered as
<div class="embed video-player"> <div class="embed video-player">
<iframe class="youtube-player" type="text/html" <iframe class="youtube-player" type="text/html"
width="640" height="385" width="640" height="385"
src="http://www.youtube.com/embed/09jf3ow9jfw" src="http://www.youtube.com/embed/09jf3ow9jfw"
allowfullscreen frameborder="0"> allowfullscreen frameborder="0">
</iframe> </iframe>