phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-05 08:42:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Switching docs highlighting to highlight.js .. Docs build super fast again!

Browse source
This commit is contained in:
spf13 2014-05-15 09:58:55 -04:00
parent b198cb26ba
commit b520f8852d
23 changed files with 662 additions and 590 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/archetypes/default.md
View file

@ -1,6 +1,4 @@
+++ +++
date = "2013-07-01"
title = "Title of the Content"
weight = 5 weight = 5
[menu] [menu]
[menu.main] [menu.main]

42
docs/content/content/example.md
View file

@ -14,35 +14,33 @@ Somethings are better shown than explained. The following is a very basic exampl
**mysite/project/nitro.md <- http://mysite.com/project/nitro.html** **mysite/project/nitro.md <- http://mysite.com/project/nitro.html**
{{% highlight yaml %}} ---
--- Title: "Nitro : A quick and simple profiler for Go"
Title: "Nitro : A quick and simple profiler for Go" Description: "Nitro is a simple profiler for you go lang applications"
Description: "Nitro is a simple profiler for you go lang applications" Tags: [ "Development", "Go", "profiling" ]
Tags: [ "Development", "Go", "profiling" ] date: "2013-06-19"
date: "2013-06-19" Topics: [ "Development", "Go" ]
Topics: [ "Development", "Go" ] Slug: "nitro"
Slug: "nitro" project_url: "http://github.com/spf13/nitro"
project_url: "http://github.com/spf13/nitro" ---
---
# Nitro # Nitro
Quick and easy performance analyzer library for Go. Quick and easy performance analyzer library for Go.
## Overview ## Overview
Nitro is a quick and easy performance analyzer library for Go. Nitro is a quick and easy performance analyzer library for Go.
It is useful for comparing A/B against different drafts of functions It is useful for comparing A/B against different drafts of functions
or different functions. or different functions.
## Implementing Nitro ## Implementing Nitro
Using Nitro is simple. First use go get to install the latest version Using Nitro is simple. First use go get to install the latest version
of the library. of the library.
$ go get github.com/spf13/nitro $ go get github.com/spf13/nitro
Next include nitro in your application. Next include nitro in your application.
{{% /highlight %}}

76
docs/content/content/front-matter.md
View file

@ -19,53 +19,47 @@ Supported formats: <br>
### YAML Example ### YAML Example
{{% highlight yaml %}} ---
--- title: "spf13-vim 3.0 release and new website"
title: "spf13-vim 3.0 release and new website" description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] date: "2012-04-06"
date: "2012-04-06" categories:
categories: - "Development"
- "Development" - "VIM"
- "VIM" slug: "spf13-vim-3-0-release-and-new-website"
slug: "spf13-vim-3-0-release-and-new-website" ---
--- Content of the file goes Here
Content of the file goes Here
{{% /highlight %}}
### TOML Example ### TOML Example
{{% highlight yaml %}} +++
+++ title = "spf13-vim 3.0 release and new website"
title = "spf13-vim 3.0 release and new website" description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] date = "2012-04-06"
date = "2012-04-06" categories = [
categories = [ "Development",
"Development", "VIM"
"VIM" ]
] slug = "spf13-vim-3-0-release-and-new-website"
slug = "spf13-vim-3-0-release-and-new-website" +++
+++ Content of the file goes Here
Content of the file goes Here
{{% /highlight %}}
### JSON Example ### JSON Example
{{% highlight json %}} {
{ "title": "spf13-vim 3.0 release and new website",
"title": "spf13-vim 3.0 release and new website", "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
"tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], "date": "2012-04-06",
"date": "2012-04-06", "categories": [
"categories": [ "Development",
"Development", "VIM"
"VIM" ],
], "slug": "spf13-vim-3-0-release-and-new-website",
"slug": "spf13-vim-3-0-release-and-new-website", }
} Content of the file goes Here
Content of the file goes Here
{{% /highlight %}}
## Variables ## Variables

108
docs/content/content/ordering.md
View file

