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.
This commit is contained in:
Rick Cogley 2015-05-12 15:56:56 +09:00 committed by bep
parent 6453bb5838
commit 6b5ed88cde
3 changed files with 88 additions and 76 deletions

View file

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

View file

@ -10,27 +10,20 @@ title: Comments in Hugo
weight: 30
---
As Hugo is a static site generator, the content produced is static and
doesnt 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 doesnt 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 doesnt, it is easy
to add.
Your theme may already support Disqus, but even it if doesnt, 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/) (Hugos author) to bring easy and fast real
time discussions to the web.
[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](http://spf13.com/) (Hugos 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.
Written using Go, Socket.io and MongoDB, it is very fast and easy to deploy.
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.
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.
## Discourse
Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](http://discuss.gohugo.io).

View file

@ -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.
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.
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.
**Warning: This only works for templates that Hugo knows about. If the
theme imports template files in a creatively named directory,
Hugo wont know to look for the local `/layouts` first.**
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:
/layouts/_default/single.html
**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 wont 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) doesnt 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) doesnt 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.