From a87f171bd4446773e05198427e920571af63e650 Mon Sep 17 00:00:00 2001 From: spf13 Date: Tue, 27 May 2014 18:32:57 -0400 Subject: [PATCH] Updating / Rewriting / Adding all of the documentation in preparation for the next release --- docs/config.toml | 23 +- docs/content/community/contributing.md | 9 +- docs/content/community/contributors.md | 3 +- docs/content/community/mailing-list.md | 2 + docs/content/community/press.md | 2 + docs/content/content/archetypes.md | 76 ++++++ docs/content/content/example.md | 4 +- docs/content/content/front-matter.md | 5 +- docs/content/content/ordering.md | 78 +------ docs/content/content/organization.md | 18 +- docs/content/content/sections.md | 13 +- docs/content/content/types.md | 88 ++++--- docs/content/extras/aliases.md | 4 +- docs/content/extras/builders.md | 60 +++++ docs/content/extras/comments.md | 67 ++++++ docs/content/extras/highlighting.md | 6 +- docs/content/extras/livereload.md | 61 +++++ docs/content/extras/menus.md | 162 +++++++++++++ docs/content/extras/permalinks.md | 2 + docs/content/extras/shortcodes.md | 4 +- docs/content/extras/toc.md | 8 +- docs/content/extras/urls.md | 6 +- docs/content/layout/homepage.md | 57 ----- docs/content/layout/indexes.md | 125 ---------- docs/content/layout/rss.md | 51 ----- docs/content/layout/templates.md | 40 ---- docs/content/layout/views.md | 83 ------- docs/content/meta/license.md | 6 +- docs/content/meta/release-notes.md | 24 +- docs/content/meta/roadmap.md | 28 +-- docs/content/overview/configuration.md | 39 +--- docs/content/overview/installing.md | 14 +- docs/content/overview/introduction.md | 53 +++-- docs/content/overview/quickstart.md | 153 +++++++++---- docs/content/overview/source-directory.md | 50 +++- docs/content/overview/usage.md | 44 ++-- docs/content/taxonomies/category.md | 57 ----- docs/content/taxonomies/displaying.md | 122 +++++----- docs/content/taxonomies/lists.md | 74 ------ docs/content/taxonomies/ordering.md | 34 +-- docs/content/taxonomies/overview.md | 113 +++++---- docs/content/taxonomies/templates.md | 50 +--- docs/content/taxonomies/usage.md | 60 +++++ docs/content/{layout => templates}/404.md | 5 + docs/content/{layout => templates}/content.md | 80 ++++--- .../{layout => templates}/functions.md | 9 +- .../{layout => templates}/go-templates.md | 5 +- docs/content/templates/homepage.md | 77 +++++++ docs/content/templates/list.md | 216 ++++++++++++++++++ docs/content/templates/overview.md | 69 ++++++ .../chrome.md => templates/partials.md} | 42 ++-- docs/content/templates/rss.md | 99 ++++++++ docs/content/{layout => templates}/sitemap.md | 14 +- docs/content/templates/terms.md | 131 +++++++++++ .../{layout => templates}/variables.md | 7 +- docs/content/templates/views.md | 126 ++++++++++ docs/content/themes/creation.md | 65 ++++++ docs/content/themes/customizing.md | 54 +++++ docs/content/themes/installing.md | 29 +++ docs/content/themes/overview.md | 32 +++ docs/content/themes/usage.md | 23 ++ docs/content/tutorials/github_pages_blog.md | 5 +- docs/content/tutorials/mathjax.md | 2 + docs/content/tutorials/migrate-from-jekyll.md | 6 +- 64 files changed, 2092 insertions(+), 982 deletions(-) create mode 100644 docs/content/content/archetypes.md create mode 100644 docs/content/extras/builders.md create mode 100644 docs/content/extras/comments.md create mode 100644 docs/content/extras/livereload.md create mode 100644 docs/content/extras/menus.md delete mode 100644 docs/content/layout/homepage.md delete mode 100644 docs/content/layout/indexes.md delete mode 100644 docs/content/layout/rss.md delete mode 100644 docs/content/layout/templates.md delete mode 100644 docs/content/layout/views.md delete mode 100644 docs/content/taxonomies/category.md delete mode 100644 docs/content/taxonomies/lists.md create mode 100644 docs/content/taxonomies/usage.md rename docs/content/{layout => templates}/404.md (88%) rename docs/content/{layout => templates}/content.md (57%) rename docs/content/{layout => templates}/functions.md (92%) rename docs/content/{layout => templates}/go-templates.md (98%) create mode 100644 docs/content/templates/homepage.md create mode 100644 docs/content/templates/list.md create mode 100644 docs/content/templates/overview.md rename docs/content/{layout/chrome.md => templates/partials.md} (62%) create mode 100644 docs/content/templates/rss.md rename docs/content/{layout => templates}/sitemap.md (79%) create mode 100644 docs/content/templates/terms.md rename docs/content/{layout => templates}/variables.md (95%) create mode 100644 docs/content/templates/views.md create mode 100644 docs/content/themes/creation.md create mode 100644 docs/content/themes/customizing.md create mode 100644 docs/content/themes/installing.md create mode 100644 docs/content/themes/overview.md create mode 100644 docs/content/themes/usage.md diff --git a/docs/config.toml b/docs/config.toml index 852cb14c5..11b968c71 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,27 +1,46 @@ baseurl = "http://hugo.spf13.com" +MetaDataFormat = "yaml" [indexes] tag = "tags" group = "groups" +[[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" [[menu.main]] name = "getting started" + pre = "" weight = -100 [[menu.main]] name = "content" + pre = "" weight = -90 [[menu.main]] - name = "layout" + name = "themes" + pre = "" + weight = -85 +[[menu.main]] + name = "templates" + identifier = "layout" + pre = "" weight = -80 [[menu.main]] - name = "taxonomy" + name = "taxonomies" + identifier = "taxonomy" + pre = "" weight = -70 [[menu.main]] name = "extras" + pre = "" weight = -60 [[menu.main]] name = "community" + pre = "" weight = -50 [[menu.main]] name = "tutorials" + pre = "" weight = -40 diff --git a/docs/content/community/contributing.md b/docs/content/community/contributing.md index c4f5aabdf..74a74a109 100644 --- a/docs/content/community/contributing.md +++ b/docs/content/community/contributing.md @@ -6,11 +6,16 @@ weight: 30 menu: main: parent: 'community' +prev: "/community/press" +next: "/community/contributors" --- -We welcome all contributions. Feel free to pick something from the roadmap +All contributions to Hugo are welcome. Whether you want to scratch an itch, or simply contribute to the project. Feel free to pick something from the roadmap or contact [spf13](http://spf13.com) about what may make sense -to do next. Go ahead and fork the project and make your changes. *We encourage pull requests to discuss code changes.* +to do next. + +You should fork the project and make your changes. *We encourage pull requests to discuss code changes.* + When you're ready to create a pull request, be sure to: diff --git a/docs/content/community/contributors.md b/docs/content/community/contributors.md index 316c35d7a..806cdae29 100644 --- a/docs/content/community/contributors.md +++ b/docs/content/community/contributors.md @@ -7,11 +7,12 @@ notoc: true menu: main: parent: 'community' +prev: "/community/contributing" +next: "/tutorials/github_pages_blog" --- Hugo was built with love and Go 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/community/mailing-list.md b/docs/content/community/mailing-list.md index 6a9dc813f..cc9debac7 100644 --- a/docs/content/community/mailing-list.md +++ b/docs/content/community/mailing-list.md @@ -5,6 +5,8 @@ weight: 10 menu: main: parent: 'community' +prev: "/extras/urls" +next: "/community/press" --- Hugo has two mailing lists: diff --git a/docs/content/community/press.md b/docs/content/community/press.md index c778e4e9c..207ebd0ab 100644 --- a/docs/content/community/press.md +++ b/docs/content/community/press.md @@ -4,6 +4,8 @@ date = 2014-03-24T20:00:00Z linktitle = "Press" weight = 20 notoc = true +prev = "/community/mailing-list" +next = "/community/contributing" [menu.main] parent = "community" +++ diff --git a/docs/content/content/archetypes.md b/docs/content/content/archetypes.md new file mode 100644 index 000000000..59287db9b --- /dev/null +++ b/docs/content/content/archetypes.md @@ -0,0 +1,76 @@ ++++ +title = "Archetypes" +date = 2014-05-14T02:13:50Z +weight = 50 +prev = "/content/types" +next = "/content/ordering" + +[menu] + [menu.main] + parent = "content" ++++ + +Hugo v0.11 introduced the concept of a content builder. Using the +command: `hugo new [relative new content path]` you can start a content file +with the date and title automatically set. This is a welcome feature, but +active writers need more. + +Hugo presents the concept of archetypes which are archetypal content files. + +## Example archetype + +In this example scenario I have a blog with a single content type (blog post). +I use ‘tags’ and ‘categories’ for my taxonomies. + +### archetypes/default.md + + +++ + tags = ["x", "y"] + categories = ["x", "y"] + +++ + + +## using archetypes + +If I wanted to create a new post in the `posts` section I would run the following command... + +`hugo new posts/my-new-post.md` + +Hugo would create the file with the following contents: + +### contents/posts/my-new-post.md + + +++ + title = "my new post" + date = 2014-05-14T02:13:50Z + tags = ["x", "y"] + categories = ["x", "y"] + +++ + + +## Using a different front matter format + +By default the front matter will be created in the TOML format +regardless of what format the archetype is using. + +You can specify a different default format in your config file using +the `MetaDataFormat` directive. Possible values are `toml`, `yaml` and `json`. + + +## Which archtype is being used + +The following rules apply: + +* If an archetype with a filename that matches the content type being created it will be used. +* If no match is found `archetypes/default.md` will be used. +* If neither are present and a theme is in use then within the theme... + * If an archetype with a filename that matches the content type being created it will be used. + * If no match is found `archetypes/default.md` will be used. +* If no archetype files are present then the one that ships with hugo will be used. + +Hugo provides a simple archetype which sets the title (based on the +file name) and the date based on now(). + +Content type is automatically detected based on the path. You are welcome to declare which +type to create using the `--kind` flag during creation. + diff --git a/docs/content/content/example.md b/docs/content/content/example.md index 2fc070151..fb9421af7 100644 --- a/docs/content/content/example.md +++ b/docs/content/content/example.md @@ -6,8 +6,10 @@ linktitle: "Example" menu: main: parent: 'content' -weight: 50 +weight: 70 notoc: true +prev: '/content/ordering' +next: '/themes/overview' --- Somethings are better shown than explained. The following is a very basic example of a content file: diff --git a/docs/content/content/front-matter.md b/docs/content/content/front-matter.md index e67dafd98..eec83df9b 100644 --- a/docs/content/content/front-matter.md +++ b/docs/content/content/front-matter.md @@ -2,10 +2,13 @@ title = "Front Matter" date = "2013-07-01" aliases = ["/doc/front-matter/"] -weight = 40 +weight = 20 +prev = "/content/organization" +next = "/content/sections" [menu.main] parent = "content" + +++ The front matter is one of the features that gives Hugo its strength. It enables diff --git a/docs/content/content/ordering.md b/docs/content/content/ordering.md index 926a539fd..81fcf0e77 100644 --- a/docs/content/content/ordering.md +++ b/docs/content/content/ordering.md @@ -6,12 +6,16 @@ menu: main: parent: "content" weight: 60 +prev: '/content/archetypes' +next: '/content/example' --- -In Hugo you have a good degree of control of how your content can be ordered. +Hugo provides you with all the flexibility you need to organize how your content is ordered. -By default, content is ordered by weight, then by date with the most recent -date first, but alternative sorting (by title and linktitle) is also available. +By default, content is ordered by weight, then by date with the most +recent date first, but alternative sorting (by title and linktitle) is +also available. The order the content will appear will be specified in +the [list template](/templates/list). _Both the date and weight fields are optional._ @@ -29,71 +33,7 @@ guaranteed. +++ Front Matter with Ordered Pages 3 -## Order by Weight -> Date (default) - {{ range .Data.Pages }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} +## Ordering Content Within Taxonomies -## Order by Weight -> Date - - {{ range .Data.Pages.ByWeight }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -## Order by Date - - {{ range .Data.Pages.ByDate }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -## Order by Length - - {{ range .Data.Pages.ByLength }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -## Reverse Order -Can be applied to any of the above. Using Date for an example. - - {{ range .Data.Pages.ByDate.Reverse }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -## Order by Title - - {{ range .Data.Pages.ByTitle }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - -## Order by LinkTitle - - {{ range .Data.Pages.ByLinkTitle }} -
  • - {{ .LinkTitle }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • - {{ end }} - - -## Ordering Content Within Indexes - -Please see the [Index Ordering Documentation](/indexes/ordering/) +Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/) diff --git a/docs/content/content/organization.md b/docs/content/content/organization.md index 832edc557..8f1544867 100644 --- a/docs/content/content/organization.md +++ b/docs/content/content/organization.md @@ -7,17 +7,21 @@ weight: 10 menu: main: parent: 'content' +prev: '/overview/source-directory' +next: '/content/front-matter' --- -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. +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). + +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 diff --git a/docs/content/content/sections.md b/docs/content/content/sections.md index ea9d75dd4..94bb02894 100644 --- a/docs/content/content/sections.md +++ b/docs/content/content/sections.md @@ -4,8 +4,10 @@ date: "2013-07-01" menu: main: parent: 'content' -weight: 20 +weight: 30 notoc: true +prev: '/content/front-matter' +next: '/content/types' --- Hugo thinks that you organize your content with a purpose. The same structure @@ -26,6 +28,13 @@ The following example site uses two sections, "post" and "quote". ├── first.md // <- http://1.com/quote/first/ └── second.md // <- http://1.com/quote/second/ + +## Section Lists + +Hugo will automatically create pages for each section root that list all +of the content in that section. See [List Templates](/templates/list) +for details on customizing the way they appear. + ## Sections and Types By default everything created within a section will use the content type @@ -40,5 +49,3 @@ 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 index 0448e0267..563e6f7cb 100644 --- a/docs/content/content/types.md +++ b/docs/content/content/types.md @@ -5,40 +5,18 @@ linktitle: "Types" menu: main: parent: 'content' -weight: 30 +weight: 40 +prev: '/content/sections' +next: '/content/archetypes' --- -Hugo has full support for multiple content types each with its own set -of meta data and template. A good example of when multiple types are -needed is to look at Tumblr. A piece of content could be a photo, quote -or post, each with different meta data and rendered differently. +Hugo has full support for different types of content. A content type can have a +unique set of meta data, template and can be automatically created by the new +command through using content [archetypes](/content/archetypes). -## 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 Type Directory -Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*. - -### Step 2: Create template -Create a file called single.html inside your directory. *Eg /layouts/post/single.html*. - -### Step 3: Create list template -Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/indexes/post.html*. - -### Step 4: Create views -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. +A good example of when multiple types are needed is to look at Tumblr. A piece +of content could be a photo, quote or post, each with different meta data and +rendered differently. ## Assigning a content type @@ -48,3 +26,51 @@ 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". + + +## Creating new content of a specific type + +Hugo has the ability to create a new content file and populate the front matter +with the data set corresponding to that type. Hugo does this by utilizing +[archetypes](/content/archetypes). + +To create a new piece of content use: + + hugo new relative/path/to/content.md + +For example if I wanted to create a new post inside the post section I would type: + + hugo new post/my-newest-post.md + + +## Defining a content type + +Creating a new content type is easy in Hugo. You simply provide the templates and archetype +that the new type will use. You only need to define the templates, archetypes and/or views +unique to that content type. Hugo will fall back to using the general templates and default archetype +whenever a specific file is not present. + +*Remember, all of the following are optional:* + +### Create Type Directory +Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*. + +### Create single template +Create a file called single.html inside your directory. *Eg /layouts/post/single.html*. + +### Create list template +Create a file called list.html inside your directory *Eg /layouts/post/list.html*. + +### Create views +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. + +### Create a corresponding archetype + +Create a file called `type`.md in the /archetypes directory *Eg /archetypes/post.md*. + +More details about archetypes can be found at the [archetypes docs](/content/archetypes) diff --git a/docs/content/extras/aliases.md b/docs/content/extras/aliases.md index c2d6eb01c..122e9981c 100644 --- a/docs/content/extras/aliases.md +++ b/docs/content/extras/aliases.md @@ -5,10 +5,12 @@ aliases: - /doc/redirects/ - /doc/alias/ - /doc/aliases/ -weight: 20 +weight: 10 menu: main: parent: 'extras' +prev: "/taxonomies/ordering" +next: "/extras/builders" --- For people migrating existing published content to Hugo theres a good chance diff --git a/docs/content/extras/builders.md b/docs/content/extras/builders.md new file mode 100644 index 000000000..4fdae9418 --- /dev/null +++ b/docs/content/extras/builders.md @@ -0,0 +1,60 @@ +--- +title: "Hugo Builders" +linktitle: "Builders" +date: "2014-05-26" +weight: 12 +menu: + main: + parent: 'extras' +prev: "/extras/aliases" +next: "/extras/comments" +--- + +Hugo provides the functionality to quickly get a site, theme or page +started. + + +## New Site + +Want to get a site built quickly?. + + hugo new site /path/to/site + +Hugo will create all the needed directories and files to get started +quickly. + +Hugo will only touch the files and create the directories (in the right +places), [configuration](/overview/configuration) and content are up to +you... but luckily we have builders for content (see below). + +## New Theme + +Want to design a new theme? + + hugo new theme `THEME_NAME` + +Run from your working directory, this will create a new theme with all +the needed files in your themes directory. Hugo will provide you with a +license and theme.toml file with most of the work done for you. + +Follow the [Theme Creation Guide](/themes/creation) once the builder is +done. + +## New Content + +You will use this builder the most of all. Every time you want to create +a new piece of content, the content builder will get you started right. + +Leveraging [content archetypes](/content/archetypes) the content builder +will not only insert the current date and appropriate metadata, but it +will pre-populate values based on the content type. + + hugo new relative/path/to/content + +This assumes it is being run from your working directory and the content +path starts from your content directory. + +I typically keep two different terminals open, one to run `hugo server +--watch`, and another to use the builders to create new content. + + diff --git a/docs/content/extras/comments.md b/docs/content/extras/comments.md new file mode 100644 index 000000000..3ff95134b --- /dev/null +++ b/docs/content/extras/comments.md @@ -0,0 +1,67 @@ +--- +title: "Comments in Hugo" +linktitle: "Comments" +date: "2014-05-26" +weight: 14 +menu: + main: + parent: 'extras' +prev: "/extras/builders" +next: "/extras/livereload" +--- + +As Hugo is a static site generator, the content produced is static and +doesn’t interact with the users. The most common interaction people ask +for is comment capability. + +Hugo ships with support for [disqus](http://disqus.com), a third party +service that provides comment and community capabilities to website via +javascript. + +Your theme may already support disqus, but even it if doesn’t it is easy +to add. + +# Disqus Support + +## Adding Disqus to a template + +Hugo comes with all the code you would need to include load disqus. +Simply include the following line where you want your comments to appear + + {{ template "_internal/disqus.html" . }} + + +## Configuring Disqus + +That template requires you to set a single value in your site config file, eg. config.yaml. + + disqusShortname = "XYW" + +Additionally you can optionally set the following in the front matter +for a given piece of content + + * **disqus_identifier** + * **disqus_title** + * **disqus_url** + +# Alternatives + +A few alternatives exist to Disqus. + +* [Intense Debate](http://intensedebate.com/) +* [LiveFyre](http://livefyre.com/) +* [Moot](http://muut.com) +* [Kaiju](http://github.com/spf13/kaiju) + + +[Kaiju](http://github.com/spf13/kaiju) is a open source project started +by [spf13](http://spf13.com) (Hugo’s author) to bring easy and fast real +time discussions to the web. + +Written using Go, Socket.io and MongoDB it is very fast and easy to +deploy. + +It is in early development but shows promise.. If you have interest +please help by contributing whether via a pull request, an issue or even +just a tweet. Everything helps. + diff --git a/docs/content/extras/highlighting.md b/docs/content/extras/highlighting.md index 6183ee429..de9812d00 100644 --- a/docs/content/extras/highlighting.md +++ b/docs/content/extras/highlighting.md @@ -1,10 +1,12 @@ --- -title: "Highlighting" +title: "Syntax Highlighting" date: "2013-07-01" -weight: 15 +weight: 50 menu: main: parent: 'extras' +prev: "/extras/shortcodes" +next: "/extras/toc" --- Hugo provides the ability for you to highlight source code in two different diff --git a/docs/content/extras/livereload.md b/docs/content/extras/livereload.md new file mode 100644 index 000000000..ee2a586b7 --- /dev/null +++ b/docs/content/extras/livereload.md @@ -0,0 +1,61 @@ +--- +title: "Live Reload" +date: "2014-05-26" +weight: 15 +menu: + main: + parent: 'extras' +prev: "/extras/comments" +next: "/extras/menus" +--- + +Hugo may not be the first static site generator to utilize live reload +technology, but it’s the first to do it right. + +The combination of Hugo’s insane build speed and live reload make +crafting your content pure joy. Virtually instantly after you hit save +your rebuilt content will appear in your browser. + +## Using livereload + +Hugo comes with livereload built in. There are no additional packages to +install. A common way to use hugo while developing a site is to have +hugo run a server and watch for changes. + + hugo server --watch + +This will run a full functioning web server while simultaneously +watching your file system for additions, deletions or changes within +your: + + * static files + * content + * layouts + * current theme + +Whenever anything changes Hugo will rebuild the site, continue to serve +the content and as soon as the build is finished it will tell the +browser and silently reload the page. Because most hugo builds are so +fast they are barely noticeable, you merely need to glance at your open +browser and you will see the change already there. + +This means that keeping the site open on a second monitor (or another +half of your current monitor), allows you to see exactly what your +content looks like without even leaving your text editor. + +## Disabling livereload + +Live reload accomplishes this by injecting javascript into the pages it +creates that creates a web socket client to the hugo web socket server. + +Awesome for development, but not something you would want to do in +production. Since many people use `hugo server --watch` in production to +instantly display any updated content, we’ve made it easy to disable the +live reload functionality. + + hugo server --watch --disableLiveReload + + + + + diff --git a/docs/content/extras/menus.md b/docs/content/extras/menus.md new file mode 100644 index 000000000..070729c00 --- /dev/null +++ b/docs/content/extras/menus.md @@ -0,0 +1,162 @@ ++++ +title = "Menus" +weight = 20 +prev = "/extras/livereload" +next = "/extras/permalinks" +date = 2014-05-14T02:36:37Z +[menu] + [menu.main] + parent = "extras" ++++ + +Hugo has a simple yet powerful menu system that permits content to be +placed in menus with a good degree of control without a lot of work. + +Some of the features of Hugo Menus: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a menu? + +A menus is a named array of menu entries accessible on the site under +.Site.Menus by name. For example if I have a menu called `main` I would +access it via .Site.Menus.main. + +A menu entry has the following properties: + +* **Url** string +* **Name** string +* **Menu** string +* **Identifier** string +* **Pre** template.HTML +* **Post** template.HTML +* **Weight** int +* **Parent** string +* **Children** Menu + + +Additionally there are some relevant functions available on the page: + + * **HasChildren** bool + * **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool + * **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool + + +## Adding content to menus + +Hugo supports a couple of different methods of adding a piece of content +to the front matter. + +### Simple + +If all you need to do is add an entry to a menu, the simple form works +well. + +**A single menu:** + + --- + menu: "main" + --- + +**Multiple menus:** + + --- + menu: ["main", "footer"] + --- + + +### Advanced + +If more control is required, then the advanced approach gives you the +control you want. All of the menu entry properties listed above are +available. + + --- + menu: + main: + parent: 'extras' + weight: 20 + --- + + +## Adding (non-content) entries to a menu + +You can also add entries to menus that aren’t attached to a piece of +content. This takes place in the site wide config file. + +Here’s an example (in toml): + + [[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" + [[menu.main]] + name = "getting started" + pre = "" + weight = -100 + +## Nesting + +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. +Identifier should be unique (within a menu). + +The following order is used to determine identity Identifier > Name > +LinkTitle > Title. This means that the title will be used unless +linktitle is present, etc. In practice Name and Identifier are never +displayed and only used to structure relationships. + +In this example, the top level of the menu is defined in the config file +and all content entries are attached to one of these entries via the +`parent` field. + +## Rendering menus + +Hugo makes no assumptions about how your rendered HTML will be +structured, instead it provides all of the functions you will need to be +able to build your menu however you want. + + +The following is an example: + + + + diff --git a/docs/content/extras/permalinks.md b/docs/content/extras/permalinks.md index e36fb9d30..6282e61c6 100644 --- a/docs/content/extras/permalinks.md +++ b/docs/content/extras/permalinks.md @@ -8,6 +8,8 @@ notoc: true menu: main: parent: 'extras' +prev: "/extras/menus" +next: "/extras/shortcodes" --- By default, content is laid out into the target `publishdir` (public) diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md index a72b4b535..a9b2a31ca 100644 --- a/docs/content/extras/shortcodes.md +++ b/docs/content/extras/shortcodes.md @@ -2,10 +2,12 @@ title: "Shortcodes" date: "2013-07-01" aliases: ["/doc/shortcodes/"] -weight: 10 +weight: 40 menu: main: parent: 'extras' +prev: "/extras/permalinks" +next: "/extras/highlighting" --- Because Hugo uses markdown for its simple content format, however there's a lot diff --git a/docs/content/extras/toc.md b/docs/content/extras/toc.md index bac221c68..f91511c2a 100644 --- a/docs/content/extras/toc.md +++ b/docs/content/extras/toc.md @@ -1,10 +1,12 @@ --- title: "Table of Contents" date: "2013-07-09" -weight: 70 +weight: 60 menu: main: parent: 'extras' +prev: "/extras/highlighting" +next: "/extras/urls" --- Hugo will automatically parse the markdown for your content and create @@ -24,12 +26,12 @@ Hugo will take this markdown and create a table of contents stored in the This is example code of a [single.html template](/layout/content). - {{ template "chrome/header.html" . }} + {{ template "partials/header.html" . }}
    {{ .TableOfContents }}

    {{ .Title }}

    {{ .Content }} - {{ template "chrome/footer.html" . }} + {{ template "partials/footer.html" . }} diff --git a/docs/content/extras/urls.md b/docs/content/extras/urls.md index 043b472d1..123bc87d7 100644 --- a/docs/content/extras/urls.md +++ b/docs/content/extras/urls.md @@ -3,11 +3,13 @@ title: "URLs" date: "2014-01-03" aliases: - "/doc/urls/" -weight: 40 +weight: 70 notoc: true menu: main: parent: 'extras' +prev: "/extras/toc" +next: "/community/mailing-list" --- ## Pretty Urls @@ -16,7 +18,7 @@ By default Hugo will create content with 'pretty' urls. For example content created at /content/extras/urls.md will be rendered at /content/extras/urls/index.html and accessible at /content/extras/urls. No no standard server side configuration is required for these pretty urls to -work. +work. If you would like to have uglyurls you are in luck. Hugo supports the ability to create your entire site with ugly urls. Simply use the diff --git a/docs/content/layout/homepage.md b/docs/content/layout/homepage.md deleted file mode 100644 index 175aef293..000000000 --- a/docs/content/layout/homepage.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Homepage Templates" -date: "2013-07-01" -weight: 30 -notoc: true -menu: - main: - parent: 'layout' ---- - -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 . Details on how to use this -list of pages can be found in [Lists](/indexes/lists/) - - - ▾ 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) and uses a [List](/indexes/lists/) - - - - - - - {{ template "chrome/meta.html" . }} - - - {{ .Site.Title }} - - - - {{ template "chrome/head_includes.html" . }} - - - - {{ template "chrome/subheader.html" . }} - -
    -
    - {{ range first 10 .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    - - {{ template "chrome/footer.html" }} diff --git a/docs/content/layout/indexes.md b/docs/content/layout/indexes.md deleted file mode 100644 index 36f2330f6..000000000 --- a/docs/content/layout/indexes.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Index Templates" -date: "2013-07-01" -weight: 50 -menu: - main: - parent: 'layout' ---- - -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 its 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 deleted file mode 100644 index fa15a60d4..000000000 --- a/docs/content/layout/rss.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "RSS (feed) Templates" -date: "2013-07-01" -weight: 40 -notoc: "one" -menu: - main: - parent: 'layout' ---- - -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 deleted file mode 100644 index ccfe908a3..000000000 --- a/docs/content/layout/templates.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Hugo Templates" -date: "2013-07-01" -aliases: ["/doc/templates/"] -linktitle: "Overview" -weight: 10 -menu: - main: - parent: 'layout' ---- - -Hugo uses the excellent go html/template library for its 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 - -### [Index](/layout/indexes) -Page that list multiple pieces of content - -### [Content](/layout/content) -Render a single piece of content - -### [Views](/layout/views) -Different view of a single piece of content type - -### [Chrome](/layout/chrome) -Support for the above templates diff --git a/docs/content/layout/views.md b/docs/content/layout/views.md deleted file mode 100644 index 22b4e9568..000000000 --- a/docs/content/layout/views.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Content Views" -date: "2013-07-01" -weight: 70 -menu: - main: - parent: 'layout' ---- - -In addition to the [single content view](/layout/content/), Hugo can render alternative views of -your content. These are especially useful in [index](/layout/indexes) 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/meta/license.md b/docs/content/meta/license.md index e1aceacbd..41372c13c 100644 --- a/docs/content/meta/license.md +++ b/docs/content/meta/license.md @@ -1,11 +1,11 @@ --- title: "License" date: "2013-07-01" -aliases: ["/doc/license/", "/license/"] +aliases: ["/doc/license/", "/license/", "/meta/license/"] weight: 50 menu: - right: - parent: 'meta' + main: + parent: 'about' --- Hugo is released under the Simple Public License. diff --git a/docs/content/meta/release-notes.md b/docs/content/meta/release-notes.md index bd8fe1ade..5a15495b4 100644 --- a/docs/content/meta/release-notes.md +++ b/docs/content/meta/release-notes.md @@ -1,12 +1,30 @@ --- title: "Release Notes" date: "2013-07-01" -aliases: ["/doc/release-notes/"] +aliases: ["/doc/release-notes/", "/meta/release-notes/"] weight: 10 menu: - right: - parent: 'meta' + main: + parent: 'about' --- + +## **0.11.0** May 27, 2014 + * Considerably faster... about 3 - 4x faster on average + * Live Reload... Hugo will automatically reload the browser when the build is complete + * Theme engine w/[Theme Repository](http://github.com/spf13/hugoThemes) + * Menu system with support for active page + * Builders to quickly create a new site, content or theme + * XML sitemap generation + * Integrated Disqus support + * Streamlined template organization + * Brand new docs site + * More sort options + * Logging support + * Much better error handling + * More informative verbose output + * Renamed Indexes > Taxonomies + * Renamed Chrome > Partials + ## **0.10.0** March 1, 2014 * [Syntax highlighting](/extras/highlighting) powered by pygments (**slow**) * Ability to [sort content](/content/ordering) many more ways diff --git a/docs/content/meta/roadmap.md b/docs/content/meta/roadmap.md index ddc3ba179..d60290f11 100644 --- a/docs/content/meta/roadmap.md +++ b/docs/content/meta/roadmap.md @@ -1,27 +1,23 @@ --- -title: "Roadmap" +title: "Hugo Roadmap" date: "2013-07-01" -aliases: ["/doc/roadmap/"] -groups: ["meta"] -groups_weight: 20 +aliases: ["/doc/roadmap/","/meta/roadmap/"] +weight: 20 notoc: true menu: - right: - parent: 'meta' + main: + parent: 'about' --- In no particular order, here is what we are working on: - * Pagination - * Better error handling - * Related Posts - * Support for other formats - * Full theming support - * Ability to automatically import from other website systems (wordpress, jekyll) - * Ship with a few default themes + * Intelligently Related Posts + * Even easier deployment to S3, SSH, Github, rsync + * Import from other website systems (wordpress, jekyll) * An interactive web based editor - * Easy deployment to S3, SSH, Github, rsync - * Live preview (auto refresh in browser) + * Additional Themes * Dynamic image resizing via shortcodes - + * Support for additional formats + * Pagination + * Your best ideas diff --git a/docs/content/overview/configuration.md b/docs/content/overview/configuration.md index 27eb2098b..799e3746e 100644 --- a/docs/content/overview/configuration.md +++ b/docs/content/overview/configuration.md @@ -8,50 +8,30 @@ notoc: true menu: main: parent: 'getting started' +prev: '/overview/usage' +next: '/overview/source-directory' --- 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. +websites since the defaults follow commonly used patterns. Hugo expects to find the config file in the root of the source directory and -will look there first for a `config.yaml` file. If none is present it will -then look for a `config.json` file, followed by a `config.toml` file. +will look there first for a `config.toml` file. If none is present it will +then look for a `config.yaml` file, followed by a `config.json` file. -**Please note the field names must be all lowercase** +The config file is a site-wide config. The config file provides directions to +hugo on how to build the site as well as site-wide parameters and menus. ## Examples -The following is an example of a yaml config file with the default values: +The following is an example of a typical yaml config file: --- - contentdir: "content" - layoutdir: "layouts" - publishdir: "public" - builddrafts: false - indexes: - category: "categories" - tag: "tags" baseurl: "http://yoursite.example.com/" - canonifyurls: true ... -The following is an example of a json config file with the default values: - - { - "contentdir": "content", - "layoutdir": "layouts", - "publishdir": "public", - "builddrafts": false, - "indexes": { - "category": "categories", - "tag": "tags" - }, - "baseurl": "http://yoursite.example.com/", - "canonifyurls": true - } - -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 some of the default values: contentdir = "content" layoutdir = "layouts" @@ -79,3 +59,4 @@ Here is a yaml configuration file which sets a few more options - "foo2" SidebarRecentLimit: 5 ... + diff --git a/docs/content/overview/installing.md b/docs/content/overview/installing.md index dcf7d7ba7..69d55425f 100644 --- a/docs/content/overview/installing.md +++ b/docs/content/overview/installing.md @@ -6,6 +6,10 @@ weight: 20 menu: main: parent: 'getting started' + +prev: '/overview/quickstart' +next: '/overview/usage' + --- Hugo is written in Go with support for Windows, Linux, FreeBSD and OSX. @@ -25,13 +29,19 @@ where you don't have a privileged account. Ideally you should install it somewhere in your path for easy use. `/usr/local/bin` is the most probable location. -The Hugo executable has one *optional* external dependency for source code highlighting (pygments). +### Installing pygments (optional) -### Installing pygments +The Hugo executable has one *optional* external dependency for source code highlighting (pygments). If you want to have source code highlighting using the [highlight shortcode](/extras/highlighting) you need to install the python-based pygments program. The procedure is outlined on the [pygments home page](http://pygments.org). +## Upgrading Hugo + +Upgrading hugo is as easy as downloading and replacing the executable you’ve +placed in your path. + + ## Installing from source ### Dependencies diff --git a/docs/content/overview/introduction.md b/docs/content/overview/introduction.md index 08185fada..eaea859f0 100644 --- a/docs/content/overview/introduction.md +++ b/docs/content/overview/introduction.md @@ -6,6 +6,7 @@ weight: 5 menu: main: parent: 'getting started' +next: '/overview/quickstart' --- ## What is Hugo? @@ -36,41 +37,53 @@ templates and uses these as input to create a complete website. Hugo boasts the following features: +### General + * Extremely fast built times (~1ms per page) - * Runs on Mac OSX, Linux and Windows - * Content written in [Markdown](/content/example) + * Completely cross platform: Runs on Mac OSX, Linux and Windows * Easy [installation](/overview/installing) - * Straightforward website [organization](/content/organization) - * Completely [customizable homepage](/layout/homepage) - * Support for multiple [content types](/content/types) - * Support for [website sections](/content/sections) - * Completely customizable [urls](/extras/urls) - * Render changes [on the fly](/overview/usage) as you develop + * Render changes [on the fly](/overview/usage) with [live reload](#) as you develop + * Complete theme support * Host your site anywhere - * Support for disqus comments - * Dynamic menu creation - * Support for TOML, YAML and JSON metadata in [frontmatter](/content/front-matter) - * [permalink](/extras/permalinks) pattern support - * [pretty urls](/extras/urls) support - * [shortcodes](/extras/shortcodes) - * [Aliases](/extras/aliases) (redirects) - * Automatic [RSS](/layout/rss) creation - * Support for go and amber templates + +### Organization + + * Straightforward [organization](/content/organization) + * Support for [website sections](/content/sections) + * Completely customizable [urls](/extras/urls) * Support for [categories](/indexes/category) and tags - * Support for configurable [indexes](/indexes/overview) to create your own organization - * Syntax [highlighting](/extras/highlighting) powered by pygments + * Support for configurable [taxonomies](/indexes/overview) to create your own organization * Ability to [sort content](/content/ordering) as you desire * Automatic [table of contents](/extras/toc) generation + * Dynamic menu creation + * [pretty urls](/extras/urls) support + * [permalink](/extras/permalinks) pattern support + * [Aliases](/extras/aliases) (redirects) + +### Content + + * Content written in [Markdown](/content/example) + * Support for TOML, YAML and JSON metadata in [frontmatter](/content/front-matter) + * Completely [customizable homepage](/layout/homepage) + * Support for multiple [content types](/content/types) * Automatic and user defined [summaries](/content/summaries) + * [shortcodes](/extras/shortcodes) to enable rich content inside of markdown * ["Minutes to Read"](/layout/variables) functionality * ["Wordcount"](/layout/variables) functionality +### Additional Features + + * Integrated Disqus comment support + * Automatic [RSS](/layout/rss) creation + * Support for go and amber templates + * Syntax [highlighting](/extras/highlighting) powered by pygments + See what's coming next in the [roadmap](/meta/roadmap) ## Who should use Hugo? Hugo is for people that prefer writing in a text editor over -a browser. +a browser. Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and diff --git a/docs/content/overview/quickstart.md b/docs/content/overview/quickstart.md index 26e41b47a..68d5fb441 100644 --- a/docs/content/overview/quickstart.md +++ b/docs/content/overview/quickstart.md @@ -6,8 +6,14 @@ weight: 10 menu: main: parent: 'getting started' +prev: '/overview/introduction' +next: '/overview/installing' --- +_This quickstart depends on features introduced in hugo v0.11. If you +have an earlier version of hugo you will need to [upgrade](/overview/installing/) before +proceeding._ + ## Step 1. Install Hugo Goto [hugo releases](https://github.com/spf13/hugo/releases) and download the @@ -17,67 +23,128 @@ Save it somewhere specific as we will be using it in the next step. More complete instructions are available at [installing hugo](/overview/installing/) -## Step 2. Build the Docs +## Step 2. Have Hugo Create a site for you -Hugo has its own example site which happens to also be the documentation site -you are reading right now. +Hugo has the ability to create a skeleton site. -Follow the following steps: + hugo new site /path/to/site - 1. Clone the [hugo repository](http://github.com/spf13/hugo) - 2. Go into the repo - 3. Run hugo in server mode and build the docs - 4. Open your browser to http://localhost:1313 +For the rest of the operations we will be executing all commands from within the site directory -Corresponding pseudo commands: + cd /path/to/site - git clone https://github.com/spf13/hugo - cd hugo - /path/to/where/you/installed/hugo server --source=./docs - > 29 pages created - > 0 tags index created - > in 27 ms - > Web Server is available at http://localhost:1313 - > Press ctrl+c to stop +The new site will have the following structure -Once you've gotten here, follow along the rest of this page on your local build. + ▸ archetypes/ + ▸ content/ + ▸ layouts/ + ▸ static/ + config.toml -## Step 3. Change the docs site +Currently the site doesn’t have any content, nor is it configured. -Stop the Hugo process by hitting ctrl+c. +## Step 3. Create Some Content -Now we are going to run hugo again, but this time with hugo in watch mode. +Hugo also has the ability to create content for you. - /path/to/hugo/from/step/1/hugo server --source=./docs --watch - > 29 pages created - > 0 tags index created - > in 27 ms - > Web Server is available at http://localhost:1313 - > Watching for changes in /Users/spf13/Code/hugo/docs/content - > Press ctrl+c to stop + hugo new about.md + +A new file is now created in `content/` with the following contents + + +++ + draft = true + title = "about" + date = 2014-05-20T10:04:31Z + +++ + +Notice the date is automatically set to the moment you created the content. + +Place some content in this file below the `+++` in the markdown format. + +For example you could put this + + ## A headline + + Some Content + +For fun, let’s create another piece of content and place some markdown in it as well. + + hugo new post/first.md + +The new file is located at `content/post/first.md` + +We still lack any templates to tell us how to display the content. + +## Step 4. Install some themes + + Hugo has rich theme support and a growing set of themes to choose from. + + git clone --recursive https://github.com/spf13/hugoThemes themes -Open your [favorite editor](http://vim.spf13.com) and change one of the source -content pages. How about changing this very file to *fix the typo*. How about changing this very file to *fix the typo*. +## Step 5. Run Hugo + +Hugo contains it’s own high performance web server. Simply run `hugo +server` and Hugo will find an available port and run a server with +your content + + hugo server --theme=hyde --buildDrafts + 2 pages created + 0 tags created + 0 categories created + in 5 ms + Serving pages from exampleHugoSite/public + Web Server is available at http://localhost:1313 + Press ctrl+c to stop + +We specified two options here. + * --theme to pick which theme. + * --buildDrafts because we want to display our content, both set to draft status + +To learn about what other options hugo has run + + hugo help + +To learn about the server options + + hugo help server + +## Step 6. Edit Content + +Not only can Hugo run a server, but it can also watch your files for +changes and automatically rebuild your site. Hugo will then +communicate with your browser and automatically reload any open page. +This even works in mobile browsers. + +Stop the Hugo process by hitting ctrl+c. Then run the following: + + hugo server --theme=hyde --buildDrafts --watch + 2 pages created + 0 tags created + 0 categories created + in 5 ms + Watching for changes in exampleHugoSite/content + Serving pages from exampleHugoSite/public + Web Server is available at http://localhost:1313 + Press ctrl+c to stop +Open your [favorite editor](http://vim.spf13.com), edit and save your content and watch as Hugo rebuilds and reloads automatically. + +It’s especially productive to leave a browser open on a second monitor +and just glance at it whenever you save. You don’t even need to tab to +your browser. Hugo is so fast, that the new site will be there before +you can look at the browser in most cases. -Content files are found in `docs/content/`. Unless otherwise specified, files -are located at the same relative location as the url, in our case -`docs/content/overview/quickstart.md`. Change and save this file.. Notice what happened in your terminal. - > Change detected, rebuilding site + Change detected, rebuilding site - > 29 pages created - > 0 tags index created - > in 26 ms + 2 pages created + 0 tags created + 0 categories created + in 5 ms -Refresh the browser and observe that the typo is now fixed. - -Notice how quick that was. Try to refresh the site before it's finished building.. I double dare you. -Having nearly instant feedback enables you to have your creativity flow without waiting for long builds. - -## Step 4. Have fun +## Step 7. Have fun The best way to learn something is to play with it. diff --git a/docs/content/overview/source-directory.md b/docs/content/overview/source-directory.md index 54fb8272c..2731afd15 100644 --- a/docs/content/overview/source-directory.md +++ b/docs/content/overview/source-directory.md @@ -1,5 +1,5 @@ --- -title: "Source Directory Organization" +title: "Source Organization" date: "2013-07-01" aliases: ["/doc/source-directory/"] weight: 50 @@ -7,18 +7,41 @@ notoc: true menu: main: parent: 'getting started' +prev: '/overview/configuration' +next: '/content/organization' --- -Hugo takes a single directory and uses it as the input for creating a complete website. +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. + +The top level of a source directory will typically have the following elements: + + ▸ archetypes/ + ▸ content/ + ▸ layouts/ + ▸ static/ + ▸ themes/ + config.toml + +Learn more about the different directories and what their purpose is + +* [config](/overview/configuration) +* [archetypes](/content/archetypes) +* [content](/content/organization) +* [layouts](/layout/overview) +* [static]() +* [themes](/themes/overview) + + +## Example An example directory may look like: . - ├── config.yaml + ├── config.toml + ├── archetypes + | └── default.md ├── content | ├── post | | ├── firstpost.md @@ -27,10 +50,13 @@ An example directory may look like: | | ├── first.md | | └── second.md ├── layouts - | ├── chrome + | ├── _default + | | ├── single.html + | | └── list.html + | ├── partials | | ├── header.html | | └── footer.html - | ├── indexes + | ├── taxonomies | | ├── category.html | | ├── post.html | | ├── quote.html @@ -48,14 +74,16 @@ An example directory may look like: | | ├── vimeo.html | | └── youtube.html | ├── index.html - | ├── rss.xml | └── sitemap.xml + ├── themes + | ├── hyde + | └── doc └── static + ├── css + └── js 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 this example site ready to be rendered. diff --git a/docs/content/overview/usage.md b/docs/content/overview/usage.md index 4405f68d1..52a09b2dc 100644 --- a/docs/content/overview/usage.md +++ b/docs/content/overview/usage.md @@ -7,10 +7,14 @@ notoc: true menu: main: parent: 'getting started' +prev: '/overview/installing' +next: '/overview/configuration' --- Make sure either hugo is in your path or provide a path to it. + + $ hugo help A Fast and Flexible Static Site Generator built with love by spf13 and friends in Go. @@ -22,23 +26,28 @@ Make sure either hugo is in your path or provide a path to it. hugo [command] Available Commands: - server :: Hugo runs it's own a webserver to render the files - version :: Print the version number of Hugo - check :: Check content in the source directory - benchmark :: Benchmark hugo by building a site a number of times - help [command] :: Help about any command + server :: Hugo runs it's own a webserver to render the files + version :: Print the version number of Hugo + check :: Check content in the source directory + benchmark :: Benchmark hugo by building a site a number of times + new [path] :: Create new content for your site + help [command] :: Help about any command Available Flags: - -b, --base-url="": hostname (and path) to the root eg. http://spf13.com/ - -D, --build-drafts=false: include content marked as draft + -b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/ + -D, --buildDrafts=false: include content marked as draft --config="": config file (default is path/config.yaml|json|toml) -d, --destination="": filesystem path to write files to + --disableRSS=false: Do not build RSS files + --disableSitemap=false: Do not build Sitemap file --log=false: Enable Logging - --logfile="": Log File path (if set, logging enabled automatically) + --logFile="": Log File path (if set, logging enabled automatically) -s, --source="": filesystem path to read files relative from - --uglyurls=false: if true, use /filename.html instead of /filename/ + --stepAnalysis=false: display memory and timing of different steps of the program + -t, --theme="": theme to use (located in /themes/THEMENAME/) + --uglyUrls=false: if true, use /filename.html instead of /filename/ -v, --verbose=false: verbose output - --verboselog=false: verbose logging + --verboseLog=false: verbose logging -w, --watch=false: watch filesystem for changes and recreate as needed Use "hugo help [command]" for more information about that command. @@ -48,26 +57,25 @@ Make sure either hugo is in your path or provide a path to it. The most common use is probably to run hugo with your current 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. **It will -recreate the site faster than you can tab over to -your browser to view the changes.** +immediately, tell Hugo to watch for changes. + +Hugo will watch the filesystem for changes, rebuild your site as soon as a file +is saved. $ hugo -s ~/mysite --watch 28 pages created - 0 tags index created in 18 ms Watching for changes in /Users/spf13/Code/hugo/docs/content Press ctrl+c to stop -Hugo can even run a server and create your site at the same time! +Hugo can even run a server and create your site at the same time! Hugo +implements live reload technology to automatically reload any open pages in +all browsers (including mobile). $ hugo server -ws ~/mysite Watching for changes in /Users/spf13/Code/hugo/docs/content diff --git a/docs/content/taxonomies/category.md b/docs/content/taxonomies/category.md deleted file mode 100644 index 11d8cbdf0..000000000 --- a/docs/content/taxonomies/category.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Example Index - Category" -date: "2013-07-01" -linktitle: "Example - Categories" -aliases: ["/extras/indexes/category"] -groups: ["indexes"] -groups_weight: 60 ---- - -This page demonstrates what would be required to add a new index called "categories" to 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", - "Go", - "Blogging" - ], - "slug": "hugo" - } - diff --git a/docs/content/taxonomies/displaying.md b/docs/content/taxonomies/displaying.md index d43020b3a..118fc8f23 100644 --- a/docs/content/taxonomies/displaying.md +++ b/docs/content/taxonomies/displaying.md @@ -1,5 +1,5 @@ --- -title: "Rendering Taxonomies" +title: "Displaying Taxonomies" date: "2013-07-01" linktitle: "Displaying" aliases: ["/indexes/displaying/"] @@ -7,15 +7,27 @@ weight: 20 menu: main: parent: 'taxonomy' +prev: "/taxonomies/usage" +next: "/taxonomies/templates" --- -## Rendering index values assigned to this content +There are four common ways you can display the data in your +taxonomies in addition to the automatic taxonomy pages created by hugo +using the [list templates](/templates/list). + +1. For a given piece of content you can list the terms attached +2. For a given piece of content you can list other content with the same + term +3. You can list all terms for a taxonomy +4. You can list all taxonomies (with their terms) + +## 1. Displaying taxonomy terms assigned to this content Within your content templates you may wish to display -the indexes that that piece of content is assigned to. +the taxonomies that that piece of content is assigned to. Because we are leveraging the front matter system to -define indexes for content, the indexes assigned to +define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (.Params.`plural`) @@ -27,9 +39,47 @@ each content piece are located in the usual place {{ end }} -## Rendering a Site's Indexes +## 2. Listing content with the same taxonomy term -If you wish to display the list of all keys for an index you can find retrieve +First you may be asking why you would use this. If you are using a +taxonomy for something like a series of posts, this is exactly how you +would do it. It’s also an quick and dirty way to show some related +content. + + +### Example + + + +## 3. Listing all content in a given taxonomy + +This would be very useful in a sidebar as “featured content”. You could +even have different sections of “featured content” by assigning +different terms to the content. + +### Example + + + + +## 4. Rendering a Site's Taxonomies + +If you wish to display the list of all keys for an taxonomy you can find retrieve them from the `.Site` variable which is available on every page. This may take the form of a tag cloud, a menu or simply a list. @@ -39,32 +89,20 @@ The following example displays all tag keys: ### Example -## Creating a menu based on indexes +### Complete Example +This example will list all taxonomies, each of their keys and all the content assigned to each key. -Hugo can generate menus based on indexes by iterating and -nesting the index keys. This can be used to build a hierarchy -of content within your site. - -To have hugo create the menu, simply create a template in chrome -called menu.html, then include it using the -`{{ template "chrome/menu.html" . }}` syntax. - - - -### Example complete menu.html file -This example will list all indexes, each of their keys and all the content assigned to each key. - -