--- /dev/null
+---
+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/>.
+
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 © 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/>
**.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>
* 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
---
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**
indexes:
category: "categories"
tag: "tags"
- baseurl: "http://yoursite.com/"
+ baseurl: "http://yoursite.example.com/"
...
"category": "categories",
"tag": "tags"
},
- "baseurl": "http://yoursite.com/"
+ "baseurl": "http://yoursite.example.com/"
}
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
+ ...
+
projects / brevno-suite / hugo / commitdiff