Updating a bunch of the docs

This commit is contained in:
spf13 2013-08-03 03:30:34 -04:00
parent def5f10183
commit 6efbd93a38
8 changed files with 80 additions and 527 deletions

View file

@ -3,8 +3,42 @@ title: "Contributing to Hugo"
Pubdate: "2013-07-01" Pubdate: "2013-07-01"
--- ---
We welcome all contributions. If you want to contribute, all
that is needed is simply fork Hugo, make changes and submit
a pull request. If you prefer, pick something from the roadmap
or contact [spf13](http://spf13.com) about what may make sense
to do next.
## Overview
1. Fork it from https://github.com/spf13/hugo 1. Fork it from https://github.com/spf13/hugo
2. Create your feature branch (`git checkout -b my-new-feature`) 2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`) 3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`) 4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request 5. Create new Pull Request
### Clone locally (for contributors):
git clone https://github.com/spf13/hugo
cd hugo
go get
Because go expects all of your libraries to be found in either
$GOROOT or $GOPATH, it's helpful to symlink the project to one
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
### Running Hugo
cd /path/to/hugo
go install github.com/spf13/hugo/hugolibs
go run main.go
### Building Hugo
cd /path/to/hugo
go build -o hugo main.go
mv hugo /usr/local/bin/

View file

