mirror/gohugoio-hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-05-11 05:54:58 +00:00
Code Issues Releases 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
Download Patch File Download Diff File Expand all files Collapse all files

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
{{% highlight yaml %}}
---
contentdir: "content"
layoutdir: "layouts"
publishdir: "public"
indexes:
category: "categories"
baseurl: "http://spencerlyon2.github.io/hugo_gh_blog"
title: "Hugo Blog Template for GitHub Pages"
...
{{% /highlight %}}
---
contentdir: "content"
layoutdir: "layouts"
publishdir: "public"
indexes:
category: "categories"
baseurl: "http://spencerlyon2.github.io/hugo_gh_blog"
title: "Hugo Blog Template for GitHub Pages"
...
### 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
{{% highlight yaml %}}
---
title: "Just another sample post"
date: "2014-03-29"
description: "This should be a more useful description"
categories:
- "hugo"
- "fun"
- "test"
---
{{% /highlight %}}
---
title: "Just another sample post"
date: "2014-03-29"
description: "This should be a more useful description"
categories:
- "hugo"
- "fun"
- "test"
---
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.
{{% highlight bash %}}
# Create a new orphand branch (no commit history) named gh-pages
git checkout --orphan gh-pages
# Create a new orphand branch (no commit history) named gh-pages
git checkout --orphan gh-pages
# Unstage all files
git rm --cached $(git ls-files)
# Unstage all files
git rm --cached $(git ls-files)
# Grab one file from the master branch so we can make a commit
git checkout master README.md
# Grab one file from the master branch so we can make a commit
git checkout master README.md
# Add and commit that file
git add .
git commit -m "INIT: initial commit on gh-pages branch"
# Add and commit that file
git add .
git commit -m "INIT: initial commit on gh-pages branch"
# Push to remote gh-pages branch
git push origin gh-pages
# Push to remote gh-pages branch
git push origin gh-pages
# Return to master branch
git checkout master
# Return to master branch
git checkout master
# Remove the public folder to make room for the gh-pages subtree
rm -rf public
# Remove the public folder to make room for the gh-pages subtree
rm -rf 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
# 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
# Pull down the file we just committed. This helps avoid merge conflicts
git subtree pull --prefix=public
# Pull down the file we just committed. This helps avoid merge conflicts
git subtree pull --prefix=public
# Run hugo. Generated site will be placed in public directory
hugo
# Run hugo. Generated site will be placed in public directory
hugo
# Add everything
git add -A
# Add everything
git add -A
# Commit and push to master
git commit -m "Updating site" && git push origin master
# Commit and push to master
git commit -m "Updating site" && git push origin master
# Push the public subtree to the gh-pages branch
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
{{% /highlight %}}
# Push the public subtree to the gh-pages branch
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
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
{{% 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.
hugo
# Build the project.
hugo
# Add changes to git.
git add -A
# Add changes to git.
git add -A
# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
then msg="$1"
fi
git commit -m "$msg"
# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
then msg="$1"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
{{% /highlight %}}
# Push source and build repos.
git push origin master
git subtree push --prefix=public git@github.com:spencerlyon2/hugo_gh_blog.git gh-pages
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:
{{% highlight html %}}
<script type="text/javascript"
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
{{% /highlight %}}
<script type="text/javascript"
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
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).
{{% highlight html %}}
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
inlineMath: [['$','$'], ['\\(','\\)']],
displayMath: [['$$','$$'], ['\[','\]']],
processEscapes: true,
processEnvironments: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
TeX: { equationNumbers: { autoNumber: "AMS" },
extensions: ["AMSmath.js", "AMSsymbols.js"] }
}
});
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
inlineMath: [['$','$'], ['\\(','\\)']],
displayMath: [['$$','$$'], ['\[','\]']],
processEscapes: true,
processEnvironments: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
TeX: { equationNumbers: { autoNumber: "AMS" },
extensions: ["AMSmath.js", "AMSsymbols.js"] }
}
});
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Queue(function() {
// Fix <code> tags after MathJax finishes running. This is a
// hack to overcome a shortcoming of Markdown. Discussion at
// https://github.com/mojombo/jekyll/issues/199
var all = MathJax.Hub.getAllJax(), i;
for(i = 0; i < all.length; i += 1) {
all[i].SourceElement().parentNode.className += ' has-jax';
}
});
</script>
{{% /highlight %}}
<script type="text/x-mathjax-config">
MathJax.Hub.Queue(function() {
// Fix <code> tags after MathJax finishes running. This is a
// hack to overcome a shortcoming of Markdown. Discussion at
// https://github.com/mojombo/jekyll/issues/199
var all = MathJax.Hub.getAllJax(), i;
for(i = 0; i < all.length; i += 1) {
all[i].SourceElement().parentNode.className += ' has-jax';
}
});
</script>
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;
font-size: 100%;
background: inherit;
border: inherit;
color: #515151;}
{{% /highlight %}}
code.has-jax {font: inherit;
font-size: 100%;
background: inherit;
border: inherit;
color: #515151;}
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
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:
1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
{{% highlight sh %}}
git submodule deinit _site
git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
{{% /highlight %}}
git submodule deinit _site
git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
1. Or, change the Hugo configuration to use `_site` instead of `public`.
{{% highlight json %}}
{
..
"publishdir": "_site",
..
}
{{% /highlight %}}
{
..
"publishdir": "_site",
..
}
## 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.
@@ -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.
Jekyll's plugin:
{{% highlight ruby %}}
module Jekyll
class ImageTag < Liquid::Tag
@url = nil
@caption = nil
@class = nil
@link = nil
// Patterns
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_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens)
super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1
@url = $3
@caption = $7
@link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1
@url = $3
@caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1
@caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1
@url = $3
elsif markup =~ IMAGE_URL
@url = $1
module Jekyll
class ImageTag < Liquid::Tag
@url = nil
@caption = nil
@class = nil
@link = nil
// Patterns
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_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens)
super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1
@url = $3
@caption = $7
@link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1
@url = $3
@caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1
@caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1
@url = $3
elsif markup =~ IMAGE_URL
@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
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
Liquid::Template.register_tag('image', Jekyll::ImageTag)
{{% /highlight %}}
Liquid::Template.register_tag('image', Jekyll::ImageTag)
is written as this Hugo shortcode:
{{% highlight html %}}
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ 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 }} />
{{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
{{% /highlight %}}
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ 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 }} />
{{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
### Usage
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/ %}
{{% /highlight %}}
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/" %}}
{{% /highlight %}}
As a bonus, the shortcode named parameters are, arguably, more readable.