Permalink
Browse files

Updating / Rewriting / Adding all of the documentation in preparation…

… for the next release
  • Loading branch information...
spf13 committed May 27, 2014
1 parent aeb06c7 commit a87f171bd4446773e05198427e920571af63e650
Showing with 2,097 additions and 987 deletions.
  1. +21 −2 docs/config.toml
  2. +7 −2 docs/content/community/contributing.md
  3. +2 −1 docs/content/community/contributors.md
  4. +2 −0 docs/content/community/mailing-list.md
  5. +2 −0 docs/content/community/press.md
  6. +76 −0 docs/content/content/archetypes.md
  7. +3 −1 docs/content/content/example.md
  8. +4 −1 docs/content/content/front-matter.md
  9. +9 −69 docs/content/content/ordering.md
  10. +11 −7 docs/content/content/organization.md
  11. +10 −3 docs/content/content/sections.md
  12. +48 −22 docs/content/content/types.md
  13. +3 −1 docs/content/extras/aliases.md
  14. +60 −0 docs/content/extras/builders.md
  15. +67 −0 docs/content/extras/comments.md
  16. +4 −2 docs/content/extras/highlighting.md
  17. +61 −0 docs/content/extras/livereload.md
  18. +162 −0 docs/content/extras/menus.md
  19. +2 −0 docs/content/extras/permalinks.md
  20. +3 −1 docs/content/extras/shortcodes.md
  21. +5 −3 docs/content/extras/toc.md
  22. +4 −2 docs/content/extras/urls.md
  23. +0 −57 docs/content/layout/homepage.md
  24. +0 −125 docs/content/layout/indexes.md
  25. +0 −51 docs/content/layout/rss.md
  26. +0 −40 docs/content/layout/templates.md
  27. +0 −83 docs/content/layout/views.md
  28. +3 −3 docs/content/meta/license.md
  29. +21 −3 docs/content/meta/release-notes.md
  30. +12 −16 docs/content/meta/roadmap.md
  31. +10 −29 docs/content/overview/configuration.md
  32. +12 −2 docs/content/overview/installing.md
  33. +33 −20 docs/content/overview/introduction.md
  34. +109 −42 docs/content/overview/quickstart.md
  35. +39 −11 docs/content/overview/source-directory.md
  36. +26 −18 docs/content/overview/usage.md
  37. +0 −57 docs/content/taxonomies/category.md
  38. +64 −58 docs/content/taxonomies/displaying.md
  39. +0 −74 docs/content/taxonomies/lists.md
  40. +18 −16 docs/content/taxonomies/ordering.md
  41. +78 −65 docs/content/taxonomies/overview.md
  42. +9 −41 docs/content/taxonomies/templates.md
  43. +60 −0 docs/content/taxonomies/usage.md
  44. +5 −0 docs/content/{layout → templates}/404.md
  45. +54 −26 docs/content/{layout → templates}/content.md
  46. +6 −3 docs/content/{layout → templates}/functions.md
  47. +4 −1 docs/content/{layout → templates}/go-templates.md
  48. +77 −0 docs/content/templates/homepage.md
  49. +216 −0 docs/content/templates/list.md
  50. +69 −0 docs/content/templates/overview.md
  51. +22 −20 docs/content/{layout/chrome.md → templates/partials.md}
  52. +99 −0 docs/content/templates/rss.md
  53. +10 −4 docs/content/{layout → templates}/sitemap.md
  54. +131 −0 docs/content/templates/terms.md
  55. +5 −2 docs/content/{layout → templates}/variables.md
  56. +126 −0 docs/content/templates/views.md
  57. +65 −0 docs/content/themes/creation.md
  58. +54 −0 docs/content/themes/customizing.md
  59. +29 −0 docs/content/themes/installing.md
  60. +32 −0 docs/content/themes/overview.md
  61. +23 −0 docs/content/themes/usage.md
  62. +4 −1 docs/content/tutorials/github_pages_blog.md
  63. +2 −0 docs/content/tutorials/mathjax.md
  64. +4 −2 docs/content/tutorials/migrate-from-jekyll.md
View
@@ -1,27 +1,46 @@
baseurl = "http://hugo.spf13.com"
+MetaDataFormat = "yaml"
[indexes]
tag = "tags"
group = "groups"
+[[menu.main]]
+ name = "about hugo"
+ pre = "<i class='fa fa-heart'></i>"
+ weight = -110
+ identifier = "about"
[[menu.main]]
name = "getting started"
+ pre = "<i class='fa fa-road'></i>"
weight = -100
[[menu.main]]
name = "content"
+ pre = "<i class='fa fa-file-text'></i>"
weight = -90
[[menu.main]]
- name = "layout"
+ name = "themes"
+ pre = "<i class='fa fa-desktop'></i>"
+ weight = -85
+[[menu.main]]
+ name = "templates"
+ identifier = "layout"
+ pre = "<i class='fa fa-columns'></i>"
weight = -80
[[menu.main]]
- name = "taxonomy"
+ name = "taxonomies"
+ identifier = "taxonomy"
+ pre = "<i class='fa fa-tags'></i>"
weight = -70
[[menu.main]]
name = "extras"
+ pre = "<i class='fa fa-gift'></i>"
weight = -60
[[menu.main]]
name = "community"
+ pre = "<i class='fa fa-group'></i>"
weight = -50
[[menu.main]]
name = "tutorials"
+ pre = "<i class='fa fa-book'></i>"
weight = -40
@@ -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:
@@ -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)
@@ -5,6 +5,8 @@ weight: 10
menu:
main:
parent: 'community'
+prev: "/extras/urls"
+next: "/community/press"
---
Hugo has two mailing lists:
@@ -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"
+++
@@ -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.
+
@@ -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:
@@ -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
@@ -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 }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
+## Ordering Content Within Taxonomies
-## Order by Weight -> Date
-
- {{ range .Data.Pages.ByWeight }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-## Order by Date
-
- {{ range .Data.Pages.ByDate }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-## Order by Length
-
- {{ range .Data.Pages.ByLength }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-## Reverse Order
-Can be applied to any of the above. Using Date for an example.
-
- {{ range .Data.Pages.ByDate.Reverse }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-## Order by Title
-
- {{ range .Data.Pages.ByTitle }}
- <li>
- <a href="{{ .Permalink }}">{{ .Title }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-## Order by LinkTitle
-
- {{ range .Data.Pages.ByLinkTitle }}
- <li>
- <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
- <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
- </li>
- {{ end }}
-
-
-## Ordering Content Within Indexes
-
-Please see the [Index Ordering Documentation](/indexes/ordering/)
+Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/)
@@ -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
@@ -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.
-
-
Oops, something went wrong.

0 comments on commit a87f171

Please sign in to comment.