--- /dev/null
+---
+title: Shortcodes
+linktitle:
+description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2019-11-07
+menu:
+ docs:
+ parent: "content-management"
+ weight: 35
+weight: 35 #rem
+categories: [content management]
+keywords: [markdown,content,shortcodes]
+draft: false
+aliases: [/extras/shortcodes/]
+testparam: "Hugo Rocks!"
+toc: true
+---
+
+## What a Shortcode is
+
+Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframes>`) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+
+Hugo created **shortcodes** to circumvent these limitations.
+
+A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+
+In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+
+## Use Shortcodes
+
+{{< youtube 2xkNJL4gJ9E >}}
+
+In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
+
+The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`.
+
+Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+
+Here are two examples of paired shortcodes:
+
+```
+{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```
+
+```
+{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+```
+
+The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+
++### Shortcodes with raw string parameters
++
++{{< new-in "0.64.1" >}}
++
++You can pass multiple lines as parameters to a shortcode by using raw string literals:
++
++```
++{{</* myshortcode `This is some <b>HTML</b>,
++and a new line with a "quouted string".` */>}}
++```
++
+### Shortcodes with Markdown
+
+In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.
+
+If you want the old behavior, you can put the following line in the start of your shortcode template:
+
+```
+{{ $_hugo_config := `{ "version": 1 }` }}
+```
+
+
+### Shortcodes Without Markdown
+
+The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML:
+
+```
+{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
+```
+
+### Nested Shortcodes
+
+You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+
+## Use Hugo's Built-in Shortcodes
+
+Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean.
+
+### `figure`
+
+`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `<figure>` element][figureelement].
+
+The `figure` shortcode can use the following named parameters:
+
+src
+: URL of the image to be displayed.
+
+link
+: If the image needs to be hyperlinked, URL of the destination.
+
+target
+: Optional `target` attribute for the URL if `link` parameter is set.
+
+rel
+: Optional `rel` attribute for the URL if `link` parameter is set.
+
+alt
+: Alternate text for the image if the image cannot be displayed.
+
+title
+: Image title.
+
+caption
+: Image caption. Markdown within the value of `caption` will be rendered.
+
+class
+: `class` attribute of the HTML `figure` tag.
+
+height
+: `height` attribute of the image.
+
+width
+: `width` attribute of the image.
+
+attr
+: Image attribution text. Markdown within the value of `attr` will be rendered.
+
+attrlink
+: If the attribution text needs to be hyperlinked, URL of the destination.
+
+#### Example `figure` Input
+
+{{< code file="figure-input-example.md" >}}
+{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+#### Example `figure` Output
+
+{{< output file="figure-output-example.html" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /output >}}
+
+### `gist`
+
+Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
+
+```
+https://gist.github.com/spf13/7896402
+```
+
+We can embed the gist in our content via username and gist ID pulled from the URL:
+
+```
+{{</* gist spf13 7896402 */>}}
+```
+
+#### Example `gist` Input
+
+If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
+
+{{< code file="gist-input.md" >}}
+{{</* gist spf13 7896402 "img.html" */>}}
+{{< /code >}}
+
+#### Example `gist` Output
+
+{{< output file="gist-output.html" >}}
+{{< gist spf13 7896402 >}}
+{{< /output >}}
+
+#### Example `gist` Display
+
+To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< gist spf13 7896402 >}}
+
+### `highlight`
+
+This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+
+#### Example `highlight` Input
+
+{{< code file="content/tutorials/learn-html.md" >}}
+{{</* highlight html */>}}
+<section id="main">
+ <div>
+ <h1 id="title">{{ .Title }}</h1>
+ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+</section>
+{{</* /highlight */>}}
+{{< /code >}}
+
+#### Example `highlight` Output
+
+The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+
+{{< output file="tutorials/learn-html/index.html" >}}
+<span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
+ <span style="color: #f92672"><div></span>
+ <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
+ {{ range .Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ <span style="color: #f92672"></div></span>
+<span style="color: #f92672"></section></span>
+{{< /output >}}
+
+{{% note "More on Syntax Highlighting" %}}
+To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/).
+{{% /note %}}
+
+### `instagram`
+
+If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
+
+```
+https://www.instagram.com/p/BWNjjyYFxVx/
+```
+
+#### Example `instagram` Input
+
+{{< code file="instagram-input.md" >}}
+{{</* instagram BWNjjyYFxVx */>}}
+{{< /code >}}
+
+You also have the option to hide the caption:
+
+{{< code file="instagram-input-hide-caption.md" >}}
+{{</* instagram BWNjjyYFxVx hidecaption */>}}
+{{< /code >}}
+
+#### Example `instagram` Output
+
+By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="instagram-hide-caption-output.html" >}}
+{{< instagram BWNjjyYFxVx hidecaption >}}
+{{< /output >}}
+
+#### Example `instagram` Display
+
+Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< instagram BWNjjyYFxVx hidecaption >}}
+
+
+### `param`
+
+Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. It will log an `ERROR` if the param with the given key could not be found in either.
+
+```bash
+{{</* param testparam */>}}
+```
+
+Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print:
+
+{{< param testparam >}}
+
+To access deeply nested params, use "dot syntax", e.g:
+
+```bash
+{{</* param "my.nested.param" */>}}
+```
+
+### `ref` and `relref`
+
+These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page.
+
+`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+
+{{% note "More on Cross References" %}}
+Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+{{% /note %}}
+
+`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+
+#### Example `ref` and `relref` Input
+
+```
+[Neat]({{</* ref "blog/neat.md" */>}})
+[Who]({{</* relref "about.md#who" */>}})
+```
+
+#### Example `ref` and `relref` Output
+
+Assuming that standard Hugo pretty URLs are turned on.
+
+```
+<a href="/blog/neat">Neat</a>
+<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
+```
+
+### `tweet`
+
+You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
+
+```
+https://twitter.com/spf13/status/877500564405444608
+```
+
+#### Example `tweet` Input
+
+Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode:
+
+{{< code file="example-tweet-input.md" >}}
+{{</* tweet 877500564405444608 */>}}
+{{< /code >}}
+
+#### Example `tweet` Output
+
+Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-tweet-output.html" >}}
+{{< tweet 877500564405444608 >}}
+{{< /output >}}
+
+#### Example `tweet` Display
+
+Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< tweet 877500564405444608 >}}
+
+### `vimeo`
+
+Adding a video from [Vimeo][] is equivalent to the YouTube shortcode above.
+
+```
+https://vimeo.com/channels/staffpicks/146022717
+```
+
+#### Example `vimeo` Input
+
+Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
+
+{{< code file="example-vimeo-input.md" >}}
+{{</* vimeo 146022717 */>}}
+{{< /code >}}
+
+#### Example `vimeo` Output
+
+Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
+
+{{< output file="example-vimeo-output.html" >}}
+{{< vimeo 146022717 >}}
+{{< /output >}}
+
+{{% tip %}}
+If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
+
+```
+{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
+```
+{{% /tip %}}
+
+#### Example `vimeo` Display
+
+Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
+
+{{< vimeo 146022717 >}}
+
+### `youtube`
+
+The `youtube` shortcode embeds a responsive video player for [YouTube videos][]. Only the ID of the video is required, e.g.:
+
+```
+https://www.youtube.com/watch?v=w7Ft2ymGmfc
+```
+
+
+#### Example `youtube` Input
+
+Copy the YouTube video ID that follows `v=` in the video's URL and pass it to the `youtube` shortcode:
+
+{{< code file="example-youtube-input.md" >}}
+{{</* youtube w7Ft2ymGmfc */>}}
+{{< /code >}}
+
+Furthermore, you can automatically start playback of the embedded video by setting the `autoplay` parameter to `true`. Remember that you can't mix named and unnamed parameters, so you'll need to assign the yet unnamed video id to the parameter `id`:
+
+
+{{< code file="example-youtube-input-with-autoplay.md" >}}
+{{</* youtube id="w7Ft2ymGmfc" autoplay="true" */>}}
+{{< /code >}}
+
+#### Example `youtube` Output
+
+Using the preceding `youtube` example, the following HTML will be added to your rendered website's markup:
+
+{{< code file="example-youtube-output.html" >}}
+{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}
+{{< /code >}}
+
+#### 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. The video is also include in the [Quick Start of the Hugo documentation][quickstart].
+
+{{< youtube w7Ft2ymGmfc >}}
+
+## Privacy Config
+
+To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
+
+## Create Custom Shortcodes
+
+To learn more about creating custom shortcodes, see the [shortcode template documentation][].
+
+[`figure` shortcode]: #figure
+[contentmanagementsection]: /content-management/formats/
+[examplegist]: https://gist.github.com/spf13/7896402
+[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
+[Hugo and the GDPR]: /about/hugo-and-gdpr/
+[Instagram]: https://www.instagram.com/
+[pagevariables]: /variables/page/
+[partials]: /templates/partials/
+[Pygments]: http://pygments.org/
+[quickstart]: /getting-started/quick-start/
+[sctemps]: /templates/shortcode-templates/
+[scvars]: /variables/shortcodes/
+[shortcode template documentation]: /templates/shortcode-templates/
+[templatessection]: /templates/
+[Vimeo]: https://vimeo.com/
+[YouTube Videos]: https://www.youtube.com/
--- /dev/null
- linktitle: Types
- description: Hugo supports sites with multiple content types and assumes your site will be organized into sections, where each section represents the corresponding type.
+---
+title: Content Types
- publishdate: 2017-02-01
- lastmod: 2017-02-01
++description: Hugo is built around content organized in sections.
+date: 2017-02-01
- A **content type** can have a unique set of metadata (i.e., [front matter][]) or customized [template][] and can be created by the `hugo new` command via [archetypes][].
+categories: [content management]
+keywords: [lists,sections,content types,types,organization]
+menu:
+ docs:
+ parent: "content-management"
+ weight: 60
+weight: 60 #rem
+draft: false
+aliases: [/content/types]
+toc: true
+---
+
- ## What is a Content Type
++A **content type** is a way to organize your content. Hugo resolves the content type from either the `type` in front matter or, if not set, the first directory in the file path. E.g. `content/blog/my-first-event.md` will be of type `blog` if no `type` set.
+
- [Tumblr][] is a good example of a website with multiple content types. A piece of "content" could be a photo, quote, or a post, each with different sets of metadata and different visual rendering.
++A content type is used to
+
- ## Assign a Content Type
++* Determine how the content is rendered. See [Template Lookup Order](/templates/lookup-order/) and [Content Views](https://gohugo.io/templates/views) for more.
++* Determine which [archetype](/content-management/archetypes/) template to use for new content.
+
- Hugo assumes that your site will be organized into [sections][] and each section represents a corresponding type. This is to reduce the amount of configuration necessary for new Hugo projects.
-
- If you are taking advantage of this default behavior, each new piece of content you place into a section will automatically inherit the type. Therefore a new file created at `content/posts/new-post.md` will automatically be assigned the type `posts`. Alternatively, you can set the content type in a content file's [front matter][] in the field "`type`".
-
- ## Create New Content of a Specific Type
-
- You can manually add files to your content directories, but Hugo can create and populate a new content file with preconfigured front matter via [archetypes][].
-
- ## Define a Content Type
-
- Creating a new content type is easy. You simply define the templates and archetype unique to your new content type, or Hugo will use defaults.
-
-
- {{% note "Declaring Content Types" %}}
- Remember, all of the following are *optional*. If you do not specifically declare content types in your front matter or develop specific layouts for content types, Hugo is smart enough to assume the content type from the file path and section. (See [Content Sections](/content-management/sections/) for more information.)
- {{% /note %}}
-
- The following examples take you stepwise through creating a new type layout for a content file that contains the following front matter:
-
- {{< code file="content/events/my-first-event.md" copy="false" >}}
- +++
- title = My First Event
- date = "2016-06-24T19:20:04-07:00"
- description = "Today is my 36th birthday. How time flies."
- type = "event"
- layout = "birthday"
- +++
- {{< /code >}}
-
- By default, Hugo assumes `*.md` under `events` is of the `events` content type. However, we have specified that this particular file at `content/events/my-first-event.md` is of type `event` and should render using the `birthday` layout.
-
- ### Create a Type Layout Directory
-
- Create a directory with the name of the type in `/layouts`. For creating these custom layouts, **type is always singular**; e.g., `events => event` and `posts => post`.
-
- For this example, you need to create `layouts/event/birthday.html`.
-
- {{% note %}}
- If you have multiple content files in your `events` directory that are of the `special` type and you don't want to define the `layout` specifically for each piece of content, you can create a layout at `layouts/special/single.html` to observe the [single page template lookup order](/templates/single-page-templates/).
- {{% /note %}}
-
- {{% warning %}}
- With the "everything is a page" data model introduced in v0.18 (see [Content Organization](/content-management/organization/)), you can use `_index.md` in content directories to add both content and front matter to [list pages](/templates/lists/).
- {{% /warning %}}
-
- ### Create Views
-
- Many sites support rendering content in a few different ways; e.g., a single page view and a summary view to be used when displaying a [list of section contents][sectiontemplates].
-
- Hugo limits assumptions about how you want to display your content to an intuitive set of sane defaults and will support as many different views of a content type as your site requires. All that is required for these additional views is that a template exists in each `/layouts/<TYPE>` directory with the same name.
-
- ### Custom Content Type Template Lookup Order
-
- The lookup order for the `content/events/my-first-event.md` templates would be as follows:
-
- * `layouts/event/birthday.html`
- * `layouts/event/single.html`
- * `layouts/events/single.html`
- * `layouts/_default/single.html`
-
- ### Create a Corresponding Archetype
-
- We can then create a custom archetype with preconfigured front matter at `event.md` in the `/archetypes` directory; i.e. `archetypes/event.md`.
-
- Read [Archetypes][archetypes] for more information on archetype usage with `hugo new`.
-
- [archetypes]: /content-management/archetypes/
- [front matter]: /content-management/front-matter/
- [sectiontemplates]: /templates/section-templates/
- [sections]: /content-management/sections/
- [template]: /templates/
- [Tumblr]: https://www.tumblr.com/
+
--- /dev/null
- aliases: [/functions/errorf]
+---
+title: errorf and warnf
+description: Log ERROR or WARNING from the templates.
+date: 2017-09-30
+publishdate: 2017-09-30
+lastmod: 2017-09-30
+categories: [functions]
+menu:
+ docs:
+ parent: "functions"
+keywords: [strings, log, error]
+signature: ["errorf FORMAT INPUT"]
+workson: []
+hugoversion:
+relatedfuncs: [printf]
+deprecated: false
+---
+
+`errorf` or `warnf` will evaluate a format string, then output the result to the ERROR or WARNING log (and only once per error message to avoid flooding the log).
+
+Any ERROR will also cause the build to fail (the `hugo` command will `exit -1`).
+
+Both functions return an empty string, so the messages are only printed to the console.
+
+```
+{{ errorf "Failed to handle page %q" .Path }}
+```
+
+```
+{{ warnf "You should update the shortcodes in %q" .Path }}
+```
+
+Note that `errorf` and `warnf` support all the formatting verbs of the [fmt](https://golang.org/pkg/fmt/) package.
--- /dev/null
- <!-- Note that .Pages is the same as .Site.RegularPages on the homepage template. -->
- {{ range first 10 .Pages }}
+---
+title: Homepage Template
+linktitle: Homepage Template
+description: The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's homepage as a unique template.
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [homepage]
+menu:
+ docs:
+ parent: "templates"
+ weight: 30
+weight: 30
+sections_weight: 30
+draft: false
+aliases: [/layout/homepage/,/templates/homepage-template/]
+toc: true
+---
+
+Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
+
+{{% note "The Only Required Template" %}}
+The homepage template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
+{{% /note %}}
+
+{{< youtube ut1xtRZ1QOA >}}
+
+## Homepage Template Lookup Order
+
+See [Template Lookup](/templates/lookup-order/).
+
+## Add Content and Front Matter to the Homepage
+
+The homepage, similar to other [list pages in Hugo][lists], accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (i.e., `content/_index.md`). You can then add body copy and metadata to your homepage the way you would any other content file.
+
+See the homepage template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
+
+## Example Homepage Template
+
+The following is an example of a homepage template that uses [partial][partials], [base][] templates, and a content file at `content/_index.md` to populate the `{{.Title}}` and `{{.Content}}` [page variables][pagevars].
+
+{{< code file="layouts/index.html" download="index.html" >}}
+{{ define "main" }}
+ <main aria-role="main">
+ <header class="homepage-header">
+ <h1>{{.Title}}</h1>
+ {{ with .Params.subtitle }}
+ <span class="subtitle">{{.}}</span>
+ {{ end }}
+ </header>
+ <div class="homepage-content">
+ <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
+ {{.Content}}
+ </div>
+ <div>
++ {{ range first 10 .Site.RegularPages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ </div>
+ </main>
+{{ end }}
+{{< /code >}}
+
+[base]: /templates/base/
+[contentorg]: /content-management/organization/
+[lists]: /templates/lists/
+[lookup]: /templates/lookup-order/
+[pagevars]: /variables/page/
+[partials]: /templates/partials/
+[sitevars]: /variables/site/
--- /dev/null
- Layout
- : Can be set in page front matter.
-
+---
+title: Hugo's Lookup Order
+linktitle: Template Lookup Order
+description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.
+godocref:
+date: 2017-02-01
+publishdate: 2017-02-01
+lastmod: 2017-07-05
+categories: [templates,fundamentals]
+keywords: [templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 15
+ quicklinks:
+weight: 15
+sections_weight: 15
+draft: false
+aliases: [/templates/lookup/]
+toc: true
+---
+
+## Hugo Layouts Lookup Rules
+
+Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
+
+
+Kind
+: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML).
+
++Layout
++: Can be set in page front matter.
++
+Output Format
+: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates.
+
+Language
+: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but `index.amp.html` will be chosen before `index.fr.html`.
+
+Type
+: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page".
+
+Section
+: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types.
+
+{{% note %}}
+**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates:
+
+```bash
+├── _default
+│ ├── baseof.html
+│ ├── list.html
+│ └── single.html
+└── index.html
+```
+{{% /note %}}
+
+
+## Hugo Layouts Lookup Rules With Theme
+
+In Hugo, layouts can live in either the project's or the themes' layout folders, and the most specific layout will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
+
+## Examples: Layout Lookup for Regular Pages
+
+{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+## Examples: Layout Lookup for Home Page
+
+{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+## Examples: Layout Lookup for Section Pages
+
+{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+## Examples: Layout Lookup for Taxonomy List Pages
+
+{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+## Examples: Layout Lookup for Taxonomy Terms Pages
+
+{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}}
+
+
+
+
--- /dev/null
- <iframe src="//player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
+---
+title: Create 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
+publishdate: 2017-02-01
+lastmod: 2017-02-01
+categories: [templates]
+keywords: [shortcodes,templates]
+menu:
+ docs:
+ parent: "templates"
+ weight: 100
+weight: 100
+sections_weight: 100
+draft: false
+aliases: []
+toc: true
+---
+
+Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][].
+
+{{% note %}}
+Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
+{{% /note %}}
+
+## Create Custom Shortcodes
+
+Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
+
+{{< youtube Eu4zSaKOY4A >}}
+
+### File Location
+
+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.
+
+You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxes`. These shortcodes would then be accessible with their relative path, e.g:
+
+```
+{{</* boxes/square */>}}
+```
+
+Note the forward slash.
+
+### 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:
+
+* Positional parameters
+* Named parameters
+* Positional *or* named parameters (i.e, "flexible")
+
+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.
+
+Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
+
+### Access Parameters
+
+All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
+
+To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string:
+
+```
+{{ .Get "class" }}
+```
+
+To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
+
+```
+{{ .Get 0 }}
+```
+
+For the second position, you would just use:
+
+```
+{{ .Get 1 }}
+```
+
+`with` is great when the output depends on a parameter being set:
+
+```
+{{ with .Get "class"}} class="{{.}}"{{ end }}
+```
+
+`.Get` can also be used to check if a parameter has been provided. This is
+most helpful when the condition depends on either of the values, or both:
+
+```
+{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}
+```
+
+#### `.Inner`
+
+If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence.
+
+A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax:
+
+```
+{{</* innershortcode /*/>}}
+```
+
+#### `.Params`
+
+The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
+
+`$.Params`
+: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
+
+`$.Page.Params`
+: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
+
+`$.Page.Site.Params`
+: refers to global variables as defined in your [site's configuration file][config].
+
+#### `.IsNamedParams`
+
+The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
+
+For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows:
+
+```
+{{</* image src="images/my-image.jpg"*/>}}
+```
+
+You could then include the following as part of your shortcode templating:
+
+```
+{{ if .IsNamedParams }}
+<img src="{{.Get "src" }}" alt="">
+{{ else }}
+<img src="{{.Get 0}}" alt="">
+{{ end }}
+```
+
+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. 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].
+
+A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
+
+### Checking for Existence
+
+You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
+
+## Custom Shortcode Examples
+
+The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`.
+
+### Single-word Example: `year`
+
+Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows:
+
+```
+{{</* year */>}}
+```
+
+{{< code file="/layouts/shortcodes/year.html" >}}
+{{ now.Format "2006" }}
+{{< /code >}}
+
+### Single Positional Example: `youtube`
+
+Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
+
+```
+{{</* youtube 09jf3ow9jfw */>}}
+```
+
+Would load the template at `/layouts/shortcodes/youtube.html`:
+
+{{< code file="/layouts/shortcodes/youtube.html" >}}
+<div class="embed video-player">
+<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
+</iframe>
+</div>
+{{< /code >}}
+
+{{< code file="youtube-embed.html" copy="false" >}}
+<div class="embed video-player">
+ <iframe class="youtube-player" type="text/html"
+ width="640" height="385"
+ src="https://www.youtube.com/embed/09jf3ow9jfw"
+ allowfullscreen frameborder="0">
+ </iframe>
+</div>
+{{< /code >}}
+
+### Single Named Example: `image`
+
+Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
+
+{{< code file="content-image.md" >}}
+{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{< /code >}}
+
+You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
+
+{{< code file="/layouts/shortcodes/img.html" >}}
+<!-- image -->
+<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
+ {{ with .Get "link"}}<a href="{{.}}">{{ end }}
+ <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
+ {{ if .Get "link"}}</a>{{ end }}
+ {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
+ <figcaption>{{ if isset .Params "title" }}
+ <h4>{{ .Get "title" }}</h4>{{ end }}
+ {{ if or (.Get "caption") (.Get "attr")}}<p>
+ {{ .Get "caption" }}
+ {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
+ {{ .Get "attr" }}
+ {{ if .Get "attrlink"}}</a> {{ end }}
+ </p> {{ end }}
+ </figcaption>
+ {{ end }}
+</figure>
+<!-- image -->
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="img-output.html" copy="false" >}}
+<figure>
+ <img src="/media/spf13.jpg" />
+ <figcaption>
+ <h4>Steve Francia</h4>
+ </figcaption>
+</figure>
+{{< /code >}}
+
+### Single Flexible Example: `vimeo`
+
+```
+{{</* vimeo 49718712 */>}}
+{{</* vimeo id="49718712" class="flex-video" */>}}
+```
+
+Would load the template found at `/layouts/shortcodes/vimeo.html`:
+
+{{< code file="/layouts/shortcodes/vimeo.html" >}}
+{{ if .IsNamedParams }}
+ <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
- <iframe src="//player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
++ <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
+ </div>
+{{ else }}
+ <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
- <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
++ <iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
+ </div>
+{{ end }}
+{{< /code >}}
+
+Would be rendered as:
+
+{{< code file="vimeo-iframes.html" copy="false" >}}
+<div class="vimeo-container">
- <iframe src="//player.vimeo.com/video/49718712" allowfullscreen></iframe>
++ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+<div class="flex-video">
++ <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
+</div>
+{{< /code >}}
+
+### Paired Example: `highlight`
+
+The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
+
+{{< code file="highlight-example.md" >}}
+{{</* highlight html */>}}
+ <html>
+ <body> This HTML </body>
+ </html>
+{{</* /highlight */>}}
+{{< /code >}}
+
+The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
+
+```
+{{ .Get 0 | highlight .Inner }}
+```
+
+The rendered output of the HTML example code block will be as follows:
+
+{{< code file="syntax-highlighted.html" copy="false" >}}
+<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
+ <span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
+<span style="color: #f92672"></html></span>
+</pre></div>
+{{< /code >}}
+
+### Nested Shortcode: Image Gallery
+
+Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
+
+The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter:
+
+{{< code file="layouts/shortcodes/gallery.html" >}}
+<div class="{{.Get "class"}}">
+ {{.Inner}}
+</div>
+{{< /code >}}
+
+You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+
+{{< code file="layouts/shortcodes/img.html" >}}
+{{- $src := .Get "src" -}}
+{{- with .Parent -}}
+ <img src="{{$src}}" class="{{.Get "class"}}-image">
+{{- else -}}
+ <img src="{{$src}}">
+{{- end }}
+{{< /code >}}
+
+You can then call your shortcode in your content as follows:
+
+```
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
+
+```
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+
+## Error Handling in Shortcodes
+
+Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
+
+```bash
+{{ with .Get "name" }}
+{{ else }}
+{{ errorf "missing value for param 'name': %s" .Position }}
+{{ end }}
+```
+
+When the above fails, you will see an `ERROR` log similar to the below:
+
+```bash
+ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
+```
+
+## More Shortcode Examples
+
+More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
+
+
+## Inline Shortcodes
+
+Since Hugo 0.52, you can implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place.
+
+This feature is disabled by default, but can be enabled in your site config:
+
+{{< code-toggle file="config">}}
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+It is disabled by default for security reasons. The security model used by Hugo's template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then `enableInlineShortcodes = true` would be considered safe. But it's something to be aware of: It allows ad-hoc [Go Text templates](https://golang.org/pkg/text/template/) to be executed from the content files.
+
+And once enabled, you can do this in your content files:
+
+ ```go-text-template
+ {{</* time.inline */>}}{{ now }}{{</* /time.inline */>}}
+ ```
+
+The above will print the current date and time.
+
+ Note that an inline shortcode's inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
+
+This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
+
+The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax:
+
+ ```go-text-template
+{{</* time.inline /*/>}}
+```
+
+
+[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
+[built-in shortcode]: /content-management/shortcodes/
+[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website."
+[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files."
+[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
+[docsshortcodes]: https://github.com/gohugoio/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."
+[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
+[templates]: /templates/ "The templates section of the Hugo docs."
+[vimeoexample]: #single-flexible-example-vimeo
+[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
--- /dev/null
- HUGO_VERSION = "0.64.0"
+[build]
+publish = "public"
+command = "hugo --gc --minify"
+
+[context.production.environment]
- HUGO_VERSION = "0.64.0"
++HUGO_VERSION = "0.64.1"
+HUGO_ENV = "production"
+HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
+command = "hugo --gc --minify --enableGitInfo"
+
+[context.split1.environment]
- HUGO_VERSION = "0.64.0"
++HUGO_VERSION = "0.64.1"
+HUGO_ENV = "production"
+
+[context.deploy-preview]
+command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
+
+[context.deploy-preview.environment]
- HUGO_VERSION = "0.64.0"
++HUGO_VERSION = "0.64.1"
+
+[context.branch-deploy]
+command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy.environment]
++HUGO_VERSION = "0.64.1"
+
+[context.next.environment]
+HUGO_ENABLEGITINFO = "true"
+
projects / brevno-suite / hugo / commitdiff