mirror of
https://github.com/gohugoio/hugo.git
synced 2024-07-02 23:30:00 +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
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -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.
|
||||
* 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
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ When you're ready to create a pull request, be sure to:
|
|||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -25,14 +25,14 @@ https://groups.google.com/forum/#!forum/hugo-discuss
|
|||
|
||||
## 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).
|
||||
|
|
|
|||
|
|
@ -80,15 +80,15 @@ Field names are always normalized to lowercase (eg. `camelCase: true` is availab
|
|||
### 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.*
|
||||
|
||||
|
|
|
|||
|
|
@ -90,7 +90,7 @@ When a url is provided it will be used exactly. Using url will ignore the
|
|||
-\-uglyurls setting.
|
||||
|
||||
|
||||
## Path breakdown in hugo
|
||||
## Path breakdown in Hugo
|
||||
|
||||
### 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
|
||||
* 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
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ weight: 30
|
|||
|
||||
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".
|
||||
|
|
@ -42,10 +42,10 @@ that matches the section name.
|
|||
|
||||
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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ title: Aliases
|
|||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ started.
|
|||
|
||||
## New Site
|
||||
|
||||
Want to get a site built quickly?.
|
||||
Want to get a site built quickly?
|
||||
|
||||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -22,8 +22,8 @@ Some of the features of Hugo Menus:
|
|||
## 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:
|
||||
|
||||
|
|
@ -134,7 +134,7 @@ and all content entries are attached to one of these entries via the
|
|||
## 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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ title: Table of Contents
|
|||
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.
|
||||
|
||||
|
|
@ -18,8 +18,8 @@ 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
|
||||
|
|
|
|||
|
|
@ -12,19 +12,19 @@ title: URLs
|
|||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,10 +14,10 @@ weight: 20
|
|||
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
|
||||
|
|
|
|||
|
|
@ -11,16 +11,16 @@ title: Installing Hugo
|
|||
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.
|
||||
|
|
@ -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`
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -50,9 +50,9 @@ 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
|
||||
|
||||
|
|
@ -62,4 +62,4 @@ placed in your path.
|
|||
|
||||
## Contributing
|
||||
|
||||
Please see the [contributing guide](/doc/contributing)
|
||||
Please see the [contributing guide](/doc/contributing).
|
||||
|
|
|
|||
|
|
@ -11,36 +11,36 @@ weight: 5
|
|||
|
||||
## 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
|
||||
|
|
@ -50,13 +50,13 @@ Hugo boasts the following features:
|
|||
|
||||
* 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
|
||||
|
|
@ -66,7 +66,7 @@ Hugo boasts the following features:
|
|||
* 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
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ Hugo boasts the following features:
|
|||
|
||||
* 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)
|
||||
|
|
@ -86,29 +86,29 @@ a browser.
|
|||
|
||||
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
|
||||
|
|
@ -121,4 +121,4 @@ as I have writing it.
|
|||
* [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)
|
||||
|
|
|
|||
|
|
@ -16,12 +16,12 @@ proceeding._
|
|||
|
||||
## 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
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -67,7 +67,7 @@ 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
|
||||
|
||||
|
|
@ -83,9 +83,9 @@ We still lack any templates to tell us how to display the content.
|
|||
|
||||
## 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
|
||||
|
|
@ -96,16 +96,16 @@ your content
|
|||
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
|
||||
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
|
@ -153,7 +153,7 @@ Things to try:
|
|||
* 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/)
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Make sure either hugo is in your path or provide a path to it.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ title: 404.html Templates
|
|||
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
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ title: Hugo Template Functions
|
|||
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
|
||||
|
|
|
|||
|
|
@ -12,25 +12,25 @@ title: Go Template Primer
|
|||
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
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ Accessing the Page Parameter "bar"
|
|||
|
||||
## 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.
|
||||
|
|
@ -109,7 +109,7 @@ Go templates provide the most basic iteration and conditional logic.
|
|||
|
||||
### 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.
|
||||
|
||||
|
|
@ -180,12 +180,12 @@ The first example above could be simplified as:
|
|||
|
||||
## 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.
|
||||
|
|
@ -229,14 +229,15 @@ By default Go Templates remove HTML comments from output. This has the unfortuna
|
|||
<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:**
|
||||
|
|
@ -246,7 +247,7 @@ instead of depending on the context.
|
|||
<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.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,21 +14,21 @@ title: Hugo Templates
|
|||
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.
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ Common page parts to be included in the above mentioned templates
|
|||
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)
|
||||
|
||||
|
|
@ -67,6 +67,6 @@ Used to render all rss documents
|
|||
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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight: 95
|
|||
---
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ matter, content or derived from file location.
|
|||
**.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>
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ using the `hugo new` command.
|
|||
`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
|
||||
|
||||
|
|
|
|||
|
|
@ -12,13 +12,13 @@ weight: 10
|
|||
|
||||
## 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">
|
||||
|
|
@ -32,13 +32,13 @@ MathJax is a stable open-source library with many features. I encourage the inte
|
|||
|
||||
## 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({
|
||||
|
|
@ -66,7 +66,7 @@ Another option is to tell markdown to treat the MathJax code as verbatim code an
|
|||
});
|
||||
</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;
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
## 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