@ -31,520 +31,16 @@ is the most probable location.
* Mercurial * Mercurial
* Bazaar * Bazaar
### Clone locally (for contributors):
git clone https://github.com/spf13/hugo
cd hugo
go get
Because go expects all of your libraries to be found in either $GOROOT or $GOPATH,
it's helpful to symlink the project to one 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
### Get directly from Github: ### Get directly from Github:
If you don't intend to contribute, it's even easier.
go get github.com/spf13/hugo go get github.com/spf13/hugo
### Running Hugo
cd /path/to/hugo
go run main.go
### Building Hugo ### Building Hugo
cd /path/to/hugo cd /path/to/hugo
go build -o hugo main.go go build -o hugo main.go
mv hugo /usr/local/bin/ mv hugo /usr/local/bin/
## Source Directory Organization
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.
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
└── public
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.
**Please note the field names must be all lowercase**
### Config Examples
The following is an example of a yaml config file with the default values:
---
sourcedir: "content"
layoutdir: "layouts"
publishdir: "public"
builddrafts: false
indexes:
category: "categories"
tag: "tags"
baseurl: "http://yoursite.com/"
...
The following is an example of a json config file with the default values:
{
"sourcedir": "content",
"layoutdir": "layouts",
"publishdir": "public",
"builddrafts": false,
"indexes": {
category: "categories",
tag: "tags"
},
"baseurl": "http://yoursite.com/"
}
The following is an example of a toml config file with the default values:
sourcedir = "content"
layoutdir = "layouts"
publishdir = "public"
builddrafts = false
baseurl = "http://yoursite.com/"
[indexes]
category = "categories"
tag = "tags"
## Usage
Make sure either hugo is in your path or provide a path to it.
$ hugo --help
usage: hugo [flags] []
-b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
-d, --build-drafts=false: include content marked as draft
--config="": config file (default is path/config.yaml|json|toml)
-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
The most common use is probably to run hugo with your current
directory being the input directory.
$ hugo
> X pages created
> Y indexes created
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.**
$ hugo --source ~/mysite --watch
Watching for changes. Press ctrl+c to stop
15 pages created
0 tags created
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
Web Server is available at http://localhost:1313
Press ctrl+c to stop
# 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
lightweight engine that provides a very small amount of logic. In our
experience that it is just the right amount of logic to be able to create a good static website
This document will not cover how to use golang templates, but the [golang docs](http://golang.org/pkg/html/template/)
provide a good introduction.
### Template roles
There are 5 different kinds of templates that Hugo works with.
#### index.html
This file must exist in the layouts directory. It is the template used to render the
homepage of your site.
#### rss.xml
This file must exist in the layouts directory. It will be used to render all rss documents.
The one provided in the example application will generate an ATOM format.
*Important: Hugo will automatically add the following header line to this file.*
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
#### Indexes
An index is a page that list multiple pieces of content. If you think of a typical blog, the tag
pages are good examples of indexes.
#### Content Type(s)
Hugo supports multiple types of content. Another way of looking at this is that Hugo has the ability
to render content in a variety of ways as determined by the type.
#### Chrome
Chrome is simply the decoration of your site. It's not a requirement to have this, but in practice
it's very convenient. Hugo doesn't know anything about Chrome, it's simply a convention that you may
likely find beneficial. As you create the rest of your templates you will include templates from the
/layout/chrome directory. I've found it helpful to include a header and footer template
in Chrome so I can include those in the other full page layouts (index.html, indexes/ type/single.html).
### Adding a new content type
Adding a type is easy.
**Step 1:**
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
**Step 2:**
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
**Step 3:**
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/index/post.html*.
**Step 4:**
Many sites support rendering content in a few different ways, for instance a single page view and a
summary view to be used when displaying a list of contents on a single page. Hugo makes no assumptions
here about how you want to display your content, and will support as many different views of a content
type as your site requires. All that is required for these additional views is that a template
exists in each layout/type directory with the same name.
For these, reviewing 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>
Any value defined in the front matter, including indexes will be made available under `.Params`.
Take for example I'm using tags and categories as my indexes. The following would be how I would access them:
**.Params.Tags** <br>
**.Params.Categories** <br>
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
you to include the meta data of the content right with it. Hugo supports a few
different formats each with their own identifying tokens.
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"
---
Content of the file goes Here
### 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"
+++
Content of the file goes Here
### JSON 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" ],
"date": "2012-04-06",
"categories": [
"Development",
"VIM"
],
"slug": "spf13-vim-3-0-release-and-new-website",
}
Content of the file goes Here
### 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.
**Field names are case insensitive.**
#### Required
**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)
#### Optional
**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>
*or*<br>
**url** The full path to the content from the web root.<br>
*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**
---
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"
---
# 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
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.
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
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.
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.
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
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 %}}
This would be rendered as
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
width="640" height="385"
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
* **0.7.0** July 4, 2013
* Hugo now includes a simple server
* First public release
* **0.6.0** July 2, 2013
* Hugo includes an [example documentation site](http://hugo.spf13.com) which it builds
* **0.5.0** June 25, 2013
* Hugo is quite usable and able to build [spf13.com](http://spf13.com)
## 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 TOML front matter -- in head
* Proper YAML support for front matter -- in head
* Support for other formats
## Contributing ## Contributing
1. Fork it Please see the [contributing guide](/doc/contributing)
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).

View file

@ -3,6 +3,19 @@ title: "Release Notes"
Pubdate: "2013-07-01" Pubdate: "2013-07-01"
--- ---
* **0.8.0** August 2, 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
* Added support for indexes for the indexes
* Better Windows compatibility
* Support for series
* Adding verbose output
* Loads of bugfixes
* **0.7.0** July 4, 2013 * **0.7.0** July 4, 2013
* Hugo now includes a simple server * Hugo now includes a simple server
* First public release * First public release

View file

@ -3,16 +3,15 @@ title: "Roadmap"
Pubdate: "2013-07-01" Pubdate: "2013-07-01"
--- ---
In no particular order, here is what I'm working on: In no particular order, here is what we are working on:
* Pagination * Pagination
* Support for top level pages (other than homepage) * Support for top level pages (other than homepage)
* Series support * Better error handling
* Syntax highlighting * Syntax highlighting
* Previous & Next * Commands
* Actions (eg. hugo create page)
* Related Posts * Related Posts
* Support for TOML front matter -- in head
* Proper YAML support for front matter -- in head
* Support for other formats * Support for other formats

View file

@ -12,7 +12,7 @@ using them.
An example directory may look like: An example directory may look like:
. .
├── config.json ├── config.yaml
├── content ├── content
| ├── post | ├── post
| | ├── firstpost.md | | ├── firstpost.md
@ -43,7 +43,7 @@ An example directory may look like:
| | └── youtube.html | | └── youtube.html
| ├── index.html | ├── index.html
| └── rss.xml | └── rss.xml
└── public └── static
This directory structure tells us a lot about this site: This directory structure tells us a lot about this site:

View file

@ -8,8 +8,9 @@ Make sure either hugo is in your path or provide a path to it.
$ hugo --help $ hugo --help
usage: hugo [flags] [] usage: hugo [flags] []
-b, --base-url="": hostname (and path) to the root eg. http://spf13.com/ -b, --base-url="": hostname (and path) to the root eg. http://spf13.com/
-d, --build-drafts=false: include content marked as draft -D, --build-drafts=false: include content marked as draft
--config="": config file (default is path/config.yaml|json|toml) --config="": config file (default is path/config.yaml|json|toml)
-d, --destination="": filesystem path to write files to
-h, --help=false: show this help -h, --help=false: show this help
--port="1313": port to run web server on, default :1313 --port="1313": port to run web server on, default :1313
-S, --server=false: run a (very) simple web server -S, --server=false: run a (very) simple web server
@ -28,12 +29,11 @@ directory being the input directory.
$ hugo $ hugo
> X pages created > X pages created
> Y indexes created > Y indexes created
in 8 ms
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. immediately, tell Hugo to watch for changes. **It will
<br>
**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.**
@ -41,6 +41,7 @@ your browser to view the changes.**
Watching for changes. Press ctrl+c to stop Watching for changes. Press ctrl+c to stop
15 pages created 15 pages created
0 tags created 0 tags created
in 8 ms
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!
@ -48,7 +49,7 @@ Hugo can even run a server and create your site at the same time!
Watching for changes. Press ctrl+c to stop Watching for changes. Press ctrl+c to stop
15 pages created 15 pages created
0 tags created 0 tags created
in 8 ms
Web Server is available at http://localhost:1313 Web Server is available at http://localhost:1313
Press ctrl+c to stop Press ctrl+c to stop

View file

@ -14,6 +14,8 @@ are available in the context for the templates.
**.Permalink** The Permanent link for this page.<br> **.Permalink** The Permanent link for this page.<br>
**.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>
**.Prev** Pointer to the previous content (based on pub date)<br>
**.Next** Pointer to the following content (based on pub date)<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:

View file

@ -17,7 +17,8 @@
<div class="hero-unit" style="background-color: #222; color: #ccc;"> <div class="hero-unit" style="background-color: #222; color: #ccc;">
<h1>Hugo</h1> <h1>Hugo</h1>
<p>A Fast and Flexible Static Site Generator built with love by <a href="http://spf13.com">spf13</a> in GO</p> <p>A Fast and Flexible Static Site Generator built with love by <a href="http://spf13.com">spf13</a>
and <a href="http://github.com/spf13/hugo/contributors">friends</a> in Go</p>
<p> <p>
<a class="btn btn-large btn-success" href="/doc/installing.html">Get Started</a> <a class="btn btn-large btn-success" href="/doc/installing.html">Get Started</a>
</p> </p>
@ -27,20 +28,27 @@
<h2>Fast <h2>Fast
<br> <br>
</h2> </h2>
<p>Written in GoLang for speed, Hugo is significantly faster than other <p>Written in GoLang for speed, Hugo is significantly faster than most
static site generators. It's so fast that it will render the site in other static site generators.
A typical website of moderate size can be
rendered in a fraction of a second. A good rule of thumb is that Hugo
takes around 1 millisecond for each piece of content.<br>
It's so fast that it will render the site in
less time than it takes to switch to your browser and reload.</p> less time than it takes to switch to your browser and reload.</p>
</div> </div>
<div class="span4"> <div class="span4">
<h2>Flexible</h2> <h2>Flexible</h2>
<p>Hugo is made to be very flexible. Define your own content types. Define <p>Hugo is made to be very flexible. Define your own content types. Define
your own indexes. Build your own templates, shortcodes and more.</p> your own indexes. Build your own templates, shortcodes and more.
It is written to work well with any
kind of website including blogs, tumbles and docs.</p>
</div> </div>
<div class="span4"> <div class="span4">
<h2>Fun</h2> <h2>Fun</h2>
<p>Hugo is more fun than you can shake a stick at. Hugo removes all <p>Hugo runs everywhere. Sites generated with Hugo work on every web
the cruft of building a site allowing you to focus on creating the server without any special configuration. Hugo
best site possible.</p> removes all the cruft of building a site allowing you to
focus on writing great content.</p>
</div> </div>
</div> </div>
{{ template "chrome/footer.html" }} {{ template "chrome/footer.html" }}