diff --git a/content/functions/with.md b/content/functions/with.md index d3c131530..c0d8a2db2 100644 --- a/content/functions/with.md +++ b/content/functions/with.md @@ -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}} +{{with .Site.Params.twitteruser}} diff --git a/content/templates/lookup-order.md b/content/templates/lookup-order.md index 864a1b40f..dc25809bb 100644 --- a/content/templates/lookup-order.md +++ b/content/templates/lookup-order.md @@ -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/ diff --git a/content/templates/shortcode-templates.md b/content/templates/shortcode-templates.md index bdd03c00a..950912ddc 100644 --- a/content/templates/shortcode-templates.md +++ b/content/templates/shortcode-templates.md @@ -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 `{{}}` 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/.html` +2. `/themes//layouts/shortcodes/.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 `{{}}` 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 `{{}}` 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." diff --git a/content/templates/single-page-templates.md b/content/templates/single-page-templates.md index d608fdaff..8a32cfff5 100644 --- a/content/templates/single-page-templates.md +++ b/content/templates/single-page-templates.md @@ -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" }}

{{ .Title }}

@@ -62,48 +60,47 @@ This content template is used for [spf13.com][spf13]. It makes use of [partial t
- -{{ 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" }}

{{ .Title }}

@@ -112,41 +109,43 @@ This content template is also used for [spf13.com][spf13] and makes use of [part
- - - {{if isset .Params "project_url" }} + {{with .Params "project_url" }} {{ 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/