shithub: hugo

Info  •  Files  •  Log  •  Branches

Updating a bunch of the docs

--- a/docs/content/doc/contributing.md

+++ b/docs/content/doc/contributing.md

@@ -3,8 +3,42 @@

 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

 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

+

+

+### 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/

+

--- a/docs/content/doc/installing.md

+++ b/docs/content/doc/installing.md

@@ -31,29 +31,10 @@

 * Mercurial

 * 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:

-If you don't intend to contribute, it's even easier. 

-

     go get github.com/spf13/hugo

-### Running Hugo

-

-    cd /path/to/hugo

-    go run main.go

-

 ### Building Hugo

     cd /path/to/hugo

@@ -60,491 +41,6 @@

     go build -o hugo main.go

     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

-1. Fork it

-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).

+Please see the [contributing guide](/doc/contributing)

--- a/docs/content/doc/release-notes.md

+++ b/docs/content/doc/release-notes.md

@@ -3,6 +3,19 @@

 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

   * Hugo now includes a simple server

   * First public release

--- a/docs/content/doc/roadmap.md

+++ b/docs/content/doc/roadmap.md

@@ -3,16 +3,15 @@

 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

  * Support for top level pages (other than homepage)

- * Series support

+ * Better error handling

  * Syntax highlighting

- * Previous & Next

+ * Commands

+ * Actions (eg. hugo create page)

  * Related Posts

- * Support for TOML front matter -- in head

- * Proper YAML support for front matter -- in head

  * Support for other formats

--- a/docs/content/doc/source-directory.md

+++ b/docs/content/doc/source-directory.md

@@ -12,7 +12,7 @@

 An example directory may look like:

     .

-    ├── config.json

+    ├── config.yaml

     ├── content

     |   ├── post

     |   |   ├── firstpost.md

@@ -43,7 +43,7 @@

     |   |   └── youtube.html

     |   ├── index.html

     |   └── rss.xml

-    └── public

+    └── static

 This directory structure tells us a lot about this site:

--- a/docs/content/doc/usage.md

+++ b/docs/content/doc/usage.md

@@ -8,8 +8,9 @@

     $ 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

+      -D, --build-drafts=false: include content marked as draft

           --config="": config file (default is path/config.yaml|json|toml)

+      -d, --destination="": filesystem path to write files to

       -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

@@ -21,7 +22,7 @@

 ## Common Usage Example:

-The most common use is probably to run hugo with your current 

+The most common use is probably to run hugo with your current

 directory being the input directory.

@@ -28,13 +29,12 @@

     $ hugo

     > X pages created

     > Y indexes created

+      in 8 ms

-If you are working on things and want to see the changes 

-immediately, tell Hugo to watch for changes. 

-<br>

-**It will 

-recreate the site faster than you can tab over to 

+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

@@ -41,6 +41,7 @@

        Watching for changes. Press ctrl+c to stop

        15 pages created

        0 tags created

+       in 8 ms

 Hugo can even run a server and create your site at the same time!

@@ -48,7 +49,7 @@

        Watching for changes. Press ctrl+c to stop

        15 pages created

        0 tags created

+       in 8 ms

        Web Server is available at http://localhost:1313

        Press ctrl+c to stop

-

--- a/docs/content/doc/variables.md

+++ b/docs/content/doc/variables.md

@@ -14,6 +14,8 @@

 **.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>

+**.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`. 

 Take for example I'm using tags and categories as my indexes. The following would be how I would access them:

--- a/docs/layouts/index.html

+++ b/docs/layouts/index.html

@@ -17,7 +17,8 @@

           <div class="hero-unit" style="background-color: #222; color: #ccc;">

             <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>

               <a class="btn btn-large btn-success" href="/doc/installing.html">Get Started</a> 

             </p>

@@ -27,20 +28,27 @@

               <h2>Fast

                 <br> 

               </h2>

-              <p>Written in GoLang for speed, Hugo is significantly faster than other

-              static site generators. It's so fast that it will render the site in 

+              <p>Written in GoLang for speed, Hugo is significantly faster than most

+              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>

             </div>

             <div class="span4">

               <h2>Flexible</h2>

               <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 class="span4">

               <h2>Fun</h2>

-              <p>Hugo is more fun than you can shake a stick at. Hugo removes all 

-              the cruft of building a site allowing you to focus on creating the 

-              best site possible.</p>

+              <p>Hugo runs everywhere. Sites generated with Hugo work on every web 

+              server without any special configuration. Hugo

+              removes all the cruft of building a site allowing you to 

+              focus on writing great content.</p>

             </div>

           </div>

 {{ template "chrome/footer.html" }}