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

[Docs] Document the new (temp?) default of canonifyurls = false

Browse source 
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
This commit is contained in:
Anthony Fok 2015-01-22 18:04:07 -07:00
parent 60c6faa317
commit 743998306a
2 changed files with 76 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
docs/content/extras/urls.md
View file

@ -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>

10
docs/content/tutorials/github-pages-blog.md
View file

@ -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: