Updating a bunch of the docs

docs/content/doc/contributing.md

@@ -3,8 +3,42 @@ title: "Contributing to Hugo"
 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/
+

docs/content/doc/installing.md

@@ -31,520 +31,16 @@ is the most probable location.
 * 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
     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
+Please see the [contributing guide](/doc/contributing)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-## Contributors
-
-* [spf13](https://github.com/spf13)
-
-
-## License
-
-Hugo is released under the Simple Public License. See [LICENSE.md](https://github.com/spf13/hugo/blob/master/LICENSE.md).

docs/content/doc/release-notes.md

@@ -3,6 +3,19 @@ title: "Release Notes"
 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

docs/content/doc/roadmap.md

@@ -3,16 +3,15 @@ title: "Roadmap"
 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
 
 

docs/content/doc/source-directory.md

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

docs/content/doc/usage.md

@@ -8,8 +8,9 @@ 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
+      -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
@@ -28,12 +29,11 @@ directory being the input directory.
     $ 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. 
+immediately, tell Hugo to watch for changes. **It will
-<br>
-**It will 
 recreate the site faster than you can tab over to
 your browser to view the changes.**
 
@@ -41,6 +41,7 @@ your browser to view the changes.**
        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 @@ Hugo can even run a server and create your site at the same time!
        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
 
-

docs/content/doc/variables.md

@@ -14,6 +14,8 @@ are available in the context for the templates.
 **.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:

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
+              <p>Written in GoLang for speed, Hugo is significantly faster than most
-              static site generators. It's so fast that it will render the site in 
+              other static site generators.
+              A typical website of moderate size can be
+              rendered in a fraction of a second. A good rule of thumb is that Hugo
+              takes around 1 millisecond for each piece of content.<br>
+              It's so fast that it will render the site in 
               less time than it takes to switch to your browser and reload.</p>
             </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 
+              <p>Hugo runs everywhere. Sites generated with Hugo work on every web 
-              the cruft of building a site allowing you to focus on creating the 
+              server without any special configuration. Hugo
-              best site possible.</p>
+              removes all the cruft of building a site allowing you to 
+              focus on writing great content.</p>
             </div>
           </div>
 {{ template "chrome/footer.html" }}