Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang.
-## Branches
+## Contributing
-* The `master` branch is the **current Hugo version** and will be auto-deployed to [gohugo.io/](https://gohugo.io/).
-* Anything not relevant to the current Hugo version goes into the `dev` branch.
-* Changes in [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs) will, in general, be merged once every release, but can be manually merged/cherry picked if needed. This goes both ways.
-* All contributions that is not tightly coupled with code changes, should be made directly to `hugoDocs`.
-* But we also merge PRs into [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs), but preferably changes that is related to the code in the PR itself
+We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you.
-To summarize, we have two branches in this repository: `master` (current Hugo) and `dev` (next Hugo).
+Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository.
+
+*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
+
+
+## Build
+
+To view the documentation site locally, you need to clone this repository with submodules:
+
+```bash
+git clone --recursive https://github.com/gohugoio/hugoDocs.git
+```
+
+Or if you already have a clone locally:
+
+```bash
+git submodule update --init
+```
+Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo).
+
+Then to view the docs in your browser, run Hugo and open up the link:
+```bash
+hugo serve
+Started building sites ...
+.
+.
+Serving pages from memory
+Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
+Press Ctrl+C to stop
+```
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
+
+# Highlighting config (Pygments)
+# It is (currently) not in use, but you can do ```go in a content file if you want to.
+pygmentsCodeFences = true
+
+# See https://help.farbox.com/pygments.html
+pygmentsStyle = "friendly"
+
[outputs]
home = [ "HTML", "RSS", "REDIR" ]
+section = [ "HTML", "RSS"]
[mediaTypes]
[mediaTypes."text/netlify"]
- heading: Custom Outputs
image_path: /images/icon-custom-outputs.svg
- tagline: HTML not Enough?
+ tagline: HTML not enough?
copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own.
sections:
- heading: "100s of Themes"
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
-{{% code file="apache-notice.txt" download="apache-notice.txt" %}}
-```
+{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-```
-{{% /code %}}
+{{< /code >}}
The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
-```bash
+```
hugo new <content-section>/<file-name.md>
```
We can use this pattern to create a new `.md` file in the `posts` section:
-{{% code file="archetype-example.sh" %}}
-```bash
+{{< code file="archetype-example.sh" >}}
hugo new posts/my-first-post.md
-```
-{{% /code %}}
+{{< /code >}}
{{% note "Override Content Type in a New File" %}}
To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
Running this command in a new site that does not have default or custom archetypes will create the following file:
{{% output file="content/posts/my-first-post.md" %}}
-```toml
+```
+++
date = "2017-02-01T19:20:04-07:00"
title = "my first post"
The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
-{{% code file="archetypes/default.md" %}}
-```toml
+{{< code file="archetypes/default.md" >}}
+++
tags = ["golang", "hugo"]
categories = ["web development"]
+++
-```
-{{% /code %}}
+{{< /code >}}
{{% warning "EOL Characters in Text Editors"%}}
If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
-{{% code file="new-post-from-default.sh" %}}
-```bash
+{{< code file="new-post-from-default.sh" >}}
$ hugo new posts/my-new-post.md
-```
-{{% /code %}}
+{{< /code >}}
Hugo then creates a new markdown file with the following front matter:
{{% output file="content/posts/my-new-post.md" %}}
-```toml
+```
+++
categories = ["web development"]
date = "2017-02-01T19:20:04-07:00"
### Create a Custom Archetype
-{{% code file="archetypes/posts.md"%}}
-```toml
+{{< code file="archetypes/posts.md">}}
+++
description = ""
tags = ""
categories = ""
+++
-```
-{{% /code %}}
+{{< /code >}}
### Use a Custom Archetype
With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
-{{% code file="new-post-from-custom.sh" %}}
-```bash
+{{< code file="new-post-from-custom.sh" >}}
$ hugo new posts/post-from-custom.md
-```
-{{% /code %}}
+{{< /code >}}
This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
{{% output file="content/posts/post-from-custom-archetype.md" %}}
-```toml
+```
+++
categories = ""
date = 2017-02-13T17:24:43-08:00
As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
-{{% code file="archetypes/functions.md" %}}
-```yaml
+{{< code file="archetypes/functions.md" >}}
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}}
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML:
-{{% code file="data/_authors/alice.toml" %}}
-```toml
+{{< code file="data/_authors/alice.toml" >}}
givenName = "Alice" # or firstName as alias
familyName = "Allison" # or lastName as alias
displayName = "Alice Allison"
[params]
random = "whatever you want"
-```
-{{% /code %}}
+{{< /code >}}
All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively.
-```yaml
+```
---
title: Why Hugo is so Awesome
date: 2016-08-22T14:27:502:00
Nothing to read here. Move along...
```
-```toml
+```
+++
title = Why Hugo is so Awesome
date = "2016-08-22T14:27:502:00"
Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks:
-{{% code file="layouts/partials/author-info.html" download="author-info.html" %}}
-```html
+{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
{{ with .Author }}
<h3>{{ .DisplayName }}</h3>
<img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Who Published What?
In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively:
-```yaml
+```
taxonomies:
author: authors
```
-```toml
+```
[taxonomies]
author = "authors"
```
In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy.
-{{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}}
-```html
+{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
<ul>
{{ range $author, $v := .Data.Terms }}
{{ $profile := $.Authors.Get $author }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
-{{% code file="layouts/taxonomy/author.html" download="author.html" %}}
-```html
+{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
{{ range .Data.Pages }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
<span>written by {{ .Author.DisplayName }}</span>
{{ .Summary }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively:
-```toml
+```
disqusShortname = "yourdiscussshortname"
```
-```yaml
+```
disqusShortname: "yourdiscussshortname"
```
## Use `ref` and `relref`
-```md
+```
{{</* ref "document" */>}}
{{</* ref "#anchor" */>}}
{{</* ref "document#anchor" */>}}
The `documentname` is the name of a document, including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result:
-```md
+```
{{</* relref "blog/post.md" */>}} => `/blog/post/`
{{</* relref "post.md" */>}} => `/blog/post/`
```
If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory:
-```bash
+```
.
└── content
├── events
To be sure to get the correct reference in this case, use the full path:
-{{% code file="content/meta/my-article.md" copy="false" %}}
-```md
+{{< code file="content/meta/my-article.md" copy="false" >}}
{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
-```
-{{% /code %}}
+{{< /code >}}
{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}}
A relative document name must *not* begin with a slash (`/`).
-```md
+```
{{</* relref "/events/my-birthday.md" */>}} => ""
```
When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
-```md
+```
{{</* relref "#anchors" */>}} => #anchors:9decaf7
{{</* relref "about-hugo/hugo-features.md#content" */>}} => /blog/post/#who:badcafe
```
The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
-```md
+```
{{</* relref "#who" */>}} => #who:9decaf7
{{</* relref "blog/post.md#who" */>}} => /blog/post/#who:badcafe
```
### Examples
-* `{{</* ref "blog/post.md" */>}}` => `http://yoursite.com/blog/post/`
-* `{{</* ref "post.md#tldr" */>}}` => `http://yoursite.com/blog/post/#tldr:caffebad`
+* `{{</* ref "blog/post.md" */>}}` => `http://example.com/blog/post/`
+* `{{</* ref "post.md#tldr" */>}}` => `http://example.com/blog/post/#tldr:caffebad`
* `{{</* relref "post.md" */>}}` => `/blog/post/`
* `{{</* relref "blog/post.md#tldr" */>}}` => `/blog/post/#tldr:caffebad`
* `{{</* ref "#tldr" */>}}` => `#tldr:badcaffe`
`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
-```md
+```
{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
```
#### Example Task List Input
-{{% code file="content/my-to-do-list.md" %}}
-```markdown
+{{< code file="content/my-to-do-list.md" >}}
- [ ] a task list item
- [ ] list syntax required
- [ ] incomplete
- [x] completed
-```
-{{% /code %}}
+{{< /code >}}
#### Example Task List Output
The preceding markdown produces the following HTML in your rendered website:
-```html
+```
<ul class="task-list">
<li><input type="checkbox" disabled="" class="task-list-item"> a task list item</li>
<li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content's front matter:
-```yaml
+```
---
title: My Post
date: 2017-04-01
The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous 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 include a `<script>` tag for the officially recommended secure CDN ([cdn.js.com](https://cdnjs.com)):
-{{% code file="add-mathjax-to-page.html" %}}
-```html
+{{< code file="add-mathjax-to-page.html" >}}
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
-```
-{{% /code %}}
+{{< /code >}}
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.
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).
-{{% code file="mathjax-markdown-solution.html" %}}
-```js
+{{< code file="mathjax-markdown-solution.html" >}}
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
}
});
</script>
-```
-{{% /code %}}
+{{< /code >}}
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 file="mathjax-style.css" %}}
-```css
+{{< code file="mathjax-style.css" >}}
code.has-jax {
font: inherit;
font-size: 100%;
border: inherit;
color: #515151;
}
-```
-{{% /code %}}
+{{< /code >}}
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.
### TOML Example
-```toml
+```
+++
title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
### YAML Example
-```yaml
+```
---
title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
### JSON Example
-```json
+```
{
"title": "spf13-vim 3.0 release and new website",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
-```yaml
+```
include_toc: true
show_comments: false
```
#### A Single Menu
-```yaml
+```
---
menu: "main"
---
#### Multiple Menus
-```yaml
+```
---
menu: ["main", "footer"]
---
#### Advanced
-```yaml
+```
---
menu:
docs:
Here’s an example snippet pulled from a `config.toml`:
-{{% code file="config.toml" %}}
-```toml
+{{< code file="config.toml" >}}
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
pre = "<i class='fa fa-road'></i>"
weight = -100
url = "/getting-started/"
-```
-{{% /code %}}
+{{< /code >}}
Here's the equivalent snippet in a `config.yaml`:
-{{% code file="config.yml" %}}
-```yaml
+{{< code file="config.yml" >}}
---
menu:
docs:
Weight: -100
URL: "/getting-started/"
---
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
The following is an example of a TOML site configuration for a multilingual Hugo project:
-{{% code file="config.toml" download="config.toml" %}}
-```toml
+{{< code file="config.toml" download="config.toml" >}}
DefaultContentLanguage = "en"
copyright = "Everything is mine"
linkedin = "lien-francais"
[Languages.fr.navigation]
help = "Aide"
-```
-{{% /code %}}
+{{< /code >}}
Anything not defined in a `[Languages]` block will fall back to the global
value for that key (e.g., `copyright` for the English [`en`] language).
Taxonomies and [Blackfriday configuration][config] can also be set per language:
-{{% code file="bf-config.toml" %}}
-```toml
+{{< code file="bf-config.toml" >}}
[Taxonomies]
tag = "tags"
title = "Français"
[Languages.fr.Taxonomies]
plaque = "plaques"
-```
-{{% /code %}}
+{{< /code >}}
## Translate Your Content
If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
-```yaml
+```
slug: "a-propos"
```
To create a list of links to translated content, use a template similar to the following:
-{{% code file="layouts/partials/i18nlist.html" %}}
-```html
+{{< code file="layouts/partials/i18nlist.html" >}}
{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
{{ end}}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language.
```
To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
-```bash
+```
hugo --i18n-warnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
```
You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file:
-```toml
+```
defaultContentLanguage = "en"
[languages.en]
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory.
-```html
+```
<ul>
{{- $currentPage := . -}}
{{ range .Site.Menus.main -}}
.
└── content
└── about
- | └── _index.md // <- http://yoursite.com/about/
+ | └── _index.md // <- http://example.com/about/
├── post
- | ├── firstpost.md // <- http://yoursite.com/post/firstpost/
+ | ├── firstpost.md // <- http://example.com/post/firstpost/
| ├── happy
- | | └── ness.md // <- http://yoursite.com/post/happy/ness/
- | └── secondpost.md // <- http://yoursite.com/post/secondpost/
+ | | └── ness.md // <- http://example.com/post/happy/ness/
+ | └── secondpost.md // <- http://example.com/post/secondpost/
└── quote
- ├── first.md // <- http://yoursite.com/quote/first/
- └── second.md // <- http://yoursite.com/quote/second/
+ ├── first.md // <- http://example.com/quote/first/
+ └── second.md // <- http://example.com/quote/second/
```
## Path Breakdown in Hugo
-The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your [site's configuration file][config].
+The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://example.com"` in your [site's configuration file][config].
### Index Pages: `_index.md`
You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
-```bash
+```
. url
. ⊢--^-⊣
. path slug
At build, this will output to the following destination with the associated values:
-```bash
+```
url ("/posts/")
⊢-^-⊣
⊢--------^---------⊣⊢-^-⊣
permalink
⊢----------^-------------⊣
-http://yoursite.com/posts/index.html
+http://example.com/posts/index.html
```
### Single Pages in Sections
Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
-```bash
+```
path ("posts/my-first-hugo-post.md")
. ⊢-----------^------------⊣
. section slug
At the time Hugo builds your site, the content will be output to the following destination:
-```bash
+```
url ("/posts/my-first-hugo-post/")
⊢------------^----------⊣
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
permalink
⊢--------------------^---------------------⊣
-http://yoursite.com/posts/my-first-hugo-post/index.html
+http://example.com/posts/my-first-hugo-post/index.html
```
### Section with Nested Directories
To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site:
-```bash
+```
section
⊢--^--⊣
url
⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣
permalink
⊢----------------------^-----------------------⊣
-http://yoursite.com/events/chicago/lollapalooza/
+http://example.com/events/chicago/lollapalooza/
```
{{% note %}}
### `filename`
-This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `yoursite.com/posts/my-post/`).
+This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
### `slug`
When defined in the front matter, the `slug` can take the place of the filename for the destination.
-{{% code file="content/posts/old-post.md" %}}
-```yaml
+{{< code file="content/posts/old-post.md" >}}
---
title: New Post
slug: "new-post"
---
-```
-{{% /code %}}
+{{< /code >}}
This will render to the following destination according to Hugo's default behavior:
```
-yoursite.com/posts/new-post/
+example.com/posts/new-post/
```
### `section`
A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
-{{% code file="content/posts/my-post.md" %}}
-```yaml
+{{< code file="content/posts/my-post.md" >}}
---
title: My Post
type: new
layout: mylayout
---
-```
-{{% /code %}}
+{{< /code >}}
<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
<!-- ### `path`
A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration:
-{{% code file="content/posts/old-url.md" %}}
-```yaml
+{{< code file="content/posts/old-url.md" >}}
---
title: Old URL
url: /blog/new-url/
---
-```
-{{% /code %}}
+{{< /code >}}
-Assuming your `baseURL` is [configured][config] to `https://yoursite.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
+Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
```
-https://yoursite.com/blog/new-url/
+https://example.com/blog/new-url/
```
You can see more information on how to control output paths in [URL Management][urls].
The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts":
-```bash
+```
.
└── content
├── authors
- | ├── _index.md // <- yoursite.com/authors/
- | ├── john-doe.md // <- yoursite.com/authors/john-doe/
- | └── jane-doe.md // <- yoursite.com/authors/jane-doe/
+ | ├── _index.md // <- example.com/authors/
+ | ├── john-doe.md // <- example.com/authors/john-doe/
+ | └── jane-doe.md // <- example.com/authors/jane-doe/
└── events
- | ├── _index.md // <- yoursite.com/events/
- | ├── event-1.md // <- yoursite.com/events/event-1/
- | ├── event-2.md // <- yoursite.com/events/event-2/
- | └── event-3.md // <- yoursite.com/events/event-3/
+ | ├── _index.md // <- example.com/events/
+ | ├── event-1.md // <- example.com/events/event-1/
+ | ├── event-2.md // <- example.com/events/event-2/
+ | └── event-3.md // <- example.com/events/event-3/
└── posts
- | ├── _index.md // <- yoursite.com/posts/
- | ├── event-1.md // <- yoursite.com/posts/event-1/
- | ├── event-2.md // <- yoursite.com/posts/event-2/
- | ├── event-3.md // <- yoursite.com/posts/event-3/
- | ├── event-4.md // <- yoursite.com/posts/event-4/
- | └── event-5.md // <- yoursite.com/posts/event-5/
+ | ├── _index.md // <- example.com/posts/
+ | ├── event-1.md // <- example.com/posts/event-1/
+ | ├── event-2.md // <- example.com/posts/event-2/
+ | ├── event-3.md // <- example.com/posts/event-3/
+ | ├── event-4.md // <- example.com/posts/event-4/
+ | └── event-5.md // <- example.com/posts/event-5/
```
## Content Section Lists
Here are two examples of paired shortcodes:
-```md
+```
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
```
-```md
+```
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
```
The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `<strong>World</strong>`:
-```md
+```
{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
```
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
-```md
+```
{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
```
#### Example `figure` Input
-{{% code file="figure-input-example.md" %}}
-```markdown
+{{< code file="figure-input-example.md" >}}
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `figure` Output
{{% output file="figure-output-example.html" %}}
-```html
+```
<figure>
<img src="/media/spf13.jpg" />
<figcaption>
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
-```html
+```
https://gist.github.com/spf13/7896402
```
We can embed the gist in our content via username and gist ID pulled from the URL:
-```md
+```
{{</* gist spf13 7896402 */>}}
```
If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
-{{% code file="gist-input.md" %}}
-```md
+{{< code file="gist-input.md" >}}
{{</* gist spf13 7896402 "img.html" */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `gist` Output
{{% output file="gist-output.html" %}}
-```html
+```
{{< gist spf13 7896402 >}}
```
{{% /output %}}
#### Example `highlight` Input
-{{% code file="content/tutorials/learn-html.md" %}}
-```html
+{{< code file="content/tutorials/learn-html.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
</div>
</section>
{{</* /highlight */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `highlight` Output
The `highlight` shortcode example above would produce the following HTML when the site is rendered:
{{% output file="tutorials/learn-html/index.html" %}}
-```html
+```
<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
<span style="color: #f92672"><div></span>
<span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
-```html
+```
https://www.instagram.com/p/BWNjjyYFxVx/
```
#### Example `instagram` Input
-{{% code file="instagram-input.md" %}}
-```md
+{{< code file="instagram-input.md" >}}
{{</* instagram BWNjjyYFxVx */>}}
-```
-{{% /code %}}
+{{< /code >}}
You also have the option to hide the caption:
-{{% code file="instagram-input-hide-caption.md" %}}
-```md
+{{< code file="instagram-input-hide-caption.md" >}}
{{</* instagram BWNjjyYFxVx hidecaption */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `instagram` Output
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
{{% output file="instagram-hide-caption-output.html" %}}
-```html
+```
{{< instagram BWNjjyYFxVx hidecaption >}}
```
{{% /output %}}
#### Example `ref` and `relref` Input
-```md
+```
[Neat]({{</* ref "blog/neat.md" */>}})
[Who]({{</* relref "about.md#who" */>}})
```
Assuming that standard Hugo pretty URLs are turned on.
-```html
+```
<a href="/blog/neat">Neat</a>
<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
```
To embed slides from [Speaker Deck][], click on "< /> Embed" (under Share right next to the template on Speaker Deck) and copy the URL:
-```html
+```
<script async class="speakerdeck-embed" data-id="4e8126e72d853c0060001f97" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
```
Extract the value from the field `data-id` and pass it to the shortcode:
-{{% code file="speakerdeck-example-input.md" %}}
-```md
+{{< code file="speakerdeck-example-input.md" >}}
{{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### `speakerdeck` Example Output
{{% output file="speakerdeck-example-input.md" %}}
-```html
+```
{{< speakerdeck 4e8126e72d853c0060001f97 >}}
```
{{% /output %}}
Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
-{{% code file="example-tweet-input.md" %}}
-```md
+{{< code file="example-tweet-input.md" >}}
{{</* tweet 877500564405444608 */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `tweet` Output
Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
{{% output file="example-tweet-output.html" %}}
-```html
+```
{{< tweet 877500564405444608 >}}
```
{{% /output %}}
Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
-{{% code file="example-vimeo-input.md" %}}
-```md
+{{< code file="example-vimeo-input.md" >}}
{{</* vimeo 146022717 */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `vimeo` Output
Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
{{% output file="example-vimeo-output.html" %}}
-```html
+```
{{< vimeo 146022717 >}}
```
{{% /output %}}
{{% tip %}}
If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well.
-```md
+```
{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" */>}}
```
{{% /tip %}}
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
-{{% code file="example-youtube-input.md" %}}
-```md
+{{< code file="example-youtube-input.md" >}}
{{</* youtube w7Ft2ymGmfc */>}}
-```
-{{% /code %}}
+{{< /code >}}
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named an unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
-{{% code file="example-youtube-input-with-autoplay.md" %}}
-```md
+{{< code file="example-youtube-input-with-autoplay.md" >}}
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `youtube` Output
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
-{{% code file="example-youtube-output.html" %}}
-```html
+{{< code file="example-youtube-output.html" >}}
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `youtube` Display
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][].
-{{% code file="page-list-with-summaries.html" %}}
-```html
+{{< code file="page-list-with-summaries.html" >}}
{{ range first 10 .Data.Pages }}
<article>
<!-- this <div> includes the title summary -->
{{ end }}
</article>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
```
Actor <- Taxonomy
Bruce Willis <- Term
- The Six Sense <- Content
+ The Sixth Sense <- Content
Unbreakable <- Content
Moonrise Kingdom <- Content
Samuel L. Jackson <- Term
Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following:
-```toml
+```
disableKinds = ["taxonomy","taxonomyTerm"]
```
When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your your configuration and used in your content front matter will create the following pages:
-* A single page at `yoursite.com/categories/` that lists all the [terms within the taxonomy][]
+* A single page at `example.com/categories/` that lists all the [terms within the taxonomy][]
* [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][]
## Configure Taxonomies
### Example: TOML Taxonomy Configuration
-```toml
+```
[taxonomies]
tag = "tags"
category = "categories"
### Example: YAML Taxonomy Configuration
-```yaml
+```
taxonomies:
tag: "tags"
category: "categories"
### Example: TOML Front Matter with Taxonomies
-```toml
+```
+++
title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ]
### Example: YAML Front Matter with Taxonomies
-```yaml
+```
---
title: "Hugo: A fast and flexible static site generator"
#tags: ["Development", "Go", "fast", "Blogging"]
### Example: JSON Front Matter with Taxonomies
-```json
+```
{
"title": "Hugo: A fast and flexible static site generator",
"tags": [
### Example: TOML Taxonomic `weight`
-```toml
+```
+++
title = "foo"
tags = [ "a", "b", "c" ]
### Example: YAML Taxonomic `weight`
-```yaml
+```
---
title: foo
#tags: [ "a", "b", "c" ]
Create your markdown the way you normally would with the appropriate headings. Here is some example content:
-```md
+```
<!-- Your front matter up here -->
## Introduction
The following is an example of a very basic [single page template][]:
-{{% code file="layout/_default/single.html" download="single.html" %}}
-```html
+{{< code file="layout/_default/single.html" download="single.html" >}}
{{ define "main" }}
<main>
<article>
</aside>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Template Example: TOC Partial
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
-{{% code file="layouts/partials/toc.html" download="toc.html" %}}
-```html
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }}
<aside>
<header>
{{.TableOfContents}}
</aside>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
The following examples take you stepwise through creating a new type layout for a content file that contains the following front matter:
-{{% code file="content/events/my-first-event.md" copy="false" %}}
-```toml
+{{< code file="content/events/my-first-event.md" copy="false" >}}
+++
title = My First Event
date = "2016-06-24T19:20:04-07:00"
type = "event"
layout = "birthday"
+++
-```
-{{% /code %}}
+{{< /code >}}
By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/ my-first-event.md` is of type `event` and should render using the `birthday` layout.
### YAML Permalinks Configuration Example
-{{% code file="config.yml" copy="false" %}}
-```yaml
+{{< code file="config.yml" copy="false" >}}
permalinks:
post: /:year/:month/:title/
-```
-{{% /code %}}
+{{< /code >}}
### TOML Permalinks Configuration Example
-{{% code file="config.toml" copy="false" %}}
-```toml
+{{< code file="config.toml" copy="false" >}}
[permalinks]
post = "/:year/:month/:title/"
-```
-{{% /code %}}
+{{< /code >}}
-Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`.
+Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `http://example.com/2013/11/sample-entry/`.
### Permalink Configuration Values
#### TOML Front Matter
-{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
-```toml
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
+++
aliases = [
"/posts/my-original-url/",
"/2010/01/01/even-earlier-url.html"
]
+++
-```
-{{% /code %}}
+{{< /code >}}
#### YAML Front Matter
-{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
-```yaml
+{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
---
aliases:
- /posts/my-original-url/
- /2010/01/01/even-earlier-url.html
---
-```
-{{% /code %}}
+{{< /code >}}
-Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `yoursite.com/posts/my-original-url/` will be immediately redirected to `yoursite.com/posts/my-awesome-blog-post/`.
+Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-blog-post/`.
### Example: Aliases in Multilingual
In `/posts/my-new-post.es.md`:
-```yaml
+```
---
aliases:
- /es/posts/my-original-post/
For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
-```yaml
+```
---
title: My New post
aliases: [/posts/my-old-url/]
---
```
-Assuming a `baseURL` of `yoursite.com`, the contents of the auto-generated alias `.html` found at `https://yoursite.com/posts/my-old-url/ will contain the following:`
+Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/ will contain the following:`
-```html
+```
<!DOCTYPE html>
<html>
<head>
- <title>http://yoursite.com/posts/my-intended-url</title>
- <link rel="canonical" href="http://yoursite.com/posts/my-intended-url"/>
+ <title>http://example.com/posts/my-intended-url</title>
+ <link rel="canonical" href="http://example.com/posts/my-intended-url"/>
<meta name=\"robots\" content=\"noindex\">
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
- <meta http-equiv="refresh" content="0; url=http://yoursite.com/posts/my-intended-url"/>
+ <meta http-equiv="refresh" content="0; url=http://example.com/posts/my-intended-url"/>
</head>
</html>
```
-The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://yoursite.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name=\"robots\" content=\"noindex\">` lets search engine bots know they they should not crawl and index your new alias page.
+The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `<meta name=\"robots\" content=\"noindex\">` lets search engine bots know they they should not crawl and index your new alias page.
### Customize
You may customize this alias page by creating an `alias.html` template in the
The following demonstrates the concept:
-```bash
+```
content/posts/_index.md
-=> yoursite.com/posts/index.html
+=> example.com/posts/index.html
content/posts/post-1.md
-=> yoursite.com/posts/post-1/
+=> example.com/posts/post-1/
```
## Ugly URLs
-If you would like to have are often referred to as "ugly URLs" (e.g., yoursite.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`..
+If you would like to have are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`..
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. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior.
See [Content Organization][contentorg] for more details on paths.
-```bash
+```
.
└── content
└── about
- | └── _index.md // <- http://yoursite.com/about/
+ | └── _index.md // <- http://example.com/about/
├── post
- | ├── firstpost.md // <- http://yoursite.com/post/firstpost/
+ | ├── firstpost.md // <- http://example.com/post/firstpost/
| ├── happy
- | | └── ness.md // <- http://yoursite.com/post/happy/ness/
- | └── secondpost.md // <- http://yoursite.com/post/secondpost/
+ | | └── ness.md // <- http://example.com/post/happy/ness/
+ | └── secondpost.md // <- http://example.com/post/secondpost/
└── quote
- ├── first.md // <- http://yoursite.com/quote/first/
- └── second.md // <- http://yoursite.com/quote/second/
+ ├── first.md // <- http://example.com/quote/first/
+ └── second.md // <- http://example.com/quote/second/
```
Here's the same organization run with `hugo --uglyURLs`:
-```bash
+```
.
└── content
└── about
- | └── _index.md // <- http://yoursite.com/about/index.html
+ | └── _index.md // <- http://example.com/about/index.html
├── post
- | ├── firstpost.md // <- http://yoursite.com/post/firstpost.html
+ | ├── firstpost.md // <- http://example.com/post/firstpost.html
| ├── happy
- | | └── ness.md // <- http://yoursite.com/post/happy/ness.html
- | └── secondpost.md // <- http://yoursite.com/post/secondpost.html
+ | | └── ness.md // <- http://example.com/post/happy/ness.html
+ | └── secondpost.md // <- http://example.com/post/secondpost.html
└── quote
- ├── first.md // <- http://yoursite.com/quote/first.html
- └── second.md // <- http://yoursite.com/quote/second.html
+ ├── first.md // <- http://example.com/quote/first.html
+ └── second.md // <- http://example.com/quote/second.html
```
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`.
-By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://yoursite.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.com/css/foo.css`.
+By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://example.com/css/foo.css`.
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue.
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
-```bash
+```
hugo config | grep -i canon
```
---
-title: Contributing to the Hugo Project
-linktitle: Contributing to Hugo
+title: Contribute to the Hugo Project
+linktitle: Contribute to Hugo
description: Contribute to Hugo development and documentation.
date: 2017-02-01
publishdate: 2017-02-01
Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
-```bash
+```
go version
```
You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
-```bash
+```
go version go1.8 darwin/amd64
```
You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; .e.g.:
-```bash
+```
/Users/<yourusername>/Code/go
```
If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:
-{{% code file="install-go.sh" %}}
-```bash
+{{< code file="install-go.sh" >}}
brew install go
-```
-{{% /code %}}
+{{< /code >}}
### Install Go via GVM
### Install Hub on Your System (Optional)
-Hub is a great tool for working with GitHub. The main site for it is [www.hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
+Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
-```sh
+```
brew install hub
```
Now we'll create an [alias in Bash](http://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
-```sh
+```
echo "alias git='hub'" >> ~/.bash_profile
```
Confirm the installation:
-```sh
+```
git version 2.6.3
hub version 2.2.2
```
So, let's clone that master repository:
-```sh
+```
go get -v -u github.com/gohugoio/hugo
```
Switch back to the terminal and move into the directory of the cloned master repository from the last step.
-```sh
+```
cd $GOPATH/src/github.com/gohugoio/hugo
```
Now Git needs to know that our fork exists by adding the copied remote url:
-```sh
+```
git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
```
Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
-```sh
+```
git fork
```
Let's check if everything went right by listing all known remotes:
-```sh
+```
git remote -v
```
The output should look similar:
-```sh
+```
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
origin https://github.com/gohugoio/hugo (fetch)
First, you should always pull the latest changes from the master repository:
-```sh
+```
git checkout master
git pull
```
Now we can create a new branch for your additions:
-```sh
+```
git checkout -b <BRANCH-NAME>
```
While making changes in the codebase it's a good idea to build the binary to test them:
-```sh
+```
go build -o hugo main.go
```
### Formatting
The Go code styleguide maybe is opiniated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our addtions:
-```sh
+```
go fmt ./...
```
Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
-```sh
+```
# Add all changed files
git add --all
git commit --message "YOUR COMMIT MESSAGE"
Let's say you want to modify the last commit message. Run the following command and replace the current message:
-```sh
+```
git commit --amend -m"YOUR NEW COMMIT MESSAGE"
```
Take a look at the commit log to see the change:
-```sh
+```
git log
# Exit with q
```
After making the last commit you may forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
-```sh
+```
git add --all
git commit --amend
```
This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
-```sh
+```
git rebase --interactive @~6
```
The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
-```sh
+```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
-```sh
+```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
You should end up with a similar setup:
-```sh
+```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix
A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
-```sh
+```
Successfully rebased and updated refs/heads/<BRANCHNAME>.
```
To push our commits to the fork on GitHub we need to speficy a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
-```sh
+```
git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
```
You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
-```git
+```
git checkout -b jon-doe-showcase-addition
```
The archetype for `functions` according to the Hugo theme is as follows:
-{{% code file="archetypes/functions.md" %}}
-```yaml
+{{< code file="archetypes/functions.md" >}}
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md">}}
-```
-{{% /code %}}
+{{< /code >}}
#### New Function Required Fields
The archetype for the `tutorials` content type is as follows:
-{{% code file="archetypes/tutorials.md" %}}
-```yaml
+{{< code file="archetypes/tutorials.md" >}}
{{< readfile file="/themes/gohugoioTheme/archetypes/tutorials.md">}}
-```
-{{% /code %}}
+{{< /code >}}
## Add Code Blocks
Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`.
-````html
-```html
+```
+```
<h1>Hello world!</h1>
```
-````
+```
### Code Block Shortcode
`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
-````markdown
+```
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
-```language
+```
A whole bunch of coding going on up in here!
```
{{%/* /code */%}}
-````
+```
The following are the arguments passed into `code`:
1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
-````md
+```
{{%/* code file="layouts/_default/single.html" download="single.html" */%}}
-```html
+```
{{ define "main" }}
<main>
<article>
{{ end }}
```
{{%/* /code */%}}
-````
+```
##### Example 'code' Display
The output of this example will render to the Hugo docs as follows:
-{{% code file="layouts/_default/single.html" download="single.html" %}}
-```html
+{{< code file="layouts/_default/single.html" download="single.html" >}}
{{ define "main" }}
<main>
<article>
</article>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
<!-- #### Output Code Block
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
-````html
+```
{{%/* output file="post/my-first-post/index.html" */%}}
-```html
+```
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
```
{{%/* /output */%}}
-````
+```
The preceding `output` example will render as follows to the Hugo docs:
{{% output file="post/my-first-post/index.html" %}}
-```html
+```
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
```
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
-```markdown
+```
> Without the threat of punishment, there is no joy in flight.
```
However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
-```markdown
+```
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
```
#### Example `note` Input
-{{% code file="note-with-heading.md" %}}
-```markdown
+{{< code file="note-with-heading.md" >}}
{{%/* note */%}}
Here is a piece of information I would like to draw your **attention** to.
{{%/* /note */%}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `note` Output
{{% output file="note-with-heading.html" %}}
-```html
+```
{{% note %}}
Here is a piece of information I would like to draw your **attention** to.
{{% /note %}}
#### Example `tip` Input
-{{% code file="using-tip.md" %}}
-```markdown
+{{< code file="using-tip.md" >}}
{{%/* tip */%}}
Here's a bit of advice to improve your productivity with Hugo.
{{%/* /tip */%}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `tip` Output
{{% output file="tip-output.html" %}}
-```html
+```
{{% tip %}}
Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}}
#### Example `warning` Input
-{{% code file="warning-admonition-input.md" %}}
-```markdown
+{{< code file="warning-admonition-input.md" >}}
{{%/* warning */%}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{%/* /warning */%}}
-```
-{{% /code %}}
+{{< /code >}}
#### Example `warning` Output
{{% output file="warning-admonition-output.html" %}}
-```html
+```
{{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}
`theme.toml` contains metadata about the theme and its creator and should be created automatically when running the `hugo new theme`. The auto-generated file is provided here as well for easy downloading:
-{{% code file="theme.toml" download="theme.toml" %}}
-```toml
+{{< code file="theme.toml" download="theme.toml" >}}
name = ""
license = "MIT"
licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
description = ""
-homepage = "http://yoursite.com/"
+homepage = "http://example.com/"
tags = []
features = []
min_version = 0.19
name = ""
homepage = ""
repo = ""
-```
-{{% /code %}}
+{{< /code >}}
The following fields are required:
-```toml
+```
name = "Hyde"
license = "MIT"
licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
You can download the following `README.md` as an outline:
-{{% code file="README.md" download="README.md" %}}
-```markdown
+{{< code file="README.md" download="README.md" >}}
# Theme Title
-```
-{{% /code %}}
+{{< /code >}}
{{% note "Screenshots in your `README.md`"%}}
If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
3. Sort the terms associated with the taxonomy by popularity.
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
-{{% code file="grab-top-two-tags.html" %}}
-```html
+{{< code file="grab-top-two-tags.html" >}}
<ul class="most-popular-tags">
{{ $t := $.Site.GetPage "taxonomyTerm" "tags" }}
{{ range first 2 $t.Data.Terms.ByCount }}
<li>{{.}}</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
[partials]: /templates/partials/
Both `absLangURL` and [`relLangURL`](/functions/rellangurl/) are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl) relatives but will add the correct language prefix when the site is configured with more than one language.
-So for a site `baseURL` set to `http://yoursite.com/hugo/` and the current language is `en`:
+So for a site `baseURL` set to `http://example.com/hugo/` and the current language is `en`:
-```golang
-{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
+```
+{{ "blog/" | absLangURL }} → "http://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
```
aliases: []
---
-Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://yoursite.com/hugo/`:
+Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://example.com/hugo/`:
-```golang
-{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
+```
+{{ "mystyle.css" | absURL }} → "http://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data (SEO)][jsonld], where some of your images for a piece of content may or may not be hosted locally:
-{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
-```html
+{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "http://schema.org",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
-```
-{{% /code %}}
+{{< /code >}}
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
Let's assume you have a file at `data/tweets.toml` that contains a list of Tweets to display on your site's homepage. The file is filled with `[[tweet]]` blocks; e.g.---
-```toml
+```
[[tweet]]
name = "Steve Francia"
twitter_handle = "@spf13"
Let's assume you want to grab Tweets from the last two years and present them in a random order. In conjunction with the [`where`](/functions/where/) and [`now`](/functions/now/) functions, you can limit our range to the last two years via `now.AddDate -2 0 0`, which represents a point in time 2 years, 0 days, and 0 hours before the time of your last site build.
-{{% code file="partials/templates/random-tweets.html" download="tweets.html" %}}
-```html
+{{< code file="partials/templates/random-tweets.html" download="tweets.html" >}}
{{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }}
<div class="item">
<blockquote>
</blockquote>
</div>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
The following shows `after` being used in conjunction with the [`slice` function][slice]:
-```html
+```
{{ $data := slice "one" "two" "three" "four" }}
{{ range after 2 $data }}
{{ . }}
## Example of `after` with `first`: 2nd–4th Most Recent Articles
-You can use `after` in combination with the [`first` function][] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `yoursite.com/articles`. You have 10 articles, but you want your templating for the [list/section page][] to show only two rows:
+You can use `after` in combination with the [`first` function][] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page][] to show only two rows:
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
-{{% code file="layouts/section/articles.html" download="articles.html" %}}
-```html
+{{< code file="layouts/section/articles.html" download="articles.html" >}}
{{ define "main" }}
<section class="row featured-article">
<h2>Featured Article</h2>
{{ end }}
</div>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
[`first` function]: /functions/first/
[list/section page]: /templates/section-templates/
Here is an example of a content file with `name:` as a front matter field:
-```toml
+```
+++
names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
+++
You can then use `apply` as follows:
-```golang
+```
{{ apply .Params.names "urlize" "." }}
```
This is *roughly* equivalent to using the following with [range][]
-```golang
+```
{{ range .Params.names }}{{ . | urlize }}{{ end }}
```
If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
-{{% code file="layouts/partial/post-tag-list.html" copy="false" %}}
-```html
+{{< code file="layouts/partial/post-tag-list.html" copy="false" >}}
{{ with .Params.tags }}
<div class="tags-list">
Tags:
{{ end }}
</div>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
-{{% code file="layouts/partial/post-tag-link.html" copy="false" %}}
-```html
+{{< code file="layouts/partial/post-tag-link.html" copy="false" >}}
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
-```
-{{% /code %}}
+{{< /code >}}
This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.
This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading. The combined and DRYer version is shown next:
-```html
+```
{{ with .Params.tags }}
<div class="tags-list">
Tags:
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp][] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
-{{% code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" %}}
-```html
+{{< code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" >}}
{{ with .Params.tags }}
<div class="tags-list">
Tags:
{{ delimit (apply (apply (sort .) "partial" "post-tag-link" ".") "chomp" ".") ", " }}
</div>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
`apply` does not work when receiving the sequence as an argument through a pipeline.
An example:
-{{% code file="base64-input.html" %}}
-```html
+{{< code file="base64-input.html" >}}
<p>Hello world = {{ "Hello world" | base64Encode }}</p>
<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
-```
-{{% /code %}}
+{{< /code >}}
{{% output file="base-64-output.html" %}}
-```html
+```
<p>Hello world = SGVsbG8gd29ybGQ=</p>
<p>SGVsbG8gd29ybGQ = Hello world</p>
```
Using base64 to decode and encode becomes really powerful if we have to handle
responses from APIs.
-```golang
+```
{{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }}
{{ $resp.content | base64Decode | markdownify }}
```
Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/markdownify/)).
-```golang
+```
{{chomp "<p>Blockhead</p>\n"}} → "<p>Blockhead</p>"
```
In contrast with `countwords` function, which counts every word in a string, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
-```html
+```
{{ "Hello, 世界" | countrunes }}
<!-- outputs a content length of 8 runes. -->
```
The template function works similar to the [.WordCount page variable][pagevars].
-```html
+```
{{ "Hugo is a static site generator." | countwords }}
<!-- outputs a content length of 6 words. -->
```
`default` function examples reference the following content page:
-{{% code file="content/posts/default-function-example.md" %}}
-```yaml
+{{< code file="content/posts/default-function-example.md" >}}
---
title: Sane Defaults
seo_title:
oldparam: The default function helps make your templating DRYer.
newparam:
---
-```
-{{% /code %}}
+{{< /code >}}
`default` can be written in more than one way:
-```golang
+```
{{ index .Params "font" | default "Roboto" }}
{{ default "Roboto" (index .Params "font") }}
```
A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation:
-{{% code file="variable-as-default-value.html" nocopy="true" %}}
-```golang
+{{< code file="variable-as-default-value.html" nocopy="true" >}}
{{$old := .Params.oldparam }}
<p>{{ .Params.newparam | default $old }}</p>
-```
-{{% /code %}}
+{{< /code >}}
Which would return:
And then using dot notation
-{{% code file="dot-notation-default-value.html" %}}
-```golang
+{{< code file="dot-notation-default-value.html" >}}
<title>{{ .Params.seo_title | default .Title }}</title>
-```
-{{% /code %}}
+{{< /code >}}
Which would return
{{% output file="dot-notation-default-return-value.html" %}}
-```html
+```
<title>Sane Defaults</title>
```
{{% /output %}}
Using `if`:
-{{% code file="if-instead-of-default.html" nocopy="true" %}}
-```golang
+{{< code file="if-instead-of-default.html" nocopy="true" >}}
<title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title>
=> Sane Defaults
-```
-{{% /code %}}
+{{< /code >}}
Using `with`:
-{{% code file="with-instead-of-default.html" nocopy="true" %}}
-```golang
+{{< code file="with-instead-of-default.html" nocopy="true" >}}
<title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title>
=> Sane Defaults
-```
-{{% /code %}}
+{{< /code >}}
The examples of `delimit` that follow all use the same front matter:
-{{% code file="delimit-example-front-matter.toml" nocopy="true" %}}
-```toml
+{{< code file="delimit-example-front-matter.toml" nocopy="true" >}}
+++
title: I love Delimit
#tags: [ "tag1", "tag2", "tag3" ]
+++
-```
-{{% /code %}}
+{{< /code >}}
-{{% code file="delimit-page-tags-input.html" %}}
-```html
+{{< code file="delimit-page-tags-input.html" >}}
<p>Tags: {{ delimit .Params.tags ", " }}</p>
-```
-{{% /code %}}
+{{< /code >}}
{{% output file="delimit-page-tags-output.html" %}}
-```html
+```
<p>Tags: tag1, tag2, tag3</p>
```
{{% /output %}}
Here is the same example but with the optional "last" delimiter:
-{{% code file="delimit-page-tags-final-and-input.html" %}}
-```golang
+{{< code file="delimit-page-tags-final-and-input.html" >}}
Tags: {{ delimit .Params.tags ", " ", and " }}
-```
-{{% /code %}}
+{{< /code >}}
{{% output file="delimit-page-tags-final-and-output.html" %}}
-```html
+```
<p>Tags: tag1, tag2, and tag3</p>
```
{{% /output %}}
The partial below creates a SVG and expects `fill` `height` and `width` from the caller:
-{{% code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" %}}
-```xml
+{{< code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" >}}
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="{{ .fill }}" width="{{ .size }}" height="{{ .size }}" viewBox="0 0 32 32" aria-label="External Link">
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
</svg>
-```
-{{% /code %}}
+{{< /code >}}
These values can be stored in one object with `dict` and passed to the partial:
-{{% code file="layouts/_default/list.html" %}}
-```html
+{{< code file="layouts/_default/list.html" >}}
{{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" 10 "width" 20 ) }}
-```
-{{% /code %}}
+{{< /code >}}
You can limit the number of matches in the list with a third parameter. The following example shows how to limit the returned value to just one match (or none, if there are no matched substrings):
-```golang
+```
{{ findRE "<h2.*?>(.|\n)*?</h2>" .Content 1 }}
<!-- returns ["<h2 id="#foo">Foo</h2>"] -->
```
---
-```golang
+```
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
Assuming a key-value of `date: 2017-03-03` in a content file's front matter, your can run the date through `.Format` followed by a layout string for your desired output at build time:
-```golang
+```
{{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017
```
This translates a piece of content based on your `i18n/en-US.yaml` (and similar) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository.
-```golang
+```
{{ i18n "translation_id" }}
```
deprecated: false
---
-```golang
+```
{{ with (imageConfig "favicon.ico") }}
favicon.ico: {{.Width}} x {{.Height}}
{{ end }}
Here is an example of the data inside `data/locations/oslo.toml`:
-```toml
+```
website = "https://www.oslo.kommune.no"
pop_city = 658390
pop_metro = 1717900
The example we will use will be an article on Oslo, which front matter should set to exactly the same name as the corresponding file name in `data/locations/`:
-```toml
+```
title = "My Norwegian Vacation"
location = "oslo"
```
The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
-```golang
+```
{{ index .Site.Data.authors .Params.author }}
=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
```
Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
-```golang
+```
{{ (index .Site.Data.locations .Params.location).pop_city }}
=> 658390
```
The following is an example of a "related posts" [partial template][partials] that could be added to a [single page template][single]:
-{{% code file="layouts/partials/related-posts.html" download="related-posts.html" %}}
-```html
+{{< code file="layouts/partials/related-posts.html" download="related-posts.html" >}}
<ul>
{{ $page_link := .Permalink }}
{{ $tags := .Params.tags }}
{{ end }}
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
This is also very useful to use as `AND` filters when combined with where:
-```html
+```
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
You may want to append a class to a heading according to the length of the string therein. The following templating checks to see if the title's length is greater than 80 characters and, if so, adds a `long-title` class to the `<h1>`:
-{{% code file="check-title-length.html" %}}
-```html
+{{< code file="check-title-length.html" >}}
<header>
<h1{{if gt (len .Title) 80}} class="long-title"{{end}}>{{.Title}}</h1>
</header>
-```
-{{% /code %}}
+{{< /code >}}
## `len` Example 2: Counting Pages with `where`
The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]:
-{{% code file="how-many-posts.html" %}}
-```html
+{{< code file="how-many-posts.html" >}}
{{ $posts := (where .Site.RegularPages "Section" "==" "post") }}
{{ $postCount := len $posts }}
-```
-{{% /code %}}
+{{< /code >}}
Note the use of `.RegularPages`, a [site variable][] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates][].
For example, social media sharing with [Twitter Cards][cards] requires the following `meta` link in your site's `<head>` to display Twitter's ["Summary Card with Large Image"][twtsummary]:
-```html
-<meta name="twitter:image" content="http://yoursite.com/images/my-twitter-image.jpg">
+```
+<meta name="twitter:image" content="http://example.com/images/my-twitter-image.jpg">
```
Let's assume you have an `image` field in the front matter of each of your content files:
-```yaml
+```
---
title: My Post
image: my-post-image.jpg
You can then concatenate the `image` value (string) with the path to your `images` directory in `static` and leverage a URL-related templating function for increased flexibility:
-{{% code file="partials/head/twitter-card.html" %}}
-```html
+{{< code file="partials/head/twitter-card.html" >}}
{{$socialimage := add "images/" .Params.image}}
<meta name="twitter:image" content="{{ $socialimage | absURL }}">
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` and its relative companion `relURL` is the recommended way to construct URLs in Hugo.
-```html
+```
{{ md5 "Hello world, gophers!" }}
<!-- returns the string "b3029f756f98f79e7f1b7f1d1f0dd53b" -->
```
This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar:
-```html
+```
<img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">
```
For example, building your site on June 24, 2017 with the following templating:
-```html
+```
<div>
<small>© {{ now.Format "2006"}}</small>
</div>
Which will produce the following:
-```html
+```
<div>
<small>© 2017</small>
</div>
The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. Here is the simplest usage:
-```golang
+```
{{ partialCached "footer.html" . }}
```
You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section:
-{{% code file="partial-cached-example.html" %}}
-```
+{{< code file="partial-cached-example.html" >}}
{{ partialCached "footer.html" . .Section }}
-```
-{{% /code %}}
+{{< /code >}}
If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
See [the go doc](https://golang.org/pkg/fmt/) for additional information.
-```golang
+```
{{ i18n ( printf "combined_%s" $var ) }}
```
The following example creates a link to a search results page on Google.
-```html
+```
<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
```
This example renders the following HTML:
-```html
+```
<a href="https://www.google.com?page=3&q=test">Search</a>
```
So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`:
-```html
+```
{{readFile "README.txt"}} → "Hugo Rocks!"
```
`ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
-```golang
+```
{{ relref . "about.md" }}
```
`absLangURL` and `relLangURL` functions are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl/) relatives but will add the correct language prefix when the site is configured with more than one language. (See [Configuring Multilingual][multiliconfig].)
-So for a site `baseURL` set to `http://yoursite.com/hugo/` and the current language is `en`:
+So for a site `baseURL` set to `http://example.com/hugo/` and the current language is `en`:
-```golang
-{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
+```
+{{ "blog/" | absLangURL }} → "http://example.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
```
`ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
-```golang
+```
{{ relref . "about.md" }}
```
aliases: []
---
-Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://yoursite.com/hugo/`:
+Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://example.com/hugo/`:
-```golang
-{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
+```
+{{ "mystyle.css" | absURL }} → "http://example.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data for SEO][jsonld] where some of your images for a piece of content may or may not be hosted locally:
-{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
-```html
+{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
<script type="application/ld+json">
{
"@context" : "http://schema.org",
"image" : {{ apply .Params.images "absURL" "." }}
}
</script>
-```
-{{% /code %}}
+{{< /code >}}
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
-```golang
+```
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
aliases: []
---
-```golang
+```
{{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io"
{{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io"
```
Given a site-wide [`config.toml`][config] with the following `copyright` value:
-```toml
+```
copyright = "© 2015 Jane Doe. <a href=\"http://creativecommons.org/licenses/by/4.0/\">Some rights reserved</a>."
```
`{{ .Site.Copyright | safeHTML }}` in a template would then output:
-```html
+```
© 2015 Jane Doe. <a href="http://creativecommons.org/licenses/by/4.0/">Some rights reserved</a>.
```
However, without the `safeHTML` function, html/template assumes `.Site.Copyright` to be unsafe and therefore escapes all HTML tags and renders the whole string as plain text:
-```html
+```
<p>© 2015 Jane Doe. <a href="http://creativecommons.org/licenses by/4.0/">Some rights reserved</a>.</p>
```
Example: Given a site-wide `config.toml` that contains this menu entry:
-```toml
+```
[[menu.main]]
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
-{{% code file="config.toml" copy="false" %}}
-```toml
+{{< code file="config.toml" copy="false" >}}
[[menu.main]]
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
-```
-{{% /code %}}
+{{< /code >}}
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
-{{% code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" %}}
-```html
+{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
{{ range .Site.Menus.main }}
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
This partial would produce the following HTML output:
{{% output file="bad-url-sidebar-menu-output.html" %}}
-```html
+```
<!-- This unordered list may be part of a sidebar menu -->
<ul>
<li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
The odd output can be remedied by adding ` | safeURL` to our `.Title` page variable:
-{{% code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" %}}
-```html
+{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
</ul>
-```
-{{% /code %}}
+{{< /code >}}
With the `.URL` page variable piped through `safeURL`, we get the desired output:
{{% output file="correct-url-sidebar-menu-output.html" %}}
-```html
+```
<ul class="sidebar-menu">
<li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
</ul>
You can use `seq` in combination with `range` and `after`. The following will return 19 elements:
-```golang
+```
{{ range after 1 (seq 20)}}
{{ end }}
```
However, when ranging with an index, the following may be less confusing in that `$indexStartingAt1` and `$num` will return `1,2,3 ... 20`:
-```golang
+```
{{ range $index, $num := (seq 20) }}
$indexStartingAt1 := (add $index 1)
{{ end }}
`sha1` hashes the given input and returns its SHA1 checksum.
-```html
+```
{{ sha1 "Hello world, gophers!" }}
<!-- returns the string "c8b5b0e33d408246e30f53e32b8f7627a7a649d4" -->
```
`sha256` hashes the given input and returns its SHA256 checksum.
-```html
+```
{{ sha256 "Hello world, gophers!" }}
<!-- returns the string "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46" -->
```
aliases: []
---
-{{% code file="shuffle-input.html" %}}
-```html
+{{< code file="shuffle-input.html" >}}
<!-- Shuffled sequence = -->
<div>{{ shuffle (seq 1 5) }}</div>
<!-- Shuffled slice = -->
<div>{{ shuffle (slice "foo" "bar" "buzz") }}</div>
-```
-{{% /code %}}
+{{< /code >}}
This example would return the following:
{{% output file="shuffle-output.html" %}}
-```html
+```
<!-- Shuffled sequence = -->
<div>2 5 3 1 4</div>
<!-- Shuffled slice = -->
One use case is the concatenation of elements in combination with the [`delimit` function][]:
-{{% code file="slice.html" %}}
-```html
+{{< code file="slice.html" >}}
{{ delimit (slice "foo" "bar" "buzz") ", " }}
<!-- returns the string "foo, bar, buzz" -->
-```
-{{% /code %}}
+{{< /code >}}
[`delimit` function]: /functions/delimit/
A sorted array of map values will be returned with the keys eliminated. There are two optional arguments: `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order as its default behavior.
-```toml
+```
+++
#tags: [ "tag3", "tag1", "tag2" ]
+++
The following example may be useful when setting up [multilingual sites][multilingual]:
-{{% code file="unix-to-month-integer.html" %}}
-```html
+{{< code file="unix-to-month-integer.html" >}}
{{$time := time (int .Params.addDate)}}
=> $time = 1489276800
{{$time.Month}}
=> "March"
{{$monthindex := printf "%d" $time.Month }}
=> $monthindex = 3
-```
-{{% /code %}}
+{{< /code >}}
[int]: /functions/int/
Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64).
-```golang
+```
{{ union (slice 1 2 3) (slice 3 4 5) }}
<!-- returns [1 2 3 4 5] -->
This is also very useful to use as `OR` filters when combined with where:
-```html
+```
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
needsexamples: false
---
-```html
+```
{{ uniq (slice 1 2 3 2) }}
{{ slice 1 2 3 2 | uniq }}
<!-- both return [1 2 3] -->
This very simple one-liner uses `now.Unix` to calculate the amount of time that has passed between the `.LastMod` for the current page and the last build of the current page.
-{{% code file="time-passed.html" %}}
-```golang
+{{< code file="time-passed.html" >}}
{{ div (sub now.Unix .Lastmod.Unix) 86400 }}
-```
-{{% /code %}}
+{{< /code >}}
Since both values are integers, they can be subtracted and then divided by the number of seconds in a day (i.e., `60 * 60 * 24 == 86400`).
The following examples pull from a content file with the following front matter:
-{{% code file="content/blog/greatest-city.md" copy="false"%}}
-```toml
+{{< code file="content/blog/greatest-city.md" copy="false">}}
+++
title = "The World's Greatest City"
location = "Chicago IL"
tags = ["pizza","beer","hot dogs"]
+++
-```
-{{% /code %}}
+{{< /code >}}
The following might be used as a partial within a [single page template][singletemplate]:
-{{% code file="layouts/partials/content-header.html" download="content-header.html" %}}
-```html
+{{< code file="layouts/partials/content-header.html" download="content-header.html" >}}
<header>
<h1>{{.Title}}</h1>
{{ with .Params.location }}
</ul>
{{ end }}
</header>
-```
-{{% /code %}}
+{{< /code >}}
The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs.
{{% output file="/blog/greatest-city/index.html" %}}
-```html
+```
<header>
<h1>The World's Greatest City</h1>
<div><a href="/locations/chicago-il/">Chicago IL</a></div>
`where` filters an array to only the elements containing a matching value for a given field.
-```html
+```
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
It can be used by dot-chaining the second argument to refer to a nested element of a value.
-```toml
+```
+++
series: golang
+++
```
-```html
+```
{{ range where .Site.Pages "Params.series" "golang" }}
{{ .Content }}
{{ end }}
It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`.
-```html
+```
{{ range where .Data.Pages "Section" "!=" "post" }}
{{ .Content }}
{{ end }}
## Use `where` with `intersect`
-```html
+```
{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }}
{{ if ne .Permalink $.Permalink }}
{{ .Render "summary" }}
You can also put the returned value of the `where` clauses into a variable:
-{{% code file="where-intersect-variables.html" %}}
-```html
+{{< code file="where-intersect-variables.html" >}}
{{ $v1 := where .Site.Pages "Params.a" "v1" }}
{{ $v2 := where .Site.Pages "Params.b" "v2" }}
{{ $filtered := $v1 | intersect $v2 }}
{{ range $filtered }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Use `where` with `first`
The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
-{{% code file="where-with-first.html" %}}
-```html
+{{< code file="where-with-first.html" >}}
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Nest `where` Clauses
You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured:
-```html
+```
{{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
```
* `=`, `==`, `eq`: True if the given field is not set.
* `!=`, `<>`, `ne`: True if the given field is set.
-```html
+```
{{ range where .Data.Pages ".Params.specialpost" "!=" nil }}
{{ .Content }}
{{ end }}
The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing:
-{{% code file="layouts/partials/twitter.html" %}}
-```html
+{{< code file="layouts/partials/twitter.html" >}}
{{with .Site.Params.twitteruser}}<span class="twitter">
<a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
alt="Twitter"></a>
</span>{{end}}
-```
-{{% /code %}}
+{{< /code >}}
---
-title: Getting Started
-linktitle: Getting Started Overview
+title: Get Started
+linktitle: Get Started Overview
description: Quick start and guides for installing Hugo on your preferred operating system.
date: 2017-02-01
publishdate: 2017-02-01
---
-title: Configuring Hugo
+title: Configure Hugo
linktitle: Configuration
description: Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.
date: 2013-07-01
The following is a typical example of a YAML configuration file. Note the document opens with 3 hyphens and closes with 3 periods. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
-{{% code file="config.yml"%}}
-```yaml
+{{< code file="config.yml">}}
---
baseURL: "https://yoursite.example.com/"
title: "My Hugo Site"
- "foo2"
SidebarRecentLimit: 5
...
-```
-{{% /code %}}
+{{< /code >}}
### All Variables, YAML
The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
-{{% code file="config.yml" download="config.yml" %}}
-```yaml
+{{< code file="config.yml" download="config.yml" >}}
---
archetypeDir: "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/
- category: "categories"
- tag: "tags"
---
-```
-{{% /code %}}
+{{< /code >}}
## TOML Configuration
The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
-```toml
+```
contentDir = "content"
layoutDir = "layouts"
publishDir = "public"
The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.
-{{% code file="config.toml" download="config.toml"%}}
-```toml
+{{< code file="config.toml" download="config.toml">}}
+++
archetypeDir = "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/
category = "categories"
tag = "tags"
+++
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
-```bash
+```
~/sites/yourhugosite
hugo config | grep emoji
enableemoji: true
For example, the following command will effectively set a website's title on Unix-like systems:
-```bash
+```
$ env HUGO_TITLE="Some Title" hugo
```
The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering:
-```toml
+```
ignoreFiles = [ "\\.foo$", "\\.boo$" ]
```
2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
{{% /note %}}
-{{% code file="bf-config.toml" %}}
-```toml
+{{< code file="bf-config.toml" >}}
[blackfriday]
angledQuotes = true
fractions = false
plainIDAnchors = true
extensions = ["hardLineBreak"]
-```
-{{% /code %}}
+{{< /code >}}
-{{% code file="bf-config.yml" %}}
-```yaml
+{{< code file="bf-config.yml" >}}
blackfriday:
angledQuotes: true
fractions: false
plainIDAnchors: true
extensions:
- hardLineBreak
-```
-{{% /code %}}
+{{< /code >}}
## Configure Additional Output Formats
Running the `hugo new site` generator from the command line will create a directory structure with the following elements:
-```bash
+```
.
├── archetypes
├── config.toml
If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:
-{{% code file="install-with-homebrew.sh" %}}
-```bash
+{{< code file="install-with-homebrew.sh" >}}
brew install hugo
-```
-{{% /code %}}
+{{< /code >}}
For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.
If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner:
-{{% code file="install-with-chocolatey.ps1" %}}
-```powershell
+{{< code file="install-with-chocolatey.ps1" >}}
choco install hugo -confirm
-```
-{{% /code %}}
+{{< /code >}}
### Source
#### Fetch from GitHub
-{{% code file="from-gh.sh" %}}
-```sh
+{{< code file="from-gh.sh" >}}
go get github.com/kardianos/govendor
govendor get github.com/gohugoio/hugo
go install github.com/gohugoio/hugo
-```
-{{% /code %}}
+{{< /code >}}
`govendor get` will fetch Hugo and all its dependent libraries to `$GOPATH/src/github.com/gohugoio/hugo`, and `go install` compiles everything into a final `hugo` (or `hugo.exe`) executable inside `$GOPATH/bin/`.
Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
-{{% code file="install-brew.sh" %}}
-```bash
+{{< code file="install-brew.sh" >}}
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-```
-{{% /code %}}
+{{< /code >}}
#### Step 2: Run the `brew` Command to Install `hugo`
Installing Hugo using `brew` is as easy as the following:
-{{% code file="install-brew.sh" %}}
-```bash
+{{< code file="install-brew.sh" >}}
brew install hugo
-```
-{{% /code %}}
+{{< /code >}}
If Homebrew is working properly, you should see something similar to the following:
-```sh
+```
==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
######################################################################### 100.0%
==> Pouring hugo-0.21.sierra.bottle.tar.gz
`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands:
-```bash
+```
$ # show the location of the hugo executable
which hugo
/usr/local/bin/hugo
Verify that the tarball wasn't corrupted during the download:
-```bash
+```
tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
#### Step 4: Install Into Your `bin` Directory
-```bash
+```
# create the directory if needed
mkdir -p ~/bin
You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.
-```bash
+```
# check if hugo is in the path
which hugo
/Users/USERNAME/bin/hugo
If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:
-```bash
+```
nano ~/.bash_profile
```
Add a line to update your `PATH` variable:
-```bash
+```
export PATH=$PATH:$HOME/bin
```
If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command:
-```bash
+```
brew install go
```
If you want to compile a specific version of Hugo, go to <https://github.com/gohugoio/hugo/releases> and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:
-```bash
+```
git clone https://github.com/gohugoio/hugo
```
Make the directory containing the source your working directory and then fetch Hugo's dependencies:
-```bash
+```
mkdir -p src/github.com/gohugoio
ln -sf $(pwd) src/github.com/gohugoio/hugo
Once you have properly configured your directory, you can compile Hugo using the following command:
-```bash
+```
go build -o hugo main.go
```
At the prompt, type `hugo help` and press the <kbd>Enter</kbd> key. You should see output that starts with:
-```powershell
+```
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator
At the prompt, change your directory to the `Sites` directory.
-```powershell
+```
C:\Program Files> cd C:\Hugo\Sites
C:\Hugo\Sites>
```
Run the command to generate a new site. I'm using `example.com` as the name of the site.
-```powershell
+```
C:\Hugo\Sites> hugo new site example.com
```
You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following:
-```powershell
+```
C:\Hugo\Sites>cd example.com
C:\Hugo\Sites\example.com>dir
Directory of C:\hugo\sites\example.com
In any of the [Linux distributions that support snaps](https://snapcraft.io/docs/core/install):
-```sh
+```
sudo apt install hugo
```
Be aware that Hugo is built from source. This means that additional tools like [Git](https://git-scm.com) and [Go](https://golang.org/doc/install) will be installed as well.
-```bash
+```
sudo pacman -S yaourt
yaourt -S hugo
```
In any of the [Linux distributions that support snaps][snaps]:
-```bash
+```
snap install hugo
```
Once `hugo` is installed, make sure to run the `help` command to verify `hugo` installation. The following is an abridged version of what will write to the console when entering the command:
-```bash
+```
hugo help
hugo is the main command, used to build your Hugo site.
You can check the version of Hugo you're currently using with the `hugo version` command:
-```bash
+```
hugo version
```
-```bash
+```
Hugo Static Site Generator v0.18.1 BuildDate: 2016-12-30T05:02:43-05:00
```
Hugo's CLI has commands that allow you to quickly scaffold a new website. Navigate to your preferred location on your file system and create a new Hugo site `bookshelf` by executing the `hugo new` command:
-```bash
+```
hugo new site bookshelf
```
Change into the newly created `bookshelf` directory. Listing the new directory's content will show the following:
-```bash
+```
.
├── archetypes
├── config.toml
Let's now add a post to our "bookshelf." We will use the `hugo new` command to add a post. This first post will be on the book [*Good To Great*][bookurl]. Make sure you are inside the `bookshelf` directory.
-{{% code file="create-new-book-review-post.sh" %}}
-```bash
+{{< code file="create-new-book-review-post.sh" >}}
hugo new post/good-to-great.md
-```
-{{% /code %}}
+{{< /code >}}
You should then see the following output:
-```bash
+```
/Users/yourusername/bookshelf/content/post/good-to-great.md created
```
The above command will create a new directory `post` inside the `content` directory and create `content/post/good-to-great.md`. The directory for your Hugo project will now look like the following:
-```bash
+```
.
├── archetypes
├── config.toml
Open `good-to-great.md` in your preferred text editor:
-```toml
+```
+++
date = "2017-02-19T21:09:05-06:00"
title = "good to great"
Let's update `good-to-great.md` with a short review of *Good to Great*:
-{{% code file="good-to-great-start.md" %}}
-```markdown
+{{< code file="good-to-great-start.md" >}}
+++
date = "2016-02-14T16:11:58+05:30"
draft = true
+++
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
-```
-{{% /code %}}
+{{< /code >}}
## Step 4. Serve Content
Hugo has a built-in server that can serve your website locally for easy previewing and development. To serve content, execute the following command inside the `bookshelf` directory:
-```bash
+```
hugo server
```
You should see something similar to the following output:
-```bash
+```
Built site for language en:
0 of 1 draft rendered
0 future content
Kill the server using <kbd>Ctrl</kbd> + <kbd>C</kbd> and then rerun the server with the `--buildDrafts` flag appended to the command:
-```bash
+```
hugo server --buildDrafts
```
You should now see something similar to the following:
-```bash
+```
Built site for language en:
1 of 1 draft rendered
0 future content
Themes should be added in the `themes` directory, one of the directories scaffolded with the `hugo new site` command we used to start our Hugo project. To install our themes, first change into the `themes` directory:
-```bash
+```
cd themes
```
Once inside the `themes` directory, you can use the following one-liner to clone Robust, check out the specific commit, and then return to your project's root directory:
-{{% code file="clone-robust-theme" %}}
-```bash
+{{< code file="clone-robust-theme" >}}
git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..
-```
-{{% /code %}}
+{{< /code >}}
Now let's start Hugo's server again but with the addition of the `-theme` flag for Robust:
-{{% code file="hugo-server-with-theme.sh" %}}
-```bash
+{{< code file="hugo-server-with-theme.sh" >}}
hugo server --theme=hugo_theme_robust --buildDrafts
-```
-{{% /code %}}
+{{< /code >}}
You should see an output to the console similar to the following:
-```bash
+```
Built site for language en:
1 of 1 draft rendered
0 future content
If Hugo doesn't find the specified theme in the `themes` directory,
it will throw an exception:
-```bash
+```
FATAL: 2016/02/14 Unable to find theme Directory: /Users/yourusername/bookshelf/themes/robust
```
Similar to the way we looked at the scaffolding for our new Hugo website, let's take a look at what comprises a typical Hugo theme. The following is only a selection of what you would see if you were to list out the contents of the Robust theme directory. These are also some of the default files created by Hugo as of v0.23. (See [Creating a Theme][createtheme])
-```bash
+```
.
├── LICENSE.md
├── archetypes
From your project root, you can use this one-liner to change into `themes`, clone Bleak, and go back to your project's root directory:
-{{% code file="clone-bleak-theme.sh" %}}
-```bash
+{{< code file="clone-bleak-theme.sh" >}}
cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
-```
-{{% /code %}}
+{{< /code >}}
Now restart the server with our new theme flag:
-{{% code file="run-server-with-bleak.sh" %}}
-```bash
+{{< code file="run-server-with-bleak.sh" >}}
hugo server --theme=hugo-theme-bleak --buildDrafts
-```
-{{% /code %}}
+{{< /code >}}
Our website is now using the `bleak` theme at <http://localhost:1313>, which should look similar to the following screenshot:
Kill the Hugo server if you are still running it with the Bleak theme, and then restart the server with the `robust` theme. We will use Robust for the duration of this Quick Start:
-{{% code file="restart-with-robust-sh" %}}
-```bash
+{{< code file="restart-with-robust-sh" >}}
hugo server --theme=hugo_theme_robust --buildDrafts
-```
-{{% /code %}}
+{{< /code >}}
### Update Our `config.toml`
Our website is currently using the dummy values specified in `bookshelf/config.toml`, which were auto-generated with `hugo new site bookshelf`. Let's update the configuration:
-{{% code file="updated-config.toml" %}}
-```toml
+{{< code file="updated-config.toml" >}}
baseURL = "http://example.org/"
languageCode = "en-us"
title = "Shekhar Gulati Book Reviews"
[Params]
Author = "Shekhar Gulati"
-```
-{{% /code %}}
+{{< /code >}}
### Watch Your Site Reload Instantly
Now we need to change the layout of the index page so that only images are shown instead of the text. The file at `themes/hugo_theme_robust/layouts/index.html` refers to a partial `li.html` template that renders the following list view:
-```html
+```
<article class="li">
<a href="{{ .Permalink }}" class="clearfix">
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
Create a new file for `li.html` inside the `bookshelf/layouts/_default` directory. If you are in your project root, you can use the following one-liner to both create the file and return to the project root:
-{{% code file="create-new-li-html.sh" %}}
-```bash
+{{< code file="create-new-li-html.sh" >}}
cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
-```
-{{% /code %}}
+{{< /code >}}
Copy the content shown below into the new `li.html`. When contrasting this with the `li.html` that ships with the Robust theme, you'll notice we have removed details of the book so that only the image is shown:
-{{% code file="layouts/_default/li.html" %}}
-```html
+{{< code file="layouts/_default/li.html" >}}
<article class="li">
<a href="{{ .Permalink }}" class="clearfix">
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
</a>
</article>
-```
-{{% /code %}}
+{{< /code >}}
Now, the website should render similar to the following screenshot:
This is a new [partial template][partials]. If you are still in the project's root directory, you can use the following one-liner to create the partial before returning to the project root:
-{{% code file="create-new-default-foot.sh" %}}
-```bash
+{{< code file="create-new-default-foot.sh" >}}
cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..
-```
-{{% /code %}}
+{{< /code >}}
Now add the following to our new `default_foot.html` partial template:
-{{% code file="layouts/partials/default_foot.html" %}}
-```html
+{{< code file="layouts/partials/default_foot.html" >}}
<footer class="site">
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}© {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
<p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
</footer>
-```
-{{% /code %}}
+{{< /code >}}
So far we are using the default image, but we would like to use the book image so that we can relate to the book. Every book review will define a configuration setting in its front matter. Update the content and front matter of `good-to-great.md` as shown below.
-{{% code file="content/post/good-to-great.md" %}}
-```markdown
+{{< code file="content/post/good-to-great.md" >}}
+++
date = "2017-02-19T21:09:05-06:00"
draft = true
+++
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
-```
-{{% /code %}}
+{{< /code >}}
Grab a (legal) image from somewhere, name it `good-to-great.jpg`, and place it in the `bookshelf/static/images` directory.
So far, all the posts that we have written are in draft status (i.e., `draft = true`). To make a draft public, you can run a Hugo CLI command or manually change the draft status in the post's front matter to `false`. Hugo provides a handy command line argument called `undraft` to do this for us:
-```bash
+```
hugo undraft content/post/good-to-great.md
```
If we check the front matter of `good-to-great.md` after running this command, we'll notice that Hugo has written the change of draft status to the file:
-```toml
+```
+++
date = "2017-02-19T22:42:53-06:00"
draft = false
Now, we can start the server *without* the `buildDrafts` option.
-```bash
+```
hugo server --theme=hugo_theme_robust
```
To enable Disqus on our new site, we only need to update the `disqusShortname` in the config.toml as shown below.
-```toml
+```
[Params]
Author = "Shekhar Gulati"
disqusShortname = <your disqus shortname>
To generate a website that can be deployed to GitHub pages, we first need to change the `baseURL` in our configuration as follows:
-```toml
+```
baseURL = "https://<yourgithubusername>.github.io/bookshelf/"
```
Then type the following command while in the root directory of your Hugo project:
-```bash
+```
hugo --theme=hugo_theme_robust
0 draft content
0 future content
Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command:
-```bash
+```
hugo help
```
The output you see in your console should be similar to the following:
-```bash
+```
hugo is the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator
The site Hugo renders into `public/` is ready to be deployed to your web server:
-```bash
+```
hugo
0 draft content
0 future content
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes:
-```bash
+```
hugo server
0 draft content
0 future content
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. The following methods make it easy to disable LiveReload:
-```bash
+```
hugo server --watch=false
```
Or...
-```bash
+```
hugo server --disableLiveReload
```
The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively:
-```toml
+```
disableLiveReload = true
```
-```yaml
+```
disableLiveReload: true
```
To start a server that builds draft content (helpful for editing), you can specify a different destination; e.g., a `dev/` directory:
-```bash
+```
hugo server -wDs ~/Code/hugo/docs -d dev
```
When the content is ready for publishing, use the default `public/` dir:
-```bash
+```
hugo -s ~/Code/hugo/docs
```
The spoiler is that you can deploy your entire website with a command that looks like the following:
-```bash
+```
hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
```
First, install the ssh client. On Debian/Ubuntu/derivates, use the following command:
-{{% code file="install-openssh.sh" %}}
-```bash
+{{< code file="install-openssh.sh" >}}
sudo apt-get install openssh-client
-```
-{{% /code %}}
+{{< /code >}}
Then generate your ssh key by entering the following commands:
-```bash
+```
~$ cd && mkdir .ssh & cd .ssh
~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id
~/.ssh/$ cat >> config <<EOF
Don't forget to replace the `HOST` and `USER` values with your own ones. Then copy your ssh public key to the remote server:
-```bash
+```
~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
```
We will put the first command in a script at the root of your Hugo tree:
-```bash
+```
~/websites/topologix.fr$ editor deploy
```
Here you put the following content. Replace the `USER`, `HOST`, and `DIR` values with your own:
-```bash
+```
#!/bin/sh
USER=my-user
HOST=my-server.com
First, create your new Hugo website using the [`hugo new site` command][basicusage] and change into the newly created directory for the project. In this guide, we are calling our new project `hugo-wercker-example`:
-{{% code file="hugo-new-site.sh" %}}
-```bash
+{{< code file="hugo-new-site.sh" >}}
hugo new site hugo-wercker-example
cd hugo-wercker-example
-```
-{{% /code %}}
+{{< /code >}}
We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory.
-{{% code file="clone-herring-cove-theme.sh" %}}
-```bash
+{{< code file="clone-herring-cove-theme.sh" >}}
cd themes
git clone https://github.com/spf13/herring-cove.git
-```
-{{% /code %}}
+{{< /code >}}
Cloning the project from the command line will conflict with our own version control. So, we need to remove the external git configuration that came with the clone of Herring Cove:
-{{% code file="remove-herring-cove-git.sh" %}}
-```bash
+{{< code file="remove-herring-cove-git.sh" >}}
rm -rf herring-cove/.git
-```
-{{% /code %}}
+{{< /code >}}
We need content for Hugo to build. Let's add a quick `/about` page:
-```bash
+```
hugo new about.md
```
Now you can edit `contents/about.md` in your text editor of choice, but this is not necessary for the purposes of this guide. Running the following command will build your Hugo site into the `public` directory. We have added `undraft` to ensure that the example page is no longer in draft mode:
-{{% code file="hugo-build-undraft.sh" %}}
-```bash
+{{< code file="hugo-build-undraft.sh" >}}
hugo undraft content/about.md
-```
-{{% /code %}}
+{{< /code >}}
Once the website is build, t's a good idea to run the following command to start a local server and ensure you're changes have been implemented:
-```bash
+```
hugo server --theme=herring-cove
```
Adding Git to your project is done by running the `git init` command from the root directory of your project.
-```bash
+```
git init
```
Running `git status` at this point will show you the following entries: the `config.toml` file, the `themes` directory, the `contents` directory, and the `public` directory. However, we don't want the `public` directory version controlled because Wercker is responsible for generating the finished website later on. Therefore, we'll add a `.gitignore` file to our project that will exclude the `/public` directory from being tracked by Git:
-{{% code file="gitignore.sh" %}}
-```bash
+{{< code file="gitignore.sh" >}}
echo "/public" >> .gitignore
-```
-{{% /code %}}
+{{< /code >}}
Wercker might complain when we try to build the site later on because we currently do not have any static files outside of the `themes` directory. We simply have to add *any* file to the static folder to prevent Wercker from complaining. To keep this guide simple, let's add a `robots.txt`. The following command creates the file in `/static`. The contents of the `robots.txt` lets search engines know they have full access to crawl the published website:
-{{% code file="addrobotstxt.sh" %}}
-```bash
+{{< code file="addrobotstxt.sh" >}}
echo "User-agent: *\nDisallow:" > static/robots.txt
-```
-{{% /code %}}
+{{< /code >}}
Now we need to add (i.e., [stage [see Git documentation]][gitbasics]) and commit all of our changes in the repository into Git:
-```bash
+```
git commit -a -m "Initial commit"
```
We then choose a name for the project (`hugo-wercker-example`). When clicking on create repository GitHub displays the commands for adding an existing project to the site. The commands shown below are the ones used for this site, if you're following along you will need to use the ones shown by GitHub. Once we've run those commands the project is in GitHub and we can move on to setting up the Wercker configuration. Be sure to replace `YourUserName` with your GitHub account/username:
-{{% code file="setup-gh-repo.sh" %}}
-```bash
+{{< code file="setup-gh-repo.sh" >}}
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
git push -u origin master
-```
-{{% /code %}}
+{{< /code >}}
![][2]
The docs are a work in progress. As such, the `version` represented in this guide may not represent the version you've been using for local development. Be sure to use the appropriate Hugo version for your build step.
{{% /warning %}}
-{{% code file="wercker-build-step.yml" %}}
-```yaml
+{{< code file="wercker-build-step.yml" >}}
box: debian
build:
steps:
version: "0.17"
theme: herring-cove
flags: --buildDrafts=true
-```
-{{% /code %}}
+{{< /code >}}
We can conclude this first step by pushing our `wercker.yml` to our GitHub repository and then seeing the magic at work within Wercker's interface.
-{{% code file="push-wecker-to-gh.sh" %}}
-```bash
+{{< code file="push-wecker-to-gh.sh" >}}
git commit -a -m "Add wercker.yml"
git push origin master
-```
-{{% /code %}}
+{{< /code >}}
If completed and successful, a green check mark should appear in the commit column of your first build. However, this is only the build step. We still need to deploy the website to our free hosting on GitHub Pages. If you would like more details about the build, you can click the commit hash.
In order to deploy to GitHub Pages, we need to add a deploy step to our `wercker.yml`. We are going to add `lukevevier/gh-pages`, the most popular GitHub Pages step in the Wercker Steps repository. Additionally, we need to ensure the box Wercker uses for our deployments has git and ssh installed. We can do this using the `install-packages` command. Here is our *final* `wercker.yml` file:
-{{% code file="wercker.yml" %}}
-```yaml
+{{< code file="wercker.yml" >}}
box: debian
build:
steps:
token: $GIT_TOKEN
domain: hugo-wercker.ig.nore.me
basedir: public
-```
-{{% /code %}}
+{{< /code >}}
### How does the GitHub Pages Configuration Work?
---
-title: Hosting on Bitbucket
-linktitle: Hosting on Bitbucket
+title: Host on Bitbucket
+linktitle: Host on Bitbucket
description: You can use Bitbucket in conjunction with Aerobatic to build, deploy, and host a Hugo website.
date: 2017-02-04
publishdate: 2017-02-04
If you haven't previously used Aerobatic, you'll first need to install the Command Line Interface (CLI) and create an account. For a list of all commands available, see the [Aerobatic CLI](https://www.aerobatic.com/docs/cli/) docs.
-```bash
+```
npm install aerobatic-cli -g
aero register
```
## Create and Deploy Site
-```bash
+```
hugo new site my-new-hugo-site
cd my-new-hugo-site
cd themes; git clone https://github.com/eliasson/liquorice
[1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png
-```bash
+```
# initialize new git repository
git init
3. On the next screen, leave the default template and click Next.
4. In the editor, paste in the yaml contents below and click Commit.
-```bash
+```
image: beevelop/nodejs-python
pipelines:
branches:
This step only needs to be done once per account. From the command line;
-```bash
+```
aero apikey
```
### Step 3: Edit and Commit Code
-```bash
+```
hugo new post/good-to-great.md
hugo server --buildDrafts -t liquorice #Check that all looks good
---
-title: Hosting on Firebase
-linktitle: Hosting on Firebase
+title: Host on Firebase
+linktitle: Host on Firebase
description: You can use Firebase's free tier to host your static website; this also gives you access to Firebase's NOSQL API.
date: 2017-03-12
publishdate: 2017-03-12
Go to the [Firebase console][console] and create a new project (unless you already have a project). You will need to globally install `firebase-tools` (node.js):
-```sh
+```
npm install -g firebase-tools
```
Log in to Firebase (setup on your local machine) using `firebase login`, which opens a browser where you can select your account. Use `firebase logout` in case you are already logged in but to the wrong account.
-```sh
+```
firebase login
```
In the root of your Hugo project, initialize the Firebase project with the `firebase init` command:
-```sh
+```
firebase init
```
From here:
To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
-```sh
+```
hugo && firebase deploy
```
You can generate a deploy token using
-```sh
+```
firebase login:ci
```
You can then add a step in your build to do the deployment using the token:
-```sh
+```
firebase deploy --token $FIREBASE_DEPLOY_TOKEN
```
---
-title: Hosting on GitHub
-linktitle: Hosting on GitHub
+title: Host on GitHub
+linktitle: Host on GitHub
description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
date: 2014-03-21
publishdate: 2014-03-21
[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
-```yaml
+```
publishDir: docs
```
-```toml
+```
publishDir = "docs"
```
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
-```bash
+```
echo "public" >> .gitignore
```
You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
-```bash
+```
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
-```sh
+```
rm -rf public
git worktree add -B gh-pages public upstream/gh-pages
```
Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
-{{% code file="commit-gh-pages-files.sh"%}}
-```bash
+{{< code file="commit-gh-pages-files.sh">}}
hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
-```
-{{% /code %}}
+{{< /code >}}
If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
-```bash
+```
git push upstream gh-pages
```
To automate these steps, you can create a script with the following contents:
-{{% code file="publish_to_ghpages.sh" %}}
-```sh
+{{< code file="publish_to_ghpages.sh" >}}
#!/bin/sh
DIR=$(dirname "$0")
echo "Updating gh-pages branch"
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
-```
-{{% /code %}}
+{{< /code >}}
This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
The following are the contents of the `deploy.sh` script:
-```sh
+```
#!/bin/bash
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
---
-title: Hosting on GitLab
-linktitle: Hosting on GitLab
+title: Host on GitLab
+linktitle: Host on GitLab
description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
date: 2016-06-23
publishdate: 2016-06-23
## Create .gitlab-ci.yml
-```bash
+```
cd your-hugo-site
```
In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
-{{% code file="gitlab-ci.yml" %}}
-```yml
+{{< code file="gitlab-ci.yml" >}}
image: publysher/hugo
pages:
- public
only:
- master
-```
-{{% /code %}}
+{{< /code >}}
## Push Your Hugo Website to GitLab
Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
-```bash
+```
# initialize new git repository
git init
---
-title: Hosting on Netlify
-linktitle: Hosting on Netlify
+title: Host on Netlify
+linktitle: Host on Netlify
description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI.
date: 2017-02-01
publishdate: 2017-02-01
If you want to tell Netlify to build with a specific version, you can append an underscore followed by the version number to the build command:
-```bash
+```
hugo_0.19
```
A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`:
-```bash
+```
cd themes
git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
```
---
date: 2016-06-06T13:54:06-04:00
description: "Hugo 0.16 is our best and biggest release ever. The Hugo community has outdone itself with continued performance improvements, beautiful themes and increased stability."
-title: "June Release"
+title: "Hugo 0.16"
categories: ["Releases"]
---
date: 2016-10-07T13:54:06-04:00
description: "Hugo now supports multilingual sites with the most simple and elegant experience."
link: ""
-title: "October Release: Hugo is going global"
+title: "0.17: Hugo is going global"
draft: false
---
Hugo is going global with our 0.17 release. We put a lot of thought into how we could extend Hugo
categories: ["Releases"]
description: "The primary new feature in Hugo 0.18 is that every piece of content is now a Page."
link: ""
-title: "December Hugo Release"
+title: "Hugo 0.18"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.19 brings native Emacs Org-mode content support, and Hugo has its own Twitter account"
link: ""
-title: "February Release"
+title: "Hugo 0.19"
draft: false
author: budparr
---
categories: ["Releases"]
description: "Hugo 0.20.1 is a bug fix release, fixing some important regressions introduced in 0.20"
link: ""
-title: "April Release"
+title: "Hugo 0.20.1"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.20.2 adds support for plain text partials included into HTML templates"
link: ""
-title: "April Release"
+title: "Hugo 0.20.2"
draft: false
author: bep
---
categories: ["Releases"]
description: "This is a bug-fix release with one important fix. But it also adds some harness around GoReleaser"
link: ""
-title: "April Release"
+title: "Hugo 0.20.3"
draft: false
author: bep
---
categories: ["Releases"]
description: "This is the second bug-fix release of the day, fixing a couple of issues related to the new release scripts"
link: ""
-title: "April Release"
+title: "Hugo 0.20.4"
draft: false
author: bep
---
categories: ["Releases"]
description: ""
link: ""
-title: "April Release"
+title: "Hugo 0.20.5"
draft: false
author: bep
---
categories: ["Releases"]
description: ""
link: ""
-title: "April Release"
+title: "Hugo 0.20.6"
draft: false
author: bep
---
categories: ["Releases"]
description: "This just fixes an issue with the release scripts, no change in the binaries"
link: ""
-title: "May Release"
+title: "Hugo 0.20.7"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.20 introduces the powerful and long sought after feature Custom Output Formats"
link: ""
-title: "April Release"
+title: "Hugo 0.20"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.21 brings full support for shortcodes per Output Format, the last vital piece of that puzzle"
link: ""
-title: "May Release"
+title: "Hugo 0.21"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.22.1 fixes a couple of issues reported after the 0.22 release"
link: ""
-title: "June Release"
+title: "Hugo 0.22.1"
draft: false
author: bep
---
**First level only:**
-```toml
+```
[permalinks]
blog = ":section/:title"
```
**Nested (all levels):**
-```toml
+```
[permalinks]
blog = ":sections/:title"
```
categories: ["Releases"]
description: "Hugo 0.22 brings nested sections, by popular demand and a long sought after feature"
link: ""
-title: "June Release"
+title: "Hugo 0.22"
draft: false
author: bep
---
`.Site.GetPage` can now also be used to get regular pages ([#2844](https://github.com/gohugoio/hugo/issues/2844)):
-```go
+```
{{ (.Site.GetPage "page" "blog" "mypost.md" ).Title }}
```
categories: ["Releases"]
description: "Hugo 0.23 is mainly a release that handles all the small changes needed to get Hugo moved to a GitHub organisation"
link: ""
-title: "June Release"
+title: "Hugo 0.23"
draft: false
author: bep
---
categories: ["Releases"]
description: "This release fixes some important archetype-related regressions from Hugo 0.24"
link: ""
-title: "June Release"
+title: "Hugo 0.24.1"
draft: false
author: bep
---
categories: ["Releases"]
description: "The Revival of the Archetypes!"
link: ""
-title: "June Release"
+title: "Hugo 0.24"
draft: false
author: bep
---
A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`:
-```markdown
+```
---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
And then create a new post with:
-```bash
+```
hugo new newsletter/the-latest-cool.stuff.md
```
categories: ["Releases"]
description: "This is a bug-fix release with a couple of important fixes"
link: ""
-title: "July Release"
+title: "Hugo 0.25.1"
draft: false
author: bep
---
categories: ["Releases"]
description: "Hugo 0.25 automatically opens the page you're working on in the browser"
link: ""
-title: "July Release"
+title: "Hugo 0.25"
draft: false
author: bep
---
Example:
-```go
+```
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
---
title: "Hugo News"
+aliases: [/release-notes/]
---
In `layouts/partials/mystyles.css`:
-```css
+```
body {
background-color: {{ .Param "colors.main" }}
}
Then in `config.toml` (note that by using the `.Param` lookup func, we can override the color in a page's front matter if we want):
-```toml
+```
[params]
[params.colors]
main = "green"
And then in `layouts/partials/head.html` (or the partial used to include the head section into your layout):
-```html
+```
<head>
<style type="text/css">
{{ partial "mystyles.css" . | safeCSS }}
Add "CSS" to your home page's `outputs` list, create the template `/layouts/index.css` using Go template syntax for the dynamic parts, and then include it into your `HTML` template with:
-```html
+```
{{ with .OutputFormats.Get "css" }}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end }}`
`angledQuotes`
: default: **`false`**<br>
Blackfriday flag: **`HTML_SMARTYPANTS_ANGLED_QUOTES`**<br>
- Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to renders to «Hugo» instead of “Hugo”.
+ Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to «Hugo» instead of “Hugo”.
`fractions`
: default: **`true`**<br>
: default: **`[]`** <br>
Blackfriday flag: **`EXTENSION_*`** <br>
Purpose: Enable one or more of Blackfriday's Markdown extensions (if they aren't Hugo defaults). <br>
- Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`.
\ No newline at end of file
+ Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`.
In addition to the standard page variables, the 404 page has access to all site content accessible from `.Data.Pages`.
-```bash
+```
▾ layouts/
404.html
```
This is a basic example of a 404.html template:
-{{% code file="layouts/404.html" download="404.html" %}}
-```html
+{{< code file="layouts/404.html" download="404.html" >}}
{{ define "main"}}
<main id="main">
<div>
</div>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Automatic Loading
In Hugo, the Ace base template will be chosen with the same rule set as for [Go base templates][].
-```bash
+```
.:
index.ace
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
-{{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
-```html
+{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
<!DOCTYPE html>
<html>
<head>
{{ end }}
</body>
</html>
-```
-{{% /code %}}
+{{< /code >}}
## Override the Base Template
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
-{{% code file="layouts/_default/list.html" download="list.html" %}}
-```html
+{{< code file="layouts/_default/list.html" download="list.html" >}}
{{ define "main" }}
<h1>Posts</h1>
{{ range .Data.Pages }}
</article>
{{ end }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
{{% warning %}}
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
-```html
+```
<!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }}
...your code here
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
-{{% code file="layouts/_default/single.html" download="single.html" %}}
-```html
+{{< code file="layouts/_default/single.html" download="single.html" >}}
{{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
{{ .Title }} – {{ .Site.Title }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
[hugolists]: /templates/lists
[lookup]: /templates/lookup-order/
You can now render the list of recordings for all the bass players in a template:
-```html
+```
{{ range $.Site.Data.jazz.bass }}
{{ partial "artist.html" . }}
{{ end }}
In your template, call the functions like this:
-```golang
+```
{{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }}
```
All passed arguments will be joined to the final URL:
-```html
+```
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
```
This will resolve internally to the following:
-```html
+```
{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }}
```
Finally, you can range over an array. This example will output the
first 5 gists for a GitHub user:
-```html
+```
<ul>
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
For `getCSV`, the one-character-long separator must be placed in the first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV:
-{{% code file="layouts/partials/get-csv.html" %}}
-```html
+{{< code file="layouts/partials/get-csv.html" >}}
<table>
<thead>
<tr>
{{ end }}
</tbody>
</table>
-```
-{{% /code %}}
+{{< /code >}}
The expression `{{index $r number}}` must be used to output the nth-column from the current row.
This shortcode creates a link to each of the files in a directory---display as the file's basename---along with the file's size in bytes.
-{{% code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" %}}
-```html
+{{< code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" >}}
{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/directoryindex.html" >}}
-```
-{{% /code %}}
+{{< /code >}}
You can then call the shortcode as follows inside of your content's markup:
-```html
+```
{{</* directoryindex path="/static/css" pathURL="/css" */>}}
```
To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*:
-```html
+```
{{ readFile "/content/templates/local-file-templates" }}
```
Here is the templating for our new `readfile` shortcode:
-{{% code file="layouts/shortcodes/readfile.html" download="readfile.html" %}}
-```
+{{< code file="layouts/shortcodes/readfile.html" download="readfile.html" >}}
{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/readfile.html">}}
-```
-{{% /code %}}
+{{< /code >}}
This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is [`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows:
The output "string" for this shortcode declaration will be the following:
-```markdown
+```
{{< readfile file="/content/readfiles/testing.txt" >}}
```
However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter:
-```html
+```
{{</* readfile file="/content/readfiles/testing.txt" markdown="true" */>}}
```
The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{Content}}` [page variables][pagevars].
-{{% code file="layouts/index.html" download="index.html" %}}
-```html
+{{< code file="layouts/index.html" download="index.html" >}}
{{ define "main" }}
<main aria-role="main">
<header class="homepage-header">
</div>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
[base]: /templates/base/
[contentorg]: /content-management/organization/
Provide your tracking id in your configuration file:
-```toml
+```
googleAnalytics = "UA-123-45"
```
-```yml
+```
googleAnalytics: "UA-123-45"
```
You can then include the Google Analytics internal template:
-```golang
+```
{{ template "_internal/google_analytics.html" . }}
```
-```golang
+```
{{ template "_internal/google_analytics_async.html" . }}
```
To use Hugo's Disqus template, you first need to set a single value in your site's `config.toml` or `config.yml`:
-```toml
+```
disqusShortname = "yourdiscussshortname"
```
-```yaml
+```
disqusShortname: "yourdiscussshortname"
```
To add Disqus, include the following line in templates where you want your comments to appear:
-```golang
+```
{{ template "_internal/disqus.html" . }}
```
You can create the following `layouts/partials/disqus.html`:
-{{% code file="layouts/partials/disqus.html" download="disqus.html" %}}
-```html
+{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
<div id="disqus_thread"></div>
<script type="text/javascript">
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
-```
-{{% /code %}}
+{{< /code >}}
The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
You can then render your custom Disqus partial template as follows:
-```golang
+```
{{ partial "disqus.html" . }}
```
### Access a Predefined Variable
-```golang
+```
{{ foo }}
```
Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`:
-```golang
+```
{{ add 1 2 }}
```
Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
-```golang
+```
{{ .Params.bar }}
```
#### Parentheses Can be Used to Group Items Together
-```golang
+```
{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
```
This is how you access a `Page` variable from a template:
-```golang
+```
<title>{{ .Title }}</title>
```
Values can also be stored in custom variables and referenced later:
-```golang
+```
{{ $address := "123 Main St."}}
{{ $address }}
```
### Example 1: Adding Numbers
-```golang
+```
{{ add 1 2 }}
=> 3
```
### Example 2: Comparing Numbers
-```golang
+```
{{ lt 1 2 }}
=> true (i.e., since 1 is less than 2)
```
### Template and Partial Examples
-```golang
+```
{{ template "partials/header.html" . }}
```
Starting with Hugo v0.12, you may also use the `partial` call
for [partial templates][partials]:
-```golang
+```
{{ partial "header.html" . }}
```
#### Example 1: Using Context
-```golang
+```
{{ range array }}
{{ . }}
{{ end }}
#### Example 2: Declaring Value => Variable name
-```golang
+```
{{range $element := array}}
{{ $element }}
{{ end }}
#### Example 3: Declaring Key-Value Variable Name
-```golang
+```
{{range $index, $element := array}}
{{ $index }}
{{ $element }}
#### Example 1: `if`
-```golang
+```
{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
```
#### Example 2: `if` … `else`
-```golang
+```
{{ if isset .Params "alt" }}
{{ index .Params "alt" }}
{{else}}
#### Example 3: `and` & `or`
-```golang
+```
{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
```
The first example above could be simplified as:
-```golang
+```
{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
```
#### Example 5: `if` … `else if`
-```golang
+```
{{ if isset .Params "alt" }}
{{ index .Params "alt" }}
{{ else if isset .Params "caption" }}
The following two examples are functionally the same:
-```golang
+```
{{ shuffle (seq 1 5) }}
```
-```golang
+```
{{ (seq 1 5) | shuffle }}
```
The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates:
-```golang
+```
{{ index .Params "disqus_url" | html }}
```
### Example 3: `or` with `isset`
-```golang
+```
{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
Stuff Here
{{ end }}
Could be rewritten as
-```golang
+```
{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
Stuff Here
{{ end }}
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:
-```golang
+```
{{ "<!--[if lt IE 9]>" | safeHTML }}
<script src="html5shiv.js"></script>
{{ "<![endif]-->" | safeHTML }}
The following shows how to define a variable independent of the context.
-{{% code file="tags-range-with-page-variable.html" %}}
-```html
+{{< code file="tags-range-with-page-variable.html" >}}
{{ $title := .Site.Title }}
<ul>
{{ range .Params.tags }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context:
-{{% code file="range-through-tags-w-global.html" %}}
-```hbs
+{{< code file="range-through-tags-w-global.html" >}}
<ul>
{{ range .Params.tags }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
{{% warning "Don't Redefine the Dot" %}}
The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
For instance, the following Go template will include the newlines and horizontal tab in its HTML output:
-```html
+```
<div>
{{ .Title }}
</div>
Which will output:
-```html
+```
<div>
Hello, World!
</div>
Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
-```html
+```
<div>
{{- .Title -}}
</div>
Which then outputs:
-```html
+```
<div>Hello, World!</div>
```
Here is the example front matter:
-```yaml
+```
---
title: Roadmap
lastmod: 2017-03-05
Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
-{{% code file="layouts/partials/toc.html" download="toc.html" %}}
-```html
+{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{ if not .Params.notoc }}
<aside>
<header>
</aside>
<a href="#" id="toc-toggle"></a>
{{end}}
-```
-{{% /code %}}
+{{< /code >}}
We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
For instance, you might declare the following:
-{{% code file="config.yaml" %}}
-```yaml
+{{< code file="config.yaml" >}}
params:
copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
twitteruser: "spf13"
sidebarrecentlimit: 5
-```
-{{% /code %}}
+{{< /code >}}
Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
-```html
+```
{{if .Site.Params.copyrighthtml}}<footer>
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
</footer>{{end}}
An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
-{{% code file="layouts/partials/twitter.html" %}}
-```html
+{{< code file="layouts/partials/twitter.html" >}}
{{with .Site.Params.twitteruser}}
<div>
<a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
</div>
{{end}}
-```
-{{% /code %}}
+{{< /code >}}
Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
-```html
+```
<nav>
<h1>Recent Posts</h1>
<ul>
Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
-{{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}}
-```html
+{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
<h4>Upcoming Events</h4>
<ul class="upcoming-events">
{{ range where .Data.Pages.ByDate "Section" "events" }}
{{ end }}
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
[`where` function]: /functions/where/
The following is an example of a typical Hugo project directory's content:
-```bash
+```
.
...
├── content
Using the above example, let's assume you have the following in `content/post/_index.md`:
-{{% code file="content/post/_index.md" %}}
-```yaml
+{{< code file="content/post/_index.md" >}}
---
title: My Golang Journey
date: 2017-03-23
I decided to start learning Golang in March 2017.
Follow my journey through this new blog.
-```
-{{% /code %}}
+{{< /code >}}
You can now access this `_index.md`'s' content in your list template:
-{{% code file="layouts/_default/list.html" download="list.html" %}}
-```html
+{{< code file="layouts/_default/list.html" download="list.html" >}}
{{ define "main" }}
<main>
<article>
</ul>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
This above will output the following HTML:
-{{% code file="yoursite.com/post/index.html" copy="false" %}}
-```html
+{{< code file="example.com/post/index.html" copy="false" >}}
<!--top of your baseof code-->
<main>
<article>
</ul>
</main>
<!--bottom of your baseof-->
-```
-{{% /code %}}
+{{< /code >}}
### List Pages Without `_index.md`
Using this same `layouts/_default/list.html` template and applying it to the the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
-{{% code file="yoursite.com/quote/index.html" copy="false" %}}
-```html
+{{< code file="example.com/quote/index.html" copy="false" >}}
<!--baseof-->
<main>
<article>
</header>
</article>
<ul>
- <li><a href="https://yoursite.com/quote/quotes-01/">Quote 1</a></li>
- <li><a href="https://yoursite.com/quote/quotes-02/">Quote 2</a></li>
+ <li><a href="https://example.com/quote/quotes-01/">Quote 1</a></li>
+ <li><a href="https://example.com/quote/quotes-02/">Quote 2</a></li>
</ul>
</main>
<!--baseof-->
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base] The examples that follow also use the [content view templates][views] `li.html` or `summary.html`.
-{{% code file="layouts/section/post.html" %}}
-```html
+{{< code file="layouts/section/post.html" >}}
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
<main>
</div>
</main>
{{ partial "footer.html" . }}
-```
-{{% /code %}}
+{{< /code >}}
### Taxonomy Template
-{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
-```html
+{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
{{ define "main" }}
<main>
<div>
</div>
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Order Content
Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates:
-### Default List Ordering: Weight > Date
+### Default: Weight > Date > LinkTitle > FilePath
-{{% code file="layouts/partials/default-order.html" %}}
-```html
+{{< code file="layouts/partials/default-order.html" >}}
<ul>
{{ range .Data.Pages }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Weight
-{{% code file="layouts/partials/by-weight.html" %}}
-```html
+{{< code file="layouts/partials/by-weight.html" >}}
<ul>
{{ range .Data.Pages.ByWeight }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Date
-{{% code file="layouts/partials/by-date.html" %}}
-```html
+{{< code file="layouts/partials/by-date.html" >}}
<ul>
<!-- orders content according to the "date" field in front matter -->
{{ range .Data.Pages.ByDate }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Publish Date
-{{% code file="layouts/partials/by-publish-date.html" %}}
-```html
+{{< code file="layouts/partials/by-publish-date.html" >}}
<ul>
<!-- orders content according to the "publishdate" field in front matter -->
{{ range .Data.Pages.ByPublishDate }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Expiration Date
-{{% code file="layouts/partials/by-expiry-date.html" %}}
-```html
+{{< code file="layouts/partials/by-expiry-date.html" >}}
<ul>
{{ range .Data.Pages.ByExpiryDate }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Last Modified Date
-{{% code file="layouts/partials/by-last-mod.html" %}}
-```html
+{{< code file="layouts/partials/by-last-mod.html" >}}
<ul>
<!-- orders content according to the "lastmod" field in front matter -->
{{ range .Data.Pages.ByLastmod }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Length
-{{% code file="layouts/partials/by-length.html" %}}
-```html
+{{< code file="layouts/partials/by-length.html" >}}
<ul>
<!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
{{ range .Data.Pages.ByLength }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Title
-{{% code file="layouts/partials/by-title.html" %}}
-```html
+{{< code file="layouts/partials/by-title.html" >}}
<ul>
<!-- ranges through content in ascending order according to the "title" field set in front matter -->
{{ range .Data.Pages.ByTitle }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Link Title
-{{% code file="layouts/partials/by-link-title.html" %}}
-```html
+{{< code file="layouts/partials/by-link-title.html" >}}
<ul>
<!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
{{ range .Data.Pages.ByLinkTitle }}
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Parameter
Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
-{{% code file="layouts/partials/by-rating.html" %}}
-```html
+{{< code file="layouts/partials/by-rating.html" >}}
<!-- Ranges through content according to the "rating" field set in front matter -->
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
If the targeted front matter field is nested beneath another field, you can access the field using dot notation.
-{{% code file="layouts/partials/by-nested-param.html" %}}
-```html
+{{< code file="layouts/partials/by-nested-param.html" >}}
{{ range (.Data.Pages.ByParam "author.last_name") }}
<!-- ... -->
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### Reverse Order
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
-{{% code file="layouts/partials/by-date-reverse.html" %}}
-```html
+{{< code file="layouts/partials/by-date-reverse.html" >}}
<ul>
{{ range .Data.Pages.ByDate.Reverse }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
## Group Content
### By Page Field
-{{% code file="layouts/partials/by-page-field.html" %}}
-```html
+{{< code file="layouts/partials/by-page-field.html" >}}
<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
{{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
-{{% code file="layouts/partials/by-page-field.html" %}}
-```html
+{{< code file="layouts/partials/by-page-field.html" >}}
<!-- Groups content according to content section.-->
{{ range .Data.Pages.GroupBy "Section" }}
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Date
-{{% code file="layouts/partials/by-page-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-date.html" >}}
<!-- Groups content by month according to the "date" field in front matter -->
{{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Publish Date
-{{% code file="layouts/partials/by-page-publish-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-publish-date.html" >}}
<!-- Groups content by month according to the "publishdate" field in front matter -->
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page Parameter
-{{% code file="layouts/partials/by-page-param.html" %}}
-```html
+{{< code file="layouts/partials/by-page-param.html" >}}
<!-- Groups content according to the "param_key" field in front matter -->
{{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page Parameter in Date Format
The following template takes grouping by `date` a step further and uses Golang's layout string. See the [`Format` function][] for more examples of how to use Golang's layout string to format dates in Hugo.
-{{% code file="layouts/partials/by-page-param-as-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-param-as-date.html" >}}
<!-- Groups content by month according to the "param_key" field in front matter -->
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### Reverse Key Order
#### 1. Adding the Reverse Method
-```html
+```
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
```
-```html
+```
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### 2. Providing the Alternate Direction
-```html
+```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
-```html
+```
{{ range .Data.Pages.GroupBy "Section" "desc" }}
```
2. Groups are listed in ascending order (i.e., the oldest groups first)
3. Pages within each respective group are ordered alphabetically according to the `title`.
-{{% code file="layouts/partials/by-group-by-page.html" %}}
-```html
+{{< code file="layouts/partials/by-group-by-page.html" >}}
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Filter and Limiting Lists
2. `key` *or* `field name`
3. `match value`
-{{% code file="layouts/_default/.html" %}}
-```html
+{{< code file="layouts/_default/.html" >}}
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
You can see more examples in the [functions documentation for `where`][wherefunction].
1. `array` *or* `slice of maps or structs`
2. `number of elements`
-{{% code file="layout/_default/section.html" %}}
-```html
+{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
-{{% code file="first-and-where-together.html" %}}
-```html
+{{< code file="first-and-where-together.html" >}}
<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts -->
{{ range first 5 (where .Data.Pages "Section" "post").ByTitle }}
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
[base]: /templates/base/
[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
[taxvars]: /variables/taxonomy/
[views]: /templates/views/
[wherefunction]: /functions/where/
-[wherekeyword]: https://www.techonthenet.com/sql/where.php
\ No newline at end of file
+[wherekeyword]: https://www.techonthenet.com/sql/where.php
1. The project is using the theme `mytheme` (specified in the project's [configuration][config]).
2. The layouts and content directories for the project are as follows:
-```bash
+```
.
├── content
│ ├── events
### Example: `my-first-post.md`
-{{% code file="content/posts/my-first-post.md" copy="false" %}}
-```yaml
+{{< code file="content/posts/my-first-post.md" copy="false" >}}
---
title: My First Post
date: 2017-02-19
description: This is my first post.
---
-```
-{{% /code %}}
+{{< /code >}}
When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`:
### Example: `my-second-post.md`
-{{% code file="content/posts/my-second-post.md" copy="false" %}}
-```yaml
+{{< code file="content/posts/my-second-post.md" copy="false" >}}
---
title: My Second Post
date: 2017-02-21
type: review
layout: reviewarticle
---
-```
-{{% /code %}}
+{{< /code >}}
Here is the way Hugo traverses the single-page lookup order for `my-second-post.md`:
### Example: `my-first-event.md`
-{{% code file="content/events/my-first-event.md" copy="false" %}}
-```yaml
+{{< code file="content/events/my-first-event.md" copy="false" >}}
---
title: My First
date: 2017-02-21
description: This is an upcoming event..
---
-```
-{{% /code %}}
+{{< /code >}}
Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:
The following is an example:
-{{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}}
-```html
+{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
<!-- sidebar start -->
<aside>
<div id="sidebar" class="nav-collapse">
</div>
</aside>
<!--sidebar end-->
-```
-{{% /code %}}
+{{< /code >}}
{{% note "`absLangURL` and `relLangURL`" %}}
Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url.
To enable this menu, add the following to your site `config`:
-```toml
+```
SectionPagesMenu = "main"
```
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
-```html
+```
<nav class="sidebar-nav">
{{ $currentPage := . }}
{{ range .Site.Menus.main }}
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
-```toml
+```
[[menu.main]]
name = "This is the blog section"
weight = -110
---
-title: Ordering and Grouping Hugo Lists
+title: Ordere and Grouping Hugo Lists
linktitle: List Ordering and Grouping
description: You can group or order your content in both your templating and content front matter.
date: 2017-02-01
This list template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary."
-{{% code file="layouts/section/post.html" %}}
-```html
+{{< code file="layouts/section/post.html" >}}
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
</div>
</section>
{{ partial "footer.html" . }}
-```
-{{% /code %}}
+{{< /code >}}
### Taxonomy Template
-{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
-```html
+{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
{{ define "main" }}
<section id="main">
<div>
</div>
</section>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Order Content
### Default: Weight > Date
-{{% code file="layouts/partials/order-default.html" %}}
-```html
+{{< code file="layouts/partials/order-default.html" >}}
<ul class="pages">
{{ range .Data.Pages }}
<li>
</li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
### By Weight
-{{% code file="layouts/partials/by-weight.html" %}}
-```html
+{{< code file="layouts/partials/by-weight.html" >}}
{{ range .Data.Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Date
-{{% code file="layouts/partials/by-date.html" %}}
-```html
+{{< code file="layouts/partials/by-date.html" >}}
{{ range .Data.Pages.ByDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Publish Date
-{{% code file="layouts/partials/by-publish-date.html" %}}
-```html
+{{< code file="layouts/partials/by-publish-date.html" >}}
{{ range .Data.Pages.ByPublishDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Expiration Date
-{{% code file="layouts/partials/by-expiry-date.html" %}}
-```html
+{{< code file="layouts/partials/by-expiry-date.html" >}}
{{ range .Data.Pages.ByExpiryDate }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Last Modified Date
-{{% code file="layouts/partials/by-last-mod.html" %}}
-```html
+{{< code file="layouts/partials/by-last-mod.html" >}}
{{ range .Data.Pages.ByLastmod }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Length
-{{% code file="layouts/partials/by-length.html" %}}
-```html
+{{< code file="layouts/partials/by-length.html" >}}
{{ range .Data.Pages.ByLength }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Title
-{{% code file="layouts/partials/by-title.html" %}}
-```html
+{{< code file="layouts/partials/by-title.html" >}}
{{ range .Data.Pages.ByTitle }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Link Title
-{{% code file="layouts/partials/by-link-title.html" %}}
-```html
+{{< code file="layouts/partials/by-link-title.html" >}}
{{ range .Data.Pages.ByLinkTitle }}
<li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Parameter
The below example sorts a list of posts by their rating.
-{{% code file="layouts/partials/by-rating.html" %}}
-```html
+{{< code file="layouts/partials/by-rating.html" >}}
{{ range (.Data.Pages.ByParam "rating") }}
<!-- ... -->
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
If the front matter field of interest is nested beneath another field, you can
also get it:
-{{% code file="layouts/partials/by-nested-param.html" %}}
-```html
+{{< code file="layouts/partials/by-nested-param.html" >}}
{{ range (.Data.Pages.ByParam "author.last_name") }}
<!-- ... -->
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### Reverse Order
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
-{{% code file="layouts/partials/by-date-reverse.html" %}}
-```html
+{{< code file="layouts/partials/by-date-reverse.html" >}}
{{ range .Data.Pages.ByDate.Reverse }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Group Content
### By Page Field
-{{% code file="layouts/partials/by-page-field.html" %}}
-```html
+{{< code file="layouts/partials/by-page-field.html" >}}
{{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page date
-{{% code file="layouts/partials/by-page-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-date.html" >}}
{{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page publish date
-{{% code file="layouts/partials/by-page-publish-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-publish-date.html" >}}
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page Param
-{{% code file="layouts/partials/by-page-param.html" %}}
-```html
+{{< code file="layouts/partials/by-page-param.html" >}}
{{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### By Page Param in Date Format
-{{% code file="layouts/partials/by-page-param-as-date.html" %}}
-```html
+{{< code file="layouts/partials/by-page-param-as-date.html" >}}
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### Reverse Key Order
#### Reverse Method
-```html
+```
{{ range (.Data.Pages.GroupBy "Section").Reverse }}
```
-```html
+```
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
```
#### Provide the Alternate Direction
-```html
+```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
```
-```html
+```
{{ range .Data.Pages.GroupBy "Section" "desc" }}
```
In the following example, groups are ordered chronologically and then content
within each group is ordered alphabetically by title.
-{{% code file="layouts/partials/by-group-by-page.html" %}}
-```html
+{{< code file="layouts/partials/by-group-by-page.html" >}}
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3>
<ul>
{{ end }}
</ul>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
## Filter and Limiting Lists
2. `key` or `field name`
3. `match value`
-{{% code file="layouts/_default/.html" %}}
-```html
+{{< code file="layouts/_default/.html" >}}
{{ range where .Data.Pages "Section" "post" }}
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### `first`
1. `array` or `slice of maps or structs`
2. `number of elements`
-{{% code file="layout/_default/section.html" %}}
-```html
+{{< code file="layout/_default/section.html" >}}
{{ range first 10 .Data.Pages }}
{{ .Render "summary" }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### `first` and `where` Together
Using `first` and `where` together can be very powerful:
-{{% code file="first-and-where-together.html" %}}
-```html
+{{< code file="first-and-where-together.html" >}}
{{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }}
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
[views]: /templates/views/
Example in `config.toml`:
-```toml
+```
[mediaTypes]
[mediaTypes."text/enriched"]
suffix = "enr"
To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/templates/configuration/), either for all sites or for a given language.
-```toml
+```
[outputFormats.MyEnrichedFormat]
mediaType = "text/enriched"
baseName = "myindex"
Example from site `config.toml`:
-```toml
+```
[outputs]
home = ["HTML", "AMP", "RSS"]
page = ["HTML"]
Example from site `config.yml`:
-```yml
+```
outputs:
home: ["HTML", "AMP", "RSS"]
page: ["HTML"]
The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`:
-```yaml
+```
---
date: "2016-03-19"
outputs:
The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles):
-```html
+```
{{ template "_internal/pagination.html" . }}
```
The following example shows how to create `.Paginator` before its used:
-```html
+```
{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
Without the `where` filter, the above example is even simpler:
-```html
+```
{{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }}
{{ .Title }}
As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory:
-```golang
+```
{{ partial "header/site-header.html" . }}
{{ partial "footer/scripts.html" . }}
```
The following `header.html` partial template is used for [spf13.com](http://spf13.com/):
-{{% code file="layouts/partials/header.html" download="header.html" %}}
-```html
+{{< code file="layouts/partials/header.html" download="header.html" >}}
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
{{ partial "head_includes.html" . }}
</head>
<body lang="en">
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
The following `footer.html` partial template is used for [spf13.com](http://spf13.com/):
-{{% code file="layouts/partials/footer.html" download="footer.html" %}}
-```html
+{{< code file="layouts/partials/footer.html" download="footer.html" >}}
<footer>
<div>
<p>
</script>
</body>
</html>
-```
-{{% /code %}}
+{{< /code >}}
[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context."
[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order."
To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything:
-```http
+```
User-agent: *
```
The following is an example `robots.txt` layout:
-{{% code file="layouts/robots.txt" download="robots.txt" %}}
-```http
+{{< code file="layouts/robots.txt" download="robots.txt" >}}
User-agent: *
{{range .Data.Pages}}
Disallow: {{.RelPermalink}}
{{end}}
-```
-{{% /code %}}
+{{< /code >}}
This template disallows all the pages of the site by creating one `Disallow` entry for each page.
The following values will also be included in the RSS output if specified in your site’s configuration:
-```toml
+```
languageCode = "en-us"
copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License."
This is the default RSS template that ships with Hugo. It adheres to the [RSS 2.0 Specification][RSS 2.0].
-```xml
+```
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}</title>
{{% warning "XML Header" %}}
Hugo will automatically add the following header line to this file on render. Please do *not* include this in the template as it's not valid HTML.
-```xml
+```
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
```
{{% /warning %}}
In your `header.html` template, you can specify your RSS feed in your `<head></head>` tag like this:
-```html
+```
{{ if .RSSLink }}
<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
<link href="{{ .RSSLink }}" rel="feed" type="application/rss+xml" title="{{ .Site.Title }}" />
If you reference your RSS link, be sure to specify the MIME type with `type="application/rss+xml"`.
-```html
+```
<a href="{{ .URL }}" type="application/rss+xml" target="_blank">{{ .SomeText }}</a>
```
## Example: Creating a Default Section Template
-{{% code file="layouts/_default/section.html" download="section.html" %}}
-```html
+{{< code file="layouts/_default/section.html" download="section.html" >}}
{{ define "main" }}
<main>
{{ .Content }}
{{ partial "pagination.html" . }}
</main>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
### Example: Using `.Site.GetPage`
The `.Site.GetPage` example that follows assumes the following project directory structure:
-```bash
+```
.
└── content
├── blog
`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name:
-```html
+```
<h1>{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}</h1>
```
Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result:
-```html
+```
<h1>My Hugo Blog</h1>
```
If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter:
-```html
+```
<h1>{{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}</h1>
```
Which then returns the following:
-```html
+```
<h1>Events</h1>
```
---
-title: Creating Your Own Shortcodes
+title: Create Your Own Shortcodes
linktitle: Shortcode Templates
description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
date: 2017-02-01
To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
-```golang
+```
{{ .Get "class" }}
```
To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
-```golang
+```
{{ .Get 0 }}
```
`with` is great when the output depends on a parameter being set:
-```golang
+```
{{ with .Get "class"}} class="{{.}}"{{ end }}
```
`.Get` can also be used to check if a parameter has been provided. This is
most helpful when the condition depends on either of the values, or both:
-```golang
+```
{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
```
A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax:
-```golang
+```
{{</* innershortcode /*/>}}
```
For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
-```md
+```
{{</* image src="images/my-image.jpg"*/>}}
```
You could then include the following as part of your shortcode templating:
-```html
+```
{{ if .IsNamedParams }}
<img src="{{.Get "src" alt="">
{{ else }}
Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows:
-```markdown
+```
{{</* year */>}}
```
-{{% code file="/layouts/shortcodes/year.html" %}}
-```golang
+{{< code file="/layouts/shortcodes/year.html" >}}
{{ .Page.Now.Year }}
-```
-{{% /code %}}
+{{< /code >}}
### Single Positional Example: `youtube`
Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
-```golang
+```
{{</* youtube 09jf3ow9jfw */>}}
```
Would load the template at `/layouts/shortcodes/youtube.html`:
-{{% code file="/layouts/shortcodes/youtube.html" %}}
-```html
+{{< code file="/layouts/shortcodes/youtube.html" >}}
<div class="embed video-player">
<iframe class="youtube-player" type="text/html" width="640" height="385" src="http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
</iframe>
</div>
-```
-{{% /code %}}
+{{< /code >}}
-{{% code file="youtube-embed.html" copy="false" %}}
-```html
+{{< code file="youtube-embed.html" copy="false" >}}
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
width="640" height="385"
allowfullscreen frameborder="0">
</iframe>
</div>
-```
-{{% /code %}}
+{{< /code >}}
### Single Named Example: `image`
Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
-{{% code file="content-image.md" %}}
-```golang
+{{< code file="content-image.md" >}}
{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
-```
-{{% /code %}}
+{{< /code >}}
You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
-{{% code file="/layouts/shortcodes/img.html" %}}
-```html
+{{< code file="/layouts/shortcodes/img.html" >}}
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }}
{{ end }}
</figure>
<!-- image -->
-```
-{{% /code %}}
+{{< /code >}}
Would be rendered as:
-{{% code file="img-output.html" copy="false" %}}
-```html
+{{< code file="img-output.html" copy="false" >}}
<figure >
<img src="/media/spf13.jpg" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
-```
-{{% /code %}}
+{{< /code >}}
### Single Flexible Example: `vimeo`
-```golang
+```
{{</* vimeo 49718712 */>}}
{{</* vimeo id="49718712" class="flex-video" */>}}
```
Would load the template found at `/layouts/shortcodes/vimeo.html`:
-{{% code file="/layouts/shortcodes/vimeo.html" %}}
-```html
+{{< code file="/layouts/shortcodes/vimeo.html" >}}
{{ if .IsNamedParams }}
<div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
<iframe src="//player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
<iframe src="//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
</div>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
Would be rendered as:
-{{% code file="vimeo-iframes.html" copy="false" %}}
-```html
+{{< code file="vimeo-iframes.html" copy="false" >}}
<div class="vimeo-container">
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
<div class="flex-video">
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
-```
-{{% /code %}}
+{{< /code >}}
### Paired Example: `highlight`
The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
-{{% code file="highlight-example.md" %}}
-```markdown
+{{< code file="highlight-example.md" >}}
{{</* highlight html */>}}
<html>
<body> This HTML </body>
</html>
{{</* /highlight */>}}
-```
-{{% /code %}}
+{{< /code >}}
The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
-```golang
+```
{{ .Get 0 | highlight .Inner }}
```
The rendered output of the HTML example code block will be as follows:
-{{% code file="syntax-highlighted.html" copy="false" %}}
-```html
+{{< code file="syntax-highlighted.html" copy="false" >}}
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
<span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
<span style="color: #f92672"></html></span>
</pre></div>
-```
-{{% /code %}}
+{{< /code >}}
{{% note %}}
The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information.
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
-{{% code file="layouts/shortcodes/gallery.html" %}}
-```html
+{{< code file="layouts/shortcodes/gallery.html" >}}
<div class="{{.Get "class"}}">
{{.Inner}}
</div>
-```
-{{% /code %}}
+{{< /code >}}
You also have an `image` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes so that the parent defines the context of each `image`:
-{{% code file="layouts/shortcodes/image.html" %}}
-```html
+{{< code file="layouts/shortcodes/image.html" >}}
{{- $src := .Get "src" -}}
{{- with .Parent -}}
<img src="{{$src}}" class="{{.Get "class"}}-image">
{{- else -}}
<img src="{{$src}}">
{{- end }}
-```
-{{% /code %}}
+{{< /code >}}
You can then call your shortcode in your content as follows:
-```markdown
+```
{{</* gallery class="content-gallery" */>}}
{{</* img src="/images/one.jpg" */>}}
{{</* img src="/images/two.jpg" */>}}
This will output the following HTML. Note how the first two `image` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `image` only uses `src`:
-```html
+```
<div class="content-gallery">
<img src="/images/one.jpg" class="content-gallery-image">
<img src="/images/two.jpg" class="content-gallery-image">
This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
-{{% code file="layouts/post/single.html" download="single.html" %}}
-```html
+{{< code file="layouts/post/single.html" download="single.html" >}}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
</div>
</aside>
{{ end }}
-```
-{{% /code %}}
+{{< /code >}}
To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html).
-```xml
+```
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{{ range .Data.Pages }}
<url>
Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in the site's config file, e.g.:
-```toml
+```
[sitemap]
changefreq = "monthly"
priority = 0.5
### Taxonomy Terms Templates Lookup Order
-A taxonomy terms page will be rendered at `
yoursite.com/<PLURALTAXONOMYNAME>`/ (e.g., http://spf13.com/topics/) according to the following lookup order:
+A taxonomy terms page will be rendered at `
example.com/<PLURALTAXONOMYNAME>`/ (e.g., http://spf13.com/topics/) according to the following lookup order:
1. `/layouts/taxonomy/<SINGULAR>.terms.html`
2. `/layouts/_default/terms.html`
Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.
-```go
+```
[]struct {
Name string
WeightedPages WeightedPages
WeightedPages is simply a slice of WeightedPage.
-```go
+```
type WeightedPages []WeightedPage
```
### Order Alphabetically Example
-```html
+```
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Taxonomy.Alphabetical }}
### Order by Popularity Example
-```html
+```
<ul>
{{ $data := .Data }}
{{ range $key, $value := .Data.Taxonomy.ByCount }}
Content can be assigned weight for each taxonomy that it's assigned to.
-```toml
+```
+++
tags = [ "a", "b", "c" ]
tags_weight = 22
### Example: List Tags in a Single Page Template
-```html
+```
<ul id="tags">
{{ range .Params.tags }}
<li><a href="{{ "/tags/" | relLangURL }}{{ . | urlize }}">{{ . }}</a> </li>
### Example: Comma-delimit Tags in a Single Page Template
-```html
+```
{{ if .Params.directors }}
<strong>Director{{ if gt (len .Params.directors) 1 }}s{{ end }}:</strong>
{{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}<a href="{{ "directors/" | relURL }}{{ . | urlize }}">{{ . }}</a>{{ end }}
### Example: Showing Content in Same Series
-```html
+```
<ul>
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
### Example: Grouping "Featured" Content
-```html
+```
<section id="menu">
<ul>
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
### Example: List All Site Tags
-```html
+```
<ul id="all-tags">
{{ range $name, $taxonomy := .Site.Taxonomies.tags }}
<li><a href="{{ "/tags/" | relLangURL }}{{ $name | urlize }}">{{ $name }}</a></li>
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
-{{% code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" %}}
-```html
+{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
<section>
<ul id="all-taxonomies">
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
{{ end }}
</ul>
</section>
-```
-{{% /code %}}
+{{< /code >}}
## `.Site.GetPage` for Taxonomies
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above:
-{{% code file="links-to-all-tags" %}}
-```html
+{{< code file="links-to-all-tags" >}}
<ul class="tags">
{{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }}
<li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
{{ end }}
</ul>
-```
-{{% /code %}}
+{{< /code >}}
<!--### `.Site.GetPage` Taxonomy List Example
You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`.
-```html
+```
{{ printf "%#v" $.Site }}
```
This will print out the value of `.Permalink`:
-```html
+```
{{ printf "%#v" .Permalink }}
```
(`.`, aka ["the dot"][tempintro]).
-```html
+```
{{ printf "%#v" . }}
```
When developing a [homepage][], what does one of the pages you're looping through look like?
-```html
+```
{{ range .Data.Pages }}
{{/* The context, ".", is now each one of the pages as it goes through the loop */}}
{{ printf "%#v" . }}
Check that you are passing variables in the `partial` function:
-```html
+```
{{ partial "header" }}
```
This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro].
-```html
+```
{{ partial "header" . }}
```
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
-```bash
+```
▾ layouts/
▾ post/
li.html
Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order.
-```bash
+```
▾ layouts/
▾ _default/
li.html
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
-{{% code file="layouts/_default/list.html" download="list.html" %}}
-```
+{{< code file="layouts/_default/list.html" download="list.html" >}}
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ end }}
</div>
</main>
-```
-{{% /code %}}
+{{< /code >}}
### `summary.html`
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
-{{% code file="layouts/_default/summary.html" download="summary.html" %}}
-```html
+{{< code file="layouts/_default/summary.html" download="summary.html" >}}
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
</footer>
</article>
-```
-{{% /code %}}
+{{< /code >}}
### `li.html`
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
-{{% code file="layouts/_default/li.html" download="li.html" %}}
-```html
+{{< code file="layouts/_default/li.html" download="li.html" >}}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
</li>
-```
-{{% /code %}}
+{{< /code >}}
[lists]: /templates/lists/
[lookup]: /templates/lookup-order/
---
-title: Creating a Theme
-linktitle: Creating a Theme
+title: Create a Theme
+linktitle: Create a Theme
description: The `hugo new theme` command will scaffold the beginnings of a new theme for you to get you on your way.
date: 2017-02-01
publishdate: 2017-02-01
Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command:
-```bash
+```
hugo new theme [name]
```
---
-title: Customizing a Theme
-linktitle: Customizing a Theme
+title: Customize a Theme
+linktitle: Customize a Theme
description: Customize a theme by overriding theme layouts and static assets in your top-level project directories.
date: 2017-02-01
publishdate: 2017-02-01
For example, a theme may use jQuery 1.8 in the following location:
-```bash
+```
/themes/<THEME>/static/js/jquery.min.js
```
You want to replace the version of jQuery that ships with the theme with the newer `jquery-3.1.1.js`. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root. Therefore, change `jquery-3.1.1.js` to `jquery.min.js` so that it is *identical* to the theme's version and place the file here:
-```bash
+```
/static/js/jquery.min.js
```
For example:
-```bash
+```
/themes/<THEME>/layouts/_default/single.html
```
Would be overwritten by
-```bash
+```
/layouts/_default/single.html
```
---
-title: Installing and Using Themes
-linktitle: Installing and Using Themes
+title: Install and Use Themes
+linktitle: Install and Use Themes
description: Install and use a theme from the Hugo theme showcase easily through the CLI.
date: 2017-02-01
publishdate: 2017-02-01
You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while.
-```bash
+```
git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
```
Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository:
-```bash
+```
cd themes
git clone URL_TO_THEME
```
The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
-{{% code file="clone-theme.sh" %}}
-```bash
+{{< code file="clone-theme.sh" >}}
cd themes
git clone https://github.com/spf13/hyde
-```
-{{% /code %}}
+{{< /code >}}
Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site:
-```bash
+```
hugo -t themename
```
Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]:
-```bash
+```
hugo server -t themename
```
If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]:
-```yaml
+```
theme: themename
```
### Example `highlight` Shortcode Input
-{{% code file="example-highlight-shortcode-input.md" %}}
-```html
+{{< code file="example-highlight-shortcode-input.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
</div>
</section>
{{</* /highlight */>}}
-```
-{{% /code %}}
+{{< /code >}}
### Example `highlight` Shortcode Output
It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
-````
-```html
+```
+```
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
</div>
</section>
```
-````
+```
{{% note "Disclaimers on Pygments" %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages:
-```html
+```
...
<link href="/css/prism.css" rel="stylesheet" />
...
Add `prism.js` near the bottom of your `<body>` tag in whatever Hugo partial template is appropriate for your site or theme.
-```html
+```
...
<script src="/js/prism.js"></script>
</body>
The client-side highlighting script therefore looks for programming language classes according to this convention: `language-go`, `language-html`, `language-css`, `language-bash`, etc. If you look at the page's source, you might see something like the following:
-```html
+```
<pre>
<code class="language-css">
body {
Here is the same example but with triple back ticks to denote the fenced code block:
{{< nohighlight >}}
-```css
+```
body {
font-family: "Noto Sans", sans-serif;
}
In the case of the coding color scheme used by the Hugo docs, the resulting output would then look like the following to the website's end users:
-```css
+```
body {
font-family: "Noto Sans", sans-serif;
}
---
-title: Troubleshooting
-linktitle: Troubleshooting
+title: Troubleshoot
+linktitle: Troubleshoot
description: Frequently asked questions and known issues pulled from the Hugo Discuss forum.
date: 2017-02-01
publishdate: 2017-02-01
> One of my categories is named "Le-carré," but the link ends up being generated like this:
>
-> ```bash
+> ```
> categories/le-carr%C3%A9
> ```
>
>
> When I run Hugo with v0.12 via `hugo new -v showcase/test.md`, I see the following output:
>
-> ```bash
+> ```
> INFO: 2015/01/04 Using config file: /private/tmp/test/config.toml
> INFO: 2015/01/04 attempting to create showcase/test.md of showcase
> INFO: 2015/01/04 curpath: /private/tmp/test/archetypes/showcase.md
Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
-```yaml
+```
---
title: My First Post
date: date: 2017-02-20T15:26:23-06:00
The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
-```yaml
+```
---
...
affiliatelink: "http://www.my-book-link.here"
Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
-{{% code file="/themes/yourtheme/layouts/review/single.html" %}}
-```html
+{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
<p>It was recommended by {{ .Params.recommendedby }}.</p>
-```
-{{% /code %}}
+{{< /code >}}
This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
{{% output file="yourbaseurl/review/book01/index.html" %}}
-```html
+```
<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
<p>It was recommended by my Mother.</p>
```
In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image):
-```golang
+```
{{ $.Param "header_image" }}
```
When front matter contains nested fields like the following:
-```yaml
+```
---
author:
given_name: John
The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`:
-```golang
+```
{{ $.Param "favorites.flavor" }}
=> vanilla
```
The following `config.toml` defines a site-wide param for `description`:
-```toml
+```
baseURL = "http://yoursite.example.com/"
[params]
You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
-{{% code file="layouts/partials/head.html" %}}
-```html
+{{< code file="layouts/partials/head.html" >}}
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
-```
-{{% /code %}}
+{{< /code >}}
[config]: /getting-started/configuration/
\ No newline at end of file
The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates].
-{{% code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" %}}
-```html
+{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}}
<section>
<ul>
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
{{ end }}
</ul>
</section>
-```
-{{% /code %}}
+{{< /code >}}
[partials]: /templates/partials/
[taxonomytemplates]: /templates/taxonomy-templates/
\ No newline at end of file
-<div class="code relative bg-primary-color moon-gray" id="{{.Get "file" | urlize}}">
- {{- with .Get "file" -}}
+{{ $file := .Get "file" }}
+{{ $isHTML := strings.HasSuffix $file "html" }}
+<div class="code relative bg-primary-color" id="{{ $file | urlize}}">
+ {{- with $file -}}
<div class="filename san-serif f6 dib lh-solid pl2 pv2">{{.}}</div>
{{- end -}}
{{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}}
{{end}}
<div class="code-copy-content nt3" {{with .Get "download"}}id="{{.}}"{{end}}>
- {{- .Inner -}}
+ {{ if $isHTML }}{{- highlight .Inner "html" "" | -}}{{ else }}<pre><code>{{- .Inner | string -}}</code></pre>{{ end }}
</div>
</div>
--- /dev/null
+Pygments==2.1.3
-Subproject commit 18141c496f18ac74bfef480403b4bbb69c44bbbe
+Subproject commit d0445e2ad6bcffcbfa305650dd66e308543bcfdc
projects / brevno-suite / hugo / commitdiff