github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-07 20:30:36 -05:00
Code Issues Projects Releases Packages Wiki Activity

Documentation updates, mostly for my bits

Browse source 
* extras/permalinks.md added, weighted to third in the extras menu
* examples added to layout/go-templates.md, using `.Site.Params`
* mention `.Site.Params` in layout/variables.md
* update meta/release-notes.md to mention `first` and the permalinks
* update overview/configuration.md to use reserved-for-documentation
  domains and with another example, nudging towards permalinks and site
  parameters, with three different data-types shown for the latter

Signed-off-by: Noah Campbell <noahcampbell@gmail.com>
This commit is contained in:
Phil Pennock 2013-11-18 18:31:02 -05:00 committed by Noah Campbell
parent 07978e4a49
commit e425226a28
5 changed files with 117 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/content/extras/permalinks.md Normal file
View file

@ -0,0 +1,33 @@
---
title: "Permalinks"
date: "2013-11-18"
aliases:
- "/doc/permalinks/"
groups: ["extras"]
groups_weight: 30
---
By default, content is laid out into the target `publishdir` (public)
namespace matching its layout within the `contentdir` hierarchy.
The `permalinks` site configuration option allows you to adjust this on a
per-section basis.
This will change where the files are written to and will change the page's
internal "canonical" location, such that template references to
`.RelPermalink` will honour the adjustments made as a result of the mappings
in this option.
For instance, if one of your sections is called `post` and you want to adjust
the canonical path to be hierarchical based on the year and month, then you
might use:
```yaml
permalinks:
post: /:year/:month/:title/
```
Only the content under `post/` will be so rewritten.
A file named `content/post/sample-entry` which contains a line
`date: 2013-11-18T19:20:00-05:00` might end up with the rendered page
appearing at `public/2013/11/sample-entry/index.html` and be reachable via
the URL <http://yoursite.example.com/2013/11/sample-entry/>.

61
docs/content/layout/go-templates.md
View file

@ -6,13 +6,64 @@ groups_weight: 80
draft: true
---
Hugo uses the excellent golang html/template library for its template engine.
Hugo uses the excellent [golang][] [html/template][gohtmltemplate] 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
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.
This is a brief primer on using go templates. The [golang docs][gohtmltemplate]
provide more details.
In your top-level configuration file (eg, `config.yaml`) you can define site
parameters, which are values which will be available to you in chrome.
For instance, you might declare:
```yaml
params:
CopyrightHTML: "Copyright &#xA9; 2013 John Doe. All Rights Reserved."
TwitterUser: "spf13"
SidebarRecentLimit: 5
```
Within a footer layout, you might then declare a `<footer>` which is only
provided if the `CopyrightHTML` parameter is provided, and if it is given,
you would declare it to be HTML-safe, so that the HTML entity is not escaped
again. This would let you easily update just your top-level config file each
January 1st, instead of hunting through your templates.
```
{{if .Site.Params.CopyrightHTML}}<footer>
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHtml}}</div>
</footer>{{end}}
```
An alternative way of writing the "if" and then referencing the same value is
to use "with" instead, which rebinds the pointer `.` within its scope, and
elides the scope if the variable is absent:
```
{{with .Site.Params.TwitterUser}}<span class="twitter">
<a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
alt="Twitter"></a>
</span>{{end}}
```
Finally, if you want to pull "magic constants" out of your layouts, you can do
so, such as in this example:
```
<nav class="recent">
<h1>Recent Posts</h1>
<ul>{{range first .Site.Params.SidebarRecentLimit .Site.Recent}}
<li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
{{end}}</ul>
</nav>
```
[golang]: <http://golang.org/>
[gohtmltemplate]: <http://golang.org/pkg/html/template/>

4
docs/content/layout/variables.md
View file

@ -52,5 +52,5 @@ Also available is `.Site` which has the following:
**.Site.BaseUrl** The base URL for the site as defined in the config.json file.<br>
**.Site.Indexes** The indexes for the entire site.<br>
**.Site.LastChange** The date of the last change of the most recent content.<br>
**.Site.Recent** Array of all content ordered by Date, newest first<br>
**.Site.Recent** Array of all content ordered by Date, newest first.<br>
**.Site.Params** A container holding the values from `params` in your site configuration file.<br>

2
docs/content/meta/release-notes.md
View file

@ -36,6 +36,8 @@ groups_weight: 10
* Better handling of most errors with directions on how to resolve
* Support for more date / time formats
* Support for go 1.2
* Support for `first` in templates
* Support for site per-section permalink pattern specifications
* **0.8.0** August 2, 2013
* Added support for pretty urls (filename/index.html vs filename.html)
* Hugo supports a destination directory

31
docs/content/overview/configuration.md
View file

@ -8,12 +8,12 @@ groups_weight: 40
---
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.
configuration for a site. In fact a config file isn't even needed for many
websites since the defaults used 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.yaml` file. If none is present it will
then look for a `config.json` file, followed by a `config.toml` file.
**Please note the field names must be all lowercase**
@ -29,7 +29,7 @@ The following is an example of a yaml config file with the default values:
indexes:
category: "categories"
tag: "tags"
baseurl: "http://yoursite.com/"
baseurl: "http://yoursite.example.com/"
...
@ -44,7 +44,7 @@ The following is an example of a json config file with the default values:
"category": "categories",
"tag": "tags"
},
"baseurl": "http://yoursite.com/"
"baseurl": "http://yoursite.example.com/"
}
@ -54,8 +54,25 @@ The following is an example of a toml config file with the default values:
layoutdir = "layouts"
publishdir = "public"
builddrafts = false
baseurl = "http://yoursite.com/"
baseurl = "http://yoursite.example.com/"
[indexes]
category = "categories"
tag = "tags"
Here is a yaml configuration file which sets a few more options
---
baseurl: "http://yoursite.example.com/"
title: "Yoyodyne Widget Blogging"
permalinks:
post: /:year/:month/:title/
params:
Subtitle: "Spinning the cogs in the widgets"
AuthorName: "John Doe"
GitHubUser: "spf13"
ListOfFoo:
- "foo1"
- "foo2"
SidebarRecentLimit: 5
...