[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

diff --git a/docs/content/extras/urls.md b/docs/content/extras/urls.md
index a3505bf779d88bb3b5ec57fdb2a531cc239c5fc7..d9f545a49c294707e86b886ec3ece948f8a3010a 100644 (file)
--- 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>

diff --git a/docs/content/tutorials/github-pages-blog.md b/docs/content/tutorials/github-pages-blog.md
index 683f9392d281adb27bfe56ae9b4c6c76cd6727bb..9ca4e23cbc11b82953c006d999965c6259a97bc2 100644 (file)
--- 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: