Edits on aliases, comments, theme customizing

Fleshed out aliases section, loading the "redirect" keyword so that it's easier to find. Specifically added a "how aliases work" section. Added Discourse to comments section. Fleshed out themes/customizing, because it seems to be the source of a lot of questions on the forum.
author: Rick Cogley <[email protected]> 2015-05-12 15:56:56 +0900
committer: bep <[email protected]> 2015-05-16 15:38:18 +0200
commit: 6b5ed88cdeeed8a35265c8613f39697b8db32e51 (patch)
tree: ec1fc386dcb33c488619b1cf4a3208b69bf815a7
parent: 6453bb5838eec2fb073af514d176dc6f109abe80 (diff)
download: hugo-6b5ed88cdeeed8a35265c8613f39697b8db32e51.tar.gz
hugo-6b5ed88cdeeed8a35265c8613f39697b8db32e51.zip
3 files changed, 89 insertions, 77 deletions
diff --git a/docs/content/extras/aliases.md b/docs/content/extras/aliases.md
index adc7dc5da..830e81ef8 100644
--- a/docs/content/extras/aliases.md
+++ b/docs/content/extras/aliases.md
@@ -13,41 +13,44 @@ title: Aliases
 weight: 10
 ---
 
-For people migrating existing published content to Hugo, there's a good chance
-you need a mechanism to handle redirecting old URLs.
+For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
 
-Luckily, this can be handled easily with aliases in Hugo.
+Luckily, redirects can be handled easily with _aliases_ in Hugo.
 
 ## Example
-**content/posts/my-awesome-blog-post.md**
-
-<table class="table">
-<thead>
-<tr>
-<th>TOML</th><th>YAML</th>
-</tr>
-</thead>
-<tbody>
-<tr valign="top">
-<td><pre><code>+++
+
+Given a post on your current Hugo site, with a path of: 
+
+``content/posts/my-awesome-blog-post.md``
+
+... you create an "aliases" section in the frontmatter of your post, and add previous paths to that. 
+
+### TOML frontmatter
+
+~~~yaml
++++
+        ...
 aliases = [
     "/posts/my-original-url/",
-    "/2010/even-earlier-url.html"
+    "/2010/01/01/even-earlier-url.html"
 ]
+        ...
 +++
-</code></pre></td>
-<td><pre><code>---
+~~~
+
+### YAML frontmatter
+
+~~~yaml
+---
+        ...
 aliases:
     - /posts/my-original-url/
-    - /2010/even-earlier-url.html
+    - /2010/01/01/even-earlier-url.html
+        ...
 ---
-</code></pre></td>
-</tr>
-</tbody>
-</table>
+~~~
 
-Now when you go to any of the aliases locations, they
-will redirect to the page.
+Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on. 
 
 ## Important Behaviors
 
@@ -57,3 +60,22 @@ complete filename or directory.*
 
 2. *Aliases are rendered prior to any content and will be overwritten by
 any content with the same location.*
+
+## How Hugo Aliases Work
+
+When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target. 
+
+Assuming a baseurl of `mysite.tld`, the contents of the html file will look something like: 
+
+~~~html
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="canonical" href="http://mysite.tld/posts/my-original-url"/>
+    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+    <meta http-equiv="refresh" content="0;url=http://mysite.tld/posts/my-original-url"/>
+  </head>
+</html>
+~~~
+
+The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case.
diff --git a/docs/content/extras/comments.md b/docs/content/extras/comments.md
index 713f6fb5f..6be5ade44 100644
--- a/docs/content/extras/comments.md
+++ b/docs/content/extras/comments.md
@@ -10,27 +10,20 @@ title: Comments in Hugo
 weight: 30
 ---
 
-As Hugo is a static site generator, the content produced is static and
-doesn’t interact with the users. The most common interaction people ask
-for is comment capability.
+As Hugo is a static site generator, the content produced is static and doesn’t interact with the users. The most common interaction people ask for is comment capability.
 
-Hugo ships with support for [Disqus](https://disqus.com/), a third-party
-service that provides comment and community capabilities to website via
-JavaScript.
+Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to website via JavaScript.
 
-Your theme may already support Disqus, but even it if doesn’t, it is easy
-to add.
+Your theme may already support Disqus, but even it if doesn’t, it is easy to add.
 
 # Disqus Support
 
 ## Adding Disqus to a template
 
-Hugo comes with all the code you would need to include load Disqus.
-Simply include the following line where you want your comments to appear:
+Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear:
 
     {{ template "_internal/disqus.html" . }}
 
-
 ## Configuring Disqus
 
 That template requires you to set a single value in your site config file, e.g. config.yaml.
@@ -44,12 +37,11 @@ for a given piece of content:
  * **disqus_title**
  * **disqus_url**
 
-
 ## Conditional Loading of Disqus Comments
 
 Users have noticed that enabling Disqus comments when running the Hugo web server on localhost causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in your `partials` folder that looks like this:
 
-```javascript
+```html
 <div id="disqus_thread"></div>
 <script type="text/javascript">
 
@@ -80,6 +72,7 @@ Now, reference the partial template from your page template:
 
 A few alternatives exist to [Disqus](https://disqus.com/):
 
+* [Discourse](http://www.discourse.org)
 * [IntenseDebate](http://intensedebate.com/)
 * [Livefyre](http://livefyre.com/)
 * [Muut](http://muut.com/)
@@ -87,15 +80,15 @@ A few alternatives exist to [Disqus](https://disqus.com/):
 * [isso](http://posativ.org/isso/) (Self-hosted, Python)
 * [Kaiju](https://github.com/spf13/kaiju)
 
+## Kaiju 
+
+[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](http://spf13.com/) (Hugo’s author) to bring easy and fast real time discussions to the web.
+
+Written using Go, Socket.io and MongoDB, it is very fast and easy to deploy.
 
-[Kaiju](https://github.com/spf13/kaiju) is an open-source project started
-by [spf13](http://spf13.com/) (Hugo’s author) to bring easy and fast real
-time discussions to the web.
+It is in early development but shows promise. If you have interest, please help by contributing whether via a pull request, an issue or even just a tweet. Everything helps.
 
-Written using Go, Socket.io and MongoDB, it is very fast and easy to
-deploy.
+## Discourse
 
-It is in early development but shows promise. If you have interest,
-please help by contributing whether via a pull request, an issue or even
-just a tweet. Everything helps.
+Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](http://discuss.gohugo.io).
 
diff --git a/docs/content/themes/customizing.md b/docs/content/themes/customizing.md
index 95914a7f4..ec66be712 100644
--- a/docs/content/themes/customizing.md
+++ b/docs/content/themes/customizing.md
@@ -9,49 +9,46 @@ title: Customizing a Theme
 weight: 40
 ---
 
-Hugo themes permit you to supplement or override any template or file
-from within your working directory.
+_The following are key concepts for Hugo site customization. Hugo permits you to **supplement or override** any theme template or static file, with files in your working directory._ 
 
-## Replacing Static files
+_When you use a theme cloned from its git repository, you do not edit the theme's files directly. Rather, you override them as per the following:_
 
-For including a different file than what the theme ships
-with. For example, if you would like to use a more recent version of jQuery
-than what the theme happens to include, simply place an identically named file in the same
-relative location but in your working directory. For example, if the
-theme has jQuery 1.6 in `/themes/themename/static/js/jquery.min.js`, simply place your file
-in the same relative path `/static/js/jquery.min.js`.
+## Replace Static Files
+
+For including a different file than what the theme ships with. For example, if you would like to use a more recent version of jQuery than what the theme happens to include, simply place an identically-named file in the same relative location but in your working directory. 
+
+For example, if the theme has jQuery 1.6 in:
+
+    /themes/themename/static/js/jquery.min.js
+
+... you would simply place your file in the same relative path, but in the root of your working folder:
+
+    /static/js/jquery.min.js
 
 ## Replace a single template file
 
-Anytime Hugo looks for a matching template, it will first check the
-working directory before looking in the theme directory. If you would
-like to modify a template, simply create that template in your local
-`layouts` directory. In the [template documentation](/templates/overview/)
-each different template type explains the rules it uses to determine
-which template to use.
+Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory. 
+
+In the [template documentation](/templates/overview/) _each different template type explains the rules it uses to determine which template to use_. Read and understand these rules carefully. 
+
+This is especially helpful when the theme creator used [partial templates](/templates/partials/). These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility.
+
+For example: 
+
+    /themes/themename/layouts/_default/single.html
+
+... would be overridden by: 
 
-This is especially helpful when the theme creator used [partial
-templates](/templates/partials/). These partial templates are perfect for easy
-injection into the theme with minimal maintenance to ensure future
-compatibility.
+    /layouts/_default/single.html
 
-**Warning: This only works for templates that Hugo knows about. If the
-theme imports template files in a creatively named directory,
-Hugo won’t know to look for the local `/layouts` first.**
+**Warning**: This only works for templates that Hugo "knows about" (that follow its convention for folder structure and naming). If the theme imports template files in a creatively-named directory, Hugo won’t know to look for the local `/layouts` first.
 
 ## Replace an archetype
 
-If the archetype that ships with the theme for a given content type (or
-all content types) doesn’t fit with how you are using the theme, feel
-free to copy it to your `/archetypes` directory and make modifications as
-you see fit.
+If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit.
 
 ## Beware of the default
 
-**Default** is a very powerful force in Hugo... Especially as it pertains to
-overwriting theme files. If a default is located in the local archetype
-directory or `/layouts/_default/` directory, it will be used instead of
-any of the similar files in the theme. 
+**Default** is a very powerful force in Hugo... Especially as it pertains to overwriting theme files. If a default is located in the local archetype directory or `/layouts/_default/` directory, it will be used instead of any of the similar files in the theme.  
 
-It is usually better to override specific files rather than using the
-default in your working directory.
+It is usually better to override specific files rather than using the default in your working directory.
author	Rick Cogley <[email protected]>	2015-05-12 15:56:56 +0900
committer	bep <[email protected]>	2015-05-16 15:38:18 +0200
commit	6b5ed88cdeeed8a35265c8613f39697b8db32e51 (patch)
tree	ec1fc386dcb33c488619b1cf4a3208b69bf815a7
parent	6453bb5838eec2fb073af514d176dc6f109abe80 (diff)
download	hugo-6b5ed88cdeeed8a35265c8613f39697b8db32e51.tar.gz hugo-6b5ed88cdeeed8a35265c8613f39697b8db32e51.zip