blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-25 15:58:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update single page examples to use more recent Hugo features

Browse Source
This commit is contained in:
Ryan Watters
2017-04-06 17:04:05 -05:00
parent 7d60b1a55a
commit c7816c5b52
4 changed files with 52 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/functions/with.md
+4 -2
View File
@@ -16,11 +16,13 @@ relatedfuncs: []
deprecated: false
---
An alternative way of writing the "`if`" and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
An alternative way of writing the "`if`" and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent.
The following example checks for a [user-defined site variable](/variables/site/) defined as `twitteruser` in your [site configuration](/getting-started/configuration/). If the key-value is not set, the following will render nothing:
{{% code file="layouts/partials/twitter.html" %}}
```html
{{with .Site.Params.TwitterUser}}<span class="twitter">
{{with .Site.Params.twitteruser}}<span class="twitter">
<a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
alt="Twitter"></a>
content/templates/lookup-order.md
+2
View File
@@ -173,6 +173,7 @@ The respective lookup order for each of Hugo's templates has been defined throug
* [Taxonomy Terms Templates][termslookup]
* [Single Page Templates][singlelookup]
* [RSS Templates][rsslookup]
* [Shortcode Templates][sclookup]
[base]: /templates/base/#base-template-lookup-order
[config]: /getting-started/configuration/
@@ -180,6 +181,7 @@ The respective lookup order for each of Hugo's templates has been defined throug
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
[home]: /templates/homepage/#homepage-template-lookup-order
[rsslookup]: /templates/rss/#rss-template-lookup-order
[sclookup]: /templates/shortcode-templates/#shortcode-template-lookup-order
[sections]: /content-management/sections/
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
[single page templates]: /templates/single-page-templates/
content/templates/shortcode-templates.md
+13 -7
View File
@@ -1,5 +1,5 @@
---
title: Creating Your Own Shortcode Templates
title: Creating Your Own Shortcodes
linktitle: Shortcode Templates
description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
date: 2017-02-01
@@ -32,7 +32,14 @@ Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, H
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
### Deciding Parameter Type
### Shortcode Template Lookup Order
Shortcode templates have a simple [lookup order][]:
1. `/layouts/shortcodes/<SHORTCODE>.html`
2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
### Positional vs Named Parameters
You can create shortcodes using the following types of parameters:
@@ -40,9 +47,7 @@ You can create shortcodes using the following types of parameters:
* Named parameters
* Positional *or* named parameters (i.e, "flexible")
#### Positional vs Named Parameters
In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from during usage by content authors.
In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors.
For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
@@ -111,10 +116,10 @@ You could then include the following as part of your shortcode templating:
{{ end }}.
```
See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action
See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action.
{{% warning %}}
While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. A shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{</* image src="images/my-image.jpg" "This is my alt text" */>}}` will return an error.
{{% /warning %}}
You can also use the variable `.Page` to access all the normal [page variables][pagevars].
@@ -347,6 +352,7 @@ More shortcode examples can be found in the [shortcodes directory for spf13.com]
[docsshortcodes]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
[figure]: /content-management/shortcodes/#figure
[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time"
[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates."
[parent]: /variables/shortcodes/
[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
content/templates/single-page-templates.md
+33 -34
View File
@@ -47,13 +47,11 @@ Content pages are of the type `page` and will therefore have all the [page varia
### `post/single.html`
This content template is used for [spf13.com][spf13]. It makes use of [partial templates][partials]:
This single page template is a modified version of one used for for [spf13.com][spf13]. It makes use of [base templates][]:
{{% code file="layouts/post/single.html" download="single.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
{{ $baseURL := .Site.BaseURL }}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
@@ -62,48 +60,47 @@ This content template is used for [spf13.com][spf13]. It makes use of [partial t
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseURL }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ with .Params.topics }}
<ul id="topics">
{{ range . }}
<li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
{{ with .Params.tags }}
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseURL }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ range . }}
<li> <a href="{{ "tags" | absURL }}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
</div>
<div>
{{ if .Prev }}
<a class="previous" href="{{.Prev.Permalink}}"> {{.Prev.Title}}</a>
{{ with .Prev }}
<a class="previous" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
{{ if .Next }}
<a class="next" href="{{.Next.Permalink}}"> {{.Next.Title}}</a>
{{ with .Next }}
<a class="next" href="{{.Permalink}}"> {{.Title}}</a>
{{ end }}
</div>
</aside>
{{ partial "disqus.html" . }}
{{ partial "footer.html" . }}
{{ end }}
```
{{% /code %}}
### `project/single.html`
This content template is also used for [spf13.com][spf13] and makes use of [partial templates][partials]:
This single page template is also modified from an existing template for [spf13.com][spf13] and makes use of [base templates][]:
{{% code file="project/single.html" download="single.html" %}}
```html
{{ partial "header.html" . }}
{{ partial "subheader.html" . }}
{{ $baseURL := .Site.BaseURL }}
{{ define "main" }}
<section id="main">
<h1 id="title">{{ .Title }}</h1>
<div>
@@ -112,41 +109,43 @@ This content template is also used for [spf13.com][spf13] and makes use of [part
</article>
</div>
</section>
<aside id="meta">
<div>
<section>
<h4 id="date"> {{ .Date.Format "Mon Jan 2, 2006" }} </h4>
<h5 id="wc"> {{ .FuzzyWordCount }} Words </h5>
</section>
<ul id="categories">
{{ range .Params.topics }}
<li><a href="{{ $baseURL }}/topics/{{ . | urlize }}">{{ . }}</a> </li>
{{ with .Params.topics }}
<ul id="topics">
{{ range . }}
<li><a href="{{ "topics" | absURL}}{{ . | urlize }}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
{{ with .Params.tags}}
<ul id="tags">
{{ range .Params.tags }}
<li> <a href="{{ $baseURL }}/tags/{{ . | urlize }}">{{ . }}</a> </li>
{{ range . }}
<li> <a href="{{ "tags" | absURL }}{{ . | urlize}}">{{ . }}</a> </li>
{{ end }}
</ul>
{{ end }}
</div>
</aside>
{{if isset .Params "project_url" }}
{{with .Params "project_url" }}
<div id="ribbon">
<a href="{{ index .Params "project_url" }}" rel="me">Fork me on GitHub</a>
<a href="{{ . }}">Fork me on GitHub</a>
</div>
{{ end }}
{{ partial "footer.html" . }}
{{ end }}
```
{{% /code %}}
Notice how `project/single.html` uses an additional parameter unique to this template. This doesn't need to be defined ahead of time. The key can wait to be used in the template if present in the content file's front matter.
Notice how `project/single.html` uses an additional parameter unique to this template (i.e., `project_url`). This doesn't need to be defined ahead of time. The use of [`with`](/functions/with) means the key can be used in the template only if set in the content file's front matter.
To easily generate new instances of this content type (e.g., new `.md` files in `project/`) with preconfigured front matter, use [content archetypes][archetypes].
To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes].
[archetypes]: /content-management/archetypes/
[base templates]: /templates/base/
[config]: /getting-started/configuration/
[content type]: /content-management/types/
[directory structure]: /getting-started/directory-structure/