tiennm99/hugoDocs
1
0 Fork 0
mirror of https://github.com/tiennm99/hugoDocs.git synced 2026-10-13 22:16:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove the code fence language codes

Browse Source 
See #61
This commit is contained in:
Bjørn Erik Pedersen committed 2017-07-20 11:51:45 +02:00
1 parent 1473b1d91a
commit a1b2fd3bdc
118 files changed
+643 -643
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/content-management/archetypes.md
+10 -10
View File
@@ -31,14 +31,14 @@ See above
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: 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> hugo new <content-section>/<file-name.md>
``` ```
We can use this pattern to create a new `.md` file in the `posts` section: We can use this pattern to create a new `.md` file in the `posts` section:
{{% code file="archetype-example.sh" %}} {{% code file="archetype-example.sh" %}}
```bash ```
hugo new posts/my-first-post.md hugo new posts/my-first-post.md
``` ```
{{% /code %}} {{% /code %}}
@@ -50,7 +50,7 @@ To override the content type Hugo infers from `[content-section]`, add the `--ki
Running this command in a new site that does not have default or custom archetypes will create the following file: 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" %}} {{% output file="content/posts/my-first-post.md" %}}
```toml ```
+++ +++
date = "2017-02-01T19:20:04-07:00" date = "2017-02-01T19:20:04-07:00"
title = "my first post" title = "my first post"
@@ -101,7 +101,7 @@ When you create a new Hugo project using `hugo new site`, you'll notice that Hug
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. 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" %}} {{% code file="archetypes/default.md" %}}
```toml ```
+++ +++
tags = ["golang", "hugo"] tags = ["golang", "hugo"]
categories = ["web development"] categories = ["web development"]
@@ -118,7 +118,7 @@ If you get an `EOF error` when using `hugo new`, add a carriage return after the
With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section: 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" %}} {{% code file="new-post-from-default.sh" %}}
```bash ```
$ hugo new posts/my-new-post.md $ hugo new posts/my-new-post.md
``` ```
{{% /code %}} {{% /code %}}
@@ -126,7 +126,7 @@ $ hugo new posts/my-new-post.md
Hugo then creates a new markdown file with the following front matter: Hugo then creates a new markdown file with the following front matter:
{{% output file="content/posts/my-new-post.md" %}} {{% output file="content/posts/my-new-post.md" %}}
```toml ```
+++ +++
categories = ["web development"] categories = ["web development"]
date = "2017-02-01T19:20:04-07:00" date = "2017-02-01T19:20:04-07:00"
@@ -149,7 +149,7 @@ Suppose your site's `posts` section requires more sophisticated front matter tha
### Create a Custom Archetype ### Create a Custom Archetype
{{% code file="archetypes/posts.md"%}} {{% code file="archetypes/posts.md"%}}
```toml ```
+++ +++
description = "" description = ""
tags = "" tags = ""
@@ -163,7 +163,7 @@ categories = ""
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: 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" %}} {{% code file="new-post-from-custom.sh" %}}
```bash ```
$ hugo new posts/post-from-custom.md $ hugo new posts/post-from-custom.md
``` ```
{{% /code %}} {{% /code %}}
@@ -171,7 +171,7 @@ $ hugo new posts/post-from-custom.md
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`: 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" %}} {{% output file="content/posts/post-from-custom-archetype.md" %}}
```toml ```
+++ +++
categories = "" categories = ""
date = 2017-02-13T17:24:43-08:00 date = 2017-02-13T17:24:43-08:00
@@ -187,7 +187,7 @@ title = "post from custom archetype"
As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs: As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
{{% code file="archetypes/functions.md" %}} {{% code file="archetypes/functions.md" %}}
```yaml ```
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}} {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}}
``` ```
{{% /code %}} {{% /code %}}
content/content-management/authors.md
+8 -8
View File
@@ -31,7 +31,7 @@ You can create a profile containing metadata for each author on your website. Th
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: 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" %}} {{% code file="data/_authors/alice.toml" %}}
```toml ```
givenName = "Alice" # or firstName as alias givenName = "Alice" # or firstName as alias
familyName = "Allison" # or lastName as alias familyName = "Allison" # or lastName as alias
displayName = "Alice Allison" displayName = "Alice Allison"
@@ -67,7 +67,7 @@ The `params` section can contain arbitrary data much like the same-named section
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. 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 title: Why Hugo is so Awesome
date: 2016-08-22T14:27:502:00 date: 2016-08-22T14:27:502:00
@@ -77,7 +77,7 @@ authors: ["alice"]
Nothing to read here. Move along... Nothing to read here. Move along...
``` ```
```toml ```
+++ +++
title = Why Hugo is so Awesome title = Why Hugo is so Awesome
date = "2016-08-22T14:27:502:00" date = "2016-08-22T14:27:502:00"
@@ -117,7 +117,7 @@ This is can be done with the `.Social.URL` function. Its only parameter is the n
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: 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" %}} {{% code file="layouts/partials/author-info.html" download="author-info.html" %}}
```html ```
{{ with .Author }} {{ with .Author }}
<h3>{{ .DisplayName }}</h3> <h3>{{ .DisplayName }}</h3>
<img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}"> <img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
@@ -137,12 +137,12 @@ That question can be answered with a list of all authors and another list contai
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: 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: taxonomies:
author: authors author: authors
``` ```
```toml ```
[taxonomies] [taxonomies]
author = "authors" author = "authors"
``` ```
@@ -153,7 +153,7 @@ taxonomies:
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. 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" %}} {{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}}
```html ```
<ul> <ul>
{{ range $author, $v := .Data.Terms }} {{ range $author, $v := .Data.Terms }}
{{ $profile := $.Authors.Get $author }} {{ $profile := $.Authors.Get $author }}
@@ -176,7 +176,7 @@ Last but not least, we have to create the second list that contains all publicat
The layout for this page can be defined in the template `layouts/taxonomy/author.html`. The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
{{% code file="layouts/taxonomy/author.html" download="author.html" %}} {{% code file="layouts/taxonomy/author.html" download="author.html" %}}
```html ```
{{ range .Data.Pages }} {{ range .Data.Pages }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2> <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
<span>written by {{ .Author.DisplayName }}</span> <span>written by {{ .Author.DisplayName }}</span>
content/content-management/comments.md
+2 -2
View File
@@ -29,11 +29,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
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: 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" disqusShortname = "yourdiscussshortname"
``` ```
```yaml ```
disqusShortname: "yourdiscussshortname" disqusShortname: "yourdiscussshortname"
``` ```
content/content-management/cross-references.md
+8 -8
View File
@@ -20,7 +20,7 @@ toc: true
## Use `ref` and `relref` ## Use `ref` and `relref`
```md ```
{{</* ref "document" */>}} {{</* ref "document" */>}}
{{</* ref "#anchor" */>}} {{</* ref "#anchor" */>}}
{{</* ref "document#anchor" */>}} {{</* ref "document#anchor" */>}}
@@ -35,14 +35,14 @@ The single parameter to `ref` is a string with a content `documentname` (e.g., `
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: 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 "blog/post.md" */>}} => `/blog/post/`
{{</* relref "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: 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 └── content
├── events ├── events
@@ -58,7 +58,7 @@ If you have the same filename used across multiple sections, you should only use
To be sure to get the correct reference in this case, use the full path: To be sure to get the correct reference in this case, use the full path:
{{% code file="content/meta/my-article.md" copy="false" %}} {{% code file="content/meta/my-article.md" copy="false" %}}
```md ```
{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/ {{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
``` ```
{{% /code %}} {{% /code %}}
@@ -66,7 +66,7 @@ To be sure to get the correct reference in this case, use the full path:
{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}} {{< 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 (`/`). A relative document name must *not* begin with a slash (`/`).
```md ```
{{</* relref "/events/my-birthday.md" */>}} => "" {{</* relref "/events/my-birthday.md" */>}} => ""
``` ```
@@ -82,14 +82,14 @@ If the page exists in multiple [output formats][], `ref` or `relref` can be used
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: 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 "#anchors" */>}} => #anchors:9decaf7
{{</* relref "about-hugo/hugo-features.md#content" */>}} => /blog/post/#who:badcafe {{</* 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 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 "#who" */>}} => #who:9decaf7
{{</* relref "blog/post.md#who" */>}} => /blog/post/#who:badcafe {{</* relref "blog/post.md#who" */>}} => /blog/post/#who:badcafe
``` ```
@@ -113,7 +113,7 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi
`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.) `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" */>}} {{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
``` ```
content/content-management/formats.md
+6 -6
View File
@@ -42,7 +42,7 @@ Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Bl
#### Example Task List Input #### Example Task List Input
{{% code file="content/my-to-do-list.md" %}} {{% code file="content/my-to-do-list.md" %}}
```markdown ```
- [ ] a task list item - [ ] a task list item
- [ ] list syntax required - [ ] list syntax required
- [ ] incomplete - [ ] incomplete
@@ -54,7 +54,7 @@ Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Bl
The preceding markdown produces the following HTML in your rendered website: The preceding markdown produces the following HTML in your rendered website:
```html ```
<ul class="task-list"> <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"> a task list item</li>
<li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li> <li><input type="checkbox" disabled="" class="task-list-item"> list syntax required</li>
@@ -98,7 +98,7 @@ As Hugo ships with Mmark, using the syntax is as easy as changing the extension
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: 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 title: My Post
date: 2017-04-01 date: 2017-04-01
@@ -121,7 +121,7 @@ This is not an introduction into actually using MathJax to render typeset mathem
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)): 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" %}} {{% code file="add-mathjax-to-page.html" %}}
```html ```
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"> <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script> </script>
``` ```
@@ -150,7 +150,7 @@ There are multiple ways to remedy this problem. One solution is to simply escape
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). 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" %}} {{% code file="mathjax-markdown-solution.html" %}}
```js ```
<script type="text/x-mathjax-config"> <script type="text/x-mathjax-config">
MathJax.Hub.Config({ MathJax.Hub.Config({
tex2jax: { tex2jax: {
@@ -184,7 +184,7 @@ MathJax.Hub.Config({
As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.
{{% code file="mathjax-style.css" %}} {{% code file="mathjax-style.css" %}}
```css ```
code.has-jax { code.has-jax {
font: inherit; font: inherit;
font-size: 100%; font-size: 100%;
content/content-management/front-matter.md
+4 -4
View File
@@ -34,7 +34,7 @@ JSON
### TOML Example ### TOML Example
```toml ```
+++ +++
title = "spf13-vim 3.0 release and new website" title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
@@ -50,7 +50,7 @@ slug = "spf13-vim-3-0-release-and-new-website"
### YAML Example ### YAML Example
```yaml ```
--- ---
title: "spf13-vim 3.0 release and new website" title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
@@ -66,7 +66,7 @@ slug: "spf13-vim-3-0-release-and-new-website"
### JSON Example ### JSON Example
```json ```
{ {
"title": "spf13-vim 3.0 release and new website", "title": "spf13-vim 3.0 release and new website",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
@@ -154,7 +154,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us
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. 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 include_toc: true
show_comments: false show_comments: false
``` ```
content/content-management/menus.md
+5 -5
View File
@@ -88,7 +88,7 @@ If all you need to do is add an entry to a menu, the simple form works well.
#### A Single Menu #### A Single Menu
```yaml ```
--- ---
menu: "main" menu: "main"
--- ---
@@ -96,7 +96,7 @@ menu: "main"
#### Multiple Menus #### Multiple Menus
```yaml ```
--- ---
menu: ["main", "footer"] menu: ["main", "footer"]
--- ---
@@ -105,7 +105,7 @@ menu: ["main", "footer"]
#### Advanced #### Advanced
```yaml ```
--- ---
menu: menu:
docs: docs:
@@ -121,7 +121,7 @@ You can also add entries to menus that aren’t attached to a piece of content.
Here’s an example snippet pulled from a `config.toml`: Here’s an example snippet pulled from a `config.toml`:
{{% code file="config.toml" %}} {{% code file="config.toml" %}}
```toml ```
[[menu.main]] [[menu.main]]
name = "about hugo" name = "about hugo"
pre = "<i class='fa fa-heart'></i>" pre = "<i class='fa fa-heart'></i>"
@@ -139,7 +139,7 @@ Here’s an example snippet pulled from a `config.toml`:
Here's the equivalent snippet in a `config.yaml`: Here's the equivalent snippet in a `config.yaml`:
{{% code file="config.yml" %}} {{% code file="config.yml" %}}
```yaml ```
--- ---
menu: menu:
docs: docs:
content/content-management/multilingual.md
+7 -7
View File
@@ -24,7 +24,7 @@ You should define the available languages in a `Languages` section in your site
The following is an example of a TOML site configuration for a multilingual Hugo project: The following is an example of a TOML site configuration for a multilingual Hugo project:
{{% code file="config.toml" download="config.toml" %}} {{% code file="config.toml" download="config.toml" %}}
```toml ```
DefaultContentLanguage = "en" DefaultContentLanguage = "en"
copyright = "Everything is mine" copyright = "Everything is mine"
@@ -67,7 +67,7 @@ Taxonomies and [Blackfriday configuration][config] can also be set per language:
{{% code file="bf-config.toml" %}} {{% code file="bf-config.toml" %}}
```toml ```
[Taxonomies] [Taxonomies]
tag = "tags" tag = "tags"
@@ -110,7 +110,7 @@ By having the same *base filename*, the content pieces are linked together as tr
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: 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" slug: "a-propos"
``` ```
@@ -128,7 +128,7 @@ We will fix this in https://github.com/gohugoio/hugo/issues/2699
To create a list of links to translated content, use a template similar to the following: To create a list of links to translated content, use a template similar to the following:
{{% code file="layouts/partials/i18nlist.html" %}} {{% code file="layouts/partials/i18nlist.html" %}}
```html ```
{{ if .IsTranslated }} {{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4> <h4>{{ i18n "translations" }}</h4>
<ul> <ul>
@@ -191,7 +191,7 @@ And then in the template:
``` ```
To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: To track down missing translation strings, run Hugo with the `--i18n-warnings` flag:
```bash ```
hugo --i18n-warnings | grep i18n hugo --i18n-warnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount i18n|MISSING_TRANSLATION|en|wordCount
``` ```
@@ -229,7 +229,7 @@ This technique extracts the day, month and year by specifying ``.Date.Day``, ``.
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: 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" defaultContentLanguage = "en"
[languages.en] [languages.en]
@@ -254,7 +254,7 @@ weight = 0
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. 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> <ul>
{{- $currentPage := . -}} {{- $currentPage := . -}}
{{ range .Site.Menus.main -}} {{ range .Site.Menus.main -}}
content/content-management/organization.md
+8 -8
View File
@@ -56,7 +56,7 @@ The following demonstrates the relationships between your content organization a
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: 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 . url
. ⊢--^-⊣ . ⊢--^-⊣
. path slug . path slug
@@ -68,7 +68,7 @@ content/posts/_index.md
At build, this will output to the following destination with the associated values: At build, this will output to the following destination with the associated values:
```bash ```
url ("/posts/") url ("/posts/")
⊢-^-⊣ ⊢-^-⊣
@@ -84,7 +84,7 @@ http://yoursite.com/posts/index.html
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`: 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") path ("posts/my-first-hugo-post.md")
. ⊢-----------^------------⊣ . ⊢-----------^------------⊣
. section slug . section slug
@@ -94,7 +94,7 @@ content/posts/my-first-hugo-post.md
At the time Hugo builds your site, the content will be output to the following destination: At the time Hugo builds your site, the content will be output to the following destination:
```bash ```
url ("/posts/my-first-hugo-post/") url ("/posts/my-first-hugo-post/")
⊢------------^----------⊣ ⊢------------^----------⊣
@@ -110,7 +110,7 @@ http://yoursite.com/posts/my-first-hugo-post/index.html
To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site: 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 section
⊢--^--⊣ ⊢--^--⊣
url url
@@ -173,7 +173,7 @@ This isn't in the front matter, but is the actual name of the file minus the ext
When defined in the front matter, the `slug` can take the place of the filename for the destination. 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" %}} {{% code file="content/posts/old-post.md" %}}
```yaml ```
--- ---
title: New Post title: New Post
slug: "new-post" slug: "new-post"
@@ -196,7 +196,7 @@ yoursite.com/posts/new-post/
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. 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" %}} {{% code file="content/posts/my-post.md" %}}
```yaml ```
--- ---
title: My Post title: My Post
type: new type: new
@@ -214,7 +214,7 @@ layout: mylayout
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: 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" %}} {{% code file="content/posts/old-url.md" %}}
```yaml ```
--- ---
title: Old URL title: Old URL
url: /blog/new-url/ url: /blog/new-url/
content/content-management/sections.md
+1 -1
View File
@@ -30,7 +30,7 @@ Following this pattern, Hugo uses the top level of your content organization as
The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts": The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts":
```bash ```
. .
└── content └── content
├── authors ├── authors
content/content-management/shortcodes.md
+29 -29
View File
@@ -38,11 +38,11 @@ Some shortcodes use or require closing shortcodes. Again like HTML, the opening
Here are two examples of paired shortcodes: Here are two examples of paired shortcodes:
```md ```
{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} {{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
``` ```
```md ```
{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}} {{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
``` ```
@@ -52,7 +52,7 @@ The examples above use two different delimiters, the difference being the `%` ch
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>`: 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 */%}} {{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}}
``` ```
@@ -60,7 +60,7 @@ The `%` character indicates that the shortcode's inner content---called in the [
The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: 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 */>}} {{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
``` ```
@@ -90,7 +90,7 @@ The `figure` shortcode can use the following named parameters:
#### Example `figure` Input #### Example `figure` Input
{{% code file="figure-input-example.md" %}} {{% code file="figure-input-example.md" %}}
```markdown ```
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}} {{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -98,7 +98,7 @@ The `figure` shortcode can use the following named parameters:
#### Example `figure` Output #### Example `figure` Output
{{% output file="figure-output-example.html" %}} {{% output file="figure-output-example.html" %}}
```html ```
<figure> <figure>
<img src="/media/spf13.jpg" /> <img src="/media/spf13.jpg" />
<figcaption> <figcaption>
@@ -112,13 +112,13 @@ The `figure` shortcode can use the following named parameters:
Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]: 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 https://gist.github.com/spf13/7896402
``` ```
We can embed the gist in our content via username and gist ID pulled from the URL: We can embed the gist in our content via username and gist ID pulled from the URL:
```md ```
{{</* gist spf13 7896402 */>}} {{</* gist spf13 7896402 */>}}
``` ```
@@ -127,7 +127,7 @@ We can embed the gist in our content via username and gist ID pulled from the UR
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: 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" %}} {{% code file="gist-input.md" %}}
```md ```
{{</* gist spf13 7896402 "img.html" */>}} {{</* gist spf13 7896402 "img.html" */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -135,7 +135,7 @@ If the gist contains several files and you want to quote just one of them, you c
#### Example `gist` Output #### Example `gist` Output
{{% output file="gist-output.html" %}} {{% output file="gist-output.html" %}}
```html ```
{{< gist spf13 7896402 >}} {{< gist spf13 7896402 >}}
``` ```
{{% /output %}} {{% /output %}}
@@ -153,7 +153,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
#### Example `highlight` Input #### Example `highlight` Input
{{% code file="content/tutorials/learn-html.md" %}} {{% code file="content/tutorials/learn-html.md" %}}
```html ```
{{</* highlight html */>}} {{</* highlight html */>}}
<section id="main"> <section id="main">
<div> <div>
@@ -172,7 +172,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
The `highlight` shortcode example above would produce the following HTML when the site is rendered: The `highlight` shortcode example above would produce the following HTML when the site is rendered:
{{% output file="tutorials/learn-html/index.html" %}} {{% output file="tutorials/learn-html/index.html" %}}
```html ```
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span> <span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span> <span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span> <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
@@ -192,14 +192,14 @@ To see even more options for adding syntax-highlighted code blocks to your websi
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: 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/ https://www.instagram.com/p/BWNjjyYFxVx/
``` ```
#### Example `instagram` Input #### Example `instagram` Input
{{% code file="instagram-input.md" %}} {{% code file="instagram-input.md" %}}
```md ```
{{</* instagram BWNjjyYFxVx */>}} {{</* instagram BWNjjyYFxVx */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -207,7 +207,7 @@ https://www.instagram.com/p/BWNjjyYFxVx/
You also have the option to hide the caption: You also have the option to hide the caption:
{{% code file="instagram-input-hide-caption.md" %}} {{% code file="instagram-input-hide-caption.md" %}}
```md ```
{{</* instagram BWNjjyYFxVx hidecaption */>}} {{</* instagram BWNjjyYFxVx hidecaption */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -217,7 +217,7 @@ You also have the option to hide the caption:
By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup: 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" %}} {{% output file="instagram-hide-caption-output.html" %}}
```html ```
{{< instagram BWNjjyYFxVx hidecaption >}} {{< instagram BWNjjyYFxVx hidecaption >}}
``` ```
{{% /output %}} {{% /output %}}
@@ -243,7 +243,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references
#### Example `ref` and `relref` Input #### Example `ref` and `relref` Input
```md ```
[Neat]({{</* ref "blog/neat.md" */>}}) [Neat]({{</* ref "blog/neat.md" */>}})
[Who]({{</* relref "about.md#who" */>}}) [Who]({{</* relref "about.md#who" */>}})
``` ```
@@ -252,7 +252,7 @@ Read a more extensive description of `ref` and `relref` in the [cross references
Assuming that standard Hugo pretty URLs are turned on. Assuming that standard Hugo pretty URLs are turned on.
```html ```
<a href="/blog/neat">Neat</a> <a href="/blog/neat">Neat</a>
<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a> <a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
``` ```
@@ -261,7 +261,7 @@ Assuming that standard Hugo pretty URLs are turned on.
To embed slides from [Speaker Deck][], click on "&lt;&#8239;/&gt;&nbsp;Embed" (under Share right next to the template on Speaker Deck) and copy the URL: To embed slides from [Speaker Deck][], click on "&lt;&#8239;/&gt;&nbsp;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> <script async class="speakerdeck-embed" data-id="4e8126e72d853c0060001f97" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
``` ```
@@ -270,7 +270,7 @@ To embed slides from [Speaker Deck][], click on "&lt;&#8239;/&gt;&nbsp;Embed" (u
Extract the value from the field `data-id` and pass it to the shortcode: Extract the value from the field `data-id` and pass it to the shortcode:
{{% code file="speakerdeck-example-input.md" %}} {{% code file="speakerdeck-example-input.md" %}}
```md ```
{{</* speakerdeck 4e8126e72d853c0060001f97 */>}} {{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -278,7 +278,7 @@ Extract the value from the field `data-id` and pass it to the shortcode:
#### `speakerdeck` Example Output #### `speakerdeck` Example Output
{{% output file="speakerdeck-example-input.md" %}} {{% output file="speakerdeck-example-input.md" %}}
```html ```
{{< speakerdeck 4e8126e72d853c0060001f97 >}} {{< speakerdeck 4e8126e72d853c0060001f97 >}}
``` ```
{{% /output %}} {{% /output %}}
@@ -302,7 +302,7 @@ https://twitter.com/spf13/status/877500564405444608
Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode: Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
{{% code file="example-tweet-input.md" %}} {{% code file="example-tweet-input.md" %}}
```md ```
{{</* tweet 877500564405444608 */>}} {{</* tweet 877500564405444608 */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -312,7 +312,7 @@ Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup: Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
{{% output file="example-tweet-output.html" %}} {{% output file="example-tweet-output.html" %}}
```html ```
{{< tweet 877500564405444608 >}} {{< tweet 877500564405444608 >}}
``` ```
{{% /output %}} {{% /output %}}
@@ -336,7 +336,7 @@ https://vimeo.com/channels/staffpicks/146022717
Extract the ID from the video's URL and pass it to the `vimeo` shortcode: Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
{{% code file="example-vimeo-input.md" %}} {{% code file="example-vimeo-input.md" %}}
```md ```
{{</* vimeo 146022717 */>}} {{</* vimeo 146022717 */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -346,7 +346,7 @@ Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup: Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
{{% output file="example-vimeo-output.html" %}} {{% output file="example-vimeo-output.html" %}}
```html ```
{{< vimeo 146022717 >}} {{< vimeo 146022717 >}}
``` ```
{{% /output %}} {{% /output %}}
@@ -354,7 +354,7 @@ Using the preceding `vimeo` example, the following HTML will be added to your re
{{% tip %}} {{% 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. 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" */>}} {{</* vimeo id="146022717" class="my-vimeo-wrapper-class" */>}}
``` ```
{{% /tip %}} {{% /tip %}}
@@ -379,7 +379,7 @@ https://www.youtube.com/watch?v=w7Ft2ymGmfc
Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode: 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" %}} {{% code file="example-youtube-input.md" %}}
```md ```
{{</* youtube w7Ft2ymGmfc */>}} {{</* youtube w7Ft2ymGmfc */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -388,7 +388,7 @@ Furthermore, you can automatically start playback of the embedded video by setti
{{% code file="example-youtube-input-with-autoplay.md" %}} {{% code file="example-youtube-input-with-autoplay.md" %}}
```md ```
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}} {{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
``` ```
{{% /code %}} {{% /code %}}
@@ -398,7 +398,7 @@ Furthermore, you can automatically start playback of the embedded video by setti
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup: Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
{{% code file="example-youtube-output.html" %}} {{% code file="example-youtube-output.html" %}}
```html ```
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}} {{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
``` ```
{{% /code %}} {{% /code %}}
content/content-management/summaries.md
+1 -1
View File
@@ -57,7 +57,7 @@ Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly
You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][]. 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" %}} {{% code file="page-list-with-summaries.html" %}}
```html ```
{{ range first 10 .Data.Pages }} {{ range first 10 .Data.Pages }}
<article> <article>
<!-- this <div> includes the title summary --> <!-- this <div> includes the title summary -->
content/content-management/taxonomies.md
+8 -8
View File
@@ -86,7 +86,7 @@ Hugo natively supports taxonomies.
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: 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"] disableKinds = ["taxonomy","taxonomyTerm"]
``` ```
@@ -103,7 +103,7 @@ Taxonomies must be defined in your [website configuration][config] before they c
### Example: TOML Taxonomy Configuration ### Example: TOML Taxonomy Configuration
```toml ```
[taxonomies] [taxonomies]
tag = "tags" tag = "tags"
category = "categories" category = "categories"
@@ -112,7 +112,7 @@ Taxonomies must be defined in your [website configuration][config] before they c
### Example: YAML Taxonomy Configuration ### Example: YAML Taxonomy Configuration
```yaml ```
taxonomies: taxonomies:
tag: "tags" tag: "tags"
category: "categories" category: "categories"
@@ -145,7 +145,7 @@ If you would like the ability to quickly generate content files with preconfigur
### Example: TOML Front Matter with Taxonomies ### Example: TOML Front Matter with Taxonomies
```toml ```
+++ +++
title = "Hugo: A fast and flexible static site generator" title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ] tags = [ "Development", "Go", "fast", "Blogging" ]
@@ -158,7 +158,7 @@ project_url = "https://github.com/gohugoio/hugo"
### Example: YAML Front Matter with Taxonomies ### Example: YAML Front Matter with Taxonomies
```yaml ```
--- ---
title: "Hugo: A fast and flexible static site generator" title: "Hugo: A fast and flexible static site generator"
#tags: ["Development", "Go", "fast", "Blogging"] #tags: ["Development", "Go", "fast", "Blogging"]
@@ -171,7 +171,7 @@ project_url: "https://github.com/gohugoio/hugo"
### Example: JSON Front Matter with Taxonomies ### Example: JSON Front Matter with Taxonomies
```json ```
{ {
"title": "Hugo: A fast and flexible static site generator", "title": "Hugo: A fast and flexible static site generator",
"tags": [ "tags": [
@@ -199,7 +199,7 @@ The following TOML and YAML examples show a piece of content that has a weight o
### Example: TOML Taxonomic `weight` ### Example: TOML Taxonomic `weight`
```toml ```
+++ +++
title = "foo" title = "foo"
tags = [ "a", "b", "c" ] tags = [ "a", "b", "c" ]
@@ -211,7 +211,7 @@ categories_weight = 44
### Example: YAML Taxonomic `weight` ### Example: YAML Taxonomic `weight`
```yaml ```
--- ---
title: foo title: foo
#tags: [ "a", "b", "c" ] #tags: [ "a", "b", "c" ]
content/content-management/toc.md
+3 -3
View File
@@ -25,7 +25,7 @@ Currently, the `{{.TableOfContents}}` [page variable](/variables/page/) does not
Create your markdown the way you normally would with the appropriate headings. Here is some example content: Create your markdown the way you normally would with the appropriate headings. Here is some example content:
```md ```
<!-- Your front matter up here --> <!-- Your front matter up here -->
## Introduction ## Introduction
@@ -50,7 +50,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
The following is an example of a very basic [single page template][]: The following is an example of a very basic [single page template][]:
{{% code file="layout/_default/single.html" download="single.html" %}} {{% code file="layout/_default/single.html" download="single.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<main> <main>
<article> <article>
@@ -72,7 +72,7 @@ The following is an example of a very basic [single page template][]:
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: 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" %}} {{% code file="layouts/partials/toc.html" download="toc.html" %}}
```html ```
{{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }} {{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }}
<aside> <aside>
<header> <header>
content/content-management/types.md
+1 -1
View File
@@ -45,7 +45,7 @@ Remember, all of the following are *optional*. If you do not specifically declar
The following examples take you stepwise through creating a new type layout for a content file that contains the following front matter: 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" %}} {{% code file="content/events/my-first-event.md" copy="false" %}}
```toml ```
+++ +++
title = My First Event title = My First Event
date = "2016-06-24T19:20:04-07:00" date = "2016-06-24T19:20:04-07:00"
content/content-management/urls.md
+11 -11
View File
@@ -32,7 +32,7 @@ For example, if one of your [sections][] is called `post` and you want to adjust
### YAML Permalinks Configuration Example ### YAML Permalinks Configuration Example
{{% code file="config.yml" copy="false" %}} {{% code file="config.yml" copy="false" %}}
```yaml ```
permalinks: permalinks:
post: /:year/:month/:title/ post: /:year/:month/:title/
``` ```
@@ -41,7 +41,7 @@ permalinks:
### TOML Permalinks Configuration Example ### TOML Permalinks Configuration Example
{{% code file="config.toml" copy="false" %}} {{% code file="config.toml" copy="false" %}}
```toml ```
[permalinks] [permalinks]
post = "/:year/:month/:title/" post = "/:year/:month/:title/"
``` ```
@@ -99,7 +99,7 @@ Let's assume you create a new piece of content at `content/posts/my-awesome-blog
#### TOML Front Matter #### TOML Front Matter
{{% code file="content/posts/my-awesome-post.md" copy="false" %}} {{% code file="content/posts/my-awesome-post.md" copy="false" %}}
```toml ```
+++ +++
aliases = [ aliases = [
"/posts/my-original-url/", "/posts/my-original-url/",
@@ -112,7 +112,7 @@ aliases = [
#### YAML Front Matter #### YAML Front Matter
{{% code file="content/posts/my-awesome-post.md" copy="false" %}} {{% code file="content/posts/my-awesome-post.md" copy="false" %}}
```yaml ```
--- ---
aliases: aliases:
- /posts/my-original-url/ - /posts/my-original-url/
@@ -129,7 +129,7 @@ On [multilingual sites][multilingual], each translation of a post can have uniqu
In `/posts/my-new-post.es.md`: In `/posts/my-new-post.es.md`:
```yaml ```
--- ---
aliases: aliases:
- /es/posts/my-original-post/ - /es/posts/my-original-post/
@@ -142,7 +142,7 @@ When aliases are specified, Hugo creates a directory to match the alias entry. I
For example, a content file at `posts/my-intended-url.md` with the following in the front matter: For example, a content file at `posts/my-intended-url.md` with the following in the front matter:
```yaml ```
--- ---
title: My New post title: My New post
aliases: [/posts/my-old-url/] aliases: [/posts/my-old-url/]
@@ -151,7 +151,7 @@ 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 `yoursite.com`, the contents of the auto-generated alias `.html` found at `https://yoursite.com/posts/my-old-url/ will contain the following:`
```html ```
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
@@ -189,7 +189,7 @@ Hugo's default behavior is to render your content with "pretty" URLs. No non-sta
The following demonstrates the concept: The following demonstrates the concept:
```bash ```
content/posts/_index.md content/posts/_index.md
=> yoursite.com/posts/index.html => yoursite.com/posts/index.html
content/posts/post-1.md content/posts/post-1.md
@@ -204,7 +204,7 @@ If you want a specific piece of content to have an exact URL, you can specify th
See [Content Organization][contentorg] for more details on paths. See [Content Organization][contentorg] for more details on paths.
```bash ```
. .
└── content └── content
└── about └── about
@@ -221,7 +221,7 @@ See [Content Organization][contentorg] for more details on paths.
Here's the same organization run with `hugo --uglyURLs`: Here's the same organization run with `hugo --uglyURLs`:
```bash ```
. .
└── content └── content
└── about └── about
@@ -253,7 +253,7 @@ In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was s
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. 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 hugo config | grep -i canon
``` ```
content/contribute/development.md
+27 -27
View File
@@ -46,13 +46,13 @@ If you are having trouble following the installation guides for go, check out [G
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: 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 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: 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 go version go1.8 darwin/amd64
``` ```
@@ -60,7 +60,7 @@ Next, make sure that you set up your `GOPATH` [as described in the installation
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.: 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 /Users/<yourusername>/Code/go
``` ```
@@ -69,7 +69,7 @@ You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty strin
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: 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" %}} {{% code file="install-go.sh" %}}
```bash ```
brew install go brew install go
``` ```
{{% /code %}} {{% /code %}}
@@ -106,19 +106,19 @@ Hub is a great tool for working with GitHub. The main site for it is [hub.github
On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh): On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
```sh ```
brew install hub 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`: 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 echo "alias git='hub'" >> ~/.bash_profile
``` ```
Confirm the installation: Confirm the installation:
```sh ```
git version 2.6.3 git version 2.6.3
hub version 2.2.2 hub version 2.2.2
``` ```
@@ -137,7 +137,7 @@ We're going to clone the [master Hugo repository](https://github.com/gohugoio/hu
So, let's clone that master repository: So, let's clone that master repository:
```sh ```
go get -v -u github.com/gohugoio/hugo go get -v -u github.com/gohugoio/hugo
``` ```
@@ -159,13 +159,13 @@ Now open your fork repository on GitHub and copy the remote url of your fork. Yo
Switch back to the terminal and move into the directory of the cloned master repository from the last step. 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 cd $GOPATH/src/github.com/gohugoio/hugo
``` ```
Now Git needs to know that our fork exists by adding the copied remote url: 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> git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
``` ```
@@ -173,7 +173,7 @@ git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy: Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
```sh ```
git fork git fork
``` ```
@@ -183,13 +183,13 @@ That command will log in to GitHub using your account, create a fork of the repo
Let's check if everything went right by listing all known remotes: Let's check if everything went right by listing all known remotes:
```sh ```
git remote -v git remote -v
``` ```
The output should look similar: The output should look similar:
```sh ```
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch) digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push) digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
origin https://github.com/gohugoio/hugo (fetch) origin https://github.com/gohugoio/hugo (fetch)
@@ -204,14 +204,14 @@ You should never develop against the "master" branch. The development team will
First, you should always pull the latest changes from the master repository: First, you should always pull the latest changes from the master repository:
```sh ```
git checkout master git checkout master
git pull git pull
``` ```
Now we can create a new branch for your additions: Now we can create a new branch for your additions:
```sh ```
git checkout -b <BRANCH-NAME> git checkout -b <BRANCH-NAME>
``` ```
@@ -229,7 +229,7 @@ We have developed a [separate Hugo documentation contribution guide][docscontrib
While making changes in the codebase it's a good idea to build the binary to test them: 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 go build -o hugo main.go
``` ```
@@ -241,13 +241,13 @@ Make sure the commands `go test ./...` passes, and `go build` completes.
### Formatting ### 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: 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 ./... 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): 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 # Add all changed files
git add --all git add --all
git commit --message "YOUR COMMIT MESSAGE" git commit --message "YOUR COMMIT MESSAGE"
@@ -265,20 +265,20 @@ If you are unsure what a command does leave the commit as it is. We can fix your
Let's say you want to modify the last commit message. Run the following command and replace the current 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" git commit --amend -m"YOUR NEW COMMIT MESSAGE"
``` ```
Take a look at the commit log to see the change: Take a look at the commit log to see the change:
```sh ```
git log git log
# Exit with q # 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: 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 add --all
git commit --amend git commit --amend
``` ```
@@ -291,13 +291,13 @@ Modifications such as those described in this section can have serious unintende
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. 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 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: 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 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix pick f0dbf2c tpl: Add the other test case for hasPrefix
@@ -310,7 +310,7 @@ In the case above we should merge the last to commits in the commit of this tuto
All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short: 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 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix pick f0dbf2c tpl: Add the other test case for hasPrefix
@@ -323,7 +323,7 @@ We also want to rewrite the commits message of the third last commit. We forgot
You should end up with a similar setup: You should end up with a similar setup:
```sh ```
pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
pick aaee038 tpl: Sort the smoke tests pick aaee038 tpl: Sort the smoke tests
pick f0dbf2c tpl: Add the other test case for hasPrefix pick f0dbf2c tpl: Add the other test case for hasPrefix
@@ -336,7 +336,7 @@ Close the editor. It should open again with a new tab. A text is instructing you
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: 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>. Successfully rebased and updated refs/heads/<BRANCHNAME>.
``` ```
@@ -346,7 +346,7 @@ Check the commit log if everything looks as expected. Should an error occur you
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. 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> git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
``` ```
content/contribute/documentation.md
+25 -25
View File
@@ -24,7 +24,7 @@ It's best to make changes to the Hugo docs on your local machine to check for co
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: 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 git checkout -b jon-doe-showcase-addition
``` ```
@@ -53,7 +53,7 @@ hugo new functions/newfunction.md
The archetype for `functions` according to the Hugo theme is as follows: The archetype for `functions` according to the Hugo theme is as follows:
{{% code file="archetypes/functions.md" %}} {{% code file="archetypes/functions.md" %}}
```yaml ```
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md">}} {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md">}}
``` ```
{{% /code %}} {{% /code %}}
@@ -105,7 +105,7 @@ hugo new tutorials/my-new-tutorial.md
The archetype for the `tutorials` content type is as follows: The archetype for the `tutorials` content type is as follows:
{{% code file="archetypes/tutorials.md" %}} {{% code file="archetypes/tutorials.md" %}}
```yaml ```
{{< readfile file="/themes/gohugoioTheme/archetypes/tutorials.md">}} {{< readfile file="/themes/gohugoioTheme/archetypes/tutorials.md">}}
``` ```
{{% /code %}} {{% /code %}}
@@ -120,11 +120,11 @@ Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax
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`. 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> <h1>Hello world!</h1>
``` ```
```` ```
### Code Block Shortcode ### Code Block Shortcode
@@ -138,13 +138,13 @@ With the `code` shortcodes, *you must include triple back ticks and a language d
`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern: `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" */%}} {{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
```language ```
A whole bunch of coding going on up in here! A whole bunch of coding going on up in here!
``` ```
{{%/* /code */%}} {{%/* /code */%}}
```` ```
The following are the arguments passed into `code`: The following are the arguments passed into `code`:
@@ -164,9 +164,9 @@ This example HTML code block tells Hugo users the following:
1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`. 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"`. 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" */%}} {{%/* code file="layouts/_default/single.html" download="single.html" */%}}
```html ```
{{ define "main" }} {{ define "main" }}
<main> <main>
<article> <article>
@@ -186,14 +186,14 @@ This example HTML code block tells Hugo users the following:
{{ end }} {{ end }}
``` ```
{{%/* /code */%}} {{%/* /code */%}}
```` ```
##### Example 'code' Display ##### Example 'code' Display
The output of this example will render to the Hugo docs as follows: The output of this example will render to the Hugo docs as follows:
{{% code file="layouts/_default/single.html" download="single.html" %}} {{% code file="layouts/_default/single.html" download="single.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<main> <main>
<article> <article>
@@ -218,19 +218,19 @@ The output of this example will render to the Hugo docs as follows:
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: 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" */%}} {{%/* output file="post/my-first-post/index.html" */%}}
```html ```
<h1>This is my First Hugo Blog Post</h1> <h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p> <p>I am excited to be using Hugo.</p>
``` ```
{{%/* /output */%}} {{%/* /output */%}}
```` ```
The preceding `output` example will render as follows to the Hugo docs: The preceding `output` example will render as follows to the Hugo docs:
{{% output file="post/my-first-post/index.html" %}} {{% output file="post/my-first-post/index.html" %}}
```html ```
<h1>This is my First Hugo Blog Post</h1> <h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p> <p>I am excited to be using Hugo.</p>
``` ```
@@ -240,7 +240,7 @@ The preceding `output` example will render as follows to the Hugo docs:
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]: 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. > Without the threat of punishment, there is no joy in flight.
``` ```
@@ -250,7 +250,7 @@ The preceding blockquote will render as follows in the Hugo docs:
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: 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) > Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
``` ```
@@ -277,7 +277,7 @@ Use the `note` shortcode when you want to draw attention to information subtly.
#### Example `note` Input #### Example `note` Input
{{% code file="note-with-heading.md" %}} {{% code file="note-with-heading.md" %}}
```markdown ```
{{%/* note */%}} {{%/* note */%}}
Here is a piece of information I would like to draw your **attention** to. Here is a piece of information I would like to draw your **attention** to.
{{%/* /note */%}} {{%/* /note */%}}
@@ -287,7 +287,7 @@ Here is a piece of information I would like to draw your **attention** to.
#### Example `note` Output #### Example `note` Output
{{% output file="note-with-heading.html" %}} {{% output file="note-with-heading.html" %}}
```html ```
{{% note %}} {{% note %}}
Here is a piece of information I would like to draw your **attention** to. Here is a piece of information I would like to draw your **attention** to.
{{% /note %}} {{% /note %}}
@@ -307,7 +307,7 @@ Use the `tip` shortcode when you want to give the reader advice. `tip`, like `no
#### Example `tip` Input #### Example `tip` Input
{{% code file="using-tip.md" %}} {{% code file="using-tip.md" %}}
```markdown ```
{{%/* tip */%}} {{%/* tip */%}}
Here's a bit of advice to improve your productivity with Hugo. Here's a bit of advice to improve your productivity with Hugo.
{{%/* /tip */%}} {{%/* /tip */%}}
@@ -317,7 +317,7 @@ Here's a bit of advice to improve your productivity with Hugo.
#### Example `tip` Output #### Example `tip` Output
{{% output file="tip-output.html" %}} {{% output file="tip-output.html" %}}
```html ```
{{% tip %}} {{% tip %}}
Here's a bit of advice to improve your productivity with Hugo. Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}} {{% /tip %}}
@@ -337,7 +337,7 @@ Use the `warning` shortcode when you want to draw the user's attention to someth
#### Example `warning` Input #### Example `warning` Input
{{% code file="warning-admonition-input.md" %}} {{% code file="warning-admonition-input.md" %}}
```markdown ```
{{%/* warning */%}} {{%/* warning */%}}
This is a warning, which should be reserved for *important* information like breaking changes. This is a warning, which should be reserved for *important* information like breaking changes.
{{%/* /warning */%}} {{%/* /warning */%}}
@@ -347,7 +347,7 @@ This is a warning, which should be reserved for *important* information like bre
#### Example `warning` Output #### Example `warning` Output
{{% output file="warning-admonition-output.html" %}} {{% output file="warning-admonition-output.html" %}}
```html ```
{{% warning %}} {{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes. This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}} {{% /warning %}}
content/contribute/themes.md
+3 -3
View File
@@ -60,7 +60,7 @@ The easiest way to add your theme is to [open up a new issue in the theme reposi
`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: `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" %}} {{% code file="theme.toml" download="theme.toml" %}}
```toml ```
name = "" name = ""
license = "MIT" license = "MIT"
licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md" licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
@@ -84,7 +84,7 @@ min_version = 0.19
The following fields are required: The following fields are required:
```toml ```
name = "Hyde" name = "Hyde"
license = "MIT" license = "MIT"
licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md" licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md"
@@ -134,7 +134,7 @@ Your theme's README file should be written in markdown and saved at the root of
You can download the following `README.md` as an outline: You can download the following `README.md` as an outline:
{{% code file="README.md" download="README.md" %}} {{% code file="README.md" download="README.md" %}}
```markdown ```
# Theme Title # Theme Title
content/functions/GetPage.md
+1 -1
View File
@@ -52,7 +52,7 @@ This code snippet---in the form of a [partial template][partials]---allows you t
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content. 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" %}} {{% code file="grab-top-two-tags.html" %}}
```html ```
<ul class="most-popular-tags"> <ul class="most-popular-tags">
{{ $t := $.Site.GetPage "taxonomyTerm" "tags" }} {{ $t := $.Site.GetPage "taxonomyTerm" "tags" }}
{{ range first 2 $t.Data.Terms.ByCount }} {{ range first 2 $t.Data.Terms.ByCount }}
content/functions/abslangurl.md
+1 -1
View File
@@ -22,7 +22,7 @@ Both `absLangURL` and [`relLangURL`](/functions/rellangurl/) are similar to thei
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://yoursite.com/hugo/` and the current language is `en`:
```golang ```
{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/" {{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/" {{ "blog/" | relLangURL }} → "/hugo/en/blog/"
``` ```
content/functions/absurl.md
+2 -2
View File
@@ -20,7 +20,7 @@ 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://yoursite.com/hugo/`:
```golang ```
{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css" {{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css" {{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/" {{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
@@ -30,7 +30,7 @@ Both `absURL` and `relURL` consider the configured value of `baseURL` in your si
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: 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" %}} {{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
```html ```
<script type="application/ld+json"> <script type="application/ld+json">
{ {
"@context" : "http://schema.org", "@context" : "http://schema.org",
content/functions/adddate.md
+2 -2
View File
@@ -25,7 +25,7 @@ The `AddDate` function takes three arguments in logical order of `years`, `month
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.--- 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]] [[tweet]]
name = "Steve Francia" name = "Steve Francia"
twitter_handle = "@spf13" twitter_handle = "@spf13"
@@ -37,7 +37,7 @@ date = "2017-01-07T00:00:00Z"
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. 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" %}} {{% code file="partials/templates/random-tweets.html" download="tweets.html" %}}
```html ```
{{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }} {{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }}
<div class="item"> <div class="item">
<blockquote> <blockquote>
content/functions/after.md
+2 -2
View File
@@ -20,7 +20,7 @@ aliases: []
The following shows `after` being used in conjunction with the [`slice` function][slice]: The following shows `after` being used in conjunction with the [`slice` function][slice]:
```html ```
{{ $data := slice "one" "two" "three" "four" }} {{ $data := slice "one" "two" "three" "four" }}
{{ range after 2 $data }} {{ range after 2 $data }}
{{ . }} {{ . }}
@@ -36,7 +36,7 @@ You can use `after` in combination with the [`first` function][] and Hugo's [pow
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles. 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" %}} {{% code file="layouts/section/articles.html" download="articles.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<section class="row featured-article"> <section class="row featured-article">
<h2>Featured Article</h2> <h2>Featured Article</h2>
content/functions/apply.md
+7 -7
View File
@@ -31,7 +31,7 @@ aliases: []
Here is an example of a content file with `name:` as a front matter field: Here is an example of a content file with `name:` as a front matter field:
```toml ```
+++ +++
names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ] names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
+++ +++
@@ -39,7 +39,7 @@ names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
You can then use `apply` as follows: You can then use `apply` as follows:
```golang ```
{{ apply .Params.names "urlize" "." }} {{ apply .Params.names "urlize" "." }}
``` ```
@@ -51,7 +51,7 @@ Which will result as follows:
This is *roughly* equivalent to using the following with [range][] This is *roughly* equivalent to using the following with [range][]
```golang ```
{{ range .Params.names }}{{ . | urlize }}{{ end }} {{ range .Params.names }}{{ . | urlize }}{{ end }}
``` ```
@@ -60,7 +60,7 @@ However, it isn’t possible to provide the output of a range to the [`delimit`
If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively: 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" %}} {{% code file="layouts/partial/post-tag-list.html" copy="false" %}}
```html ```
{{ with .Params.tags }} {{ with .Params.tags }}
<div class="tags-list"> <div class="tags-list">
Tags: Tags:
@@ -80,7 +80,7 @@ If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *
{{% /code %}} {{% /code %}}
{{% code file="layouts/partial/post-tag-link.html" copy="false" %}} {{% code file="layouts/partial/post-tag-link.html" copy="false" %}}
```html ```
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a> <a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
``` ```
{{% /code %}} {{% /code %}}
@@ -89,7 +89,7 @@ This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo
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: 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 }} {{ with .Params.tags }}
<div class="tags-list"> <div class="tags-list">
Tags: Tags:
@@ -104,7 +104,7 @@ This first version of `layouts/partials/post-tag-list.html` separates all of the
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: 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" %}} {{% code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" %}}
```html ```
{{ with .Params.tags }} {{ with .Params.tags }}
<div class="tags-list"> <div class="tags-list">
Tags: Tags:
content/functions/base64.md
+3 -3
View File
@@ -22,14 +22,14 @@ aliases: []
An example: An example:
{{% code file="base64-input.html" %}} {{% code file="base64-input.html" %}}
```html ```
<p>Hello world = {{ "Hello world" | base64Encode }}</p> <p>Hello world = {{ "Hello world" | base64Encode }}</p>
<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p> <p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
``` ```
{{% /code %}} {{% /code %}}
{{% output file="base-64-output.html" %}} {{% output file="base-64-output.html" %}}
```html ```
<p>Hello world = SGVsbG8gd29ybGQ=</p> <p>Hello world = SGVsbG8gd29ybGQ=</p>
<p>SGVsbG8gd29ybGQ = Hello world</p> <p>SGVsbG8gd29ybGQ = Hello world</p>
``` ```
@@ -47,7 +47,7 @@ You can also pass other data types as arguments to the template function which t
Using base64 to decode and encode becomes really powerful if we have to handle Using base64 to decode and encode becomes really powerful if we have to handle
responses from APIs. responses from APIs.
```golang ```
{{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }} {{ $resp := getJSON "https://api.github.com/repos/gohugoio/hugo/readme" }}
{{ $resp.content | base64Decode | markdownify }} {{ $resp.content | base64Decode | markdownify }}
``` ```
content/functions/chomp.md
+1 -1
View File
@@ -19,6 +19,6 @@ deprecated: false
Useful in a pipeline to remove newlines added by other processing (e.g., [`markdownify`](/functions/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>" {{chomp "<p>Blockhead</p>\n"}} → "<p>Blockhead</p>"
``` ```
content/functions/countrunes.md
+1 -1
View File
@@ -20,7 +20,7 @@ aliases: [/functions/countrunes/,/functions/countwords/]
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. 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 }} {{ "Hello, 世界" | countrunes }}
<!-- outputs a content length of 8 runes. --> <!-- outputs a content length of 8 runes. -->
``` ```
content/functions/countwords.md
+1 -1
View File
@@ -20,7 +20,7 @@ aliases: [/functions/countrunes/,/functions/countwords/]
The template function works similar to the [.WordCount page variable][pagevars]. The template function works similar to the [.WordCount page variable][pagevars].
```html ```
{{ "Hugo is a static site generator." | countwords }} {{ "Hugo is a static site generator." | countwords }}
<!-- outputs a content length of 6 words. --> <!-- outputs a content length of 6 words. -->
``` ```
content/functions/default.md
+7 -7
View File
@@ -32,7 +32,7 @@ needsexamples: false
`default` function examples reference the following content page: `default` function examples reference the following content page:
{{% code file="content/posts/default-function-example.md" %}} {{% code file="content/posts/default-function-example.md" %}}
```yaml ```
--- ---
title: Sane Defaults title: Sane Defaults
seo_title: seo_title:
@@ -46,7 +46,7 @@ newparam:
`default` can be written in more than one way: `default` can be written in more than one way:
```golang ```
{{ index .Params "font" | default "Roboto" }} {{ index .Params "font" | default "Roboto" }}
{{ default "Roboto" (index .Params "font") }} {{ default "Roboto" (index .Params "font") }}
``` ```
@@ -56,7 +56,7 @@ Both of the above `default` function calls return `Roboto`.
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: 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" %}} {{% code file="variable-as-default-value.html" nocopy="true" %}}
```golang ```
{{$old := .Params.oldparam }} {{$old := .Params.oldparam }}
<p>{{ .Params.newparam | default $old }}</p> <p>{{ .Params.newparam | default $old }}</p>
``` ```
@@ -71,7 +71,7 @@ Which would return:
And then using dot notation And then using dot notation
{{% code file="dot-notation-default-value.html" %}} {{% code file="dot-notation-default-value.html" %}}
```golang ```
<title>{{ .Params.seo_title | default .Title }}</title> <title>{{ .Params.seo_title | default .Title }}</title>
``` ```
{{% /code %}} {{% /code %}}
@@ -79,7 +79,7 @@ And then using dot notation
Which would return Which would return
{{% output file="dot-notation-default-return-value.html" %}} {{% output file="dot-notation-default-return-value.html" %}}
```html ```
<title>Sane Defaults</title> <title>Sane Defaults</title>
``` ```
{{% /output %}} {{% /output %}}
@@ -89,7 +89,7 @@ The following have equivalent return values but are far less terse. This demonst
Using `if`: Using `if`:
{{% code file="if-instead-of-default.html" nocopy="true" %}} {{% code file="if-instead-of-default.html" nocopy="true" %}}
```golang ```
<title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title> <title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title>
=> Sane Defaults => Sane Defaults
``` ```
@@ -98,7 +98,7 @@ Using `if`:
Using `with`: Using `with`:
{{% code file="with-instead-of-default.html" nocopy="true" %}} {{% code file="with-instead-of-default.html" nocopy="true" %}}
```golang ```
<title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title> <title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title>
=> Sane Defaults => Sane Defaults
``` ```
content/functions/delimit.md
+5 -5
View File
@@ -34,7 +34,7 @@ To maintain a consistent output order, maps will be sorted by keys and only a sl
The examples of `delimit` that follow all use the same front matter: The examples of `delimit` that follow all use the same front matter:
{{% code file="delimit-example-front-matter.toml" nocopy="true" %}} {{% code file="delimit-example-front-matter.toml" nocopy="true" %}}
```toml ```
+++ +++
title: I love Delimit title: I love Delimit
#tags: [ "tag1", "tag2", "tag3" ] #tags: [ "tag1", "tag2", "tag3" ]
@@ -43,13 +43,13 @@ title: I love Delimit
{{% /code %}} {{% /code %}}
{{% code file="delimit-page-tags-input.html" %}} {{% code file="delimit-page-tags-input.html" %}}
```html ```
<p>Tags: {{ delimit .Params.tags ", " }}</p> <p>Tags: {{ delimit .Params.tags ", " }}</p>
``` ```
{{% /code %}} {{% /code %}}
{{% output file="delimit-page-tags-output.html" %}} {{% output file="delimit-page-tags-output.html" %}}
```html ```
<p>Tags: tag1, tag2, tag3</p> <p>Tags: tag1, tag2, tag3</p>
``` ```
{{% /output %}} {{% /output %}}
@@ -57,13 +57,13 @@ title: I love Delimit
Here is the same example but with the optional "last" delimiter: Here is the same example but with the optional "last" delimiter:
{{% code file="delimit-page-tags-final-and-input.html" %}} {{% code file="delimit-page-tags-final-and-input.html" %}}
```golang ```
Tags: {{ delimit .Params.tags ", " ", and " }} Tags: {{ delimit .Params.tags ", " ", and " }}
``` ```
{{% /code %}} {{% /code %}}
{{% output file="delimit-page-tags-final-and-output.html" %}} {{% output file="delimit-page-tags-final-and-output.html" %}}
```html ```
<p>Tags: tag1, tag2, and tag3</p> <p>Tags: tag1, tag2, and tag3</p>
``` ```
{{% /output %}} {{% /output %}}
content/functions/dict.md
+2 -2
View File
@@ -27,7 +27,7 @@ aliases: []
The partial below creates a SVG and expects `fill` `height` and `width` from the caller: 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" %}} {{% code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" %}}
```xml ```
<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"> <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> <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> </svg>
@@ -37,7 +37,7 @@ The partial below creates a SVG and expects `fill` `height` and `width` from the
These values can be stored in one object with `dict` and passed to the partial: These values can be stored in one object with `dict` and passed to the partial:
{{% code file="layouts/_default/list.html" %}} {{% code file="layouts/_default/list.html" %}}
```html ```
{{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" 10 "width" 20 ) }} {{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" 10 "width" 20 ) }}
``` ```
{{% /code %}} {{% /code %}}
content/functions/findRe.md
+1 -1
View File
@@ -29,7 +29,7 @@ The example below returns a list of all second level headers (`<h2>`) in the con
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): 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 }} {{ findRE "<h2.*?>(.|\n)*?</h2>" .Content 1 }}
<!-- returns ["<h2 id="#foo">Foo</h2>"] --> <!-- returns ["<h2 id="#foo">Foo</h2>"] -->
``` ```
content/functions/first.md
+1 -1
View File
@@ -20,7 +20,7 @@ aliases: []
--- ---
```golang ```
{{ range first 10 .Data.Pages }} {{ range first 10 .Data.Pages }}
{{ .Render "summary" }} {{ .Render "summary" }}
{{ end }} {{ end }}
content/functions/format.md
+1 -1
View File
@@ -27,7 +27,7 @@ toc: true
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: 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 {{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017
``` ```
content/functions/i18n.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
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. 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" }} {{ i18n "translation_id" }}
``` ```
content/functions/imageConfig.md
+1 -1
View File
@@ -17,7 +17,7 @@ relatedfuncs: []
deprecated: false deprecated: false
--- ---
```golang ```
{{ with (imageConfig "favicon.ico") }} {{ with (imageConfig "favicon.ico") }}
favicon.ico: {{.Width}} x {{.Height}} favicon.ico: {{.Width}} x {{.Height}}
{{ end }} {{ end }}
content/functions/index-function.md
+4 -4
View File
@@ -44,7 +44,7 @@ Assume you want to add a `location = ""` field to your front matter for every ar
Here is an example of the data inside `data/locations/oslo.toml`: Here is an example of the data inside `data/locations/oslo.toml`:
```toml ```
website = "https://www.oslo.kommune.no" website = "https://www.oslo.kommune.no"
pop_city = 658390 pop_city = 658390
pop_metro = 1717900 pop_metro = 1717900
@@ -52,7 +52,7 @@ 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/`: 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" title = "My Norwegian Vacation"
location = "oslo" location = "oslo"
``` ```
@@ -70,14 +70,14 @@ This is where the `index` function is needed. `index` takes 2 parameters in this
The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above: The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
```golang ```
{{ index .Site.Data.authors .Params.author }} {{ index .Site.Data.authors .Params.author }}
=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900] => 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 (`.`): 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 }} {{ (index .Site.Data.locations .Params.location).pop_city }}
=> 658390 => 658390
``` ```
content/functions/intersect.md
+2 -2
View File
@@ -26,7 +26,7 @@ A useful example of `intersect` functionality is a "related posts" block. `isset
The following is an example of a "related posts" [partial template][partials] that could be added to a [single page template][single]: 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" %}} {{% code file="layouts/partials/related-posts.html" download="related-posts.html" %}}
```html ```
<ul> <ul>
{{ $page_link := .Permalink }} {{ $page_link := .Permalink }}
{{ $tags := .Params.tags }} {{ $tags := .Params.tags }}
@@ -43,7 +43,7 @@ The following is an example of a "related posts" [partial template][partials] th
This is also very useful to use as `AND` filters when combined with where: 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 := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} {{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} {{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
content/functions/len.md
+2 -2
View File
@@ -36,7 +36,7 @@ aliases: []
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>`: 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" %}} {{% code file="check-title-length.html" %}}
```html ```
<header> <header>
<h1{{if gt (len .Title) 80}} class="long-title"{{end}}>{{.Title}}</h1> <h1{{if gt (len .Title) 80}} class="long-title"{{end}}>{{.Title}}</h1>
</header> </header>
@@ -48,7 +48,7 @@ You may want to append a class to a heading according to the length of the strin
The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]: 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" %}} {{% code file="how-many-posts.html" %}}
```html ```
{{ $posts := (where .Site.RegularPages "Section" "==" "post") }} {{ $posts := (where .Site.RegularPages "Section" "==" "post") }}
{{ $postCount := len $posts }} {{ $postCount := len $posts }}
``` ```
content/functions/math.md
+3 -3
View File
@@ -37,13 +37,13 @@ You can also use the `add` function with strings. You may like this functionalit
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]: 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://yoursite.com/images/my-twitter-image.jpg">
``` ```
Let's assume you have an `image` field in the front matter of each of your content files: Let's assume you have an `image` field in the front matter of each of your content files:
```yaml ```
--- ---
title: My Post title: My Post
image: my-post-image.jpg image: my-post-image.jpg
@@ -53,7 +53,7 @@ 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: 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" %}} {{% code file="partials/head/twitter-card.html" %}}
```html ```
{{$socialimage := add "images/" .Params.image}} {{$socialimage := add "images/" .Params.image}}
<meta name="twitter:image" content="{{ $socialimage | absURL }}"> <meta name="twitter:image" content="{{ $socialimage | absURL }}">
``` ```
content/functions/md5.md
+2 -2
View File
@@ -21,13 +21,13 @@ aliases: []
```html ```
{{ md5 "Hello world, gophers!" }} {{ md5 "Hello world, gophers!" }}
<!-- returns the string "b3029f756f98f79e7f1b7f1d1f0dd53b" --> <!-- returns the string "b3029f756f98f79e7f1b7f1d1f0dd53b" -->
``` ```
This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar: 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"> <img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">
``` ```
content/functions/now.md
+2 -2
View File
@@ -23,7 +23,7 @@ See [`time.Time`](https://godoc.org/time#Time).
For example, building your site on June 24, 2017 with the following templating: For example, building your site on June 24, 2017 with the following templating:
```html ```
<div> <div>
<small>&copy; {{ now.Format "2006"}}</small> <small>&copy; {{ now.Format "2006"}}</small>
</div> </div>
@@ -31,7 +31,7 @@ For example, building your site on June 24, 2017 with the following templating:
Which will produce the following: Which will produce the following:
```html ```
<div> <div>
<small>&copy; 2017</small> <small>&copy; 2017</small>
</div> </div>
content/functions/partialCached.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
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: 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" . }} {{ partialCached "footer.html" . }}
``` ```
content/functions/printf.md
+1 -1
View File
@@ -20,7 +20,7 @@ deprecated: false
See [the go doc](https://golang.org/pkg/fmt/) for additional information. See [the go doc](https://golang.org/pkg/fmt/) for additional information.
```golang ```
{{ i18n ( printf "combined_%s" $var ) }} {{ i18n ( printf "combined_%s" $var ) }}
``` ```
content/functions/querify.md
+2 -2
View File
@@ -23,12 +23,12 @@ aliases: []
The following example creates a link to a search results page on Google. 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> <a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
``` ```
This example renders the following HTML: This example renders the following HTML:
```html ```
<a href="https://www.google.com?page=3&q=test">Search</a> <a href="https://www.google.com?page=3&q=test">Search</a>
``` ```
content/functions/readfile.md
+1 -1
View File
@@ -22,7 +22,7 @@ Note that the filename must be relative to the current project working directory
So, if you have a file with the name `README.txt` in the root of your project with the content `Hugo Rocks!`: 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!" {{readFile "README.txt"}} → "Hugo Rocks!"
``` ```
content/functions/ref.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
`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 "`.`"): `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" }} {{ relref . "about.md" }}
``` ```
content/functions/relLangURL.md
+1 -1
View File
@@ -22,7 +22,7 @@ aliases: []
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://yoursite.com/hugo/` and the current language is `en`:
```golang ```
{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/" {{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
{{ "blog/" | relLangURL }} → "/hugo/en/blog/" {{ "blog/" | relLangURL }} → "/hugo/en/blog/"
``` ```
content/functions/relref.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
`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 "`.`"): `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" }} {{ relref . "about.md" }}
``` ```
content/functions/relurl.md
+2 -2
View File
@@ -20,7 +20,7 @@ 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://yoursite.com/hugo/`:
```golang ```
{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css" {{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css" {{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/" {{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
@@ -30,7 +30,7 @@ Both `absURL` and `relURL` consider the configured value of `baseURL` in your si
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: 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" %}} {{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
```html ```
<script type="application/ld+json"> <script type="application/ld+json">
{ {
"@context" : "http://schema.org", "@context" : "http://schema.org",
content/functions/render.md
+1 -1
View File
@@ -25,7 +25,7 @@ This function is only available when applied to a single piece of content within
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`: This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
```golang ```
{{ range .Data.Pages }} {{ range .Data.Pages }}
{{ .Render "summary"}} {{ .Render "summary"}}
{{ end }} {{ end }}
content/functions/replacere.md
+1 -1
View File
@@ -19,7 +19,7 @@ deprecated: false
aliases: [] aliases: []
--- ---
```golang ```
{{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io" {{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io"
{{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io" {{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io"
``` ```
content/functions/safeHTML.md
+3 -3
View File
@@ -22,19 +22,19 @@ It should not be used for HTML from a third-party, or HTML with unclosed tags or
Given a site-wide [`config.toml`][config] with the following `copyright` value: 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>." 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: `{{ .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>. © 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: 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. &lt;a href=&#34;http://creativecommons.org/licenses by/4.0/&#34;&gt;Some rights reserved&lt;/a&gt;.</p> <p>© 2015 Jane Doe. &lt;a href=&#34;http://creativecommons.org/licenses by/4.0/&#34;&gt;Some rights reserved&lt;/a&gt;.</p>
``` ```
content/functions/safeHTMLAttr.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
Example: Given a site-wide `config.toml` that contains this menu entry: Example: Given a site-wide `config.toml` that contains this menu entry:
```toml ```
[[menu.main]] [[menu.main]]
name = "IRC: #golang at freenode" name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang" url = "irc://irc.freenode.net/#golang"
content/functions/safeURL.md
+5 -5
View File
@@ -25,7 +25,7 @@ Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are cons
The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]: The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
{{% code file="config.toml" copy="false" %}} {{% code file="config.toml" copy="false" %}}
```toml ```
[[menu.main]] [[menu.main]]
name = "IRC: #golang at freenode" name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang" url = "irc://irc.freenode.net/#golang"
@@ -35,7 +35,7 @@ The following examples use a [site `config.toml`][configuration] with the follow
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example: 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" %}} {{% code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" %}}
```html ```
<!-- This unordered list may be part of a sidebar menu --> <!-- This unordered list may be part of a sidebar menu -->
<ul> <ul>
{{ range .Site.Menus.main }} {{ range .Site.Menus.main }}
@@ -48,7 +48,7 @@ The following is an example of a sidebar partial that may be used in conjunction
This partial would produce the following HTML output: This partial would produce the following HTML output:
{{% output file="bad-url-sidebar-menu-output.html" %}} {{% output file="bad-url-sidebar-menu-output.html" %}}
```html ```
<!-- This unordered list may be part of a sidebar menu --> <!-- This unordered list may be part of a sidebar menu -->
<ul> <ul>
<li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li> <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
@@ -59,7 +59,7 @@ This partial would produce the following HTML output:
The odd output can be remedied by adding ` | safeURL` to our `.Title` page variable: 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" %}} {{% code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" %}}
```html ```
<!-- This unordered list may be part of a sidebar menu --> <!-- This unordered list may be part of a sidebar menu -->
<ul> <ul>
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li> <li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
@@ -70,7 +70,7 @@ The odd output can be remedied by adding ` | safeURL` to our `.Title` page varia
With the `.URL` page variable piped through `safeURL`, we get the desired output: With the `.URL` page variable piped through `safeURL`, we get the desired output:
{{% output file="correct-url-sidebar-menu-output.html" %}} {{% output file="correct-url-sidebar-menu-output.html" %}}
```html ```
<ul class="sidebar-menu"> <ul class="sidebar-menu">
<li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li> <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
</ul> </ul>
content/functions/seq.md
+2 -2
View File
@@ -34,14 +34,14 @@ It's named and used in the model of [GNU's seq][].
You can use `seq` in combination with `range` and `after`. The following will return 19 elements: You can use `seq` in combination with `range` and `after`. The following will return 19 elements:
```golang ```
{{ range after 1 (seq 20)}} {{ range after 1 (seq 20)}}
{{ end }} {{ end }}
``` ```
However, when ranging with an index, the following may be less confusing in that `$indexStartingAt1` and `$num` will return `1,2,3 ... 20`: 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) }} {{ range $index, $num := (seq 20) }}
$indexStartingAt1 := (add $index 1) $indexStartingAt1 := (add $index 1)
{{ end }} {{ end }}
content/functions/sha.md
+2 -2
View File
@@ -21,14 +21,14 @@ aliases: []
`sha1` hashes the given input and returns its SHA1 checksum. `sha1` hashes the given input and returns its SHA1 checksum.
```html ```
{{ sha1 "Hello world, gophers!" }} {{ sha1 "Hello world, gophers!" }}
<!-- returns the string "c8b5b0e33d408246e30f53e32b8f7627a7a649d4" --> <!-- returns the string "c8b5b0e33d408246e30f53e32b8f7627a7a649d4" -->
``` ```
`sha256` hashes the given input and returns its SHA256 checksum. `sha256` hashes the given input and returns its SHA256 checksum.
```html ```
{{ sha256 "Hello world, gophers!" }} {{ sha256 "Hello world, gophers!" }}
<!-- returns the string "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46" --> <!-- returns the string "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46" -->
``` ```
content/functions/shuffle.md
+2 -2
View File
@@ -21,7 +21,7 @@ aliases: []
--- ---
{{% code file="shuffle-input.html" %}} {{% code file="shuffle-input.html" %}}
```html ```
<!-- Shuffled sequence = --> <!-- Shuffled sequence = -->
<div>{{ shuffle (seq 1 5) }}</div> <div>{{ shuffle (seq 1 5) }}</div>
<!-- Shuffled slice = --> <!-- Shuffled slice = -->
@@ -32,7 +32,7 @@ aliases: []
This example would return the following: This example would return the following:
{{% output file="shuffle-output.html" %}} {{% output file="shuffle-output.html" %}}
```html ```
<!-- Shuffled sequence = --> <!-- Shuffled sequence = -->
<div>2 5 3 1 4</div> <div>2 5 3 1 4</div>
<!-- Shuffled slice = --> <!-- Shuffled slice = -->
content/functions/slice.md
+1 -1
View File
@@ -24,7 +24,7 @@ toc: false
One use case is the concatenation of elements in combination with the [`delimit` function][]: One use case is the concatenation of elements in combination with the [`delimit` function][]:
{{% code file="slice.html" %}} {{% code file="slice.html" %}}
```html ```
{{ delimit (slice "foo" "bar" "buzz") ", " }} {{ delimit (slice "foo" "bar" "buzz") ", " }}
<!-- returns the string "foo, bar, buzz" --> <!-- returns the string "foo, bar, buzz" -->
``` ```
content/functions/sort.md
+1 -1
View File
@@ -21,7 +21,7 @@ aliases: []
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. 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" ] #tags: [ "tag3", "tag1", "tag2" ]
+++ +++
content/functions/time.md
+1 -1
View File
@@ -34,7 +34,7 @@ The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"`
The following example may be useful when setting up [multilingual sites][multilingual]: The following example may be useful when setting up [multilingual sites][multilingual]:
{{% code file="unix-to-month-integer.html" %}} {{% code file="unix-to-month-integer.html" %}}
```html ```
{{$time := time (int .Params.addDate)}} {{$time := time (int .Params.addDate)}}
=> $time = 1489276800 => $time = 1489276800
{{$time.Month}} {{$time.Month}}
content/functions/union.md
+2 -2
View File
@@ -21,7 +21,7 @@ aliases: []
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). 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) }} {{ union (slice 1 2 3) (slice 3 4 5) }}
<!-- returns [1 2 3 4 5] --> <!-- returns [1 2 3 4 5] -->
@@ -38,7 +38,7 @@ Given two arrays (or slices) A and B, this function will return a new array that
This is also very useful to use as `OR` filters when combined with where: 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 := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} {{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} {{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
content/functions/uniq.md
+1 -1
View File
@@ -20,7 +20,7 @@ aliases: []
needsexamples: false needsexamples: false
--- ---
```html ```
{{ uniq (slice 1 2 3 2) }} {{ uniq (slice 1 2 3 2) }}
{{ slice 1 2 3 2 | uniq }} {{ slice 1 2 3 2 | uniq }}
<!-- both return [1 2 3] --> <!-- both return [1 2 3] -->
content/functions/unix.md
+1 -1
View File
@@ -24,7 +24,7 @@ aliases: []
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. 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" %}} {{% code file="time-passed.html" %}}
```golang ```
{{ div (sub now.Unix .Lastmod.Unix) 86400 }} {{ div (sub now.Unix .Lastmod.Unix) 86400 }}
``` ```
{{% /code %}} {{% /code %}}
content/functions/urlize.md
+3 -3
View File
@@ -21,7 +21,7 @@ relatedfuncs: []
The following examples pull from a content file with the following front matter: The following examples pull from a content file with the following front matter:
{{% code file="content/blog/greatest-city.md" copy="false"%}} {{% code file="content/blog/greatest-city.md" copy="false"%}}
```toml ```
+++ +++
title = "The World's Greatest City" title = "The World's Greatest City"
location = "Chicago IL" location = "Chicago IL"
@@ -33,7 +33,7 @@ tags = ["pizza","beer","hot dogs"]
The following might be used as a partial within a [single page template][singletemplate]: 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" %}} {{% code file="layouts/partials/content-header.html" download="content-header.html" %}}
```html ```
<header> <header>
<h1>{{.Title}}</h1> <h1>{{.Title}}</h1>
{{ with .Params.location }} {{ with .Params.location }}
@@ -56,7 +56,7 @@ The following might be used as a partial within a [single page template][singlet
The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs. 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" %}} {{% output file="/blog/greatest-city/index.html" %}}
```html ```
<header> <header>
<h1>The World's Greatest City</h1> <h1>The World's Greatest City</h1>
<div><a href="/locations/chicago-il/">Chicago IL</a></div> <div><a href="/locations/chicago-il/">Chicago IL</a></div>
content/functions/where.md
+9 -9
View File
@@ -22,7 +22,7 @@ needsexample: true
`where` filters an array to only the elements containing a matching value for a given field. `where` filters an array to only the elements containing a matching value for a given field.
```html ```
{{ range where .Data.Pages "Section" "post" }} {{ range where .Data.Pages "Section" "post" }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -30,13 +30,13 @@ needsexample: true
It can be used by dot-chaining the second argument to refer to a nested element of a value. It can be used by dot-chaining the second argument to refer to a nested element of a value.
```toml ```
+++ +++
series: golang series: golang
+++ +++
``` ```
```html ```
{{ range where .Site.Pages "Params.series" "golang" }} {{ range where .Site.Pages "Params.series" "golang" }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -44,7 +44,7 @@ series: golang
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 `=`. 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" }} {{ range where .Data.Pages "Section" "!=" "post" }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -81,7 +81,7 @@ The following logical operators are vailable with `where`:
## Use `where` with `intersect` ## Use `where` with `intersect`
```html ```
{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }} {{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }}
{{ if ne .Permalink $.Permalink }} {{ if ne .Permalink $.Permalink }}
{{ .Render "summary" }} {{ .Render "summary" }}
@@ -92,7 +92,7 @@ The following logical operators are vailable with `where`:
You can also put the returned value of the `where` clauses into a variable: You can also put the returned value of the `where` clauses into a variable:
{{% code file="where-intersect-variables.html" %}} {{% code file="where-intersect-variables.html" %}}
```html ```
{{ $v1 := where .Site.Pages "Params.a" "v1" }} {{ $v1 := where .Site.Pages "Params.a" "v1" }}
{{ $v2 := where .Site.Pages "Params.b" "v2" }} {{ $v2 := where .Site.Pages "Params.b" "v2" }}
{{ $filtered := $v1 | intersect $v2 }} {{ $filtered := $v1 | intersect $v2 }}
@@ -106,7 +106,7 @@ You can also put the returned value of the `where` clauses into a variable:
The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`): 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" %}} {{% code file="where-with-first.html" %}}
```html ```
{{ range first 5 (where .Data.Pages "Section" "post") }} {{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -117,7 +117,7 @@ The following grabs the first five content files in `post` using the [default or
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: 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" }} {{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }}
``` ```
@@ -132,7 +132,7 @@ Only the following operators are available for `nil`
* `=`, `==`, `eq`: True if the given field is not set. * `=`, `==`, `eq`: True if the given field is not set.
* `!=`, `<>`, `ne`: True if the given field is set. * `!=`, `<>`, `ne`: True if the given field is set.
```html ```
{{ range where .Data.Pages ".Params.specialpost" "!=" nil }} {{ range where .Data.Pages ".Params.specialpost" "!=" nil }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
content/functions/with.md
+1 -1
View File
@@ -23,7 +23,7 @@ An alternative way of writing an `if` statement and then referencing the same va
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: 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" %}} {{% code file="layouts/partials/twitter.html" %}}
```html ```
{{with .Site.Params.twitteruser}}<span class="twitter"> {{with .Site.Params.twitteruser}}<span class="twitter">
<a href="https://twitter.com/{{.}}" rel="author"> <a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" <img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
content/getting-started/configuration.md
+9 -9
View File
@@ -37,7 +37,7 @@ In your `config` file, you can direct Hugo as to how you want your website rende
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][]: 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"%}} {{% code file="config.yml"%}}
```yaml ```
--- ---
baseURL: "https://yoursite.example.com/" baseURL: "https://yoursite.example.com/"
title: "My Hugo Site" title: "My Hugo Site"
@@ -61,7 +61,7 @@ params:
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. 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" %}} {{% code file="config.yml" download="config.yml" %}}
```yaml ```
--- ---
archetypeDir: "archetypes" archetypeDir: "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/ # hostname (and path) to the root, e.g. http://spf13.com/
@@ -177,7 +177,7 @@ taxonomies:
The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]: 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" contentDir = "content"
layoutDir = "layouts" layoutDir = "layouts"
publishDir = "public" publishDir = "public"
@@ -200,7 +200,7 @@ title = "My Hugo Site"
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. 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"%}} {{% code file="config.toml" download="config.toml"%}}
```toml ```
+++ +++
archetypeDir = "archetypes" archetypeDir = "archetypes"
# hostname (and path) to the root, e.g. http://spf13.com/ # hostname (and path) to the root, e.g. http://spf13.com/
@@ -314,7 +314,7 @@ watch = true
{{% note %}} {{% 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: 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 ~/sites/yourhugosite
hugo config | grep emoji hugo config | grep emoji
enableemoji: true enableemoji: true
@@ -327,7 +327,7 @@ In addition to the 3 config options already mentioned, configuration key-values
For example, the following command will effectively set a website's title on Unix-like systems: For example, the following command will effectively set a website's title on Unix-like systems:
```bash ```
$ env HUGO_TITLE="Some Title" hugo $ env HUGO_TITLE="Some Title" hugo
``` ```
@@ -339,7 +339,7 @@ Names must be prefixed with `HUGO_` and the configuration key must be set in upp
The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering: The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering:
```toml ```
ignoreFiles = [ "\\.foo$", "\\.boo$" ] ignoreFiles = [ "\\.foo$", "\\.boo$" ]
``` ```
@@ -361,7 +361,7 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
{{% /note %}} {{% /note %}}
{{% code file="bf-config.toml" %}} {{% code file="bf-config.toml" %}}
```toml ```
[blackfriday] [blackfriday]
angledQuotes = true angledQuotes = true
fractions = false fractions = false
@@ -371,7 +371,7 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
{{% /code %}} {{% /code %}}
{{% code file="bf-config.yml" %}} {{% code file="bf-config.yml" %}}
```yaml ```
blackfriday: blackfriday:
angledQuotes: true angledQuotes: true
fractions: false fractions: false
content/getting-started/directory-structure.md
+1 -1
View File
@@ -22,7 +22,7 @@ toc: true
Running the `hugo new site` generator from the command line will create a directory structure with the following elements: Running the `hugo new site` generator from the command line will create a directory structure with the following elements:
```bash ```
. .
├── archetypes ├── archetypes
├── config.toml ├── config.toml
content/getting-started/installing.md
+23 -23
View File
@@ -48,7 +48,7 @@ Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/loca
If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner: If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:
{{% code file="install-with-homebrew.sh" %}} {{% code file="install-with-homebrew.sh" %}}
```bash ```
brew install hugo brew install hugo
``` ```
{{% /code %}} {{% /code %}}
@@ -60,7 +60,7 @@ For more detailed explanations, read the installation guides that follow for ins
If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner: 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" %}} {{% code file="install-with-chocolatey.ps1" %}}
```powershell ```
choco install hugo -confirm choco install hugo -confirm
``` ```
{{% /code %}} {{% /code %}}
@@ -80,7 +80,7 @@ Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored
#### Fetch from GitHub #### Fetch from GitHub
{{% code file="from-gh.sh" %}} {{% code file="from-gh.sh" %}}
```sh ```
go get github.com/kardianos/govendor go get github.com/kardianos/govendor
govendor get github.com/gohugoio/hugo govendor get github.com/gohugoio/hugo
go install github.com/gohugoio/hugo go install github.com/gohugoio/hugo
@@ -132,7 +132,7 @@ Since building from source is appealing to more seasoned command line users, thi
Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line: 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" %}} {{% code file="install-brew.sh" %}}
```bash ```
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
``` ```
{{% /code %}} {{% /code %}}
@@ -142,14 +142,14 @@ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/
Installing Hugo using `brew` is as easy as the following: Installing Hugo using `brew` is as easy as the following:
{{% code file="install-brew.sh" %}} {{% code file="install-brew.sh" %}}
```bash ```
brew install hugo brew install hugo
``` ```
{{% /code %}} {{% /code %}}
If Homebrew is working properly, you should see something similar to the following: 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 ==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
######################################################################### 100.0% ######################################################################### 100.0%
==> Pouring hugo-0.21.sierra.bottle.tar.gz ==> Pouring hugo-0.21.sierra.bottle.tar.gz
@@ -162,7 +162,7 @@ Replace `brew install hugo` with `brew install hugo --HEAD` if you want the abso
`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands: `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 $ # show the location of the hugo executable
which hugo which hugo
/usr/local/bin/hugo /usr/local/bin/hugo
@@ -204,7 +204,7 @@ All three locations will work for you. In the interest of brevity, this guide fo
Verify that the tarball wasn't corrupted during the download: Verify that the tarball wasn't corrupted during the download:
```bash ```
tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz 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 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 -rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
@@ -215,7 +215,7 @@ The `.md` files are documentation for Hugo. The other file is the executable.
#### Step 4: Install Into Your `bin` Directory #### Step 4: Install Into Your `bin` Directory
```bash ```
# create the directory if needed # create the directory if needed
mkdir -p ~/bin mkdir -p ~/bin
@@ -237,7 +237,7 @@ Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
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. 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 # check if hugo is in the path
which hugo which hugo
/Users/USERNAME/bin/hugo /Users/USERNAME/bin/hugo
@@ -245,13 +245,13 @@ which hugo
If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor: If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:
```bash ```
nano ~/.bash_profile nano ~/.bash_profile
``` ```
Add a line to update your `PATH` variable: Add a line to update your `PATH` variable:
```bash ```
export PATH=$PATH:$HOME/bin export PATH=$PATH:$HOME/bin
``` ```
@@ -265,7 +265,7 @@ You've successfully installed Hugo.
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: 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 brew install go
``` ```
@@ -273,7 +273,7 @@ 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: 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 git clone https://github.com/gohugoio/hugo
``` ```
@@ -285,7 +285,7 @@ Cloning the Hugo repository directly means taking the good with the bad. By usin
Make the directory containing the source your working directory and then fetch Hugo's dependencies: Make the directory containing the source your working directory and then fetch Hugo's dependencies:
```bash ```
mkdir -p src/github.com/gohugoio mkdir -p src/github.com/gohugoio
ln -sf $(pwd) src/github.com/gohugoio/hugo ln -sf $(pwd) src/github.com/gohugoio/hugo
@@ -299,7 +299,7 @@ This will fetch the absolute latest version of the dependencies. If Hugo fails t
Once you have properly configured your directory, you can compile Hugo using the following command: Once you have properly configured your directory, you can compile Hugo using the following command:
```bash ```
go build -o hugo main.go go build -o hugo main.go
``` ```
@@ -369,7 +369,7 @@ Run a few commands to verify that the executable is ready to run, and then build
At the prompt, type `hugo help` and press the <kbd>Enter</kbd> key. You should see output that starts with: 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 the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator Hugo is a Fast and Flexible Static Site Generator
@@ -382,7 +382,7 @@ If you do, then the installation is complete. If you don't, double-check the pat
At the prompt, change your directory to the `Sites` directory. At the prompt, change your directory to the `Sites` directory.
```powershell ```
C:\Program Files> cd C:\Hugo\Sites C:\Program Files> cd C:\Hugo\Sites
C:\Hugo\Sites> C:\Hugo\Sites>
``` ```
@@ -391,13 +391,13 @@ C:\Hugo\Sites>
Run the command to generate a new site. I'm using `example.com` as the name of the site. 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 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: 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&gt;cd example.com C:\Hugo\Sites&gt;cd example.com
C:\Hugo\Sites\example.com&gt;dir C:\Hugo\Sites\example.com&gt;dir
&nbsp;Directory of C:\hugo\sites\example.com &nbsp;Directory of C:\hugo\sites\example.com
@@ -426,7 +426,7 @@ C:\Hugo\Sites\example.com&gt;dir
In any of the [Linux distributions that support snaps](https://snapcraft.io/docs/core/install): In any of the [Linux distributions that support snaps](https://snapcraft.io/docs/core/install):
```sh ```
sudo apt install hugo sudo apt install hugo
``` ```
@@ -445,7 +445,7 @@ You can also install Hugo from the [Arch user repository](https://aur.archlinux.
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. 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 sudo pacman -S yaourt
yaourt -S hugo yaourt -S hugo
``` ```
@@ -461,7 +461,7 @@ See the [related discussion in the Hugo forums][redhatforum].
In any of the [Linux distributions that support snaps][snaps]: In any of the [Linux distributions that support snaps][snaps]:
```bash ```
snap install hugo snap install hugo
``` ```
content/getting-started/quick-start.md
+36 -36
View File
@@ -36,7 +36,7 @@ If you're on Windows, this Quick Start will assume you're using [Git Bash](https
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: 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 help
hugo is the main command, used to build your Hugo site. hugo is the main command, used to build your Hugo site.
@@ -49,11 +49,11 @@ Complete documentation is available at http://gohugo.io/.
You can check the version of Hugo you're currently using with the `hugo version` command: You can check the version of Hugo you're currently using with the `hugo version` command:
```bash ```
hugo version hugo version
``` ```
```bash ```
Hugo Static Site Generator v0.18.1 BuildDate: 2016-12-30T05:02:43-05:00 Hugo Static Site Generator v0.18.1 BuildDate: 2016-12-30T05:02:43-05:00
``` ```
@@ -61,13 +61,13 @@ 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: 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 hugo new site bookshelf
``` ```
Change into the newly created `bookshelf` directory. Listing the new directory's content will show the following: Change into the newly created `bookshelf` directory. Listing the new directory's content will show the following:
```bash ```
. .
├── archetypes ├── archetypes
├── config.toml ├── config.toml
@@ -95,20 +95,20 @@ You'll see the `bookshelf` directory has 6 subdirectories and 1 file. Let's look
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. 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" %}} {{% code file="create-new-book-review-post.sh" %}}
```bash ```
hugo new post/good-to-great.md hugo new post/good-to-great.md
``` ```
{{% /code %}} {{% /code %}}
You should then see the following output: You should then see the following output:
```bash ```
/Users/yourusername/bookshelf/content/post/good-to-great.md created /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: 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 ├── archetypes
├── config.toml ├── config.toml
@@ -123,7 +123,7 @@ The above command will create a new directory `post` inside the `content` direct
Open `good-to-great.md` in your preferred text editor: Open `good-to-great.md` in your preferred text editor:
```toml ```
+++ +++
date = "2017-02-19T21:09:05-06:00" date = "2017-02-19T21:09:05-06:00"
title = "good to great" title = "good to great"
@@ -141,7 +141,7 @@ The text bracketed by `+++` is the TOML [front matter][fm] for the content. Fron
Let's update `good-to-great.md` with a short review of *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" %}} {{% code file="good-to-great-start.md" %}}
```markdown ```
+++ +++
date = "2016-02-14T16:11:58+05:30" date = "2016-02-14T16:11:58+05:30"
draft = true draft = true
@@ -156,13 +156,13 @@ I read **Good to Great in January 2016**. An awesome read sharing detailed analy
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: 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 hugo server
``` ```
You should see something similar to the following output: You should see something similar to the following output:
```bash ```
Built site for language en: Built site for language en:
0 of 1 draft rendered 0 of 1 draft rendered
0 future content 0 future content
@@ -187,13 +187,13 @@ This will start the server on port `1313`. You can view your blog at <http://loc
Kill the server using <kbd>Ctrl</kbd> + <kbd>C</kbd> and then rerun the server with the `--buildDrafts` flag appended to the command: 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 hugo server --buildDrafts
``` ```
You should now see something similar to the following: You should now see something similar to the following:
```bash ```
Built site for language en: Built site for language en:
1 of 1 draft rendered 1 of 1 draft rendered
0 future content 0 future content
@@ -225,7 +225,7 @@ Hugo currently doesn’t ship with a default theme, thus allowing end users to p
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: 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 cd themes
``` ```
@@ -234,7 +234,7 @@ You can clone one or more themes from within the `themes` directory. We will use
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: 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" %}} {{% code file="clone-robust-theme" %}}
```bash ```
git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../.. git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..
``` ```
{{% /code %}} {{% /code %}}
@@ -242,14 +242,14 @@ git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robu
Now let's start Hugo's server again but with the addition of the `-theme` flag for Robust: 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" %}} {{% code file="hugo-server-with-theme.sh" %}}
```bash ```
hugo server --theme=hugo_theme_robust --buildDrafts hugo server --theme=hugo_theme_robust --buildDrafts
``` ```
{{% /code %}} {{% /code %}}
You should see an output to the console similar to the following: You should see an output to the console similar to the following:
```bash ```
Built site for language en: Built site for language en:
1 of 1 draft rendered 1 of 1 draft rendered
0 future content 0 future content
@@ -270,7 +270,7 @@ Press Ctrl+C to stop
If Hugo doesn't find the specified theme in the `themes` directory, If Hugo doesn't find the specified theme in the `themes` directory,
it will throw an exception: it will throw an exception:
```bash ```
FATAL: 2016/02/14 Unable to find theme Directory: /Users/yourusername/bookshelf/themes/robust FATAL: 2016/02/14 Unable to find theme Directory: /Users/yourusername/bookshelf/themes/robust
``` ```
@@ -280,7 +280,7 @@ To view your website, you can go to <http://localhost:1313/>. You should see som
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]) 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 ├── LICENSE.md
├── archetypes ├── archetypes
@@ -311,7 +311,7 @@ You can very easily switch between different themes in Hugo. Let's suppose we wa
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: 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" %}} {{% code file="clone-bleak-theme.sh" %}}
```bash ```
cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd .. cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
``` ```
{{% /code %}} {{% /code %}}
@@ -319,7 +319,7 @@ cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
Now restart the server with our new theme flag: Now restart the server with our new theme flag:
{{% code file="run-server-with-bleak.sh" %}} {{% code file="run-server-with-bleak.sh" %}}
```bash ```
hugo server --theme=hugo-theme-bleak --buildDrafts hugo server --theme=hugo-theme-bleak --buildDrafts
``` ```
{{% /code %}} {{% /code %}}
@@ -333,7 +333,7 @@ Our website is now using the `bleak` theme at <http://localhost:1313>, which sho
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: 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" %}} {{% code file="restart-with-robust-sh" %}}
```bash ```
hugo server --theme=hugo_theme_robust --buildDrafts hugo server --theme=hugo_theme_robust --buildDrafts
``` ```
{{% /code %}} {{% /code %}}
@@ -343,7 +343,7 @@ hugo server --theme=hugo_theme_robust --buildDrafts
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: 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" %}} {{% code file="updated-config.toml" %}}
```toml ```
baseURL = "http://example.org/" baseURL = "http://example.org/"
languageCode = "en-us" languageCode = "en-us"
title = "Shekhar Gulati Book Reviews" title = "Shekhar Gulati Book Reviews"
@@ -393,7 +393,7 @@ Hugo will sync the changes and reload the website to use the new image:
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: 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"> <article class="li">
<a href="{{ .Permalink }}" class="clearfix"> <a href="{{ .Permalink }}" class="clearfix">
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div> <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
@@ -409,7 +409,7 @@ Now we need to change the layout of the index page so that only images are shown
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: 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" %}} {{% code file="create-new-li-html.sh" %}}
```bash ```
cd layouts && mkdir _default && cd _default && touch li.html && cd ../.. cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
``` ```
{{% /code %}} {{% /code %}}
@@ -417,7 +417,7 @@ cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
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: 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" %}} {{% code file="layouts/_default/li.html" %}}
```html ```
<article class="li"> <article class="li">
<a href="{{ .Permalink }}" class="clearfix"> <a href="{{ .Permalink }}" class="clearfix">
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div> <div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
@@ -435,7 +435,7 @@ Next, we want to remove information related to the theme from the footer. Let's
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: 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" %}} {{% code file="create-new-default-foot.sh" %}}
```bash ```
cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../.. cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..
``` ```
{{% /code %}} {{% /code %}}
@@ -443,7 +443,7 @@ cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../
Now add the following to our new `default_foot.html` partial template: Now add the following to our new `default_foot.html` partial template:
{{% code file="layouts/partials/default_foot.html" %}} {{% code file="layouts/partials/default_foot.html" %}}
```html ```
<footer class="site"> <footer class="site">
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}&copy; {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p> <p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}&copy; {{ $.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> <p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
@@ -454,7 +454,7 @@ Now add the following to our new `default_foot.html` partial template:
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. 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" %}} {{% code file="content/post/good-to-great.md" %}}
```markdown ```
+++ +++
date = "2017-02-19T21:09:05-06:00" date = "2017-02-19T21:09:05-06:00"
draft = true draft = true
@@ -477,13 +477,13 @@ After adding a few more books to our shelf, the shelf appears as shown below.
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: 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 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: 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" date = "2017-02-19T22:42:53-06:00"
draft = false draft = false
@@ -494,7 +494,7 @@ image = "good-to-great.jpg"
Now, we can start the server *without* the `buildDrafts` option. Now, we can start the server *without* the `buildDrafts` option.
```bash ```
hugo server --theme=hugo_theme_robust hugo server --theme=hugo_theme_robust
``` ```
@@ -506,7 +506,7 @@ To implement Disqus comments as part of the Quick Start, you'll need to set up a
To enable Disqus on our new site, we only need to update the `disqusShortname` in the config.toml as shown below. To enable Disqus on our new site, we only need to update the `disqusShortname` in the config.toml as shown below.
```toml ```
[Params] [Params]
Author = "Shekhar Gulati" Author = "Shekhar Gulati"
disqusShortname = <your disqus shortname> disqusShortname = <your disqus shortname>
@@ -520,13 +520,13 @@ Now, commenting will be enabled in your blog.
To generate a website that can be deployed to GitHub pages, we first need to change the `baseURL` in our configuration as follows: 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/" baseURL = "https://<yourgithubusername>.github.io/bookshelf/"
``` ```
Then type the following command while in the root directory of your Hugo project: Then type the following command while in the root directory of your Hugo project:
```bash ```
hugo --theme=hugo_theme_robust hugo --theme=hugo_theme_robust
0 draft content 0 draft content
0 future content 0 future content
content/getting-started/usage.md
+10 -10
View File
@@ -24,13 +24,13 @@ The following is a description of the most command commands you will use while d
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: 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 hugo help
``` ```
The output you see in your console should be similar to the following: 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 the main command, used to build your Hugo site.
Hugo is a Fast and Flexible Static Site Generator Hugo is a Fast and Flexible Static Site Generator
@@ -104,7 +104,7 @@ This generates your website to the `public/` directory by default, although you
The site Hugo renders into `public/` is ready to be deployed to your web server: The site Hugo renders into `public/` is ready to be deployed to your web server:
```bash ```
hugo hugo
0 draft content 0 draft content
0 future content 0 future content
@@ -133,7 +133,7 @@ All three of these can be overridden during both local development *and* deploym
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: 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 hugo server
0 draft content 0 draft content
0 future content 0 future content
@@ -172,23 +172,23 @@ LiveReload works by injecting JavaScript into the pages Hugo generates. The scri
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: 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 hugo server --watch=false
``` ```
Or... Or...
```bash ```
hugo server --disableLiveReload hugo server --disableLiveReload
``` ```
The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively: The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively:
```toml ```
disableLiveReload = true disableLiveReload = true
``` ```
```yaml ```
disableLiveReload: true disableLiveReload: true
``` ```
@@ -208,13 +208,13 @@ Hugo does not remove generated files before building. An easy workaround is to u
To start a server that builds draft content (helpful for editing), you can specify a different destination; e.g., a `dev/` directory: 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 hugo server -wDs ~/Code/hugo/docs -d dev
``` ```
When the content is ready for publishing, use the default `public/` dir: When the content is ready for publishing, use the default `public/` dir:
```bash ```
hugo -s ~/Code/hugo/docs hugo -s ~/Code/hugo/docs
``` ```
content/hosting-and-deployment/deployment-with-rsync.md
+6 -6
View File
@@ -27,7 +27,7 @@ notesforauthors:
The spoiler is that you can deploy your entire website with a command that looks like the following: 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/ hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
``` ```
@@ -40,14 +40,14 @@ If it is not done yet, we will make an automated way to SSH to your server. If y
First, install the ssh client. On Debian/Ubuntu/derivates, use the following command: First, install the ssh client. On Debian/Ubuntu/derivates, use the following command:
{{% code file="install-openssh.sh" %}} {{% code file="install-openssh.sh" %}}
```bash ```
sudo apt-get install openssh-client sudo apt-get install openssh-client
``` ```
{{% /code %}} {{% /code %}}
Then generate your ssh key by entering the following commands: Then generate your ssh key by entering the following commands:
```bash ```
~$ cd && mkdir .ssh & cd .ssh ~$ cd && mkdir .ssh & cd .ssh
~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id ~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id
~/.ssh/$ cat >> config <<EOF ~/.ssh/$ cat >> config <<EOF
@@ -61,7 +61,7 @@ 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: 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 ~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
``` ```
@@ -78,13 +78,13 @@ And you've done it!
We will put the first command in a script at the root of your Hugo tree: We will put the first command in a script at the root of your Hugo tree:
```bash ```
~/websites/topologix.fr$ editor deploy ~/websites/topologix.fr$ editor deploy
``` ```
Here you put the following content. Replace the `USER`, `HOST`, and `DIR` values with your own: Here you put the following content. Replace the `USER`, `HOST`, and `DIR` values with your own:
```bash ```
#!/bin/sh #!/bin/sh
USER=my-user USER=my-user
HOST=my-server.com HOST=my-server.com
content/hosting-and-deployment/deployment-with-wercker.md
+14 -14
View File
@@ -48,7 +48,7 @@ All the work for setting up a Hugo project and using this guide is done via the
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`: 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" %}} {{% code file="hugo-new-site.sh" %}}
```bash ```
hugo new site hugo-wercker-example hugo new site hugo-wercker-example
cd hugo-wercker-example cd hugo-wercker-example
``` ```
@@ -57,7 +57,7 @@ cd hugo-wercker-example
We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory. We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory.
{{% code file="clone-herring-cove-theme.sh" %}} {{% code file="clone-herring-cove-theme.sh" %}}
```bash ```
cd themes cd themes
git clone https://github.com/spf13/herring-cove.git git clone https://github.com/spf13/herring-cove.git
``` ```
@@ -66,14 +66,14 @@ git clone https://github.com/spf13/herring-cove.git
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: 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" %}} {{% code file="remove-herring-cove-git.sh" %}}
```bash ```
rm -rf herring-cove/.git rm -rf herring-cove/.git
``` ```
{{% /code %}} {{% /code %}}
We need content for Hugo to build. Let's add a quick `/about` page: We need content for Hugo to build. Let's add a quick `/about` page:
```bash ```
hugo new about.md hugo new about.md
``` ```
@@ -84,14 +84,14 @@ The preceding example for the about page leverages archetypes to scaffold a new
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: 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" %}} {{% code file="hugo-build-undraft.sh" %}}
```bash ```
hugo undraft content/about.md 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: 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 hugo server --theme=herring-cove
``` ```
@@ -103,14 +103,14 @@ If everything is fine, you should see something similar to the image below when
Adding Git to your project is done by running the `git init` command from the root directory of your project. Adding Git to your project is done by running the `git init` command from the root directory of your project.
```bash ```
git init 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: 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" %}} {{% code file="gitignore.sh" %}}
```bash ```
echo "/public" >> .gitignore echo "/public" >> .gitignore
``` ```
{{% /code %}} {{% /code %}}
@@ -118,14 +118,14 @@ echo "/public" >> .gitignore
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: 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" %}} {{% code file="addrobotstxt.sh" %}}
```bash ```
echo "User-agent: *\nDisallow:" > static/robots.txt 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: 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" git commit -a -m "Initial commit"
``` ```
@@ -136,7 +136,7 @@ Now we need to create a new repository on GitHub. Once you are signed in to GitH
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: 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" %}} {{% code file="setup-gh-repo.sh" %}}
```bash ```
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
git push -u origin master git push -u origin master
``` ```
@@ -231,7 +231,7 @@ The docs are a work in progress. As such, the `version` represented in this guid
{{% /warning %}} {{% /warning %}}
{{% code file="wercker-build-step.yml" %}} {{% code file="wercker-build-step.yml" %}}
```yaml ```
box: debian box: debian
build: build:
steps: steps:
@@ -245,7 +245,7 @@ build:
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. 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" %}} {{% code file="push-wecker-to-gh.sh" %}}
```bash ```
git commit -a -m "Add wercker.yml" git commit -a -m "Add wercker.yml"
git push origin master git push origin master
``` ```
@@ -260,7 +260,7 @@ If completed and successful, a green check mark should appear in the commit colu
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: 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" %}} {{% code file="wercker.yml" %}}
```yaml ```
box: debian box: debian
build: build:
steps: steps:
content/hosting-and-deployment/hosting-on-bitbucket.md
+6 -6
View File
@@ -30,14 +30,14 @@ You can use [Bitbucket](https://bitbucket.org/) and [Aerobatic](https://www.aero
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. 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 npm install aerobatic-cli -g
aero register aero register
``` ```
## Create and Deploy Site ## Create and Deploy Site
```bash ```
hugo new site my-new-hugo-site hugo new site my-new-hugo-site
cd my-new-hugo-site cd my-new-hugo-site
cd themes; git clone https://github.com/eliasson/liquorice cd themes; git clone https://github.com/eliasson/liquorice
@@ -61,7 +61,7 @@ We will now create a git repository and then push our code to Bitbucket. In Bitb
[1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png [1]: /images/hosting-and-deployment/hosting-on-bitbucket/bitbucket-create-repo.png
```bash ```
# initialize new git repository # initialize new git repository
git init git init
@@ -88,7 +88,7 @@ In your Hugo website's Bitbucket repo;
3. On the next screen, leave the default template and click Next. 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. 4. In the editor, paste in the yaml contents below and click Commit.
```bash ```
image: beevelop/nodejs-python image: beevelop/nodejs-python
pipelines: pipelines:
branches: branches:
@@ -109,7 +109,7 @@ pipelines:
This step only needs to be done once per account. From the command line; This step only needs to be done once per account. From the command line;
```bash ```
aero apikey aero apikey
``` ```
@@ -119,7 +119,7 @@ aero apikey
### Step 3: Edit and Commit Code ### Step 3: Edit and Commit Code
```bash ```
hugo new post/good-to-great.md hugo new post/good-to-great.md
hugo server --buildDrafts -t liquorice #Check that all looks good hugo server --buildDrafts -t liquorice #Check that all looks good
content/hosting-and-deployment/hosting-on-firebase.md
+6 -6
View File
@@ -29,19 +29,19 @@ aliases: []
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): 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 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. 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 firebase login
``` ```
In the root of your Hugo project, initialize the Firebase project with the `firebase init` command: In the root of your Hugo project, initialize the Firebase project with the `firebase init` command:
```sh ```
firebase init firebase init
``` ```
From here: From here:
@@ -56,7 +56,7 @@ From here:
To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time: To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
```sh ```
hugo && firebase deploy hugo && firebase deploy
``` ```
@@ -65,7 +65,7 @@ hugo && firebase deploy
You can generate a deploy token using You can generate a deploy token using
```sh ```
firebase login:ci firebase login:ci
``` ```
@@ -77,7 +77,7 @@ This is a private secret and it should not appear in a public repository. Make s
You can then add a step in your build to do the deployment using the token: You can then add a step in your build to do the deployment using the token:
```sh ```
firebase deploy --token $FIREBASE_DEPLOY_TOKEN firebase deploy --token $FIREBASE_DEPLOY_TOKEN
``` ```
content/hosting-and-deployment/hosting-on-github.md
+9 -9
View File
@@ -37,11 +37,11 @@ Make sure your `baseURL` key-value in your [site configuration](/getting-started
[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: [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 publishDir: docs
``` ```
```toml ```
publishDir = "docs" publishDir = "docs"
``` ```
@@ -69,7 +69,7 @@ These steps only need to be done once. Replace `upstream` with the name of your
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch: 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 echo "public" >> .gitignore
``` ```
@@ -77,7 +77,7 @@ echo "public" >> .gitignore
You can now initialize your `gh-pages` branch as an empty [orphan branch][]: You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
```bash ```
git checkout --orphan gh-pages git checkout --orphan gh-pages
git reset --hard git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch" git commit --allow-empty -m "Initializing gh-pages branch"
@@ -89,7 +89,7 @@ git checkout master
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: 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 rm -rf public
git worktree add -B gh-pages public upstream/gh-pages git worktree add -B gh-pages public upstream/gh-pages
``` ```
@@ -97,7 +97,7 @@ 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: Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
{{% code file="commit-gh-pages-files.sh"%}} {{% code file="commit-gh-pages-files.sh"%}}
```bash ```
hugo hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd .. cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
``` ```
@@ -105,7 +105,7 @@ cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
If the changes in your local `gh-pages` branch look alright, push them to the remote repo: If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
```bash ```
git push upstream gh-pages git push upstream gh-pages
``` ```
@@ -123,7 +123,7 @@ After a short while, you'll see the updated contents on your GitHub Pages site.
To automate these steps, you can create a script with the following contents: To automate these steps, you can create a script with the following contents:
{{% code file="publish_to_ghpages.sh" %}} {{% code file="publish_to_ghpages.sh" %}}
```sh ```
#!/bin/sh #!/bin/sh
DIR=$(dirname "$0") DIR=$(dirname "$0")
@@ -193,7 +193,7 @@ You're almost done. You can also add a `deploy.sh` script to automate the preced
The following are the contents of the `deploy.sh` script: The following are the contents of the `deploy.sh` script:
```sh ```
#!/bin/bash #!/bin/bash
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m" echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
content/hosting-and-deployment/hosting-on-gitlab.md
+3 -3
View File
@@ -31,14 +31,14 @@ aliases: [/tutorials/hosting-on-gitlab/]
## Create .gitlab-ci.yml ## Create .gitlab-ci.yml
```bash ```
cd your-hugo-site 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. 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" %}} {{% code file="gitlab-ci.yml" %}}
```yml ```
image: publysher/hugo image: publysher/hugo
pages: pages:
@@ -56,7 +56,7 @@ pages:
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. 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 # initialize new git repository
git init git init
content/hosting-and-deployment/hosting-on-netlify.md
+2 -2
View File
@@ -65,7 +65,7 @@ Setting the build command to `hugo` will build your site according to the curren
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: 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 hugo_0.19
``` ```
@@ -93,7 +93,7 @@ The [`git clone` method for installing themes][installthemes] is not supported b
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`: 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 cd themes
git submodule add https://github.com/<THEMECREATOR>/<THEMENAME> git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
``` ```
content/news/0-22-1.md
+2 -2
View File
@@ -16,14 +16,14 @@ With this release you can configure **permalinks with sections** like this:
**First level only:** **First level only:**
```toml ```
[permalinks] [permalinks]
blog = ":section/:title" blog = ":section/:title"
``` ```
**Nested (all levels):** **Nested (all levels):**
```toml ```
[permalinks] [permalinks]
blog = ":sections/:title" blog = ":sections/:title"
``` ```
content/news/0-22.md
+1 -1
View File
@@ -25,7 +25,7 @@ Hugo now has:
`.Site.GetPage` can now also be used to get regular pages ([#2844](https://github.com/gohugoio/hugo/issues/2844)): `.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 }} {{ (.Site.GetPage "page" "blog" "mypost.md" ).Title }}
``` ```
content/news/0-24.md
+2 -2
View File
@@ -14,7 +14,7 @@ Hugo now handles the **archetype files as Go templates**. This means that the is
A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`: A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`:
```markdown ```
--- ---
title: "{{ replace .TranslationBaseName "-" " " | title }}" title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }} date: {{ .Date }}
@@ -34,7 +34,7 @@ draft: true
And then create a new post with: And then create a new post with:
```bash ```
hugo new newsletter/the-latest-cool.stuff.md hugo new newsletter/the-latest-cool.stuff.md
``` ```
content/news/0-25.md
+1 -1
View File
@@ -16,7 +16,7 @@ If you start with `hugo server --navigateToChanged`, Hugo will navigate to the r
Example: Example:
```go ```
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} {{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} {{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
content/news/release-notes.md
+4 -4
View File
@@ -21,7 +21,7 @@ A simple example:
In `layouts/partials/mystyles.css`: In `layouts/partials/mystyles.css`:
```css ```
body { body {
background-color: {{ .Param "colors.main" }} background-color: {{ .Param "colors.main" }}
} }
@@ -29,7 +29,7 @@ body {
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): 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]
[params.colors] [params.colors]
main = "green" main = "green"
@@ -38,7 +38,7 @@ text = "blue"
And then in `layouts/partials/head.html` (or the partial used to include the head section into your layout): And then in `layouts/partials/head.html` (or the partial used to include the head section into your layout):
```html ```
<head> <head>
<style type="text/css"> <style type="text/css">
{{ partial "mystyles.css" . | safeCSS }} {{ partial "mystyles.css" . | safeCSS }}
@@ -50,7 +50,7 @@ Of course, `0.20` also made it super-easy to create external `CSS` stylesheets b
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: 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" }} {{ with .OutputFormats.Get "css" }}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}"> <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end }}` {{ end }}`
content/templates/404.md
+2 -2
View File
@@ -23,7 +23,7 @@ When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide y
In addition to the standard page variables, the 404 page has access to all site content accessible from `.Data.Pages`. In addition to the standard page variables, the 404 page has access to all site content accessible from `.Data.Pages`.
```bash ```
▾ layouts/ ▾ layouts/
404.html 404.html
``` ```
@@ -33,7 +33,7 @@ In addition to the standard page variables, the 404 page has access to all site
This is a basic example of a 404.html template: This is a basic example of a 404.html template:
{{% code file="layouts/404.html" download="404.html" %}} {{% code file="layouts/404.html" download="404.html" %}}
```html ```
{{ define "main"}} {{ define "main"}}
<main id="main"> <main id="main">
<div> <div>
content/templates/alternatives.md
+1 -1
View File
@@ -34,7 +34,7 @@ One noticeable difference between Ace and the other templating engines in Hugo i
In Hugo, the Ace base template will be chosen with the same rule set as for [Go base templates][]. In Hugo, the Ace base template will be chosen with the same rule set as for [Go base templates][].
```bash ```
.: .:
index.ace index.ace
content/templates/base.md
+4 -4
View File
@@ -60,7 +60,7 @@ Here is the lookup order for the `post` base template:
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. 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" %}} {{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
```html ```
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
@@ -88,7 +88,7 @@ The following defines a simple base template at `_default/baseof.html`. As a def
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: 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" %}} {{% code file="layouts/_default/list.html" download="list.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<h1>Posts</h1> <h1>Posts</h1>
{{ range .Data.Pages }} {{ range .Data.Pages }}
@@ -106,7 +106,7 @@ This replaces the contents of our (basically empty) "main" block with something
{{% warning %}} {{% warning %}}
Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: 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 --> <!-- Seemingly harmless HTML comment..that will break your layout at build -->
{{ define "main" }} {{ define "main" }}
...your code here ...your code here
@@ -118,7 +118,7 @@ Code that you put outside the block definitions *can* break your layout. This ev
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]: 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" %}} {{% code file="layouts/_default/single.html" download="single.html" %}}
```html ```
{{ define "title" }} {{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example--> <!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
{{ .Title }} &ndash; {{ .Site.Title }} {{ .Title }} &ndash; {{ .Site.Title }}
content/templates/data-templates.md
+6 -6
View File
@@ -73,7 +73,7 @@ The list of bass players can be accessed via `.Site.Data.jazz.bass`, a single ba
You can now render the list of recordings for all the bass players in a template: You can now render the list of recordings for all the bass players in a template:
```html ```
{{ range $.Site.Data.jazz.bass }} {{ range $.Site.Data.jazz.bass }}
{{ partial "artist.html" . }} {{ partial "artist.html" . }}
{{ end }} {{ end }}
@@ -126,7 +126,7 @@ Data-driven content currently consists of two functions, `getJSON` and `getCSV`,
In your template, call the functions like this: In your template, call the functions like this:
```golang ```
{{ $dataJ := getJSON "url" }} {{ $dataJ := getJSON "url" }}
{{ $dataC := getCSV "separator" "url" }} {{ $dataC := getCSV "separator" "url" }}
``` ```
@@ -142,21 +142,21 @@ The separator for `getCSV` must be put in the first position and can only be one
All passed arguments will be joined to the final URL: All passed arguments will be joined to the final URL:
```html ```
{{ $urlPre := "https://api.github.com" }} {{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
``` ```
This will resolve internally to the following: This will resolve internally to the following:
```html ```
{{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }} {{ $gistJ := getJSON "https://api.github.com/users/GITHUB_USERNAME/gists" }}
``` ```
Finally, you can range over an array. This example will output the Finally, you can range over an array. This example will output the
first 5 gists for a GitHub user: first 5 gists for a GitHub user:
```html ```
<ul> <ul>
{{ $urlPre := "https://api.github.com" }} {{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }} {{ $gistJ := getJSON $urlPre "/users/GITHUB_USERNAME/gists" }}
@@ -173,7 +173,7 @@ first 5 gists for a GitHub user:
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: 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" %}} {{% code file="layouts/partials/get-csv.html" %}}
```html ```
<table> <table>
<thead> <thead>
<tr> <tr>
content/templates/files.md
+5 -5
View File
@@ -37,14 +37,14 @@ Whether the path is absolute or relative does not matter because---at least for
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. 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" %}} {{% code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" %}}
```html ```
{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/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: You can then call the shortcode as follows inside of your content's markup:
```html ```
{{</* directoryindex path="/static/css" pathURL="/css" */>}} {{</* directoryindex path="/static/css" pathURL="/css" */>}}
``` ```
@@ -62,7 +62,7 @@ The [`readfile` function][reads] reads a file from disk and converts it into a s
To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*: 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" }} {{ readFile "/content/templates/local-file-templates" }}
``` ```
@@ -94,13 +94,13 @@ This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is
The output "string" for this shortcode declaration will be the following: The output "string" for this shortcode declaration will be the following:
```markdown ```
{{< readfile file="/content/readfiles/testing.txt" >}} {{< 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: 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" */>}} {{</* readfile file="/content/readfiles/testing.txt" markdown="true" */>}}
``` ```
content/templates/homepage.md
+1 -1
View File
@@ -48,7 +48,7 @@ In addition to the standard [page variables][pagevars], the homepage template ha
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]. 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" %}} {{% code file="layouts/index.html" download="index.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<main aria-role="main"> <main aria-role="main">
<header class="homepage-header"> <header class="homepage-header">
content/templates/internal.md
+9 -9
View File
@@ -33,11 +33,11 @@ Hugo ships with internal templates for Google Analytics tracking, including both
Provide your tracking id in your configuration file: Provide your tracking id in your configuration file:
```toml ```
googleAnalytics = "UA-123-45" googleAnalytics = "UA-123-45"
``` ```
```yml ```
googleAnalytics: "UA-123-45" googleAnalytics: "UA-123-45"
``` ```
@@ -45,12 +45,12 @@ googleAnalytics: "UA-123-45"
You can then include the Google Analytics internal template: You can then include the Google Analytics internal template:
```golang ```
{{ template "_internal/google_analytics.html" . }} {{ template "_internal/google_analytics.html" . }}
``` ```
```golang ```
{{ template "_internal/google_analytics_async.html" . }} {{ template "_internal/google_analytics_async.html" . }}
``` ```
@@ -62,11 +62,11 @@ Hugo also ships with an internal template for [Disqus comments][disqus], a popul
To use Hugo's Disqus template, you first need to set a single value in your site's `config.toml` or `config.yml`: 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" disqusShortname = "yourdiscussshortname"
``` ```
```yaml ```
disqusShortname: "yourdiscussshortname" disqusShortname: "yourdiscussshortname"
``` ```
@@ -80,7 +80,7 @@ You also have the option to set the following in the front matter for a given pi
To add Disqus, include the following line in templates where you want your comments to appear: To add Disqus, include the following line in templates where you want your comments to appear:
```golang ```
{{ template "_internal/disqus.html" . }} {{ template "_internal/disqus.html" . }}
``` ```
@@ -91,7 +91,7 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
You can create the following `layouts/partials/disqus.html`: You can create the following `layouts/partials/disqus.html`:
{{% code file="layouts/partials/disqus.html" download="disqus.html" %}} {{% code file="layouts/partials/disqus.html" download="disqus.html" %}}
```html ```
<div id="disqus_thread"></div> <div id="disqus_thread"></div>
<script type="text/javascript"> <script type="text/javascript">
@@ -116,7 +116,7 @@ The `if` statement skips the initialization of the Disqus comment injection when
You can then render your custom Disqus partial template as follows: You can then render your custom Disqus partial template as follows:
```golang ```
{{ partial "disqus.html" . }} {{ partial "disqus.html" . }}
``` ```
content/templates/introduction.md
+37 -37
View File
@@ -31,13 +31,13 @@ Golang templates are HTML files with the addition of [variables][variables] and
### Access a Predefined Variable ### Access a Predefined Variable
```golang ```
{{ foo }} {{ foo }}
``` ```
Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`:
```golang ```
{{ add 1 2 }} {{ add 1 2 }}
``` ```
@@ -45,13 +45,13 @@ Parameters for functions are separated using spaces. The following example calls
Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. Accessing the Page Parameter `bar` defined in a piece of content's [front matter][].
```golang ```
{{ .Params.bar }} {{ .Params.bar }}
``` ```
#### Parentheses Can be Used to Group Items Together #### Parentheses Can be Used to Group Items Together
```golang ```
{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}
``` ```
@@ -61,13 +61,13 @@ Each Go template gets a data object. In Hugo, each template is passed a `Page`.
This is how you access a `Page` variable from a template: This is how you access a `Page` variable from a template:
```golang ```
<title>{{ .Title }}</title> <title>{{ .Title }}</title>
``` ```
Values can also be stored in custom variables and referenced later: Values can also be stored in custom variables and referenced later:
```golang ```
{{ $address := "123 Main St."}} {{ $address := "123 Main St."}}
{{ $address }} {{ $address }}
``` ```
@@ -87,14 +87,14 @@ Go templates only ship with a few basic functions but also provide a mechanism f
### Example 1: Adding Numbers ### Example 1: Adding Numbers
```golang ```
{{ add 1 2 }} {{ add 1 2 }}
=> 3 => 3
``` ```
### Example 2: Comparing Numbers ### Example 2: Comparing Numbers
```golang ```
{{ lt 1 2 }} {{ lt 1 2 }}
=> true (i.e., since 1 is less than 2) => true (i.e., since 1 is less than 2)
``` ```
@@ -114,14 +114,14 @@ the `/layout/` directory within Hugo.
### Template and Partial Examples ### Template and Partial Examples
```golang ```
{{ template "partials/header.html" . }} {{ template "partials/header.html" . }}
``` ```
Starting with Hugo v0.12, you may also use the `partial` call Starting with Hugo v0.12, you may also use the `partial` call
for [partial templates][partials]: for [partial templates][partials]:
```golang ```
{{ partial "header.html" . }} {{ partial "header.html" . }}
``` ```
@@ -137,7 +137,7 @@ range.
#### Example 1: Using Context #### Example 1: Using Context
```golang ```
{{ range array }} {{ range array }}
{{ . }} {{ . }}
{{ end }} {{ end }}
@@ -145,7 +145,7 @@ range.
#### Example 2: Declaring Value => Variable name #### Example 2: Declaring Value => Variable name
```golang ```
{{range $element := array}} {{range $element := array}}
{{ $element }} {{ $element }}
{{ end }} {{ end }}
@@ -153,7 +153,7 @@ range.
#### Example 3: Declaring Key-Value Variable Name #### Example 3: Declaring Key-Value Variable Name
```golang ```
{{range $index, $element := array}} {{range $index, $element := array}}
{{ $index }} {{ $index }}
{{ $element }} {{ $element }}
@@ -172,13 +172,13 @@ Go Templates treat the following values as false:
#### Example 1: `if` #### Example 1: `if`
```golang ```
{{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }} {{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}
``` ```
#### Example 2: `if` … `else` #### Example 2: `if` … `else`
```golang ```
{{ if isset .Params "alt" }} {{ if isset .Params "alt" }}
{{ index .Params "alt" }} {{ index .Params "alt" }}
{{else}} {{else}}
@@ -188,7 +188,7 @@ Go Templates treat the following values as false:
#### Example 3: `and` & `or` #### Example 3: `and` & `or`
```golang ```
{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
``` ```
@@ -200,13 +200,13 @@ and skips the block if the variable is absent.
The first example above could be simplified as: The first example above could be simplified as:
```golang ```
{{ with .Params.title }}<h4>{{ . }}</h4>{{ end }} {{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}
``` ```
#### Example 5: `if` … `else if` #### Example 5: `if` … `else if`
```golang ```
{{ if isset .Params "alt" }} {{ if isset .Params "alt" }}
{{ index .Params "alt" }} {{ index .Params "alt" }}
{{ else if isset .Params "caption" }} {{ else if isset .Params "caption" }}
@@ -226,12 +226,12 @@ A few simple examples should help convey how to use the pipe.
The following two examples are functionally the same: The following two examples are functionally the same:
```golang ```
{{ shuffle (seq 1 5) }} {{ shuffle (seq 1 5) }}
``` ```
```golang ```
{{ (seq 1 5) | shuffle }} {{ (seq 1 5) | shuffle }}
``` ```
@@ -239,13 +239,13 @@ The following two examples are functionally the same:
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: 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 }} {{ index .Params "disqus_url" | html }}
``` ```
### Example 3: `or` with `isset` ### Example 3: `or` with `isset`
```golang ```
{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }}
Stuff Here Stuff Here
{{ end }} {{ end }}
@@ -253,7 +253,7 @@ Stuff Here
Could be rewritten as Could be rewritten as
```golang ```
{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} {{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }}
Stuff Here Stuff Here
{{ end }} {{ end }}
@@ -263,7 +263,7 @@ Stuff Here
By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this:
```golang ```
{{ "<!--[if lt IE 9]>" | safeHTML }} {{ "<!--[if lt IE 9]>" | safeHTML }}
<script src="html5shiv.js"></script> <script src="html5shiv.js"></script>
{{ "<![endif]-->" | safeHTML }} {{ "<![endif]-->" | safeHTML }}
@@ -284,7 +284,7 @@ The most easily overlooked concept to understand about Go templates is that `{{
The following shows how to define a variable independent of the context. The following shows how to define a variable independent of the context.
{{% code file="tags-range-with-page-variable.html" %}} {{% code file="tags-range-with-page-variable.html" %}}
```html ```
{{ $title := .Site.Title }} {{ $title := .Site.Title }}
<ul> <ul>
{{ range .Params.tags }} {{ range .Params.tags }}
@@ -306,7 +306,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
`$` 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: `$` 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" %}} {{% code file="range-through-tags-w-global.html" %}}
```hbs ```
<ul> <ul>
{{ range .Params.tags }} {{ range .Params.tags }}
<li> <li>
@@ -328,7 +328,7 @@ Go 1.6 includes the ability to trim the whitespace from either side of a Go tag
For instance, the following Go template will include the newlines and horizontal tab in its HTML output: For instance, the following Go template will include the newlines and horizontal tab in its HTML output:
```html ```
<div> <div>
{{ .Title }} {{ .Title }}
</div> </div>
@@ -336,7 +336,7 @@ For instance, the following Go template will include the newlines and horizontal
Which will output: Which will output:
```html ```
<div> <div>
Hello, World! Hello, World!
</div> </div>
@@ -344,7 +344,7 @@ Which will output:
Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
```html ```
<div> <div>
{{- .Title -}} {{- .Title -}}
</div> </div>
@@ -352,7 +352,7 @@ Leveraging the `-` in the following example will remove the extra white space su
Which then outputs: Which then outputs:
```html ```
<div>Hello, World!</div> <div>Hello, World!</div>
``` ```
@@ -375,7 +375,7 @@ An example of this is used in the Hugo docs. Most of the pages benefit from havi
Here is the example front matter: Here is the example front matter:
```yaml ```
--- ---
title: Roadmap title: Roadmap
lastmod: 2017-03-05 lastmod: 2017-03-05
@@ -387,7 +387,7 @@ notoc: true
Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: 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" %}} {{% code file="layouts/partials/toc.html" download="toc.html" %}}
```html ```
{{ if not .Params.notoc }} {{ if not .Params.notoc }}
<aside> <aside>
<header> <header>
@@ -411,7 +411,7 @@ You can arbitrarily define as many site-level parameters as you want in your [si
For instance, you might declare the following: For instance, you might declare the following:
{{% code file="config.yaml" %}} {{% code file="config.yaml" %}}
```yaml ```
params: params:
copyrighthtml: "Copyright &#xA9; 2017 John Doe. All Rights Reserved." copyrighthtml: "Copyright &#xA9; 2017 John Doe. All Rights Reserved."
twitteruser: "spf13" twitteruser: "spf13"
@@ -421,7 +421,7 @@ params:
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. 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> {{if .Site.Params.copyrighthtml}}<footer>
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div> <div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
</footer>{{end}} </footer>{{end}}
@@ -430,7 +430,7 @@ Within a footer layout, you might then declare a `<footer>` that is only rendere
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: 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" %}} {{% code file="layouts/partials/twitter.html" %}}
```html ```
{{with .Site.Params.twitteruser}} {{with .Site.Params.twitteruser}}
<div> <div>
<a href="https://twitter.com/{{.}}" rel="author"> <a href="https://twitter.com/{{.}}" rel="author">
@@ -442,7 +442,7 @@ An alternative way of writing the "`if`" and then referencing the same value is
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. 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> <nav>
<h1>Recent Posts</h1> <h1>Recent Posts</h1>
<ul> <ul>
@@ -458,7 +458,7 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
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]: 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" %}} {{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}}
```html ```
<h4>Upcoming Events</h4> <h4>Upcoming Events</h4>
<ul class="upcoming-events"> <ul class="upcoming-events">
{{ range where .Data.Pages.ByDate "Section" "events" }} {{ range where .Data.Pages.ByDate "Section" "events" }}
content/templates/lists.md
+33 -33
View File
@@ -63,7 +63,7 @@ It is important to note that all `_index.md` content files will render according
The following is an example of a typical Hugo project directory's content: The following is an example of a typical Hugo project directory's content:
```bash ```
. .
... ...
├── content ├── content
@@ -80,7 +80,7 @@ The following is an example of a typical Hugo project directory's content:
Using the above example, let's assume you have the following in `content/post/_index.md`: Using the above example, let's assume you have the following in `content/post/_index.md`:
{{% code file="content/post/_index.md" %}} {{% code file="content/post/_index.md" %}}
```yaml ```
--- ---
title: My Golang Journey title: My Golang Journey
date: 2017-03-23 date: 2017-03-23
@@ -96,7 +96,7 @@ Follow my journey through this new blog.
You can now access this `_index.md`'s' content in your list template: You can now access this `_index.md`'s' content in your list template:
{{% code file="layouts/_default/list.html" download="list.html" %}} {{% code file="layouts/_default/list.html" download="list.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<main> <main>
<article> <article>
@@ -122,7 +122,7 @@ You can now access this `_index.md`'s' content in your list template:
This above will output the following HTML: This above will output the following HTML:
{{% code file="yoursite.com/post/index.html" copy="false" %}} {{% code file="yoursite.com/post/index.html" copy="false" %}}
```html ```
<!--top of your baseof code--> <!--top of your baseof code-->
<main> <main>
<article> <article>
@@ -148,7 +148,7 @@ You do *not* have to create an `_index.md` file for every list page (i.e. sectio
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: 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" %}} {{% code file="yoursite.com/quote/index.html" copy="false" %}}
```html ```
<!--baseof--> <!--baseof-->
<main> <main>
<article> <article>
@@ -177,7 +177,7 @@ The default behavior of Hugo is to pluralize list titles; hence the inflection o
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`. 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" %}} {{% code file="layouts/section/post.html" %}}
```html ```
{{ partial "header.html" . }} {{ partial "header.html" . }}
{{ partial "subheader.html" . }} {{ partial "subheader.html" . }}
<main> <main>
@@ -198,7 +198,7 @@ This list template has been modified slightly from a template originally used in
### Taxonomy Template ### Taxonomy Template
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} {{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<main> <main>
<div> <div>
@@ -220,7 +220,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### Default: Weight > Date > LinkTitle > FilePath ### Default: Weight > Date > LinkTitle > FilePath
{{% code file="layouts/partials/default-order.html" %}} {{% code file="layouts/partials/default-order.html" %}}
```html ```
<ul> <ul>
{{ range .Data.Pages }} {{ range .Data.Pages }}
<li> <li>
@@ -235,7 +235,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Weight ### By Weight
{{% code file="layouts/partials/by-weight.html" %}} {{% code file="layouts/partials/by-weight.html" %}}
```html ```
<ul> <ul>
{{ range .Data.Pages.ByWeight }} {{ range .Data.Pages.ByWeight }}
<li> <li>
@@ -250,7 +250,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Date ### By Date
{{% code file="layouts/partials/by-date.html" %}} {{% code file="layouts/partials/by-date.html" %}}
```html ```
<ul> <ul>
<!-- orders content according to the "date" field in front matter --> <!-- orders content according to the "date" field in front matter -->
{{ range .Data.Pages.ByDate }} {{ range .Data.Pages.ByDate }}
@@ -266,7 +266,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Publish Date ### By Publish Date
{{% code file="layouts/partials/by-publish-date.html" %}} {{% code file="layouts/partials/by-publish-date.html" %}}
```html ```
<ul> <ul>
<!-- orders content according to the "publishdate" field in front matter --> <!-- orders content according to the "publishdate" field in front matter -->
{{ range .Data.Pages.ByPublishDate }} {{ range .Data.Pages.ByPublishDate }}
@@ -282,7 +282,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Expiration Date ### By Expiration Date
{{% code file="layouts/partials/by-expiry-date.html" %}} {{% code file="layouts/partials/by-expiry-date.html" %}}
```html ```
<ul> <ul>
{{ range .Data.Pages.ByExpiryDate }} {{ range .Data.Pages.ByExpiryDate }}
<li> <li>
@@ -297,7 +297,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Last Modified Date ### By Last Modified Date
{{% code file="layouts/partials/by-last-mod.html" %}} {{% code file="layouts/partials/by-last-mod.html" %}}
```html ```
<ul> <ul>
<!-- orders content according to the "lastmod" field in front matter --> <!-- orders content according to the "lastmod" field in front matter -->
{{ range .Data.Pages.ByLastmod }} {{ range .Data.Pages.ByLastmod }}
@@ -313,7 +313,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Length ### By Length
{{% code file="layouts/partials/by-length.html" %}} {{% code file="layouts/partials/by-length.html" %}}
```html ```
<ul> <ul>
<!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) --> <!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
{{ range .Data.Pages.ByLength }} {{ range .Data.Pages.ByLength }}
@@ -329,7 +329,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Title ### By Title
{{% code file="layouts/partials/by-title.html" %}} {{% code file="layouts/partials/by-title.html" %}}
```html ```
<ul> <ul>
<!-- ranges through content in ascending order according to the "title" field set in front matter --> <!-- ranges through content in ascending order according to the "title" field set in front matter -->
{{ range .Data.Pages.ByTitle }} {{ range .Data.Pages.ByTitle }}
@@ -345,7 +345,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
### By Link Title ### By Link Title
{{% code file="layouts/partials/by-link-title.html" %}} {{% code file="layouts/partials/by-link-title.html" %}}
```html ```
<ul> <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 --> <!-- 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 }} {{ range .Data.Pages.ByLinkTitle }}
@@ -363,7 +363,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
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. 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" %}} {{% code file="layouts/partials/by-rating.html" %}}
```html ```
<!-- Ranges through content according to the "rating" field set in front matter --> <!-- Ranges through content according to the "rating" field set in front matter -->
{{ range (.Data.Pages.ByParam "rating") }} {{ range (.Data.Pages.ByParam "rating") }}
<!-- ... --> <!-- ... -->
@@ -374,7 +374,7 @@ Order based on the specified front matter parameter. Content that does not have
If the targeted front matter field is nested beneath another field, you can access the field using dot notation. 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" %}} {{% code file="layouts/partials/by-nested-param.html" %}}
```html ```
{{ range (.Data.Pages.ByParam "author.last_name") }} {{ range (.Data.Pages.ByParam "author.last_name") }}
<!-- ... --> <!-- ... -->
{{ end }} {{ end }}
@@ -386,7 +386,7 @@ If the targeted front matter field is nested beneath another field, you can acce
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: 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" %}} {{% code file="layouts/partials/by-date-reverse.html" %}}
```html ```
<ul> <ul>
{{ range .Data.Pages.ByDate.Reverse }} {{ range .Data.Pages.ByDate.Reverse }}
<li> <li>
@@ -405,7 +405,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page Field ### By Page Field
{{% code file="layouts/partials/by-page-field.html" %}} {{% code file="layouts/partials/by-page-field.html" %}}
```html ```
<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. --> <!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
{{ range .Data.Pages.GroupBy "Section" }} {{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
@@ -424,7 +424,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
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]: 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" %}} {{% code file="layouts/partials/by-page-field.html" %}}
```html ```
<!-- Groups content according to content section.--> <!-- Groups content according to content section.-->
{{ range .Data.Pages.GroupBy "Section" }} {{ range .Data.Pages.GroupBy "Section" }}
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter --> <!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
@@ -449,7 +449,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
### By Date ### By Date
{{% code file="layouts/partials/by-page-date.html" %}} {{% code file="layouts/partials/by-page-date.html" %}}
```html ```
<!-- Groups content by month according to the "date" field in front matter --> <!-- Groups content by month according to the "date" field in front matter -->
{{ range .Data.Pages.GroupByDate "2006-01" }} {{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
@@ -468,7 +468,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
### By Publish Date ### By Publish Date
{{% code file="layouts/partials/by-page-publish-date.html" %}} {{% code file="layouts/partials/by-page-publish-date.html" %}}
```html ```
<!-- Groups content by month according to the "publishdate" field in front matter --> <!-- Groups content by month according to the "publishdate" field in front matter -->
{{ range .Data.Pages.GroupByPublishDate "2006-01" }} {{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
@@ -487,7 +487,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
### By Page Parameter ### By Page Parameter
{{% code file="layouts/partials/by-page-param.html" %}} {{% code file="layouts/partials/by-page-param.html" %}}
```html ```
<!-- Groups content according to the "param_key" field in front matter --> <!-- Groups content according to the "param_key" field in front matter -->
{{ range .Data.Pages.GroupByParam "param_key" }} {{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
@@ -508,7 +508,7 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
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. 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" %}} {{% code file="layouts/partials/by-page-param-as-date.html" %}}
```html ```
<!-- Groups content by month according to the "param_key" field in front matter --> <!-- Groups content by month according to the "param_key" field in front matter -->
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} {{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
@@ -532,21 +532,21 @@ While these are logical defaults, they are not always the desired order. There a
#### 1. Adding the Reverse Method #### 1. Adding the Reverse Method
```html ```
{{ range (.Data.Pages.GroupBy "Section").Reverse }} {{ range (.Data.Pages.GroupBy "Section").Reverse }}
``` ```
```html ```
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
``` ```
#### 2. Providing the Alternate Direction #### 2. Providing the Alternate Direction
```html ```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
``` ```
```html ```
{{ range .Data.Pages.GroupBy "Section" "desc" }} {{ range .Data.Pages.GroupBy "Section" "desc" }}
``` ```
@@ -561,7 +561,7 @@ Here is the ordering for the example that follows:
3. Pages within each respective group are ordered alphabetically according to the `title`. 3. Pages within each respective group are ordered alphabetically according to the `title`.
{{% code file="layouts/partials/by-group-by-page.html" %}} {{% code file="layouts/partials/by-group-by-page.html" %}}
```html ```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -589,7 +589,7 @@ Sometimes you only want to list a subset of the available content. A common is t
3. `match value` 3. `match value`
{{% code file="layouts/_default/.html" %}} {{% code file="layouts/_default/.html" %}}
```html ```
{{ range where .Data.Pages "Section" "post" }} {{ range where .Data.Pages "Section" "post" }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -606,7 +606,7 @@ You can see more examples in the [functions documentation for `where`][wherefunc
2. `number of elements` 2. `number of elements`
{{% code file="layout/_default/section.html" %}} {{% code file="layout/_default/section.html" %}}
```html ```
{{ range first 10 .Data.Pages }} {{ range first 10 .Data.Pages }}
{{ .Render "summary" }} {{ .Render "summary" }}
{{ end }} {{ end }}
@@ -618,7 +618,7 @@ You can see more examples in the [functions documentation for `where`][wherefunc
Using `first` and `where` together can be very powerful: Using `first` and `where` together can be very powerful:
{{% code file="first-and-where-together.html" %}} {{% code file="first-and-where-together.html" %}}
```html ```
<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts --> <!-- 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 }} {{ range first 5 (where .Data.Pages "Section" "post").ByTitle }}
{{ .Content }} {{ .Content }}
content/templates/lookup-order.md
+4 -4
View File
@@ -52,7 +52,7 @@ The lookup order is best illustrated through examples. The following shows you t
1. The project is using the theme `mytheme` (specified in the project's [configuration][config]). 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: 2. The layouts and content directories for the project are as follows:
```bash ```
. .
├── content ├── content
│ ├── events │ ├── events
@@ -89,7 +89,7 @@ Only three of the four markdown files in the above project are subject to the *s
### Example: `my-first-post.md` ### Example: `my-first-post.md`
{{% code file="content/posts/my-first-post.md" copy="false" %}} {{% code file="content/posts/my-first-post.md" copy="false" %}}
```yaml ```
--- ---
title: My First Post title: My First Post
date: 2017-02-19 date: 2017-02-19
@@ -119,7 +119,7 @@ Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo th
### Example: `my-second-post.md` ### Example: `my-second-post.md`
{{% code file="content/posts/my-second-post.md" copy="false" %}} {{% code file="content/posts/my-second-post.md" copy="false" %}}
```yaml ```
--- ---
title: My Second Post title: My Second Post
date: 2017-02-21 date: 2017-02-21
@@ -153,7 +153,7 @@ Notice that the directory for the template for `my-second-post.md` is `review` a
### Example: `my-first-event.md` ### Example: `my-first-event.md`
{{% code file="content/events/my-first-event.md" copy="false" %}} {{% code file="content/events/my-first-event.md" copy="false" %}}
```yaml ```
--- ---
title: My First title: My First
date: 2017-02-21 date: 2017-02-21
content/templates/menu-templates.md
+4 -4
View File
@@ -25,7 +25,7 @@ able to build your menu however you want.
The following is an example: The following is an example:
{{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}} {{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}}
```html ```
<!-- sidebar start --> <!-- sidebar start -->
<aside> <aside>
<div id="sidebar" class="nav-collapse"> <div id="sidebar" class="nav-collapse">
@@ -73,7 +73,7 @@ Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rella
To enable this menu, add the following to your site `config`: To enable this menu, add the following to your site `config`:
```toml ```
SectionPagesMenu = "main" SectionPagesMenu = "main"
``` ```
@@ -81,7 +81,7 @@ The menu name can be anything, but take a note of what it is.
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: 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"> <nav class="sidebar-nav">
{{ $currentPage := . }} {{ $currentPage := . }}
{{ range .Site.Menus.main }} {{ range .Site.Menus.main }}
@@ -94,7 +94,7 @@ In the above, the menu item is marked as active if on the current section's list
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`: 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]] [[menu.main]]
name = "This is the blog section" name = "This is the blog section"
weight = -110 weight = -110
content/templates/ordering-and-grouping.md
+27 -27
View File
@@ -28,7 +28,7 @@ In Hugo, A list template is any template that will be used to render multiple pi
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." 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" %}} {{% code file="layouts/section/post.html" %}}
```html ```
{{ partial "header.html" . }} {{ partial "header.html" . }}
{{ partial "subheader.html" . }} {{ partial "subheader.html" . }}
@@ -49,7 +49,7 @@ This list template is used for [spf13.com](http://spf13.com/). It makes use of [
### Taxonomy Template ### Taxonomy Template
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} {{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
```html ```
{{ define "main" }} {{ define "main" }}
<section id="main"> <section id="main">
<div> <div>
@@ -73,7 +73,7 @@ your list templates:
### Default: Weight > Date ### Default: Weight > Date
{{% code file="layouts/partials/order-default.html" %}} {{% code file="layouts/partials/order-default.html" %}}
```html ```
<ul class="pages"> <ul class="pages">
{{ range .Data.Pages }} {{ range .Data.Pages }}
<li> <li>
@@ -88,7 +88,7 @@ your list templates:
### By Weight ### By Weight
{{% code file="layouts/partials/by-weight.html" %}} {{% code file="layouts/partials/by-weight.html" %}}
```html ```
{{ range .Data.Pages.ByWeight }} {{ range .Data.Pages.ByWeight }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -101,7 +101,7 @@ your list templates:
### By Date ### By Date
{{% code file="layouts/partials/by-date.html" %}} {{% code file="layouts/partials/by-date.html" %}}
```html ```
{{ range .Data.Pages.ByDate }} {{ range .Data.Pages.ByDate }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -114,7 +114,7 @@ your list templates:
### By Publish Date ### By Publish Date
{{% code file="layouts/partials/by-publish-date.html" %}} {{% code file="layouts/partials/by-publish-date.html" %}}
```html ```
{{ range .Data.Pages.ByPublishDate }} {{ range .Data.Pages.ByPublishDate }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -127,7 +127,7 @@ your list templates:
### By Expiration Date ### By Expiration Date
{{% code file="layouts/partials/by-expiry-date.html" %}} {{% code file="layouts/partials/by-expiry-date.html" %}}
```html ```
{{ range .Data.Pages.ByExpiryDate }} {{ range .Data.Pages.ByExpiryDate }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -140,7 +140,7 @@ your list templates:
### By Last Modified Date ### By Last Modified Date
{{% code file="layouts/partials/by-last-mod.html" %}} {{% code file="layouts/partials/by-last-mod.html" %}}
```html ```
{{ range .Data.Pages.ByLastmod }} {{ range .Data.Pages.ByLastmod }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -153,7 +153,7 @@ your list templates:
### By Length ### By Length
{{% code file="layouts/partials/by-length.html" %}} {{% code file="layouts/partials/by-length.html" %}}
```html ```
{{ range .Data.Pages.ByLength }} {{ range .Data.Pages.ByLength }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -167,7 +167,7 @@ your list templates:
### By Title ### By Title
{{% code file="layouts/partials/by-title.html" %}} {{% code file="layouts/partials/by-title.html" %}}
```html ```
{{ range .Data.Pages.ByTitle }} {{ range .Data.Pages.ByTitle }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -180,7 +180,7 @@ your list templates:
### By Link Title ### By Link Title
{{% code file="layouts/partials/by-link-title.html" %}} {{% code file="layouts/partials/by-link-title.html" %}}
```html ```
{{ range .Data.Pages.ByLinkTitle }} {{ range .Data.Pages.ByLinkTitle }}
<li> <li>
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a> <a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
@@ -197,7 +197,7 @@ Order based on the specified front matter parameter. Content that does not have
The below example sorts a list of posts by their rating. The below example sorts a list of posts by their rating.
{{% code file="layouts/partials/by-rating.html" %}} {{% code file="layouts/partials/by-rating.html" %}}
```html ```
{{ range (.Data.Pages.ByParam "rating") }} {{ range (.Data.Pages.ByParam "rating") }}
<!-- ... --> <!-- ... -->
{{ end }} {{ end }}
@@ -208,7 +208,7 @@ If the front matter field of interest is nested beneath another field, you can
also get it: also get it:
{{% code file="layouts/partials/by-nested-param.html" %}} {{% code file="layouts/partials/by-nested-param.html" %}}
```html ```
{{ range (.Data.Pages.ByParam "author.last_name") }} {{ range (.Data.Pages.ByParam "author.last_name") }}
<!-- ... --> <!-- ... -->
{{ end }} {{ end }}
@@ -220,7 +220,7 @@ also get it:
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: 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" %}} {{% code file="layouts/partials/by-date-reverse.html" %}}
```html ```
{{ range .Data.Pages.ByDate.Reverse }} {{ range .Data.Pages.ByDate.Reverse }}
<li> <li>
<a href="{{ .Permalink }}">{{ .Title }}</a> <a href="{{ .Permalink }}">{{ .Title }}</a>
@@ -237,7 +237,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page Field ### By Page Field
{{% code file="layouts/partials/by-page-field.html" %}} {{% code file="layouts/partials/by-page-field.html" %}}
```html ```
{{ range .Data.Pages.GroupBy "Section" }} {{ range .Data.Pages.GroupBy "Section" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -255,7 +255,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page date ### By Page date
{{% code file="layouts/partials/by-page-date.html" %}} {{% code file="layouts/partials/by-page-date.html" %}}
```html ```
{{ range .Data.Pages.GroupByDate "2006-01" }} {{ range .Data.Pages.GroupByDate "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -273,7 +273,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page publish date ### By Page publish date
{{% code file="layouts/partials/by-page-publish-date.html" %}} {{% code file="layouts/partials/by-page-publish-date.html" %}}
```html ```
{{ range .Data.Pages.GroupByPublishDate "2006-01" }} {{ range .Data.Pages.GroupByPublishDate "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -291,7 +291,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page Param ### By Page Param
{{% code file="layouts/partials/by-page-param.html" %}} {{% code file="layouts/partials/by-page-param.html" %}}
```html ```
{{ range .Data.Pages.GroupByParam "param_key" }} {{ range .Data.Pages.GroupByParam "param_key" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -309,7 +309,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
### By Page Param in Date Format ### By Page Param in Date Format
{{% code file="layouts/partials/by-page-param-as-date.html" %}} {{% code file="layouts/partials/by-page-param-as-date.html" %}}
```html ```
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} {{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -332,22 +332,22 @@ While these are logical defaults, they are not always the desired order. There a
#### Reverse Method #### Reverse Method
```html ```
{{ range (.Data.Pages.GroupBy "Section").Reverse }} {{ range (.Data.Pages.GroupBy "Section").Reverse }}
``` ```
```html ```
{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }}
``` ```
#### Provide the Alternate Direction #### Provide the Alternate Direction
```html ```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
``` ```
```html ```
{{ range .Data.Pages.GroupBy "Section" "desc" }} {{ range .Data.Pages.GroupBy "Section" "desc" }}
``` ```
@@ -359,7 +359,7 @@ In the following example, groups are ordered chronologically and then content
within each group is ordered alphabetically by title. within each group is ordered alphabetically by title.
{{% code file="layouts/partials/by-group-by-page.html" %}} {{% code file="layouts/partials/by-group-by-page.html" %}}
```html ```
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
<h3>{{ .Key }}</h3> <h3>{{ .Key }}</h3>
<ul> <ul>
@@ -387,7 +387,7 @@ Sometimes you only want to list a subset of the available content. A common requ
3. `match value` 3. `match value`
{{% code file="layouts/_default/.html" %}} {{% code file="layouts/_default/.html" %}}
```html ```
{{ range where .Data.Pages "Section" "post" }} {{ range where .Data.Pages "Section" "post" }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
@@ -402,7 +402,7 @@ Sometimes you only want to list a subset of the available content. A common requ
2. `number of elements` 2. `number of elements`
{{% code file="layout/_default/section.html" %}} {{% code file="layout/_default/section.html" %}}
```html ```
{{ range first 10 .Data.Pages }} {{ range first 10 .Data.Pages }}
{{ .Render "summary" }} {{ .Render "summary" }}
{{ end }} {{ end }}
@@ -414,7 +414,7 @@ Sometimes you only want to list a subset of the available content. A common requ
Using `first` and `where` together can be very powerful: Using `first` and `where` together can be very powerful:
{{% code file="first-and-where-together.html" %}} {{% code file="first-and-where-together.html" %}}
```html ```
{{ range first 5 (where .Data.Pages "Section" "post") }} {{ range first 5 (where .Data.Pages "Section" "post") }}
{{ .Content }} {{ .Content }}
{{ end }} {{ end }}
content/templates/output-formats.md
+5 -5
View File
@@ -39,7 +39,7 @@ To add or modify a media type, define it in a `mediaTypes` section in your [site
Example in `config.toml`: Example in `config.toml`:
```toml ```
[mediaTypes] [mediaTypes]
[mediaTypes."text/enriched"] [mediaTypes."text/enriched"]
suffix = "enr" suffix = "enr"
@@ -63,7 +63,7 @@ This is the full set of Hugo's built-in output formats:
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. 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] [outputFormats.MyEnrichedFormat]
mediaType = "text/enriched" mediaType = "text/enriched"
baseName = "myindex" baseName = "myindex"
@@ -115,7 +115,7 @@ This can be changed by defining an `outputs` list of output formats in either th
Example from site `config.toml`: Example from site `config.toml`:
```toml ```
[outputs] [outputs]
home = ["HTML", "AMP", "RSS"] home = ["HTML", "AMP", "RSS"]
page = ["HTML"] page = ["HTML"]
@@ -123,7 +123,7 @@ Example from site `config.toml`:
Example from site `config.yml`: Example from site `config.yml`:
```yml ```
outputs: outputs:
home: ["HTML", "AMP", "RSS"] home: ["HTML", "AMP", "RSS"]
page: ["HTML"] page: ["HTML"]
@@ -138,7 +138,7 @@ outputs:
The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`: 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" date: "2016-03-19"
outputs: outputs:
content/templates/pagination.md
+3 -3
View File
@@ -64,7 +64,7 @@ The `.Paginator` contains enough information to build a paginator interface.
The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles): 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" . }} {{ template "_internal/pagination.html" . }}
``` ```
@@ -74,7 +74,7 @@ If you use any filters or ordering functions to create your `.Paginator` *and* y
The following example shows how to create `.Paginator` before its used: The following example shows how to create `.Paginator` before its used:
```html ```
{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }} {{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
{{ template "_internal/pagination.html" . }} {{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }} {{ range $paginator.Pages }}
@@ -84,7 +84,7 @@ The following example shows how to create `.Paginator` before its used:
Without the `where` filter, the above example is even simpler: Without the `where` filter, the above example is even simpler:
```html ```
{{ template "_internal/pagination.html" . }} {{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }} {{ range .Paginator.Pages }}
{{ .Title }} {{ .Title }}
content/templates/partials.md
+3 -3
View File
@@ -60,7 +60,7 @@ One of the most common mistakes with new Hugo users is failing to pass a context
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: 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 "header/site-header.html" . }}
{{ partial "footer/scripts.html" . }} {{ partial "footer/scripts.html" . }}
``` ```
@@ -104,7 +104,7 @@ Note that the variant parameters are not made available to the underlying partia
The following `header.html` partial template is used for [spf13.com](http://spf13.com/): The following `header.html` partial template is used for [spf13.com](http://spf13.com/):
{{% code file="layouts/partials/header.html" download="header.html" %}} {{% code file="layouts/partials/header.html" download="header.html" %}}
```html ```
<!DOCTYPE html> <!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#"> <html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head> <head>
@@ -132,7 +132,7 @@ The `header.html` example partial was built before the introduction of block tem
The following `footer.html` partial template is used for [spf13.com](http://spf13.com/): The following `footer.html` partial template is used for [spf13.com](http://spf13.com/):
{{% code file="layouts/partials/footer.html" download="footer.html" %}} {{% code file="layouts/partials/footer.html" download="footer.html" %}}
```html ```
<footer> <footer>
<div> <div>
<p> <p>
Loaded 100 of 118 files, more files were not shown because too many files have changed in this diff. Show more