From 8c0ab4def124cc632c6e046e3e770bd4a055133a Mon Sep 17 00:00:00 2001 From: spf13 Date: Sat, 17 Aug 2013 08:34:25 -0400 Subject: [PATCH] Complete overhaul of the docs --- docs/content/{doc => content}/example.md | 5 +- docs/content/{doc => content}/front-matter.md | 5 +- docs/content/content/organization.md | 154 ++++++++++++++++++ docs/content/content/sections.md | 43 +++++ docs/content/content/types.md | 49 ++++++ docs/content/doc/contributors.md | 9 - docs/content/doc/organization.md | 22 --- docs/content/doc/templates.md | 66 -------- docs/content/{doc => extras}/aliases.md | 5 +- docs/content/{doc => extras}/indexes.md | 11 +- docs/content/extras/indexes/category.md | 54 ++++++ docs/content/extras/indexes/series.md | 0 docs/content/{doc => extras}/shortcodes.md | 3 +- docs/content/layout/chrome.md | 80 +++++++++ docs/content/layout/content.md | 125 ++++++++++++++ docs/content/layout/go-templates.md | 15 ++ docs/content/layout/homepage.md | 50 ++++++ docs/content/layout/index.md | 122 ++++++++++++++ docs/content/layout/rss.md | 47 ++++++ docs/content/layout/templates.md | 35 ++++ docs/content/{doc => layout}/variables.md | 27 ++- docs/content/layout/views.md | 79 +++++++++ docs/content/{doc => meta}/contributing.md | 15 +- docs/content/meta/contributors.md | 12 ++ docs/content/{doc => meta}/license.md | 3 +- docs/content/{doc => meta}/release-notes.md | 11 +- docs/content/{doc => meta}/roadmap.md | 3 +- .../{doc => overview}/configuration.md | 10 +- docs/content/{doc => overview}/installing.md | 3 +- .../{doc => overview}/source-directory.md | 3 +- docs/content/{doc => overview}/usage.md | 3 +- docs/layouts/{doc => _default}/single.html | 0 docs/layouts/chrome/header.html | 5 +- docs/layouts/chrome/menu.html | 45 +++-- docs/layouts/index.html | 3 + 35 files changed, 971 insertions(+), 151 deletions(-) rename docs/content/{doc => content}/example.md (93%) rename docs/content/{doc => content}/front-matter.md (97%) create mode 100644 docs/content/content/organization.md create mode 100644 docs/content/content/sections.md create mode 100644 docs/content/content/types.md delete mode 100644 docs/content/doc/contributors.md delete mode 100644 docs/content/doc/organization.md delete mode 100644 docs/content/doc/templates.md rename docs/content/{doc => extras}/aliases.md (94%) rename docs/content/{doc => extras}/indexes.md (97%) create mode 100644 docs/content/extras/indexes/category.md create mode 100644 docs/content/extras/indexes/series.md rename docs/content/{doc => extras}/shortcodes.md (98%) create mode 100644 docs/content/layout/chrome.md create mode 100644 docs/content/layout/content.md create mode 100644 docs/content/layout/go-templates.md create mode 100644 docs/content/layout/homepage.md create mode 100644 docs/content/layout/index.md create mode 100644 docs/content/layout/rss.md create mode 100644 docs/content/layout/templates.md rename docs/content/{doc => layout}/variables.md (67%) create mode 100644 docs/content/layout/views.md rename docs/content/{doc => meta}/contributing.md (69%) create mode 100644 docs/content/meta/contributors.md rename docs/content/{doc => meta}/license.md (97%) rename docs/content/{doc => meta}/release-notes.md (72%) rename docs/content/{doc => meta}/roadmap.md (86%) rename docs/content/{doc => overview}/configuration.md (94%) rename docs/content/{doc => overview}/installing.md (95%) rename docs/content/{doc => overview}/source-directory.md (96%) rename docs/content/{doc => overview}/usage.md (97%) rename docs/layouts/{doc => _default}/single.html (100%) diff --git a/docs/content/doc/example.md b/docs/content/content/example.md similarity index 93% rename from docs/content/doc/example.md rename to docs/content/content/example.md index 51e3c160e..9d90c97fa 100644 --- a/docs/content/doc/example.md +++ b/docs/content/content/example.md @@ -1,6 +1,7 @@ --- title: "Example Content File" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/example/"] --- Somethings are better shown than explained. The following is a very basic example of a content file: @@ -12,7 +13,7 @@ Somethings are better shown than explained. The following is a very basic exampl Description": "" Keywords": [ "Development", "golang", "profiling" ] Tags": [ "Development", "golang", "profiling" ] - Pubdate": "2013-06-19" + date": "2013-06-19" Topics": [ "Development", "GoLang" ] Slug": "nitro" project_url": "http://github.com/spf13/nitro" diff --git a/docs/content/doc/front-matter.md b/docs/content/content/front-matter.md similarity index 97% rename from docs/content/doc/front-matter.md rename to docs/content/content/front-matter.md index 566fb1fba..0a409c56a 100644 --- a/docs/content/doc/front-matter.md +++ b/docs/content/content/front-matter.md @@ -1,6 +1,7 @@ +++ title = "Front Matter" date = "2013-07-01" +aliases = ["/doc/front-matter/"] +++ The front matter is one of the features that gives Hugo it's strength. It enables @@ -18,7 +19,7 @@ Supported formats:
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" + date: "2012-04-06" categories: - "Development" - "VIM" @@ -32,7 +33,7 @@ Supported formats:
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" + date = "2012-04-06" categories = [ "Development", "VIM" diff --git a/docs/content/content/organization.md b/docs/content/content/organization.md new file mode 100644 index 000000000..f9eba097a --- /dev/null +++ b/docs/content/content/organization.md @@ -0,0 +1,154 @@ +--- +title: "Content Organization" +date: "2013-07-01" +aliases: ["/doc/organization/"] +--- + +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. Hugo supports +content nested at any level. The top level is special in Hugo and is used as the +[section](/content/sections). + + . + └── content + ├── post + | ├── firstpost.md // <- http://site.com/post/firstpost/ + | ├── happy + | | └── happiness.md // <- http://site.com/happy/happiness/ + | └── secondpost.md // <- http://site.com/post/secondpost/ + └── quote + ├── first.md // <- http://site.com/quote/first/ + └── second.md // <- http://site.com/quote/second/ + +**Here's the same organization run with hugo -\-uglyurls** + + . + └── content + ├── post + | ├── firstpost.md // <- http://site.com/post/firstpost.html + | ├── happy + | | └── happiness.md // <- http://site.com/happy/happiness.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 + +## Destinations + +Hugo thinks 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. + +The following items are defined in order, latter items in the list will override +earlier settings. + +#### filename +This isn't in the front matter, but is the actual name of the file minus the +extension. This will be the name of the file in the destination. + +#### slug +Defined in the front matter, the slug can take the place of the filename for the +destination. + +#### filepath +The actual path to the file on disk. Destination will create the destination +with the same path. Includes [section](/content/sections). + +#### section +section can be provided in the front matter overriding the section derived from +the source content location on disk. See [section](/content/sections). + +#### path +path can be provided in the front matter. This will replace the actual +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 +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. + + +## Path breakdown in hugo + +### Content + + . path slug + . ⊢-------^----⊣ ⊢------^-------⊣ + content/extras/indexes/category-example/index.html + + + . section slug + . ⊢--^--⊣ ⊢------^-------⊣ + content/extras/indexes/category-example/index.html + + + . section slug + . ⊢--^--⊣⊢--^--⊣ + content/extras/indexes/index.html + +### Destination + + + permalink + ⊢--------------^-------------⊣ + http://spf13.com/projects/hugo + + + baseUrl section slug + ⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣ + http://spf13.com/projects/hugo + + + baseUrl section slug + ⊢-----^--------⊣ ⊢--^--⊣ ⊢--^--⊣ + http://spf13.com/extras/indexes/example + + + baseUrl path slug + ⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣ + http://spf13.com/extras/indexes/example + + + baseUrl url + ⊢-----^--------⊣ ⊢-----^-----⊣ + http://spf13.com/projects/hugo + + + baseUrl url + ⊢-----^--------⊣ ⊢--------^-----------⊣ + http://spf13.com/extras/indexes/example + + + +section = which type the content is by default + based on content location + front matter overrides + + +slug = name.ext or name/ + based on content-name.md + front matter overrides + + +path = section + path to file exluding slug + based on path to content location + + +url = relative url + defined in front matter + overrides all the above + + + diff --git a/docs/content/content/sections.md b/docs/content/content/sections.md new file mode 100644 index 000000000..ca72d6109 --- /dev/null +++ b/docs/content/content/sections.md @@ -0,0 +1,43 @@ +--- +title: "Sections" +date: "2013-07-01" +--- + +Hugo thinks 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**. + +The following example site uses two sections, "post" and "quote". + + . + └── content + ├── post + | ├── firstpost.md // <- http://site.com/post/firstpost/ + | ├── happy + | | └── happiness.md // <- http://site.com/happy/happiness/ + | └── secondpost.md // <- http://site.com/post/secondpost/ + └── quote + ├── first.md // <- http://site.com/quote/first/ + └── second.md // <- http://site.com/quote/second/ + + +*Regardless of location on disk, the section can be provided in the front matter +which will affect the destination location*. + +## Sections and Types + +By default everything created within a section will use the content type +that matches the section name. + +Section defined in the front matter have the same impact. + +To change the type of a given piece of content simply define the type +in the front matter. + +If a layout for a given type hasn't been provided a default type template will +be used instead provided is exists. + + + + diff --git a/docs/content/content/types.md b/docs/content/content/types.md new file mode 100644 index 000000000..8f535454c --- /dev/null +++ b/docs/content/content/types.md @@ -0,0 +1,49 @@ +--- +title: "Content Types" +date: "2013-07-01" +--- + +Hugo has full support for multiple content types each with it's own set +of meta data and template. A good example of when multiple types are +needed is to look a tumblr. A piece of content could be a photo, quote +or post, each with different meta data and rendered differently. + + +## Defining a content type + +Creating a new content type is easy in Hugo. You simply provide the +templates that the new type will use. + +It is essential to provide the single render view template as well as a +list view template. + +**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 this example site will be very helpful in order to understand how these types work. + +## Assigning a content type + +Hugo assumes that your site will be organized into [sections](/content/sections) +and each section will use the corresponding type. If you are taking advantage of +this then each new piece of content you place into a section will automatically +inherit the type. + +Alternatively you can set the type in the meta data under the key "type". + + + diff --git a/docs/content/doc/contributors.md b/docs/content/doc/contributors.md deleted file mode 100644 index 4bc5a9d31..000000000 --- a/docs/content/doc/contributors.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Contributors" -date: "2013-07-01" ---- - -Hugo was built with love and golang by: - -* [spf13](https://github.com/spf13) - diff --git a/docs/content/doc/organization.md b/docs/content/doc/organization.md deleted file mode 100644 index f524c59d0..000000000 --- a/docs/content/doc/organization.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Organization" -Pubdate: "2013-07-01" ---- - -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 - diff --git a/docs/content/doc/templates.md b/docs/content/doc/templates.md deleted file mode 100644 index 6b6e0f34c..000000000 --- a/docs/content/doc/templates.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Templates" -Pubdate: "2013-07-01" ---- - -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.* - - - -#### 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 this example site will be very helpful in order to understand how these types work. - diff --git a/docs/content/doc/aliases.md b/docs/content/extras/aliases.md similarity index 94% rename from docs/content/doc/aliases.md rename to docs/content/extras/aliases.md index 1e8a3556e..d1228d696 100644 --- a/docs/content/doc/aliases.md +++ b/docs/content/extras/aliases.md @@ -1,9 +1,10 @@ --- title: "Aliases" -Pubdate: "2013-07-09" -Aliases: +date: "2013-07-09" +aliases: - /doc/redirects/ - /doc/alias/ + - /doc/aliases/ --- For people migrating existing published content to Hugo theres a good chance diff --git a/docs/content/doc/indexes.md b/docs/content/extras/indexes.md similarity index 97% rename from docs/content/doc/indexes.md rename to docs/content/extras/indexes.md index 9731a7739..b08c83742 100644 --- a/docs/content/doc/indexes.md +++ b/docs/content/extras/indexes.md @@ -1,6 +1,7 @@ --- title: "Indexes" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/indexes/"] --- Hugo includes support for user defined indexes of content. In our @@ -70,8 +71,6 @@ The following variables are available to the index template: - - {{ template "chrome/footer.html" }} @@ -88,13 +87,13 @@ and assign all keys you want this content to match against. #### Example { - "Title": "Hugo: A fast and flexible static site generator", - "Tags": [ + "title": "Hugo: A fast and flexible static site generator", + "tags": [ "Development", "golang", "Blogging" ], - "Slug": "hugo", + "slug": "hugo", "project_url": "http://github.com/spf13/hugo" } diff --git a/docs/content/extras/indexes/category.md b/docs/content/extras/indexes/category.md new file mode 100644 index 000000000..6b948124d --- /dev/null +++ b/docs/content/extras/indexes/category.md @@ -0,0 +1,54 @@ +--- +title: "Index Category Example" +date: "2013-07-01" +--- + +This page demonstrates an example of using indexes to provide categories for your site. + +### config.yaml +First step is to define the index in your config file. +*Because we use both the singular and plural name of the index in our rendering it's +important to provide both here. We require this, rather than using inflection in +effort to support as many languages as possible.* + + --- + indexes: + category: "categories" + baseurl: "http://spf13.com/" + title: "Steve Francia is spf13.com" + --- + +### /layouts/indexes/category.html + +For each index type a template needs to be provided to render the index page. +In the case of categories, this will render the content for /categories/CATEGORYNAME/. + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ + {{ template "chrome/footer.html" }} + + +### Assigning indexes to content + +Make sure that the index is set in the front matter: + + { + "title": "Hugo: A fast and flexible static site generator", + "categories": [ + "Development", + "golang", + "Blogging" + ], + "slug": "hugo" + } + diff --git a/docs/content/extras/indexes/series.md b/docs/content/extras/indexes/series.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/content/doc/shortcodes.md b/docs/content/extras/shortcodes.md similarity index 98% rename from docs/content/doc/shortcodes.md rename to docs/content/extras/shortcodes.md index 222963b03..a288fe585 100644 --- a/docs/content/doc/shortcodes.md +++ b/docs/content/extras/shortcodes.md @@ -1,6 +1,7 @@ --- title: "Shortcodes" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/shortcodes/"] --- Because Hugo uses markdown for it's content format, it was clear that there's a lot of things that diff --git a/docs/content/layout/chrome.md b/docs/content/layout/chrome.md new file mode 100644 index 000000000..1616625a3 --- /dev/null +++ b/docs/content/layout/chrome.md @@ -0,0 +1,80 @@ +--- +title: "Chrome Templates" +date: "2013-07-01" +--- +Chrome is a convention to create templates that are used by the other templates +throughout the site. There is nothing special about the name "chrome", feel free +to provide and use your own. + +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). There is nothing special about header.html and footer.html +other than they seem like good names to use for inclusion in your other +templates. + + ▾ layouts/ + ▾ chrome/ + header.html + footer.html + +By ensuring that we only reference [variables](/layout/variables/) variables +used for both nodes and pages we can use the same chrome for both. + +## example header.html +This header template is used for [spf13.com](http://spf13.com). + + + + + + + {{ template "chrome/meta.html" . }} + + + {{ .Title }} : spf13.com + + {{ if .RSSlink }}{{ end }} + + {{ template "chrome/head_includes.html" . }} + + + + + +## example footer.html +This header template is used for [spf13.com](http://spf13.com). + + + + + + +**For examples of referencing these templates, see [content +templates](/layout/content/) and [homepage templates](/layout/homepage/)** diff --git a/docs/content/layout/content.md b/docs/content/layout/content.md new file mode 100644 index 000000000..e6df58867 --- /dev/null +++ b/docs/content/layout/content.md @@ -0,0 +1,125 @@ +--- +title: "Content Templates" +date: "2013-07-01" +--- + +Content templates are created in a directory matching the name of the content. + +Content pages are of the type "page" and have all the [page +variables](/layout/variables/) available to use in the templates. + +In the following examples we have created two different content types as well as +a default content type. + + ▾ layouts/ + ▾ post/ + single.html + ▾ project/ + single.html + +Hugo also has support for a default content template to be used in the event +that a specific template has not been provided for that type. The default type +works the same as the other types but the directory must be called "_default". +[Content views](/layout/views) can also be defined in the "_default" directory. + + + ▾ layouts/ + ▾ _default/ + single.html + + + + +## post/single.html +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome) + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + {{ $baseurl := .Site.BaseUrl }} + +
+

{{ .Title }}

+
+
+ {{ .Content }} +
+
+
+ + + + {{ template "chrome/disqus.html" . }} + {{ template "chrome/footer.html" . }} + + +## project/single.html +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome) + + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + {{ $baseurl := .Site.BaseUrl }} + +
+

{{ .Title }}

+
+
+ {{ .Content }} +
+
+
+ + + + {{if isset .Params "project_url" }} +
+ Fork me on GitHub +
+ {{ end }} + + {{ template "chrome/footer.html" }} + + +Notice how the project/single.html template uses an additional parameter unique +to this template. This doesn't need to be defined ahead of time. If the key is +present in the front matter than it can be used in the template. diff --git a/docs/content/layout/go-templates.md b/docs/content/layout/go-templates.md new file mode 100644 index 000000000..b3c15a09a --- /dev/null +++ b/docs/content/layout/go-templates.md @@ -0,0 +1,15 @@ +--- +title: "Go Templates" +date: "2013-07-01" +--- + +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 is a brief primer on using go templates. The [golang +docs](http://golang.org/pkg/html/template/) provide more details. + + + diff --git a/docs/content/layout/homepage.md b/docs/content/layout/homepage.md new file mode 100644 index 000000000..85fb276cb --- /dev/null +++ b/docs/content/layout/homepage.md @@ -0,0 +1,50 @@ +--- +title: "Homepage Templates" +date: "2013-07-01" +--- + +Home pages are of the type "node" and have all the [node +variables](/layout/variables/) available to use in the templates. + +*This is the only required template for building a site and useful when +bootstrapping a new site and template.* + +In addition to the standard node variables, the homepage has access to +all site content accessible from .Data.Pages + + + ▾ layouts/ + index.html + + +## example index.html +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome) + + + + + + + {{ template "chrome/meta.html" . }} + + + {{ .Site.Title }} + + + + {{ template "chrome/head_includes.html" . }} + + + + {{ template "chrome/subheader.html" . }} + +
+
+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ + {{ template "chrome/footer.html" }} diff --git a/docs/content/layout/index.md b/docs/content/layout/index.md new file mode 100644 index 000000000..7184bbf6a --- /dev/null +++ b/docs/content/layout/index.md @@ -0,0 +1,122 @@ +--- +title: "Index Templates" +date: "2013-07-01" +--- + +An index template is any template that will be used to render multiple pieces of +content (with the exception of the [homepage](/layout/homepage) which has a +dedicated template). + +We are using the term index in it's truest sense, a sequential arrangement of +material, especially in alphabetical or numerical order. In the case of Hugo +each index will render the content in newest first order based on the date +provided in the [front matter](/content/front-matter). + +index pages are of the type "node" and have all the [node +variables](/layout/variables/) available to use in the templates. +All index templates live in the layouts/indexes directory. There are 3 different +kinds of indexes that Hugo can produce. + +1. A listing of all the content for a given [section](/content/sections) +2. A listing of all the content for a given [index](/extras/indexes) +3. A listing of listings... [meta index](/extras/indexes) + +It's critical that the name of the index template matches either: + +1. The section name +2. The index singular name +3. "indexes" + +The following illustrates the location of one of each of these types. + + ▾ layouts/ + ▾ indexes/ + indexes.html + post.html + tag.html + +## Example section template (post.html) +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome). All examples use a +[view](/layout/views/) called either "li" or "summary" which this example site +defined. + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+
    + {{ range .Data.Pages }} + {{ .Render "li"}} + {{ end }} +
+
+
+ + {{ template "chrome/footer.html" }} + +## Example index template (tag.html) +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome). All examples use a +[view](/layout/views/) called either "li" or "summary" which this example site +defined. + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ + {{ template "chrome/footer.html" }} + + +## Example listing of indexes template (indexes.html) +This content template is used for [spf13.com](http://spf13.com). +It makes use of [chrome templates](/layout/chrome). The list of indexes +templates cannot use a [content view](/layout/views) as they don't display the content, but +rather information about the content. + +This particular template lists all of the Tags used on +[spf13.com](http://spf13.com) and provides a count for the number of pieces of +content tagged with each tag. + +This example demonstrates two different approaches. The first uses .Data.Index and +the latter uses .Data.OrderedIndex. .Data.Index is alphabetical by key name, while +.Data.Orderedindex is ordered by the quantity of content assigned to that particular +index key. In practice you would only use one of these approaches. + + {{ template "chrome/header.html" . }} + {{ template "chrome/subheader.html" . }} + +
+
+

{{ .Title }}

+ +
    + {{ $data := .Data }} + {{ range $key, $value := .Data.Index }} +
  • {{ $key }} {{ len $value }}
    • + {{ end }} +
+
+ + +
+ + {{ template "chrome/footer.html" }} + + + + diff --git a/docs/content/layout/rss.md b/docs/content/layout/rss.md new file mode 100644 index 000000000..6331cb080 --- /dev/null +++ b/docs/content/layout/rss.md @@ -0,0 +1,47 @@ +--- +title: "RSS (feed) Templates" +date: "2013-07-01" +--- + +A single RSS template is used to generate all of the RSS content for the entire +site. + +RSS pages are of the type "node" and have all the [node +variables](/layout/variables/) available to use in the templates. + +In addition to the standard node variables, the homepage has access to +all site content accessible from .Data.Pages + + ▾ layouts/ + rss.xml + +## rss.xml +This rss template is used for [spf13.com](http://spf13.com). It adheres to the +ATOM 2.0 Spec. + + + + + {{ .Title }} on {{ .Site.Title }} + {{ .Permalink }} + en-us + Steve Francia + Copyright (c) 2008 - 2013, Steve Francia; all rights reserved. + {{ .Date }} + {{ range .Data.Pages }} + + {{ .Title }} + {{ .Permalink }} + {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }} + Steve Francia + {{ .Permalink }} + {{ .Content | html }} + + {{ end }} + + + +*Important: Hugo will automatically add the following header line to this file +on render...please don't include this in the template as it's not valid HTML.* + + diff --git a/docs/content/layout/templates.md b/docs/content/layout/templates.md new file mode 100644 index 000000000..521c73cb4 --- /dev/null +++ b/docs/content/layout/templates.md @@ -0,0 +1,35 @@ +--- +title: "Templates" +date: "2013-07-01" +aliases: ["/doc/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 + +If you are new to go's templates the [go template primer](/layout/go-templates) +is a great place to start. + +## Template roles + +There are 6 different kinds of templates that Hugo works with. + +### [Homepage](/layout/homepage/) +The homepage of your site. + +### [RSS](/layout/rss/) +Used to render all rss documents. + +### [Indexes](/layout/indexes) +Page that list multiple pieces of content. + +### [Content](/layout/content) +Templates to render a single piece of content. + +### [Views](/layout/views) +Different ways of rendering each content type + +### [Chrome](/layout/chrome) +Simply the decoration of your site. diff --git a/docs/content/doc/variables.md b/docs/content/layout/variables.md similarity index 67% rename from docs/content/doc/variables.md rename to docs/content/layout/variables.md index 27f4c66a6..9e8115517 100644 --- a/docs/content/doc/variables.md +++ b/docs/content/layout/variables.md @@ -1,11 +1,14 @@ --- title: "Variables" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/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. +## Page Variables + **.Title** The title for the content.
**.Description** The description for the content.
**.Keywords** The meta keywords for this content.
@@ -16,13 +19,28 @@ are available in the context for the templates. **.RSSLink** Link to the indexes' rss link
**.Prev** Pointer to the previous content (based on pub date)
**.Next** Pointer to the following content (based on pub date)
+**.Site** See site variables below
**.Content** The content itself, defined below the front matter.
-Any value defined in the front matter, including indexes will be made available under `.Params`. +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**
-**.Params.Categories**
+**.Params.Tags**
+**.Params.Categories**
+ +## Node Variables +In Hugo a node is any page not rendered directly by a content file. This +includes indexes, lists and the homepage. + +**.Title** The title for the content.
+**.Date** The date the content is published on.
+**.Data** The data specific to this type of node.
+**.Permalink** The Permanent link for this node
+**.Url** The relative url for this node.
+**.RSSLink** Link to the indexes' rss link
+**.Site** See site variables below
+ +## Site Variables Also available is `.Site` which has the following: @@ -30,3 +48,4 @@ Also available is `.Site` which has the following: **.Site.Indexes** The names of the indexes of the site.
**.Site.LastChange** The date of the last change of the most recent content.
**.Site.Recent** Array of all content ordered by Date, newest first
+ diff --git a/docs/content/layout/views.md b/docs/content/layout/views.md new file mode 100644 index 000000000..bf02ceda9 --- /dev/null +++ b/docs/content/layout/views.md @@ -0,0 +1,79 @@ +--- +title: "Content Views" +date: "2013-07-01" +--- + +In addition to the [single content view](/layout/content/), Hugo can render alternative views of +your content. These are especially useful in [index](/layout/index) templates. + +To create a new view simple create a template in each of your different content +type directories with the view name. In the following example we have created a +"li" view and a "summary" view for our two content types of post and project. As +you can see these sit next to the [single content view](/layout/content) +template "single.html" + + ▾ layouts/ + ▾ post/ + li.html + single.html + summary.html + ▾ project/ + li.html + single.html + summary.html + +Hugo also has support for a default content template to be used in the event +that a specific template has not been provided for that type. The default type +works the same as the other types but the directory must be called "_default". +Content views can also be defined in the "_default" directory. + + + ▾ layouts/ + ▾ _default/ + li.html + single.html + summary.html + + +Hugo will pass the entire page object to the view template. See [page +variables](/layout/variables) for a complete list. + +## Example li.html +This content template is used for [spf13.com](http://spf13.com). + +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • + +## Example summary.html +This content template is used for [spf13.com](http://spf13.com). + +
    +
    +

    {{ .Title }}

    +
    {{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words
    +
    + + {{ .Summary }} + +
    + + +## Example render of view +Using the summary view inside of another ([index](/layout/index)) template. + +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    + +In the above example you will notice that we have called .Render and passed in +which view to render the content with. Render is a special function available on +a content which tells the content to render itself with the provided view template. diff --git a/docs/content/doc/contributing.md b/docs/content/meta/contributing.md similarity index 69% rename from docs/content/doc/contributing.md rename to docs/content/meta/contributing.md index 84d08633c..0a1a04931 100644 --- a/docs/content/doc/contributing.md +++ b/docs/content/meta/contributing.md @@ -1,15 +1,16 @@ --- title: "Contributing to Hugo" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/contributing/"] --- -We welcome all contributions. If you want to contribute, all -that is needed is simply fork Hugo, make changes and submit +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 +or contact [spf13](http://spf13.com) about what may make sense to do next. -## Overview +## 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'`) @@ -23,8 +24,8 @@ to do next. 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 +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 diff --git a/docs/content/meta/contributors.md b/docs/content/meta/contributors.md new file mode 100644 index 000000000..3b24fb2a8 --- /dev/null +++ b/docs/content/meta/contributors.md @@ -0,0 +1,12 @@ +--- +title: "Contributors" +date: "2013-07-01" +aliases: ["/doc/contributors/"] +--- + +Hugo was built with love and golang by: + +* Steve Francia - [spf13](https://github.com/spf13) +* Noah Campbell - [noahcampbell](https://github.com/noahcampbell) +* [Many more](http://github.com/spf13/hugo/graphs/contributors) + diff --git a/docs/content/doc/license.md b/docs/content/meta/license.md similarity index 97% rename from docs/content/doc/license.md rename to docs/content/meta/license.md index 613a7ed27..e9b2c4664 100644 --- a/docs/content/doc/license.md +++ b/docs/content/meta/license.md @@ -1,6 +1,7 @@ --- title: "License" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/license/", "/license/"] --- Hugo is released under the Simple Public License. diff --git a/docs/content/doc/release-notes.md b/docs/content/meta/release-notes.md similarity index 72% rename from docs/content/doc/release-notes.md rename to docs/content/meta/release-notes.md index 025b71875..f4af8cdd3 100644 --- a/docs/content/doc/release-notes.md +++ b/docs/content/meta/release-notes.md @@ -1,10 +1,17 @@ --- title: "Release Notes" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/release-notes/"] --- -* **0.9.0** +* **0.9.0** HEAD * Added support for aliases (redirects) + * Cleanup of how content organization is handled + * Support for top level pages (other than homepage) + * Loads of unit and performance tests + * Integration with travis ci + * Complete overhaul of the documentation site + * Full Windows support * **0.8.0** August 2, 2013 * Added support for pretty urls (filename/index.html vs filename.html) * Hugo supports a destination directory diff --git a/docs/content/doc/roadmap.md b/docs/content/meta/roadmap.md similarity index 86% rename from docs/content/doc/roadmap.md rename to docs/content/meta/roadmap.md index a0921efaf..d0e8276e8 100644 --- a/docs/content/doc/roadmap.md +++ b/docs/content/meta/roadmap.md @@ -1,6 +1,7 @@ --- title: "Roadmap" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/roadmap/"] --- In no particular order, here is what we are working on: diff --git a/docs/content/doc/configuration.md b/docs/content/overview/configuration.md similarity index 94% rename from docs/content/doc/configuration.md rename to docs/content/overview/configuration.md index 0fee65297..84790fdab 100644 --- a/docs/content/doc/configuration.md +++ b/docs/content/overview/configuration.md @@ -1,6 +1,7 @@ --- title: "Configuring Hugo" -pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/configuration/"] --- The directory structure and templates provide the majority of the @@ -15,7 +16,7 @@ then look for a config.json file, followed by a config.toml file. ## Examples -The following is an example of a yaml config file with the default values: +The following is an example of a yaml config file with the default values: --- contentdir: "content" @@ -29,7 +30,7 @@ The following is an example of a yaml config file with the default values: ... -The following is an example of a json config file with the default values: +The following is an example of a json config file with the default values: { "contentdir": "content", @@ -44,7 +45,7 @@ The following is an example of a json config file with the default values: } -The following is an example of a toml config file with the default values: +The following is an example of a toml config file with the default values: contentdir = "content" layoutdir = "layouts" @@ -55,4 +56,3 @@ The following is an example of a toml config file with the default values: category = "categories" tag = "tags" - diff --git a/docs/content/doc/installing.md b/docs/content/overview/installing.md similarity index 95% rename from docs/content/doc/installing.md rename to docs/content/overview/installing.md index 53c0fb618..90456111d 100644 --- a/docs/content/doc/installing.md +++ b/docs/content/overview/installing.md @@ -1,6 +1,7 @@ --- title: "Installing Hugo" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/installing/"] --- Hugo is written in GoLang with support for Windows, Linux, FreeBSD and OSX. diff --git a/docs/content/doc/source-directory.md b/docs/content/overview/source-directory.md similarity index 96% rename from docs/content/doc/source-directory.md rename to docs/content/overview/source-directory.md index 263127573..12a703536 100644 --- a/docs/content/doc/source-directory.md +++ b/docs/content/overview/source-directory.md @@ -1,6 +1,7 @@ --- title: "Source Directory Organization" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/source-directory/"] --- Hugo takes a single directory and uses it as the input for creating a complete website. diff --git a/docs/content/doc/usage.md b/docs/content/overview/usage.md similarity index 97% rename from docs/content/doc/usage.md rename to docs/content/overview/usage.md index 3d0dbe9ee..3f022a16a 100644 --- a/docs/content/doc/usage.md +++ b/docs/content/overview/usage.md @@ -1,6 +1,7 @@ --- title: "Using Hugo" -Pubdate: "2013-07-01" +date: "2013-07-01" +aliases: ["/doc/usage/"] --- Make sure either hugo is in your path or provide a path to it. diff --git a/docs/layouts/doc/single.html b/docs/layouts/_default/single.html similarity index 100% rename from docs/layouts/doc/single.html rename to docs/layouts/_default/single.html diff --git a/docs/layouts/chrome/header.html b/docs/layouts/chrome/header.html index 544f08ab4..324d922ca 100644 --- a/docs/layouts/chrome/header.html +++ b/docs/layouts/chrome/header.html @@ -13,7 +13,10 @@

    Hugo

    -

    A Fast and Flexible Static Site Generator built with love by spf13 in Go

    +

    A Fast and Flexible Static Site Generator + built with love by spf13 and friends + in Go

    {{ template "chrome/menu.html" . }}
    diff --git a/docs/layouts/chrome/menu.html b/docs/layouts/chrome/menu.html index 5efd81830..40b3b6693 100644 --- a/docs/layouts/chrome/menu.html +++ b/docs/layouts/chrome/menu.html @@ -2,29 +2,40 @@
  • Home
  • Getting Started
    • -
  • Installing Hugo
    • -
  • Usage
    • -
  • Configuration
    • -
  • Input Directory Layout
    • +
  • Installing Hugo
    • +
  • Usage
    • +
  • Configuration
    • +
  • Source Directory Layout
  • Layout
    • -
  • Templates
    • -
  • Variables
    • +
  • Overview
    • + +
  • Variables
    • +
  • Homepage
    • +
  • RSS
    • +
  • Index
    • +
  • Content
    • +
  • Content Views
    • +
  • Chrome
  • Content
    • -
  • Organization
    • -
  • Front Matter
    • -
  • Example
    • +
  • Organization
    • +
  • Sections
    • +
  • Types
    • +
  • Front Matter
    • +
  • Example
  • Extras
    • -
  • ShortCodes
    • -
  • Indexes
    • -
  • Aliases
    • +
  • ShortCodes
    • +
  • Aliases
    • +
  • Indexes
    • +
  • Example Index - Category
    • +
  • Meta
    • -
  • Release Notes
    • -
  • Roadmap
    • -
  • Contributing
    • -
  • Contributors
    • -
  • License
    • +
  • Release Notes
    • +
  • Roadmap
    • +
  • Contributing
    • +
  • Contributors
    • +
  • License
    • diff --git a/docs/layouts/index.html b/docs/layouts/index.html index b6646e751..92e82fa33 100644 --- a/docs/layouts/index.html +++ b/docs/layouts/index.html @@ -51,4 +51,7 @@ focus on writing great content.

    + {{ range $key, $val := .Site.Recent }} + {{ $val.Title}} + {{ end }} {{ template "chrome/footer.html" }}