mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-15 01:56:36 -04:00
Clean up the code shortcode use
* No markdown needed * No code fence needed See #61
This commit is contained in:
Bjørn Erik Pedersen
parent
a1b2fd3bdc
commit
572b9e7590
@ -148,8 +148,7 @@ _END OF TERMS AND CONDITIONS_
|
||||
|
||||
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
|
||||
|
||||
{{% code file="apache-notice.txt" download="apache-notice.txt" %}}
|
||||
```
|
||||
{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
@ -163,5 +162,4 @@ distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
@ -37,11 +37,9 @@ hugo new <content-section>/<file-name.md>
|
||||
|
||||
We can use this pattern to create a new `.md` file in the `posts` section:
|
||||
|
||||
{{% code file="archetype-example.sh" %}}
|
||||
```
|
||||
{{< code file="archetype-example.sh" >}}
|
||||
hugo new posts/my-first-post.md
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note "Override Content Type in a New File" %}}
|
||||
To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
|
||||
@ -100,14 +98,12 @@ 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.
|
||||
|
||||
{{% code file="archetypes/default.md" %}}
|
||||
```
|
||||
{{< code file="archetypes/default.md" >}}
|
||||
+++
|
||||
tags = ["golang", "hugo"]
|
||||
categories = ["web development"]
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% warning "EOL Characters in Text Editors"%}}
|
||||
If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
|
||||
@ -117,11 +113,9 @@ 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:
|
||||
|
||||
{{% code file="new-post-from-default.sh" %}}
|
||||
```
|
||||
{{< code file="new-post-from-default.sh" >}}
|
||||
$ hugo new posts/my-new-post.md
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Hugo then creates a new markdown file with the following front matter:
|
||||
|
||||
@ -148,25 +142,21 @@ Suppose your site's `posts` section requires more sophisticated front matter tha
|
||||
|
||||
### Create a Custom Archetype
|
||||
|
||||
{{% code file="archetypes/posts.md"%}}
|
||||
```
|
||||
{{< code file="archetypes/posts.md">}}
|
||||
+++
|
||||
description = ""
|
||||
tags = ""
|
||||
categories = ""
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Use a Custom Archetype
|
||||
|
||||
With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
|
||||
|
||||
{{% code file="new-post-from-custom.sh" %}}
|
||||
```
|
||||
{{< code file="new-post-from-custom.sh" >}}
|
||||
$ hugo new posts/post-from-custom.md
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
|
||||
|
||||
@ -186,11 +176,9 @@ title = "post from custom archetype"
|
||||
|
||||
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" >}}
|
||||
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
|
||||
|
||||
@ -30,8 +30,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:
|
||||
|
||||
{{% code file="data/_authors/alice.toml" %}}
|
||||
```
|
||||
{{< code file="data/_authors/alice.toml" >}}
|
||||
givenName = "Alice" # or firstName as alias
|
||||
familyName = "Allison" # or lastName as alias
|
||||
displayName = "Alice Allison"
|
||||
@ -50,8 +49,7 @@ weight = 10
|
||||
|
||||
[params]
|
||||
random = "whatever you want"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
|
||||
|
||||
@ -116,8 +114,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:
|
||||
|
||||
{{% code file="layouts/partials/author-info.html" download="author-info.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
|
||||
{{ with .Author }}
|
||||
<h3>{{ .DisplayName }}</h3>
|
||||
<img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
|
||||
@ -128,8 +125,7 @@ Most articles feature a small section with information about the author at the e
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Who Published What?
|
||||
|
||||
@ -152,8 +148,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.
|
||||
|
||||
{{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}}
|
||||
```
|
||||
{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
|
||||
<ul>
|
||||
{{ range $author, $v := .Data.Terms }}
|
||||
{{ $profile := $.Authors.Get $author }}
|
||||
@ -164,8 +159,7 @@ In the next step we can create a template to list all authors of your website. L
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
|
||||
|
||||
@ -175,15 +169,13 @@ 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`.
|
||||
|
||||
{{% code file="layouts/taxonomy/author.html" download="author.html" %}}
|
||||
```
|
||||
{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
|
||||
{{ range .Data.Pages }}
|
||||
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
|
||||
<span>written by {{ .Author.DisplayName }}</span>
|
||||
{{ .Summary }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
|
||||
|
||||
|
||||
@ -57,11 +57,9 @@ 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:
|
||||
|
||||
{{% code file="content/meta/my-article.md" copy="false" %}}
|
||||
```
|
||||
{{< code file="content/meta/my-article.md" copy="false" >}}
|
||||
{{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}}
|
||||
|
||||
|
||||
@ -41,14 +41,12 @@ Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Bl
|
||||
|
||||
#### Example Task List Input
|
||||
|
||||
{{% code file="content/my-to-do-list.md" %}}
|
||||
```
|
||||
{{< code file="content/my-to-do-list.md" >}}
|
||||
- [ ] a task list item
|
||||
- [ ] list syntax required
|
||||
- [ ] incomplete
|
||||
- [x] completed
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example Task List Output
|
||||
|
||||
@ -120,12 +118,10 @@ 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)):
|
||||
|
||||
{{% code file="add-mathjax-to-page.html" %}}
|
||||
```
|
||||
{{< code file="add-mathjax-to-page.html" >}}
|
||||
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website.
|
||||
|
||||
@ -149,8 +145,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).
|
||||
|
||||
{{% code file="mathjax-markdown-solution.html" %}}
|
||||
```
|
||||
{{< code file="mathjax-markdown-solution.html" >}}
|
||||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
tex2jax: {
|
||||
@ -176,15 +171,13 @@ MathJax.Hub.Config({
|
||||
}
|
||||
});
|
||||
</script>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
|
||||
As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page.
|
||||
|
||||
{{% code file="mathjax-style.css" %}}
|
||||
```
|
||||
{{< code file="mathjax-style.css" >}}
|
||||
code.has-jax {
|
||||
font: inherit;
|
||||
font-size: 100%;
|
||||
@ -192,8 +185,7 @@ code.has-jax {
|
||||
border: inherit;
|
||||
color: #515151;
|
||||
}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body.
|
||||
|
||||
|
||||
@ -120,8 +120,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`:
|
||||
|
||||
{{% code file="config.toml" %}}
|
||||
```
|
||||
{{< code file="config.toml" >}}
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
pre = "<i class='fa fa-heart'></i>"
|
||||
@ -133,13 +132,11 @@ Here’s an example snippet pulled from a `config.toml`:
|
||||
pre = "<i class='fa fa-road'></i>"
|
||||
weight = -100
|
||||
url = "/getting-started/"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Here's the equivalent snippet in a `config.yaml`:
|
||||
|
||||
{{% code file="config.yml" %}}
|
||||
```
|
||||
{{< code file="config.yml" >}}
|
||||
---
|
||||
menu:
|
||||
docs:
|
||||
@ -153,8 +150,7 @@ menu:
|
||||
Weight: -100
|
||||
URL: "/getting-started/"
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`.
|
||||
|
||||
@ -23,8 +23,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:
|
||||
|
||||
{{% code file="config.toml" download="config.toml" %}}
|
||||
```
|
||||
{{< code file="config.toml" download="config.toml" >}}
|
||||
DefaultContentLanguage = "en"
|
||||
copyright = "Everything is mine"
|
||||
|
||||
@ -46,8 +45,7 @@ weight = 2
|
||||
linkedin = "lien-francais"
|
||||
[Languages.fr.navigation]
|
||||
help = "Aide"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Anything not defined in a `[Languages]` block will fall back to the global
|
||||
value for that key (e.g., `copyright` for the English [`en`] language).
|
||||
@ -66,8 +64,7 @@ Only the obvious non-global options can be overridden per language. Examples of
|
||||
Taxonomies and [Blackfriday configuration][config] can also be set per language:
|
||||
|
||||
|
||||
{{% code file="bf-config.toml" %}}
|
||||
```
|
||||
{{< code file="bf-config.toml" >}}
|
||||
[Taxonomies]
|
||||
tag = "tags"
|
||||
|
||||
@ -87,8 +84,7 @@ weight = 2
|
||||
title = "Français"
|
||||
[Languages.fr.Taxonomies]
|
||||
plaque = "plaques"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Translate Your Content
|
||||
|
||||
@ -127,8 +123,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:
|
||||
|
||||
{{% code file="layouts/partials/i18nlist.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/i18nlist.html" >}}
|
||||
{{ if .IsTranslated }}
|
||||
<h4>{{ i18n "translations" }}</h4>
|
||||
<ul>
|
||||
@ -139,8 +134,7 @@ To create a list of links to translated content, use a template similar to the f
|
||||
{{ end}}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language.
|
||||
|
||||
|
||||
@ -172,14 +172,12 @@ 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.
|
||||
|
||||
{{% code file="content/posts/old-post.md" %}}
|
||||
```
|
||||
{{< code file="content/posts/old-post.md" >}}
|
||||
---
|
||||
title: New Post
|
||||
slug: "new-post"
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This will render to the following destination according to Hugo's default behavior:
|
||||
|
||||
@ -195,15 +193,13 @@ 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.
|
||||
|
||||
{{% code file="content/posts/my-post.md" %}}
|
||||
```
|
||||
{{< code file="content/posts/my-post.md" >}}
|
||||
---
|
||||
title: My Post
|
||||
type: new
|
||||
layout: mylayout
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
<!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
|
||||
<!-- ### `path`
|
||||
|
||||
@ -213,14 +209,12 @@ 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:
|
||||
|
||||
{{% code file="content/posts/old-url.md" %}}
|
||||
```
|
||||
{{< code file="content/posts/old-url.md" >}}
|
||||
---
|
||||
title: Old URL
|
||||
url: /blog/new-url/
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Assuming your `baseURL` is [configured][config] to `https://yoursite.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
|
||||
|
||||
|
||||
@ -89,11 +89,9 @@ The `figure` shortcode can use the following named parameters:
|
||||
|
||||
#### Example `figure` Input
|
||||
|
||||
{{% code file="figure-input-example.md" %}}
|
||||
```
|
||||
{{< code file="figure-input-example.md" >}}
|
||||
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `figure` Output
|
||||
|
||||
@ -126,11 +124,9 @@ 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:
|
||||
|
||||
{{% code file="gist-input.md" %}}
|
||||
```
|
||||
{{< code file="gist-input.md" >}}
|
||||
{{</* gist spf13 7896402 "img.html" */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `gist` Output
|
||||
|
||||
@ -152,8 +148,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
|
||||
|
||||
#### Example `highlight` Input
|
||||
|
||||
{{% code file="content/tutorials/learn-html.md" %}}
|
||||
```
|
||||
{{< code file="content/tutorials/learn-html.md" >}}
|
||||
{{</* highlight html */>}}
|
||||
<section id="main">
|
||||
<div>
|
||||
@ -164,8 +159,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
|
||||
</div>
|
||||
</section>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `highlight` Output
|
||||
|
||||
@ -198,19 +192,15 @@ https://www.instagram.com/p/BWNjjyYFxVx/
|
||||
|
||||
#### Example `instagram` Input
|
||||
|
||||
{{% code file="instagram-input.md" %}}
|
||||
```
|
||||
{{< code file="instagram-input.md" >}}
|
||||
{{</* instagram BWNjjyYFxVx */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You also have the option to hide the caption:
|
||||
|
||||
{{% code file="instagram-input-hide-caption.md" %}}
|
||||
```
|
||||
{{< code file="instagram-input-hide-caption.md" >}}
|
||||
{{</* instagram BWNjjyYFxVx hidecaption */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `instagram` Output
|
||||
|
||||
@ -269,11 +259,9 @@ To embed slides from [Speaker Deck][], click on "< /> Embed" (u
|
||||
|
||||
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" >}}
|
||||
{{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### `speakerdeck` Example Output
|
||||
|
||||
@ -301,11 +289,9 @@ https://twitter.com/spf13/status/877500564405444608
|
||||
|
||||
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" >}}
|
||||
{{</* tweet 877500564405444608 */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `tweet` Output
|
||||
|
||||
@ -335,11 +321,9 @@ https://vimeo.com/channels/staffpicks/146022717
|
||||
|
||||
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" >}}
|
||||
{{</* vimeo 146022717 */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `vimeo` Output
|
||||
|
||||
@ -378,30 +362,24 @@ 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:
|
||||
|
||||
{{% code file="example-youtube-input.md" %}}
|
||||
```
|
||||
{{< code file="example-youtube-input.md" >}}
|
||||
{{</* youtube w7Ft2ymGmfc */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named an unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
|
||||
|
||||
|
||||
{{% code file="example-youtube-input-with-autoplay.md" %}}
|
||||
```
|
||||
{{< code file="example-youtube-input-with-autoplay.md" >}}
|
||||
{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `youtube` Output
|
||||
|
||||
Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
|
||||
|
||||
{{% code file="example-youtube-output.html" %}}
|
||||
```
|
||||
{{< code file="example-youtube-output.html" >}}
|
||||
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `youtube` Display
|
||||
|
||||
|
||||
@ -56,8 +56,7 @@ Be careful to enter <code><!--more--></code> exactly
|
||||
|
||||
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" >}}
|
||||
{{ range first 10 .Data.Pages }}
|
||||
<article>
|
||||
<!-- this <div> includes the title summary -->
|
||||
@ -73,8 +72,7 @@ You can show content summaries with the following code. You could use the follow
|
||||
{{ end }}
|
||||
</article>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
|
||||
|
||||
|
||||
@ -49,8 +49,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
|
||||
|
||||
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" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
@ -64,15 +63,13 @@ The following is an example of a very basic [single page template][]:
|
||||
</aside>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Template Example: TOC Partial
|
||||
|
||||
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter][] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals][] in your templating:
|
||||
|
||||
{{% code file="layouts/partials/toc.html" download="toc.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
|
||||
{{ if and (gt .WordCount 400 ) (ne .Params.toc "false") }}
|
||||
<aside>
|
||||
<header>
|
||||
@ -81,8 +78,7 @@ The following is a [partial template][partials] that adds slightly more logic fo
|
||||
{{.TableOfContents}}
|
||||
</aside>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
With the preceding example, even pages with > 400 words *and* `toc` not set to `false` will not render a table of contents if there are no headings in the page for the `{{.TableOfContents}}` variable to pull from.
|
||||
|
||||
@ -44,8 +44,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:
|
||||
|
||||
{{% code file="content/events/my-first-event.md" copy="false" %}}
|
||||
```
|
||||
{{< code file="content/events/my-first-event.md" copy="false" >}}
|
||||
+++
|
||||
title = My First Event
|
||||
date = "2016-06-24T19:20:04-07:00"
|
||||
@ -53,8 +52,7 @@ description = "Today is my 36th birthday. How time flies."
|
||||
type = "event"
|
||||
layout = "birthday"
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/ my-first-event.md` is of type `event` and should render using the `birthday` layout.
|
||||
|
||||
|
||||
@ -31,21 +31,17 @@ For example, if one of your [sections][] is called `post` and you want to adjust
|
||||
|
||||
### YAML Permalinks Configuration Example
|
||||
|
||||
{{% code file="config.yml" copy="false" %}}
|
||||
```
|
||||
{{< code file="config.yml" copy="false" >}}
|
||||
permalinks:
|
||||
post: /:year/:month/:title/
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### TOML Permalinks Configuration Example
|
||||
|
||||
{{% code file="config.toml" copy="false" %}}
|
||||
```
|
||||
{{< code file="config.toml" copy="false" >}}
|
||||
[permalinks]
|
||||
post = "/:year/:month/:title/"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`.
|
||||
|
||||
@ -98,28 +94,24 @@ Let's assume you create a new piece of content at `content/posts/my-awesome-blog
|
||||
|
||||
#### TOML Front Matter
|
||||
|
||||
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
|
||||
```
|
||||
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
|
||||
+++
|
||||
aliases = [
|
||||
"/posts/my-original-url/",
|
||||
"/2010/01/01/even-earlier-url.html"
|
||||
]
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### YAML Front Matter
|
||||
|
||||
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
|
||||
```
|
||||
{{< code file="content/posts/my-awesome-post.md" copy="false" >}}
|
||||
---
|
||||
aliases:
|
||||
- /posts/my-original-url/
|
||||
- /2010/01/01/even-earlier-url.html
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `yoursite.com/posts/my-original-url/` will be immediately redirected to `yoursite.com/posts/my-awesome-blog-post/`.
|
||||
|
||||
|
||||
@ -68,11 +68,9 @@ 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:
|
||||
|
||||
{{% code file="install-go.sh" %}}
|
||||
```
|
||||
{{< code file="install-go.sh" >}}
|
||||
brew install go
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Install Go via GVM
|
||||
|
||||
|
||||
@ -52,11 +52,9 @@ hugo new functions/newfunction.md
|
||||
|
||||
The archetype for `functions` according to the Hugo theme is as follows:
|
||||
|
||||
{{% code file="archetypes/functions.md" %}}
|
||||
```
|
||||
{{< code file="archetypes/functions.md" >}}
|
||||
{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### New Function Required Fields
|
||||
|
||||
@ -104,11 +102,9 @@ hugo new tutorials/my-new-tutorial.md
|
||||
|
||||
The archetype for the `tutorials` content type is as follows:
|
||||
|
||||
{{% code file="archetypes/tutorials.md" %}}
|
||||
```
|
||||
{{< code file="archetypes/tutorials.md" >}}
|
||||
{{< readfile file="/themes/gohugoioTheme/archetypes/tutorials.md">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Add Code Blocks
|
||||
|
||||
@ -192,8 +188,7 @@ This example HTML code block tells Hugo users the following:
|
||||
|
||||
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" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
@ -211,8 +206,7 @@ The output of this example will render to the Hugo docs as follows:
|
||||
</article>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
<!-- #### Output Code Block
|
||||
|
||||
@ -276,13 +270,11 @@ Use the `note` shortcode when you want to draw attention to information subtly.
|
||||
|
||||
#### Example `note` Input
|
||||
|
||||
{{% code file="note-with-heading.md" %}}
|
||||
```
|
||||
{{< code file="note-with-heading.md" >}}
|
||||
{{%/* note */%}}
|
||||
Here is a piece of information I would like to draw your **attention** to.
|
||||
{{%/* /note */%}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `note` Output
|
||||
|
||||
@ -306,13 +298,11 @@ Use the `tip` shortcode when you want to give the reader advice. `tip`, like `no
|
||||
|
||||
#### Example `tip` Input
|
||||
|
||||
{{% code file="using-tip.md" %}}
|
||||
```
|
||||
{{< code file="using-tip.md" >}}
|
||||
{{%/* tip */%}}
|
||||
Here's a bit of advice to improve your productivity with Hugo.
|
||||
{{%/* /tip */%}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `tip` Output
|
||||
|
||||
@ -336,13 +326,11 @@ Use the `warning` shortcode when you want to draw the user's attention to someth
|
||||
|
||||
#### Example `warning` Input
|
||||
|
||||
{{% code file="warning-admonition-input.md" %}}
|
||||
```
|
||||
{{< code file="warning-admonition-input.md" >}}
|
||||
{{%/* warning */%}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{%/* /warning */%}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Example `warning` Output
|
||||
|
||||
|
||||
@ -59,8 +59,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:
|
||||
|
||||
{{% code file="theme.toml" download="theme.toml" %}}
|
||||
```
|
||||
{{< code file="theme.toml" download="theme.toml" >}}
|
||||
name = ""
|
||||
license = "MIT"
|
||||
licenselink = "https://github.com/<YOURNAME>/<YOURTHEME>/blob/master/LICENSE.md"
|
||||
@ -79,8 +78,7 @@ min_version = 0.19
|
||||
name = ""
|
||||
homepage = ""
|
||||
repo = ""
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The following fields are required:
|
||||
|
||||
@ -133,8 +131,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:
|
||||
|
||||
{{% code file="README.md" download="README.md" %}}
|
||||
```
|
||||
{{< code file="README.md" download="README.md" >}}
|
||||
|
||||
# Theme Title
|
||||
|
||||
@ -143,8 +140,7 @@ You can download the following `README.md` as an outline:
|
||||
|
||||
|
||||
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note "Screenshots in your `README.md`"%}}
|
||||
If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path.
|
||||
|
||||
@ -51,16 +51,14 @@ This code snippet---in the form of a [partial template][partials]---allows you t
|
||||
3. Sort the terms associated with the taxonomy by popularity.
|
||||
4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content.
|
||||
|
||||
{{% code file="grab-top-two-tags.html" %}}
|
||||
```
|
||||
{{< code file="grab-top-two-tags.html" >}}
|
||||
<ul class="most-popular-tags">
|
||||
{{ $t := $.Site.GetPage "taxonomyTerm" "tags" }}
|
||||
{{ range first 2 $t.Data.Terms.ByCount }}
|
||||
<li>{{.}}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
[partials]: /templates/partials/
|
||||
|
||||
@ -29,8 +29,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:
|
||||
|
||||
{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context" : "http://schema.org",
|
||||
@ -38,8 +37,7 @@ The last two examples may look strange but can be very useful. For example, the
|
||||
"image" : {{ apply .Params.images "absURL" "." }}
|
||||
}
|
||||
</script>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
|
||||
|
||||
|
||||
@ -36,8 +36,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.
|
||||
|
||||
{{% code file="partials/templates/random-tweets.html" download="tweets.html" %}}
|
||||
```
|
||||
{{< code file="partials/templates/random-tweets.html" download="tweets.html" >}}
|
||||
{{ range where $.Site.Data.tweets.tweet "date" "ge" (now.AddDate -2 0 0) | shuffle }}
|
||||
<div class="item">
|
||||
<blockquote>
|
||||
@ -50,5 +49,4 @@ Let's assume you want to grab Tweets from the last two years and present them in
|
||||
</blockquote>
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
@ -35,8 +35,7 @@ You can use `after` in combination with the [`first` function][] and Hugo's [pow
|
||||
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
|
||||
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
|
||||
|
||||
{{% code file="layouts/section/articles.html" download="articles.html" %}}
|
||||
```
|
||||
{{< code file="layouts/section/articles.html" download="articles.html" >}}
|
||||
{{ define "main" }}
|
||||
<section class="row featured-article">
|
||||
<h2>Featured Article</h2>
|
||||
@ -59,8 +58,7 @@ You can use `after` in combination with the [`first` function][] and Hugo's [pow
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[`first` function]: /functions/first/
|
||||
[list/section page]: /templates/section-templates/
|
||||
|
||||
@ -59,8 +59,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:
|
||||
|
||||
{{% code file="layouts/partial/post-tag-list.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="layouts/partial/post-tag-list.html" copy="false" >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
@ -76,14 +75,11 @@ If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% code file="layouts/partial/post-tag-link.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="layouts/partial/post-tag-link.html" copy="false" >}}
|
||||
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This works, but the complexity of `post-tag-list.html` is fairly high. The Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.
|
||||
|
||||
@ -103,16 +99,14 @@ 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:
|
||||
|
||||
{{% 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" >}}
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ delimit (apply (apply (sort .) "partial" "post-tag-link" ".") "chomp" ".") ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
`apply` does not work when receiving the sequence as an argument through a pipeline.
|
||||
|
||||
@ -21,12 +21,10 @@ aliases: []
|
||||
|
||||
An example:
|
||||
|
||||
{{% code file="base64-input.html" %}}
|
||||
```
|
||||
{{< code file="base64-input.html" >}}
|
||||
<p>Hello world = {{ "Hello world" | base64Encode }}</p>
|
||||
<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% output file="base-64-output.html" %}}
|
||||
```
|
||||
|
||||
@ -31,8 +31,7 @@ needsexamples: false
|
||||
|
||||
`default` function examples reference the following content page:
|
||||
|
||||
{{% code file="content/posts/default-function-example.md" %}}
|
||||
```
|
||||
{{< code file="content/posts/default-function-example.md" >}}
|
||||
---
|
||||
title: Sane Defaults
|
||||
seo_title:
|
||||
@ -41,8 +40,7 @@ font:
|
||||
oldparam: The default function helps make your templating DRYer.
|
||||
newparam:
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
`default` can be written in more than one way:
|
||||
|
||||
@ -55,12 +53,10 @@ 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:
|
||||
|
||||
{{% code file="variable-as-default-value.html" nocopy="true" %}}
|
||||
```
|
||||
{{< code file="variable-as-default-value.html" nocopy="true" >}}
|
||||
{{$old := .Params.oldparam }}
|
||||
<p>{{ .Params.newparam | default $old }}</p>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Which would return:
|
||||
|
||||
@ -70,11 +66,9 @@ Which would return:
|
||||
|
||||
And then using dot notation
|
||||
|
||||
{{% code file="dot-notation-default-value.html" %}}
|
||||
```
|
||||
{{< code file="dot-notation-default-value.html" >}}
|
||||
<title>{{ .Params.seo_title | default .Title }}</title>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Which would return
|
||||
|
||||
@ -88,18 +82,14 @@ The following have equivalent return values but are far less terse. This demonst
|
||||
|
||||
Using `if`:
|
||||
|
||||
{{% code file="if-instead-of-default.html" nocopy="true" %}}
|
||||
```
|
||||
{{< code file="if-instead-of-default.html" nocopy="true" >}}
|
||||
<title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title>
|
||||
=> Sane Defaults
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Using `with`:
|
||||
|
||||
{{% code file="with-instead-of-default.html" nocopy="true" %}}
|
||||
```
|
||||
{{< code file="with-instead-of-default.html" nocopy="true" >}}
|
||||
<title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title>
|
||||
=> Sane Defaults
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
@ -33,20 +33,16 @@ 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:
|
||||
|
||||
{{% code file="delimit-example-front-matter.toml" nocopy="true" %}}
|
||||
```
|
||||
{{< code file="delimit-example-front-matter.toml" nocopy="true" >}}
|
||||
+++
|
||||
title: I love Delimit
|
||||
#tags: [ "tag1", "tag2", "tag3" ]
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% code file="delimit-page-tags-input.html" %}}
|
||||
```
|
||||
{{< code file="delimit-page-tags-input.html" >}}
|
||||
<p>Tags: {{ delimit .Params.tags ", " }}</p>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% output file="delimit-page-tags-output.html" %}}
|
||||
```
|
||||
@ -56,11 +52,9 @@ title: I love Delimit
|
||||
|
||||
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" >}}
|
||||
Tags: {{ delimit .Params.tags ", " ", and " }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% output file="delimit-page-tags-final-and-output.html" %}}
|
||||
```
|
||||
|
||||
@ -26,21 +26,17 @@ aliases: []
|
||||
|
||||
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" >}}
|
||||
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="{{ .fill }}" width="{{ .size }}" height="{{ .size }}" viewBox="0 0 32 32" aria-label="External Link">
|
||||
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
|
||||
</svg>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
These values can be stored in one object with `dict` and passed to the partial:
|
||||
|
||||
{{% code file="layouts/_default/list.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/list.html" >}}
|
||||
{{ partial "svg/link-ext.svg" (dict "fill" "#01589B" "size" 10 "width" 20 ) }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
|
||||
|
||||
@ -25,8 +25,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]:
|
||||
|
||||
{{% code file="layouts/partials/related-posts.html" download="related-posts.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/related-posts.html" download="related-posts.html" >}}
|
||||
<ul>
|
||||
{{ $page_link := .Permalink }}
|
||||
{{ $tags := .Params.tags }}
|
||||
@ -38,8 +37,7 @@ The following is an example of a "related posts" [partial template][partials] th
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This is also very useful to use as `AND` filters when combined with where:
|
||||
|
||||
|
||||
@ -35,24 +35,20 @@ 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>`:
|
||||
|
||||
{{% code file="check-title-length.html" %}}
|
||||
```
|
||||
{{< code file="check-title-length.html" >}}
|
||||
<header>
|
||||
<h1{{if gt (len .Title) 80}} class="long-title"{{end}}>{{.Title}}</h1>
|
||||
</header>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## `len` Example 2: Counting Pages with `where`
|
||||
|
||||
The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]:
|
||||
|
||||
{{% code file="how-many-posts.html" %}}
|
||||
```
|
||||
{{< code file="how-many-posts.html" >}}
|
||||
{{ $posts := (where .Site.RegularPages "Section" "==" "post") }}
|
||||
{{ $postCount := len $posts }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Note the use of `.RegularPages`, a [site variable][] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates][].
|
||||
|
||||
|
||||
@ -52,12 +52,10 @@ image: my-post-image.jpg
|
||||
|
||||
You can then concatenate the `image` value (string) with the path to your `images` directory in `static` and leverage a URL-related templating function for increased flexibility:
|
||||
|
||||
{{% code file="partials/head/twitter-card.html" %}}
|
||||
```
|
||||
{{< code file="partials/head/twitter-card.html" >}}
|
||||
{{$socialimage := add "images/" .Params.image}}
|
||||
<meta name="twitter:image" content="{{ $socialimage | absURL }}">
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The `add` example above makes use of the [`absURL` function](/functions/absurl/). `absURL` and its relative companion `relURL` is the recommended way to construct URLs in Hugo.
|
||||
|
||||
@ -27,11 +27,9 @@ The `partialCached` template function can offer significant performance gains fo
|
||||
|
||||
You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section:
|
||||
|
||||
{{% code file="partial-cached-example.html" %}}
|
||||
```
|
||||
{{< code file="partial-cached-example.html" >}}
|
||||
{{ partialCached "footer.html" . .Section }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
|
||||
|
||||
|
||||
@ -29,8 +29,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:
|
||||
|
||||
{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}}
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context" : "http://schema.org",
|
||||
@ -38,8 +37,7 @@ The last two examples may look strange but can be very useful. For example, the
|
||||
"image" : {{ apply .Params.images "absURL" "." }}
|
||||
}
|
||||
</script>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `<script>` tags. See [the safeJS template function][safejs] for examples of how to tell Hugo not to escape strings inside of such tags.
|
||||
|
||||
|
||||
@ -24,26 +24,22 @@ 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]:
|
||||
|
||||
{{% code file="config.toml" copy="false" %}}
|
||||
```
|
||||
{{< code file="config.toml" copy="false" >}}
|
||||
[[menu.main]]
|
||||
name = "IRC: #golang at freenode"
|
||||
url = "irc://irc.freenode.net/#golang"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
|
||||
|
||||
{{% code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}}
|
||||
<!-- This unordered list may be part of a sidebar menu -->
|
||||
<ul>
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This partial would produce the following HTML output:
|
||||
|
||||
@ -58,14 +54,12 @@ This partial would produce the following HTML output:
|
||||
|
||||
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" >}}
|
||||
<!-- This unordered list may be part of a sidebar menu -->
|
||||
<ul>
|
||||
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
With the `.URL` page variable piped through `safeURL`, we get the desired output:
|
||||
|
||||
|
||||
@ -20,14 +20,12 @@ draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
{{% code file="shuffle-input.html" %}}
|
||||
```
|
||||
{{< code file="shuffle-input.html" >}}
|
||||
<!-- Shuffled sequence = -->
|
||||
<div>{{ shuffle (seq 1 5) }}</div>
|
||||
<!-- Shuffled slice = -->
|
||||
<div>{{ shuffle (slice "foo" "bar" "buzz") }}</div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This example would return the following:
|
||||
|
||||
|
||||
@ -23,12 +23,10 @@ toc: false
|
||||
|
||||
One use case is the concatenation of elements in combination with the [`delimit` function][]:
|
||||
|
||||
{{% code file="slice.html" %}}
|
||||
```
|
||||
{{< code file="slice.html" >}}
|
||||
{{ delimit (slice "foo" "bar" "buzz") ", " }}
|
||||
<!-- returns the string "foo, bar, buzz" -->
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
[`delimit` function]: /functions/delimit/
|
||||
|
||||
@ -33,16 +33,14 @@ The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"`
|
||||
|
||||
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" >}}
|
||||
{{$time := time (int .Params.addDate)}}
|
||||
=> $time = 1489276800
|
||||
{{$time.Month}}
|
||||
=> "March"
|
||||
{{$monthindex := printf "%d" $time.Month }}
|
||||
=> $monthindex = 3
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
[int]: /functions/int/
|
||||
|
||||
@ -23,11 +23,9 @@ 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.
|
||||
|
||||
{{% code file="time-passed.html" %}}
|
||||
```
|
||||
{{< code file="time-passed.html" >}}
|
||||
{{ div (sub now.Unix .Lastmod.Unix) 86400 }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Since both values are integers, they can be subtracted and then divided by the number of seconds in a day (i.e., `60 * 60 * 24 == 86400`).
|
||||
|
||||
|
||||
@ -20,20 +20,17 @@ relatedfuncs: []
|
||||
|
||||
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">}}
|
||||
+++
|
||||
title = "The World's Greatest City"
|
||||
location = "Chicago IL"
|
||||
tags = ["pizza","beer","hot dogs"]
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The following might be used as a partial within a [single page template][singletemplate]:
|
||||
|
||||
{{% code file="layouts/partials/content-header.html" download="content-header.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/content-header.html" download="content-header.html" >}}
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
{{ with .Params.location }}
|
||||
@ -50,8 +47,7 @@ The following might be used as a partial within a [single page template][singlet
|
||||
</ul>
|
||||
{{ end }}
|
||||
</header>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs.
|
||||
|
||||
|
||||
@ -91,27 +91,23 @@ The following logical operators are vailable with `where`:
|
||||
|
||||
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" >}}
|
||||
{{ $v1 := where .Site.Pages "Params.a" "v1" }}
|
||||
{{ $v2 := where .Site.Pages "Params.b" "v2" }}
|
||||
{{ $filtered := $v1 | intersect $v2 }}
|
||||
{{ range $filtered }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Use `where` with `first`
|
||||
|
||||
The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`):
|
||||
|
||||
{{% code file="where-with-first.html" %}}
|
||||
```
|
||||
{{< code file="where-with-first.html" >}}
|
||||
{{ range first 5 (where .Data.Pages "Section" "post") }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Nest `where` Clauses
|
||||
|
||||
|
||||
@ -22,12 +22,10 @@ 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:
|
||||
|
||||
{{% code file="layouts/partials/twitter.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/twitter.html" >}}
|
||||
{{with .Site.Params.twitteruser}}<span class="twitter">
|
||||
<a href="https://twitter.com/{{.}}" rel="author">
|
||||
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
|
||||
alt="Twitter"></a>
|
||||
</span>{{end}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
@ -36,8 +36,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][]:
|
||||
|
||||
{{% code file="config.yml"%}}
|
||||
```
|
||||
{{< code file="config.yml">}}
|
||||
---
|
||||
baseURL: "https://yoursite.example.com/"
|
||||
title: "My Hugo Site"
|
||||
@ -53,15 +52,13 @@ params:
|
||||
- "foo2"
|
||||
SidebarRecentLimit: 5
|
||||
...
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### All Variables, YAML
|
||||
|
||||
The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
|
||||
|
||||
{{% code file="config.yml" download="config.yml" %}}
|
||||
```
|
||||
{{< code file="config.yml" download="config.yml" >}}
|
||||
---
|
||||
archetypeDir: "archetypes"
|
||||
# hostname (and path) to the root, e.g. http://spf13.com/
|
||||
@ -170,8 +167,7 @@ taxonomies:
|
||||
- category: "categories"
|
||||
- tag: "tags"
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## TOML Configuration
|
||||
|
||||
@ -199,8 +195,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.
|
||||
|
||||
{{% code file="config.toml" download="config.toml"%}}
|
||||
```
|
||||
{{< code file="config.toml" download="config.toml">}}
|
||||
+++
|
||||
archetypeDir = "archetypes"
|
||||
# hostname (and path) to the root, e.g. http://spf13.com/
|
||||
@ -309,8 +304,7 @@ watch = true
|
||||
category = "categories"
|
||||
tag = "tags"
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
|
||||
@ -360,26 +354,22 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
|
||||
2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
|
||||
{{% /note %}}
|
||||
|
||||
{{% code file="bf-config.toml" %}}
|
||||
```
|
||||
{{< code file="bf-config.toml" >}}
|
||||
[blackfriday]
|
||||
angledQuotes = true
|
||||
fractions = false
|
||||
plainIDAnchors = true
|
||||
extensions = ["hardLineBreak"]
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% code file="bf-config.yml" %}}
|
||||
```
|
||||
{{< code file="bf-config.yml" >}}
|
||||
blackfriday:
|
||||
angledQuotes: true
|
||||
fractions: false
|
||||
plainIDAnchors: true
|
||||
extensions:
|
||||
- hardLineBreak
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Configure Additional Output Formats
|
||||
|
||||
|
||||
@ -47,11 +47,9 @@ 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:
|
||||
|
||||
{{% code file="install-with-homebrew.sh" %}}
|
||||
```
|
||||
{{< code file="install-with-homebrew.sh" >}}
|
||||
brew install hugo
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.
|
||||
|
||||
@ -59,11 +57,9 @@ 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:
|
||||
|
||||
{{% code file="install-with-chocolatey.ps1" %}}
|
||||
```
|
||||
{{< code file="install-with-chocolatey.ps1" >}}
|
||||
choco install hugo -confirm
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Source
|
||||
|
||||
@ -79,13 +75,11 @@ Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored
|
||||
|
||||
#### Fetch from GitHub
|
||||
|
||||
{{% code file="from-gh.sh" %}}
|
||||
```
|
||||
{{< code file="from-gh.sh" >}}
|
||||
go get github.com/kardianos/govendor
|
||||
govendor get github.com/gohugoio/hugo
|
||||
go install github.com/gohugoio/hugo
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
`govendor get` will fetch Hugo and all its dependent libraries to `$GOPATH/src/github.com/gohugoio/hugo`, and `go install` compiles everything into a final `hugo` (or `hugo.exe`) executable inside `$GOPATH/bin/`.
|
||||
|
||||
@ -131,21 +125,17 @@ 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:
|
||||
|
||||
{{% code file="install-brew.sh" %}}
|
||||
```
|
||||
{{< code file="install-brew.sh" >}}
|
||||
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
#### Step 2: Run the `brew` Command to Install `hugo`
|
||||
|
||||
Installing Hugo using `brew` is as easy as the following:
|
||||
|
||||
{{% code file="install-brew.sh" %}}
|
||||
```
|
||||
{{< code file="install-brew.sh" >}}
|
||||
brew install hugo
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If Homebrew is working properly, you should see something similar to the following:
|
||||
|
||||
|
||||
@ -94,11 +94,9 @@ 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.
|
||||
|
||||
{{% code file="create-new-book-review-post.sh" %}}
|
||||
```
|
||||
{{< code file="create-new-book-review-post.sh" >}}
|
||||
hugo new post/good-to-great.md
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You should then see the following output:
|
||||
|
||||
@ -140,8 +138,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*:
|
||||
|
||||
{{% code file="good-to-great-start.md" %}}
|
||||
```
|
||||
{{< code file="good-to-great-start.md" >}}
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
draft = true
|
||||
@ -149,8 +146,7 @@ title = "Good to Great Book Review"
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Step 4. Serve Content
|
||||
|
||||
@ -233,19 +229,15 @@ 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:
|
||||
|
||||
{{% code file="clone-robust-theme" %}}
|
||||
```
|
||||
{{< code file="clone-robust-theme" >}}
|
||||
git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now let's start Hugo's server again but with the addition of the `-theme` flag for Robust:
|
||||
|
||||
{{% code file="hugo-server-with-theme.sh" %}}
|
||||
```
|
||||
{{< code file="hugo-server-with-theme.sh" >}}
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You should see an output to the console similar to the following:
|
||||
|
||||
@ -310,19 +302,15 @@ 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:
|
||||
|
||||
{{% code file="clone-bleak-theme.sh" %}}
|
||||
```
|
||||
{{< code file="clone-bleak-theme.sh" >}}
|
||||
cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now restart the server with our new theme flag:
|
||||
|
||||
{{% code file="run-server-with-bleak.sh" %}}
|
||||
```
|
||||
{{< code file="run-server-with-bleak.sh" >}}
|
||||
hugo server --theme=hugo-theme-bleak --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Our website is now using the `bleak` theme at <http://localhost:1313>, which should look similar to the following screenshot:
|
||||
|
||||
@ -332,26 +320,22 @@ 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:
|
||||
|
||||
{{% code file="restart-with-robust-sh" %}}
|
||||
```
|
||||
{{< code file="restart-with-robust-sh" >}}
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Update Our `config.toml`
|
||||
|
||||
Our website is currently using the dummy values specified in `bookshelf/config.toml`, which were auto-generated with `hugo new site bookshelf`. Let's update the configuration:
|
||||
|
||||
{{% code file="updated-config.toml" %}}
|
||||
```
|
||||
{{< code file="updated-config.toml" >}}
|
||||
baseURL = "http://example.org/"
|
||||
languageCode = "en-us"
|
||||
title = "Shekhar Gulati Book Reviews"
|
||||
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Watch Your Site Reload Instantly
|
||||
|
||||
@ -408,23 +392,19 @@ 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:
|
||||
|
||||
{{% code file="create-new-li-html.sh" %}}
|
||||
```
|
||||
{{< code file="create-new-li-html.sh" >}}
|
||||
cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Copy the content shown below into the new `li.html`. When contrasting this with the `li.html` that ships with the Robust theme, you'll notice we have removed details of the book so that only the image is shown:
|
||||
|
||||
{{% code file="layouts/_default/li.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/li.html" >}}
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now, the website should render similar to the following screenshot:
|
||||
|
||||
@ -434,27 +414,22 @@ 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:
|
||||
|
||||
{{% code file="create-new-default-foot.sh" %}}
|
||||
```
|
||||
{{< code file="create-new-default-foot.sh" >}}
|
||||
cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now add the following to our new `default_foot.html` partial template:
|
||||
|
||||
{{% code file="layouts/partials/default_foot.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/default_foot.html" >}}
|
||||
<footer class="site">
|
||||
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}© {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
|
||||
<p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
|
||||
</footer>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
So far we are using the default image, but we would like to use the book image so that we can relate to the book. Every book review will define a configuration setting in its front matter. Update the content and front matter of `good-to-great.md` as shown below.
|
||||
|
||||
{{% code file="content/post/good-to-great.md" %}}
|
||||
```
|
||||
{{< code file="content/post/good-to-great.md" >}}
|
||||
+++
|
||||
date = "2017-02-19T21:09:05-06:00"
|
||||
draft = true
|
||||
@ -463,8 +438,7 @@ image = "good-to-great.jpg"
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Grab a (legal) image from somewhere, name it `good-to-great.jpg`, and place it in the `bookshelf/static/images` directory.
|
||||
|
||||
|
||||
@ -39,11 +39,9 @@ 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:
|
||||
|
||||
{{% code file="install-openssh.sh" %}}
|
||||
```
|
||||
{{< code file="install-openssh.sh" >}}
|
||||
sudo apt-get install openssh-client
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Then generate your ssh key by entering the following commands:
|
||||
|
||||
|
||||
@ -47,29 +47,23 @@ 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`:
|
||||
|
||||
{{% code file="hugo-new-site.sh" %}}
|
||||
```
|
||||
{{< code file="hugo-new-site.sh" >}}
|
||||
hugo new site hugo-wercker-example
|
||||
cd hugo-wercker-example
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory.
|
||||
|
||||
{{% code file="clone-herring-cove-theme.sh" %}}
|
||||
```
|
||||
{{< code file="clone-herring-cove-theme.sh" >}}
|
||||
cd themes
|
||||
git clone https://github.com/spf13/herring-cove.git
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Cloning the project from the command line will conflict with our own version control. So, we need to remove the external git configuration that came with the clone of Herring Cove:
|
||||
|
||||
{{% code file="remove-herring-cove-git.sh" %}}
|
||||
```
|
||||
{{< code file="remove-herring-cove-git.sh" >}}
|
||||
rm -rf herring-cove/.git
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
We need content for Hugo to build. Let's add a quick `/about` page:
|
||||
|
||||
@ -83,11 +77,9 @@ 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:
|
||||
|
||||
{{% code file="hugo-build-undraft.sh" %}}
|
||||
```
|
||||
{{< code file="hugo-build-undraft.sh" >}}
|
||||
hugo undraft content/about.md
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Once the website is build, t's a good idea to run the following command to start a local server and ensure you're changes have been implemented:
|
||||
|
||||
@ -109,19 +101,15 @@ git init
|
||||
|
||||
Running `git status` at this point will show you the following entries: the `config.toml` file, the `themes` directory, the `contents` directory, and the `public` directory. However, we don't want the `public` directory version controlled because Wercker is responsible for generating the finished website later on. Therefore, we'll add a `.gitignore` file to our project that will exclude the `/public` directory from being tracked by Git:
|
||||
|
||||
{{% code file="gitignore.sh" %}}
|
||||
```
|
||||
{{< code file="gitignore.sh" >}}
|
||||
echo "/public" >> .gitignore
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Wercker might complain when we try to build the site later on because we currently do not have any static files outside of the `themes` directory. We simply have to add *any* file to the static folder to prevent Wercker from complaining. To keep this guide simple, let's add a `robots.txt`. The following command creates the file in `/static`. The contents of the `robots.txt` lets search engines know they have full access to crawl the published website:
|
||||
|
||||
{{% code file="addrobotstxt.sh" %}}
|
||||
```
|
||||
{{< code file="addrobotstxt.sh" >}}
|
||||
echo "User-agent: *\nDisallow:" > static/robots.txt
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Now we need to add (i.e., [stage [see Git documentation]][gitbasics]) and commit all of our changes in the repository into Git:
|
||||
|
||||
@ -135,12 +123,10 @@ 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:
|
||||
|
||||
{{% code file="setup-gh-repo.sh" %}}
|
||||
```
|
||||
{{< code file="setup-gh-repo.sh" >}}
|
||||
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
|
||||
git push -u origin master
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
![][2]
|
||||
|
||||
@ -230,8 +216,7 @@ We're not going to use any of the advanced features of Hugo-Build in this guide.
|
||||
The docs are a work in progress. As such, the `version` represented in this guide may not represent the version you've been using for local development. Be sure to use the appropriate Hugo version for your build step.
|
||||
{{% /warning %}}
|
||||
|
||||
{{% code file="wercker-build-step.yml" %}}
|
||||
```
|
||||
{{< code file="wercker-build-step.yml" >}}
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
@ -239,17 +224,14 @@ build:
|
||||
version: "0.17"
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
We can conclude this first step by pushing our `wercker.yml` to our GitHub repository and then seeing the magic at work within Wercker's interface.
|
||||
|
||||
{{% code file="push-wecker-to-gh.sh" %}}
|
||||
```
|
||||
{{< code file="push-wecker-to-gh.sh" >}}
|
||||
git commit -a -m "Add wercker.yml"
|
||||
git push origin master
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If completed and successful, a green check mark should appear in the commit column of your first build. However, this is only the build step. We still need to deploy the website to our free hosting on GitHub Pages. If you would like more details about the build, you can click the commit hash.
|
||||
|
||||
@ -259,8 +241,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:
|
||||
|
||||
{{% code file="wercker.yml" %}}
|
||||
```
|
||||
{{< code file="wercker.yml" >}}
|
||||
box: debian
|
||||
build:
|
||||
steps:
|
||||
@ -276,8 +257,7 @@ deploy:
|
||||
token: $GIT_TOKEN
|
||||
domain: hugo-wercker.ig.nore.me
|
||||
basedir: public
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### How does the GitHub Pages Configuration Work?
|
||||
|
||||
|
||||
@ -96,12 +96,10 @@ git worktree add -B gh-pages public upstream/gh-pages
|
||||
|
||||
Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
|
||||
|
||||
{{% code file="commit-gh-pages-files.sh"%}}
|
||||
```
|
||||
{{< code file="commit-gh-pages-files.sh">}}
|
||||
hugo
|
||||
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
|
||||
|
||||
@ -122,8 +120,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:
|
||||
|
||||
{{% code file="publish_to_ghpages.sh" %}}
|
||||
```
|
||||
{{< code file="publish_to_ghpages.sh" >}}
|
||||
#!/bin/sh
|
||||
|
||||
DIR=$(dirname "$0")
|
||||
@ -153,8 +150,7 @@ hugo
|
||||
|
||||
echo "Updating gh-pages branch"
|
||||
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
|
||||
|
||||
|
||||
@ -37,8 +37,7 @@ cd your-hugo-site
|
||||
|
||||
In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
|
||||
|
||||
{{% code file="gitlab-ci.yml" %}}
|
||||
```
|
||||
{{< code file="gitlab-ci.yml" >}}
|
||||
image: publysher/hugo
|
||||
|
||||
pages:
|
||||
@ -49,8 +48,7 @@ pages:
|
||||
- public
|
||||
only:
|
||||
- master
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Push Your Hugo Website to GitLab
|
||||
|
||||
|
||||
@ -32,8 +32,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:
|
||||
|
||||
{{% code file="layouts/404.html" download="404.html" %}}
|
||||
```
|
||||
{{< code file="layouts/404.html" download="404.html" >}}
|
||||
{{ define "main"}}
|
||||
<main id="main">
|
||||
<div>
|
||||
@ -41,8 +40,7 @@ This is a basic example of a 404.html template:
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Automatic Loading
|
||||
|
||||
|
||||
@ -59,8 +59,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.
|
||||
|
||||
{{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
@ -80,15 +79,13 @@ The following defines a simple base template at `_default/baseof.html`. As a def
|
||||
{{ end }}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Override the Base Template
|
||||
|
||||
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
|
||||
|
||||
{{% code file="layouts/_default/list.html" download="list.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
{{ define "main" }}
|
||||
<h1>Posts</h1>
|
||||
{{ range .Data.Pages }}
|
||||
@ -98,8 +95,7 @@ From the above base template, you can define a [default list template][hugolists
|
||||
</article>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
|
||||
|
||||
@ -117,8 +113,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]:
|
||||
|
||||
{{% code file="layouts/_default/single.html" download="single.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/single.html" download="single.html" >}}
|
||||
{{ define "title" }}
|
||||
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
|
||||
{{ .Title }} – {{ .Site.Title }}
|
||||
@ -127,8 +122,7 @@ The following shows how you can override both the `"main"` and `"title"` block a
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[hugolists]: /templates/lists
|
||||
[lookup]: /templates/lookup-order/
|
||||
|
||||
@ -172,8 +172,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:
|
||||
|
||||
{{% code file="layouts/partials/get-csv.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/get-csv.html" >}}
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@ -194,8 +193,7 @@ For `getCSV`, the one-character-long separator must be placed in the first posit
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The expression `{{index $r number}}` must be used to output the nth-column from the current row.
|
||||
|
||||
|
||||
@ -36,11 +36,9 @@ 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.
|
||||
|
||||
{{% code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" %}}
|
||||
```
|
||||
{{< code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" >}}
|
||||
{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/directoryindex.html" >}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You can then call the shortcode as follows inside of your content's markup:
|
||||
|
||||
@ -80,11 +78,9 @@ If you are going to create [custom shortcodes](/templates/shortcode-templates/)
|
||||
|
||||
Here is the templating for our new `readfile` shortcode:
|
||||
|
||||
{{% code file="layouts/shortcodes/readfile.html" download="readfile.html" %}}
|
||||
```
|
||||
{{< code file="layouts/shortcodes/readfile.html" download="readfile.html" >}}
|
||||
{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/readfile.html">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is [`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows:
|
||||
|
||||
|
||||
@ -47,8 +47,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].
|
||||
|
||||
{{% code file="layouts/index.html" download="index.html" %}}
|
||||
```
|
||||
{{< code file="layouts/index.html" download="index.html" >}}
|
||||
{{ define "main" }}
|
||||
<main aria-role="main">
|
||||
<header class="homepage-header">
|
||||
@ -69,8 +68,7 @@ The following is an example of a homepage template that uses [partial][partials]
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[base]: /templates/base/
|
||||
[contentorg]: /content-management/organization/
|
||||
|
||||
@ -90,8 +90,7 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
|
||||
|
||||
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" >}}
|
||||
<div id="disqus_thread"></div>
|
||||
<script type="text/javascript">
|
||||
|
||||
@ -109,8 +108,7 @@ You can create the following `layouts/partials/disqus.html`:
|
||||
</script>
|
||||
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
|
||||
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
|
||||
|
||||
|
||||
@ -283,8 +283,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.
|
||||
|
||||
{{% code file="tags-range-with-page-variable.html" %}}
|
||||
```
|
||||
{{< code file="tags-range-with-page-variable.html" >}}
|
||||
{{ $title := .Site.Title }}
|
||||
<ul>
|
||||
{{ range .Params.tags }}
|
||||
@ -294,8 +293,7 @@ The following shows how to define a variable independent of the context.
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
|
||||
@ -305,8 +303,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:
|
||||
|
||||
{{% code file="range-through-tags-w-global.html" %}}
|
||||
```
|
||||
{{< code file="range-through-tags-w-global.html" >}}
|
||||
<ul>
|
||||
{{ range .Params.tags }}
|
||||
<li>
|
||||
@ -315,8 +312,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% warning "Don't Redefine the Dot" %}}
|
||||
The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
|
||||
@ -386,8 +382,7 @@ notoc: true
|
||||
|
||||
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" >}}
|
||||
{{ if not .Params.notoc }}
|
||||
<aside>
|
||||
<header>
|
||||
@ -399,8 +394,7 @@ Here is an example of corresponding code that could be used inside a `toc.html`
|
||||
</aside>
|
||||
<a href="#" id="toc-toggle"></a>
|
||||
{{end}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`.
|
||||
|
||||
@ -410,14 +404,12 @@ You can arbitrarily define as many site-level parameters as you want in your [si
|
||||
|
||||
For instance, you might declare the following:
|
||||
|
||||
{{% code file="config.yaml" %}}
|
||||
```
|
||||
{{< code file="config.yaml" >}}
|
||||
params:
|
||||
copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved."
|
||||
twitteruser: "spf13"
|
||||
sidebarrecentlimit: 5
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Within a footer layout, you might then declare a `<footer>` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
|
||||
|
||||
@ -429,16 +421,14 @@ 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:
|
||||
|
||||
{{% code file="layouts/partials/twitter.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/twitter.html" >}}
|
||||
{{with .Site.Params.twitteruser}}
|
||||
<div>
|
||||
<a href="https://twitter.com/{{.}}" rel="author">
|
||||
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}" alt="Twitter"></a>
|
||||
</div>
|
||||
{{end}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable.
|
||||
|
||||
@ -457,8 +447,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]:
|
||||
|
||||
{{% code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}}
|
||||
<h4>Upcoming Events</h4>
|
||||
<ul class="upcoming-events">
|
||||
{{ range where .Data.Pages.ByDate "Section" "events" }}
|
||||
@ -474,8 +463,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
[`where` function]: /functions/where/
|
||||
|
||||
@ -79,8 +79,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`:
|
||||
|
||||
{{% code file="content/post/_index.md" %}}
|
||||
```
|
||||
{{< code file="content/post/_index.md" >}}
|
||||
---
|
||||
title: My Golang Journey
|
||||
date: 2017-03-23
|
||||
@ -90,13 +89,11 @@ publishdate: 2017-03-24
|
||||
I decided to start learning Golang in March 2017.
|
||||
|
||||
Follow my journey through this new blog.
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You can now access this `_index.md`'s' content in your list template:
|
||||
|
||||
{{% code file="layouts/_default/list.html" download="list.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<article>
|
||||
@ -116,13 +113,11 @@ You can now access this `_index.md`'s' content in your list template:
|
||||
</ul>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
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" >}}
|
||||
<!--top of your baseof code-->
|
||||
<main>
|
||||
<article>
|
||||
@ -138,8 +133,7 @@ This above will output the following HTML:
|
||||
</ul>
|
||||
</main>
|
||||
<!--bottom of your baseof-->
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### List Pages Without `_index.md`
|
||||
|
||||
@ -147,8 +141,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:
|
||||
|
||||
{{% code file="yoursite.com/quote/index.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="yoursite.com/quote/index.html" copy="false" >}}
|
||||
<!--baseof-->
|
||||
<main>
|
||||
<article>
|
||||
@ -163,8 +156,7 @@ Using this same `layouts/_default/list.html` template and applying it to the the
|
||||
</ul>
|
||||
</main>
|
||||
<!--baseof-->
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/).
|
||||
@ -176,8 +168,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`.
|
||||
|
||||
{{% code file="layouts/section/post.html" %}}
|
||||
```
|
||||
{{< code file="layouts/section/post.html" >}}
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
<main>
|
||||
@ -192,13 +183,11 @@ This list template has been modified slightly from a template originally used in
|
||||
</div>
|
||||
</main>
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Taxonomy Template
|
||||
|
||||
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
<div>
|
||||
@ -210,8 +199,7 @@ This list template has been modified slightly from a template originally used in
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Order Content
|
||||
|
||||
@ -219,8 +207,7 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
|
||||
### Default: Weight > Date > LinkTitle > FilePath
|
||||
|
||||
{{% code file="layouts/partials/default-order.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/default-order.html" >}}
|
||||
<ul>
|
||||
{{ range .Data.Pages }}
|
||||
<li>
|
||||
@ -229,13 +216,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Weight
|
||||
|
||||
{{% code file="layouts/partials/by-weight.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-weight.html" >}}
|
||||
<ul>
|
||||
{{ range .Data.Pages.ByWeight }}
|
||||
<li>
|
||||
@ -244,13 +229,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Date
|
||||
|
||||
{{% code file="layouts/partials/by-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-date.html" >}}
|
||||
<ul>
|
||||
<!-- orders content according to the "date" field in front matter -->
|
||||
{{ range .Data.Pages.ByDate }}
|
||||
@ -260,13 +243,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Publish Date
|
||||
|
||||
{{% code file="layouts/partials/by-publish-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-publish-date.html" >}}
|
||||
<ul>
|
||||
<!-- orders content according to the "publishdate" field in front matter -->
|
||||
{{ range .Data.Pages.ByPublishDate }}
|
||||
@ -276,13 +257,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Expiration Date
|
||||
|
||||
{{% code file="layouts/partials/by-expiry-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-expiry-date.html" >}}
|
||||
<ul>
|
||||
{{ range .Data.Pages.ByExpiryDate }}
|
||||
<li>
|
||||
@ -291,13 +270,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Last Modified Date
|
||||
|
||||
{{% code file="layouts/partials/by-last-mod.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-last-mod.html" >}}
|
||||
<ul>
|
||||
<!-- orders content according to the "lastmod" field in front matter -->
|
||||
{{ range .Data.Pages.ByLastmod }}
|
||||
@ -307,13 +284,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Length
|
||||
|
||||
{{% code file="layouts/partials/by-length.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-length.html" >}}
|
||||
<ul>
|
||||
<!-- orders content according to content length in ascending order (i.e., the shortest content will be listed first) -->
|
||||
{{ range .Data.Pages.ByLength }}
|
||||
@ -323,13 +298,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Title
|
||||
|
||||
{{% code file="layouts/partials/by-title.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-title.html" >}}
|
||||
<ul>
|
||||
<!-- ranges through content in ascending order according to the "title" field set in front matter -->
|
||||
{{ range .Data.Pages.ByTitle }}
|
||||
@ -339,13 +312,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Link Title
|
||||
|
||||
{{% code file="layouts/partials/by-link-title.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-link-title.html" >}}
|
||||
<ul>
|
||||
<!-- ranges through content in ascending order according to the "linktitle" field in front matter. If a "linktitle" field is not set, the range will start with content that only has a "title" field and use that value for .LinkTitle -->
|
||||
{{ range .Data.Pages.ByLinkTitle }}
|
||||
@ -355,38 +326,32 @@ Hugo lists render the content based on metadata you provide in [front matter][].
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Parameter
|
||||
|
||||
Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering.
|
||||
|
||||
{{% code file="layouts/partials/by-rating.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-rating.html" >}}
|
||||
<!-- Ranges through content according to the "rating" field set in front matter -->
|
||||
{{ range (.Data.Pages.ByParam "rating") }}
|
||||
<!-- ... -->
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If the targeted front matter field is nested beneath another field, you can access the field using dot notation.
|
||||
|
||||
{{% code file="layouts/partials/by-nested-param.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-nested-param.html" >}}
|
||||
{{ range (.Data.Pages.ByParam "author.last_name") }}
|
||||
<!-- ... -->
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Reverse Order
|
||||
|
||||
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
|
||||
|
||||
{{% code file="layouts/partials/by-date-reverse.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-date-reverse.html" >}}
|
||||
<ul>
|
||||
{{ range .Data.Pages.ByDate.Reverse }}
|
||||
<li>
|
||||
@ -395,8 +360,7 @@ Reversing order can be applied to any of the above methods. The following uses `
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Group Content
|
||||
|
||||
@ -404,8 +368,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
|
||||
### By Page Field
|
||||
|
||||
{{% code file="layouts/partials/by-page-field.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-field.html" >}}
|
||||
<!-- Groups content according to content section. The ".Key" in this instance will be the section's title. -->
|
||||
{{ range .Data.Pages.GroupBy "Section" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
@ -418,13 +381,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]:
|
||||
|
||||
{{% code file="layouts/partials/by-page-field.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-field.html" >}}
|
||||
<!-- Groups content according to content section.-->
|
||||
{{ range .Data.Pages.GroupBy "Section" }}
|
||||
<!-- Checks for existence of _index.md for a section; if available, pulls from "title" in front matter -->
|
||||
@ -443,13 +404,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Date
|
||||
|
||||
{{% code file="layouts/partials/by-page-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-date.html" >}}
|
||||
<!-- Groups content by month according to the "date" field in front matter -->
|
||||
{{ range .Data.Pages.GroupByDate "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
@ -462,13 +421,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Publish Date
|
||||
|
||||
{{% code file="layouts/partials/by-page-publish-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-publish-date.html" >}}
|
||||
<!-- Groups content by month according to the "publishdate" field in front matter -->
|
||||
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
@ -481,13 +438,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Page Parameter
|
||||
|
||||
{{% code file="layouts/partials/by-page-param.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-param.html" >}}
|
||||
<!-- Groups content according to the "param_key" field in front matter -->
|
||||
{{ range .Data.Pages.GroupByParam "param_key" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
@ -500,15 +455,13 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Page Parameter in Date Format
|
||||
|
||||
The following template takes grouping by `date` a step further and uses Golang's layout string. See the [`Format` function][] for more examples of how to use Golang's layout string to format dates in Hugo.
|
||||
|
||||
{{% code file="layouts/partials/by-page-param-as-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-param-as-date.html" >}}
|
||||
<!-- Groups content by month according to the "param_key" field in front matter -->
|
||||
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
@ -521,8 +474,7 @@ The following template takes grouping by `date` a step further and uses Golang's
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Reverse Key Order
|
||||
|
||||
@ -560,8 +512,7 @@ Here is the ordering for the example that follows:
|
||||
2. Groups are listed in ascending order (i.e., the oldest groups first)
|
||||
3. Pages within each respective group are ordered alphabetically according to the `title`.
|
||||
|
||||
{{% code file="layouts/partials/by-group-by-page.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-group-by-page.html" >}}
|
||||
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -573,8 +524,7 @@ Here is the ordering for the example that follows:
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Filter and Limiting Lists
|
||||
|
||||
@ -588,13 +538,11 @@ Sometimes you only want to list a subset of the available content. A common is t
|
||||
2. `key` *or* `field name`
|
||||
3. `match value`
|
||||
|
||||
{{% code file="layouts/_default/.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/.html" >}}
|
||||
{{ range where .Data.Pages "Section" "post" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You can see more examples in the [functions documentation for `where`][wherefunction].
|
||||
|
||||
@ -605,26 +553,22 @@ You can see more examples in the [functions documentation for `where`][wherefunc
|
||||
1. `array` *or* `slice of maps or structs`
|
||||
2. `number of elements`
|
||||
|
||||
{{% code file="layout/_default/section.html" %}}
|
||||
```
|
||||
{{< code file="layout/_default/section.html" >}}
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### `first` and `where` Together
|
||||
|
||||
Using `first` and `where` together can be very powerful:
|
||||
|
||||
{{% code file="first-and-where-together.html" %}}
|
||||
```
|
||||
{{< code file="first-and-where-together.html" >}}
|
||||
<!-- Orders the content inside the "posts" section by the "title" field and then ranges through only the first 5 posts -->
|
||||
{{ range first 5 (where .Data.Pages "Section" "post").ByTitle }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[base]: /templates/base/
|
||||
[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/
|
||||
|
||||
@ -88,15 +88,13 @@ Only three of the four markdown files in the above project are subject to the *s
|
||||
|
||||
### 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" >}}
|
||||
---
|
||||
title: My First Post
|
||||
date: 2017-02-19
|
||||
description: This is my first post.
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`:
|
||||
|
||||
@ -118,8 +116,7 @@ Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo th
|
||||
|
||||
### 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" >}}
|
||||
---
|
||||
title: My Second Post
|
||||
date: 2017-02-21
|
||||
@ -127,8 +124,7 @@ description: This is my second post.
|
||||
type: review
|
||||
layout: reviewarticle
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Here is the way Hugo traverses the single-page lookup order for `my-second-post.md`:
|
||||
|
||||
@ -152,15 +148,13 @@ Notice that the directory for the template for `my-second-post.md` is `review` a
|
||||
|
||||
### 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" >}}
|
||||
---
|
||||
title: My First
|
||||
date: 2017-02-21
|
||||
description: This is an upcoming event..
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`:
|
||||
|
||||
|
||||
@ -24,8 +24,7 @@ able to build your menu however you want.
|
||||
|
||||
The following is an example:
|
||||
|
||||
{{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
|
||||
<!-- sidebar start -->
|
||||
<aside>
|
||||
<div id="sidebar" class="nav-collapse">
|
||||
@ -62,8 +61,7 @@ The following is an example:
|
||||
</div>
|
||||
</aside>
|
||||
<!--sidebar end-->
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note "`absLangURL` and `relLangURL`" %}}
|
||||
Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url.
|
||||
|
||||
@ -27,8 +27,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."
|
||||
|
||||
{{% code file="layouts/section/post.html" %}}
|
||||
```
|
||||
{{< code file="layouts/section/post.html" >}}
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
|
||||
@ -43,13 +42,11 @@ This list template is used for [spf13.com](http://spf13.com/). It makes use of [
|
||||
</div>
|
||||
</section>
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Taxonomy Template
|
||||
|
||||
{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}}
|
||||
{{ define "main" }}
|
||||
<section id="main">
|
||||
<div>
|
||||
@ -60,8 +57,7 @@ This list template is used for [spf13.com](http://spf13.com/). It makes use of [
|
||||
</div>
|
||||
</section>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Order Content
|
||||
|
||||
@ -72,8 +68,7 @@ your list templates:
|
||||
|
||||
### Default: Weight > Date
|
||||
|
||||
{{% code file="layouts/partials/order-default.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/order-default.html" >}}
|
||||
<ul class="pages">
|
||||
{{ range .Data.Pages }}
|
||||
<li>
|
||||
@ -82,113 +77,96 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Weight
|
||||
|
||||
{{% code file="layouts/partials/by-weight.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-weight.html" >}}
|
||||
{{ range .Data.Pages.ByWeight }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Date
|
||||
|
||||
{{% code file="layouts/partials/by-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-date.html" >}}
|
||||
{{ range .Data.Pages.ByDate }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Publish Date
|
||||
|
||||
{{% code file="layouts/partials/by-publish-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-publish-date.html" >}}
|
||||
{{ range .Data.Pages.ByPublishDate }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .PublishDate.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Expiration Date
|
||||
|
||||
{{% code file="layouts/partials/by-expiry-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-expiry-date.html" >}}
|
||||
{{ range .Data.Pages.ByExpiryDate }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Last Modified Date
|
||||
|
||||
{{% code file="layouts/partials/by-last-mod.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-last-mod.html" >}}
|
||||
{{ range .Data.Pages.ByLastmod }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Length
|
||||
|
||||
{{% code file="layouts/partials/by-length.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-length.html" >}}
|
||||
{{ range .Data.Pages.ByLength }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
### By Title
|
||||
|
||||
{{% code file="layouts/partials/by-title.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-title.html" >}}
|
||||
{{ range .Data.Pages.ByTitle }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Link Title
|
||||
|
||||
{{% code file="layouts/partials/by-link-title.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-link-title.html" >}}
|
||||
{{ range .Data.Pages.ByLinkTitle }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Parameter
|
||||
|
||||
@ -196,39 +174,33 @@ Order based on the specified front matter parameter. Content that does not have
|
||||
|
||||
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" >}}
|
||||
{{ range (.Data.Pages.ByParam "rating") }}
|
||||
<!-- ... -->
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
If the front matter field of interest is nested beneath another field, you can
|
||||
also get it:
|
||||
|
||||
{{% code file="layouts/partials/by-nested-param.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-nested-param.html" >}}
|
||||
{{ range (.Data.Pages.ByParam "author.last_name") }}
|
||||
<!-- ... -->
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Reverse Order
|
||||
|
||||
Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example:
|
||||
|
||||
{{% code file="layouts/partials/by-date-reverse.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-date-reverse.html" >}}
|
||||
{{ range .Data.Pages.ByDate.Reverse }}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Group Content
|
||||
|
||||
@ -236,8 +208,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
|
||||
### By Page Field
|
||||
|
||||
{{% code file="layouts/partials/by-page-field.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-field.html" >}}
|
||||
{{ range .Data.Pages.GroupBy "Section" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -249,13 +220,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Page date
|
||||
|
||||
{{% code file="layouts/partials/by-page-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-date.html" >}}
|
||||
{{ range .Data.Pages.GroupByDate "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -267,13 +236,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Page publish date
|
||||
|
||||
{{% code file="layouts/partials/by-page-publish-date.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-publish-date.html" >}}
|
||||
{{ range .Data.Pages.GroupByPublishDate "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -285,13 +252,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### By Page Param
|
||||
|
||||
{{% code file="layouts/partials/by-page-param.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-page-param.html" >}}
|
||||
{{ range .Data.Pages.GroupByParam "param_key" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -303,13 +268,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### 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" >}}
|
||||
{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -321,8 +284,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Reverse Key Order
|
||||
|
||||
@ -358,8 +320,7 @@ Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering
|
||||
In the following example, groups are ordered chronologically and then content
|
||||
within each group is ordered alphabetically by title.
|
||||
|
||||
{{% code file="layouts/partials/by-group-by-page.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/by-group-by-page.html" >}}
|
||||
{{ range .Data.Pages.GroupByDate "2006-01" "asc" }}
|
||||
<h3>{{ .Key }}</h3>
|
||||
<ul>
|
||||
@ -371,8 +332,7 @@ within each group is ordered alphabetically by title.
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## Filter and Limiting Lists
|
||||
|
||||
@ -386,13 +346,11 @@ Sometimes you only want to list a subset of the available content. A common requ
|
||||
2. `key` or `field name`
|
||||
3. `match value`
|
||||
|
||||
{{% code file="layouts/_default/.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/.html" >}}
|
||||
{{ range where .Data.Pages "Section" "post" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### `first`
|
||||
|
||||
@ -401,25 +359,21 @@ Sometimes you only want to list a subset of the available content. A common requ
|
||||
1. `array` or `slice of maps or structs`
|
||||
2. `number of elements`
|
||||
|
||||
{{% code file="layout/_default/section.html" %}}
|
||||
```
|
||||
{{< code file="layout/_default/section.html" >}}
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### `first` and `where` Together
|
||||
|
||||
Using `first` and `where` together can be very powerful:
|
||||
|
||||
{{% code file="first-and-where-together.html" %}}
|
||||
```
|
||||
{{< code file="first-and-where-together.html" >}}
|
||||
{{ range first 5 (where .Data.Pages "Section" "post") }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
|
||||
[views]: /templates/views/
|
||||
|
||||
@ -103,8 +103,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/):
|
||||
|
||||
{{% code file="layouts/partials/header.html" download="header.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/header.html" download="header.html" >}}
|
||||
<!DOCTYPE html>
|
||||
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
|
||||
<head>
|
||||
@ -120,8 +119,7 @@ The following `header.html` partial template is used for [spf13.com](http://spf1
|
||||
{{ partial "head_includes.html" . }}
|
||||
</head>
|
||||
<body lang="en">
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
|
||||
@ -131,8 +129,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/):
|
||||
|
||||
{{% code file="layouts/partials/footer.html" download="footer.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/footer.html" download="footer.html" >}}
|
||||
<footer>
|
||||
<div>
|
||||
<p>
|
||||
@ -159,8 +156,7 @@ The following `footer.html` partial template is used for [spf13.com](http://spf1
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context."
|
||||
[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order."
|
||||
|
||||
@ -39,15 +39,13 @@ If you do not want Hugo to create a default `robots.txt` or leverage the `robots
|
||||
|
||||
The following is an example `robots.txt` layout:
|
||||
|
||||
{{% code file="layouts/robots.txt" download="robots.txt" %}}
|
||||
```
|
||||
{{< code file="layouts/robots.txt" download="robots.txt" >}}
|
||||
User-agent: *
|
||||
|
||||
{{range .Data.Pages}}
|
||||
Disallow: {{.RelPermalink}}
|
||||
{{end}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This template disallows all the pages of the site by creating one `Disallow` entry for each page.
|
||||
|
||||
|
||||
@ -57,8 +57,7 @@ These are the valid values for 'kind':
|
||||
|
||||
## Example: Creating a Default Section Template
|
||||
|
||||
{{% code file="layouts/_default/section.html" download="section.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/section.html" download="section.html" >}}
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
{{ .Content }}
|
||||
@ -74,8 +73,7 @@ These are the valid values for 'kind':
|
||||
{{ partial "pagination.html" . }}
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Example: Using `.Site.GetPage`
|
||||
|
||||
|
||||
@ -147,11 +147,9 @@ Let's assume you would like to keep mentions of your copyright year current in y
|
||||
{{</* year */>}}
|
||||
```
|
||||
|
||||
{{% code file="/layouts/shortcodes/year.html" %}}
|
||||
```
|
||||
{{< code file="/layouts/shortcodes/year.html" >}}
|
||||
{{ .Page.Now.Year }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Single Positional Example: `youtube`
|
||||
|
||||
@ -163,17 +161,14 @@ Embedded videos are a common addition to markdown content that can quickly becom
|
||||
|
||||
Would load the template at `/layouts/shortcodes/youtube.html`:
|
||||
|
||||
{{% code file="/layouts/shortcodes/youtube.html" %}}
|
||||
```
|
||||
{{< code file="/layouts/shortcodes/youtube.html" >}}
|
||||
<div class="embed video-player">
|
||||
<iframe class="youtube-player" type="text/html" width="640" height="385" src="http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
|
||||
</iframe>
|
||||
</div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% code file="youtube-embed.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="youtube-embed.html" copy="false" >}}
|
||||
<div class="embed video-player">
|
||||
<iframe class="youtube-player" type="text/html"
|
||||
width="640" height="385"
|
||||
@ -181,23 +176,19 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
|
||||
allowfullscreen frameborder="0">
|
||||
</iframe>
|
||||
</div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Single Named Example: `image`
|
||||
|
||||
Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
|
||||
|
||||
{{% code file="content-image.md" %}}
|
||||
```
|
||||
{{< code file="content-image.md" >}}
|
||||
{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
|
||||
|
||||
{{% code file="/layouts/shortcodes/img.html" %}}
|
||||
```
|
||||
{{< code file="/layouts/shortcodes/img.html" >}}
|
||||
<!-- image -->
|
||||
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
|
||||
{{ with .Get "link"}}<a href="{{.}}">{{ end }}
|
||||
@ -216,21 +207,18 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
|
||||
{{ end }}
|
||||
</figure>
|
||||
<!-- image -->
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
{{% code file="img-output.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="img-output.html" copy="false" >}}
|
||||
<figure >
|
||||
<img src="/media/spf13.jpg" />
|
||||
<figcaption>
|
||||
<h4>Steve Francia</h4>
|
||||
</figcaption>
|
||||
</figure>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Single Flexible Example: `vimeo`
|
||||
|
||||
@ -241,8 +229,7 @@ Would be rendered as:
|
||||
|
||||
Would load the template found at `/layouts/shortcodes/vimeo.html`:
|
||||
|
||||
{{% code file="/layouts/shortcodes/vimeo.html" %}}
|
||||
```
|
||||
{{< code file="/layouts/shortcodes/vimeo.html" >}}
|
||||
{{ if .IsNamedParams }}
|
||||
<div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
|
||||
<iframe src="//player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
|
||||
@ -252,35 +239,30 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
|
||||
<iframe src="//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
{{% code file="vimeo-iframes.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="vimeo-iframes.html" copy="false" >}}
|
||||
<div class="vimeo-container">
|
||||
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
|
||||
</div>
|
||||
<div class="flex-video">
|
||||
<iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
|
||||
</div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Paired Example: `highlight`
|
||||
|
||||
The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
|
||||
|
||||
{{% code file="highlight-example.md" %}}
|
||||
```
|
||||
{{< code file="highlight-example.md" >}}
|
||||
{{</* highlight html */>}}
|
||||
<html>
|
||||
<body> This HTML </body>
|
||||
</html>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
|
||||
|
||||
@ -290,14 +272,12 @@ The template for the `highlight` shortcode uses the following code, which is alr
|
||||
|
||||
The rendered output of the HTML example code block will be as follows:
|
||||
|
||||
{{% code file="syntax-highlighted.html" copy="false" %}}
|
||||
```
|
||||
{{< code file="syntax-highlighted.html" copy="false" >}}
|
||||
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
|
||||
<span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
|
||||
<span style="color: #f92672"></html></span>
|
||||
</pre></div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information.
|
||||
@ -309,26 +289,22 @@ Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending
|
||||
|
||||
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
|
||||
|
||||
{{% code file="layouts/shortcodes/gallery.html" %}}
|
||||
```
|
||||
{{< code file="layouts/shortcodes/gallery.html" >}}
|
||||
<div class="{{.Get "class"}}">
|
||||
{{.Inner}}
|
||||
</div>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You also have an `image` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes so that the parent defines the context of each `image`:
|
||||
|
||||
{{% code file="layouts/shortcodes/image.html" %}}
|
||||
```
|
||||
{{< code file="layouts/shortcodes/image.html" >}}
|
||||
{{- $src := .Get "src" -}}
|
||||
{{- with .Parent -}}
|
||||
<img src="{{$src}}" class="{{.Get "class"}}-image">
|
||||
{{- else -}}
|
||||
<img src="{{$src}}">
|
||||
{{- end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
You can then call your shortcode in your content as follows:
|
||||
|
||||
|
||||
@ -43,8 +43,7 @@ Content pages are of the type `page` and will therefore have all the [page varia
|
||||
|
||||
This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter.
|
||||
|
||||
{{% code file="layouts/post/single.html" download="single.html" %}}
|
||||
```
|
||||
{{< code file="layouts/post/single.html" download="single.html" >}}
|
||||
{{ define "main" }}
|
||||
<section id="main">
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
@ -85,8 +84,7 @@ This single page template makes use of Hugo [base templates][], the [`.Format` f
|
||||
</div>
|
||||
</aside>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
|
||||
|
||||
|
||||
@ -291,8 +291,7 @@ The following example displays all terms in a site's tags taxonomy:
|
||||
|
||||
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
|
||||
|
||||
{{% code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
|
||||
<section>
|
||||
<ul id="all-taxonomies">
|
||||
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
|
||||
@ -311,22 +310,19 @@ This example will list all taxonomies and their terms, as well as all the conten
|
||||
{{ end }}
|
||||
</ul>
|
||||
</section>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
## `.Site.GetPage` for Taxonomies
|
||||
|
||||
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above:
|
||||
|
||||
{{% code file="links-to-all-tags" %}}
|
||||
```
|
||||
{{< code file="links-to-all-tags" >}}
|
||||
<ul class="tags">
|
||||
{{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }}
|
||||
<li><a href="{{ .Permalink }}">{{ .Title}}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
<!--### `.Site.GetPage` Taxonomy List Example
|
||||
|
||||
|
||||
@ -69,8 +69,7 @@ The following example demonstrates how to use content views inside of your [list
|
||||
|
||||
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
|
||||
|
||||
{{% code file="layouts/_default/list.html" download="list.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/list.html" download="list.html" >}}
|
||||
<main id="main">
|
||||
<div>
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
@ -79,15 +78,13 @@ In this example, `.Render` is passed into the template to call the [render funct
|
||||
{{ end }}
|
||||
</div>
|
||||
</main>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### `summary.html`
|
||||
|
||||
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
|
||||
|
||||
{{% code file="layouts/_default/summary.html" download="summary.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/summary.html" download="summary.html" >}}
|
||||
<article class="post">
|
||||
<header>
|
||||
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
|
||||
@ -98,21 +95,18 @@ Hugo will pass the entire page object to the following `summary.html` view templ
|
||||
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
|
||||
</footer>
|
||||
</article>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### `li.html`
|
||||
|
||||
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
|
||||
|
||||
{{% code file="layouts/_default/li.html" download="li.html" %}}
|
||||
```
|
||||
{{< code file="layouts/_default/li.html" download="li.html" >}}
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[lists]: /templates/lists/
|
||||
[lookup]: /templates/lookup-order/
|
||||
|
||||
@ -57,12 +57,10 @@ git clone URL_TO_THEME
|
||||
|
||||
The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
|
||||
|
||||
{{% code file="clone-theme.sh" %}}
|
||||
```
|
||||
{{< code file="clone-theme.sh" >}}
|
||||
cd themes
|
||||
git clone https://github.com/spf13/hyde
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
|
||||
|
||||
|
||||
@ -48,8 +48,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho
|
||||
|
||||
### Example `highlight` Shortcode Input
|
||||
|
||||
{{% code file="example-highlight-shortcode-input.md" %}}
|
||||
```
|
||||
{{< code file="example-highlight-shortcode-input.md" >}}
|
||||
{{</* highlight html */>}}
|
||||
<section id="main">
|
||||
<div>
|
||||
@ -60,8 +59,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho
|
||||
</div>
|
||||
</section>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
### Example `highlight` Shortcode Output
|
||||
|
||||
|
||||
@ -206,12 +206,10 @@ These fields would then be accessible to the `/themes/yourtheme/layouts/review/s
|
||||
|
||||
Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
|
||||
|
||||
{{% code file="/themes/yourtheme/layouts/review/single.html" %}}
|
||||
```
|
||||
{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
|
||||
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
|
||||
<p>It was recommended by {{ .Params.recommendedby }}.</p>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
|
||||
|
||||
|
||||
@ -118,10 +118,8 @@ baseURL = "http://yoursite.example.com/"
|
||||
|
||||
You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
|
||||
|
||||
{{% code file="layouts/partials/head.html" %}}
|
||||
```
|
||||
{{< code file="layouts/partials/head.html" >}}
|
||||
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
@ -59,8 +59,7 @@ The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, co
|
||||
|
||||
The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates].
|
||||
|
||||
{{% code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" %}}
|
||||
```
|
||||
{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}}
|
||||
<section>
|
||||
<ul>
|
||||
{{ range $taxonomyname, $taxonomy := .Site.Taxonomies }}
|
||||
@ -79,8 +78,7 @@ The following [partial template][partials] will list all your site's taxonomies,
|
||||
{{ end }}
|
||||
</ul>
|
||||
</section>
|
||||
```
|
||||
{{% /code %}}
|
||||
{{< /code >}}
|
||||
|
||||
[partials]: /templates/partials/
|
||||
[taxonomytemplates]: /templates/taxonomy-templates/
|
||||
Loading…
x
Reference in New Issue
Block a user