---
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
+### Step 2. Using the archetype
-If I wanted to create a new post in the `post` section, I would run the following command:
+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 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
* 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.
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
- $ go get github.com/spf13/nitro
+Using Nitro is simple. First, use `go get` to install the latest version
+of the library.
- Next include nitro in your application.
+ $ go get github.com/spf13/nitro
+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/).
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
]
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
],
"slug": "spf13-vim-3-0-release-and-new-website",
}
+
Content of the file goes Here
## Variables
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>
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).
├── 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
## 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.
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
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**.
weight: 20
---
-Hugo is written in Go with support for Windows, Linux, FreeBSD and OS 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 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 X for x64
and i386 architectures.
## Installing Hugo (binary)
* 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
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
### General
* Extremely fast build times (~1 ms per page)
- * Completely cross platform: Runs on Mac OS X, Linux and Windows
+ * Completely cross platform: Runs on <i class="fa fa-apple"></i> Mac OS X, <i class="fa fa-linux"></i> Linux, <i class="fa fa-windows"></i> Windows, and more!
* Easy [installation](/overview/installing)
* Render changes [on the fly](/overview/usage) with [LiveReload](/extras/livereload) as you develop
* Complete theme support
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
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)
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
## 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
## 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]
From now on, any time you want to put a new post on your blog all you need to do is push your new page to GitHub and the rest will happen automatically. The source code for the example site used here is available on [GitHub](https://github.com/ArjenSchwarz/hugo-wercker-example), as is the [Hugo Build step](https://github.com/ArjenSchwarz/wercker-step-hugo-build) itself.
-If you want to see an example of how you can deploy to S3 instead of GitHub pages, take a look at [Wercker's blogpost](http://blog.wercker.com/2013/06/10/Streamlining-Middleman-Deploys-to-s3.html) about how to set that up for Middleman.
\ No newline at end of file
+If you want to see an example of how you can deploy to S3 instead of GitHub pages, take a look at [Wercker's blogpost](http://blog.wercker.com/2013/06/10/Streamlining-Middleman-Deploys-to-s3.html) about how to set that up for Middleman.
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`):
projects / brevno-suite / hugo / commitdiff