[Docs] More random revision and copyediting

General revisions to (hopefully) make the documentation
easier to understand and more comprehensive.

Revise "Strange EOF error" troubleshooting page to say that
a fix is in place for the upcoming Hugo v0.13.

Also add more external links, and cute icons from Font Awesome.
This commit is contained in:
Anthony Fok 2015-01-13 20:48:44 -07:00
parent 6fda9012d6
commit 4107fd50a8
11 changed files with 177 additions and 104 deletions

View file

@ -10,51 +10,62 @@ weight: 50
---
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.
command: <code>hugo new <em>[relative new content path]</em></code>,
you can start a content file with the date and title automatically set.
While this is a welcome feature, active writers need more.
Hugo presents the concept of archetypes which are archetypal content files.
Hugo presents the concept of archetypes, which are archetypal content files
with pre-configured [front matter](content/front-matter) which will
populate each new content file whenever you run the `hugo new` command.
## 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.
## Example
### archetypes/default.md
### Step 1. Creating an archetype
In this example scenario, we have a blog with a single content type (blog post).
We will use tags and categories for our taxonomies, so let's create an archetype file with tags and categories pre-defined, as follows:
#### archetypes/default.md
+++
tags = ["x", "y"]
categories = ["x", "y"]
+++
__NOTE:__ Some editors (e.g. Sublime) do not insert an EOL at the last line. If you get an EOF error using `hugo new` type a carriage return `<Enter>` after the closing `+++` in each archetype file.
__CAVEAT:__ Some editors (e.g. Sublime, Emacs) do not insert an EOL (end-of-line) character at the end of the file (i.e. EOF). If you get a [strange EOF error](/troubleshooting/strange-eof-error/) when using `hugo new`, please open each archetype file (i.e. `archetypes/*.md`) and press <kbd>Enter</kbd> to type a carriage return after the closing `+++` or `---` as necessary.
## Using archetypes
If I wanted to create a new post in the `post` section, I would run the following command:
### Step 2. Using the archetype
`hugo new post/my-new-post.md`
Now, with `archetypes/default.md` in place, let's create a new post in the `post` section with the `hugo new` command:
$ hugo new post/my-new-post.md
Hugo would create the file with the following contents:
### content/post/my-new-post.md
#### content/post/my-new-post.md
+++
title = "my new post"
date = 2014-05-14T02:13:50Z
date = "2015-01-12T19:20:04-07:00"
tags = ["x", "y"]
categories = ["x", "y"]
+++
We see that the `title` and `date` variables have been added, in addition to the `tags` and `categories` variables which were carried over from `archetype/default.md`.
Congratulations! We have successfully created an archetype and used it for our new contents. That's all there is to it!
## 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`.
You can specify a different default format in your site-wide config file
(e.g. `config.toml`) using the `MetaDataFormat` directive.
Possible values are `"toml"`, `"yaml"` and `"json"`.
## Which archetype is being used
@ -63,13 +74,13 @@ 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 neither is 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()`.
Hugo provides a simple archetype which sets the `title` (based on the
file name) and the `date` based on `now()`.
Content type is automatically detected based on the path. You are welcome to declare which
type to create using the `--kind` flag during creation.

View file

@ -13,37 +13,79 @@ title: Example Content File
weight: 70
---
Some things are better shown than explained. The following is a very basic example of a content file:
Some things are better shown than explained. The following is a very basic example of a content file written in [Markdown](https://help.github.com/articles/github-flavored-markdown/):
**mysite/project/nitro.md ← http://mysite.com/project/nitro.html**
**mysite/content/project/nitro.md → http://mysite.com/project/nitro.html**
---
Title: "Nitro : A quick and simple profiler for Go"
Description: "Nitro is a simple profiler for you go lang applications"
Tags: [ "Development", "Go", "profiling" ]
date: "2013-06-19"
Topics: [ "Development", "Go" ]
Slug: "nitro"
project_url: "http://github.com/spf13/nitro"
---
With TOML front matter:
# Nitro
```markdown
+++
date = "2013-06-21T11:27:27-04:00"
title = "Nitro: A quick and simple profiler for Go"
description = "Nitro is a simple profiler for your Golang applications"
tags = [ "Development", "Go", "profiling" ]
topics = [ "Development", "Go" ]
slug = "nitro"
project_url = "https://github.com/spf13/nitro"
+++
Quick and easy performance analyzer library for Go.
# Nitro
## Overview
Quick and easy performance analyzer library for [Go](http://golang.org/).
Nitro is a quick and easy performance analyzer library for Go.
It is useful for comparing A/B against different drafts of functions
or different functions.
## Overview
## Implementing Nitro
Nitro is a quick and easy performance analyzer library for Go.
It is useful for comparing A/B against different drafts of functions
or different functions.
Using Nitro is simple. First use go get to install the latest version
of the library.
## 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.
Next, include nitro in your application.
```
You may also use the equivalent YAML front matter:
```markdown
---
date: "2013-06-21T11:27:27-04:00"
title: "Nitro: A quick and simple profiler for Go"
description: "Nitro is a simple profiler for your Go lang applications"
tags: [ "Development", "Go", "profiling" ]
topics: [ "Development", "Go" ]
slug: "nitro"
project_url: "https://github.com/spf13/nitro"
---
```
`nitro.md` would be rendered as follows:
> # Nitro
>
> Quick and easy performance analyzer library for [Go](http://golang.org/).
>
> ## Overview
>
> Nitro is a quick and easy performance analyzer library for Go.
> 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.
The source `nitro.md` file is converted to HTML by the excellent
[Blackfriday](https://github.com/russross/blackfriday) Markdown processor,
which supports extended features found in the popular
[GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/).

View file

@ -11,29 +11,19 @@ title: Front Matter
weight: 20
---
The front matter is one of the features that gives Hugo its strength. It enables
The **front matter** is one of the features that gives Hugo its 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:
* **YAML**, identified by '`---`'.
* **TOML**, identified with '`+++`'.
* **JSON**, a single JSON object which is surrounded by '`{`' and '`}`', each on their own line.
* **[TOML][]**, identified by '`+++`'.
* **[YAML][]**, identified by '`---`'.
* **[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" ]
date: "2012-04-06"
categories:
- "Development"
- "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---
Content of the file goes Here
[TOML]: https://github.com/toml-lang/toml "Tom's Obvious, Minimal Language"
[YAML]: http://www.yaml.org/ "YAML Ain't Markup Language"
[JSON]: http://www.json.org/ "JavaScript Object Notation"
### TOML Example
@ -48,6 +38,22 @@ Supported formats:
]
slug = "spf13-vim-3-0-release-and-new-website"
+++
Content of the file goes Here
### 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" ]
date: "2012-04-06"
categories:
- "Development"
- "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---
Content of the file goes Here
### JSON Example
@ -63,6 +69,7 @@ Supported formats:
],
"slug": "spf13-vim-3-0-release-and-new-website",
}
Content of the file goes Here
## Variables
@ -71,22 +78,22 @@ There are a few predefined variables that Hugo is aware of and utilizes. The use
any variable they want to. These will be placed into the `.Params` variable available to the templates.
Field names are always normalized to lowercase (e.g. `camelCase: true` is available as `.Params.camelcase`).
### Required
### Required variables
* **title** The title for the content
* **description** The description for the content
* **date** The date the content will be sorted by
* **taxonomies** These will use the field name of the plural form of the index (see tags and categories above)
### Optional
### Optional variables
* **redirect** Mark the post as a redirect post
* **draft** If true, the content will not be rendered unless `hugo` is called with `--buildDrafts`
* **publishdate** If in the future, content will not be rendered unless `hugo` is called with `--buildFuture`
* **type** The type of the content (will be derived from the directory automatically if unset)
* **weight** Used for sorting
* **markup** (Experimental) Specify "rst" for reStructuredText (requires
`rst2html`) or "md" (default) for Markdown
* **markup** *(Experimental)* Specify `"rst"` for reStructuredText (requires
`rst2html`) or `"md"` (default) for Markdown
* **slug** The token to appear in the tail of the URL,
*or*<br>
* **url** The full path to the content from the web root.<br>

View file

@ -12,15 +12,15 @@ title: Content Organization
weight: 10
---
Hugo uses markdown files with headers commonly called the front matter. Hugo
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
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).
@ -35,7 +35,7 @@ in Hugo and is used as the [section](/content/sections).
├── first.md // <- http://1.com/quote/first/
└── second.md // <- http://1.com/quote/second/
**Here's the same organization run with hugo -\-uglyurls**
**Here's the same organization run with `hugo --uglyurls`**
.
└── content
@ -50,14 +50,14 @@ in Hugo and is used as the [section](/content/sections).
## Destinations
Hugo thinks that you organize your content with a purpose. The same structure
Hugo believes that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site. As displayed above, the organization of the source content will be
mirrored in the destination.
There are times when one would need more control over their content. In these
cases there are a variety of things that can be specified in the front matter to
determine the destination of a specific piece of content.
cases, there are a variety of things that can be specified in the front matter
to determine the destination of a specific piece of content.
The following items are defined in order, latter items in the list will override
earlier settings.
@ -84,10 +84,10 @@ path to the file on disk. Destination will create the destination with the same
path. Includes [section](/content/sections).
### url
A complete url can be provided. This will override all the above as it pertains
A complete URL can be provided. This will override all the above as it pertains
to the end destination. This must be the path from the baseurl (starting with a "/").
When a url is provided it will be used exactly. Using url will ignore the
-\-uglyurls setting.
When a url is provided, it will be used exactly. Using url will ignore the
`--uglyurls` setting.
## Path breakdown in Hugo

View file

@ -10,7 +10,7 @@ title: Sections
weight: 30
---
Hugo thinks that you organize your content with a purpose. The same structure
Hugo believes that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
site (see [Organization](/content/organization)). Following this pattern Hugo
uses the top level of your content organization as **the Section**.

View file

@ -11,10 +11,10 @@ title: Installing Hugo
weight: 20
---
Hugo is written in Go with support for Windows, Linux, FreeBSD and OS&nbsp;X.
Hugo is written in Go with support for multiple platforms.
The latest release can be found at [Hugo Releases](https://github.com/spf13/hugo/releases).
We currently build for Windows, Linux, FreeBSD and OS&nbsp;X for x64
We currently build for <i class="fa fa-windows"></i> Windows, <i class="fa fa-linux"></i> Linux, FreeBSD and <i class="fa fa-apple"></i> OS&nbsp;X for x64
and i386 architectures.
## Installing Hugo (binary)
@ -53,15 +53,15 @@ placed in your `PATH`.
* Mercurial
* Bazaar
### Get directly from GitHub:
### Get directly from GitHub
$ export GOPATH=$HOME/go
$ go get -v github.com/spf13/hugo
### Building Hugo
$ cd /path/to/hugo
$ go build -o hugo main.go
$ mv hugo /usr/local/bin/
`go get` will then fetch Hugo and all its dependent libraries to your
`$GOPATH/src` directory, and compile everything into the final `hugo`
(or `hugo.exe`) executable, which you will find sitting in the
`$GOPATH/bin/hugo` directory, all ready to go!
## Contributing

View file

@ -20,10 +20,17 @@ edited, Hugo is optimized for website viewing while providing a great
writing experience.
Sites built with Hugo are extremely fast and very secure. Hugo sites can
be hosted anywhere, including Heroku, GoDaddy, GitHub Pages, Amazon S3
and CloudFront, and work well with CDNs. Hugo sites run without dependencies
on expensive runtimes like Ruby, Python or PHP and without dependencies
on any databases.
be hosted anywhere, including [Heroku][], [GoDaddy][], [DreamHost][],
[GitHub Pages][], [Amazon S3][] and [CloudFront][], and work well with CDNs.
Hugo sites run without dependencies on expensive runtimes like Ruby,
Python or PHP and without dependencies on any databases.
[Heroku]: https://www.heroku.com/
[GoDaddy]: https://www.godaddy.com/
[DreamHost]: http://www.dreamhost.com/
[GitHub Pages]: http://www.dreamhost.com/cloud/
[Amazon S3]: http://aws.amazon.com/s3/
[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
We think of Hugo as the ideal website creation tool. With nearly instant
build times and the ability to rebuild whenever a change is made, Hugo
@ -40,7 +47,7 @@ Hugo boasts the following features:
### General
* Extremely fast build times (~1&nbsp;ms per page)
* Completely cross platform: Runs on Mac OS&nbsp;X, Linux and Windows
* Completely cross platform: Runs on <i class="fa fa-apple"></i>&nbsp;Mac OS&nbsp;X, <i class="fa fa-linux"></i>&nbsp;Linux, <i class="fa fa-windows"></i>&nbsp;Windows, and more!
* Easy [installation](/overview/installing)
* Render changes [on the fly](/overview/usage) with [LiveReload](/extras/livereload) as you develop
* Complete theme support
@ -102,7 +109,7 @@ hacked blogs. I hated how content was written in HTML instead of the much
simpler Markdown. Overall, I felt like it got in my way more than it helped
me from writing great content.
I looked at existing static site generators like Jekyll, Middleman and nanoc.
I looked at existing static site generators like [Jekyll][], [Middleman][] and [nanoc][].
All had complicated dependencies to install and took far longer to render
my blog with hundreds of posts than I felt was acceptable. I wanted
a framework to be able to get rapid feedback while making changes to the
@ -110,12 +117,18 @@ templates, and the 5+-minute render times was just too slow. In general,
they were also very blog minded and didn't have the ability to have
different content types and flexible URLs.
[Jekyll]: http://jekyllrb.com/
[Middleman]: https://middlemanapp.com/
[nanoc]: http://nanoc.ws/
I wanted to develop a fast and full-featured website framework without
dependencies. The Go language seemed to have all of the features I needed
dependencies. The [Go language][] seemed to have all of the features I needed
in a language. I began developing Hugo in Go and fell in love with the
language. I hope you will enjoy using (and contributing to) Hugo as much
as I have writing it.
[Go language]: http://golang.org/ "The Go Programming Language"
## Next Steps
* [Install Hugo](/overview/installing)

View file

@ -9,21 +9,21 @@ title: Installing Themes
weight: 20
---
Hugo themes are located in a centralized github repository. [Hugo Themes
Hugo themes are located in a centralized GitHub repository. The [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.
If you would like to install all of the available Hugo themes, simply
clone the entire repository from within your working directory:
```bash
git clone --recursive https://github.com/spf13/hugoThemes.git themes
$ git clone --recursive https://github.com/spf13/hugoThemes.git themes
```
## Installing a specific theme
mkdir themes
cd themes
git clone URL_TO_THEME
$ mkdir themes
$ cd themes
$ git clone URL_TO_THEME

View file

@ -24,17 +24,17 @@ Is there something that I am blatantly missing?
## Solution
Thank you for reporting this issue. The solution is to add a final newline (or EOL) to the end of your default.md archetype file of your theme. More discussions happened on the forum here:
Thank you for reporting this issue. The solution is to add a final newline (i.e. EOL) to the end of your default.md archetype file of your theme. More discussions happened on the forum here:
* http://discuss.gohugo.io/t/archetypes-not-properly-working-in-0-12/544
* http://discuss.gohugo.io/t/eol-f-in-archetype-files/554
So yes, we do need to fix this. We need to do the following:
Due to popular demand, Hugo's parser has been enhanced to
accommodate archetype files without final EOL,
thanks to the great work by [@tatsushid](https://github.com/tatsushid),
in the upcoming v0.13 release,
1. Add warnings about this in the Hugo documentation, as several people have run into the same problem already. (Users of editors like Vim, nano and gedit are immune to this because these editors enforce an EOL at the end of the file by default, but other editors like Emacs don't do that.)
2. Improve the error message. It is difficult to determine what went wrong with just three characters "`EOF`"
3. Allow archetype files without the final EOL to compile anyway, but do give an appropriate and detailed warning. (optional, to be discussed)
https://github.com/spf13/hugo/issues/776
Until then, for us running the stable v0.12 release, please remember to add the final EOL diligently. <i class="fa fa-smile-o"></i>
## References

View file

@ -112,7 +112,7 @@ Let's start by setting up an account for Wercker. To do so we'll go to www.werck
## Register
To make life easier for ourselves, we will then register using GitHub. If you don't have a GitHub account, or don't want to use it for your account you can of course register with a username and password as well.
To make life easier for ourselves, we will then register using GitHub. If you don't have a GitHub account, or don't want to use it for your account, you can of course register with a username and password as well.
![][4]

View file

@ -240,7 +240,7 @@ Step by step:
2. Create on GitHub `<username>.github.io` repository (it will host the `public` folder: the static website)
2. `git clone <<your-project>-hugo-url> && cd <your-project>-hugo`
3. Make your website work locally (`hugo serve --watch -t <yourtheme>`)
4. Once you are happy with the results, `Ctrl+c` (kill server) and `rm -rf public` (don't worry, it can always be regenerated with `hugo -t <yourtheme>`)
4. Once you are happy with the results, <kbd>Ctrl</kbd>+<kbd>C</kbd> (kill server) and `rm -rf public` (don't worry, it can always be regenerated with `hugo -t <yourtheme>`)
5. `git submodule add git@github.com:<username>/<username>.github.io.git public`
6. Almost done: add a `deploy.sh` script to help you (and make it executable: `chmod +x deploy.sh`):