@ -10,13 +10,15 @@ weight: 60
In Hugo you have a good degree of control of how your content can be ordered. In Hugo you have a good degree of control of how your content can be ordered.
By default, content is ordered by weight, then by date with the most recent date first, but alternative sorting (by title and linktitle) is also available. By default, content is ordered by weight, then by date with the most recent
date first, but alternative sorting (by title and linktitle) is also available.
_Both the date and weight fields are optional._ _Both the date and weight fields are optional._
Unweighted pages appear at the end of the list. Unweighted pages appear at the end of the list. If no weights are provided (or
If no weights are provided (or if weights are the same) date will be used to sort. If neither are provided if weights are the same) date will be used to sort. If neither are provided
content will be ordered based on how it's read off the disk and no order is guaranteed. content will be ordered based on how it's read off the disk and no order is
guaranteed.
## Assigning Weight to content ## Assigning Weight to content
@ -29,81 +31,67 @@ content will be ordered based on how it's read off the disk and no order is guar
## Order by Weight -> Date (default) ## Order by Weight -> Date (default)
{{% highlight html %}} {{ range .Data.Pages }}
{{ range .Data.Pages }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Order by Weight -> Date ## Order by Weight -> Date
{{% highlight html %}} {{ range .Data.Pages.ByWeight }}
{{ range .Data.Pages.ByWeight }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Order by Date ## Order by Date
{{% highlight html %}} {{ range .Data.Pages.ByDate }}
{{ range .Data.Pages.ByDate }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Order by Length ## Order by Length
{{% highlight html %}} {{ range .Data.Pages.ByLength }}
{{ range .Data.Pages.ByLength }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Reverse Order ## Reverse Order
Can be applied to any of the above. Using Date for an example. Can be applied to any of the above. Using Date for an example.
{{% highlight html %}} {{ range .Data.Pages.ByDate.Reverse }}
{{ range .Data.Pages.ByDate.Reverse }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Order by Title ## Order by Title
{{% highlight html %}} {{ range .Data.Pages.ByTitle }}
{{ range .Data.Pages.ByTitle }} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Order by LinkTitle ## Order by LinkTitle
{{% highlight html %}} {{ range .Data.Pages.ByLinkTitle }}
{{ range .Data.Pages.ByLinkTitle }} <li>
<li> <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li> {{ end }}
{{ end }}
{{% /highlight %}}
## Ordering Content Within Indexes ## Ordering Content Within Indexes

4
docs/content/content/types.md
View file

@ -13,7 +13,6 @@ of meta data and template. A good example of when multiple types are
needed is to look at Tumblr. A piece of content could be a photo, quote needed is to look at Tumblr. A piece of content could be a photo, quote
or post, each with different meta data and rendered differently. or post, each with different meta data and rendered differently.
## Defining a content type ## Defining a content type
Creating a new content type is easy in Hugo. You simply provide the Creating a new content type is easy in Hugo. You simply provide the
@ -49,6 +48,3 @@ this then each new piece of content you place into a section will automatically
inherit the type. inherit the type.
Alternatively you can set the type in the meta data under the key "type". Alternatively you can set the type in the meta data under the key "type".

13
docs/content/extras/aliases.md
View file

@ -18,13 +18,12 @@ Luckily, this can be handled easily with aliases in Hugo.
## Example ## Example
**content/posts/my-awesome-blog-post.md** **content/posts/my-awesome-blog-post.md**
{{% highlight yaml %}}
--- ---
aliases: aliases:
- /posts/my-original-url/ - /posts/my-original-url/
- /2010/even-earlier-url.html - /2010/even-earlier-url.html
--- ---
{{% /highlight %}}
Now when you go to any of the aliases locations they Now when you go to any of the aliases locations they
will redirect to the page. will redirect to the page.

39
docs/content/extras/highlighting.md
View file

@ -24,8 +24,7 @@ silently simply pass the content along unhighlighted.
### Disclaimers ### Disclaimers
* **Warning** pygments is relatively slow and our integration isn't * **Warning** pygments is relatively slow. Expect much longer build times when using server side highlighting.
as optimized as it could be. Expect much longer build times when using server side highlighting.
* Languages available depends on your pygments installation. * Languages available depends on your pygments installation.
* Styles are inline in order to be supported in syndicated content when references * Styles are inline in order to be supported in syndicated content when references
to style sheets are not carried over. to style sheets are not carried over.
@ -40,8 +39,9 @@ Highlight takes exactly one required parameter of language and requires a
closing shortcode. closing shortcode.
### Example ### Example
{{% highlight html %}} The example has an extra space between the “{{” and “%” characters to prevent rendering here.
{{&#37; highlight html %}}
{{ % highlight html %}}
<section id="main"> <section id="main">
<div> <div>
<h1 id="title">{{ .Title }}</h1> <h1 id="title">{{ .Title }}</h1>
@ -50,22 +50,19 @@ closing shortcode.
{{ end }} {{ end }}
</div> </div>
</section> </section>
{{&#37; /highlight %}} {{ % /highlight %}}
{{% /highlight %}}
### Example Output ### Example Output
{{% highlight html %}} <span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span> <span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span> <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span> {{ range .Data.Pages }}
{{ range .Data.Pages }} {{ .Render &quot;summary&quot;}}
{{ .Render &quot;summary&quot;}} {{ end }}
{{ end }} <span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/div&gt;</span> <span style="color: #f92672">&lt;/section&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
{{% /highlight %}}
## Client-side ## Client-side
@ -74,10 +71,10 @@ Alternatively, code highlighting can be done in client-side JavaScript.
Client-side syntax highlighting is very simple to add. You'll need to pick Client-side syntax highlighting is very simple to add. You'll need to pick
a library and a corresponding theme. Some popular libraries are: a library and a corresponding theme. Some popular libraries are:
- [Highlight.js]
- [Rainbow] - [Rainbow]
- [Syntax Highlighter] - [Syntax Highlighter]
- [Google Prettify] - [Google Prettify]
- [Highlight.js]
This example uses the popular [Highlight.js] library, hosted by [Yandex], a This example uses the popular [Highlight.js] library, hosted by [Yandex], a
popular Russian search engine. popular Russian search engine.
@ -86,17 +83,15 @@ In your `./layouts/chrome/` folder, depending on your specific theme, there
will be a snippet that will be included in every generated HTML page, such will be a snippet that will be included in every generated HTML page, such
as `header.html` or `header.includes.html`. Simply add: as `header.html` or `header.includes.html`. Simply add:
{{% highlight html %}} <link rel="stylesheet" href="https://yandex.st/highlightjs/8.0/styles/default.min.css">
<link rel="stylesheet" href="https://yandex.st/highlightjs/8.0/styles/default.min.css"> <script src="https://yandex.st/highlightjs/8.0/highlight.min.js"></script>
<script src="https://yandex.st/highlightjs/8.0/highlight.min.js"></script>
{{% /highlight %}}
You can of course use your own copy of these files, typically in `./static/`. You can of course use your own copy of these files, typically in `./static/`.
[Highlight.js]: http://highlightjs.org/
[Rainbow]: http://craig.is/making/rainbows [Rainbow]: http://craig.is/making/rainbows
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/ [Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://code.google.com/p/google-code-prettify/ [Google Prettify]: https://code.google.com/p/google-code-prettify/
[Yandex]: http://yandex.ru/ [Yandex]: http://yandex.ru/
[Highlight.js]: http://highlightjs.org/
Please see individual libraries documentation for how to implement the JavaScript based libraries. Please see individual libraries documentation for how to implement the JavaScript based libraries.

30
docs/content/extras/shortcodes.md
View file

@ -37,7 +37,8 @@ Some shortcodes use or require closing shortcodes. Like HTML, the opening and cl
shortcodes match (name only), the closing being prepended with a slash. shortcodes match (name only), the closing being prepended with a slash.
Example of a paired shortcode: Example of a paired shortcode:
{{&#37; highlight go %}} A bunch of code here {{&#37; /highlight %}}
{{ % highlight go %}} A bunch of code here {{ % /highlight %}}
## Hugo Shortcodes ## Hugo Shortcodes
@ -54,8 +55,9 @@ Highlight takes exactly one required parameter of language and requires a
closing shortcode. closing shortcode.
#### Example #### Example
{{% highlight html %}} The example has an extra space between the “{{” and “%” characters to prevent rendering here.
{{&#37; highlight html %}}
{{ % highlight html %}}
<section id="main"> <section id="main">
<div> <div>
<h1 id="title">{{ .Title }}</h1> <h1 id="title">{{ .Title }}</h1>
@ -64,13 +66,11 @@ closing shortcode.
{{ end }} {{ end }}
</div> </div>
</section> </section>
{{&#37; /highlight %}} {{ % /highlight %}}
{{% /highlight %}}
#### Example Output #### Example Output
{{% highlight html %}}
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span> <span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span> <span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span> <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
@ -79,7 +79,6 @@ closing shortcode.
{{ end }} {{ end }}
<span style="color: #f92672">&lt;/div&gt;</span> <span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span> <span style="color: #f92672">&lt;/section&gt;</span>
{{% /highlight %}}
### figure ### figure
Figure is simply an extension of the image capabilities present with Markdown. Figure is simply an extension of the image capabilities present with Markdown.
@ -98,16 +97,18 @@ figure can use the following parameters
* alt * alt
#### Example #### Example
*Example has an extra space so Hugo doesn't actually render it*.
{{% highlight html %}} {{ % figure src="/media/spf13.jpg" title="Steve Francia" %}}
{{&#37; figure src="/media/spf13.jpg" title="Steve Francia" %}}
{{% /highlight %}}
#### Example output #### Example output
{{% highlight html %}} <figure>
<img src="/media/spf13.jpg" />
{{% /highlight %}} <figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
## Creating your own shortcodes ## Creating your own shortcodes
@ -173,6 +174,7 @@ This would be rendered as
{{ % img src="/media/spf13.jpg" title="Steve Francia" %}} {{ % img src="/media/spf13.jpg" title="Steve Francia" %}}
Would load the template /layouts/shortcodes/img.html Would load the template /layouts/shortcodes/img.html
<!-- image --> <!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}> <figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }} {{ with .Get "link"}}<a href="{{.}}">{{ end }}
@ -206,11 +208,9 @@ Would be rendered as:
*Example has an extra space so Hugo doesn't actually render it*. *Example has an extra space so Hugo doesn't actually render it*.
{{% highlight html %}}
<html> <html>
<body> This HTML </body> <body> This HTML </body>
</html> </html>
{{% /highlight %}}
The template for this utilizes the following code (already include in hugo) The template for this utilizes the following code (already include in hugo)
{{ .Get 0 | highlight .Inner }} {{ .Get 0 | highlight .Inner }}

4
docs/content/extras/toc.md
View file

@ -9,12 +9,12 @@ menu:
Hugo will automatically parse the markdown for your content and create Hugo will automatically parse the markdown for your content and create
a Table of Contents you can use to guide readers to the sections within a Table of Contents you can use to guide readers to the sections within
your content. your content.
## Usage ## Usage
Simply create content like you normally would with the appropriate Simply create content like you normally would with the appropriate
headers. headers.
Hugo will take this markdown and create a table of contents stored in the Hugo will take this markdown and create a table of contents stored in the
[content variable](/layout/variables) .TableOfContents [content variable](/layout/variables) .TableOfContents

75
docs/content/layout/chrome.md
View file

@ -32,56 +32,51 @@ used for both nodes and pages we can use the same chrome for both.
## example header.html ## example header.html
This header template is used for [spf13.com](http://spf13.com). This header template is used for [spf13.com](http://spf13.com).
{{% highlight html %}} <!DOCTYPE html>
<!DOCTYPE html> <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> <head>
<head> <meta charset="utf-8">
<meta charset="utf-8">
{{ template "chrome/meta.html" . }} {{ template "chrome/meta.html" . }}
<base href="{{ .Site.BaseUrl }}"> <base href="{{ .Site.BaseUrl }}">
<title> {{ .Title }} : spf13.com </title> <title> {{ .Title }} : spf13.com </title>
<link rel="canonical" href="{{ .Permalink }}"> <link rel="canonical" href="{{ .Permalink }}">
{{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }} {{ if .RSSlink }}<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Title }}" />{{ end }}
{{ template "chrome/head_includes.html" . }}
</head>
<body lang="en">
{{% /highlight %}}
{{ template "chrome/head_includes.html" . }}
</head>
<body lang="en">
## example footer.html ## example footer.html
This header template is used for [spf13.com](http://spf13.com). This header template is used for [spf13.com](http://spf13.com).
{{% highlight html %}} <footer>
<footer> <div>
<div> <p>
<p> &copy; 2013 Steve Francia.
&copy; 2013 Steve Francia. <a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
<a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>; please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>. </p>
</p> </div>
</div> </footer>
</footer> <script type="text/javascript">
<script type="text/javascript">
var _gaq = _gaq || []; var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-XYSYXYSY-X']); _gaq.push(['_setAccount', 'UA-XYSYXYSY-X']);
_gaq.push(['_trackPageview']); _gaq.push(['_trackPageview']);
(function() { (function() {
var ga = document.createElement('script'); var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js'; 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true'); ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga); document.documentElement.firstChild.appendChild(ga);
})(); })();
</script> </script>
</body> </body>
</html> </html>
{{% /highlight %}}
**For examples of referencing these templates, see [content **For examples of referencing these templates, see [content
templates](/layout/content/) and [homepage templates](/layout/homepage/)** templates](/layout/content/) and [homepage templates](/layout/homepage/)**

44
docs/content/layout/homepage.md
View file

@ -28,32 +28,30 @@ This content template is used for [spf13.com](http://spf13.com).
It makes use of [chrome templates](/layout/chrome) and uses a [List](/indexes/lists/) It makes use of [chrome templates](/layout/chrome) and uses a [List](/indexes/lists/)
{{% highlight html %}} <!DOCTYPE html>
<!DOCTYPE html> <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> <head>
<head> <meta charset="utf-8">
<meta charset="utf-8">
{{ template "chrome/meta.html" . }} {{ template "chrome/meta.html" . }}
<base href="{{ .Site.BaseUrl }}"> <base href="{{ .Site.BaseUrl }}">
<title>{{ .Site.Title }}</title> <title>{{ .Site.Title }}</title>
<link rel="canonical" href="{{ .Permalink }}"> <link rel="canonical" href="{{ .Permalink }}">
<link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" /> <link href="{{ .RSSlink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
{{ template "chrome/head_includes.html" . }} {{ template "chrome/head_includes.html" . }}
</head> </head>
<body lang="en"> <body lang="en">
{{ template "chrome/subheader.html" . }} {{ template "chrome/subheader.html" . }}
<section id="main"> <section id="main">
<div> <div>
{{ range first 10 .Data.Pages }} {{ range first 10 .Data.Pages }}
{{ .Render "summary"}} {{ .Render "summary"}}
{{ end }} {{ end }}
</div> </div>
</section> </section>
{{ template "chrome/footer.html" }} {{ template "chrome/footer.html" }}
{{% /highlight %}}

92
docs/content/layout/indexes.md
View file

@ -45,23 +45,21 @@ It makes use of [chrome templates](/layout/chrome). All examples use a
[view](/layout/views/) called either "li" or "summary" which this example site [view](/layout/views/) called either "li" or "summary" which this example site
defined. defined.
{{% highlight html %}} {{ template "chrome/header.html" . }}
{{ template "chrome/header.html" . }} {{ template "chrome/subheader.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main"> <section id="main">
<div> <div>
<h1 id="title">{{ .Title }}</h1> <h1 id="title">{{ .Title }}</h1>
<ul id="list"> <ul id="list">
{{ range .Data.Pages }} {{ range .Data.Pages }}
{{ .Render "li"}} {{ .Render "li"}}
{{ end }} {{ end }}
</ul> </ul>
</div> </div>
</section> </section>
{{ template "chrome/footer.html" }} {{ template "chrome/footer.html" }}
{{% /highlight %}}
## Example index template (tag.html) ## Example index template (tag.html)
This content template is used for [spf13.com](http://spf13.com). This content template is used for [spf13.com](http://spf13.com).
@ -69,21 +67,19 @@ It makes use of [chrome templates](/layout/chrome). All examples use a
[view](/layout/views/) called either "li" or "summary" which this example site [view](/layout/views/) called either "li" or "summary" which this example site
defined. defined.
{{% highlight html %}} {{ template "chrome/header.html" . }}
{{ template "chrome/header.html" . }} {{ template "chrome/subheader.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main"> <section id="main">
<div> <div>
<h1 id="title">{{ .Title }}</h1> <h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }} {{ range .Data.Pages }}
{{ .Render "summary"}} {{ .Render "summary"}}
{{ end }} {{ end }}
</div> </div>
</section> </section>
{{ template "chrome/footer.html" }} {{ template "chrome/footer.html" }}
{{% /highlight %}}
## Example listing of indexes template (indexes.html) ## Example listing of indexes template (indexes.html)
This content template is used for [spf13.com](http://spf13.com). This content template is used for [spf13.com](http://spf13.com).
@ -100,31 +96,29 @@ the latter uses .Data.OrderedIndex. .Data.Index is alphabetical by key name, whi
.Data.Orderedindex is ordered by the quantity of content assigned to that particular .Data.Orderedindex is ordered by the quantity of content assigned to that particular
index key. In practice you would only use one of these approaches. index key. In practice you would only use one of these approaches.
{{% highlight html %}} {{ template "chrome/header.html" . }}
{{ template "chrome/header.html" . }} {{ template "chrome/subheader.html" . }}
{{ template "chrome/subheader.html" . }}
<section id="main"> <section id="main">
<div> <div>
<h1 id="title">{{ .Title }}</h1> <h1 id="title">{{ .Title }}</h1>
<ul> <ul>
{{ $data := .Data }} {{ $data := .Data }}
{{ range $key, $value := .Data.Index }} {{ range $key, $value := .Data.Index }}
<li><a href="{{ $data.Plural }}/{{ $key | urlize }}"> {{ $key }} </a> {{ len $value }} </li> <li><a href="{{ $data.Plural }}/{{ $key | urlize }}"> {{ $key }} </a> {{ len $value }} </li>
{{ end }} {{ end }}
</ul> </ul>
</div> </div>
<ul> <ul>
{{ range $data.OrderedIndex }} {{ range $data.OrderedIndex }}
<li><a href="{{ $data.Plural }}/{{ .Name | urlize }}"> {{ .Name }} </a> {{ .Count }} </li> <li><a href="{{ $data.Plural }}/{{ .Name | urlize }}"> {{ .Name }} </a> {{ .Count }} </li>
{{ end }} {{ end }}
</ul> </ul>
</section> </section>
{{ template "chrome/footer.html" }} {{ template "chrome/footer.html" }}
{{% /highlight %}}

42
docs/content/layout/rss.md
View file

@ -24,28 +24,26 @@ all site content accessible from .Data.Pages
This rss template is used for [spf13.com](http://spf13.com). It adheres to the This rss template is used for [spf13.com](http://spf13.com). It adheres to the
ATOM 2.0 Spec. ATOM 2.0 Spec.
{{% highlight xml %}} <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> <channel>
<channel> <title>{{ .Title }} on {{ .Site.Title }} </title>
<title>{{ .Title }} on {{ .Site.Title }} </title> <link>{{ .Permalink }}</link>
<link>{{ .Permalink }}</link> <language>en-us</language>
<language>en-us</language> <author>Steve Francia</author>
<author>Steve Francia</author> <rights>Copyright (c) 2008 - 2013, Steve Francia; all rights reserved.</rights>
<rights>Copyright (c) 2008 - 2013, Steve Francia; all rights reserved.</rights> <updated>{{ .Date }}</updated>
<updated>{{ .Date }}</updated> {{ range .Data.Pages }}
{{ range .Data.Pages }} <item>
<item> <title>{{ .Title }}</title>
<title>{{ .Title }}</title> <link>{{ .Permalink }}</link>
<link>{{ .Permalink }}</link> <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</pubDate>
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 MST" }}</pubDate> <author>Steve Francia</author>
<author>Steve Francia</author> <guid>{{ .Permalink }}</guid>
<guid>{{ .Permalink }}</guid> <description>{{ .Content | html }}</description>
<description>{{ .Content | html }}</description> </item>
</item> {{ end }}
{{ end }} </channel>
</channel> </rss>
</rss>
{{% /highlight %}}
*Important: Hugo will automatically add the following header line to this file *Important: Hugo will automatically add the following header line to this file
on render...please don't include this in the template as it's not valid HTML.* on render...please don't include this in the template as it's not valid HTML.*

22
docs/content/layout/sitemap.md
View file

@ -28,18 +28,16 @@ site pages through `.Data.Pages`.
This template respects the version 0.9 of the [Sitemap This template respects the version 0.9 of the [Sitemap
Protocol](http://www.sitemaps.org/protocol.html). Protocol](http://www.sitemaps.org/protocol.html).
{{% highlight xml %}} <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> {{ range .Data.Pages }}
{{ range .Data.Pages }} <url>
<url> <loc>{{ .Permalink }}</loc>
<loc>{{ .Permalink }}</loc> <lastmod>{{ safeHtml ( .Date.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ with .Sitemap.ChangeFreq }}
<lastmod>{{ safeHtml ( .Date.Format "2006-01-02T15:04:05-07:00" ) }}</lastmod>{{ with .Sitemap.ChangeFreq }} <changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }}
<changefreq>{{ . }}</changefreq>{{ end }}{{ if ge .Sitemap.Priority 0.0 }} <priority>{{ .Sitemap.Priority }}</priority>{{ end }}
<priority>{{ .Sitemap.Priority }}</priority>{{ end }} </url>
</url> {{ end }}
{{ end }} </urlset>
</urlset>
{{% /highlight %}}
*Important: Hugo will automatically add the following header line to this file *Important: Hugo will automatically add the following header line to this file
on render...please don't include this in the template as it's not valid HTML.* on render...please don't include this in the template as it's not valid HTML.*

50
docs/content/layout/views.md
View file

@ -45,44 +45,38 @@ variables](/layout/variables) for a complete list.
## Example li.html ## Example li.html
This content template is used for [spf13.com](http://spf13.com). This content template is used for [spf13.com](http://spf13.com).
{{% highlight html %}} <li>
<li> <a href="{{ .Permalink }}">{{ .Title }}</a>
<a href="{{ .Permalink }}">{{ .Title }}</a> <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div> </li>
</li>
{{% /highlight %}}
## Example summary.html ## Example summary.html
This content template is used for [spf13.com](http://spf13.com). This content template is used for [spf13.com](http://spf13.com).
{{% highlight html %}} <article class="post">
<article class="post"> <header>
<header> <h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2> <div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div> </header>
</header>
{{ .Summary }} {{ .Summary }}
<footer> <footer>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a> <a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer> </footer>
</article> </article>
{{% /highlight %}}
## Example render of view ## Example render of view
Using the summary view inside of another ([index](/layout/index)) template. Using the summary view inside of another ([index](/layout/index)) template.
{{% highlight html %}} <section id="main">
<section id="main"> <div>
<div> <h1 id="title">{{ .Title }}</h1>
<h1 id="title">{{ .Title }}</h1> {{ range .Data.Pages }}
{{ range .Data.Pages }} {{ .Render "summary"}}
{{ .Render "summary"}} {{ end }}
{{ end }} </div>
</div> </section>
</section>
{{% /highlight %}}
In the above example you will notice that we have called .Render and passed in In the above example you will notice that we have called .Render and passed in
which view to render the content with. Render is a special function available on which view to render the content with. Render is a special function available on

81
docs/content/overview/configuration.md
View file

@ -23,36 +23,33 @@ then look for a `config.json` file, followed by a `config.toml` file.
## Examples ## Examples
The following is an example of a yaml config file with the default values: The following is an example of a yaml config file with the default values:
{{% highlight yaml %}}
--- ---
contentdir: "content" contentdir: "content"
layoutdir: "layouts" layoutdir: "layouts"
publishdir: "public" publishdir: "public"
builddrafts: false builddrafts: false
indexes: indexes:
category: "categories" category: "categories"
tag: "tags" tag: "tags"
baseurl: "http://yoursite.example.com/" baseurl: "http://yoursite.example.com/"
canonifyurls: true canonifyurls: true
... ...
{{% /highlight %}}
The following is an example of a json config file with the default values: The following is an example of a json config file with the default values:
{{% highlight json %}} {
{ "contentdir": "content",
"contentdir": "content", "layoutdir": "layouts",
"layoutdir": "layouts", "publishdir": "public",
"publishdir": "public", "builddrafts": false,
"builddrafts": false, "indexes": {
"indexes": { "category": "categories",
"category": "categories", "tag": "tags"
"tag": "tags" },
}, "baseurl": "http://yoursite.example.com/",
"baseurl": "http://yoursite.example.com/", "canonifyurls": true
"canonifyurls": true }
}
{{% /highlight %}}
The following is an example of a toml config file with the default values: The following is an example of a toml config file with the default values:
@ -68,19 +65,17 @@ The following is an example of a toml config file with the default values:
Here is a yaml configuration file which sets a few more options Here is a yaml configuration file which sets a few more options
{{% highlight yaml %}} ---
--- baseurl: "http://yoursite.example.com/"
baseurl: "http://yoursite.example.com/" title: "Yoyodyne Widget Blogging"
title: "Yoyodyne Widget Blogging" permalinks:
permalinks: post: /:year/:month/:title/
post: /:year/:month/:title/ params:
params: Subtitle: "Spinning the cogs in the widgets"
Subtitle: "Spinning the cogs in the widgets" AuthorName: "John Doe"
AuthorName: "John Doe" GitHubUser: "spf13"
GitHubUser: "spf13" ListOfFoo:
ListOfFoo: - "foo1"
- "foo1" - "foo2"
- "foo2" SidebarRecentLimit: 5
SidebarRecentLimit: 5 ...
...
{{% /highlight %}}

4
docs/content/overview/usage.md
View file

@ -63,7 +63,7 @@ your browser to view the changes.**
$ hugo -s ~/mysite --watch $ hugo -s ~/mysite --watch
28 pages created 28 pages created
0 tags index created 0 tags index created
in 38 ms in 18 ms
Watching for changes in /Users/spf13/Code/hugo/docs/content Watching for changes in /Users/spf13/Code/hugo/docs/content
Press ctrl+c to stop Press ctrl+c to stop
@ -75,5 +75,5 @@ Hugo can even run a server and create your site at the same time!
Press ctrl+c to stop Press ctrl+c to stop
28 pages created 28 pages created
0 tags created 0 tags created
in 28 ms in 18 ms

128
docs/content/tutorials/github_pages_blog.md
View file

@ -24,17 +24,15 @@ As our goal is to host a website using GitHub pages, it is natural for us to hos
The very first step in creating a new Hugo site is to [write the config file](/overview/configuration). This config file is important for at least two reasons: (1) this is where site-wide settings (like the websites `baseurl`) go and (2) the config file dictates to some extent how Hugo will generate the website. For the example website I created a file `config.yaml` with the following contents The very first step in creating a new Hugo site is to [write the config file](/overview/configuration). This config file is important for at least two reasons: (1) this is where site-wide settings (like the websites `baseurl`) go and (2) the config file dictates to some extent how Hugo will generate the website. For the example website I created a file `config.yaml` with the following contents
{{% highlight yaml %}} ---
--- contentdir: "content"
contentdir: "content" layoutdir: "layouts"
layoutdir: "layouts" publishdir: "public"
publishdir: "public" indexes:
indexes: category: "categories"
category: "categories" baseurl: "http://spencerlyon2.github.io/hugo_gh_blog"
baseurl: "http://spencerlyon2.github.io/hugo_gh_blog" title: "Hugo Blog Template for GitHub Pages"
title: "Hugo Blog Template for GitHub Pages" ...
...
{{% /highlight %}}
### Define Structure of Website ### Define Structure of Website
@ -82,17 +80,15 @@ Each of the files in the example repository is well commented with a description
The final step in creating the blog is to add some actual blog posts. To do this simply create one markdown file (with extension .md) for each new blog post. At the top of each file you should include a metadata section that tells Hugo some things about the post (see [docs](/content/front-matter)). For example, consider the yaml metadata section from the top of the file `/content/posts/newest.md` from the example repository The final step in creating the blog is to add some actual blog posts. To do this simply create one markdown file (with extension .md) for each new blog post. At the top of each file you should include a metadata section that tells Hugo some things about the post (see [docs](/content/front-matter)). For example, consider the yaml metadata section from the top of the file `/content/posts/newest.md` from the example repository
{{% highlight yaml %}} ---
--- title: "Just another sample post"
title: "Just another sample post" date: "2014-03-29"
date: "2014-03-29" description: "This should be a more useful description"
description: "This should be a more useful description" categories:
categories: - "hugo"
- "hugo" - "fun"
- "fun" - "test"
- "test" ---
---
{{% /highlight %}}
The keys set in this section are the mandatory `title` and `date` as well as the optional `description` and `categories`. Each of these items is used throughout the templates found in the `/layouts` directory and gives Hugo information about the post from other pages in the website. The keys set in this section are the mandatory `title` and `date` as well as the optional `description` and `categories`. Each of these items is used throughout the templates found in the `/layouts` directory and gives Hugo information about the post from other pages in the website.
@ -104,47 +100,45 @@ GitHub pages will serve up a website for any repository that has a branch called
To get this properly set up we will execute a series of commands at the terminal. I will include all of them in one place here for easy copy and paste, and will explain what each line does via comments. Note that this is to be run from the `<root>` directory (wherever the `content` and `layout` folders of your Hugo project live). Also note that you will need to change the commands that have the example repository GitHub address so that they point to your repo. To get this properly set up we will execute a series of commands at the terminal. I will include all of them in one place here for easy copy and paste, and will explain what each line does via comments. Note that this is to be run from the `<root>` directory (wherever the `content` and `layout` folders of your Hugo project live). Also note that you will need to change the commands that have the example repository GitHub address so that they point to your repo.
{{% highlight bash %}} # Create a new orphand branch (no commit history) named gh-pages
# Create a new orphand branch (no commit history) named gh-pages git checkout --orphan gh-pages
git checkout --orphan gh-pages
# Unstage all files # Unstage all files
git rm --cached $(git ls-files) git rm --cached $(git ls-files)
# Grab one file from the master branch so we can make a commit # Grab one file from the master branch so we can make a commit
git checkout master README.md git checkout master README.md
# Add and commit that file # Add and commit that file
git add . git add .
git commit -m "INIT: initial commit on gh-pages branch" git commit -m "INIT: initial commit on gh-pages branch"
# Push to remote gh-pages branch # Push to remote gh-pages branch
git push origin gh-pages git push origin gh-pages
# Return to master branch # Return to master branch
git checkout master git checkout master
# Remove the public folder to make room for the gh-pages subtree # Remove the public folder to make room for the gh-pages subtree
rm -rf public rm -rf public
# Add the gh-pages branch of the repository. It will look like a folder named public # Add the gh-pages branch of the repository. It will look like a folder named public
git subtree add --prefix public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages --squash git subtree add --prefix public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages --squash
# Pull down the file we just committed. This helps avoid merge conflicts # Pull down the file we just committed. This helps avoid merge conflicts
git subtree pull --prefix=public git subtree pull --prefix=public
# Run hugo. Generated site will be placed in public directory # Run hugo. Generated site will be placed in public directory
hugo hugo
# Add everything # Add everything
git add -A git add -A
# Commit and push to master # Commit and push to master
git commit -m "Updating site" && git push origin master git commit -m "Updating site" && git push origin master
# Push the public subtree to the gh-pages branch # Push the public subtree to the gh-pages branch
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
{{% /highlight %}}
After executing these commands and waiting for the GitHub servers to update, the website we just created was live at [http://spencerlyon2.github.io/hugo_gh_blog](http://spencerlyon2.github.io/hugo_gh_blog). After executing these commands and waiting for the GitHub servers to update, the website we just created was live at [http://spencerlyon2.github.io/hugo_gh_blog](http://spencerlyon2.github.io/hugo_gh_blog).
@ -161,28 +155,26 @@ Now, as you add new posts to your blog, you will follow steps that look somethin
The first two items in the previous list are simply a way to conveniently preview your content as you write. This is a dynamic and fairly streamlined process. All the remaining items, however, are the same every time you want to add new content to the website. To make this repetitive process easier, I have adapted a script from the source repository for the [Chimer Arta & Maker Space](https://github.com/chimera/chimeraarts.org) website that is highlighted in the [Hugo Showcase](/showcase). The script lives in a file called `deploy.sh` and has the following contents The first two items in the previous list are simply a way to conveniently preview your content as you write. This is a dynamic and fairly streamlined process. All the remaining items, however, are the same every time you want to add new content to the website. To make this repetitive process easier, I have adapted a script from the source repository for the [Chimer Arta & Maker Space](https://github.com/chimera/chimeraarts.org) website that is highlighted in the [Hugo Showcase](/showcase). The script lives in a file called `deploy.sh` and has the following contents
{{% highlight bash %}} #!/bin/bash
#!/bin/bash
echo -e "\033[0;32mDeploying updates to Github...\033[0m" echo -e "\033[0;32mDeploying updates to Github...\033[0m"
# Build the project. # Build the project.
hugo hugo
# Add changes to git. # Add changes to git.
git add -A git add -A
# Commit changes. # Commit changes.
msg="rebuilding site `date`" msg="rebuilding site `date`"
if [ $# -eq 1 ] if [ $# -eq 1 ]
then msg="$1" then msg="$1"
fi fi
git commit -m "$msg" git commit -m "$msg"
# Push source and build repos. # Push source and build repos.
git push origin master git push origin master
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
{{% /highlight %}}
Now I can replace the last four items from our workflow list with a single command `bash deploy.sh`. This script accepts as an optional argument the commit message that git should use when committing your changes. If you wish to include a custom commit message, do so by putting it quotes after calling bash on the script: `bash deploy.sh "<my commit msg>"`. If you choose not to specify the commit message, one will be generated for you using the current time. Now I can replace the last four items from our workflow list with a single command `bash deploy.sh`. This script accepts as an optional argument the commit message that git should use when committing your changes. If you wish to include a custom commit message, do so by putting it quotes after calling bash on the script: `bash deploy.sh "<my commit msg>"`. If you choose not to specify the commit message, one will be generated for you using the current time.

71
docs/content/tutorials/mathjax.md
View file

@ -18,11 +18,9 @@ This is not an introduction into actually using MathJax to render typeset mathem
The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventerous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by including the following html snippet in the source of a page: The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventerous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by including the following html snippet in the source of a page:
{{% highlight html %}} <script type="text/javascript"
<script type="text/javascript" src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> </script>
</script>
{{% /highlight %}}
One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/chrome/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/chrome/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
@ -40,48 +38,43 @@ There are multiple ways to remedy this problem. One solution is to simply escape
Another option is to tell markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem we could create a new css entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the html and css source that would accomplish this (note this solution adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html) -- all credit goes to the original author). Another option is to tell markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `<div>` `</div>` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `<div>` is not acceptable. The syntax for instructing markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem we could create a new css entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the html and css source that would accomplish this (note this solution adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html) -- all credit goes to the original author).
{{% highlight html %}} <script type="text/x-mathjax-config">
<script type="text/x-mathjax-config"> MathJax.Hub.Config({
MathJax.Hub.Config({ tex2jax: {
tex2jax: { inlineMath: [['$','$'], ['\\(','\\)']],
inlineMath: [['$','$'], ['\\(','\\)']], displayMath: [['$$','$$'], ['\[','\]']],
displayMath: [['$$','$$'], ['\[','\]']], processEscapes: true,
processEscapes: true, processEnvironments: true,
processEnvironments: true, skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'], TeX: { equationNumbers: { autoNumber: "AMS" },
TeX: { equationNumbers: { autoNumber: "AMS" }, extensions: ["AMSmath.js", "AMSsymbols.js"] }
extensions: ["AMSmath.js", "AMSsymbols.js"] } }
} });
}); </script>
</script>
<script type="text/x-mathjax-config"> <script type="text/x-mathjax-config">
MathJax.Hub.Queue(function() { MathJax.Hub.Queue(function() {
// Fix <code> tags after MathJax finishes running. This is a // Fix <code> tags after MathJax finishes running. This is a
// hack to overcome a shortcoming of Markdown. Discussion at // hack to overcome a shortcoming of Markdown. Discussion at
// https://github.com/mojombo/jekyll/issues/199 // https://github.com/mojombo/jekyll/issues/199
var all = MathJax.Hub.getAllJax(), i; var all = MathJax.Hub.getAllJax(), i;
for(i = 0; i < all.length; i += 1) { for(i = 0; i < all.length; i += 1) {
all[i].SourceElement().parentNode.className += ' has-jax'; all[i].SourceElement().parentNode.className += ' has-jax';
} }
}); });
</script> </script>
{{% /highlight %}}
As before, this content should be included in the html source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. As before, this content should be included in the html source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.
{{% highlight css %}} code.has-jax {font: inherit;
code.has-jax {font: inherit; font-size: 100%;
font-size: 100%; background: inherit;
background: inherit; border: inherit;
border: inherit; color: #515151;}
color: #515151;}
{{% /highlight %}}
In the css snippet notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my css. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. In the css snippet notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my css. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
### Usage ### Usage
With this setup, everything is inplace for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page! With this setup, everything is inplace for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!

172
docs/content/tutorials/migrate-from-jekyll.md
View file

@ -31,20 +31,18 @@ Hugo can read your configuration as json, yaml or toml. Hugo supports parameters
The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives: The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:
1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended). 1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
{{% highlight sh %}}
git submodule deinit _site git submodule deinit _site
git rm _site git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
{{% /highlight %}}
1. Or, change the Hugo configuration to use `_site` instead of `public`. 1. Or, change the Hugo configuration to use `_site` instead of `public`.
{{% highlight json %}}
{ {
.. ..
"publishdir": "_site", "publishdir": "_site",
.. ..
} }
{{% /highlight %}}
## Convert Jekyll templates to Hugo templates ## Convert Jekyll templates to Hugo templates
That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way. That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.
@ -58,94 +56,90 @@ Jekyll has [plugins](http://jekyllrb.com/docs/plugins/), Hugo has [shortcodes](/
As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing. As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.
Jekyll's plugin: Jekyll's plugin:
{{% highlight ruby %}}
module Jekyll module Jekyll
class ImageTag < Liquid::Tag class ImageTag < Liquid::Tag
@url = nil @url = nil
@caption = nil @caption = nil
@class = nil @class = nil
@link = nil @link = nil
// Patterns // Patterns
IMAGE_URL_WITH_CLASS_AND_CAPTION = IMAGE_URL_WITH_CLASS_AND_CAPTION =
IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens) def initialize(tag_name, markup, tokens)
super super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1 @class = $1
@url = $3 @url = $3
@caption = $7 @caption = $7
@link = $9 @link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1 @class = $1
@url = $3 @url = $3
@caption = $7 @caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1 @url = $1
@caption = $5 @caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1 @class = $1
@url = $3 @url = $3
elsif markup =~ IMAGE_URL elsif markup =~ IMAGE_URL
@url = $1 @url = $1
end
end
def render(context)
if @class
source = "<figure class='#{@class}'>"
else
source = "<figure>"
end
if @link
source += "<a href=\"#{@link}\">"
end
source += "<img src=\"#{@url}\">"
if @link
source += "</a>"
end
source += "<figcaption>#{@caption}</figcaption>" if @caption
source += "</figure>"
source
end
end end
end end
def render(context) Liquid::Template.register_tag('image', Jekyll::ImageTag)
if @class
source = "<figure class='#{@class}'>"
else
source = "<figure>"
end
if @link
source += "<a href=\"#{@link}\">"
end
source += "<img src=\"#{@url}\">"
if @link
source += "</a>"
end
source += "<figcaption>#{@caption}</figcaption>" if @caption
source += "</figure>"
source
end
end
end
Liquid::Template.register_tag('image', Jekyll::ImageTag)
{{% /highlight %}}
is written as this Hugo shortcode: is written as this Hugo shortcode:
{{% highlight html %}}
<!-- image --> <!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}> <figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }} {{ with .Get "link"}}<a href="{{.}}">{{ end }}
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} /> <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
{{ if .Get "link"}}</a>{{ end }} {{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }} <figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }} {{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p> {{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }} {{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }} {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }} {{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }} {{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }} </p> {{ end }}
</figcaption> </figcaption>
{{ end }} {{ end }}
</figure> </figure>
<!-- image --> <!-- image -->
{{% /highlight %}}
### Usage ### Usage
I simply changed: I simply changed:
{{% highlight html %}}
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %} {% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
{{% /highlight %}}
to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`): to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):
{{% highlight html %}}
{{% fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" %}} {{% fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" %}}
{{% /highlight %}}
As a bonus, the shortcode named parameters are, arguably, more readable. As a bonus, the shortcode named parameters are, arguably, more readable.

3
docs/layouts/chrome/includes.html
View file

@ -2,3 +2,6 @@
<link href="/static/css/styles.css" rel="stylesheet"/> <link href="/static/css/styles.css" rel="stylesheet"/>
<link href="/static/css/hugofont.css" rel="stylesheet"/> <link href="/static/css/hugofont.css" rel="stylesheet"/>
<link href='http://fonts.googleapis.com/css?family=Arbutus+Slab&family=Cabin:600&family=Source+Code+Pro' rel='stylesheet' type='text/css'> <link href='http://fonts.googleapis.com/css?family=Arbutus+Slab&family=Cabin:600&family=Source+Code+Pro' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="/static/css/monokai_sublime.css">
<script src="/static/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

149
docs/static/static/css/monokai_sublime.css vendored Normal file
View file

@ -0,0 +1,149 @@
/*
Monokai Sublime style. Derived from Monokai by noformnocontent http://nn.mit-license.org/
*/
.hljs {
display: block;
padding: 0.5em;
background: #23241f;
}
.hljs,
.hljs-tag,
.css .hljs-rules,
.css .hljs-value,
.css .hljs-function
.hljs-preprocessor,
.hljs-pragma {
color: #f8f8f2;
}
.hljs-strongemphasis,
.hljs-strong,
.hljs-emphasis {
color: #a8a8a2;
}
.hljs-bullet,
.hljs-blockquote,
.hljs-horizontal_rule,
.hljs-number,
.hljs-regexp,
.alias .hljs-keyword,
.hljs-literal,
.hljs-hexcolor {
color: #ae81ff;
}
.hljs-tag .hljs-value,
.hljs-code,
.hljs-title,
.css .hljs-class,
.hljs-class .hljs-title:last-child {
color: #a6e22e;
}
.hljs-link_url {
font-size: 80%;
}
.hljs-strong,
.hljs-strongemphasis {
font-weight: bold;
}
.hljs-emphasis,
.hljs-strongemphasis,
.hljs-class .hljs-title:last-child {
font-style: italic;
}
.hljs-keyword,
.hljs-function,
.hljs-change,
.hljs-winutils,
.hljs-flow,
.lisp .hljs-title,
.clojure .hljs-built_in,
.nginx .hljs-title,
.tex .hljs-special,
.hljs-header,
.hljs-attribute,
.hljs-symbol,
.hljs-symbol .hljs-string,
.hljs-tag .hljs-title,
.hljs-value,
.alias .hljs-keyword:first-child,
.css .hljs-tag,
.css .unit,
.css .hljs-important {
color: #F92672;
}
.hljs-function .hljs-keyword,
.hljs-class .hljs-keyword:first-child,
.hljs-constant,
.css .hljs-attribute {
color: #66d9ef;
}
.hljs-variable,
.hljs-params,
.hljs-class .hljs-title {
color: #f8f8f2;
}
.hljs-string,
.css .hljs-id,
.hljs-subst,
.haskell .hljs-type,
.ruby .hljs-class .hljs-parent,
.hljs-built_in,
.sql .hljs-aggregate,
.django .hljs-template_tag,
.django .hljs-variable,
.smalltalk .hljs-class,
.django .hljs-filter .hljs-argument,
.smalltalk .hljs-localvars,
.smalltalk .hljs-array,
.hljs-attr_selector,
.hljs-pseudo,
.hljs-addition,
.hljs-stream,
.hljs-envvar,
.apache .hljs-tag,
.apache .hljs-cbracket,
.tex .hljs-command,
.hljs-prompt,
.hljs-link_label,
.hljs-link_url {
color: #e6db74;
}
.hljs-comment,
.hljs-javadoc,
.java .hljs-annotation,
.python .hljs-decorator,
.hljs-template_comment,
.hljs-pi,
.hljs-doctype,
.hljs-deletion,
.hljs-shebang,
.apache .hljs-sqbracket,
.tex .hljs-formula {
color: #75715e;
}
.coffeescript .javascript,
.javascript .xml,
.tex .hljs-formula,
.xml .javascript,
.xml .vbscript,
.xml .css,
.xml .hljs-cdata,
.xml .php,
.php .xml {
opacity: 0.5;
}

1
docs/static/static/js/highlight.pack.js vendored Normal file
View file

File diff suppressed because one or more lines are too long