mirror of
https://github.com/gohugoio/hugo.git
synced 2024-07-05 08:42:12 +00:00
Minor proofreading corrections to Hugo docs
This commit is contained in:
Anthony Fok
spf13
parent
f142458c4b
commit
a6022293af
|
|
@ -12,7 +12,7 @@ title: Contributing to Hugo
|
||||||
weight: 30
|
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
|
or contact [spf13](http://spf13.com) about what may make sense
|
||||||
to do next.
|
to do next.
|
||||||
|
|
||||||
|
|
@ -24,7 +24,7 @@ When you're ready to create a pull request, be sure to:
|
||||||
* Have test cases for the new code. If you have questions about how to do it, please ask in your pull request.
|
* 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`
|
* Run `go fmt`
|
||||||
* Squash your commits into a single commit. `git rebase -i`. It's okay to force update your pull request.
|
* 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
|
## Contribution Overview
|
||||||
|
|
||||||
|
|
@ -46,7 +46,7 @@ When you're ready to create a pull request, be sure to:
|
||||||
cd hugo
|
cd hugo
|
||||||
go get
|
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
|
$GOROOT or $GOPATH, it's helpful to symlink the project to one
|
||||||
of the following paths:
|
of the following paths:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -25,14 +25,14 @@ https://groups.google.com/forum/#!forum/hugo-discuss
|
||||||
|
|
||||||
## GoNuts
|
## 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
|
https://groups.google.com/forum/#!forum/golang-nuts
|
||||||
|
|
||||||
## Github Issues
|
## GitHub Issues
|
||||||
|
|
||||||
https://github.com/spf13/hugo/issues
|
https://github.com/spf13/hugo/issues
|
||||||
|
|
||||||
## Twitter
|
## 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).
|
||||||
|
|
|
||||||
|
|
@ -80,15 +80,15 @@ Field names are always normalized to lowercase (eg. `camelCase: true` is availab
|
||||||
### Optional
|
### Optional
|
||||||
|
|
||||||
* **redirect** Mark the post as a redirect post
|
* **redirect** Mark the post as a redirect post
|
||||||
* **draft** If true the content will not be rendered unless hugo is called with --buildDrafts
|
* **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
|
* **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)
|
* **type** The type of the content (will be derived from the directory automatically if unset)
|
||||||
* **weight** Used for sorting
|
* **weight** Used for sorting
|
||||||
* **markup** (Experimental) Specify "rst" for reStructuredText (requires
|
* **markup** (Experimental) Specify "rst" for reStructuredText (requires
|
||||||
`rst2html`,) or "md" (default) for the Markdown
|
`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>
|
*or*<br>
|
||||||
* **url** The full path to the content from the web root.<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.*
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -90,7 +90,7 @@ When a url is provided it will be used exactly. Using url will ignore the
|
||||||
-\-uglyurls setting.
|
-\-uglyurls setting.
|
||||||
|
|
||||||
|
|
||||||
## Path breakdown in hugo
|
## Path breakdown in Hugo
|
||||||
|
|
||||||
### Content
|
### Content
|
||||||
|
|
||||||
|
|
@ -152,12 +152,12 @@ When a url is provided it will be used exactly. Using url will ignore the
|
||||||
* based on content-name.md
|
* based on content-name.md
|
||||||
* front matter overrides
|
* front matter overrides
|
||||||
|
|
||||||
**path** = section + path to file exluding slug
|
**path** = section + path to file excluding slug
|
||||||
|
|
||||||
* based on path to content location
|
* based on path to content location
|
||||||
|
|
||||||
|
|
||||||
**url** = relative url
|
**url** = relative URL
|
||||||
|
|
||||||
* defined in front matter
|
* defined in front matter
|
||||||
* overrides all the above
|
* overrides all the above
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@ weight: 30
|
||||||
|
|
||||||
Hugo thinks that you organize your content with a purpose. The same structure
|
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
|
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**.
|
uses the top level of your content organization as **the Section**.
|
||||||
|
|
||||||
The following example site uses two sections, "post" and "quote".
|
The following example site uses two sections, "post" and "quote".
|
||||||
|
|
@ -42,10 +42,10 @@ that matches the section name.
|
||||||
|
|
||||||
Section defined in the front matter have the same impact.
|
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.
|
in the front matter.
|
||||||
|
|
||||||
If a layout for a given type hasn't been provided a default type template will
|
If a layout for a given type hasn't been provided, a default type template will
|
||||||
be used instead provided is exists.
|
be used instead provided it exists.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -13,8 +13,8 @@ title: Aliases
|
||||||
weight: 10
|
weight: 10
|
||||||
---
|
---
|
||||||
|
|
||||||
For people migrating existing published content to Hugo theres a good chance
|
For people migrating existing published content to Hugo there's a good chance
|
||||||
you need a mechanism to handle redirecting old urls.
|
you need a mechanism to handle redirecting old URLs.
|
||||||
|
|
||||||
Luckily, this can be handled easily with aliases in Hugo.
|
Luckily, this can be handled easily with aliases in Hugo.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -16,7 +16,7 @@ started.
|
||||||
|
|
||||||
## New Site
|
## New Site
|
||||||
|
|
||||||
Want to get a site built quickly?.
|
Want to get a site built quickly?
|
||||||
|
|
||||||
hugo new site /path/to/site
|
hugo new site /path/to/site
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -24,12 +24,12 @@ python based program called [pygments](http://pygments.org) and is triggered
|
||||||
via an embedded shortcode. If pygments is absent from the path, it will
|
via an embedded shortcode. If pygments is absent from the path, it will
|
||||||
silently simply pass the content along unhighlighted.
|
silently simply pass the content along unhighlighted.
|
||||||
|
|
||||||
## Server Side
|
## Server-side
|
||||||
|
|
||||||
### Disclaimers
|
### Disclaimers
|
||||||
|
|
||||||
* **Warning** pygments is relatively slow. Expect much longer build times when using server side highlighting.
|
* **Warning:** Pygments is relatively slow. 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.
|
||||||
* We have sought to have the simplest interface possible, which consequently
|
* We have sought to have the simplest interface possible, which consequently
|
||||||
|
|
|
||||||
|
|
@ -22,8 +22,8 @@ Some of the features of Hugo Menus:
|
||||||
## What is a menu?
|
## What is a menu?
|
||||||
|
|
||||||
A menus is a named array of menu entries accessible on the site under
|
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
|
`.Site.Menus` by name. For example if I have a menu called `main` I would
|
||||||
access it via .Site.Menus.main.
|
access it via `.Site.Menus.main`.
|
||||||
|
|
||||||
A menu entry has the following properties:
|
A menu entry has the following properties:
|
||||||
|
|
||||||
|
|
@ -134,7 +134,7 @@ and all content entries are attached to one of these entries via the
|
||||||
## Rendering menus
|
## Rendering menus
|
||||||
|
|
||||||
Hugo makes no assumptions about how your rendered HTML will be
|
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.
|
able to build your menu however you want.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -9,7 +9,7 @@ title: Table of Contents
|
||||||
weight: 60
|
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
|
a Table of Contents you can use to guide readers to the sections within
|
||||||
your content.
|
your content.
|
||||||
|
|
||||||
|
|
@ -18,8 +18,8 @@ your content.
|
||||||
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`
|
||||||
|
|
||||||
|
|
||||||
## Template Example
|
## Template Example
|
||||||
|
|
|
||||||
|
|
@ -12,19 +12,19 @@ title: URLs
|
||||||
weight: 70
|
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 created at /content/extras/urls.md will be rendered at
|
||||||
/content/extras/urls/index.html and accessible at /content/extras/urls. No
|
/content/extras/urls/index.html and accessible at /content/extras/urls. No
|
||||||
no standard server side configuration is required for these pretty urls to
|
no standard server side configuration is required for these pretty urls to
|
||||||
work.
|
work.
|
||||||
|
|
||||||
If you would like to have uglyurls you are in luck. Hugo supports 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
|
ability to create your entire site with ugly URLs. Simply use the
|
||||||
`--uglyurls=true` flag on the command line.
|
`--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
|
specify this in the front matter under the url key. See [Content
|
||||||
Organization](/content/organization/) for more details.
|
Organization](/content/organization/) for more details.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -14,10 +14,10 @@ weight: 20
|
||||||
In no particular order, here is what we are working on:
|
In no particular order, here is what we are working on:
|
||||||
|
|
||||||
* Intelligently Related Posts
|
* Intelligently Related Posts
|
||||||
* Even easier deployment to S3, SSH, Github, rsync
|
* Even easier deployment to S3, SSH, GitHub, rsync
|
||||||
* Import from other website systems (wordpress, jekyll)
|
* Import from other website systems (WordPress, Jekyll)
|
||||||
* An interactive web based editor
|
* An interactive web based editor
|
||||||
* Additional Themes
|
* Additional themes
|
||||||
* Dynamic image resizing via shortcodes
|
* Dynamic image resizing via shortcodes
|
||||||
* Support for additional formats
|
* Support for additional formats
|
||||||
* Pagination
|
* Pagination
|
||||||
|
|
|
||||||
|
|
@ -11,16 +11,16 @@ title: Installing Hugo
|
||||||
weight: 20
|
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).
|
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
|
We currently build for Windows, Linux, FreeBSD and OS X for x64
|
||||||
and 386 architectures.
|
and i386 architectures.
|
||||||
|
|
||||||
## Installing Hugo (binary)
|
## Installing Hugo (binary)
|
||||||
|
|
||||||
Installation is very easy. Simply download the appropriate version for your
|
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
|
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
|
it into a global location. This works well for shared hosts and other systems
|
||||||
where you don't have a privileged account.
|
where you don't have a privileged account.
|
||||||
|
|
@ -28,16 +28,16 @@ where you don't have a privileged account.
|
||||||
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
|
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
|
||||||
is the most probable location.
|
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)
|
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).
|
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
|
||||||
|
|
||||||
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.
|
placed in your path.
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -50,9 +50,9 @@ placed in your path.
|
||||||
* Mercurial
|
* Mercurial
|
||||||
* Bazaar
|
* Bazaar
|
||||||
|
|
||||||
### Get directly from Github:
|
### Get directly from GitHub:
|
||||||
|
|
||||||
go get github.com/spf13/hugo
|
go get -v github.com/spf13/hugo
|
||||||
|
|
||||||
### Building Hugo
|
### Building Hugo
|
||||||
|
|
||||||
|
|
@ -62,4 +62,4 @@ placed in your path.
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Please see the [contributing guide](/doc/contributing)
|
Please see the [contributing guide](/doc/contributing).
|
||||||
|
|
|
||||||
|
|
@ -11,36 +11,36 @@ weight: 5
|
||||||
|
|
||||||
## What is Hugo?
|
## What is Hugo?
|
||||||
|
|
||||||
Hugo is a general purpose website framework. Technically speaking, Hugo is
|
Hugo is a general-purpose website framework. Technically speaking, Hugo is
|
||||||
a static site generator. This means that unlike systems like Wordpress,
|
a static site generator. This means that unlike systems like WordPress,
|
||||||
Ghost & Drupal which run on your web server expensively building a page
|
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
|
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
|
your content. Since websites are viewed far more often then they are
|
||||||
edited, Hugo is optimized for website viewing while providing a great
|
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
|
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 expensive run times like Ruby, Python or PHP and without dependencies
|
||||||
on any databases.
|
on any databases.
|
||||||
|
|
||||||
We think of Hugo as the ideal website creation tool. With nearly instant
|
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
|
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?
|
## What does Hugo do?
|
||||||
|
|
||||||
In technical terms Hugo takes a source directory of markdown files and
|
In technical terms Hugo takes a source directory of Markdown files and
|
||||||
templates and uses these as input to create a complete website.
|
templates and uses these as input to create a complete website.
|
||||||
|
|
||||||
Hugo boasts the following features:
|
Hugo boasts the following features:
|
||||||
|
|
||||||
### General
|
### General
|
||||||
|
|
||||||
* Extremely fast built times (~1ms per page)
|
* Extremely fast build times (~1 ms per page)
|
||||||
* Completely cross platform: Runs on Mac OSX, Linux and Windows
|
* Completely cross platform: Runs on Mac OS X, Linux and Windows
|
||||||
* Easy [installation](/overview/installing)
|
* Easy [installation](/overview/installing)
|
||||||
* Render changes [on the fly](/overview/usage) with [live reload](/extras/livereload) as you develop
|
* Render changes [on the fly](/overview/usage) with [live reload](/extras/livereload) as you develop
|
||||||
* Complete theme support
|
* Complete theme support
|
||||||
|
|
@ -50,13 +50,13 @@ Hugo boasts the following features:
|
||||||
|
|
||||||
* Straightforward [organization](/content/organization)
|
* Straightforward [organization](/content/organization)
|
||||||
* Support for [website sections](/content/sections)
|
* 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
|
* 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
|
* Ability to [sort content](/content/ordering) as you desire
|
||||||
* Automatic [table of contents](/extras/toc) generation
|
* Automatic [table of contents](/extras/toc) generation
|
||||||
* Dynamic menu creation
|
* Dynamic menu creation
|
||||||
* [pretty urls](/extras/urls) support
|
* [Pretty URLs](/extras/urls) support
|
||||||
* [permalink](/extras/permalinks) pattern support
|
* [Permalink](/extras/permalinks) pattern support
|
||||||
* [Aliases](/extras/aliases) (redirects)
|
* [Aliases](/extras/aliases) (redirects)
|
||||||
|
|
||||||
### Content
|
### Content
|
||||||
|
|
@ -66,7 +66,7 @@ Hugo boasts the following features:
|
||||||
* Completely [customizable homepage](/layout/homepage)
|
* Completely [customizable homepage](/layout/homepage)
|
||||||
* Support for multiple [content types](/content/types)
|
* Support for multiple [content types](/content/types)
|
||||||
* Automatic and user defined [summaries](/content/summaries)
|
* 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
|
* ["Minutes to Read"](/layout/variables) functionality
|
||||||
* ["Wordcount"](/layout/variables) functionality
|
* ["Wordcount"](/layout/variables) functionality
|
||||||
|
|
||||||
|
|
@ -74,7 +74,7 @@ Hugo boasts the following features:
|
||||||
|
|
||||||
* Integrated Disqus comment support
|
* Integrated Disqus comment support
|
||||||
* Automatic [RSS](/layout/rss) creation
|
* 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
|
* Syntax [highlighting](/extras/highlighting) powered by pygments
|
||||||
|
|
||||||
See what's coming next in the [roadmap](/meta/roadmap)
|
See what's coming next in the [roadmap](/meta/roadmap)
|
||||||
|
|
@ -86,29 +86,29 @@ a browser.
|
||||||
|
|
||||||
Hugo is for people who want to hand code their own website without
|
Hugo is for people who want to hand code their own website without
|
||||||
worrying about setting up complicated runtimes, dependencies and
|
worrying about setting up complicated runtimes, dependencies and
|
||||||
databases.
|
databases.
|
||||||
|
|
||||||
Hugo is for people building a blog, company site, portfolio, tumblog,
|
Hugo is for people building a blog, company site, portfolio, tumblog,
|
||||||
documentation, single page site or a site with thousands of
|
documentation, single page site or a site with thousands of
|
||||||
pages.
|
pages.
|
||||||
|
|
||||||
## Why did you write Hugo?
|
## Why did you write Hugo?
|
||||||
|
|
||||||
I wrote Hugo ultimately for a few reasons. First I was disappointed with
|
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
|
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
|
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
|
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.
|
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
|
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
|
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
|
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
|
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
|
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
|
dependencies. The Go language seemed to have all of the features I needed
|
||||||
|
|
@ -121,4 +121,4 @@ as I have writing it.
|
||||||
* [Install Hugo](/overview/installing)
|
* [Install Hugo](/overview/installing)
|
||||||
* [Quick start](/overview/quickstart)
|
* [Quick start](/overview/quickstart)
|
||||||
* [Join the Mailing List](/community/mailing-list)
|
* [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)
|
||||||
|
|
|
||||||
|
|
@ -16,12 +16,12 @@ proceeding._
|
||||||
|
|
||||||
## Step 1. Install 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.
|
appropriate version for your os and architecture.
|
||||||
|
|
||||||
Save it somewhere specific as we will be using it in the next step.
|
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
|
## Step 2. Have Hugo Create a site for you
|
||||||
|
|
||||||
|
|
@ -59,7 +59,7 @@ A new file is now created in `content/` with the following contents
|
||||||
|
|
||||||
Notice the date is automatically set to the moment you created the content.
|
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
|
For example you could put this
|
||||||
|
|
||||||
|
|
@ -67,7 +67,7 @@ For example you could put this
|
||||||
|
|
||||||
Some Content
|
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
|
hugo new post/first.md
|
||||||
|
|
||||||
|
|
@ -83,9 +83,9 @@ We still lack any templates to tell us how to display the content.
|
||||||
|
|
||||||
## Step 5. Run Hugo
|
## 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
|
server` and Hugo will find an available port and run a server with
|
||||||
your content
|
your content:
|
||||||
|
|
||||||
hugo server --theme=hyde --buildDrafts
|
hugo server --theme=hyde --buildDrafts
|
||||||
2 pages created
|
2 pages created
|
||||||
|
|
@ -96,16 +96,16 @@ your content
|
||||||
Web Server is available at http://localhost:1313
|
Web Server is available at http://localhost:1313
|
||||||
Press ctrl+c to stop
|
Press ctrl+c to stop
|
||||||
|
|
||||||
We specified two options here.
|
We specified two options here:
|
||||||
|
|
||||||
* `--theme` to pick which theme.
|
* `--theme` to pick which theme;
|
||||||
* `--buildDrafts` because we want to display our content, both set to draft status
|
* `--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
|
hugo help
|
||||||
|
|
||||||
To learn about the server options
|
To learn about the server options:
|
||||||
|
|
||||||
hugo help server
|
hugo help server
|
||||||
|
|
||||||
|
|
@ -132,7 +132,7 @@ Open your [favorite editor](http://vim.spf13.com), edit and save your content an
|
||||||
|
|
||||||
It’s especially productive to leave a browser open on a second monitor
|
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
|
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.
|
you can look at the browser in most cases.
|
||||||
|
|
||||||
Change and save this file. Notice what happened in your terminal.
|
Change and save this file. Notice what happened in your terminal.
|
||||||
|
|
@ -153,7 +153,7 @@ Things to try:
|
||||||
* Add a [new content file](/content/organization/)
|
* Add a [new content file](/content/organization/)
|
||||||
* Create a [new section](/content/sections/)
|
* Create a [new section](/content/sections/)
|
||||||
* Modify [a template](/layout/templates/)
|
* 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/)
|
* Define your own field in [front matter](/content/front-matter/)
|
||||||
* Display that [field in the template](/layout/variables/)
|
* Display that [field in the template](/layout/variables/)
|
||||||
* Create a [new content type](/content/types/)
|
* Create a [new content type](/content/types/)
|
||||||
|
|
|
||||||
|
|
@ -27,7 +27,7 @@ Make sure either hugo is in your path or provide a path to it.
|
||||||
hugo [command]
|
hugo [command]
|
||||||
|
|
||||||
Available Commands:
|
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
|
version :: Print the version number of Hugo
|
||||||
check :: Check content in the source directory
|
check :: Check content in the source directory
|
||||||
benchmark :: Benchmark hugo by building a site a number of times
|
benchmark :: Benchmark hugo by building a site a number of times
|
||||||
|
|
|
||||||
|
|
@ -20,8 +20,8 @@ taxonomies. Taxonomies give us a way to classify our content so we can
|
||||||
demonstrate relationships in a variety of logical ways.
|
demonstrate relationships in a variety of logical ways.
|
||||||
|
|
||||||
The default taxonomies for Hugo are tags and categories. These
|
The default taxonomies for Hugo are tags and categories. These
|
||||||
taxonomies are common to many websites systems (Wordpress, Drupal,
|
taxonomies are common to many website systems (WordPress, Drupal,
|
||||||
Jekyll). Unlike all of those Systems, Hugo makes it trivial to customize
|
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
|
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
|
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
|
common uses would include categories, tags, groups, series and many
|
||||||
|
|
|
||||||
|
|
@ -13,7 +13,7 @@ title: 404.html Templates
|
||||||
weight: 100
|
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.
|
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
|
404 pages are of the type "node" and have all the [node
|
||||||
|
|
|
||||||
|
|
@ -12,9 +12,9 @@ title: Hugo Template Functions
|
||||||
weight: 20
|
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
|
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.
|
to create a good static website.
|
||||||
|
|
||||||
Go templates are lightweight but extensible. Hugo has added the following
|
Go templates are lightweight but extensible. Hugo has added the following
|
||||||
|
|
|
||||||
|
|
@ -12,25 +12,25 @@ title: Go Template Primer
|
||||||
weight: 15
|
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
|
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
|
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
|
template systems from different languages or frameworks, you will find a lot of
|
||||||
similarities in go templates.
|
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.
|
provide more details.
|
||||||
|
|
||||||
## Introduction to Go Templates
|
## Introduction to Go Templates
|
||||||
|
|
||||||
Go templates provide an extremely simple template language. It adheres to the
|
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.
|
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
|
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
|
## Basic Syntax
|
||||||
|
|
||||||
|
|
@ -62,7 +62,7 @@ Accessing the Page Parameter "bar"
|
||||||
|
|
||||||
## Variables
|
## 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
|
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
|
page you are rendering. More details are available on the
|
||||||
[variables](/layout/variables) page.
|
[variables](/layout/variables) page.
|
||||||
|
|
@ -109,7 +109,7 @@ Go templates provide the most basic iteration and conditional logic.
|
||||||
|
|
||||||
### Iteration
|
### 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
|
a map, array or slice. The following are different examples of how to use
|
||||||
range.
|
range.
|
||||||
|
|
||||||
|
|
@ -180,12 +180,12 @@ The first example above could be simplified as:
|
||||||
|
|
||||||
## Pipes
|
## 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
|
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
|
from unix pipes, the concept is simple, each pipeline's output becomes the
|
||||||
input of the following pipe.
|
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
|
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
|
pipes is that they only can work with a single value and that value
|
||||||
becomes the last parameter of the next pipeline.
|
becomes the last parameter of the next pipeline.
|
||||||
|
|
@ -229,14 +229,15 @@ By default Go Templates remove HTML comments from output. This has the unfortuna
|
||||||
<script src="html5shiv.js"></script>
|
<script src="html5shiv.js"></script>
|
||||||
{{ "<![endif]-->" | safeHtml }}
|
{{ "<![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
|
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
|
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. .
|
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
|
`.` will no longer refer to the data available to the entire page. If you need
|
||||||
access this from within the loop you will likely want to set it to a variable
|
to
|
||||||
|
access this from within the loop, you will likely want to set it to a variable
|
||||||
instead of depending on the context.
|
instead of depending on the context.
|
||||||
|
|
||||||
**Example:**
|
**Example:**
|
||||||
|
|
@ -246,7 +247,7 @@ instead of depending on the context.
|
||||||
<li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li>
|
<li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li>
|
||||||
{{ end }}
|
{{ 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
|
have defined a variable outside of the loop so we have access to it from within
|
||||||
the loop.
|
the loop.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -14,21 +14,21 @@ title: Hugo Templates
|
||||||
weight: 10
|
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
|
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.
|
to create a good static website.
|
||||||
|
|
||||||
While Hugo has a number of different template roles, most complete
|
While Hugo has a number of different template roles, most complete
|
||||||
websites can be built using just a small number of template files.
|
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
|
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)
|
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.
|
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
|
template functions](/templates/functions) and [variables](/templates/variables) you will want to be familiar
|
||||||
with.
|
with.
|
||||||
|
|
||||||
|
|
@ -56,7 +56,7 @@ Common page parts to be included in the above mentioned templates
|
||||||
Different ways of rendering a (single) content type
|
Different ways of rendering a (single) content type
|
||||||
|
|
||||||
### [Taxonomy Terms](/templates/terms)
|
### [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)
|
## Other Templates (generally unnecessary)
|
||||||
|
|
||||||
|
|
@ -67,6 +67,6 @@ Used to render all rss documents
|
||||||
Used to render the XML sitemap
|
Used to render the XML sitemap
|
||||||
|
|
||||||
### [404](/templates/404)
|
### [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
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,7 @@ weight: 95
|
||||||
---
|
---
|
||||||
|
|
||||||
A single Sitemap template is used to generate the `sitemap.xml` file.
|
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.**
|
the users part unless they want to customize the sitemap.xml.**
|
||||||
|
|
||||||
This page is of the type "node" and have all the [node
|
This page is of the type "node" and have all the [node
|
||||||
|
|
|
||||||
|
|
@ -29,7 +29,7 @@ matter, content or derived from file location.
|
||||||
**.Keywords** The meta keywords for this content.<br>
|
**.Keywords** The meta keywords for this content.<br>
|
||||||
**.Date** The date the content is associated with.<br>
|
**.Date** The date the content is associated with.<br>
|
||||||
**.PublishDate** The date the content is published on.<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>
|
**.Section** The [section](/content/sections/) this content belongs to<br>
|
||||||
**.Permalink** The Permanent link for this page.<br>
|
**.Permalink** The Permanent link for this page.<br>
|
||||||
**.RelPermalink** The Relative permanent link for this page.<br>
|
**.RelPermalink** The Relative permanent link for this page.<br>
|
||||||
|
|
|
||||||
|
|
@ -15,8 +15,8 @@ using the `hugo new` command.
|
||||||
`hugo new theme [name]`
|
`hugo new theme [name]`
|
||||||
|
|
||||||
This command will initialize all of the files and directories a basic theme
|
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
|
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.
|
to Go, the [Go template primer](/layout/go-templates/) will help you get started.
|
||||||
|
|
||||||
## Theme Components
|
## Theme Components
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -12,13 +12,13 @@ weight: 10
|
||||||
|
|
||||||
## What is MathJax?
|
## 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.
|
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
|
## 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"
|
<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">
|
||||||
|
|
@ -32,13 +32,13 @@ MathJax is a stable open-source library with many features. I encourage the inte
|
||||||
|
|
||||||
## Issues with Markdown
|
## 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
|
### 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.
|
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">
|
<script type="text/x-mathjax-config">
|
||||||
MathJax.Hub.Config({
|
MathJax.Hub.Config({
|
||||||
|
|
@ -66,7 +66,7 @@ Another option is to tell markdown to treat the MathJax code as verbatim code an
|
||||||
});
|
});
|
||||||
</script>
|
</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;
|
code.has-jax {font: inherit;
|
||||||
|
|
|
||||||
|
|
@ -153,4 +153,4 @@ Depending on the amount of customization that was done with each post with Jekyl
|
||||||
You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.
|
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
|
## 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).
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue