[Docs] Document the new (temp?) default of `canonifyurls = false` - hugo - [fork] hugo port for 9front
HTML git clone git@git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
DIR commit 743998306a02a683371caeac477501418894a8f5
DIR parent 60c6faa317d3a07d02effc86b4fe03c9bc84be98
HTML Author: Anthony Fok <foka@debian.org>
Date: Thu, 22 Jan 2015 18:04:07 -0700
[Docs] Document the new (temp?) default of `canonifyurls = false`
Also add a **Caveat** on http://gohugo.io/tutorials/github-pages-blog/
warning the reader that a `canonifyurls = true` must be added
for Spencer's old example files to work.
Fixes #802
Diffstat:
M docs/content/extras/urls.md | 76 +++++++++++++++++++++++++++----
M docs/content/tutorials/github-page… | 10 ++++++++++
2 files changed, 76 insertions(+), 10 deletions(-)
---
DIR diff --git a/docs/content/extras/urls.md b/docs/content/extras/urls.md
@@ -14,27 +14,39 @@ weight: 110
## Pretty URLs
-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.
+By default, Hugo create content with 'pretty' URLs. For example,
+content created at `/content/extras/urls.md` will be rendered at
+`/public/extras/urls/index.html`, thus accessible from the browser
+at http://example.com/extras/urls/. No non-standard server-side
+configuration is required for these pretty URLs to work.
-If you would like to have ugly URLs, you are in luck. Hugo supports the
-ability to create your entire site with ugly URLs. Simply use the
-`--uglyUrls=true` flag on the command line.
+If you would like to have what we call "ugly URLs",
+e.g. http://example.com/extras/urls.html, you are in luck.
+Hugo supports the ability to create your entire site with ugly URLs.
+Simply add `uglyurls = true` to your site-wide `config.toml`,
+or use the `--uglyUrls=true` flag on the command line.
If you want a specific piece of content to have an exact URL, you can
-specify this in the front matter under the url key. See [Content
+specify this in the front matter under the `url` key. See [Content
Organization](/content/organization/) for more details.
## Canonicalization
+<!--
By default, all relative URLs encountered in the input will be canonicalized
using `baseurl`, so that a link `/css/foo.css` becomes
`http://yoursite.example.com/css/foo.css`.
-Setting `canonifyurls` to `false` will prevent this canonicalization.
+By setting `canonifyurls` to `false` will prevent this canonicalization.
+-->
+By default, all relative URLs encountered in the input are left unmodified,
+e.g. `/css/foo.css` would stay as `/css/foo.css`.
+
+By setting `canonifyurls` to `true`, all relative URLs would instead
+be *canonicalized* using `baseurl`. For example, assuming you have
+`baseurl = http://yoursite.example.com/` defined in the site-wide
+config.toml, the relative URL `/css/foo.css` would be turned into
+the absolute URL `http://yoursite.example.com/css/foo.css`.
Benefits of canonicalization include fixing all URLs to be absolute, which may
aid with some parsing tasks. Note though that all real browsers handle this
@@ -43,3 +55,47 @@ client-side without issues.
Benefits of non-canonicalization include being able to have resource inclusion
be scheme-relative, so that http vs https can be decided based on how this
page was retrieved.
+
+### Caveat: Default of `canonifyurls` changed in v0.11
+
+<table class="table table-bordered">
+<thead>
+<tr>
+<th>Hugo Version</th>
+<th>Release Date</th>
+<th>Default</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td>v0.9</td>
+<td>2013-11-15</td>
+<td><code>canonifyurls = true</code> <small>(non-configurable)</small></td>
+</tr>
+
+<tr>
+<td>v0.10</td>
+<td>2014-03-01</td>
+<td><code>canonifyurls = true</code></td>
+</tr>
+
+<tr>
+<td>v0.11</td>
+<td>2014-05-29</td>
+<td><code>canonifyurls = false</code></td>
+</tr>
+
+<tr>
+<td>v0.12</td>
+<td>2014-09-01</td>
+<td><code>canonifyurls = false</code></td>
+</tr>
+
+<tr>
+<td>v0.13-DEV</td>
+<td><small>in development</small></td>
+<td><code>canonifyurls = false</code> <small>(as of January 2015)</small></td>
+</tr>
+</tbody>
+</table>
DIR diff --git a/docs/content/tutorials/github-pages-blog.md b/docs/content/tutorials/github-pages-blog.md
@@ -39,8 +39,18 @@ The very first step in creating a new Hugo site is to [write the config file](/o
category: "categories"
baseurl: "http://spencerlyon2.github.io/hugo_gh_blog"
title: "Hugo Blog Template for GitHub Pages"
+ canonifyurls: true
...
+> **Caveat:** Hugo's former default of `canonifyurls: true` has been changed
+> to `false` since this tutorial has written. **Please make sure you manually
+> add `canonifyurls: true` to your `config.yaml`** if you are using Spencer's
+> https://github.com/spencerlyon2/hugo_gh_blog for this tutorial, or you *will*
+> run into problems such as the CSS files not loading.
+
+> See ["Canonicalization: Caveat" on the "Extras: URLs page"](/extras/urls/)
+> for more information.
+
### Define Structure of Website
Hugo assumes that you organize the content of your site in a meaningful way and uses the same structure to render the website. Notice that we have the line `contentdir: "content"` in our configuration file. This means that all the actual content of the website should be placed somewhere within a folder named `content`. Hugo treats all directories in `content` as sections. For our example we only need one section: a place to hold our blog posts. So we created two new folders: