mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
More proofreading and minor revisions to Hugo docs
Among the various changes, most instances of
{{ template "partials/FILE.html" . }}
were changed to
{{ partial "FILE.html" . }}
Also, in main.go, change "2013" to "2013-14".
This commit is contained in:
Anthony Fok
spf13
parent
ac78d25240
commit
5dd3eaabee
31 changed files with 258 additions and 252 deletions
28
README.md
28
README.md
|
|
@ -9,9 +9,9 @@ and [friends](http://github.com/spf13/hugo/graphs/contributors) in Go.
|
|||
|
||||
Hugo is a static site generator written in Go. It is optimized for
|
||||
speed, easy use and configurability. Hugo takes a directory with content and
|
||||
templates and renders them into a full html website.
|
||||
templates and renders them into a full HTML website.
|
||||
|
||||
Hugo makes use of markdown files with front matter for meta data.
|
||||
Hugo makes use of Markdown files with front matter for meta data.
|
||||
|
||||
A typical website of moderate size can be
|
||||
rendered in a fraction of a second. A good rule of thumb is that Hugo
|
||||
|
|
@ -26,21 +26,21 @@ kind of website including blogs, tumbles and docs.
|
|||
|
||||
## Installing Hugo
|
||||
|
||||
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.
|
||||
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).
|
||||
Once downloaded it can be run from anywhere. You don't need to install
|
||||
platform from [Hugo Releases](https://github.com/spf13/hugo/releases).
|
||||
Once downloaded, it can be run from anywhere. You don't need to install
|
||||
it into a global location. This works well for shared hosts and other systems
|
||||
where you don't have a privileged account.
|
||||
|
||||
Ideally you should install it somewhere in your path for easy use. `/usr/local/bin`
|
||||
Ideally, you should install it somewhere in your path for easy use. `/usr/local/bin`
|
||||
is the most probable location.
|
||||
|
||||
*The Hugo executable has no external dependencies.*
|
||||
|
|
@ -60,17 +60,17 @@ is the most probable location.
|
|||
cd hugo
|
||||
go get
|
||||
|
||||
Because go expects all of your libraries to be found in either $GOROOT or $GOPATH,
|
||||
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:
|
||||
|
||||
* ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo
|
||||
* ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo
|
||||
* `ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo`
|
||||
* `ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo`
|
||||
|
||||
#### Get directly from Github:
|
||||
#### Get directly from GitHub:
|
||||
|
||||
If you only want to build from source, it's even easier.
|
||||
|
||||
go get github.com/spf13/hugo
|
||||
go get -v github.com/spf13/hugo
|
||||
|
||||
#### Building Hugo
|
||||
|
||||
|
|
@ -93,7 +93,7 @@ We welcome your contributions. To make the process as seamless as possible, we
|
|||
* 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.
|
||||
|
||||
**Complete documentation is available at [Hugo Documentation](http://hugo.spf13.com).**
|
||||
|
||||
|
|
|
|||
|
|
@ -29,9 +29,9 @@ I use ‘tags’ and ‘categories’ for my taxonomies.
|
|||
+++
|
||||
|
||||
|
||||
## using archetypes
|
||||
## Using archetypes
|
||||
|
||||
If I wanted to create a new post in the `posts` section I would run the following command...
|
||||
If I wanted to create a new post in the `posts` section, I would run the following command:
|
||||
|
||||
`hugo new posts/my-new-post.md`
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ Hugo would create the file with the following contents:
|
|||
|
||||
## Using a different front matter format
|
||||
|
||||
By default the front matter will be created in the TOML format
|
||||
By default, the front matter will be created in the TOML format
|
||||
regardless of what format the archetype is using.
|
||||
|
||||
You can specify a different default format in your config file using
|
||||
|
|
@ -60,15 +60,15 @@ the `MetaDataFormat` directive. Possible values are `toml`, `yaml` and `json`.
|
|||
|
||||
The following rules apply:
|
||||
|
||||
* If an archetype with a filename that matches the content type being created it will be used.
|
||||
* If no match is found `archetypes/default.md` will be used.
|
||||
* If neither are present and a theme is in use then within the theme...
|
||||
* If an archetype with a filename that matches the content type being created it will be used.
|
||||
* If no match is found `archetypes/default.md` will be used.
|
||||
* If no archetype files are present then the one that ships with hugo will be used.
|
||||
* If an archetype with a filename that matches the content type being created, it will be used.
|
||||
* If no match is found, `archetypes/default.md` will be used.
|
||||
* If neither are present and a theme is in use, then within the theme:
|
||||
* If an archetype with a filename that matches the content type being created, it will be used.
|
||||
* If no match is found, `archetypes/default.md` will be used.
|
||||
* If no archetype files are present, then the one that ships with Hugo will be used.
|
||||
|
||||
Hugo provides a simple archetype which sets the title (based on the
|
||||
file name) and the date based on now().
|
||||
file name) and the date based on `now()`.
|
||||
|
||||
Content type is automatically detected based on the path. You are welcome to declare which
|
||||
type to create using the `--kind` flag during creation.
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ title: Example Content File
|
|||
weight: 70
|
||||
---
|
||||
|
||||
Somethings are better shown than explained. The following is a very basic example of a content file:
|
||||
Some things are better shown than explained. The following is a very basic example of a content file:
|
||||
|
||||
**mysite/project/nitro.md <- http://mysite.com/project/nitro.html**
|
||||
**mysite/project/nitro.md ← http://mysite.com/project/nitro.html**
|
||||
|
||||
---
|
||||
Title: "Nitro : A quick and simple profiler for Go"
|
||||
|
|
|
|||
|
|
@ -13,12 +13,13 @@ weight: 20
|
|||
|
||||
The front matter is one of the features that gives Hugo its strength. It enables
|
||||
you to include the meta data of the content right with it. Hugo supports a few
|
||||
different formats each with their own identifying tokens.
|
||||
different formats, each with their own identifying tokens.
|
||||
|
||||
Supported formats: <br>
|
||||
**YAML**, identified by '\-\-\-'. <br>
|
||||
**TOML**, indentified with '+++'.<br>
|
||||
**JSON**, a single JSON object which is surrounded by '{' and '}' each on their own line.
|
||||
Supported formats:
|
||||
|
||||
* **YAML**, identified by '`---`'.
|
||||
* **TOML**, identified with '`+++`'.
|
||||
* **JSON**, a single JSON object which is surrounded by '`{`' and '`}`', each on their own line.
|
||||
|
||||
### YAML Example
|
||||
|
||||
|
|
@ -68,7 +69,7 @@ Supported formats: <br>
|
|||
|
||||
There are a few predefined variables that Hugo is aware of and utilizes. The user can also create
|
||||
any variable they want to. These will be placed into the `.Params` variable available to the templates.
|
||||
Field names are always normalized to lowercase (eg. `camelCase: true` is available as `.Params.camelcase`).
|
||||
Field names are always normalized to lowercase (e.g. `camelCase: true` is available as `.Params.camelcase`).
|
||||
|
||||
### Required
|
||||
|
||||
|
|
|
|||
|
|
@ -13,15 +13,15 @@ weight: 60
|
|||
Hugo provides you with all the flexibility you need to organize how your content is ordered.
|
||||
|
||||
By default, content is ordered by weight, then by date with the most
|
||||
recent date first, but alternative sorting (by title and linktitle) is
|
||||
also available. The order the content will appear will be specified in
|
||||
recent date first, but alternative sorting (by `title` and `linktitle`) is
|
||||
also available. The order the content would appear is specified in
|
||||
the [list template](/templates/list).
|
||||
|
||||
_Both the date and weight fields are optional._
|
||||
_Both the `date` and `weight` fields are optional._
|
||||
|
||||
Unweighted pages appear at the end of the list. If no weights are provided (or
|
||||
if weights are the same) date will be used to sort. If neither are provided
|
||||
content will be ordered based on how it's read off the disk and no order is
|
||||
if weights are the same), `date` will be used to sort. If neither is provided,
|
||||
content will be ordered based on how it's read off the disk, and no order is
|
||||
guaranteed.
|
||||
|
||||
## Assigning weight to content
|
||||
|
|
@ -36,4 +36,4 @@ guaranteed.
|
|||
|
||||
## Ordering Content Within Taxonomies
|
||||
|
||||
Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/)
|
||||
Please see the [Taxonomy Ordering Documentation](/taxonomies/ordering/).
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ Hugo has full support for different types of content. A content type can have a
|
|||
unique set of meta data, template and can be automatically created by the new
|
||||
command through using content [archetypes](/content/archetypes).
|
||||
|
||||
A good example of when multiple types are needed is to look at Tumblr. A piece
|
||||
A good example of when multiple types are needed is to look at [Tumblr](https://www.tumblr.com/). A piece
|
||||
of content could be a photo, quote or post, each with different meta data and
|
||||
rendered differently.
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ rendered differently.
|
|||
|
||||
Hugo assumes that your site will be organized into [sections](/content/sections)
|
||||
and each section will use the corresponding type. If you are taking advantage of
|
||||
this then each new piece of content you place into a section will automatically
|
||||
this, then each new piece of content you place into a section will automatically
|
||||
inherit the type.
|
||||
|
||||
Alternatively you can set the type in the meta data under the key "type".
|
||||
|
|
@ -34,11 +34,11 @@ Hugo has the ability to create a new content file and populate the front matter
|
|||
with the data set corresponding to that type. Hugo does this by utilizing
|
||||
[archetypes](/content/archetypes).
|
||||
|
||||
To create a new piece of content use:
|
||||
To create a new piece of content, use:
|
||||
|
||||
hugo new relative/path/to/content.md
|
||||
|
||||
For example if I wanted to create a new post inside the post section I would type:
|
||||
For example, if I wanted to create a new post inside the post section, I would type:
|
||||
|
||||
hugo new post/my-newest-post.md
|
||||
|
||||
|
|
@ -53,13 +53,13 @@ whenever a specific file is not present.
|
|||
*Remember, all of the following are optional:*
|
||||
|
||||
### Create Type Directory
|
||||
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
|
||||
Create a directory with the name of the type in layouts. Type is always singular. *Eg /layouts/post*.
|
||||
|
||||
### Create single template
|
||||
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
|
||||
|
||||
### Create list template
|
||||
Create a file called list.html inside your directory *Eg /layouts/post/list.html*.
|
||||
Create a file called list.html inside your directory. *Eg /layouts/post/list.html*.
|
||||
|
||||
### Create views
|
||||
Many sites support rendering content in a few different ways, for
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ title: Aliases
|
|||
weight: 10
|
||||
---
|
||||
|
||||
For people migrating existing published content to Hugo there's 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.
|
||||
|
||||
Luckily, this can be handled easily with aliases in Hugo.
|
||||
|
|
@ -27,7 +27,7 @@ Luckily, this can be handled easily with aliases in Hugo.
|
|||
- /2010/even-earlier-url.html
|
||||
---
|
||||
|
||||
Now when you go to any of the aliases locations they
|
||||
Now when you go to any of the aliases locations, they
|
||||
will redirect to the page.
|
||||
|
||||
## Important Behaviors
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ Simply include the following line where you want your comments to appear
|
|||
|
||||
## Configuring Disqus
|
||||
|
||||
That template requires you to set a single value in your site config file, eg. config.yaml.
|
||||
That template requires you to set a single value in your site config file, e.g. config.yaml.
|
||||
|
||||
disqusShortname = "XYW"
|
||||
|
||||
|
|
@ -73,7 +73,7 @@ Notice that there is a simple if statement that detects when you are running on
|
|||
|
||||
Now reference the partial template from your page template:
|
||||
|
||||
{{ template "partials/disqus.html" . }}
|
||||
{{ partial "disqus.html" . }}
|
||||
|
||||
|
||||
# Alternatives
|
||||
|
|
|
|||
|
|
@ -15,13 +15,13 @@ Hugo provides the ability for you to highlight source code in two different
|
|||
ways — either pre-processed server side from your content, or to defer
|
||||
the processing to the client side, using a JavaScript library. The advantage of
|
||||
server side is that it doesn’t depend on a JavaScript library and consequently
|
||||
works very well when read from an rss feed. The advantage of client side is that
|
||||
works very well when read from an RSS feed. The advantage of client side is that
|
||||
it doesn’t cost anything when building your site and some of the highlighting
|
||||
scripts available cover more languages than pygments does.
|
||||
scripts available cover more languages than Pygments does.
|
||||
|
||||
For the pre-processed approach, Highlighting is performed by an external
|
||||
python based program called [pygments](http://pygments.org) and is triggered
|
||||
via an embedded shortcode. If pygments is absent from the path, it will
|
||||
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
|
||||
|
|
@ -83,7 +83,7 @@ a library and a corresponding theme. Some popular libraries are:
|
|||
This example uses the popular [Highlight.js] library, hosted by [Yandex], a
|
||||
popular Russian search engine.
|
||||
|
||||
In your `./layouts/chrome/` folder, depending on your specific theme, there
|
||||
In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your specific theme, there
|
||||
will be a snippet that will be included in every generated HTML page, such
|
||||
as `header.html` or `header.includes.html`. Simply add:
|
||||
|
||||
|
|
@ -98,4 +98,4 @@ You can of course use your own copy of these files, typically in `./static/`.
|
|||
[Google Prettify]: https://code.google.com/p/google-code-prettify/
|
||||
[Yandex]: http://yandex.ru/
|
||||
|
||||
Please see individual libraries documentation for how to implement the JavaScript based libraries.
|
||||
Please see individual libraries documentation for how to implement the JavaScript-based libraries.
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ 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
|
||||
`.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:
|
||||
|
|
@ -89,7 +89,7 @@ available.
|
|||
You can also add entries to menus that aren’t attached to a piece of
|
||||
content. This takes place in the site wide [config file](http://hugo.spf13.com/overview/configuration).
|
||||
|
||||
Here’s an example (in toml):
|
||||
Here’s an example (in TOML):
|
||||
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
|
|
@ -101,7 +101,7 @@ Here’s an example (in toml):
|
|||
pre = "<i class='fa fa-road'></i>"
|
||||
weight = -100
|
||||
|
||||
Here’s an example (in yaml):
|
||||
Here’s an example (in YAML):
|
||||
|
||||
---
|
||||
menu:
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ internal "canonical" location, such that template references to
|
|||
`.RelPermalink` will honour the adjustments made as a result of the mappings
|
||||
in this option.
|
||||
|
||||
For instance, if one of your sections is called `post` and you want to adjust
|
||||
For instance, if one of your sections is called `post`, and you want to adjust
|
||||
the canonical path to be hierarchical based on the year and month, then you
|
||||
might use:
|
||||
|
||||
|
|
@ -36,18 +36,18 @@ A file named `content/post/sample-entry` which contains a line
|
|||
appearing at `public/2013/11/sample-entry/index.html` and be reachable via
|
||||
the URL <http://yoursite.example.com/2013/11/sample-entry/>.
|
||||
|
||||
The following is a list of values that can be used in a permalink definition,
|
||||
all references to time are dependent on the content's date.
|
||||
The following is a list of values that can be used in a permalink definition.
|
||||
All references to time are dependent on the content's date.
|
||||
|
||||
**:year** the 4 digit year<br/>
|
||||
**:month** the 2 digit month<br/>
|
||||
**:monthname** the name of the month<br/>
|
||||
**:day** the 2 digit day<br/>
|
||||
**:weekday** the 1 digit day of the week (Sunday = 0)<br/>
|
||||
**:weekdayname** the name of the day of the week<br/>
|
||||
**:yearday** the 1-3 digit day of the year<br/>
|
||||
**:section** the content's section<br/>
|
||||
**:title** the content's title<br/>
|
||||
**:slug** the content's slug (or title if no slug)<br/>
|
||||
**:filename** the content's filename (without extension)<br/>
|
||||
* **:year** the 4-digit year
|
||||
* **:month** the 2-digit month
|
||||
* **:monthname** the name of the month
|
||||
* **:day** the 2-digit day
|
||||
* **:weekday** the 1-digit day of the week (Sunday = 0)
|
||||
* **:weekdayname** the name of the day of the week
|
||||
* **:yearday** the 1- to 3-digit day of the year
|
||||
* **:section** the content's section
|
||||
* **:title** the content's title
|
||||
* **:slug** the content's slug (or title if no slug)
|
||||
* **:filename** the content's filename (without extension)
|
||||
|
||||
|
|
|
|||
|
|
@ -26,12 +26,12 @@ Hugo will take this Markdown and create a table of contents stored in the
|
|||
|
||||
This is example code of a [single.html template](/layout/content).
|
||||
|
||||
{{ template "partials/header.html" . }}
|
||||
{{ partial "header.html" . }}
|
||||
<div id="toc" class="well col-md-4 col-sm-6">
|
||||
{{ .TableOfContents }}
|
||||
</div>
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ template "partials/footer.html" . }}
|
||||
{{ partial "footer.html" . }}
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -14,11 +14,11 @@ weight: 40
|
|||
---
|
||||
|
||||
The directory structure and templates provide the majority of the
|
||||
configuration for a site. In fact a config file isn't even needed for many
|
||||
configuration for a site. In fact, a config file isn't even needed for many
|
||||
websites since the defaults follow commonly used patterns.
|
||||
|
||||
Hugo expects to find the config file in the root of the source directory and
|
||||
will look there first for a `config.toml` file. If none is present it will
|
||||
will look there first for a `config.toml` file. If none is present, it will
|
||||
then look for a `config.yaml` file, followed by a `config.json` file.
|
||||
|
||||
The config file is a site-wide config. The config file provides directions to
|
||||
|
|
|
|||
|
|
@ -12,17 +12,17 @@ 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 and Drupal which run on your web server expensively building a page
|
||||
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.
|
||||
|
||||
Sites built with Hugo are extremely fast and very secure. Hugo sites can
|
||||
be hosted anywhere including Heroku, GoDaddy, GitHub pages, S3
|
||||
and Cloudfront and work well with CDNs. Hugo sites run without dependencies
|
||||
on expensive run times like Ruby, Python or PHP and without dependencies
|
||||
be hosted anywhere, including Heroku, GoDaddy, GitHub Pages, Amazon S3
|
||||
and CloudFront, and work well with CDNs. Hugo sites run without dependencies
|
||||
on expensive runtimes like Ruby, Python or PHP and without dependencies
|
||||
on any databases.
|
||||
|
||||
We think of Hugo as the ideal website creation tool. With nearly instant
|
||||
|
|
@ -32,7 +32,7 @@ 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
|
||||
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:
|
||||
|
|
@ -77,7 +77,7 @@ Hugo boasts the following features:
|
|||
* 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)
|
||||
See what's coming next in the [roadmap](/meta/roadmap).
|
||||
|
||||
## Who should use Hugo?
|
||||
|
||||
|
|
@ -94,23 +94,23 @@ pages.
|
|||
|
||||
## 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
|
||||
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
|
||||
my from writing great content.
|
||||
simpler Markdown. Overall, I felt like it got in my way more than it helped
|
||||
me from writing great content.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
in a language. I began developing Hugo in Go and fell in love with the
|
||||
language. I hope you will enjoy using (and contributing to) Hugo as much
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ The top level of a source directory will typically have the following elements:
|
|||
▸ themes/
|
||||
config.toml
|
||||
|
||||
Learn more about the different directories and what their purpose is
|
||||
Learn more about the different directories and what their purpose is:
|
||||
|
||||
* [config](/overview/configuration)
|
||||
* [archetypes](/content/archetypes)
|
||||
|
|
@ -85,6 +85,6 @@ An example directory may look like:
|
|||
|
||||
This directory structure tells us a lot about this site:
|
||||
|
||||
1. the website intends to have two different types of content, posts and quotes.
|
||||
2. It will also apply two different indexes to that content, categories and tags.
|
||||
3. It will be displaying content in 3 different views, a list, a summary and a full page view.
|
||||
1. The website intends to have two different types of content: posts and quotes.
|
||||
2. It will also apply two different indexes to that content: categories and tags.
|
||||
3. It will be displaying content in 3 different views: a list, a summary and a full page view.
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ Make sure either hugo is in your path or provide a path to it.
|
|||
|
||||
Use "hugo help [command]" for more information about that command.
|
||||
|
||||
## Common Usage Example:
|
||||
## Common Usage Example
|
||||
|
||||
The most common use is probably to run hugo with your current
|
||||
directory being the input directory.
|
||||
|
|
|
|||
|
|
@ -28,8 +28,8 @@ all site content accessible from .Data.Pages
|
|||
## 404.html
|
||||
This is a basic example of a 404.html template:
|
||||
|
||||
{{ template "chrome/header.html" . }}
|
||||
{{ template "chrome/subheader.html" . }}
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
|
||||
<section id="main">
|
||||
<div>
|
||||
|
|
@ -37,5 +37,5 @@ This is a basic example of a 404.html template:
|
|||
</div>
|
||||
</section>
|
||||
|
||||
{{ template "chrome/footer.html" }}
|
||||
{{ partial "footer.html" }}
|
||||
|
||||
|
|
|
|||
|
|
@ -12,22 +12,22 @@ title: Single Content Template
|
|||
weight: 30
|
||||
---
|
||||
|
||||
The primary view of content in hugo is the single view. Hugo for every
|
||||
markdown file provided hugo will render it with a single template.
|
||||
The primary view of content in Hugo is the single view. Hugo, for every
|
||||
Markdown file provided, will render it with a single template.
|
||||
|
||||
|
||||
## Which Template will be rendered?
|
||||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
Users can specify the `type` and `layout` in the [front-matter](/content/front-matter). `Section`
|
||||
is determined based on the content file’s location. If `type` is provide
|
||||
is determined based on the content file’s location. If `type` is provide,
|
||||
it will be used instead of `section`.
|
||||
|
||||
### Single
|
||||
|
|
@ -50,7 +50,7 @@ a default content type.
|
|||
|
||||
The default content template to be used in the event that a specific
|
||||
template has not been provided for that type. The default type works the
|
||||
same as the other types but the directory must be called "\_default".
|
||||
same as the other types, but the directory must be called "\_default".
|
||||
|
||||
▾ layouts/
|
||||
▾ _default/
|
||||
|
|
|
|||
|
|
@ -28,19 +28,19 @@ Go documentation for the built-in functions can be found [here](http://golang.or
|
|||
Return true if the parameter is set.
|
||||
Takes either a slice, array or channel and an index or a map and a key as input.
|
||||
|
||||
eg. {{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}
|
||||
e.g. {{ if isset .Params "project_url" }} {{ index .Params "project_url" }}{{ end }}
|
||||
|
||||
### echoParam
|
||||
If parameter is set, then echo it.
|
||||
|
||||
eg. {{echoParam .Params "project_url" }}
|
||||
e.g. {{echoParam .Params "project_url" }}
|
||||
|
||||
### first
|
||||
Slices an array to only the first X elements.
|
||||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
eg.
|
||||
e.g.
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
|
|
@ -50,7 +50,7 @@ Filters an array to only elements containing a matching value for a given field.
|
|||
|
||||
Works on [lists](/templates/list/), [taxonomies](/taxonomies/displaying/), [terms](/templates/terms/), [groups](/templates/list/)
|
||||
|
||||
eg.
|
||||
e.g.
|
||||
|
||||
{{ range where .Data.Pages "Section" "post" }}
|
||||
{{ .Content}}
|
||||
|
|
@ -58,7 +58,7 @@ eg.
|
|||
|
||||
*where and first can be stacked*
|
||||
|
||||
eg.
|
||||
e.g.
|
||||
|
||||
{{ range first 5 (where .Data.Pages "Section" "post") }}
|
||||
{{ .Content}}
|
||||
|
|
@ -70,61 +70,61 @@ eg.
|
|||
### add
|
||||
Adds two integers.
|
||||
|
||||
eg {{add 1 2}} -> 3
|
||||
e.g. {{add 1 2}} → 3
|
||||
|
||||
### sub
|
||||
Subtracts two integers.
|
||||
|
||||
eg {{sub 3 2}} -> 1
|
||||
e.g. {{sub 3 2}} → 1
|
||||
|
||||
### div
|
||||
Divides two integers.
|
||||
|
||||
eg {{div 6 3}} -> 2
|
||||
e.g. {{div 6 3}} → 2
|
||||
|
||||
### mul
|
||||
Multiplies two integers.
|
||||
|
||||
eg {{mul 2 3}} -> 6
|
||||
e.g. {{mul 2 3}} → 6
|
||||
|
||||
### mod
|
||||
Modulus of two integers.
|
||||
|
||||
eg {{mod 15 3}} -> 0
|
||||
e.g. {{mod 15 3}} → 0
|
||||
|
||||
### modBool
|
||||
Boolean of modulus of two integers.
|
||||
true if modulus is 0.
|
||||
|
||||
eg {{modBool 15 3}} -> true
|
||||
e.g. {{modBool 15 3}} → true
|
||||
|
||||
## Strings
|
||||
|
||||
### urlize
|
||||
Takes a string and sanitizes it for usage in urls, converts spaces to "-".
|
||||
Takes a string and sanitizes it for usage in URLs, converts spaces to "-".
|
||||
|
||||
eg. <a href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
e.g. <a href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
|
||||
### safeHtml
|
||||
Declares the provided string as "safe" so go templates will not filter it.
|
||||
Declares the provided string as "safe" so Go templates will not filter it.
|
||||
|
||||
eg. {{ .Params.CopyrightHTML | safeHtml }}
|
||||
e.g. {{ .Params.CopyrightHTML | safeHtml }}
|
||||
|
||||
### lower
|
||||
Convert all characters in string to lowercase.
|
||||
|
||||
eg {{lower "BatMan"}} -> "batman"
|
||||
e.g. {{lower "BatMan"}} → "batman"
|
||||
|
||||
### upper
|
||||
Convert all characters in string to uppercase.
|
||||
|
||||
eg {{upper "BatMan"}} -> "BATMAN"
|
||||
e.g. {{upper "BatMan"}} → "BATMAN"
|
||||
|
||||
### title
|
||||
Convert all characters in string to titlecase.
|
||||
|
||||
eg {{title "BatMan"}} -> "Batman"
|
||||
e.g. {{title "BatMan"}} → "Batman"
|
||||
|
||||
### highlight
|
||||
Take a string of code and a language, uses pygments to return the syntax
|
||||
highlighted code in html. Used in the [highlight shortcode](/extras/highlighting).
|
||||
Take a string of code and a language, uses Pygments to return the syntax
|
||||
highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting).
|
||||
|
|
|
|||
|
|
@ -34,8 +34,8 @@ details can be found in the [Go docs][gohtmltemplate].
|
|||
|
||||
## Basic Syntax
|
||||
|
||||
Go lang templates are html files with the addition of variables and
|
||||
functions.
|
||||
Go lang templates are HTML files with the addition of variables and
|
||||
functions.
|
||||
|
||||
**Go variables and functions are accessible within {{ }}**
|
||||
|
||||
|
|
@ -45,7 +45,7 @@ Accessing a predefined variable "foo":
|
|||
|
||||
**Parameters are separated using spaces**
|
||||
|
||||
Calling the add function with input of 1, 2:
|
||||
Calling the `add` function with input of 1, 2:
|
||||
|
||||
{{ add 1 2 }}
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -79,13 +79,13 @@ Variables can also be defined and referenced.
|
|||
|
||||
## Functions
|
||||
|
||||
Go template ship with a few functions which provide basic functionality. The go
|
||||
Go template ships with a few functions which provide basic functionality. The Go
|
||||
template system also provides a mechanism for applications to extend the
|
||||
available functions with their own. [Hugo template
|
||||
functions](/layout/functions) provide some additional functionality we believe
|
||||
are useful for building websites. Functions are called by using their name
|
||||
followed by the required parameters separated by spaces. Template
|
||||
functions cannot be added without recompiling hugo.
|
||||
functions cannot be added without recompiling Hugo.
|
||||
|
||||
**Example:**
|
||||
|
||||
|
|
@ -93,86 +93,91 @@ functions cannot be added without recompiling hugo.
|
|||
|
||||
## Includes
|
||||
|
||||
When including another template you will pass to it the data it will be
|
||||
able to access. To pass along the current context please remember to
|
||||
When including another template, you will pass to it the data it will be
|
||||
able to access. To pass along the current context, please remember to
|
||||
include a trailing dot. The templates location will always be starting at
|
||||
the /layout/ directory within Hugo.
|
||||
|
||||
**Example:**
|
||||
|
||||
{{ template "chrome/header.html" . }}
|
||||
{{ template "partials/header.html" . }}
|
||||
|
||||
And, starting with Hugo v0.12, you may also use the `partial` call
|
||||
for [partial templates](/templates/partials/):
|
||||
|
||||
{{ partial "header.html" . }}
|
||||
|
||||
|
||||
## Logic
|
||||
|
||||
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
|
||||
range.
|
||||
|
||||
**Example 1: Using Context**
|
||||
|
||||
{{ range array }}
|
||||
{{ range array }}
|
||||
{{ . }}
|
||||
{{ end }}
|
||||
|
||||
**Example 2: Declaring value variable name**
|
||||
|
||||
{{range $element := array}}
|
||||
{{ $element }}
|
||||
{{range $element := array}}
|
||||
{{ $element }}
|
||||
{{ end }}
|
||||
|
||||
**Example 2: Declaring key and value variable name**
|
||||
|
||||
{{range $index, $element := array}}
|
||||
{{ $index }}
|
||||
{{ $element }}
|
||||
{{ $index }}
|
||||
{{ $element }}
|
||||
{{ end }}
|
||||
|
||||
### Conditionals
|
||||
### Conditionals
|
||||
|
||||
If, else, with, or, & and provide the framework for handling conditional
|
||||
logic in Go Templates. Like range, each statement is closed with `end`.
|
||||
`if`, `else`, `with`, `or` & `and` provide the framework for handling conditional
|
||||
logic in Go Templates. Like `range`, each statement is closed with `end`.
|
||||
|
||||
|
||||
Go Templates treat the following values as false:
|
||||
Go Templates treat the following values as false:
|
||||
|
||||
* false
|
||||
* 0
|
||||
* 0
|
||||
* any array, slice, map, or string of length zero
|
||||
|
||||
**Example 1: If**
|
||||
**Example 1: `if`**
|
||||
|
||||
{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
|
||||
|
||||
**Example 2: If -> Else**
|
||||
**Example 2: `if` … `else`**
|
||||
|
||||
{{ if isset .Params "alt" }}
|
||||
{{ if isset .Params "alt" }}
|
||||
{{ index .Params "alt" }}
|
||||
{{else}}
|
||||
{{ index .Params "caption" }}
|
||||
{{ end }}
|
||||
|
||||
**Example 3: And & Or**
|
||||
**Example 3: `and` & `or`**
|
||||
|
||||
{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
|
||||
|
||||
**Example 4: With**
|
||||
**Example 4: `with`**
|
||||
|
||||
An alternative way of writing "if" and then referencing the same value
|
||||
is to use "with" instead. With rebinds the context `.` within its scope,
|
||||
An alternative way of writing "`if`" and then referencing the same value
|
||||
is to use "`with`" instead. `with` rebinds the context `.` within its scope,
|
||||
and skips the block if the variable is absent.
|
||||
|
||||
The first example above could be simplified as:
|
||||
|
||||
{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
|
||||
|
||||
**Example 5: If -> Else If**
|
||||
**Example 5: `if` … `else if`**
|
||||
|
||||
{{ if isset .Params "alt" }}
|
||||
{{ if isset .Params "alt" }}
|
||||
{{ index .Params "alt" }}
|
||||
{{ else if isset .Params "caption" }}
|
||||
{{ index .Params "caption" }}
|
||||
|
|
@ -182,48 +187,48 @@ The first example above could be simplified as:
|
|||
|
||||
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.
|
||||
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
|
||||
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.
|
||||
becomes the last parameter of the next pipeline.
|
||||
|
||||
A few simple examples should help convey how to use the pipe.
|
||||
|
||||
**Example 1 :**
|
||||
**Example 1:**
|
||||
|
||||
{{ if eq 1 1 }} Same {{ end }}
|
||||
|
||||
is the same as
|
||||
is the same as
|
||||
|
||||
{{ eq 1 1 | if }} Same {{ end }}
|
||||
|
||||
It does look odd to place the if at the end, but it does provide a good
|
||||
illustration of how to use the pipes.
|
||||
|
||||
**Example 2 :**
|
||||
**Example 2:**
|
||||
|
||||
{{ index .Params "disqus_url" | html }}
|
||||
|
||||
Access the page parameter called "disqus_url" and escape the HTML.
|
||||
|
||||
**Example 3 :**
|
||||
**Example 3:**
|
||||
|
||||
{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
|
||||
Stuff Here
|
||||
{{ end }}
|
||||
|
||||
Could be rewritten as
|
||||
Could be rewritten as
|
||||
|
||||
{{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }}
|
||||
Stuff Here
|
||||
Stuff Here
|
||||
{{ end }}
|
||||
|
||||
### Internet Explorer conditional comments using Pipes
|
||||
|
||||
By default Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
|
||||
By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
|
||||
|
||||
{{ "<!--[if lt IE 9]>" | safeHtml }}
|
||||
<script src="html5shiv.js"></script>
|
||||
|
|
@ -251,24 +256,24 @@ 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.
|
||||
|
||||
# Hugo Parameters
|
||||
# Hugo Parameters
|
||||
|
||||
Hugo provides the option of passing values to the template language
|
||||
through the site configuration (for sitewide values), or through the meta
|
||||
data of each specific piece of content. You can define any values of any
|
||||
type (supported by your front matter/config format) and use them however
|
||||
you want to inside of your templates.
|
||||
you want to inside of your templates.
|
||||
|
||||
|
||||
## Using Content (page) Parameters
|
||||
## Using Content (page) Parameters
|
||||
|
||||
In each piece of content you can provide variables to be used by the
|
||||
templates. This happens in the [front matter](/content/front-matter).
|
||||
In each piece of content, you can provide variables to be used by the
|
||||
templates. This happens in the [front matter](/content/front-matter).
|
||||
|
||||
An example of this is used in this documentation site. Most of the pages
|
||||
benefit from having the table of contents provided. Sometimes the TOC just
|
||||
doesn't make a lot of sense. We've defined a variable in our front matter
|
||||
of some pages to turn off the TOC from being displayed.
|
||||
of some pages to turn off the TOC from being displayed.
|
||||
|
||||
Here is the example front matter:
|
||||
|
||||
|
|
@ -295,8 +300,8 @@ Here is the corresponding code inside of the template:
|
|||
|
||||
|
||||
## Using Site (config) Parameters
|
||||
In your top-level configuration file (eg, `config.yaml`) you can define site
|
||||
parameters, which are values which will be available to you in chrome.
|
||||
In your top-level configuration file (e.g., `config.yaml`) you can define site
|
||||
parameters, which are values which will be available to you in partials.
|
||||
|
||||
For instance, you might declare:
|
||||
|
||||
|
|
@ -319,8 +324,8 @@ January 1st, instead of hunting through your templates.
|
|||
</footer>{{end}}
|
||||
```
|
||||
|
||||
An alternative way of writing the "if" and then referencing the same value
|
||||
is to use "with" instead. With rebinds the context `.` within its scope,
|
||||
An alternative way of writing the "`if`" and then referencing the same value
|
||||
is to use "`with`" instead. With rebinds the context `.` within its scope,
|
||||
and skips the block if the variable is absent:
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -24,17 +24,17 @@ bootstrapping a new site and template. It is also the only required
|
|||
template when using a single page site.*
|
||||
|
||||
In addition to the standard node variables, the homepage has access to
|
||||
all site content accessible from .Data.Pages . Details on how to use the
|
||||
list of pages can be found in the [Lists Template](/templates/list/)
|
||||
all site content accessible from `.Data.Pages`. Details on how to use the
|
||||
list of pages can be found in the [Lists Template](/templates/list/).
|
||||
|
||||
## Which Template will be rendered?
|
||||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites, only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
* /layouts/index.html
|
||||
|
|
@ -44,7 +44,7 @@ the list will be needed.
|
|||
* /themes/`THEME`/layouts/\_default/list.html
|
||||
* /themes/`THEME`/layouts/\_default/single.html
|
||||
|
||||
## example index.html
|
||||
## Example index.html
|
||||
This content template is used for [spf13.com](http://spf13.com).
|
||||
|
||||
It makes use of [partial templates](/templates/partials) and uses a similar approach as a [List](/templates/list/).
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ weight: 40
|
|||
---
|
||||
|
||||
A list template is any template that will be used to render multiple pieces of
|
||||
content in a single html page (with the exception of the [homepage](/layout/homepage) which has a
|
||||
content in a single HTML page (with the exception of the [homepage](/layout/homepage) which has a
|
||||
dedicated template).
|
||||
|
||||
We are using the term list in its truest sense, a sequential arrangement
|
||||
|
|
@ -26,10 +26,10 @@ taxonomies and sections.
|
|||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
|
||||
|
|
@ -60,8 +60,8 @@ A Taxonomy will be rendered at /`PLURAL`/`TERM`/
|
|||
|
||||
A Section’s RSS will be rendered at /`SECTION`/index.xml
|
||||
|
||||
*Hugo ships with it’s own ATOM 2.0 RSS template. In most cases this will
|
||||
be sufficient and an RSS template will not need to be provided by the
|
||||
*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will
|
||||
be sufficient, and an RSS template will not need to be provided by the
|
||||
user.*
|
||||
|
||||
Hugo provides the ability for you to define any RSS type you wish, and
|
||||
|
|
@ -76,8 +76,8 @@ can have different RSS files for each section and taxonomy.
|
|||
|
||||
A Taxonomy’s RSS will be rendered at /`PLURAL`/`TERM`/index.xml
|
||||
|
||||
*Hugo ships with it’s own ATOM 2.0 RSS template. In most cases this will
|
||||
be sufficient and an RSS template will not need to be provided by the
|
||||
*Hugo ships with its own ATOM 2.0 RSS template. In most cases this will
|
||||
be sufficient, and an RSS template will not need to be provided by the
|
||||
user.*
|
||||
|
||||
Hugo provides the ability for you to define any RSS type you wish, and
|
||||
|
|
@ -254,8 +254,8 @@ your list templates:
|
|||
|
||||
### Reversing Key Order
|
||||
|
||||
The ordering of the groups is performed by keys in alpha-numeric order (A-Z,
|
||||
1-100) and in reverse chronological order (newest first) for dates.
|
||||
The ordering of the groups is performed by keys in alpha-numeric order (A–Z,
|
||||
1–100) and in reverse chronological order (newest first) for dates.
|
||||
|
||||
While these are logical defaults, they are not always the desired order. There
|
||||
are two different syntaxes to change the order, they both work the same way, so
|
||||
|
|
@ -280,7 +280,7 @@ it’s really just a matter of preference.
|
|||
|
||||
### Ordering Pages within Group
|
||||
|
||||
Because Grouping returns a key and a slice of pages all of the ordering methods listed above are available.
|
||||
Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
|
||||
|
||||
In this example I’ve ordered the groups in chronological order and the content
|
||||
within each group in alphabetical order by title.
|
||||
|
|
@ -305,7 +305,7 @@ you can do just that.
|
|||
|
||||
### First
|
||||
|
||||
`first` works like the limit keyword in SQL. It reduces the array to only the
|
||||
`first` works like the `limit` keyword in SQL. It reduces the array to only the
|
||||
first X elements. It takes the array and number of elements as input.
|
||||
|
||||
{{ range first 10 .Data.Pages }}
|
||||
|
|
@ -314,7 +314,7 @@ first X elements. It takes the array and number of elements as input.
|
|||
|
||||
### Where
|
||||
|
||||
`where` works in a similar manner to the where keyword in SQL. It selects all
|
||||
`where` works in a similar manner to the `where` keyword in SQL. It selects all
|
||||
elements of the slice that match the provided field and value. It takes three
|
||||
arguments 'array or slice of maps or structs', 'key or field name' and 'match
|
||||
value'
|
||||
|
|
|
|||
|
|
@ -11,14 +11,14 @@ title: Partial Templates
|
|||
weight: 80
|
||||
---
|
||||
|
||||
In practice it's very convenient to split out common template portions into a
|
||||
In practice, it's very convenient to split out common template portions into a
|
||||
partial template that can be included anywhere. As you create the rest of your
|
||||
templates you will include templates from the /layout/partials directory.
|
||||
templates, you will include templates from the /layout/partials directory.
|
||||
|
||||
Partials are especially important for themes as it gives users an opportunity
|
||||
to overwrite just a small part of your theme, while maintaining future compatibility.
|
||||
|
||||
Theme developers may want to include a few partials with empty html
|
||||
Theme developers may want to include a few partials with empty HTML
|
||||
files in the theme just so end users have an easy place to inject their
|
||||
customized content.
|
||||
|
||||
|
|
@ -33,25 +33,25 @@ like good names to use for inclusion in your other templates.
|
|||
footer.html
|
||||
|
||||
By ensuring that we only reference [variables](/layout/variables/)
|
||||
used for both nodes and pages we can use the same partials for both.
|
||||
used for both nodes and pages, we can use the same partials for both.
|
||||
|
||||
## Partial vs Template
|
||||
|
||||
Version v0.12 of Hugo introduced the partial call inside the template system.
|
||||
Version v0.12 of Hugo introduced the `partial` call inside the template system.
|
||||
This is a change to the way partials were handled previously inside the
|
||||
template system. In earlier versions, Hugo didn’t treat partials specially and
|
||||
template system. In earlier versions, Hugo didn’t treat partials specially, and
|
||||
you could include a partial template with the `template` call in the standard
|
||||
template language.
|
||||
|
||||
With the addition of the theme system in v0.11 it became apparent that a theme
|
||||
With the addition of the theme system in v0.11, it became apparent that a theme
|
||||
& override aware partial was needed.
|
||||
|
||||
When using Hugo v0.12 and above please use the `partial` call (and leave out
|
||||
the “partial/” path). The old approach will still work, but won’t benefit from
|
||||
When using Hugo v0.12 and above, please use the `partial` call (and leave out
|
||||
the “partial/” path). The old approach would still work, but wouldn’t benefit from
|
||||
the ability to have users override the partial theme file with local layouts.
|
||||
|
||||
## example header.html
|
||||
This header template is used for [spf13.com](http://spf13.com).
|
||||
## Example header.html
|
||||
This header template is used for [spf13.com](http://spf13.com):
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
|
||||
|
|
@ -69,13 +69,13 @@ This header template is used for [spf13.com](http://spf13.com).
|
|||
</head>
|
||||
<body lang="en">
|
||||
|
||||
## example footer.html
|
||||
This header template is used for [spf13.com](http://spf13.com).
|
||||
## Example footer.html
|
||||
This footer template is used for [spf13.com](http://spf13.com):
|
||||
|
||||
<footer>
|
||||
<div>
|
||||
<p>
|
||||
© 2013 Steve Francia.
|
||||
© 2013-14 Steve Francia.
|
||||
<a href="http://creativecommons.org/licenses/by/3.0/" title="Creative Commons Attribution">Some rights reserved</a>;
|
||||
please attribute properly and link back. Hosted by <a href="http://servergrove.com">ServerGrove</a>.
|
||||
</p>
|
||||
|
|
@ -100,4 +100,4 @@ This header template is used for [spf13.com](http://spf13.com).
|
|||
</html>
|
||||
|
||||
**For examples of referencing these templates, see [single content
|
||||
templates](/templates/content), [list templates](/templates/list) and [homepage templates](/templates/homepage)**
|
||||
templates](/templates/content), [list templates](/templates/list) and [homepage templates](/templates/homepage).**
|
||||
|
|
|
|||
|
|
@ -14,9 +14,9 @@ weight: 90
|
|||
---
|
||||
|
||||
Like all other templates, you can use a single RSS template to generate
|
||||
all of your RSS feeds or you can create a specific template for each
|
||||
individual feed. Unlinke other templates, *Hugo ships with it’s own ATOM
|
||||
2.0 RSS template. In most cases this will be sufficient and an RSS
|
||||
all of your RSS feeds, or you can create a specific template for each
|
||||
individual feed. Unlike other templates, *Hugo ships with its own ATOM
|
||||
2.0 RSS template. In most cases this will be sufficient, and an RSS
|
||||
template will not need to be provided by the user.*
|
||||
|
||||
RSS pages are of the type "node" and have all the [node
|
||||
|
|
@ -27,10 +27,10 @@ variables](/layout/variables/) available to use in the templates.
|
|||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
### Main RSS
|
||||
|
|
@ -58,7 +58,7 @@ the list will be needed.
|
|||
|
||||
## Configuring RSS
|
||||
|
||||
If the following are provided in the site’s config file then then they
|
||||
If the following are provided in the site’s config file, then they
|
||||
will be included in the RSS output. Example values are provided.
|
||||
|
||||
languageCode = "en-us"
|
||||
|
|
@ -95,6 +95,6 @@ ATOM 2.0 Spec.
|
|||
</rss>
|
||||
|
||||
*Important: Hugo will automatically add the following header line to this file
|
||||
on render...please don't include this in the template as it's not valid HTML.*
|
||||
on render… please don't include this in the template as it's not valid HTML.*
|
||||
|
||||
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
|
||||
|
|
|
|||
|
|
@ -22,10 +22,10 @@ as that template is a list of content, where this is a list of meta data.
|
|||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
A Taxonomy Terms List will be rendered at /`PLURAL`/
|
||||
|
|
@ -43,15 +43,15 @@ dedicated page for the terms.
|
|||
|
||||
Taxonomy Terms pages are of the type "node" and have all the [node
|
||||
variables](/templates/variables/) and [site
|
||||
variables](/templates/variables/) available to use in the templates.
|
||||
variables](/templates/variables/) available to use in the templates.
|
||||
|
||||
Taxonomy Terms pages will additionally have:
|
||||
|
||||
**.Data.Singular** The singular name of the taxonomy <br>
|
||||
**.Data.Plural** The plural name of the taxonomy<br>
|
||||
**.Data.Terms** The taxonomy itself<br>
|
||||
**.Data.Terms.Alphabetical** The Terms alphabetized<br>
|
||||
**.Data.Terms.ByCount** The Terms ordered by popularity<br>
|
||||
* **.Data.Singular** The singular name of the taxonomy
|
||||
* **.Data.Plural** The plural name of the taxonomy
|
||||
* **.Data.Terms** The taxonomy itself
|
||||
* **.Data.Terms.Alphabetical** The Terms alphabetized
|
||||
* **.Data.Terms.ByCount** The Terms ordered by popularity
|
||||
|
||||
## Example terms.html file
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ This particular template lists all of the Tags used on
|
|||
[spf13.com](http://spf13.com) and provides a count for the number of pieces of
|
||||
content tagged with each tag.
|
||||
|
||||
.Data.Terms is an map of terms => [contents]
|
||||
`.Data.Terms` is an map of terms ⇒ [contents]
|
||||
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ provide a specific view for a given type and continue to use the
|
|||
|
||||
Hugo also has support for a default content template to be used in the event
|
||||
that a specific template has not been provided for that type. The default type
|
||||
works the same as the other types but the directory must be called "_default".
|
||||
works the same as the other types, but the directory must be called "_default".
|
||||
Content views can also be defined in the "_default" directory.
|
||||
|
||||
|
||||
|
|
@ -58,10 +58,10 @@ Content views can also be defined in the "_default" directory.
|
|||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present
|
||||
than the next one in the list will be used. This enables you to craft
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
then necessary. For most sites only the \_default file at the end of
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
|
||||
* /layouts/`TYPE`/`VIEW`.html
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@ weight: 10
|
|||
|
||||
## Intro
|
||||
|
||||
Many Hugo users have expressed interest in seeing a tutorial for how to set up a blog that generated by Hugo and hosted on GitHub pages. This tutorial will do just that. We only require that the reader has Hugo installed correctly and is comfortable with git and GitHub.
|
||||
Many Hugo users have expressed interest in seeing a tutorial for how to set up a blog that generated by Hugo and hosted on GitHub Pages. This tutorial will do just that. We only require that the reader has Hugo installed correctly and is comfortable with git and GitHub.
|
||||
|
||||
During this tutorial, I will walk you through the main steps I took to create an example blog available at [http://spencerlyon2.github.io/hugo_gh_blog](http://spencerlyon2.github.io/hugo_gh_blog). The source code for this blog is on [GitHub](https://github.com/spencerlyon2/hugo_gh_blog). Readers are encouraged to download the example repository and follow along.
|
||||
|
||||
### Find a Home for Your Files
|
||||
|
||||
As our goal is to host a website using GitHub pages, it is natural for us to host the content of the page in a GitHub repository. Thus, the first step is to either create a new repository on GitHub or create a new directory within an existing repository where the content of the website will live. To do this I created the repository [spencerlyon2/hugo_gh_blog](https://github.com/spencerlyon2/hugo_gh_blog).
|
||||
As our goal is to host a website using GitHub Pages, it is natural for us to host the content of the page in a GitHub repository. Thus, the first step is to either create a new repository on GitHub or create a new directory within an existing repository where the content of the website will live. To do this I created the repository [spencerlyon2/hugo_gh_blog](https://github.com/spencerlyon2/hugo_gh_blog).
|
||||
|
||||
## Create the Blog
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ Because there are so many files needed to fully compose a complete website, I wi
|
|||
lanyon.css
|
||||
poole.css
|
||||
▾ layouts/
|
||||
▾ chrome/
|
||||
▾ partials/
|
||||
<templates to be used in other files>.html
|
||||
▾ posts/
|
||||
li.html
|
||||
|
|
@ -97,9 +97,9 @@ The keys set in this section are the mandatory `title` and `date` as well as the
|
|||
|
||||
## Configure `git` Workflow
|
||||
|
||||
Once the site is set up and working properly, we need to push it to the correct branch of a GitHub repository so the website can be served through GitHub Pages. There are many ways to do this. Here I will show the workflow I currently use to manage my websites that are hosted through GitHub pages.
|
||||
Once the site is set up and working properly, we need to push it to the correct branch of a GitHub repository so the website can be served through GitHub Pages. There are many ways to do this. Here I will show the workflow I currently use to manage my websites that are hosted through GitHub Pages.
|
||||
|
||||
GitHub pages will serve up a website for any repository that has a branch called `gh-pages` with a valid `index.html` file at that branch's root. A typical workflow might be to keep the content of a website on the `master` branch of a repository and the generated website on the `gh-pages` branch. This provides nice separation between input and output, but can be very tedious to work with. As a workaround we will use the `git subtree` family of commands to have the `public` directory (or whatever `publishdir` is set to in your `config.yaml`) mirror the root of the `gh-pages` branch of the repository. This will allow us to do all our work on the `master` branch, run Hugo have have the site output into the `public` directory, and then push that directory directly to the correct place for GitHub Pages to serve our site.
|
||||
GitHub Pages will serve up a website for any repository that has a branch called `gh-pages` with a valid `index.html` file at that branch's root. A typical workflow might be to keep the content of a website on the `master` branch of a repository and the generated website on the `gh-pages` branch. This provides nice separation between input and output, but can be very tedious to work with. As a workaround we will use the `git subtree` family of commands to have the `public` directory (or whatever `publishdir` is set to in your `config.yaml`) mirror the root of the `gh-pages` branch of the repository. This will allow us to do all our work on the `master` branch, run Hugo have have the site output into the `public` directory, and then push that directory directly to the correct place for GitHub Pages to serve our site.
|
||||
|
||||
To get this properly set up we will execute a series of commands at the terminal. I will include all of them in one place here for easy copy and paste, and will explain what each line does via comments. Note that this is to be run from the `<root>` directory (wherever the `content` and `layout` folders of your Hugo project live). Also note that you will need to change the commands that have the example repository GitHub address so that they point to your repo.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ weight: 10
|
|||
|
||||
[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
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ The first step is to enable MathJax on pages that you would like to have typeset
|
|||
src="https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
|
||||
One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/chrome/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
|
||||
One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
|
||||
|
||||
### Options and Features
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ After enabling MathJax, any math entered in-between proper markers (see document
|
|||
|
||||
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 was 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({
|
||||
|
|
@ -75,8 +75,8 @@ As before, this content should be included in the HTML source of each page that
|
|||
border: inherit;
|
||||
color: #515151;}
|
||||
|
||||
In the css snippet notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my css. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
|
||||
In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
|
||||
|
||||
### Usage
|
||||
|
||||
With this setup, everything is inplace for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!
|
||||
With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `<div>$$TeX Code$$</div>`. All the math will be properly typeset and displayed within your Hugo generated web page!
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ With Jekyll, something that looked like
|
|||
▾ images/
|
||||
logo.png
|
||||
|
||||
Should become
|
||||
should become
|
||||
|
||||
▾ <root>/
|
||||
▾ static/
|
||||
|
|
@ -27,24 +27,24 @@ Should become
|
|||
Additionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`.
|
||||
|
||||
## Create your Hugo configuration file
|
||||
Hugo can read your configuration as json, yaml or toml. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.
|
||||
Hugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.
|
||||
|
||||
## Set your configuration publish folder to `_site`
|
||||
The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:
|
||||
|
||||
1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
|
||||
|
||||
git submodule deinit _site
|
||||
git rm _site
|
||||
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
|
||||
git submodule deinit _site
|
||||
git rm _site
|
||||
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
|
||||
|
||||
1. Or, change the Hugo configuration to use `_site` instead of `public`.
|
||||
2. Or, change the Hugo configuration to use `_site` instead of `public`.
|
||||
|
||||
{
|
||||
..
|
||||
"publishdir": "_site",
|
||||
..
|
||||
}
|
||||
{
|
||||
..
|
||||
"publishdir": "_site",
|
||||
..
|
||||
}
|
||||
|
||||
## Convert Jekyll templates to Hugo templates
|
||||
That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.
|
||||
|
|
@ -52,7 +52,7 @@ That's the bulk of the work right here. The documentation is your friend. You sh
|
|||
As a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net) took me no more than a few hours.
|
||||
|
||||
## Convert Jekyll plugins to Hugo shortcodes
|
||||
Jekyll has [plugins](http://jekyllrb.com/docs/plugins/), Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.
|
||||
Jekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.
|
||||
|
||||
### Implementation
|
||||
As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.
|
||||
|
|
|
|||
|
|
@ -230,7 +230,7 @@
|
|||
<li><a href="http://github.com/spf13/hugo" class="icon-octocat icon-2x"></a></li>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>Copyright © Steve Francia 2013 - 2014</p>
|
||||
<p>Copyright © Steve Francia 2013–2014</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
2
main.go
2
main.go
|
|
@ -1,4 +1,4 @@
|
|||
// Copyright © 2013 Steve Francia <spf@spf13.com>.
|
||||
// Copyright © 2013-14 Steve Francia <spf@spf13.com>.
|
||||
//
|
||||
// Licensed under the Simple Public License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
|
|
|
|||
Loading…
Reference in a new issue