From 4107fd50a86728cc45f5c974050204bc82044994 Mon Sep 17 00:00:00 2001 From: Anthony Fok Date: Tue, 13 Jan 2015 20:48:44 -0700 Subject: [PATCH] [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. --- docs/content/content/archetypes.md | 49 +++++++---- docs/content/content/example.md | 86 ++++++++++++++----- docs/content/content/front-matter.md | 49 ++++++----- docs/content/content/organization.md | 20 ++--- docs/content/content/sections.md | 2 +- docs/content/overview/installing.md | 16 ++-- docs/content/overview/introduction.md | 27 ++++-- docs/content/themes/installing.md | 14 +-- .../troubleshooting/strange-eof-error.md | 12 +-- .../tutorials/automated-deployments.md | 4 +- docs/content/tutorials/github_pages_blog.md | 2 +- 11 files changed, 177 insertions(+), 104 deletions(-) diff --git a/docs/content/content/archetypes.md b/docs/content/content/archetypes.md index be79ce392..1426841bb 100644 --- a/docs/content/content/archetypes.md +++ b/docs/content/content/archetypes.md @@ -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: hugo new [relative new content path], +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 `` 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 Enter 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. diff --git a/docs/content/content/example.md b/docs/content/content/example.md index 17de00fd0..20d07c469 100644 --- a/docs/content/content/example.md +++ b/docs/content/content/example.md @@ -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 - $ 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/). diff --git a/docs/content/content/front-matter.md b/docs/content/content/front-matter.md index 87729f896..a733215a4 100644 --- a/docs/content/content/front-matter.md +++ b/docs/content/content/front-matter.md @@ -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*
* **url** The full path to the content from the web root.
diff --git a/docs/content/content/organization.md b/docs/content/content/organization.md index da52e093d..e6bc8e8c0 100644 --- a/docs/content/content/organization.md +++ b/docs/content/content/organization.md @@ -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 diff --git a/docs/content/content/sections.md b/docs/content/content/sections.md index 72d746497..602e89a08 100644 --- a/docs/content/content/sections.md +++ b/docs/content/content/sections.md @@ -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**. diff --git a/docs/content/overview/installing.md b/docs/content/overview/installing.md index bf3bc5797..623499cff 100644 --- a/docs/content/overview/installing.md +++ b/docs/content/overview/installing.md @@ -11,10 +11,10 @@ title: Installing Hugo 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 Windows, Linux, FreeBSD and OS 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 diff --git a/docs/content/overview/introduction.md b/docs/content/overview/introduction.md index 8a5e91c5b..7b3246d57 100644 --- a/docs/content/overview/introduction.md +++ b/docs/content/overview/introduction.md @@ -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 ms per page) - * Completely cross platform: Runs on Mac OS X, Linux and Windows + * Completely cross platform: Runs on  Mac OS X,  Linux,  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) diff --git a/docs/content/themes/installing.md b/docs/content/themes/installing.md index 04b1342c3..99f6dab55 100644 --- a/docs/content/themes/installing.md +++ b/docs/content/themes/installing.md @@ -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 diff --git a/docs/content/troubleshooting/strange-eof-error.md b/docs/content/troubleshooting/strange-eof-error.md index 55a5cb496..9837e2269 100644 --- a/docs/content/troubleshooting/strange-eof-error.md +++ b/docs/content/troubleshooting/strange-eof-error.md @@ -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. ## References diff --git a/docs/content/tutorials/automated-deployments.md b/docs/content/tutorials/automated-deployments.md index 3f15f0c8f..84dad2f74 100644 --- a/docs/content/tutorials/automated-deployments.md +++ b/docs/content/tutorials/automated-deployments.md @@ -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] @@ -252,4 +252,4 @@ Simply fill in the name, and make sure you enable **auto deploy** from the **mas 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. diff --git a/docs/content/tutorials/github_pages_blog.md b/docs/content/tutorials/github_pages_blog.md index 5337f457d..0423b03b0 100644 --- a/docs/content/tutorials/github_pages_blog.md +++ b/docs/content/tutorials/github_pages_blog.md @@ -240,7 +240,7 @@ Step by step: 2. Create on GitHub `.github.io` repository (it will host the `public` folder: the static website) 2. `git clone <-hugo-url> && cd -hugo` 3. Make your website work locally (`hugo serve --watch -t `) -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 `) +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 `) 5. `git submodule add git@github.com:/.github.io.git public` 6. Almost done: add a `deploy.sh` script to help you (and make it executable: `chmod +x deploy.sh`):