weight: 30
---
-All contributions to Hugo are welcome. Whether you want to scratch an itch, or simply contribute to the project. Feel free to pick something from the roadmap
+All contributions to Hugo are welcome. Whether you want to scratch an itch, or simply contribute to the project, feel free to pick something from the roadmap
or contact [spf13](http://spf13.com) about what may make sense
to do next.
* Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
* Run `go fmt`
* Squash your commits into a single commit. `git rebase -i`. It's okay to force update your pull request.
- * Make sure `go test ./...` passes, and go build completes. Our Travis CI loop will catch most things that are missing. The exception: Windows. We run on windows from time to time, but if you have access please check on a Windows machine too.
+ * Make sure `go test ./...` passes, and `go build` completes. Our Travis CI loop will catch most things that are missing. The exception: Windows. We run on Windows from time to time, but if you have access, please check on a Windows machine too.
## Contribution Overview
cd hugo
go get
-Because go expects all of your libraries to be found in either
+Because Go expects all of your libraries to be found in either
$GOROOT or $GOPATH, it's helpful to symlink the project to one
of the following paths:
## GoNuts
-For general go questions or discussion please refer to the go mailing list.
+For general Go questions or discussion please refer to the Go mailing list.
https://groups.google.com/forum/#!forum/golang-nuts
-## Github Issues
+## GitHub Issues
https://github.com/spf13/hugo/issues
## Twitter
-Hugo doesn't have it's own twitter handle, but feel free to tweet [@spf13](http://twitter.com/spf13).
+Hugo doesn't have its own Twitter handle, but feel free to tweet [@spf13](http://twitter.com/spf13).
### Optional
* **redirect** Mark the post as a redirect post
-* **draft** If true the content will not be rendered unless hugo is called with --buildDrafts
-* **publishdate** If in the future, content will not be rendered unless hugo is called with --buildFuture
+* **draft** If true, the content will not be rendered unless `hugo` is called with `--buildDrafts`
+* **publishdate** If in the future, content will not be rendered unless `hugo` is called with `--buildFuture`
* **type** The type of the content (will be derived from the directory automatically if unset)
* **weight** Used for sorting
* **markup** (Experimental) Specify "rst" for reStructuredText (requires
`rst2html`,) or "md" (default) for the Markdown
-* **slug** The token to appear in the tail of the url
+* **slug** The token to appear in the tail of the URL
*or*<br>
* **url** The full path to the content from the web root.<br>
-*If neither slug or url is present the filename will be used.*
+*If neither slug or url is present, the filename will be used.*
-\-uglyurls setting.
-## Path breakdown in hugo
+## Path breakdown in Hugo
### Content
* based on content-name.md
* front matter overrides
-**path** = section + path to file exluding slug
+**path** = section + path to file excluding slug
* based on path to content location
-**url** = relative url
+**url** = relative URL
* defined in front matter
* overrides all the above
Hugo thinks that you organize your content with a purpose. The same structure
that works to organize your source content is used to organize the rendered
-site ( [see organization](/content/organization) ). Following this pattern Hugo
+site (see [Organization](/content/organization)). Following this pattern Hugo
uses the top level of your content organization as **the Section**.
The following example site uses two sections, "post" and "quote".
Section defined in the front matter have the same impact.
-To change the type of a given piece of content simply define the type
+To change the type of a given piece of content, simply define the type
in the front matter.
-If a layout for a given type hasn't been provided a default type template will
-be used instead provided is exists.
+If a layout for a given type hasn't been provided, a default type template will
+be used instead provided it exists.
weight: 10
---
-For people migrating existing published content to Hugo theres 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.
## New Site
-Want to get a site built quickly?.
+Want to get a site built quickly?
hugo new site /path/to/site
via an embedded shortcode. If pygments is absent from the path, it will
silently simply pass the content along unhighlighted.
-## Server Side
+## Server-side
### Disclaimers
- * **Warning** pygments is relatively slow. Expect much longer build times when using server side highlighting.
- * Languages available depends on your pygments installation.
+ * **Warning:** Pygments is relatively slow. Expect much longer build times when using server-side highlighting.
+ * Languages available depends on your Pygments installation.
* Styles are inline in order to be supported in syndicated content when references
to style sheets are not carried over.
* We have sought to have the simplest interface possible, which consequently
## What is a menu?
A menus is a named array of menu entries accessible on the site under
-.Site.Menus by name. For example if I have a menu called `main` I would
-access it via .Site.Menus.main.
+`.Site.Menus` by name. For example if I have a menu called `main` I would
+access it via `.Site.Menus.main`.
A menu entry has the following properties:
## Rendering menus
Hugo makes no assumptions about how your rendered HTML will be
-structured, instead it provides all of the functions you will need to be
+structured. Instead, it provides all of the functions you will need to be
able to build your menu however you want.
weight: 60
---
-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
your content.
Simply create content like you normally would with the appropriate
headers.
-Hugo will take this markdown and create a table of contents stored in the
-[content variable](/layout/variables) .TableOfContents
+Hugo will take this Markdown and create a table of contents stored in the
+[content variable](/layout/variables) `.TableOfContents`
## Template Example
weight: 70
---
-## Pretty Urls
+## Pretty URLs
-By default Hugo will create content with 'pretty' urls. For example
+By default Hugo will create content with 'pretty' URLs. For example
content created at /content/extras/urls.md will be rendered at
/content/extras/urls/index.html and accessible at /content/extras/urls. No
no standard server side configuration is required for these pretty urls to
work.
-If you would like to have uglyurls you are in luck. Hugo supports the
-ability to create your entire site with ugly urls. Simply use the
+If you would like to have ugly URLs, you are in luck. Hugo supports the
+ability to create your entire site with ugly URLs. Simply use the
`--uglyurls=true` flag on the command line.
-If you want a specific piece of content to have an exact url you can
+If you want a specific piece of content to have an exact URL, you can
specify this in the front matter under the url key. See [Content
Organization](/content/organization/) for more details.
In no particular order, here is what we are working on:
* Intelligently Related Posts
- * Even easier deployment to S3, SSH, Github, rsync
- * Import from other website systems (wordpress, jekyll)
+ * Even easier deployment to S3, SSH, GitHub, rsync
+ * Import from other website systems (WordPress, Jekyll)
* An interactive web based editor
- * Additional Themes
+ * Additional themes
* Dynamic image resizing via shortcodes
* Support for additional formats
* Pagination
weight: 20
---
-Hugo is written in Go with support for Windows, Linux, FreeBSD and OSX.
+Hugo is written in Go with support for Windows, Linux, FreeBSD and OS X.
-The latest release can be found at [hugo releases](https://github.com/spf13/hugo/releases).
-We currently build for Windows, Linux, FreeBSD and OS X for x64
-and 386 architectures.
+The latest release can be found at [Hugo Releases](https://github.com/spf13/hugo/releases).
+We currently build for Windows, Linux, FreeBSD and OS X for x64
+and i386 architectures.
## Installing Hugo (binary)
Installation is very easy. Simply download the appropriate version for your
-platform from [hugo releases](https://github.com/spf13/hugo/releases).
+platform from [Hugo Releases](https://github.com/spf13/hugo/releases).
Once downloaded it can be run from anywhere. You don't need to install
it into a global location. This works well for shared hosts and other systems
where you don't have a privileged account.
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
is the most probable location.
-### Installing pygments (optional)
+### Installing Pygments (optional)
-The Hugo executable has one *optional* external dependency for source code highlighting (pygments).
+The Hugo executable has one *optional* external dependency for source code highlighting (Pygments).
-If you want to have source code highlighting using the [highlight shortcode](/extras/highlighting)
-you need to install the python-based pygments program. The procedure is outlined on the [pygments home page](http://pygments.org).
+If you want to have source code highlighting using the [highlight shortcode](/extras/highlighting),
+you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments home page](http://pygments.org).
## Upgrading Hugo
-Upgrading hugo is as easy as downloading and replacing the executable you’ve
+Upgrading Hugo is as easy as downloading and replacing the executable you’ve
placed in your path.
* Mercurial
* Bazaar
-### Get directly from Github:
+### Get directly from GitHub:
- go get github.com/spf13/hugo
+ go get -v github.com/spf13/hugo
### Building Hugo
## Contributing
-Please see the [contributing guide](/doc/contributing)
+Please see the [contributing guide](/doc/contributing).
## What is Hugo?
-Hugo is a general purpose website framework. Technically speaking, Hugo is
-a static site generator. This means that unlike systems like Wordpress,
-Ghost & Drupal which run on your web server expensively building a page
+Hugo is a general-purpose website framework. Technically speaking, Hugo is
+a static site generator. This means that unlike systems like WordPress,
+Ghost and Drupal which run on your web server expensively building a page
every time a visitor requests one, Hugo does the building when you create
your content. Since websites are viewed far more often then they are
edited, Hugo is optimized for website viewing while providing a great
-writing experience.
+writing experience.
-Sites built with hugo are extremely fast and very secure. Hugo sites can
+Sites built with Hugo are extremely fast and very secure. Hugo sites can
be hosted anywhere including Heroku, GoDaddy, GitHub pages, S3
-& Cloudfront and work well with CDNs. Hugo sites run without dependencies
+and Cloudfront and work well with CDNs. Hugo sites run without dependencies
on expensive run times like Ruby, Python or PHP and without dependencies
on any databases.
We think of Hugo as the ideal website creation tool. With nearly instant
-built times and the ability to rebuild whenever a change is made Hugo
+build times and the ability to rebuild whenever a change is made, Hugo
provides a very fast feedback loop. This is essential when you are
-designing websites, but also very useful when creating content.
+designing websites, but also very useful when creating content.
## What does Hugo do?
-In technical terms Hugo takes a source directory of markdown files and
-templates and uses these as input to create a complete website.
+In technical terms Hugo takes a source directory of Markdown files and
+templates and uses these as input to create a complete website.
Hugo boasts the following features:
### General
- * Extremely fast built times (~1ms per page)
- * Completely cross platform: Runs on Mac OSX, Linux and Windows
+ * Extremely fast build times (~1 ms per page)
+ * Completely cross platform: Runs on Mac OS X, Linux and Windows
* Easy [installation](/overview/installing)
* Render changes [on the fly](/overview/usage) with [live reload](/extras/livereload) as you develop
* Complete theme support
* Straightforward [organization](/content/organization)
* Support for [website sections](/content/sections)
- * Completely customizable [urls](/extras/urls)
+ * Completely customizable [URLs](/extras/urls)
* Support for configurable [taxonomies](/indexes/overview) which includes categories and tags. Create your own custom organization of content
* Ability to [sort content](/content/ordering) as you desire
* Automatic [table of contents](/extras/toc) generation
* Dynamic menu creation
- * [pretty urls](/extras/urls) support
- * [permalink](/extras/permalinks) pattern support
+ * [Pretty URLs](/extras/urls) support
+ * [Permalink](/extras/permalinks) pattern support
* [Aliases](/extras/aliases) (redirects)
### Content
* Completely [customizable homepage](/layout/homepage)
* Support for multiple [content types](/content/types)
* Automatic and user defined [summaries](/content/summaries)
- * [shortcodes](/extras/shortcodes) to enable rich content inside of markdown
+ * [shortcodes](/extras/shortcodes) to enable rich content inside of Markdown
* ["Minutes to Read"](/layout/variables) functionality
* ["Wordcount"](/layout/variables) functionality
* Integrated Disqus comment support
* Automatic [RSS](/layout/rss) creation
- * Support for go and amber templates
+ * Support for Go and [Amber](https://github.com/eknkc/amber) templates
* Syntax [highlighting](/extras/highlighting) powered by pygments
See what's coming next in the [roadmap](/meta/roadmap)
Hugo is for people who want to hand code their own website without
worrying about setting up complicated runtimes, dependencies and
-databases.
+databases.
Hugo is for people building a blog, company site, portfolio, tumblog,
documentation, single page site or a site with thousands of
-pages.
+pages.
## Why did you write Hugo?
I wrote Hugo ultimately for a few reasons. First I was disappointed with
-wordpress, my then website solution. It rendered slowly. I couldn't create
+WordPress, my then website solution. It rendered slowly. I couldn't create
content as efficiently as I wanted to and needed to be online to write
posts. The constant security updates and the horror stories of people's
hacked blogs. I hated how content was written in HTML instead of the much
-simpler markdown. Overall I felt like it got in my way more than it helped
+simpler Markdown. Overall I felt like it got in my way more than it helped
my from writing great content.
-I looked at existing static site generators like Jekyll, Middle and Nanoc.
+I looked at existing static site generators like Jekyll, Middleman and nanoc.
All had complicated dependencies to install and took far longer to render
my blog with hundreds of posts than I felt was acceptable. I wanted
a framework to be able to get rapid feedback while making changes to the
-templates and the 5+ minute render times was just too slow. In general
+templates and the 5+-minute render times was just too slow. In general
they were also very blog minded and didn't have the ability to have
-different content types and flexible urls.
+different content types and flexible URLs.
I wanted to develop a fast and full featured website framework without
dependencies. The Go language seemed to have all of the features I needed
* [Install Hugo](/overview/installing)
* [Quick start](/overview/quickstart)
* [Join the Mailing List](/community/mailing-list)
- * [Star us on Github](http://github.com/spf13/hugo)
+ * [Star us on GitHub](http://github.com/spf13/hugo)
## Step 1. Install Hugo
-Goto [hugo releases](https://github.com/spf13/hugo/releases) and download the
+Go to [Hugo Releases](https://github.com/spf13/hugo/releases) and download the
appropriate version for your os and architecture.
Save it somewhere specific as we will be using it in the next step.
-More complete instructions are available at [installing hugo](/overview/installing/)
+More complete instructions are available at [Installing Hugo](/overview/installing/)
## Step 2. Have Hugo Create a site for you
Notice the date is automatically set to the moment you created the content.
-Place some content in this file below the `+++` in the markdown format.
+Place some content in this file below the `+++` in the Markdown format.
For example you could put this
Some Content
-For fun, let’s create another piece of content and place some markdown in it as well.
+For fun, let’s create another piece of content and place some Markdown in it as well.
hugo new post/first.md
## Step 5. Run Hugo
-Hugo contains it’s own high performance web server. Simply run `hugo
+Hugo contains its own high performance web server. Simply run `hugo
server` and Hugo will find an available port and run a server with
-your content
+your content:
hugo server --theme=hyde --buildDrafts
2 pages created
Web Server is available at http://localhost:1313
Press ctrl+c to stop
-We specified two options here.
+We specified two options here:
- * `--theme` to pick which theme.
- * `--buildDrafts` because we want to display our content, both set to draft status
+ * `--theme` to pick which theme;
+ * `--buildDrafts` because we want to display our content, both set to draft status.
-To learn about what other options hugo has run
+To learn about what other options hugo has, run:
hugo help
-To learn about the server options
+To learn about the server options:
hugo help server
It’s especially productive to leave a browser open on a second monitor
and just glance at it whenever you save. You don’t even need to tab to
-your browser. Hugo is so fast, that the new site will be there before
+your browser. Hugo is so fast that the new site will be there before
you can look at the browser in most cases.
Change and save this file. Notice what happened in your terminal.
* Add a [new content file](/content/organization/)
* Create a [new section](/content/sections/)
* Modify [a template](/layout/templates/)
- * Create content with [toml front matter](/content/front-matter/)
+ * Create content with [TOML front matter](/content/front-matter/)
* Define your own field in [front matter](/content/front-matter/)
* Display that [field in the template](/layout/variables/)
* Create a [new content type](/content/types/)
hugo [command]
Available Commands:
- server :: Hugo runs it's own a webserver to render the files
+ server :: Hugo runs its own a webserver to render the files
version :: Print the version number of Hugo
check :: Check content in the source directory
benchmark :: Benchmark hugo by building a site a number of times
demonstrate relationships in a variety of logical ways.
The default taxonomies for Hugo are tags and categories. These
-taxonomies are common to many websites systems (Wordpress, Drupal,
-Jekyll). Unlike all of those Systems, Hugo makes it trivial to customize
+taxonomies are common to many website systems (WordPress, Drupal,
+Jekyll). Unlike all of those systems, Hugo makes it trivial to customize
the taxonomies you will be using for your site however you wish. Another
good use for taxonomies is to group a set of posts into a series. Other
common uses would include categories, tags, groups, series and many
weight: 100
---
-When using Hugo with [github pages](http://pages.github.com/) you can provide
+When using Hugo with [GitHub Pages](http://pages.github.com/) you can provide
your own 404 template by creating a 404.html file in the root.
404 pages are of the type "node" and have all the [node
weight: 20
---
-Hugo uses the excellent go html/template library for its template engine.
+Hugo uses the excellent Go html/template library for its template engine.
It is an extremely lightweight engine that provides a very small amount of
-logic. In our experience that it is just the right amount of logic to be able
+logic. In our experience it is just the right amount of logic to be able
to create a good static website.
Go templates are lightweight but extensible. Hugo has added the following
weight: 15
---
-Hugo uses the excellent [go][] [html/template][gohtmltemplate] library for
+Hugo uses the excellent [Go][] [html/template][gohtmltemplate] library for
its template engine. It is an extremely lightweight engine that provides a very
-small amount of logic. In our experience that it is just the right amount of
+small amount of logic. In our experience it is just the right amount of
logic to be able to create a good static website. If you have used other
-template systems from different languages or frameworks you will find a lot of
-similarities in go templates.
+template systems from different languages or frameworks, you will find a lot of
+similarities in Go templates.
-This document is a brief primer on using go templates. The [go docs][gohtmltemplate]
+This document is a brief primer on using Go templates. The [Go docs][gohtmltemplate]
provide more details.
## Introduction to Go Templates
Go templates provide an extremely simple template language. It adheres to the
belief that only the most basic of logic belongs in the template or view layer.
-One consequence of this simplicity is that go templates parse very quickly.
+One consequence of this simplicity is that Go templates parse very quickly.
-A unique characteristic of go templates is they are content aware. Variables and
+A unique characteristic of Go templates is they are content aware. Variables and
content will be sanitized depending on the context of where they are used. More
-details can be found in the [go docs][gohtmltemplate].
+details can be found in the [Go docs][gohtmltemplate].
## Basic Syntax
## Variables
-Each go template has a struct (object) made available to it. In hugo each
+Each Go template has a struct (object) made available to it. In Hugo each
template is passed either a page or a node struct depending on which type of
page you are rendering. More details are available on the
[variables](/layout/variables) page.
### Iteration
-Just like in go, the go templates make heavy use of range to iterate over
+Just like in Go, the Go templates make heavy use of range to iterate over
a map, array or slice. The following are different examples of how to use
range.
## Pipes
-One of the most powerful components of go templates is the ability to
+One of the most powerful components of Go templates is the ability to
stack actions one after another. This is done by using pipes. Borrowed
from unix pipes, the concept is simple, each pipeline's output becomes the
input of the following pipe.
-Because of the very simple syntax of go templates, the pipe is essential
+Because of the very simple syntax of Go templates, the pipe is essential
to being able to chain together function calls. One limitation of the
pipes is that they only can work with a single value and that value
becomes the last parameter of the next pipeline.
<script src="html5shiv.js"></script>
{{ "<![endif]-->" | safeHtml }}
-## Context (aka. the dot)
+## Context (a.k.a. the dot)
-The most easily overlooked concept to understand about go templates is that {{ . }}
+The most easily overlooked concept to understand about Go templates is that `{{ . }}`
always refers to the current context. In the top level of your template this
will be the data set made available to it. Inside of a iteration it will have
-the value of the current item. When inside of a loop the context has changed. .
-will no longer refer to the data available to the entire page. If you need to
-access this from within the loop you will likely want to set it to a variable
+the value of the current item. When inside of a loop the context has changed.
+`.` will no longer refer to the data available to the entire page. If you need
+to
+access this from within the loop, you will likely want to set it to a variable
instead of depending on the context.
**Example:**
<li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li>
{{ end }}
-Notice how once we have entered the loop the value of {{ . }} has changed. We
+Notice how once we have entered the loop the value of `{{ . }}` has changed. We
have defined a variable outside of the loop so we have access to it from within
the loop.
weight: 10
---
-Hugo uses the excellent go html/template library for its template engine.
+Hugo uses the excellent Go html/template library for its template engine.
It is an extremely lightweight engine that provides a very small amount of
-logic. In our experience that it is just the right amount of logic to be able
+logic. In our experience it is just the right amount of logic to be able
to create a good static website.
While Hugo has a number of different template roles, most complete
websites can be built using just a small number of template files.
Please don’t be afraid of the variety of different template roles. They
-are enable Hugo to build very complicated sites. Most sites will only
+enable Hugo to build very complicated sites. Most sites will only
need to create a [/layouts/\_default/single.html](/templates/content) & [/layouts/\_default/list.html](/templates/list)
-If you are new to go's templates the [go template primer](/layout/go-templates)
+If you are new to Go's templates, the [Go Template Primer](/layout/go-templates)
is a great place to start.
-If you are familiar with go’s templates, Hugo provides some [additional
+If you are familiar with Go’s templates, Hugo provides some [additional
template functions](/templates/functions) and [variables](/templates/variables) you will want to be familiar
with.
Different ways of rendering a (single) content type
### [Taxonomy Terms](/templates/terms)
-A list of the terms used for a specific taxonomy eg. a Tag cloud
+A list of the terms used for a specific taxonomy, e.g. a Tag cloud
## Other Templates (generally unnecessary)
Used to render the XML sitemap
### [404](/templates/404)
-This template will create a 404.html page used when hosting on github pages
+This template will create a 404.html page used when hosting on GitHub Pages
---
A single Sitemap template is used to generate the `sitemap.xml` file.
-Hugo Automatically comes with this template file. **No work is needed on
+Hugo automatically comes with this template file. **No work is needed on
the users part unless they want to customize the sitemap.xml.**
This page is of the type "node" and have all the [node
**.Keywords** The meta keywords for this content.<br>
**.Date** The date the content is associated with.<br>
**.PublishDate** The date the content is published on.<br>
-**.Type** The content [type](/content/types/) (eg. post)<br>
+**.Type** The content [type](/content/types/) (e.g. post)<br>
**.Section** The [section](/content/sections/) this content belongs to<br>
**.Permalink** The Permanent link for this page.<br>
**.RelPermalink** The Relative permanent link for this page.<br>
`hugo new theme [name]`
This command will initialize all of the files and directories a basic theme
-would need. Hugo themes are written in the go template language. If you are new
-to Go, the [go template primer](/layout/go-templates/) will help you get started.
+would need. Hugo themes are written in the Go template language. If you are new
+to Go, the [Go template primer](/layout/go-templates/) will help you get started.
## Theme Components
## What is MathJax?
-[MathJax](http://www.mathjax.org/) is a JavaScript library that allows allows the display of mathematical expressions described via a LaTeX-style syntax in the html (or markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.
+[MathJax](http://www.mathjax.org/) is a JavaScript library that allows allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here.
This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo.
## Enabling MathJax
-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:
<script type="text/javascript"
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
## Issues with Markdown
-After enabling MathJax, any math entered in-between proper markers (see documentation) will be processed and typeset in the web page. One issue that comes up, however, with markdown is that the underscore character (`_`) is interpreted by markdown as a way to wrap text in `emph` blocks while LaTex (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior.
+After enabling MathJax, any math entered in-between proper markers (see documentation) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior.
### Solution
There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts.
-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).
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
});
</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.
+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.
code.has-jax {font: inherit;
You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.
## A pratical example in a diff
-[Hey, it's alex](http://heyitsalex.net) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).
+[Hey, it's Alex](http://heyitsalex.net) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).
projects / brevno-suite / hugo / commitdiff