Featured Article
@@ -61,7 +61,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power {{ end }} {{ end }} -{{< /code >}} +``` [`first`]: /functions/collections/first/ [`slice`]: /functions/collections/slice/ diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index 4254560eb..05dafe3c9 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -214,12 +214,12 @@ With TOML, date values are first-class citizens. TOML has a date data type while In the TOML example below, note that the event date is not quoted. -{{< code file=content/events/2024-user-conference.md >}} +```text {file="content/events/2024-user-conference.md"} +++ title = '2024 User Conference" eventDate = 2024-04-01 +++ -{{< /code >}} +``` To return a collection of future events: diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md index 77432dc57..8741f7330 100644 --- a/content/en/functions/css/PostCSS.md +++ b/content/en/functions/css/PostCSS.md @@ -42,13 +42,13 @@ npm i -D postcss postcss-cli autoprefixer Create a PostCSS configuration file in the root of your project. -{{< code file=postcss.config.js >}} +```js {file="postcss.config.js"} module.exports = { plugins: [ require('autoprefixer') ] }; -{{< /code >}} +``` {{< note >}} {{% include "/_common/functions/postcss-windows-warning.md" %}} diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md index 9da079f1d..4c5bbac75 100644 --- a/content/en/functions/css/TailwindCSS.md +++ b/content/en/functions/css/TailwindCSS.md @@ -58,10 +58,10 @@ target = "css" Create a CSS entry file: -{{< code file=assets/css/main.css copy=true >}} +```css {file="assets/css/main.css" copy=true} @import "tailwindcss"; @source "hugo_stats.json"; -{{< /code >}} +``` Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above. @@ -69,7 +69,7 @@ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` i Create a partial template to process the CSS with the Tailwind CSS CLI: -{{< code file=layouts/partials/css.html copy=true >}} +```go-html-template {file="layouts/partials/css.html" copy=true} {{ with (templates.Defer (dict "key" "global")) }} {{ with resources.Get "css/main.css" }} {{ $opts := dict @@ -87,19 +87,19 @@ Create a partial template to process the CSS with the Tailwind CSS CLI: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` ### Step 5 Call the partial template from your base template: -{{< code file=layouts/default/baseof.html >}} +```go-html-template {file="layouts/default/baseof.html"} ... {{ partialCached "css.html" . }} ... -{{< /code >}} +``` ### Step 6 @@ -109,7 +109,7 @@ extension] for Visual Studio Code. [Tailwind CSS IntelliSense extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss -{{< code file=tailwind.config.js copy=true >}} +```js {file="tailwind.config.js" copy=true} /* This file is present to satisfy a requirement of the Tailwind CSS IntelliSense extension for Visual Studio Code. @@ -118,7 +118,7 @@ https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss The rest of this file is intentionally empty. */ -{{< /code >}} +``` ## Options diff --git a/content/en/functions/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md index 483dcb26f..6b7dc0019 100644 --- a/content/en/functions/diagrams/Goat.md +++ b/content/en/functions/diagrams/Goat.md @@ -36,7 +36,7 @@ Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [emb This Markdown: -```` +````text ```goat .---. .-. .-. .-. .---. | A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | @@ -68,7 +68,7 @@ To customize rendering, override Hugo's [embedded code block render hook] for Go By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. -{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock-goat.html"} {{ $caption := or .Attributes.caption "" }} {{ $class := or .Attributes.class "diagram" }} {{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} @@ -81,17 +81,17 @@ By way of example, let's create a code block render hook to render GoAT diagrams {{ end }}{{ .Title }}
{{ .Content }} {{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -48,6 +48,6 @@ The typical use is to define a set of root templates that are then customized by{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md index 68c9baeed..8d43d2d31 100644 --- a/content/en/functions/go-template/return.md +++ b/content/en/functions/go-template/return.md @@ -24,13 +24,13 @@ Unlike `return` statements in other languages, Hugo executes the first occurrenc By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: -{{< code file=layouts/partials/odd-or-even.html >}} +```go-html-template {file="layouts/partials/odd-or-even.html"} {{ if math.ModBool . 2 }}{{ . }} is even
{{ else }}{{ . }} is odd
{{ end }} -{{< /code >}} +``` When called, the partial renders HTML: @@ -40,9 +40,9 @@ When called, the partial renders HTML: Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: -{{< code file=layouts/partials/is-even.html >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ return math.ModBool . 2 }} -{{< /code >}} +``` With this template: @@ -75,7 +75,7 @@ A partial that returns a value must contain only one `return` statement, placed For example: -{{< code file=layouts/partials/is-even.html >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ $result := false }} {{ if math.ModBool . 2 }} {{ $result = "even" }} @@ -83,16 +83,16 @@ For example: {{ $result = "odd" }} {{ end }} {{ return $result }} -{{< /code >}} +``` {{< note >}} The construct below is incorrect; it contains more than one `return` statement. {{< /note >}} -{{< code file=layouts/partials/do-not-do-this.html >}} +```go-html-template {file="layouts/partials/do-not-do-this.html"} {{ if math.ModBool . 2 }} {{ return "even" }} {{ else }} {{ return "odd" }} {{ end }} -{{< /code >}} +``` diff --git a/content/en/functions/images/AutoOrient.md b/content/en/functions/images/AutoOrient.md index 4a5e221a8..5af396e59 100644 --- a/content/en/functions/images/AutoOrient.md +++ b/content/en/functions/images/AutoOrient.md @@ -20,7 +20,6 @@ Create the filter: {{ $filter := images.AutoOrient }} ``` - {{% include "/_common/functions/images/apply-image-filter.md" %}} {{< note >}} diff --git a/content/en/functions/images/QR.md b/content/en/functions/images/QR.md index 6d6a5485a..a8375b904 100644 --- a/content/en/functions/images/QR.md +++ b/content/en/functions/images/QR.md @@ -73,7 +73,7 @@ Specify `level`, `scale`, and `targetDir` as needed to achieve the desired resul To include a QR code that points to the `Permalink` of the current page: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with images.QR .Permalink }}-
{{ range .Site.Menus.main }}
- {{ .Name }} {{ end }}
-
{{ range .Site.Menus.main }}
- {{ .Name }} {{ end }}
{{ .Title }}
{{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, we: diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md index 8e39a9981..a97f6461c 100644 --- a/content/en/methods/page/Paginator.md +++ b/content/en/methods/page/Paginator.md @@ -22,12 +22,12 @@ You can invoke pagination on the [home template], [section templates], [taxonomy [taxonomy templates]: /templates/types/#taxonomy [term templates]: /templates/types/#term -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ range .Paginator.Pages }}{{ .LinkTitle }}
{{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, the embedded pagination template creates navigation links between pagers. diff --git a/content/en/methods/page/RenderShortcodes.md b/content/en/methods/page/RenderShortcodes.md index c91e9ef8d..d124606f0 100644 --- a/content/en/methods/page/RenderShortcodes.md +++ b/content/en/methods/page/RenderShortcodes.md @@ -15,7 +15,7 @@ Use this method in shortcode templates to compose a page from multiple content f For example: -{{< code file=layouts/shortcodes/include.html >}} +```go-html-template {file="layouts/shortcodes/include.html" copy=true} {{ with .Get 0 }} {{ with $.Page.GetPage . }} {{- .RenderShortcodes }} @@ -25,15 +25,15 @@ For example: {{ else }} {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Then call the shortcode in your Markdown: -{{< code file=content/about.md lang=text >}} +```text {file="content/about.md"} {{%/* include "/snippets/services" */%}} {{%/* include "/snippets/values" */%}} {{%/* include "/snippets/leadership" */%}} -{{< /code >}} +``` Each of the included Markdown files can contain calls to other shortcodes. @@ -50,7 +50,7 @@ Use the latter for the "include" shortcode described above. To understand what is returned by the `RenderShortcodes` method, consider this content file -{{< code file=content/about.md lang=text >}} +```text {file="content/about.md"} +++ title = 'About' date = 2023-10-07T12:28:33-07:00 @@ -59,7 +59,7 @@ date = 2023-10-07T12:28:33-07:00 {{}} An *emphasized* word. -{{< /code >}} +``` With this template code: diff --git a/content/en/methods/page/Sitemap.md b/content/en/methods/page/Sitemap.md index 772460ab3..80ad0b3b6 100644 --- a/content/en/methods/page/Sitemap.md +++ b/content/en/methods/page/Sitemap.md @@ -59,7 +59,7 @@ changeFreq = 'hourly' And this simplistic sitemap template: -{{< code file=layouts/_default/sitemap.xml >}} +```xml {file="layouts/_default/sitemap.xml"} {{ printf "" | safeHTML }}Related pages:
-
@@ -24,11 +24,11 @@ The argument passed to the `Related` method may be a `Page` or an options map. F
{{ end }}
{{ with .Get "title" }}
-{{< /code >}}
+```
Is rendered to:
@@ -57,7 +57,7 @@ Let's modify the example above to pass the value returned by `Inner` through the
[`RenderString`]: /methods/page/renderstring/
-{{< code file=layouts/shortcodes/card.html >}}
+```go-html-template {file="layouts/shortcodes/card.html"}
{{ . }}
@@ -28,7 +28,7 @@ With this shortcode:
{{ .Inner | strings.TrimSpace }}
{{ with .Get "title" }}
-{{< /code >}}
+```
Hugo renders this to:
@@ -88,11 +88,11 @@ You can use the [`markdownify`] function instead of the `RenderString` method, b
Instead of calling the shortcode with the `{{}}` notation, use the `{{%/* */%}}` notation:
-{{< code file=content/services.md lang=text >}}
+```text {file="content/services.md"}
{{%/* card title="Product Design" */%}}
We design the **best** widgets in the world.
{{%/* /card */%}}
-{{< /code >}}
+```
When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
@@ -107,7 +107,7 @@ This configuration is not unsafe if _you_ control the content. Read more about H
Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
-{{< code file=layouts/shortcodes/card.html >}}
+```go-html-template {file="layouts/shortcodes/card.html"}
{{ . }}
@@ -66,7 +66,7 @@ Let's modify the example above to pass the value returned by `Inner` through the
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
{{ with .Get "title" }}
-{{< /code >}}
+```
The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method.
diff --git a/content/en/methods/shortcode/InnerDeindent.md b/content/en/methods/shortcode/InnerDeindent.md
index 7faa297ca..0b8c8e2d8 100644
--- a/content/en/methods/shortcode/InnerDeindent.md
+++ b/content/en/methods/shortcode/InnerDeindent.md
@@ -15,7 +15,7 @@ This allows us to effectively bypass the rules governing [indentation] as provid
Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
-{{< code file=content/about.md lang=text >}}
+```text {file="content/about.md"}
- Gallery one
{{}}
@@ -29,17 +29,17 @@ Consider this Markdown, an unordered list with a small gallery of thumbnail imag
{{}}
-{{< /code >}}
+```
In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block.
With this shortcode, calling `Inner` instead of `InnerDeindent`:
-{{< code file=layouts/shortcodes/gallery.html >}}
+```go-html-template {file="layouts/shortcodes/gallery.html"}
{{ . }}
@@ -117,7 +117,7 @@ Second, because we are rendering the entire shortcode as Markdown, we must adher
{{ .Inner | strings.TrimSpace }}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}}
+```
Hugo renders the Markdown to:
@@ -66,11 +66,11 @@ Hugo renders the Markdown to:
Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method:
-{{< code file=layouts/shortcodes/gallery.html >}}
+```go-html-template {file="layouts/shortcodes/gallery.html"}
{{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}}
+```
Hugo renders the Markdown to:
diff --git a/content/en/methods/shortcode/IsNamedParams.md b/content/en/methods/shortcode/IsNamedParams.md
index 4d4cc5134..1e0a7f00e 100644
--- a/content/en/methods/shortcode/IsNamedParams.md
+++ b/content/en/methods/shortcode/IsNamedParams.md
@@ -13,17 +13,17 @@ To support both positional and named arguments when calling a shortcode, use the
With this shortcode template:
-{{< code file=layouts/shortcodes/myshortcode.html >}}
+```go-html-template {file="layouts/shortcodes/myshortcode.html"}
{{ if .IsNamedParams }}
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
{{ else }}
{{ printf "%s %s." (.Get 0) (.Get 1) }}
{{ end }}
-{{< /code >}}
+```
Both of these calls return the same value:
-{{< code file=content/about.md lang=text >}}
+```text {file="content/about.md"}
{{}}
{{}}
-{{< /code >}}
+```
diff --git a/content/en/methods/shortcode/Name.md b/content/en/methods/shortcode/Name.md
index 78ed91e69..b5f9b6c17 100644
--- a/content/en/methods/shortcode/Name.md
+++ b/content/en/methods/shortcode/Name.md
@@ -11,14 +11,14 @@ params:
The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
-{{< code file=layouts/shortcodes/myshortcode.html >}}
+```go-html-template {file="layouts/shortcodes/myshortcode.html"}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
{{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
-{{< /code >}}
+```
In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md
index fcbea1bab..605494dd5 100644
--- a/content/en/methods/shortcode/Ordinal.md
+++ b/content/en/methods/shortcode/Ordinal.md
@@ -18,15 +18,15 @@ Hugo increments the ordinal with each shortcode call, regardless of the specific
This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
-{{< code file=content/about.md lang=text >}}
+```text {file="content/about.md"}
{{}}
{{}}
-{{< /code >}}
+```
This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
-{{< code file=layouts/shortcodes/img.html >}}
+```go-html-template {file="layouts/shortcodes/img.html"}
{{ $src := "" }}
{{ with .Get "src" }}
{{ $src = . }}
@@ -39,7 +39,7 @@ This shortcode performs error checking, then renders an HTML `img` element with
{{ else }}
{{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
{{ end }}
-{{< /code >}}
+```
Hugo renders the page to:
diff --git a/content/en/methods/shortcode/Page.md b/content/en/methods/shortcode/Page.md
index b5ca5d6cd..007294c8a 100644
--- a/content/en/methods/shortcode/Page.md
+++ b/content/en/methods/shortcode/Page.md
@@ -27,11 +27,11 @@ Calling this shortcode:
We can access the front matter values using the `Page` method:
-{{< code file=layouts/shortcodes/book-details.html >}}
+```go-html-template {file="layouts/shortcodes/book-details.html"}
- Title: {{ .Page.Title }}
- Author: {{ .Page.Params.author }}
- Published: {{ .Page.Params.publication_year }}
- ISBN: {{ .Page.Params.isbn }}
{{ .Inner | strings.TrimSpace | .Page.RenderString }}
-{{< /code >}}
+```
-{{< code file=layouts/shortcodes/now.html >}}
+```go-html-template {file="layouts/shortcodes/now.html"}
{{- $dateFormat := "January 2, 2006 15:04:05" }}
{{- with .Params }}
@@ -42,7 +42,7 @@ Welcome. Today is {{}}.
{{- end }}
{{- now | time.Format $dateFormat -}}
-{{< /code >}}
+```
The "now" shortcode formats the current time using:
diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md
index d62818189..5ee25ade4 100644
--- a/content/en/methods/shortcode/Position.md
+++ b/content/en/methods/shortcode/Position.md
@@ -11,14 +11,14 @@ params:
The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
-{{< code file=layouts/shortcodes/myshortcode.html >}}
+```go-html-template {file="layouts/shortcodes/myshortcode.html"}
{{ $greeting := "" }}
{{ with .Get "greeting" }}
{{ $greeting = . }}
{{ else }}
{{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}
-{{< /code >}}
+```
In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
diff --git a/content/en/methods/shortcode/Ref.md b/content/en/methods/shortcode/Ref.md
index 6fd669a0c..3a877d568 100644
--- a/content/en/methods/shortcode/Ref.md
+++ b/content/en/methods/shortcode/Ref.md
@@ -9,7 +9,6 @@ params:
signatures: [SHORTCODE.Ref OPTIONS]
---
-
## Usage
The `Ref` method accepts a single argument: an options map.
diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md
index d65c0a0e0..e720d14e7 100644
--- a/content/en/methods/site/Data.md
+++ b/content/en/methods/site/Data.md
@@ -33,23 +33,23 @@ data/
And these data files:
-{{< code file=data/books/fiction.yaml lang=yaml >}}
+```yaml {file="data/books/fiction.yaml"}
- title: The Hunchback of Notre Dame
author: Victor Hugo
isbn: 978-0140443530
- title: Les Misérables
author: Victor Hugo
isbn: 978-0451419439
-{{< /code >}}
+```
-{{< code file=data/books/nonfiction.yaml lang=yaml >}}
+```yaml {file="data/books/nonfiction.yaml"}
- title: The Ancien Régime and the Revolution
author: Alexis de Tocqueville
isbn: 978-0141441641
- title: Interpreting the French Revolution
author: François Furet
isbn: 978-0521280495
-{{< /code >}}
+```
Access the data by [chaining](g) the [identifiers](g):
diff --git a/content/en/methods/site/Pages.md b/content/en/methods/site/Pages.md
index a19988780..a6ba5e029 100644
--- a/content/en/methods/site/Pages.md
+++ b/content/en/methods/site/Pages.md
@@ -11,8 +11,6 @@ params:
This method returns all page [kinds](g) in the current language, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
-
-
In most cases you should use the [`RegularPages`] method instead.
[`RegularPages`]: /methods/site/regularpages/
diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md
index 5b69efff3..bb8a2d228 100644
--- a/content/en/methods/site/Taxonomies.md
+++ b/content/en/methods/site/Taxonomies.md
@@ -144,7 +144,7 @@ The following example displays all terms in a site's tags taxonomy:
```
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
-{{< code file=layouts/partials/all-taxonomies.html >}}
+```go-html-template {file="layouts/partials/all-taxonomies.html"}
{{ with .Site.Taxonomies }}
{{ $numberOfTerms := 0 }}
{{ range $taxonomy, $terms := . }}
@@ -175,4 +175,4 @@ This example will list all taxonomies and their terms, as well as all the conten
{{ end }}
{{ end }}
-{{< /code >}}
+```
diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md
index 7b099372e..cb8d71f8b 100755
--- a/content/en/render-hooks/blockquotes.md
+++ b/content/en/render-hooks/blockquotes.md
@@ -58,15 +58,15 @@ In its default configuration, Hugo renders Markdown blockquotes according to the
[CommonMark specification]: https://spec.commonmark.org/current/
-{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
+```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ .Text }}-{{< /code >}} +``` To render a blockquote as an HTML `figure` element with an optional citation and caption: -{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ .Text }} @@ -77,7 +77,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and {{ end }}
{{- .Inner | htmlEscape | safeHTML }}
{{ .Page.Store.Set "hasMermaid" true }}
-{{< /code >}}
+```
Then include this snippet at the bottom of the your base template:
-{{< code file=layouts/_default/baseof.html copy=true >}}
+```go-html-template {file="layouts/_default/baseof.html" copy=true}
{{ if .Store.Get "hasMermaid" }}
{{ end }}
-{{< /code >}}
+```
See the [diagrams] page for details.
diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md
index f4ded9b70..89868d478 100755
--- a/content/en/render-hooks/headings.md
+++ b/content/en/render-hooks/headings.md
@@ -46,19 +46,19 @@ In its default configuration, Hugo renders Markdown headings according to the [C
[CommonMark specification]: https://spec.commonmark.org/current/
-{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
+```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true}
404 Not Found
The page you requested cannot be found.
@@ -19,7 +19,7 @@ To render a 404 error page in the root of your site, create a 404 template in th {{ end }} -{{< /code >}} +``` For multilingual sites, add the language key to the file name: diff --git a/content/en/templates/base.md b/content/en/templates/base.md index b4550fcd4..bf861fbab 100644 --- a/content/en/templates/base.md +++ b/content/en/templates/base.md @@ -21,7 +21,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples. The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} @@ -41,13 +41,13 @@ The following defines a simple base template at `_default/baseof.html`. As a def {{ end }} -{{< /code >}} +``` ## Override the base template 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 >}} +```go-html-template {file="layouts/_default/list.html"} {{ define "main" }}Posts
{{ range .Pages }} @@ -57,7 +57,7 @@ The default list template will inherit all of the code defined above and can the {{ 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. @@ -75,7 +75,7 @@ Code that you put outside the block definitions *can* break your layout. This ev The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "title" }} {{ .Title }} – {{ .Site.Title }} @@ -84,6 +84,6 @@ The following shows how you can override both the `"main"` and `"title"` block a{{ .Title }}
{{ .Content }} {{ end }} -{{< /code >}} +``` [single template]: /templates/types/#single diff --git a/content/en/templates/content-view.md b/content/en/templates/content-view.md index 07b2589a4..f001e400e 100644 --- a/content/en/templates/content-view.md +++ b/content/en/templates/content-view.md @@ -45,7 +45,7 @@ The following is the lookup order for content views ordered by specificity. In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"}{{ .Title }}
@@ -54,13 +54,13 @@ In this example, `.Render` is passed into the template to call the [render funct {{ end }}{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/filter-sort-group.md" %}} @@ -48,7 +48,7 @@ params: The home page template below inherits the site's shell from the base template, renders the subtitle and content as defined in the `_index.md` file, then renders of list of the site's [regular pages](g). -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }}{{ .Params.Subtitle }}
{{ .Content }} @@ -56,4 +56,4 @@ The home page template below inherits the site's shell from the base template, r{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index c6e49f18b..4f4081729 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -46,9 +46,9 @@ For example, a template for a single page receives a `Page` object, and the `Pag Within a template, the dot (`.`) represents the current context. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"}{{ .Title }}
-{{< /code >}} +``` In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter]. @@ -60,7 +60,7 @@ The current context may change within a template. For example, at the top of a t [`range`]: /functions/go-template/range/ [`with`]: /functions/go-template/with/ -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"}{{ .Title }}
{{ range slice "foo" "bar" }} @@ -70,7 +70,7 @@ The current context may change within a template. For example, at the top of a t {{ with "baz" }}{{ . }}
{{ end }} -{{< /code >}} +``` In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to: @@ -85,11 +85,11 @@ In the example above, the context changes as we `range` through the [slice](g) o Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with "foo" }}{{ $.Title }} - {{ . }}
{{ end }} -{{< /code >}} +``` Hugo renders this to: @@ -107,12 +107,12 @@ In the examples above the paired opening and closing braces represent the beginn A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), variables, functions, and methods. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $convertToLower := true }} {{ if $convertToLower }}{{ strings.ToLower .Title }}
{{ end }} -{{< /code >}} +``` In the example above: @@ -134,12 +134,12 @@ Hugo renders the above to: Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{- $convertToLower := true -}} {{- if $convertToLower -}}{{ strings.ToLower .Title }}
{{- end -}} -{{< /code >}} +``` Hugo renders this to: @@ -296,24 +296,24 @@ Chain the method to its object with a dot (`.`) as shown below, remembering that [current context]: #current-context -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ .Site.Title }} → My Site Title {{ .Page.Title }} → My Page Title -{{< /code >}} +``` The context passed into most templates is a `Page` object, so this is equivalent to the previous example: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ .Site.Title }} → My Site Title {{ .Title }} → My Page Title -{{< /code >}} +``` Some methods take an argument. Separate the argument from the method with a space. For example: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $page := .Page.GetPage "/books/les-miserables" }} {{ $page.Title }} → Les Misérables -{{< /code >}} +``` ## Comments diff --git a/content/en/templates/menu.md b/content/en/templates/menu.md index b6ec3f9bd..4ff423255 100644 --- a/content/en/templates/menu.md +++ b/content/en/templates/menu.md @@ -23,7 +23,7 @@ The example below handles every combination. This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list. -{{< code file=layouts/partials/menu.html copy=true >}} +```go-html-template {file="layouts/partials/menu.html" copy=true} {{- $page := .page }} {{- $menuID := .menuID }} @@ -66,14 +66,14 @@ This partial template recursively "walks" a menu structure, rendering a localize {{- end }} {{- end }} -{{< /code >}} +``` Call the partial above, passing a menu ID and the current page in context. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ partial "menu.html" (dict "menuID" "main" "page" .) }} {{ partial "menu.html" (dict "menuID" "footer" "page" .) }} -{{< /code >}} +``` ## Page references @@ -81,7 +81,7 @@ Regardless of how you [define menu entries], an entry associated with a page has This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{- range site.Menus.main }} {{ .Name }} @@ -92,7 +92,7 @@ This simplistic example renders a page parameter named `version` next to each en {{- end }} {{- end }} -{{< /code >}} +``` ## Menu entry parameters @@ -103,13 +103,13 @@ When you define menu entries [in site configuration] or [in front matter], you c This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined. -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} {{- range site.Menus.main }} {{ .Name }} {{- end }} -{{< /code >}} +``` ## Localize diff --git a/content/en/templates/partial.md b/content/en/templates/partial.md index f3322b4d2..ba63ae37f 100644 --- a/content/en/templates/partial.md +++ b/content/en/templates/partial.md @@ -121,7 +121,7 @@ The `partialCached` template function provides significant performance gains for The following `header.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file=layouts/partials/header.html >}} +```go-html-template {file="layouts/partials/header.html"} @@ -136,7 +136,7 @@ The following `header.html` partial template is used for [spf13.com](https://spf {{ partial "head_includes.html" . }} -{{< /code >}} +``` {{< note >}} The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. @@ -146,7 +146,7 @@ The `header.html` example partial was built before the introduction of block tem The following `footer.html` partial template is used for [spf13.com](https://spf13.com/): -{{< code file=layouts/partials/footer.html >}} +```go-html-template {file="layouts/partials/footer.html"} -{{< /code >}} +``` [context]: /templates/introduction/ [customize]: /hugo-modules/theme-components/ diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md index 7909334e2..72ddf81b6 100644 --- a/content/en/templates/robots.md +++ b/content/en/templates/robots.md @@ -33,12 +33,12 @@ You may overwrite the internal template with a custom template. Hugo selects the ## robots.txt template example -{{< code file=layouts/robots.txt >}} +```text {file="cayouts/robots.txt"} User-agent: * {{ range .Pages }} Disallow: {{ .RelPermalink }} {{ end }} -{{< /code >}} +``` This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site. diff --git a/content/en/templates/section.md b/content/en/templates/section.md index 8f4f5ae3b..8bc0f9dab 100644 --- a/content/en/templates/section.md +++ b/content/en/templates/section.md @@ -17,7 +17,7 @@ See [Template Lookup](/templates/lookup-order/). ## Example: creating a default section template -{{< code file=layouts/_default/section.html >}} +```go-html-template {file="layouts/_default/section.html"} {{ define "main" }}{{ .Get "title" }}
{{ .Inner | .Page.RenderString }}
{{ .Inner }}
-{{< /code >}}
+```
You also have an `img` shortcode with a single named `src` argument 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 >}}
+```go-html-template {file="layouts/shortcodes/img.html"}
{{ $src := .Get "src" }}
{{ with .Parent }}
{{ .Title }}
{{ .Content }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -24,7 +24,7 @@ Review the [template lookup order] to select a template path that provides the d The single template below inherits the site's shell from the base template, and renders the page title, creation date, content, and a list of associated terms in the "tags" taxonomy. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}{{ .Title }}
@@ -48,4 +48,4 @@ The single template below inherits the site's shell from the base template, and{{ .Title }}
{{ .Content }} @@ -19,7 +19,7 @@ The [taxonomy](g) template below inherits the site's shell from the [base templa{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -64,7 +64,7 @@ Once we have the `Taxonomy` object, we can call any of its [methods], allowing u The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list alphabetically by term, and displays the number of pages associated with each term. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -72,13 +72,13 @@ The taxonomy template below inherits the site's shell from the base template, an{{ .Page.LinkTitle }} ({{ .Count }})
{{ end }} {{ end }} -{{< /code >}} +``` ## Sort by term count The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, and displays the number of pages associated with each term. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -86,7 +86,7 @@ The taxonomy template below inherits the site's shell from the base template, an{{ .Page.LinkTitle }} ({{ .Count }})
{{ end }} {{ end }} -{{< /code >}} +``` ## Include content links @@ -97,7 +97,7 @@ The [`Alphabetical`] and [`ByCount`] methods used in the previous examples retur The taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. Hugo sorts the list by the number of pages associated with each term, displays the number of pages associated with each term, then lists the content to which each term is assigned. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -110,7 +110,7 @@ The taxonomy template below inherits the site's shell from the base template, an {{ end }} {{ end }} -{{< /code >}} +``` ## Display metadata @@ -145,7 +145,7 @@ affiliation = "University of Chicago" Then create a taxonomy template specific to the "authors" taxonomy: -{{< code file=layouts/authors/taxonomy.html >}} +```go-html-template {file="layouts/authors/taxonomy.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -159,6 +159,6 @@ Then create a taxonomy template specific to the "authors" taxonomy: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` In the example above we list each author including their affiliation and portrait. diff --git a/content/en/templates/term.md b/content/en/templates/term.md index d6e11b0f7..cf1097e86 100644 --- a/content/en/templates/term.md +++ b/content/en/templates/term.md @@ -10,7 +10,7 @@ The [term](g) template below inherits the site's shell from the [base template], [base template]: /templates/types/ -{{< code file=layouts/_default/term.html >}} +```go-html-template {file="layouts/_default/term.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -18,7 +18,7 @@ The [term](g) template below inherits the site's shell from the [base template],{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` Review the [template lookup order] to select a template path that provides the desired level of specificity. @@ -88,7 +88,7 @@ affiliation = "University of Chicago" Then create a term template specific to the "authors" taxonomy: -{{< code file=layouts/authors/term.html >}} +```go-html-template {file="layouts/authors/term.html"} {{ define "main" }}{{ .Title }}
Affiliation: {{ .Params.affiliation }}
@@ -102,6 +102,6 @@ Then create a term template specific to the "authors" taxonomy:{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` In the example above we display the author with their affiliation and portrait, then a list of associated content. diff --git a/content/en/templates/types.md b/content/en/templates/types.md index 8dd47aca1..e623b8be2 100644 --- a/content/en/templates/types.md +++ b/content/en/templates/types.md @@ -54,7 +54,7 @@ For example, the base template below calls the [partial] function to include par [block]: /functions/go-template/block/ [partial]: /functions/partials/include/ -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} @@ -72,7 +72,7 @@ For example, the base template below calls the [partial] function to include par -{{< /code >}} +``` Learn more about [base templates](/templates/base/). @@ -80,14 +80,14 @@ Learn more about [base templates](/templates/base/). A home page template is used to render your site's home page, and is the only template required for a single-page website. For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages. -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }} {{ .Content }} {{ range site.RegularPages }}{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/filter-sort-group.md" %}} @@ -99,12 +99,12 @@ A single template renders a single page. For example, the single template below inherits the site's shell from the base template, and renders the title and content of each page. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} {{ end }} -{{< /code >}} +``` Learn more about [single templates](/templates/single/). @@ -114,7 +114,7 @@ A section template typically renders a list of pages within a section. For example, the section template below inherits the site's shell from the base template, and renders a list of pages in the current section. -{{< code file=layouts/_default/section.html >}} +```go-html-template {file="layouts/_default/section.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -122,7 +122,7 @@ For example, the section template below inherits the site's shell from the base{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/filter-sort-group.md" %}} @@ -134,7 +134,7 @@ A taxonomy template renders a list of terms in a [taxonomy](g). For example, the taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy. -{{< code file=layouts/_default/taxonomy.html >}} +```go-html-template {file="layouts/_default/taxonomy.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -142,7 +142,7 @@ For example, the taxonomy template below inherits the site's shell from the base{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/filter-sort-group.md" %}} @@ -154,7 +154,7 @@ A term template renders a list of pages associated with a [term](g). For example, the term template below inherits the site's shell from the base template, and renders a list of pages associated with the current term. -{{< code file=layouts/_default/term.html >}} +```go-html-template {file="layouts/_default/term.html"} {{ define "main" }}{{ .Title }}
{{ .Content }} @@ -162,7 +162,7 @@ For example, the term template below inherits the site's shell from the base tem{{ .LinkTitle }}
{{ end }} {{ end }} -{{< /code >}} +``` {{% include "/_common/filter-sort-group.md" %}} @@ -180,9 +180,9 @@ Unlike other template types, you cannot create partial templates to target a par For example, the partial template below renders copyright information. -{{< code file=layouts/partials/footer.html >}} +```go-html-template {file="layouts/partials/footer.html"}Copyright {{ now.Year }}. All rights reserved.
-{{< /code >}} +``` Learn more about [partial templates](/templates/partial/). @@ -197,7 +197,7 @@ A content view template is similar to a partial template, invoked by calling the For example, the home template below inherits the site's shell from the base template, and renders a card component for each page within the "articles" section of your site. -{{< code file=layouts/_default/home.html >}} +```go-html-template {file="layouts/_default/home.html"} {{ define "main" }} {{ .Content }}-
@@ -206,14 +206,14 @@ For example, the home template below inherits the site's shell from the base tem
{{ end }}
{{ .LinkTitle }}
{{ .Summary }}
{{- if $copy }}
diff --git a/layouts/shortcodes/code.html b/layouts/shortcodes/code.html
deleted file mode 100644
index ae50aa2f0..000000000
--- a/layouts/shortcodes/code.html
+++ /dev/null
@@ -1,38 +0,0 @@
-{{- $codeLang := or (.Get "lang") "" }}
-
- {{ if (.Get "copy") }}
-
- {{ end }}
- {{- with .Get "file" -}}
- {{- if not $codeLang }}
- {{- $ext := strings.TrimPrefix "." (path.Ext .) }}
- {{- $codeLang = cond (eq $ext "html") "go-html-template" $ext }}
- {{- end }}
-
- {{ . }}
-
- {{- end -}}
-
-
-
- {{ $inner := trim .Inner "\n" | safeHTML }}
- {{ if .Get "nocode" }}
- {{ $inner }}
- {{ else }}
- {{ with $codeLang }}
- {{ highlight $inner . "" }}
- {{ else }}
-
-{{ $inner }}
-