mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 15:28:54 +00:00
Add first round of functions
This commit is contained in:
Ryan Watters
@@ -2,3 +2,4 @@ themes/hugodocs/pipeline/node_modules
|
||||
ryans-notes.md
|
||||
notes-for-reviewers.md
|
||||
functions-page.md
|
||||
specific-reviewers.md
|
||||
|
||||
@@ -8,4 +8,4 @@
|
||||
|
||||
## Contributing to the Docs
|
||||
|
||||
(WIP) See the guide at <http://gohugo.io/contribute-to-hugo/contribute-to-the-hugo-docs> for instructions on how to contribute to the documentation.
|
||||
(WIP) See the guide at <http://gohugo.io/contribute/contribute-to-the-hugo-docs> for instructions on how to contribute to the documentation.
|
||||
@@ -33,12 +33,12 @@ Feel free to [contribute to Hugo's development][devcontribute], [improve Hugo's
|
||||
[#1014]: https://github.com/spf13/hugo/issues/1014
|
||||
[#1435]: https://github.com/spf13/hugo/issues/1435
|
||||
[#1436]: https://github.com/spf13/hugo/issues/1436
|
||||
[devcontribute]: /contribute-to-hugo/contribute-to-hugo-development/
|
||||
[doccontribute]: /contribute-to-hugo/contribute-to-the-hugo-docs/
|
||||
[devcontribute]: /contribute/contribute-to-hugo-development/
|
||||
[doccontribute]: /contribute/contribute-to-the-hugo-docs/
|
||||
[hosting and deployment]: /hosting-and-deployment/
|
||||
[migrate]: /developer-tools/migrate-to-hugo/
|
||||
[newissue]: https://github.com/spf13/hugo/issues/
|
||||
[related Discuss thread]: https://discuss.gohugo.io/t/web-based-editor/155
|
||||
[themes]: /themes/
|
||||
[tutorials]: /tutorials
|
||||
[***your*** best ideas!]: /contribute-to-hugo/
|
||||
[***your*** best ideas!]: /contribute/
|
||||
+28
-13
@@ -16,7 +16,7 @@ toc: true
|
||||
## Strategy, Tactics, and Requirements
|
||||
|
||||
{{% warning "Disclaimer" %}}
|
||||
WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the content strategy document.
|
||||
WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document.
|
||||
{{% /warning %}}
|
||||
|
||||
### Introduction
|
||||
@@ -115,12 +115,18 @@ The following are high-level requirements for the documentation site.
|
||||
- [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`)
|
||||
- [X] SSL
|
||||
- [ ] AMP?
|
||||
- [ ] 301s [^1]
|
||||
|
||||
#### Accessibility
|
||||
|
||||
- [ ] Aria roles
|
||||
- [ ] Alt text for all images
|
||||
|
||||
#### Editorial and Content
|
||||
|
||||
- [ ] Basic style guide
|
||||
- The style guide should facilitate a more consistent UX for the site but not be so complex as to deter documentation contributors
|
||||
- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/))
|
||||
- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute/contribute-to-the-hugo-docs/))
|
||||
- [X] Standardized content types (see [WIP archetypes in source](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
|
||||
- [X] New content model, including taxonomies ([see tags page][tagspage])
|
||||
- [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
|
||||
@@ -140,7 +146,7 @@ The following are high-level requirements for the documentation site.
|
||||
- [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords)
|
||||
- [X] Dual in-page navigation (i.e. site nav *and* in-page TOC)
|
||||
- [X] Smooth scrolling
|
||||
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](http://localhost:1313/contribute-to-hugo/contribute-to-the-hugo-docs/#admonition-short-codes))
|
||||
- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](/contribute/contribute-to-the-hugo-docs/#admonition-short-codes))
|
||||
- [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums
|
||||
|
||||
## Author Experience (AX)
|
||||
@@ -171,14 +177,7 @@ The following are high-level requirements for the documentation site.
|
||||
- [X] Abstracted color palette
|
||||
- [X] Abstracted typefaces (multiple open-source fonts available)
|
||||
|
||||
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
|
||||
[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
|
||||
[forum]: https://discuss.gohugo.io
|
||||
[ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
|
||||
[ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
|
||||
[forum]:
|
||||
[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md
|
||||
[tagspage]: https://hugodocsconcept.netlify.com/tags/
|
||||
|
||||
|
||||
## Content Changes
|
||||
|
||||
@@ -344,11 +343,27 @@ Apache License - 60
|
||||
|
||||
**Ordered by title**
|
||||
|
||||
[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
|
||||
|
||||
## Current Content (Source)
|
||||
|
||||
```markdown
|
||||
{{< readfile file="content/tree.txt" >}}
|
||||
```
|
||||
|
||||
## Proposed Schedule for Hugo Docs Release
|
||||
|
||||
|
||||
1. **2017-02-26** Release to Gitter Channel for Review
|
||||
2. **2017-03-01** Post in Discussion Forum for Feedback
|
||||
3. **2017-??-??** Add to Hugo repo for release with v19
|
||||
|
||||
[^1]: As this point, the URL structure has changed considerably. I've been fastidious about adding aliases wherever possible, but I'm not sure what negative effect this approach is going to take with our current search relevancy. The [current list of aliases is quite large](/contribute/contribute-to-the-hugo-docs/#be-mindful-of-aliases).
|
||||
|
||||
|
||||
[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
|
||||
[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources
|
||||
[forum]: https://discuss.gohugo.io
|
||||
[ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
|
||||
[ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
|
||||
[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md
|
||||
[tagspage]: https://hugodocsconcept.netlify.com/tags/
|
||||
[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/
|
||||
@@ -16,11 +16,11 @@ needsreview: true
|
||||
|
||||
## Introduction
|
||||
|
||||
Hugo uses files (see [supported content formats][]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][].
|
||||
Hugo uses files (see [Supported Content Formats][]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][].
|
||||
|
||||
## Organizing Source Content
|
||||
|
||||
In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/<directories>*``) is special in Hugo and is considered the content [section](/content-management/sections/).
|
||||
In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/<directories>*``) is special in Hugo and is considered the content [section][].
|
||||
|
||||
## Destinations
|
||||
|
||||
@@ -141,6 +141,116 @@ http://spf13.com/extras/indexes/example
|
||||
* defined in front matter
|
||||
* overrides all the above
|
||||
|
||||
## \_index.md and 'Everything is a Page'
|
||||
|
||||
As of version v0.18 Hugo now treats '[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)'. This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomies][taxonomytemplates], [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Homepage](/templates/homepage/).
|
||||
|
||||
In order to take advantage of this behaviour you need to do a few things.
|
||||
|
||||
1. Create an \_index.md file that contains the front matter and content you would like to apply.
|
||||
|
||||
2. Place the \_index.md file in the correct place in the [directory structure][].
|
||||
|
||||
3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the \_index.md file to be rendered on the respective page.
|
||||
|
||||
### How `_index.md` Works
|
||||
|
||||
Before continuing, it's important to know that this page must reference certain templates to describe how the \_index.md page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
|
||||
|
||||
If this is confusing or you are unfamiliar with Hugo's template hierarchy, visit the various template pages listed below. You may need to find the 'active' template responsible for any particular page on your own site by going through the template hierarchy and matching it to your particular setup/theme you are using.
|
||||
|
||||
- [Homepage template](/templates/homepage/)
|
||||
- [Content List templates](/templates/list/)
|
||||
- [Single Content templates](/templates/content/)
|
||||
- [Taxonomy Terms templates](/templates/terms/)
|
||||
|
||||
Now that you've got a handle on templates lets recap some Hugo basics to understand how to use an \_index.md file with a List page.
|
||||
|
||||
1. Sections and Taxonomies are 'List' pages, NOT single pages.
|
||||
2. List pages are rendered using the template heirarchy found in the [Content - List Template](http://localhost:1313/templates/list/) docs.
|
||||
3. The Homepage, though technically a List page, can have [it's own template](/templates/homepage/) at layouts/index.html rather than \_default/list.html. Many themes exploit this behaviour so you are likely to encounter this specific use case.
|
||||
4. Taxonomy terms pages are 'lists of metadata' not lists of content, so [have their own templates](/templates/terms/).
|
||||
|
||||
Let's put all this information together:
|
||||
|
||||
> **\_index.md files used in List pages, Terms pages or the Homepage are NOT rendered as single pages or with Single Content templates.**
|
||||
|
||||
> **All pages, including List pages, can have front matter and front matter can have markdown content - meaning \_index.md files are the way to _provide_ front matter and content to the respective List/Terms/Homepage.**
|
||||
|
||||
Here are a couple of examples to make it clearer...
|
||||
|
||||
```
|
||||
| \_index.md location | Page affected | Rendered by |
|
||||
| ------------------- | ------------ | ----------- |
|
||||
| /content/post/\_index.md | site.com/post/ | /layouts/section/post.html |
|
||||
| /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html |
|
||||
```
|
||||
|
||||
## Why `_index.md files are used`
|
||||
|
||||
With a Single page such as a post it's possible to add the front matter and content directly into the .md page itself. With List/Terms/Homepages this is not possible so \_index.md files can be used to provide that front matter/content to them.
|
||||
|
||||
## How to display content from \_index.md files
|
||||
|
||||
From the information above it should follow that content within an \_index.md file won't be rendered in its own Single Page, instead it'll be made available to the respective list, terms, Homepage.
|
||||
|
||||
To **_actually render that content_** you need to ensure that the relevant template responsible for rendering the List/Terms/Homepage contains (at least) `{{ .Content }}`.
|
||||
|
||||
This is the way to actually display the content within the \_index.md file on the List/Terms/Homepage.
|
||||
|
||||
A very simple example is shown in the following default section list page:
|
||||
|
||||
{{% code file="layouts/_default/section.html" download="section.html" %}}
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
{{ .Content }}
|
||||
<ul class="contents">
|
||||
{{ range .Paginator.Pages }}
|
||||
<li>{{.Title}}
|
||||
<div>
|
||||
{{ partial "summary.html" . }}
|
||||
</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ partial "pagination.html" . }}
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
You can see `{{ .Content }}` just after the `<main>` element. For this particular example, the content of the \_index.md file will show before the main list of summaries.
|
||||
|
||||
## Where to Organize `_index.md` Files
|
||||
|
||||
To add content and front matter to the homepage, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name \_index on the relevant place on the file system.
|
||||
|
||||
```bash
|
||||
└── content
|
||||
├── _index.md
|
||||
├── categories
|
||||
│ ├── _index.md
|
||||
│ └── photo
|
||||
│ └── _index.md
|
||||
├── post
|
||||
│ ├── _index.md
|
||||
│ └── firstpost.md
|
||||
└── tags
|
||||
├── _index.md
|
||||
└── hugo
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
In the above example, `_index.md, pages have been added to each section and taxonomy.
|
||||
|
||||
An `_index.md` file has also been added in the top level 'content' directory.
|
||||
|
||||
### Where to place `_index.md` for the Homepage Template
|
||||
|
||||
Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the homepage.
|
||||
|
||||
[front matter]: /content-management/front-matter/
|
||||
[section]: /content-management/section/
|
||||
[supported content formats]: /content-management/supported-content-formats/
|
||||
[URL management]: /content-management/url-management/
|
||||
|
||||
@@ -9,7 +9,7 @@ categories: [content management]
|
||||
tags: [summaries,abstracts,read more]
|
||||
weight: 90
|
||||
draft: false
|
||||
aliases: [/content/summaries/]
|
||||
aliases: [/content/summaries/,/content-management/summaries]
|
||||
toc: true
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Cross References
|
||||
linktitle:
|
||||
description:
|
||||
description: Hugo makes it easy to link documents together with the ref and relref shortcodes, which safely provide links to headings inside of your content, whether across documents or within a document.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-01-09
|
||||
@@ -9,12 +9,11 @@ categories: [content management]
|
||||
tags: ["cross references","references", "anchors", "urls"]
|
||||
weight: 100
|
||||
draft: false
|
||||
aliases: []
|
||||
aliases: [/extras/crossreferences/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
Hugo makes it easy to link documents together with `ref` and `relref`, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`).
|
||||
Hugo makes it easy to link documents together with `ref` and `relref`, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively.
|
||||
|
||||
## Using `ref` and `relref`
|
||||
|
||||
@@ -27,35 +26,59 @@ Hugo makes it easy to link documents together with `ref` and `relref`, both of w
|
||||
{{</* relref "document#anchor" */>}}
|
||||
```
|
||||
|
||||
The single parameter to `ref` is a string with a content _document name_ (`about.md`), an in-document _anchor_ (`#who`), or both (`about.md#who`).
|
||||
The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces.
|
||||
|
||||
### Document Names
|
||||
|
||||
The _document name_ is the name of a document including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result.
|
||||
The `documentname` is the name of a document, including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result:
|
||||
|
||||
```golang
|
||||
{{</* relref "blog/post.md" */>}} ⇒ `/blog/post/`
|
||||
{{</* relref "post.md" */>}} ⇒ `/blog/post/`
|
||||
```
|
||||
|
||||
If you have multiple sections with the same filename, you should only use the relative path format, because the behaviour is _undefined_. So, if I also have a document `link/post.md`, the output of `ref` is unknown for `post.md`.
|
||||
If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory:
|
||||
|
||||
```golang
|
||||
{{</* relref "blog/post.md" */>}} ⇒ `/blog/post/`
|
||||
{{</* relref "post.md" */>}} ⇒ `/blog/post/` (maybe)
|
||||
{{</* relref "post.md" */>}} ⇒ `/link/post/` (maybe)
|
||||
{{</* relref "link/post.md" */>}} ⇒ `/link/post/`
|
||||
```bash
|
||||
.
|
||||
└── content
|
||||
├── events
|
||||
│ └── my-birthday.md
|
||||
├── galleries
|
||||
│ └── my-birthday.md
|
||||
├── meta
|
||||
│ └── my-article.md
|
||||
└── posts
|
||||
└── my-birthday.md
|
||||
```
|
||||
|
||||
A relative document name must *not* begin with a slash (`/`).
|
||||
The potential for conflicting `documentname` is more likely in larger sites. Using the example of multiple `my-birthday.md` files, the following shows how these cross references may or may not render when called from within `content/meta/my-article.md`:
|
||||
|
||||
{{% code file="content/meta/my-article.md" copy="false" %}}
|
||||
```golang
|
||||
{{</* relref "/blog/post.md" */>}} ⇒ `""`
|
||||
{{</* relref "my-birthday.md" */>}} ⇒ `/events/my-birthday/` (maybe)
|
||||
{{</* relref "my-birthday.md" */>}} ⇒ `/posts/my-birthday/` (maybe)
|
||||
{{</* relref "my-birthday.md" */>}} ⇒ `/galleries/my-birthday/` (maybe)
|
||||
{{</* relref "events/my-birthday.md" */>}} ⇒ `/events/my-birthday/`
|
||||
{{</* relref "galleries/my-birthday.md" */>}} ⇒ `/galleries/my-birthday/`
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
A relative document name must *not* begin with a slash (`/`).
|
||||
```golang
|
||||
{{</* relref "/events/my-birthday.md" */>}} ⇒ `""`
|
||||
```
|
||||
|
||||
### Anchors
|
||||
|
||||
When an _anchor_ is provided by itself, the current page’s unique identifier will be appended; when an _anchor_ is provided with a document name, the found page's unique identifier will be appended.
|
||||
When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
|
||||
|
||||
```golang
|
||||
{{</* relref "#anchors" */>}} ⇒ `#anchors:9decaf7`
|
||||
{{</* relref "about-hugo/hugo-features.md#content" */>}} ⇒ `/blog/post/#who:badcafe`
|
||||
```
|
||||
|
||||
The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
|
||||
|
||||
```golang
|
||||
{{</* relref "#who" */>}} ⇒ `#who:9decaf7`
|
||||
@@ -66,8 +89,8 @@ More information about document unique identifiers and headings can be found [be
|
||||
|
||||
### Examples
|
||||
|
||||
* `{{</* ref "blog/post.md" */>}}` ⇒ `http://1.com/blog/post/`
|
||||
* `{{</* ref "post.md#tldr" */>}}` ⇒ `http://1.com/blog/post/#tldr:caffebad`
|
||||
* `{{</* ref "blog/post.md" */>}}` ⇒ `http://yoursite.com/blog/post/`
|
||||
* `{{</* ref "post.md#tldr" */>}}` ⇒ `http://yoursite.com/blog/post/#tldr:caffebad`
|
||||
* `{{</* relref "post.md" */>}}` ⇒ `/blog/post/`
|
||||
* `{{</* relref "blog/post.md#tldr" */>}}` ⇒ `/blog/post/#tldr:caffebad`
|
||||
* `{{</* ref "#tldr" */>}}` ⇒ `#tldr:badcaffe`
|
||||
@@ -82,8 +105,8 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi
|
||||
`ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)
|
||||
|
||||
```golang
|
||||
{{</* relref "content-management/crossreferences.md#hugo-heading-anchors" */>}}
|
||||
/content-management/crossreferences/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
|
||||
{{</* relref "content-management/cross-references.md#hugo-heading-anchors" */>}}
|
||||
/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242
|
||||
```
|
||||
|
||||
What follows is a deeper discussion of *why* and *how* Hugo generates heading anchors. It is not necessary to know this to use `ref` and `relref`, but it may be useful in understanding how some anchors may not match your expectations.
|
||||
@@ -142,27 +165,27 @@ This can even affect specified heading anchors that come after a generated headi
|
||||
* `# My Heading` ⇒ `my-heading`
|
||||
* `# My Heading {#my-heading}` ⇒ `my-heading-1`
|
||||
|
||||
> This particular collision and override is unfortunate, but unavoidable because Hugo processes each heading for collision detection as it sees it during conversion.
|
||||
{{% note %}}
|
||||
This particular collision and override both unfortunate and unavoidable because Hugo processes each heading for collision detection as it sees it during conversion.
|
||||
{{% /note %}}
|
||||
|
||||
This technique works well for documents rendered on individual pages, like blog posts. What about on Hugo list pages?
|
||||
This technique works well for documents rendered on individual pages (e.g., blog posts), but what about [Hugo list pages][lists]?
|
||||
|
||||
### Unique Heading Anchors in Lists
|
||||
|
||||
Hugo converts each document from Markdown independently. It doesn’t know that `blog/post.md` has an "Example" heading that will collide with the "Example" heading in `blog/post2.md`. Even if it did know this, the addition of `blog/post3.md` should not cause the anchors for the headings in the other blog posts to change.
|
||||
|
||||
Enter the document’s unique identifier. To prevent this sort of collision on
|
||||
list pages, Hugo always appends the document's to a generated heading anchor.
|
||||
So, the "Example" heading in `blog/post.md` actually turns into
|
||||
`#example:81df004…`, and the "Example" heading in `blog/post2.md` actually
|
||||
turns into `#example:8cf1599…`. All you have to know is the heading anchor that
|
||||
was generated, not the document identifier; `ref` and `relref` take care of the
|
||||
rest for you.
|
||||
Enter the document’s unique identifier. To prevent this sort of collision on list pages, Hugo always appends the document's to a generated heading anchor. So, the "Example" heading in `blog/post.md` actually turns into `#example:81df004…`, and the "Example" heading in `blog/post2.md` actually turns into `#example:8cf1599…`. All you have to know is the heading anchor that was generated, not the document identifier; `ref` and `relref` take care of the rest for you.
|
||||
|
||||
<a href='{{</* relref "blog/post.md#example" */>}}'>Post Example</a>
|
||||
<a href='/blog/post.md#81df004…'>Post Example</a>
|
||||
```html
|
||||
<a href='{{</* relref "blog/post.md#example" */>}}'>Post Example</a>
|
||||
<a href='/blog/post.md#81df004…'>Post Example</a>
|
||||
```
|
||||
|
||||
[Post Two Example]({{</* relref "blog/post2.md#example" */>}})
|
||||
<a href='/blog/post2.md#8cf1599…'>Post Two Example</a>
|
||||
```
|
||||
[Post Two Example]({{</* relref "blog/post2.md#example" */>}})
|
||||
<a href='/blog/post2.md#8cf1599…'>Post Two Example</a>
|
||||
```
|
||||
|
||||
|
||||
[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
|
||||
[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
|
||||
[lists]: /templates/lists/
|
||||
@@ -49,7 +49,7 @@ Hugo will automatically create pages for each section root that list all of the
|
||||
As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content.
|
||||
|
||||
{{% warning "`index.md` vs `_index.md`" %}}
|
||||
Hugo themes developed before v0.18 often used an `index.md` in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as the *preferred* content section index page. **Note:** `_index.md`'s layout, as representative of a section, is a [list template](/templates/section-templates/) and *not* a [single template](/templates/single-page-templates/).
|
||||
Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/).
|
||||
{{% /warning %}}
|
||||
|
||||
## Content *Section* vs Content *Type*
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Shortcodes
|
||||
linktitle:
|
||||
description:
|
||||
description: Shortcodes are simple snippets inside your content files that Hugo renders renders so as not to mess with the clean and simple syntax of your preferred content format.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
@@ -389,7 +389,7 @@ Using the preceding `youtube` example, the following HTML will be added to your
|
||||
|
||||
#### Example `youtube` Display
|
||||
|
||||
Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
|
||||
Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
|
||||
|
||||
{{< youtube w7Ft2ymGmfc >}}
|
||||
|
||||
@@ -406,6 +406,7 @@ To learn more about creating your own shortcode templates, see the [shortcode te
|
||||
[partials]: /templates/partials-templates/
|
||||
[Pygments]: http://pygments.org/
|
||||
[projectorganizationsection]: /project-organization/directory-structure/
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[shortcode template documentation]: /templates/shortcode-templates/
|
||||
[Speaker Deck]: https://speakerdeck.com/
|
||||
[templatessection]: /templates/
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: URL Management
|
||||
linktitle: URL Management
|
||||
description:
|
||||
description: Hugo provides native support for permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
@@ -16,7 +16,7 @@ needsreview: true
|
||||
|
||||
## Permalinks
|
||||
|
||||
By default, a Hugo-built site is laid out into the target `publishdir` specified in your [site configuration][configuration]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder. namespace matching its layout within the `contentdir` hierarchy. The `permalinks` option in your [site configuration][] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
|
||||
By default, a Hugo-built site is laid out into the target `publishdir` specified in your [site configuration][configuration]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder. namespace matching its layout within the `contentdir` hierarchy. The `permalinks` option in your [site configuration][] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option.
|
||||
|
||||
{{% note "Default Publish and Content Folders" %}}
|
||||
These examples use the default values for `publishDir` and `contentDir`; i.e., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/).
|
||||
@@ -26,19 +26,23 @@ 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" %}}
|
||||
```yaml
|
||||
permalinks:
|
||||
post: /:year/:month/:title/
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### TOML Permalinks Configuration Example
|
||||
|
||||
{{% code file="config.toml" copy="false" %}}
|
||||
```toml
|
||||
[permalinks]
|
||||
post = "/:year/:month/:title/"
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry` with `date: 2013-11-18T19:20:00-05:00` in its front matter will render to `public/2013/11/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.example.com/2013/11/sample-entry/`.
|
||||
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry` with `date: 2013-11-18T19:20:00-05:00` in its front matter will render to `public/2013/11/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`.
|
||||
|
||||
### Permalink Configuration Values
|
||||
|
||||
@@ -58,51 +62,38 @@ The following is a list of values that can be used in a `permalink` definition i
|
||||
|
||||
## Example
|
||||
|
||||
Given a post on your current Hugo site, with a path of:
|
||||
Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following show examples of creating this filed in TOML and YAML front matter, respectively.
|
||||
|
||||
``content/posts/my-awesome-blog-post.md``
|
||||
|
||||
... you create an "aliases" section in the frontmatter of your post, and add previous paths to that.
|
||||
|
||||
### TOML frontmatter
|
||||
### TOML Front Matter
|
||||
|
||||
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
|
||||
```toml
|
||||
+++
|
||||
...
|
||||
aliases = [
|
||||
"/posts/my-original-url/",
|
||||
"/2010/01/01/even-earlier-url.html"
|
||||
]
|
||||
...
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### YAML frontmatter
|
||||
### YAML Front Matter
|
||||
|
||||
{{% code file="content/posts/my-awesome-post.md" copy="false" %}}
|
||||
```yaml
|
||||
---
|
||||
...
|
||||
aliases:
|
||||
- /posts/my-original-url/
|
||||
- /2010/01/01/even-earlier-url.html
|
||||
...
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on.
|
||||
|
||||
## Important Behaviors
|
||||
|
||||
1. *Hugo makes no assumptions about aliases. They also don't change based
|
||||
on your UglyURLs setting. You need to provide absolute path to your webroot
|
||||
and the complete filename or directory.*
|
||||
|
||||
2. *Aliases are rendered prior to any content and will be overwritten by
|
||||
any content with the same location.*
|
||||
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`.
|
||||
|
||||
## Multilingual example
|
||||
|
||||
On [multilingual sites](/content-management/multilingual/), each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
|
||||
On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code.
|
||||
|
||||
In `/posts/my-new-post.es.md`:
|
||||
|
||||
@@ -117,22 +108,22 @@ aliases:
|
||||
|
||||
For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs.
|
||||
|
||||
Luckily, redirects can be handled easily with _aliases_ in Hugo.
|
||||
Luckily, redirects can be handled easily with **aliases** in Hugo.
|
||||
|
||||
### How Hugo Aliases Work
|
||||
|
||||
When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target.
|
||||
When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target.
|
||||
|
||||
Assuming a baseURL of `mysite.tld`, the contents of the html file will look something like:
|
||||
Assuming a baseURL of `yoursite.com`, the contents of the html file will look something like:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>http://mysite.tld/posts/my-original-url</title>
|
||||
<link rel="canonical" href="http://mysite.tld/posts/my-original-url"/>
|
||||
<title>http://yoursite.com/posts/my-original-url</title>
|
||||
<link rel="canonical" href="http://yoursite.com/posts/my-original-url"/>
|
||||
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
|
||||
<meta http-equiv="refresh" content="0; url=http://mysite.tld/posts/my-original-url"/>
|
||||
<meta http-equiv="refresh" content="0; url=http://yoursite.com/posts/my-original-url"/>
|
||||
</head>
|
||||
</html>
|
||||
```
|
||||
@@ -142,7 +133,7 @@ The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in t
|
||||
### Customizing
|
||||
|
||||
You may customize this alias page by creating an alias.html template in the
|
||||
layouts folder of your site. In this case, the data passed to the template is
|
||||
layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is
|
||||
|
||||
`Permalink`
|
||||
: the link to the page being aliased
|
||||
@@ -150,6 +141,15 @@ layouts folder of your site. In this case, the data passed to the template is
|
||||
`Page`
|
||||
: the Page data for the page being aliased
|
||||
|
||||
### Important Behaviors of Aliases
|
||||
|
||||
1. Hugo makes no assumptions about aliases. They also do not change based
|
||||
on your UglyURLs setting. You need to provide absolute paths to your web root
|
||||
and the complete filename or directory.
|
||||
|
||||
2. Aliases are rendered *before* to any content and will be overwritten by
|
||||
any content with the same location.
|
||||
|
||||
## Pretty URLs
|
||||
|
||||
Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work.
|
||||
@@ -175,15 +175,15 @@ If you want a specific piece of content to have an exact URL, you can specify th
|
||||
.
|
||||
└── content
|
||||
└── about
|
||||
| └── _index.md // <- http://1.com/about/
|
||||
| └── _index.md // <- http://yoursite.com/about/
|
||||
├── post
|
||||
| ├── firstpost.md // <- http://1.com/post/firstpost/
|
||||
| ├── firstpost.md // <- http://yoursite.com/post/firstpost/
|
||||
| ├── happy
|
||||
| | └── ness.md // <- http://1.com/post/happy/ness/
|
||||
| └── secondpost.md // <- http://1.com/post/secondpost/
|
||||
| | └── ness.md // <- http://yoursite.com/post/happy/ness/
|
||||
| └── secondpost.md // <- http://yoursite.com/post/secondpost/
|
||||
└── quote
|
||||
├── first.md // <- http://1.com/quote/first/
|
||||
└── second.md // <- http://1.com/quote/second/
|
||||
├── first.md // <- http://yoursite.com/quote/first/
|
||||
└── second.md // <- http://yoursite.com/quote/second/
|
||||
```
|
||||
|
||||
Here's the same organization run with `hugo --uglyURLs`:
|
||||
@@ -192,15 +192,15 @@ Here's the same organization run with `hugo --uglyURLs`:
|
||||
.
|
||||
└── content
|
||||
└── about
|
||||
| └── _index.md // <- http://1.com/about/
|
||||
| └── _index.md // <- http://yoursite.com/about/
|
||||
├── post
|
||||
| ├── firstpost.md // <- http://1.com/post/firstpost.html
|
||||
| ├── firstpost.md // <- http://yoursite.com/post/firstpost.html
|
||||
| ├── happy
|
||||
| | └── ness.md // <- http://1.com/post/happy/ness.html
|
||||
| └── secondpost.md // <- http://1.com/post/secondpost.html
|
||||
| | └── ness.md // <- http://yoursite.com/post/happy/ness.html
|
||||
| └── secondpost.md // <- http://yoursite.com/post/secondpost.html
|
||||
└── quote
|
||||
├── first.md // <- http://1.com/quote/first.html
|
||||
└── second.md // <- http://1.com/quote/second.html
|
||||
├── first.md // <- http://yoursite.com/quote/first.html
|
||||
└── second.md // <- http://yoursite.com/quote/second.html
|
||||
```
|
||||
|
||||
|
||||
@@ -208,14 +208,14 @@ Here's the same organization run with `hugo --uglyURLs`:
|
||||
|
||||
By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`, i.e. `canonifyURLs` defaults to `false`.
|
||||
|
||||
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = http://yoursite.example.com/` defined in the site-wide `config.toml`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.example.com/css/foo.css`.
|
||||
By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = http://yoursite.com/` defined in the site-wide `config.toml`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.com/css/foo.css`.
|
||||
|
||||
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note though that all real browsers handle this client-side without issues.
|
||||
Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issues.
|
||||
|
||||
Benefits of non-canonicalization include being able to have resource inclusion be scheme-relative, so that http vs https can be decided based on how this page was retrieved.
|
||||
Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved.
|
||||
|
||||
{{% note "`canonifyURLs` default change" %}}
|
||||
In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. So, please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
|
||||
In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions.
|
||||
{{% /note %}}
|
||||
|
||||
To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13.
|
||||
@@ -234,12 +234,14 @@ hugo config | FINDSTR /I canon
|
||||
|
||||
By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system.
|
||||
|
||||
Setting `relativeURLs` to `true` in the site configuration will cause Hugo to rewrite all relative URLs to be relative to the current content.
|
||||
Setting `relativeURLs` to `true` in your [site configuration][configuration] will cause Hugo to rewrite all relative URLs to be relative to the current content.
|
||||
|
||||
For example, if the `/post/first/` page contained a link with a relative URL of `/about/`, Hugo would rewrite that URL to `../../about/`.
|
||||
For example, if the `/post/first/` page contained a link to `/about/`, Hugo would rewrite that URL to `../../about/`.
|
||||
|
||||
[configuration]: /getting-started/configuration/
|
||||
[Content Organization]: /content-management/content-organization/
|
||||
[flag from the command line]: /getting-started/basic-usage/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[multilingual]: /content-management/multilingual-mode/
|
||||
[sections]: /content-management/sections/
|
||||
[site configuration]: /project-organization/configuration/
|
||||
+1
-1
@@ -49,7 +49,7 @@ tags: []
|
||||
image: "yourimage.jpg"
|
||||
toc: false
|
||||
title: my hugo site name
|
||||
notesforauthors: "For the image, only include the file name *without* a directory/path, which is taken care of in the templating. See the showcase contribution page at gohugo.io/contribute-to-hugo/add-your-site-to-the-showcase/ for more details. As always, feel free to delete `notesforauthors` or modify for anyone in the future who may edit the content in this file."
|
||||
notesforauthors: "For the image, only include the file name *without* a directory/path, which is taken care of in the templating. See the showcase contribution page at gohugo.io/contribute/add-your-site-to-the-showcase/ for more details. As always, feel free to delete `notesforauthors` or modify for anyone in the future who may edit the content in this file."
|
||||
---
|
||||
```
|
||||
|
||||
+6
-6
@@ -10,7 +10,7 @@ tags: [dev,open source]
|
||||
authors: [digitalcraftsman]
|
||||
weight: 10
|
||||
draft: false
|
||||
aliases: [/contribute-to-hugo/contribute-to-hugo-development/]
|
||||
aliases: [/contribute/contribute-to-hugo-development/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
notesforauthors:
|
||||
@@ -141,11 +141,11 @@ If you're not fimiliar with this term, GitHub's [help pages](https://help.github
|
||||
|
||||
Open the [Hugo repository](https://github.com/spf13/hugo) on Github and click on the "Fork" button in the top right.
|
||||
|
||||
|
||||
|
||||
|
||||
Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
|
||||
|
||||
|
||||
|
||||
|
||||
Switch back to the terminal and move into the directory of the cloned master repository from the last step.
|
||||
|
||||
@@ -350,7 +350,7 @@ We made a lot of progress. Good work. In this step we finally open a pull reques
|
||||
|
||||
You should find a green button labeld with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
|
||||
|
||||
|
||||
|
||||
|
||||
The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
|
||||
|
||||
@@ -358,13 +358,13 @@ The new page summaries the most important information of your pull request. Scro
|
||||
|
||||
Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
|
||||
|
||||
|
||||
|
||||
|
||||
### Automatic builds
|
||||
|
||||
We use the [Travis CI loop](https://travis-ci.org/spf13/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) to compile Hugo with your additions. This should ensure that everything works as expected before merging your pull request. This in most cases only relevant if you made changes to the codebase of Hugo.
|
||||
|
||||
|
||||
|
||||
|
||||
Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems.
|
||||
|
||||
+2
@@ -151,6 +151,8 @@ The Hugo docs are not especially prescriptive in terms of grammar and usage. We
|
||||
|
||||
## Pages Needing Code Examples
|
||||
|
||||
Examples
|
||||
|
||||
{{< needsexamples >}}
|
||||
|
||||
## How Content is Ordered in the Docs
|
||||
@@ -18,7 +18,17 @@ draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
Every `Page` has a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path.
|
||||
|
||||
## Advanced Example
|
||||
`GetPage` looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages, such as the home page or a section, from a template:
|
||||
|
||||
{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
|
||||
|
||||
This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found.
|
||||
|
||||
The valid page kinds are: *home, section, taxonomy and taxonomyTerm.*
|
||||
|
||||
**The following is a good example of `.GetPage`**:
|
||||
|
||||
<https://discuss.gohugo.io/t/problem-with-loop-and-scratch/5597
|
||||
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: absurl
|
||||
linktitle: absURL
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: abslangurl and rellangurl
|
||||
linktitle: absLangURL and relLangURL
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [multilingual,i18n,urls]
|
||||
categories: [functions]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: [/functions/absurl/,/functions/rellangurl/]
|
||||
needsexamples: true
|
||||
---
|
||||
|
||||
These functions are similar to their [`absURL` and `relURL`](/functions/absurl-and-relurl) relatives but will add the correct language prefix when the site is configured with more than one language.
|
||||
|
||||
So for a site `baseURL` set to `http://yoursite.com/hugo/` and the current language is `en`:
|
||||
|
||||
```golang
|
||||
{{ "blog/" | absLangURL }} → "http://yoursite.com/hugo/en/blog/"
|
||||
{{ "blog/" | relLangURL }} → "/hugo/en/blog/"
|
||||
```
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: absurl and relurl
|
||||
linktitle: absURL and relURL
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: [/functions/relurl/]
|
||||
---
|
||||
|
||||
Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `http://yoursite.com/hugo/`:
|
||||
|
||||
```golang
|
||||
{{ "mystyle.css" | absURL }} → "http://yoursite.com/hugo/mystyle.css"
|
||||
{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css"
|
||||
{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/"
|
||||
{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/"
|
||||
```
|
||||
|
||||
The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data for SEO][jsonld] where some of your images for a piece of content may or may not be hosted locally:
|
||||
|
||||
{{% code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" %}}
|
||||
```html
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context" : "http://schema.org",
|
||||
"@type" : "BlogPosting",
|
||||
"image" : {{ apply .Params.images "absURL" "." }}
|
||||
}
|
||||
</script>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
The above uses the [apply function][] and also exploits the fact that 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.
|
||||
|
||||
{{% note "Ending Slash" %}}
|
||||
`absURL` and `relURL` are smart about missing slashes, but they will *not* add a closing slash to a URL if it is not present.
|
||||
{{% /note %}}
|
||||
|
||||
[apply function]: /functions/apply/
|
||||
[configuration]: /getting-started/configuration/
|
||||
[jsonld]: https://developers.google.com/search/docs/guides/intro-structured-data
|
||||
[safejs]: /functions/safejs
|
||||
+102
-5
@@ -1,14 +1,13 @@
|
||||
---
|
||||
title: apply
|
||||
linktitle: apply
|
||||
description:
|
||||
description: Given a map, array, or slice, `description` returns a new slice with a function applied over it.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [advanced]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
@@ -16,8 +15,106 @@ relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
## Example
|
||||
Given a map, array, or slice, `apply` returns a new slice with a function applied over it. `apply` expects at least three parameters, depending on the function being applied.
|
||||
|
||||
## Advanced Example
|
||||
1. The first parameter is the sequence to operate on
|
||||
2. The second parameter is the name of the function as a string, which must be in the [Hugo function map][functions].
|
||||
3. After that, the parameters to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against.
|
||||
|
||||
Here is an example of a content file with `name:` as a front matter field:
|
||||
|
||||
```toml
|
||||
+++
|
||||
names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
|
||||
+++
|
||||
```
|
||||
|
||||
You can then use `apply` as follows:
|
||||
|
||||
```golang
|
||||
{{ apply .Params.names "urlize" "." }}
|
||||
```
|
||||
|
||||
Which will result as follows:
|
||||
|
||||
```
|
||||
"derek-perkins", "joe-bergevin", "tanner-linsley"
|
||||
```
|
||||
|
||||
This is *roughly* equivalent to using the following with [range][]
|
||||
|
||||
```golang
|
||||
{{ range .Params.names }}{{ . | urlize }}{{ end }}
|
||||
```
|
||||
|
||||
However, it isn’t possible to provide the output of a range to the [`delimit` function][delimit], so you need to `apply` it.
|
||||
|
||||
If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
|
||||
|
||||
{{% code file="layouts/partial/post-tag-list.html" copy="false" %}}
|
||||
```html
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $len := len . }}
|
||||
{{ if eq $len 1 }}
|
||||
{{ partial "post/tag/link" (index . 0) }}
|
||||
{{ else }}
|
||||
{{ $last := sub $len 1 }}
|
||||
{{ range first $last . }}
|
||||
{{ partial "post/tag/link" . }},
|
||||
{{ end }}
|
||||
{{ partial "post/tag/link" (index . $last) }}
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% code file="layouts/partial/post-tag-link.html" copy="false" %}}
|
||||
```html
|
||||
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
This works, but the complexity of `post-tag-list.html` is fairly high: the Hugo template needs to perform special behavior for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like `Tags: tag1 , tag2 , tag3` because of the way that the HTML is generated and then interpreted by a browser.
|
||||
|
||||
This first version of `layouts/partials/post-tag-list.html` separates all of the operations for ease of reading; the combined and DRYer version is shown next:
|
||||
|
||||
```html
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ $sort := sort . }}
|
||||
{{ $links := apply $sort "partial" "post-tag-link" "." }}
|
||||
{{ $clean := apply $links "chomp" "." }}
|
||||
{{ delimit $clean ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Now in the complete 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 a DRYer version of the preceding example:
|
||||
|
||||
{{% code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" %}}
|
||||
```html
|
||||
{{ with .Params.tags }}
|
||||
<div class="tags-list">
|
||||
Tags:
|
||||
{{ delimit (apply (apply (sort .) "partial" "post-tag-link" ".") "chomp" ".") ", " }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% note %}}
|
||||
`apply` does not work when receiving the sequence as an argument through a pipeline.
|
||||
{{% /note %}}
|
||||
|
||||
[chome]: /functions/chomp/
|
||||
[delimit]: /functions/delimit/
|
||||
[functions]: /functions/
|
||||
[partials]: /templates/partial-templates/
|
||||
[range]: /functions/range/
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: base64
|
||||
linktitle: base64
|
||||
description: base64Encode and base64Decode let you easily decode content with a base64 encoding and vice versa through pipes.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: []
|
||||
relatedfuncs: []
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`base64Encode` and `base64Decode` let you easily decode content with a base64 encoding and vice versa through pipes. Let's take a look at an example:
|
||||
|
||||
{{% code "base64-input.html" %}}
|
||||
```html
|
||||
<p>Hello world = {{ "Hello world" | base64Encode }}</p>
|
||||
<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% output "base-64-output.html" %}}
|
||||
```html
|
||||
<p>Hello world = SGVsbG8gd29ybGQ=</p>
|
||||
<p>SGVsbG8gd29ybGQ = Hello world</p>
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
You can also pass other data types as arguments to the template function which tries to convert them. The following will convert *42* from an integer to a string because both `base64Encode` and `base64Decode` always return a string.
|
||||
|
||||
```
|
||||
{{ 42 | base64Encode | base64Decode }}
|
||||
=> "42" rather than 42
|
||||
```
|
||||
|
||||
## `base64` with APIs
|
||||
|
||||
Using base64 to decode and encode becomes really powerful if we have to handle
|
||||
responses from APIs.
|
||||
|
||||
```golang
|
||||
{{ $resp := getJSON "https://api.github.com/repos/spf13/hugo/readme" }}
|
||||
{{ $resp.content | base64Decode | markdownify }}
|
||||
```
|
||||
|
||||
The response of the GitHub API contains the base64-encoded version of the [README.md](https://github.com/spf13/hugo/blob/master/README.md) in the Hugo repository. Now we can decode it and parse the Markdown. The final output will look similar to the rendered version on GitHub.
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: base64decode
|
||||
linktitle: base64Decode
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: base64encode
|
||||
linktitle: base64Encode
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: countrunes and countwords
|
||||
linktitle: countrunes and countwords
|
||||
description: countrunes and countwords both serve as a means to quantify the total the length of your content.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: [counting, word count]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: [/functions/countrunes/,/functions/countwords/]
|
||||
---
|
||||
|
||||
`countwords` tries to convert the passed content to a string and counts each word in it. The template function works similar to the [.WordCount page variable][pagevars].
|
||||
|
||||
```html
|
||||
{{ "Hugo is a static site generator." | countwords }}
|
||||
<!-- outputs a content length of 6 words. -->
|
||||
```
|
||||
|
||||
|
||||
In contrast with counting every word, the `countrunes` function determines the number of runes in the content and excludes any whitespace. This has specific utility if you are dealing with CJK-like languages.
|
||||
|
||||
```html
|
||||
{{ "Hello, 世界" | countrunes }}
|
||||
<!-- outputs a content length of 8 runes. -->
|
||||
```
|
||||
|
||||
[pagevars]: /variables/page-variables/
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: countrunes
|
||||
linktitle: countrunes
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
@@ -6,18 +6,12 @@ godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [dates,time]
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [dates,time]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
---
|
||||
@@ -1,24 +1,29 @@
|
||||
---
|
||||
title: i18n
|
||||
linktitle: i18n
|
||||
description:
|
||||
description: Translates a piece of content based on your i18n configuration files.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: [internationalization,i18n,multilingual]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
This translates a piece of content based on your `i18n/en-US.yaml` (and friends) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository.
|
||||
|
||||
## Advanced Example
|
||||
```golang
|
||||
{{ i18n "translation_id" }}
|
||||
```
|
||||
|
||||
{{% note "Alias `T`" %}}
|
||||
`T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`.
|
||||
{{% /note %}}
|
||||
|
||||
For more information about string translations, see [Translation of strings](/content-management/multilingual-mode/#translation-of-strings).
|
||||
@@ -1,24 +1,20 @@
|
||||
---
|
||||
title: abslangurl
|
||||
linktitle: absLangURL
|
||||
title: now
|
||||
linktitle: now
|
||||
description:
|
||||
godocref:
|
||||
godocref: https://godoc.org/time#Time
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [multilingual,i18n,urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [dates,time]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
needsexamples: true
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
`now` returns the current local time as a [`time.Time`](https://godoc.org/time#Time).
|
||||
@@ -18,7 +18,26 @@ draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
### partialCached
|
||||
|
||||
## Advanced Example
|
||||
The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. Here is the simplest usage:
|
||||
|
||||
```golang
|
||||
{{ partialCached "footer.html" . }}
|
||||
```
|
||||
|
||||
You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section:
|
||||
|
||||
{{% code file="partial-cached-example.html" %}}
|
||||
```
|
||||
{{ partialCached "footer.html" . .Section }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need:
|
||||
|
||||
```
|
||||
{{ partialCached "footer.html" . .Params.country .Params.province }}
|
||||
```
|
||||
|
||||
Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key.
|
||||
@@ -1,24 +1,31 @@
|
||||
---
|
||||
title: querify
|
||||
linktitle:
|
||||
linktitle: querify
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [urls]
|
||||
godocref:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
workson: []
|
||||
relatedfuncs: []
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
`querify` takes a set of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL. E.g.
|
||||
|
||||
## Advanced Example
|
||||
The following example creates a link to a search results page on Google.
|
||||
|
||||
```html
|
||||
<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
|
||||
```
|
||||
|
||||
This example renders the following HTML:
|
||||
|
||||
```html
|
||||
<a href="https://www.google.com?page=3&q=test">Search</a>
|
||||
```
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: readFile
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [files]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: readDir
|
||||
title: readdir and readfile
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
@@ -8,17 +8,11 @@ publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [files]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
aliases: [/functions/readdir/,/functions/readfile/]
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: ref and relref
|
||||
linktitle: ref and relref
|
||||
description: Looks up a content page by relative path or logical name to return the content page's permalink.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: [cross references, anchors]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: [relref]
|
||||
deprecated: false
|
||||
aliases: [/functions/ref/,/functions/relref/]
|
||||
---
|
||||
|
||||
These two functions looks up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink. Both functions require a `Page` object (usually satisfied with a "`.`"):
|
||||
|
||||
```golang
|
||||
{{ relref . "about.md" }}
|
||||
```
|
||||
|
||||
These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
|
||||
|
||||
For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: relLangURL
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: [internationalization,multilingual,i18n,urls]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: relURL
|
||||
linktitle: relURL
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: relref
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -18,7 +18,14 @@ draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
Takes a view to render the content with. The view is an alternate layout, and should be a file name that points to a template in one of the locations specified in the documentation for [Content Views](/templates/views).
|
||||
|
||||
## Advanced Example
|
||||
This function is only available on a piece of content, and in list context.
|
||||
|
||||
This example could render a piece of content using the content view located at `/layouts/_default/summary.html`:
|
||||
|
||||
```golang
|
||||
{{ range .Data.Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
```
|
||||
@@ -1,24 +1,77 @@
|
||||
---
|
||||
title: safeURL
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
title: safeurl
|
||||
linktitle: safeURL
|
||||
description: Declares the provided string as a safe URL or URL substring.
|
||||
godocref: https://golang.org/pkg/html/template/#HTMLEscape
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [strings,urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986][]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector.
|
||||
|
||||
## Advanced Example
|
||||
Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless.
|
||||
|
||||
The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
|
||||
|
||||
{{% code file="config.toml" copy="false" %}}
|
||||
```toml
|
||||
[[menu.main]]
|
||||
name = "IRC: #golang at freenode"
|
||||
url = "irc://irc.freenode.net/#golang"
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
|
||||
|
||||
{{% code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" %}}
|
||||
```html
|
||||
<ul class="sidebar-menu">
|
||||
{{ range .Site.Menus.main }}
|
||||
<li><a href="{{ .URL }}">{{ .Name }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
This partial would produce the following HTML output:
|
||||
|
||||
{{% output file="bad-url-sidebar-menu-output.html" %}}
|
||||
```html
|
||||
<ul class="sidebar-menu">
|
||||
<li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
|
||||
</ul>
|
||||
```
|
||||
{{% /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" %}}
|
||||
```html
|
||||
<ul class="sidebar-menu">
|
||||
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>
|
||||
</ul>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
With the `.URL` page variable piped through `safeURL`, we get the desired output:
|
||||
|
||||
{{% output file="correct-url-sidebar-menu-output.html" %}}
|
||||
```html
|
||||
<ul class="sidebar-menu">
|
||||
<li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
|
||||
</ul>
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
[configuration]: /getting-started/configuration/
|
||||
[menus]: /content-management/menus/
|
||||
[RFC 3986]: http://tools.ietf.org/html/rfc3986
|
||||
|
||||
@@ -18,7 +18,7 @@ draft: false
|
||||
aliases: [/extras/scratch/,/doc/scratch/]
|
||||
---
|
||||
|
||||
`Scratch` -- a "scratchpad" for your page-scoped variables. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
|
||||
**`Scratch`** is a "scratchpad" for your [page-scoped variables][pagevars]. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.
|
||||
|
||||
`Scratch` is added to both `Page` and `Shortcode` -- with following methods:
|
||||
|
||||
@@ -68,3 +68,4 @@ The usage is best illustrated with some samples:
|
||||
**Note:** The examples above uses the special `$` variable, which refers to the top-level node. This is the behavior you most likely want, and will help remove some confusion when using `Scratch` inside page range loops -- and you start inadvertently calling the wrong `Scratch`. But there may be use cases for `{{ .Scratch.Add "key" "some value" }}`.
|
||||
|
||||
|
||||
[pagevars]: /variables/page-variables/
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: sha
|
||||
linktitle: sha
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [functions]
|
||||
tags: []
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
`sha1` hashes the given input and returns its SHA1 checksum.
|
||||
|
||||
```html
|
||||
{{ sha1 "Hello world, gophers!" }}
|
||||
<!-- returns the string "c8b5b0e33d408246e30f53e32b8f7627a7a649d4" -->
|
||||
```
|
||||
|
||||
`sha256` hashes the given input and returns its SHA256 checksum.
|
||||
|
||||
```html
|
||||
{{ sha256 "Hello world, gophers!" }}
|
||||
<!-- returns the string "6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46" -->
|
||||
```
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: sha1
|
||||
linktitle: sha1
|
||||
description:
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: sha256
|
||||
linktitle: sha256
|
||||
description:
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: []
|
||||
categories: [functions]
|
||||
toc:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
## Advanced Example
|
||||
|
||||
@@ -6,21 +6,20 @@ godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [dates,time]
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [dates,time]
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
refer to http://gohugo.io/templates/go-templates/#template-example-show-only-upcoming-events
|
||||
|
||||
## Advanced Example
|
||||
`time` converts a timestamp string into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields:
|
||||
|
||||
```
|
||||
{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z"
|
||||
{{ (time "2016-05-28").YearDay }} → 149
|
||||
{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds
|
||||
```
|
||||
+54
-11
@@ -1,24 +1,67 @@
|
||||
---
|
||||
title: urlize
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
linktitle: urlize
|
||||
description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
tags: [strings,urls]
|
||||
categories: [functions]
|
||||
toc:
|
||||
tags: [urls,strings]
|
||||
godocref:
|
||||
signature:
|
||||
workson: []
|
||||
hugoversion:
|
||||
relatedfuncs: []
|
||||
deprecated: false
|
||||
draft: false
|
||||
aliases: []
|
||||
workson: []
|
||||
relatedfuncs: []
|
||||
---
|
||||
|
||||
## Example
|
||||
`urlize` takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens ("`-`").
|
||||
|
||||
## Advanced Example
|
||||
The following examples pull from a content file with the following front matter:
|
||||
|
||||
{{% code file="content/blog/greatest-city.md" copy="false"%}}
|
||||
```toml
|
||||
+++
|
||||
title = "The World's Greatest City"
|
||||
location = "Chicago IL"
|
||||
tags = ["pizza","beer","hot dogs"]
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
The following might be used as a partial within a [single page template][singletemplate]:
|
||||
|
||||
{{% code file="layouts/partials/content-header.html" %}}
|
||||
```html
|
||||
<header class="content-header">
|
||||
<h1>{{.Title}}</h1>
|
||||
{{ with .Params.location }}
|
||||
<div class="location"><a href="/locations/{{ . | urlize}}">{{.}}</a></div>
|
||||
{{ end }}
|
||||
<div class="tags">
|
||||
{{range .Params.tags}}
|
||||
<a href="/tags/{{ . | urlize }}" class="tag">{{ . }}</a><br>
|
||||
{{end}}
|
||||
</div>
|
||||
</header>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs.
|
||||
|
||||
{{% output file="/blog/greatest-city/index.html" %}}
|
||||
```html
|
||||
<header class="content-header">
|
||||
<h1>The World's Greatest City</h1>
|
||||
<div class="location"><a href="/locations/chicago-il/">Chicago IL</a></div>
|
||||
<div class="tags">
|
||||
<a href="/tags/pizza" class="tag">pizza</a>
|
||||
<a href="/tags/beer" class="tag">beer</a>
|
||||
<a href="/tags/hot-dogs" class="tag">hot dogs</a>
|
||||
</div>
|
||||
</header>
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
|
||||
[singletemplate]: /templates/single-page-template/
|
||||
@@ -342,7 +342,7 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
|
||||
{{< bfconfig >}}
|
||||
|
||||
{{% note %}}
|
||||
1. Blackfriday flags are **case sensitive** as of Hugo v0.15.
|
||||
1. Blackfriday flags are *case sensitive* as of Hugo v0.15.
|
||||
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 the site setting there. See [site configuration for more information](/content-management/front-matter/#override-global-blackfriday-configuration).
|
||||
{{% /note %}}
|
||||
|
||||
@@ -367,16 +367,15 @@ blackfriday:
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
## Specs for Configuration Formats
|
||||
|
||||
* [TOML Spec][]
|
||||
* [YAML Spec][]
|
||||
* [JSON Spec][]
|
||||
* [TOML Spec][toml]
|
||||
* [YAML Spec][yaml]
|
||||
* [JSON Spec][json]
|
||||
|
||||
[`.Site.Params`]: /variables/
|
||||
[directory structure]: /project-organization/directory-structure
|
||||
[JSON Spec]: /documents/ecma-404-json-spec.pdf
|
||||
[json]: /documents/ecma-404-json-spec.pdf
|
||||
[templates]: /templates/
|
||||
[TOML Spec]: https://github.com/toml-lang/toml
|
||||
[YAML Spec]: http://yaml.org/spec/
|
||||
[toml]: https://github.com/toml-lang/toml
|
||||
[yaml]: http://yaml.org/spec/
|
||||
@@ -58,7 +58,7 @@ Hugo Static Site Generator v0.18.1 BuildDate: 2016-12-30T05:02:43-05:00
|
||||
|
||||
## Step 2. Scaffold Your Hugo Bookshelf Website
|
||||
|
||||
Hugo's CLI has commands that allow you to quickly scaffold a new website. Navigate to your preferred location on your file system and create a new Hugo site `bookshelf` by executing the `hugo new` command as follows:
|
||||
Hugo's CLI has commands that allow you to quickly scaffold a new website. Navigate to your preferred location on your file system and create a new Hugo site `bookshelf` by executing the `hugo new` command:
|
||||
|
||||
```bash
|
||||
hugo new site bookshelf
|
||||
@@ -539,48 +539,15 @@ in 17 ms
|
||||
|
||||
After you run the `hugo` command, a `bookshelf/public` directory will be created containing the generated website source.
|
||||
|
||||
## Step 12. Deploy Your Bookshelf Website on GitHub Pages
|
||||
## Step 9. What Next?
|
||||
|
||||
{{% note "GitHub Account" %}}
|
||||
The following step assumes that you have a working familiarity with Git version control and also a GitHub account. A GitHub account is required to leverage Pages, a static website hosting service that is complimentary for GitHub users. [Setting up a GitHub account is free](https://github.com/join).
|
||||
**Congratulations!** Your new `bookshelf`/public directory is a fully generated, deployable Hugo website. Since all your files are *static*, you have innumerable options for hosting, and your new directory structure and simple content format are going to make scaling your website a breeze.
|
||||
|
||||
There is more than one way to host your site on GitHub. Be sure to check out [Hosting on GitHub](/hosting-and-deployment/hosting-on-github/) and [Deployment with Wercker](/hosting-and-deployment/deployment-with-wercker).
|
||||
{{% /note %}}
|
||||
Here's what you should look into next:
|
||||
|
||||
First, let's set up Git version control for your bookshelf website and include a `.gitignore` file to prevent tracking of the `public` and `themes` directories. From within your root project directory, you can use the following one-liner:
|
||||
|
||||
{{% code file="set-up-git.sh" %}}
|
||||
```bash
|
||||
git init && echo "/public/" >> .gitignore && echo "/themes/" >> .gitignore && git add . && git commit -m "Initial commit"
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now the Git repositories under `bookshelf/themes` won't conflict with your `bookshelf` repository, and neither will a Git repository in `bookshelf/public`.
|
||||
|
||||
Create a new repository on GitHub named `bookshelf`. Do not create a `README.md`. Once you have created a new repository, change into the `public` directory within `bookshelf` and create a *new* Git repository and add your new GitHub repository as the remote. Keep in mind that you will need to replace `<github-username>` with your actual username and repository URL:
|
||||
|
||||
```bash
|
||||
cd public
|
||||
git init
|
||||
git remote add origin git@github.com:<github-username>/bookshelf.git
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
Once everything in `public` has been pushed to your new GitHub repository, navigate to the repository's settings and scroll to the "GitHub Pages" section. Select "master branch" from the Source dropdown and then click the **Save** button.
|
||||
|
||||
|
||||
|
||||
In a couple of minutes, your website will be live at `https://<github-username>.github.io/bookshelf/`.
|
||||
|
||||
Now, from within your project's root directory, you can regenerate and update your published website with the following commands. Note that changing your Hugo theme is as simple as changing the `theme` flag appended to the `hugo` build command:
|
||||
|
||||
```bash
|
||||
hugo --theme=hugo_theme_robust
|
||||
cd public
|
||||
git add --all
|
||||
git commit -m "<some change message>"
|
||||
git push
|
||||
```
|
||||
1. [See hosting and deployment options][hostinganddeploy] for sharing your newly created Hugo website with the world.
|
||||
2. [Learn more about Hugo's powerful templating][templating] to tailor your new Hugo website to your specific needs and keep it scaling accordingly.
|
||||
3. [Visit the Hugo Discussion Forum][forum] to ask questions, answer questions, and become an active member of the Hugo community.
|
||||
|
||||
--------
|
||||
|
||||
@@ -594,7 +561,9 @@ git push
|
||||
[configuration]: /getting-started/configuration/
|
||||
[createtheme]: /themes/creating-a-theme/
|
||||
[datatemplates]: /templates/data-templates/
|
||||
[forum]: https://discuss.gohugo.io
|
||||
[frontmatter]: /content-management/front-matter/
|
||||
[hostinganddeploy]: /hosting-and-deployment/
|
||||
[hugodirectories]: /getting-started/directory-structure/
|
||||
[install]: /getting-started/install-hugo/
|
||||
[lists]: /templating/lists/
|
||||
|
||||
@@ -47,4 +47,4 @@ Interested in helping us improve the Hugo docs?
|
||||
2. If you're not up for git and GitHub, start a thread on the ["docs" category in the Hugo Forums][hugodiscussion]
|
||||
|
||||
[hugodiscussion]: https://discuss.gohugo.io/c/feature
|
||||
[contributedocs]: /contribute-to-hugo/contribute-to-the-hugo-docs/
|
||||
[contributedocs]: /contribute/contribute-to-the-hugo-docs/
|
||||
@@ -18,4 +18,4 @@ toc: false
|
||||
The following sites have been built with <i class="icon-love"></i> and Hugo. [Interested in adding your site to the showcase?][addshowcase]
|
||||
|
||||
|
||||
[addshowcase]: /contribute-to-hugo/add-your-site-to-the-showcase/
|
||||
[addshowcase]: /contribute/add-your-site-to-the-showcase/
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Base Templates and Blocks
|
||||
linktitle:
|
||||
description:
|
||||
godocref:
|
||||
description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page) in a syntax that allows for easy extending and overwriting.
|
||||
godocref: https://golang.org/pkg/text/template/#example_Template_block
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
@@ -21,29 +21,28 @@ Go 1.6 includes a powerful new keyword, `block`. This construct allows you to de
|
||||
|
||||
This is the order Hugo searches for a base template:
|
||||
|
||||
1. /layouts/_current-path_/_template-name_-baseof.html, e.g. list-baseof.html.
|
||||
2. /layouts/_current-path_/baseof.html
|
||||
3. /layouts/_default/_template-name_-baseof.html e.g. list-baseof.html.
|
||||
4. /layouts/_default/baseof.html
|
||||
|
||||
For each of the steps above, it will first look in the project, then, if theme is set, in the theme's layouts folder. Hugo picks the first base template found.
|
||||
1. `/layouts/<CURRENTPATH>/<TEMPLATENAME>-baseof.html`
|
||||
2. `/layouts/<CURRENTPATH>/baseof.html`
|
||||
3. `/layouts/_default/<TEMPLATENAME>-baseof.html`
|
||||
4. `/layouts/_default/baseof.html`
|
||||
|
||||
As an example, with a site using the theme `exampletheme`, when rendering the section list for the section `post`. Hugo picks the `section/post.html` as the template and this template has a `define` section that indicates it needs a base template. This is then the lookup order:
|
||||
|
||||
1. `/layouts/section/post-baseof.html`
|
||||
2. `/themes/exampletheme/layouts/section/post-baseof.html`
|
||||
3. `/layouts/section/baseof.html`
|
||||
4. `/themes/exampletheme/layouts/section/baseof.html`
|
||||
5. `/layouts/_default/post-baseof.html`
|
||||
6. `/themes/exampletheme/layouts/_default/post-baseof.html`
|
||||
7. `/layouts/_default/baseof.html`
|
||||
8. `/themes/exampletheme/layouts/_default/baseof.html`
|
||||
2. `/themes/<THEME>/layouts/section/post-baseof.html`
|
||||
3. `/layouts/section/baseof.html`
|
||||
4. `/themes/<THEME>/layouts/section/baseof.html`
|
||||
5. `/layouts/_default/post-baseof.html`
|
||||
6. `/themes/<THEME>/layouts/_default/post-baseof.html`
|
||||
7. `/layouts/_default/baseof.html`
|
||||
8. `/themes/<THEME>/layouts/_default/baseof.html`
|
||||
|
||||
|
||||
## Define the base template
|
||||
## Defining the Base Template
|
||||
|
||||
Let's define a simple base template (`_default/baseof.html`), a shell from which all our pages will start.
|
||||
The following defines a simple base template at `_default/baseof.html`). As a default template, it is the shell from which all our pages will start unless a more specific `*baseof.html` is defined.
|
||||
|
||||
{{% code file="layouts/_default/baseof.html" download="baseof.html" %}}
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
@@ -65,13 +64,14 @@ Let's define a simple base template (`_default/baseof.html`), a shell from which
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Overriding the Base Template
|
||||
|
||||
Your [default list template](/templates/list/)---`_default/list.html`---will inherit all of the code defined in the base template. It could then implement its own "main" block from the base template above like so:
|
||||
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
|
||||
|
||||
{{% code file="layouts/_default/list.html" download="list.html" %}}
|
||||
```html
|
||||
<!-- Note the lack of Go's context "dot" when defining blocks -->
|
||||
{{ define "main" }}
|
||||
<h1>Posts</h1>
|
||||
{{ range .Data.Pages }}
|
||||
@@ -82,13 +82,20 @@ Your [default list template](/templates/list/)---`_default/list.html`---will inh
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /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.
|
||||
{{% note "No Go Context \"Dot\" in Block Definitions" %}}
|
||||
When using the `define` keyword, you do *not* need to use Go templates context reference (i.e., 'The Dot"). (Read more on the [Go Context Dot](/functions/the-dot/).)
|
||||
{{% /note %}}
|
||||
|
||||
In our [default single template](/templates/content/)---`_default/single.html`---let's implement both blocks:
|
||||
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.
|
||||
|
||||
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
|
||||
|
||||
{{% code file="layouts/_default/single.html" download="single.html" %}}
|
||||
```html
|
||||
{{ define "title" }}
|
||||
<!-- This will override the default value set in baseof.html; i.e., "{{.Site.Title}}" in the original example-->
|
||||
{{ .Title }} – {{ .Site.Title }}
|
||||
{{ end }}
|
||||
{{ define "main" }}
|
||||
@@ -96,6 +103,7 @@ In our [default single template](/templates/content/)---`_default/single.html`--
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
This overrides both block areas from the base template with code unique to our single template.
|
||||
|
||||
[hugolists]: /templates/lists
|
||||
[singletemplate]: /templates/single-page-templates/
|
||||
@@ -14,17 +14,14 @@ toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
In addition to the [single content template](/templates/content/), Hugo can render alternative views of
|
||||
your content. These are especially useful in [list templates](/templates/list/).
|
||||
In addition to the [single page content template][singletemplates], Hugo can render alternative views of your content. These are especially useful in [list templates][listtemplates].
|
||||
|
||||
For example you may want content of every type to be shown on the
|
||||
homepage, but only a summary view of it there. Perhaps on a taxonomy
|
||||
list page you would only want a bulleted list of your content. Views
|
||||
make this very straightforward by delegating the rendering of each
|
||||
different type of content to the content itself.
|
||||
Content views are appropriate for cases like the following:
|
||||
|
||||
* You want content of every type to be shown on the homepage but only with limited [summary views][summaries].
|
||||
* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself.
|
||||
|
||||
## Creating a content view
|
||||
## Creating a Content View
|
||||
|
||||
To create a new view, simply create a template in each of your different
|
||||
content type directories with the view name. In the following example, we
|
||||
@@ -34,95 +31,109 @@ content view](/templates/content/) template "single.html". You can even
|
||||
provide a specific view for a given type and continue to use the
|
||||
\_default/single.html for the primary view.
|
||||
|
||||
▾ layouts/
|
||||
▾ post/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
▾ project/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
```bash
|
||||
▾ layouts/
|
||||
▾ post/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
▾ project/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
```
|
||||
|
||||
Hugo also has support for a default content template to be used in the event
|
||||
that a specific template has not been provided for that type. The default type
|
||||
works the same as the other types, but the directory must be called "_default".
|
||||
Content views can also be defined in the "_default" directory.
|
||||
Hugo also has support for a default content template to be used in the event that a specific template has not been provided for that type. The default type works the same as the other types, but the directory must be called "_default". Content views can also be defined in the "_default" directory.
|
||||
|
||||
|
||||
▾ layouts/
|
||||
▾ _default/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
```bash
|
||||
▾ layouts/
|
||||
▾ _default/
|
||||
li.html
|
||||
single.html
|
||||
summary.html
|
||||
```
|
||||
|
||||
## Which Template Will be Rendered?
|
||||
|
||||
## Which Template will be rendered?
|
||||
Hugo uses a set of rules to figure out which template to use when
|
||||
rendering a specific page.
|
||||
Hugo uses a set of rules to figure out which template to use when rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present,
|
||||
then the next one in the list will be used. This enables you to craft
|
||||
specific layouts when you want to without creating more templates
|
||||
than necessary. For most sites only the \_default file at the end of
|
||||
the list will be needed.
|
||||
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites only the \_default file at the end of the list will be needed.
|
||||
|
||||
* /layouts/`TYPE`/`VIEW`.html
|
||||
* /layouts/\_default/`VIEW`.html
|
||||
* /themes/`THEME`/layouts/`TYPE`/`VIEW`.html
|
||||
* /themes/`THEME`/layouts/\_default/`view`.html
|
||||
* `/layouts/<TYPE>/<VIEW>.html`
|
||||
* `/layouts/\_default/<VIEW>.html`
|
||||
* `/themes/<THEME>/layouts/<TYPE>/<VIEW>.html`
|
||||
* `/themes/<THEME>/layouts/\_default/<VIEW>.html`
|
||||
|
||||
## Example: Content View Inside a List
|
||||
|
||||
## Example using views
|
||||
The following example demonstrates how to use content views inside of your [list page templates][listtemplates].
|
||||
|
||||
### rendering view inside of a list
|
||||
### `list.html`
|
||||
|
||||
Using the summary view (defined below) inside of a ([list
|
||||
templates](/templates/list/)).
|
||||
In this example, `.Render` is passed into the template to call the [render function][]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument.
|
||||
|
||||
<section id="main">
|
||||
<div>
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
{{ range .Data.Pages }}
|
||||
This `list.html` content view template is part of a larger `section.html` default template used for [spf13.com][spf]. ([See source on GitHub][spfsourcesection].)
|
||||
|
||||
{{% code file="layouts/_default/list.html" download="list.html" %}}
|
||||
```
|
||||
<section id="main">
|
||||
<div>
|
||||
<h1 id="title">{{ .Title }}</h1>
|
||||
{{ range .Data.Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
</div>
|
||||
</section>
|
||||
{{ end }}
|
||||
</div>
|
||||
</section>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
In the above example, you will notice that we have called `.Render` and passed in
|
||||
which view to render the content with. `.Render` is a special function available on
|
||||
a content which tells the content to render itself with the provided view template.
|
||||
In this example, we are not using the li view. To use this we would
|
||||
change the render line to `{{ .Render "li" }}`.
|
||||
|
||||
|
||||
### li.html
|
||||
### `summary.html`
|
||||
|
||||
Hugo will pass the entire page object to the view template. See [page
|
||||
variables](/templates/variables/) for a complete list.
|
||||
|
||||
This content template is used for [spf13.com](http://spf13.com/).
|
||||
This `summary.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourcesummary].)
|
||||
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
|
||||
### summary.html
|
||||
|
||||
Hugo will pass the entire page object to the view template. See [page
|
||||
variables](/templates/variables/) for a complete list.
|
||||
|
||||
This content template is used for [spf13.com](http://spf13.com/).
|
||||
|
||||
<article class="post">
|
||||
<header>
|
||||
{{% code file="layouts/_default/summary.html" download="summary.html" %}}
|
||||
```html
|
||||
<article class="post">
|
||||
<header>
|
||||
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
|
||||
<div class="post-meta">{{ .Date.Format "Mon, Jan 2, 2006" }} - {{ .FuzzyWordCount }} Words </div>
|
||||
</header>
|
||||
</header>
|
||||
{{ .Summary }}
|
||||
<footer>
|
||||
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
|
||||
</footer>
|
||||
</article>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{ .Summary }}
|
||||
<footer>
|
||||
<a href='{{ .Permalink }}'><nobr>Read more →</nobr></a>
|
||||
</footer>
|
||||
</article>
|
||||
### `li.html`
|
||||
|
||||
Hugo will pass the entire page object to the view template. See [Page Variables][pagevars] for a complete list of variables Hugo makes available to you.
|
||||
|
||||
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" }}`).
|
||||
|
||||
This `li.html` content view template is used for [spf13.com][spf]. ([See source on GitHub][spfsourceli].)
|
||||
|
||||
{{% code file="layouts/_default/li.html" download="li.html" %}}
|
||||
```html
|
||||
<li>
|
||||
<a href="{{ .Permalink }}">{{ .Title }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
[listtemplates]: /templates/lists/
|
||||
[pagevars]: /variables/page-variables/
|
||||
[render function]: /functions/render/
|
||||
[singletemplates]: /templates/single-page-templates/
|
||||
[spf]: http://spf13.com
|
||||
[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html
|
||||
[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html
|
||||
[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html
|
||||
[summaries]: /content-management/content-summaries/
|
||||
[taxonomylists]: /templates/taxonomy-templates/
|
||||
@@ -18,11 +18,13 @@ needsreview: true
|
||||
|
||||
In addition to the [built-in variables](/templates/variables/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
|
||||
|
||||
Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
|
||||
Hugo supports loading data from YAML(http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
|
||||
|
||||
**It even works with [LiveReload](/extras/livereload/).**
|
||||
{{% note %}}
|
||||
Templates using `.Site.Data` even work with LiveReload!
|
||||
{{% /note %}}
|
||||
|
||||
Data Files can also be used in [themes](/themes/overview/), but note: If the same `key` is used in both the main data folder and in the theme's data folder, the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/<MYTHEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag, e.g. `hugo -v`.
|
||||
Data Files can also be used in [Hugo themes][themes], but note: If the same `key` is used in both the root data folder (i.e. `data/`) and in the theme's data folder (i.e., `themes/<THEME>/data/), the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag; e.g., `hugo -v`.
|
||||
|
||||
## The Data Folder
|
||||
|
||||
@@ -228,4 +230,15 @@ your Markdown files until the content has been downloaded.
|
||||
|
||||
- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
|
||||
- GitHub Starred Repositories [in a posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
|
||||
- More? Please tell us!
|
||||
- More? Please tell us!
|
||||
|
||||
## Specs for Configuration Formats
|
||||
|
||||
* [TOML Spec][toml]
|
||||
* [YAML Spec][yaml]
|
||||
* [JSON Spec][json]
|
||||
|
||||
[json]: /documents/ecma-404-json-spec.pdf
|
||||
[themes]: /themes/
|
||||
[toml]: https://github.com/toml-lang/toml
|
||||
[yaml]: http://yaml.org/spec/
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
title: Go Template Primer
|
||||
linktitle: Go Template Primer
|
||||
description:
|
||||
description: Hugo uses Go html/template library, an extremely lightweight and performant, engine as the basis for all Hugo templating.
|
||||
godocref: https://golang.org/pkg/html/template/
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
lastmod: 2017-02-25
|
||||
categories: [templates]
|
||||
tags: [go,fundamentals]
|
||||
weight: 10
|
||||
@@ -15,19 +15,21 @@ toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
Hugo uses the excellent [Go html/template][] library, an extremely lightweight engine that provides just the right amount of logic to be able to create a good static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates.
|
||||
Hugo uses the excellent [Go html/template][gohtmltemplate] library, an extremely lightweight engine that provides just the right amount of logic to be able to create any style of static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates.
|
||||
|
||||
This document is a brief primer on using Go templates. The [Go docs][gohtmltemplate] go into more depth and cover features that aren't mentioned here.
|
||||
{{% note "Go Deep with the Go Docs" %}}
|
||||
This document is only designed as a brief primer. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/).
|
||||
{{% /note %}}
|
||||
|
||||
## Introduction to Go Templates
|
||||
|
||||
Go templates provide an extremely simple template language. It adheres to the belief that only the most basic of logic belongs in the template or view layer. One consequence of this simplicity is that Go templates parse very quickly.
|
||||
Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. As a positive consequence of this simplicity, Go templates parse very quickly.
|
||||
|
||||
A unique characteristic of Go templates is they are content aware. Variables and content will be sanitized depending on the context of where they are used. More details can be found in the [Go docs][gohtmltemplate].
|
||||
A unique characteristic of Go templates is that they are content aware. Variables and content will be sanitized depending on the context of where they are used.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
Golang templates are HTML files with the addition of [variables][variablesparams] and [functions][hugofunctions]. Golang template variables and functions are accessible within `{{ }}`.
|
||||
Golang templates are HTML files with the addition of [variables][variables] and [functions][hugofunctions]. Golang template variables and functions are accessible within `{{ }}`.
|
||||
|
||||
### Accessing a Predefined Variable
|
||||
|
||||
@@ -451,9 +453,9 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
|
||||
|
||||
## Go Templating Example: Show Only Upcoming Events
|
||||
|
||||
Go allows you to do more than what's shown here. Using Hugo's [`where` function](/functions/where/) and Go built-ins, we can list only the items from `content/events/` whose date (set in the [front matter][]) is in the future:
|
||||
Go allows you to do more than what's shown here. Using Hugo's [`where` function](/functions/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="show-upcoming-dates.html" %}}
|
||||
{{% code file="layouts/partials/show-upcoming-dates.html" download="show-upcoming-dates.html" %}}
|
||||
```golang
|
||||
<h4>Upcoming Events</h4>
|
||||
<ul class="upcoming-events">
|
||||
@@ -478,7 +480,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating"
|
||||
[hugoconfig]: /getting-started/configuration/
|
||||
[hugofunctions]: /functions/ "Link to section for Hugo's templating functions"
|
||||
[math functions]: /functions/math
|
||||
[math functions]: /functions/math/
|
||||
[partials]: /templates/partials-templates/ "Link to the partial templates page inside of the templating section of the Hugo docs"
|
||||
[variablesparams]: /variables/ "Link to the list page for the Variables and Params section of the site."
|
||||
[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates."
|
||||
[You can read more about `index` in the Godocs]: http://golang.org/pkg/text/template/ "Godocs page for index function"
|
||||
+1
-1
@@ -16,7 +16,7 @@ needsreview: true
|
||||
|
||||
|
||||
|
||||
## Understanding `.Data.*Pages`
|
||||
## Understanding `.Data.Pages`
|
||||
|
||||
From this image, we can assume that the "homepage" for Section A---presumably, `/section-a/index.html`---is going to list the content pages 1,2,3. In this way, pages 1,2,3 are *data* made available to the template that renders to the .
|
||||
|
||||
+17
-113
@@ -18,7 +18,19 @@ needsreview: true
|
||||
|
||||
A list page template is a template used to render multiple pieces of content in a single HTML page (with the exception of the homepage, which has a [dedicated template][homepage]).
|
||||
|
||||
Hugo uses the term *list* in its truest sense: a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is being listed (e.g., [taxonomies][], [sections][], and [RSS][]). The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
|
||||
Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed:
|
||||
|
||||
* [Taxonomy terms pages][taxonomy terms]
|
||||
* [Taxonomy list pages][taxonomy lists]
|
||||
* [Section list pages][section templates]
|
||||
* [RSS][]
|
||||
|
||||
The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
```yaml
|
||||
---
|
||||
@@ -38,120 +50,13 @@ weight: 70
|
||||
---
|
||||
```
|
||||
|
||||
## \_index.md and 'Everything is a Page'
|
||||
|
||||
As of version v0.18 Hugo now treats '[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)'. This allows you to add content and front matter to any page - including List pages like [Sections](/content/sections/), [Taxonomies](/taxonomies/overview/), [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Home page](/templates/homepage/).
|
||||
|
||||
In order to take advantage of this behaviour you need to do a few things.
|
||||
|
||||
1. Create an \_index.md file that contains the front matter and content you would like to apply.
|
||||
|
||||
2. Place the \_index.md file in the correct place in the directory structure.
|
||||
|
||||
3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the \_index.md file to be rendered on the respective page.
|
||||
|
||||
### How \_index.md Pages Work
|
||||
|
||||
Before continuing it's important to know that this page must reference certain templates to describe how the \_index.md page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
|
||||
|
||||
If this is confusing or you are unfamiliar with Hugo's template hierarchy, visit the various template pages listed below. You may need to find the 'active' template responsible for any particular page on your own site by going through the template hierarchy and matching it to your particular setup/theme you are using.
|
||||
|
||||
- [Home page template](/templates/homepage/)
|
||||
- [Content List templates](/templates/list/)
|
||||
- [Single Content templates](/templates/content/)
|
||||
- [Taxonomy Terms templates](/templates/terms/)
|
||||
|
||||
Now that you've got a handle on templates lets recap some Hugo basics to understand how to use an \_index.md file with a List page.
|
||||
|
||||
1. Sections and Taxonomies are 'List' pages, NOT single pages.
|
||||
2. List pages are rendered using the template heirarchy found in the [Content - List Template](http://localhost:1313/templates/list/) docs.
|
||||
3. The Home page, though technically a List page, can have [it's own template](/templates/homepage/) at layouts/index.html rather than \_default/list.html. Many themes exploit this behaviour so you are likely to encounter this specific use case.
|
||||
4. Taxonomy terms pages are 'lists of metadata' not lists of content, so [have their own templates](/templates/terms/).
|
||||
|
||||
Let's put all this information together:
|
||||
|
||||
> **\_index.md files used in List pages, Terms pages or the Home page are NOT rendered as single pages or with Single Content templates.**
|
||||
|
||||
> **All pages, including List pages, can have front matter and front matter can have markdown content - meaning \_index.md files are the way to _provide_ front matter and content to the respective List/Terms/Home page.**
|
||||
|
||||
Here are a couple of examples to make it clearer...
|
||||
|
||||
```
|
||||
| \_index.md location | Page affected | Rendered by |
|
||||
| ------------------- | ------------ | ----------- |
|
||||
| /content/post/\_index.md | site.com/post/ | /layouts/section/post.html |
|
||||
| /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html |
|
||||
```
|
||||
|
||||
## Why \_index.md files are used
|
||||
|
||||
With a Single page such as a post it's possible to add the front matter and content directly into the .md page itself. With List/Terms/Home pages this is not possible so \_index.md files can be used to provide that front matter/content to them.
|
||||
|
||||
## How to display content from \_index.md files
|
||||
|
||||
From the information above it should follow that content within an \_index.md file won't be rendered in its own Single Page, instead it'll be made available to the respective list, terms, Home page.
|
||||
|
||||
To **_actually render that content_** you need to ensure that the relevant template responsible for rendering the List/Terms/Home page contains (at least) `{{ .Content }}`.
|
||||
|
||||
This is the way to actually display the content within the \_index.md file on the List/Terms/Home page.
|
||||
|
||||
A very simple example is shown in the following default section list page:
|
||||
|
||||
{{% code file="layouts/_default/section.html" download="section.html" %}}
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<main>
|
||||
{{ .Content }}
|
||||
<ul class="contents">
|
||||
{{ range .Paginator.Pages }}
|
||||
<li>{{.Title}}
|
||||
<div>
|
||||
{{ partial "summary.html" . }}
|
||||
</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ partial "pagination.html" . }}
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
You can see `{{ .Content }}` just after the `<main>` element. For this particular example, the content of the \_index.md file will show before the main list of summaries.
|
||||
|
||||
## Where to Organize `\_index.md` Files
|
||||
|
||||
To add content and front matter to the home page, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name \_index on the relevant place on the file system.
|
||||
|
||||
```bash
|
||||
└── content
|
||||
├── _index.md
|
||||
├── categories
|
||||
│ ├── _index.md
|
||||
│ └── photo
|
||||
│ └── _index.md
|
||||
├── post
|
||||
│ ├── _index.md
|
||||
│ └── firstpost.md
|
||||
└── tags
|
||||
├── _index.md
|
||||
└── hugo
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
In the above example \_index.md pages have been added to each section/taxonomy.
|
||||
|
||||
An `_index.md` file has also been added in the top level 'content' directory.
|
||||
|
||||
### Where to place \_index.md for the Homepage Template
|
||||
|
||||
Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the home page.
|
||||
|
||||
## List Defaults
|
||||
|
||||
### Default Templates
|
||||
|
||||
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][]) are both *lists* with regards to their templates, both of these templates have the same terminating default of `_default/list.html`---or `themes/<MYTHEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sections] and [taxonomy lists][taxonomies] have their own default list templates in `_default`:
|
||||
Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html`---or `themes/<THEME>/layouts/_default/list.html` in the case of a themed project---in their *lookup orders*. In addition, both [section lists][sectiontemplates] and [taxonomy lists][taxonomies] have their own default list templates in `_default`:
|
||||
|
||||
#### Default Section Templates
|
||||
|
||||
@@ -217,7 +122,6 @@ If `where` or `first` receives invalid input or a field name that doesn’t exis
|
||||
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
|
||||
[RSS]: /templates/rss-templates/
|
||||
[sections]: /content-management/sections/
|
||||
[sections]: /templates/section-templates
|
||||
[singlepages]: /templates/single-page-templates/
|
||||
[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates/
|
||||
[taxonomy terms lists]: /templates/#taxonomy-terms-templates/
|
||||
[section templates]: /templates/section-templates
|
||||
[taxonomy lists]: /templates/taxonomy-templates/#taxonomy-list-templates/
|
||||
[taxonomy terms]: /templates/taxonomy-templates/#taxonomy-terms-templates/
|
||||
|
||||
@@ -13,26 +13,27 @@ draft: false
|
||||
aliases: [/extras/localfiles/,/templates/files/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
needsexample: true
|
||||
---
|
||||
|
||||
## Traversing Local Files
|
||||
|
||||
With Hugo's [`readDir` function][], you can traverse your website's files on your server.
|
||||
With Hugo's [`readDir` and `readFile` template functions][reads], you can traverse your website's files on your server.
|
||||
|
||||
## Using `readDir`
|
||||
|
||||
The [`readDir`](/functions/readdir) function returns an array of [`os.FileInfo`](https://golang.org/pkg/os/#FileInfo). It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e. as found on your server's file system).
|
||||
The [`readDir` function][reads] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system).
|
||||
|
||||
Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both:
|
||||
|
||||
1. The file system root
|
||||
2. The current working directory
|
||||
|
||||
## Example Shortcode: List Directory's Files
|
||||
## Example: List Directory Files
|
||||
|
||||
So, let's create a new shortcode using `readDir`:
|
||||
|
||||
{{% code file="layouts/shortcodes/directoryindex.html" %}}
|
||||
{{% code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" %}}
|
||||
```html
|
||||
{{< readfile file="layouts/shortcodes/directoryindex.html" >}}
|
||||
```
|
||||
@@ -56,9 +57,11 @@ The initial slash `/` in `pathURL` is important. Otherwise, `pathURL` becomes re
|
||||
|
||||
## Using `readFile`
|
||||
|
||||
The [`readDir`](/functions/readdir) function returns...
|
||||
The [`readfile` function][reads] returns...
|
||||
|
||||
**CONTENT NEEDED**.
|
||||
|
||||
[has already been included in this very website]: https://github.com/spf13/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html
|
||||
[`readDir` function]: /functions/readdir/
|
||||
[osfileinfo]: https://golang.org/pkg/os/#FileInfo
|
||||
[reads]: /functions/readdir-and-readfile/
|
||||
[shortcodes]: /content-management/shortcodes/
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Template Lookup Order
|
||||
linktitle: Template Lookup Order
|
||||
description: The lookup order is a prioritized list used by Hugo as it traverses your files looking for the appropriate template to render your content.
|
||||
godocref:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-25
|
||||
categories: [templates]
|
||||
tags: [lookup,fundamentals]
|
||||
weight: 15
|
||||
draft: false
|
||||
aliases: []
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
Before creating your templates, it's important to know how Hugo looks for files within your project's [directory structure][].
|
||||
|
||||
Hugo uses a prioritized list called the **lookup order** as it traverses your files *looking* for the appropriate template to render your content.
|
||||
|
||||
The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C...and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<THEME>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
|
||||
|
||||
The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][].
|
||||
|
||||
{{% note %}}
|
||||
Most Hugo websites will only need the default template files at the end of the lookup order (i.e. `_default/*.html`).
|
||||
{{% /note %}}
|
||||
|
||||
See examples of the lookup order for each of the Hugo template types:
|
||||
|
||||
* [Base Templates][]
|
||||
* [Section Page Templates][sectionlookup]
|
||||
* [Taxonomy List Templates][taxonomylookup]
|
||||
* [Taxonomy Terms Templates][termslookup]
|
||||
* [Single Page Templates][singlelookup]
|
||||
* [RSS Templates][rsslookup]
|
||||
|
||||
[Base Templates]: /templates/base-templates-and-blocks/#base-template-lookup-order
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||||
[rsslookup]: /templates/rss-templates/#rss-template-lookup-order
|
||||
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
|
||||
[singlelookup]: templates/single-page-templates/#single-page-template-lookup-order
|
||||
[switch]: https://en.wikipedia.org/wiki/Switch_statement#Fallthrough
|
||||
[taxonomylookup]: /templates/taxonomy-templates/#taxonomy-list-template-lookup-order
|
||||
[termslookup]: /templates/taxonomy-templtes/#taxonomy-terms-template-lookup-order
|
||||
@@ -18,10 +18,10 @@ needsreview: true
|
||||
|
||||
Like all other templates, you can use a single RSS template to generate all of your RSS feeds, or you can create a specific template for each individual feed.
|
||||
|
||||
* `/layouts/section/<section>.rss.xml`
|
||||
* `/layouts/\_default/rss.xml`
|
||||
* `/themes/<theme>/layouts/section/<section>.rss.xml`
|
||||
* `/themes/<theme>/layouts/\_default/rss.xml`
|
||||
`/layouts/section/<section>.rss.xml`
|
||||
`/layouts/\_default/rss.xml`
|
||||
`/themes/<theme>/layouts/section/<section>.rss.xml`
|
||||
`/themes/<theme>/layouts/\_default/rss.xml`
|
||||
|
||||
{{% note "Hugo Ships with an RSS Template" %}}
|
||||
Unlike other Hugo templates, Hugo ships with its own [RSS 2.0 template][embedded]. In most cases this will be sufficient, and an RSS template will not need to be provided by the user. But you can provide an rss template if you like, as you can see in the next section.
|
||||
@@ -56,7 +56,7 @@ Hugo will use the following prioritized list. If a file isn’t present, then th
|
||||
|
||||
* /layouts/section/`SECTION`.rss.xml
|
||||
* /layouts/\_default/rss.xml
|
||||
* /themes/<mytheme>/layouts/section/<section>.rss.xml
|
||||
* /themes/<THEME>/layouts/section/<section>.rss.xml
|
||||
* /themes/`THEME`/layouts/\_default/rss.xml
|
||||
* [Embedded rss.xml][embedded]
|
||||
|
||||
|
||||
@@ -14,19 +14,15 @@ toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
## Introduction to the Template Lookup Order
|
||||
Section page templates are lists and therefore have all the variables and methods available to [list pages][lists].
|
||||
|
||||
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
|
||||
{{% warning "Section Pages Pull Content from `_index.md`" %}}
|
||||
To effectively leverage section page templates, you should first understand the Hugo [content organization](/content-management/content-organization/), and specifically the purpose of `_index.md`.
|
||||
{{% /warning %}}
|
||||
|
||||
## Lookup Order for Section Page Templates
|
||||
### Section Template Lookup Order
|
||||
|
||||
Hugo uses a set of rules to figure out which template to use when rendering a specific page.
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites only the \_default file at the end of the list will be needed.
|
||||
|
||||
### Section Template Page Lookup Order
|
||||
|
||||
A Section will be rendered at /<SECTION>/ (e.g. http://spf13.com/project/)
|
||||
The [lookup order][lookup] for section pages
|
||||
|
||||
* /layouts/section/<SECTION>.html
|
||||
* /layouts/\_default/section.html
|
||||
@@ -57,7 +53,13 @@ The valid values for 'kind' are as follows:
|
||||
The `.Site.GetPage` example assumes the following project directory structure:
|
||||
|
||||
{{% code file="grab-blog-section-index-page-title.html" %}}
|
||||
```golang
|
||||
{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
`.Site.GetPage` will return `nil` if no `_index.md` page is found. If `content/blog/_index.md` does not exist, the template will output a blank section where `{{.Title}}` should have been in the preceding example.
|
||||
|
||||
|
||||
[lists]: /templates/lists/
|
||||
[lookup]: /templates/lookup-order/
|
||||
@@ -15,11 +15,7 @@ toc: true
|
||||
|
||||
The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.
|
||||
|
||||
## Introduction to the Template Lookup Order
|
||||
|
||||
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
|
||||
|
||||
## Lookup Order for Single Page Templates
|
||||
## Single Page Template Lookup Order
|
||||
|
||||
You can specify `type` (i.e., [content type][]) and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]).
|
||||
|
||||
@@ -36,7 +32,7 @@ Hugo assumes your content section and content type are the same unless you tell
|
||||
9. `/themes/<THEME>/layouts/<SECTION>/single.html`
|
||||
10. `/themes/<THEME>/layouts/_default/single.html`
|
||||
|
||||
## Single Page Lookup Examples
|
||||
## Single Page Template Lookup Examples
|
||||
|
||||
The following examples assume two things:
|
||||
|
||||
@@ -97,11 +93,11 @@ When it comes time for Hugo to render the content to the page, it will go throug
|
||||
4. <span class="yes">`/layouts/posts/single.html`</span>
|
||||
<br><span class="break">BREAK</span>
|
||||
5. <span class="na">`/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<MYTHEME>/layouts/posts/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<MYTHEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/posts/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo the specific type and layout, it makes assumptions based on sane defaults. `my-first-post.md` does not specify a content `type` in its front matter. Therefore, Hugo assumes the content `type` and `section` (i.e. `posts`, which is defined by file location) are one in the same. ([Read more on sections][section].)
|
||||
|
||||
@@ -129,11 +125,11 @@ Here is the way Hugo's traverses the single-page lookup order for `my-second-pos
|
||||
3. <span class="na">`/layouts/review/single.html`</span>
|
||||
4. <span class="na">`/layouts/posts/single.html`</span>
|
||||
5. <span class="na">`/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<MYTHEME>/layouts/review/reviewarticle.html`</span>
|
||||
7. <span class="na">`/themes/<MYTHEME>/layouts/posts/reviewarticle.html`</span>
|
||||
8. <span class="na">`/themes/<MYTHEME>/layouts/review/single.html`</span>
|
||||
9. <span class="na">`/themes/<MYTHEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/review/reviewarticle.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/posts/reviewarticle.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/review/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/posts/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
The front matter in `my-second-post.md` specifies the content `type` (i.e. `review`) as well as the `layout` (i.e. `reviewarticle`). Hugo finds the layout it needs at the top level of the lookup (#1) and does not continue to search through the other templates.
|
||||
|
||||
@@ -161,11 +157,11 @@ Here is the way Hugo's traverses the single-page lookup order for `my-first-even
|
||||
4. <span class="no">`/layouts/events/single.html`</span>
|
||||
5. <span class="yes">`/layouts/_default/single.html`</span>
|
||||
<br><span class="break">BREAK</span>
|
||||
6. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<MYTHEME>/layouts/events/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<MYTHEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<MYTHEME>/layouts/events/single.html`</span>
|
||||
10. <span class="na">`/themes/<MYTHEME>/layouts/_default/single.html`</span>
|
||||
6. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/UNSPECIFIED.html`</span>
|
||||
7. <span class="na">`/themes/<THEME>/layouts/events/UNSPECIFIED.html`</span>
|
||||
8. <span class="na">`/themes/<THEME>/layouts/UNSPECIFIED/single.html`</span>
|
||||
9. <span class="na">`/themes/<THEME>/layouts/events/single.html`</span>
|
||||
10. <span class="na">`/themes/<THEME>/layouts/_default/single.html`</span>
|
||||
|
||||
{{% note %}}
|
||||
`my-first-event.md` is significant because it demonstrates the role of the lookup order in Hugo themes. Both the root project directory *and* the `mytheme` themes directory have a file at `_default/single.html`. Understanding this order allows you to [customize Hugo themes](/themes/customizing-a-theme/) by creating template files with identical names in your project directory that step in front of theme template files in the lookup. This allows you to customize the look and feel of your website while maintaining compatibility with the theme's upstream.
|
||||
|
||||
@@ -9,30 +9,30 @@ categories: [templates]
|
||||
tags: [taxonomies,metadata,front matter,terms]
|
||||
weight: 50
|
||||
draft: false
|
||||
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/]
|
||||
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies](/content-management/taxonomies) if you are unfamiliar with how Hugo uses taxonomies for content management.
|
||||
<!-- NOTE! Check on https://github.com/spf13/hugo/issues/2826 for shifting of terms' pages to .Data.Pages -->
|
||||
|
||||
Hugo provides multiple ways to leverage taxonomies through your project:
|
||||
Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature for content management.
|
||||
|
||||
Hugo provides multiple ways to use taxonomies throughout your project:
|
||||
|
||||
* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template)
|
||||
* Order the way content associated with a taxonomy term are display in a [taxonomy list template](#taxonomy-list-template)
|
||||
* List a single content's taxonomy terms within a [single page template]()
|
||||
|
||||
## Introduction to the Template Lookup Order
|
||||
|
||||
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
|
||||
* List a single content's taxonomy terms within a [single page template][taxinotherpage]
|
||||
|
||||
## Taxonomy List Templates
|
||||
|
||||
### Lookup Order for Taxonomy List Templates
|
||||
Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
|
||||
|
||||
### Taxonomy List Template Lookup Order
|
||||
|
||||
## Taxonomy Terms Template
|
||||
|
||||
### Lookup Order for Taxonomy Terms Templates
|
||||
### Taxonomy Terms Templates Lookup Order
|
||||
|
||||
{{% note "The Taxonomy Terms Template has a Unique Lookup Order" %}}
|
||||
Compared to taxonomy list pages and [other list templates](/templates/section-templates/), a terms template lookup has only two options. If Hugo does not find a terms template in `layout/` or `/themes/<yourchosentheme>/layouts/`, Hugo will *not* render a taxonomy terms page.,
|
||||
@@ -98,8 +98,6 @@ type WeightedPages []WeightedPage
|
||||
|
||||
<!-- Begin /taxonomies/ordering/ -->
|
||||
|
||||
|
||||
|
||||
## Ordering Taxonomies
|
||||
|
||||
Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
|
||||
|
||||
@@ -33,7 +33,7 @@ There are times where you want to include static assets that differ from version
|
||||
Let's assume the theme you are using has jQuery 1.8 in the following location:
|
||||
|
||||
```bash
|
||||
/themes/<MYTHEME>/static/js/jquery.min.js
|
||||
/themes/<THEME>/static/js/jquery.min.js
|
||||
```
|
||||
|
||||
You want to replace jQuery with jQuery 1.7. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root.
|
||||
@@ -73,7 +73,7 @@ This only works for templates that Hugo "knows about" (i.e., that follow its con
|
||||
If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit.
|
||||
|
||||
{{% warning "Beware of `layouts/_default`" %}}
|
||||
The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetype](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes/<mytheme>/archetypes/default.md` or `themes/<mytheme>/layout/_defaults/*.html`, respectively).
|
||||
The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetype](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes/<THEME>/archetypes/default.md` or `themes/<THEME>/layout/_defaults/*.html`, respectively).
|
||||
|
||||
It is usually better to override specific files; i.e. rather than using `layouts/_default/*.html` in your working directory.
|
||||
{{% /warning %}}
|
||||
@@ -94,7 +94,7 @@ theme: themename
|
||||
```
|
||||
|
||||
{{% note "A Note on `themename`" %}}
|
||||
The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather the (likely humanized) name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io).
|
||||
The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io).
|
||||
{{% /note %}}
|
||||
|
||||
[customizethemes]: /themes/customizing-a-theme/
|
||||
|
||||
@@ -6,13 +6,11 @@ date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [variables and params]
|
||||
tags: [files]
|
||||
tags: [variables,params,values,globals]
|
||||
draft: false
|
||||
weight: 01
|
||||
aliases: [/templates/variables/]
|
||||
toc: false
|
||||
hidesectioncontents: false
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
[Go templates][], the backbone of Hugo templating, are context based, and Hugo makes a large number of values available to you as you're creating views for your website. The following variables and params provide convenient means to displaying your content with Hugo's powerful templating engine.
|
||||
@@ -36,7 +36,7 @@ functions:
|
||||
variablesandparams:
|
||||
order: 6
|
||||
title: "Variables and Params"
|
||||
url: "variables-and-params"
|
||||
url: "variables"
|
||||
haschildren: true
|
||||
sortsubpagesby: "weight"
|
||||
desc: "Page-, file-, taxonomy-, and site-level variables and parameters available in templates"
|
||||
@@ -99,7 +99,7 @@ siteshowcase:
|
||||
contributetohugo:
|
||||
order: 15
|
||||
title: "Contribute to Hugo"
|
||||
url: "contribute-to-hugo"
|
||||
url: "contribute"
|
||||
haschildren: true
|
||||
sortsubpagesby: "weight"
|
||||
desc: "Contribute to Hugo development and documentation"
|
||||
@@ -5,12 +5,12 @@
|
||||
<a href="{{.}}" class="see-code-source" role="button" target="_blank" title="See source for this snippet">See Source</a>
|
||||
{{end}}
|
||||
{{with .Get "download"}}
|
||||
<button class="download-button" title="Download a copy of {{.}}">
|
||||
<button class="download-button" title="Download "{{.}}".">
|
||||
<i class="icon-download"></i>
|
||||
</button>
|
||||
{{end}}
|
||||
{{ if ne (.Get "copy") "false" }}
|
||||
<button class="copy-button" title="Copy to clipboard" data-clipboard-snippet>
|
||||
<button class="copy-button" title="Copy this code to your clipboard." data-clipboard-snippet>
|
||||
<i class="icon-clipboard"></i><!-- <div class="copy-text"> COPY</div> -->
|
||||
</button>
|
||||
{{end}}
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
{{- if eq (.Get "markdown") "true" -}}
|
||||
{{- $file | readFile | markdownify -}}
|
||||
{{- else -}}
|
||||
{{ $file | readFile }}
|
||||
{{ $file | readFile | safeHTML }}
|
||||
{{- end -}}
|
||||
@@ -1,4 +1,4 @@
|
||||
Hugo uses a prioritized list called the *lookup order* as it traverses your files looking for the appropriate template to render your content. The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C, and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<mytheme>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
|
||||
Hugo uses a prioritized list called the *lookup order* as it traverses your files looking for the appropriate template to render your content. The template lookup order is an inverted cascade: if template A isn’t present or specified, Hugo will look to template B. If template B isn't present or specified, Hugo will look for template C, and so on until it reaches the `layouts/_default/` directory for your project, or in the case of themes, `themes/<THEME>/layouts/_default/`. In many ways, the lookup order is similar to the [control mechanism of a switch statement (i.e. without fallthrough)][switch] seen in many programming languages.
|
||||
|
||||
The power of the lookup order is that it enables you to craft specific layouts as needed without creating more templating than necessary, thereby keeping your templating [DRY][dry]. *Most sites will only need the default template files at the end of the lookup* (i.e. `_default/*.html`).
|
||||
|
||||
|
||||
Vendored
+1
-1
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 32 KiB |
|
Before Width: | Height: | Size: 122 KiB After Width: | Height: | Size: 122 KiB |
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 6.6 KiB After Width: | Height: | Size: 6.6 KiB |
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 59 KiB |
|
Before Width: | Height: | Size: 7.5 KiB After Width: | Height: | Size: 7.5 KiB |
|
Before Width: | Height: | Size: 2.6 KiB After Width: | Height: | Size: 2.6 KiB |
@@ -5,7 +5,12 @@
|
||||
<article class="content" id="{{.Title | urlize}}">
|
||||
<header class="content-header">
|
||||
{{- partial "breadcrumb.html" . -}}
|
||||
<h1 class="page-title {{.Section}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">{{ .Title | markdownify }}</h1>
|
||||
<h1 class="page-title {{.Section}}" id="{{with .LinkTitle}}{{. | urlize}}{{else}}{{ .Title | urlize }}{{end}}">
|
||||
{{- if eq .Section "functions" -}}
|
||||
{{- replace (.LinkTitle) "and" "<em>and</em>" | safeHTML -}}
|
||||
{{- else -}}
|
||||
{{- .Title | markdownify -}}
|
||||
{{- end -}}</h1>
|
||||
{{- partial "content-header-links.html" . -}}
|
||||
{{- partial "tags.html" . -}}
|
||||
{{- if .Params.needsreview -}}
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
{{ define "main" }}
|
||||
<main class="main">
|
||||
<header class="content-header">
|
||||
<h1 class="page-title"><a href="{{.Site.BaseURL}}{{.Data.Plural}}"><i class="icon-{{.Data.Plural}}"></i>{{.Data.Plural}}:</a> {{ replace .Title "-" " "}}</h1>
|
||||
</header>
|
||||
<div class="body-copy taxonomies">
|
||||
{{partial "contents-list.html" . }}
|
||||
<div class="content">
|
||||
<header class="content-header">
|
||||
<h1 class="page-title"><a href="{{.Site.BaseURL}}{{.Data.Plural}}"><i class="icon-{{.Data.Plural}}"></i>{{.Data.Plural}}:</a> {{ replace .Title "-" " "}}</h1>
|
||||
</header>
|
||||
<div class="body-copy taxonomies">
|
||||
{{partial "contents-list.html" . }}
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
@@ -1,28 +1,30 @@
|
||||
{{ define "main" }}
|
||||
<main class="main">
|
||||
<header class="content-header">
|
||||
<h1 class="page-title"><i class="icon-{{.Data.Plural}}"></i> {{.Data.Plural}}</h1>
|
||||
</header>
|
||||
<div class="body-copy taxonomies">
|
||||
{{ $data := .Data }}
|
||||
{{ $dataPlural := .Title | urlize}}
|
||||
{{ $base := $.Site.BaseURL }}
|
||||
<table class="terms-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Term</th>
|
||||
<th>Count</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range $key, $value := .Data.Terms.Alphabetical }}
|
||||
<tr>
|
||||
<td><a href="{{ $base }}{{ $dataPlural }}/{{$value.Name | urlize}}">{{ $value.Name }}</a></td>
|
||||
<td>{{ $value.Count }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="content">
|
||||
<header class="content-header">
|
||||
<h1 class="page-title"><i class="icon-{{.Data.Plural}}"></i> {{.Data.Plural}}</h1>
|
||||
</header>
|
||||
<div class="body-copy taxonomies">
|
||||
{{ $data := .Data }}
|
||||
{{ $dataPlural := .Title | urlize}}
|
||||
{{ $base := $.Site.BaseURL }}
|
||||
<table class="terms-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Term</th>
|
||||
<th>Count</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range $key, $value := .Data.Terms.Alphabetical }}
|
||||
<tr>
|
||||
<td><a href="{{ $base }}{{ $dataPlural }}/{{$value.Name | urlize}}">{{ $value.Name }}</a></td>
|
||||
<td>{{ $value.Count }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
{{ end }}
|
||||
@@ -6,7 +6,7 @@
|
||||
<i class="fa fa-chevron-left"></i>
|
||||
<div class="page-info">
|
||||
<span>Previous</span>
|
||||
<h5 class="{{$section}}">{{.NextInSection.Title}}</h5>
|
||||
<h5 class="{{$section}}">{{if eq .Section "functions"}}{{- replace (.NextInSection.LinkTitle) "and" "<em>and</em>" | safeHTML -}}{{else}}{{.NextInSection.Title | markdownify}}{{end}}</h5>
|
||||
</div>
|
||||
</a>
|
||||
{{ else if eq .Kind "page" }}
|
||||
@@ -15,7 +15,7 @@
|
||||
<i class="fa fa-chevron-left"></i>
|
||||
<div class="page-info">
|
||||
<span>Previous</span>
|
||||
<h5 class="{{$section}}">{{ .LinkTitle }}</h5>
|
||||
<h5 class="{{$section}}">{{if eq .Section "functions"}}{{- replace (.LinkTitle) "and" "<em>and</em>" | safeHTML -}}{{else}}{{.Title | markdownify}}{{end}}</h5>
|
||||
</div>
|
||||
</a>
|
||||
{{ end }}
|
||||
@@ -24,7 +24,7 @@
|
||||
<a href="{{.Permalink}}" class="prev-and-next-link next-page">
|
||||
<div class="page-info">
|
||||
<span>Next</span>
|
||||
<h5 class="{{$section}}">{{.Title}}</h5>
|
||||
<h5 class="{{$section}}">{{if eq .Section "functions"}}{{- replace (.LinkTitle) "and" "<em>and</em>" | safeHTML -}}{{else}}{{.Title | markdownify}}{{end}}</h5>
|
||||
</div>
|
||||
<i class="fa fa-chevron-right"></i>
|
||||
</a>
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>{{.Title}}{{if not .IsHome}} | {{.Site.Title}}{{end}}</title>
|
||||
{{$st := .Site.Title}}
|
||||
{{- if eq .Section "functions" -}}
|
||||
<title>{{.LinkTitle}} | {{$st}}</title>
|
||||
{{- else -}}
|
||||
<title>{{.Title}}{{if not .IsHome}} | {{$st}}{{end}}</title>
|
||||
{{- end -}}
|
||||
<meta name="description" content="{{ .Description }}" />
|
||||
@@ -1,24 +1,23 @@
|
||||
<!-- Note that the withtoc class is added as a class for content/*.md containing toc: true in the front matter. TOCs need to be declared explicityly in the front matter. -->
|
||||
<footer id="site-footer" class="site-footer{{if .Params.toc}} withtoc{{end}}">
|
||||
<div class="footer-content">
|
||||
<div class="footer-info">
|
||||
<span>By <a href="http://spf13.com" target="_blank">spf13</a> and friends.</span>
|
||||
<img src="{{ "images/hugo-logo/made-with-hugo-dark.png" | relURL}}" alt="Made with Hugo Logo">
|
||||
</div>
|
||||
<div class="footer-lists">
|
||||
<ul class="footer-list">
|
||||
<li><a href="{{.Site.Params.ghrepo}}" target="_blank"><i class="icon-github"></i> Project Source</a></li>
|
||||
<li><a href="{{.Site.Params.discuss}}" target="_blank"><i class="icon-forum"></i> Discuss Hugo</a></li>
|
||||
<li><a href="{{.Site.Params.gitter}}" target="_blank"><i class="icon-gitter"></i> Gitter (Dev Chat Only)</a></li>
|
||||
</ul>
|
||||
<ul class="footer-list">
|
||||
<li><a href="https://twitter.com/spf13" target="_blank"><i class="icon-twitter"></i> @spf13</a></li>
|
||||
<li><a href="https://twitter.com/gohugoio" target="_blank"><i class="icon-twitter"></i> @GoHugoIO</a></li>
|
||||
<li><a href="https://twitter.com/bepsays" target="_blank"><i class="icon-twitter"></i> @bepsays</a></li>
|
||||
<li><a href="https://"></a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<div class="footer-content">
|
||||
<div class="footer-info">
|
||||
<span>By <a href="http://spf13.com" target="_blank">spf13</a> and friends.</span>
|
||||
<img src="{{ "images/hugo-logo/made-with-hugo-dark.png" | relURL}}" alt="Made with Hugo Logo">
|
||||
</div>
|
||||
<div class="footer-lists">
|
||||
<ul class="footer-list">
|
||||
<li><a href="{{.Site.Params.ghrepo}}" target="_blank"><i class="icon-github"></i> Project Source</a></li>
|
||||
<li><a href="{{.Site.Params.discuss}}" target="_blank"><i class="icon-forum"></i> Discuss Hugo</a></li>
|
||||
<li><a href="{{.Site.Params.gitter}}" target="_blank"><i class="icon-gitter"></i> Gitter (Dev Chat Only)</a></li>
|
||||
</ul>
|
||||
<ul class="footer-list">
|
||||
<li><a href="https://twitter.com/gohugoio" target="_blank"><i class="icon-twitter"></i> @GoHugoIO</a></li>
|
||||
<li><a href="https://twitter.com/spf13" target="_blank"><i class="icon-twitter"></i> @spf13</a></li>
|
||||
<li><a href="https://twitter.com/bepsays" target="_blank"><i class="icon-twitter"></i> @bepsays</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
{{if ne .Params.toc false}}
|
||||
<!-- TOCs need to be declared explicitly in the front matter of content/*.md -->
|
||||
{{if .Params.toc }}
|
||||
<aside id="toc">
|
||||
<header class="toc-header">
|
||||
<a href="#{{.Title | urlize}}">
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
{{define "main"}}
|
||||
<main class="main showcase-list">
|
||||
<div class="content">
|
||||
<header class="content-header">
|
||||
{{partial "breadcrumb.html" . }}
|
||||
<h1 class="page-title" id="{{ .Title | urlize }}">{{ .Title | markdownify }}</h1>
|
||||
{{.Content}}
|
||||
</header>
|
||||
</div>
|
||||
</main>
|
||||
{{end}}
|
||||
@@ -15,13 +15,13 @@ h4 {
|
||||
|
||||
h1.page-title {
|
||||
font-size: 2.2em;
|
||||
line-height:1.2;
|
||||
line-height: 1.2;
|
||||
letter-spacing: -.021em;
|
||||
padding-bottom: 0px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
margin-bottom: 8px;
|
||||
font-weight:$heading-font-weight;
|
||||
font-weight: $heading-font-weight;
|
||||
@include MQ(M) {
|
||||
padding-top: 0px;
|
||||
}
|
||||
@@ -45,10 +45,10 @@ h3 {
|
||||
h2 {
|
||||
font-size: 1.6em;
|
||||
&.contents-list-heading {
|
||||
text-transform:uppercase;
|
||||
color:$hugo-gray;
|
||||
text-transform: uppercase;
|
||||
color: $hugo-gray;
|
||||
em {
|
||||
font-style:normal;
|
||||
font-style: normal;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -60,14 +60,30 @@ h3 {
|
||||
h4 {
|
||||
font-size: 1.1em;
|
||||
margin-top: 1em;
|
||||
margin-bottom:1em;
|
||||
margin-bottom: 1em;
|
||||
color: $hugo-gray;
|
||||
// text-transform: uppercase;
|
||||
}
|
||||
|
||||
//used throughout the "functions" section to render titles in the base code font family
|
||||
.functions {
|
||||
font-family: $code-font-family;
|
||||
font-weight: $base-font-weight;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
//just for function section page titles that include the word "and":
|
||||
//in templates, a conditional statement checks for section=functions, and if so, replaces "and" in title/linktitle with <em>and</em>
|
||||
.functions {
|
||||
> em {
|
||||
font-style: normal;
|
||||
font-family: $base-font-family;
|
||||
padding-left: .25em;
|
||||
padding-right: .25em;
|
||||
font-size: .8em;
|
||||
position: relative;
|
||||
margin-bottom: .3em;
|
||||
}
|
||||
}
|
||||
|
||||
//keeps index page from taking on code/pre font family
|
||||
@@ -79,4 +95,4 @@ h4 {
|
||||
|
||||
hr {
|
||||
border-top: 3px double $base-font-color;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
.last-modified {
|
||||
color: $hugo-gray;
|
||||
display: block;
|
||||
display: inline-block;
|
||||
min-width: 200px;
|
||||
width: 100%;
|
||||
text-align: center;
|
||||
|
||||
@@ -37,10 +37,21 @@ main.main {
|
||||
}
|
||||
}
|
||||
|
||||
//note: article.content in single pages and div.content in section pages for improved semantics
|
||||
.content {
|
||||
width: 90%;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
max-width: $content-max-width;
|
||||
@include MQ(L) {
|
||||
float:left;
|
||||
margin-left:5%;
|
||||
margin-right:auto;
|
||||
}
|
||||
@include MQ(XL) {
|
||||
min-width: $content-max-width;
|
||||
max-width: 90%;
|
||||
}
|
||||
}
|
||||
|
||||
header.content-header {
|
||||
|
||||
@@ -78,6 +78,13 @@
|
||||
&.active-page {
|
||||
font-weight: 700;
|
||||
color: $hugo-blue;
|
||||
> code {
|
||||
color: $hugo-blue;
|
||||
> em {
|
||||
font-style:normal;
|
||||
family:$base-font-family;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user