Merge commit 'a024bc7d76fcc5e49e8210f9b0896db9ef21861a'

docs/layouts/shortcodes/chroma-lexers.html

@@ -0,0 +1,7 @@
+<dl>
+    {{ range .Site.Data.docs.chroma.lexers }}
+      <dt>{{ .Name }}</dt>
+      <dd>{{ with .Aliases }}{{ delimit . ", " }}{{ end }}</dd>
+    {{ end }}
+  </dl>
+  

docs/layouts/shortcodes/code-toggle.html

@@ -0,0 +1,109 @@
+{{- /*
+  Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats.
+
+  @param {string} [config] The section of site.Data.docs.config to render.
+  @param {bool} [copy=false] If true, display a copy to clipboard button.
+  @param {string} [file] The file name to display above the rendered code.
+  @param {bool} [fm=false] If true, render the code as front matter.
+  @param {bool} [skipHeader=false] If false, omit top level key(s) when rendering a section of site.Data.docs.config.
+
+  @returns {template.HTML}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $config := "" }}
+{{- $dataKey := "" }}
+{{- $copy := false }}
+{{- $file := "" }}
+{{- $fm := false }}
+{{- $skipHeader := false }}
+
+{{- /* Get parameters. */}}
+{{- $config = .Get "config" }}
+{{- $dataKey = .Get "dataKey" }}
+{{- $file = .Get "file" }}
+{{- if in (slice "false" false 0) (.Get "copy") }}
+  {{- $copy = false }}
+{{- else if in (slice "true" true 1) (.Get "copy") }}
+  {{- $copy = true }}
+{{- end }}
+{{- if in (slice "false" false 0) (.Get "fm") }}
+  {{- $fm = false }}
+{{- else if in (slice "true" true 1) (.Get "fm") }}
+  {{- $fm = true }}
+{{- end }}
+{{- if in (slice "false" false 0) (.Get "skipHeader") }}
+  {{- $skipHeader = false }}
+{{- else if in (slice "true" true 1) (.Get "skipHeader") }}
+  {{- $skipHeader = true }}
+{{- end }}
+
+{{- /* Define constants. */}}
+{{- $delimiters := dict "toml" "+++" "yaml" "---" }}
+{{- $langs := slice "yaml" "toml" "json" }}
+{{- $placeHolder := "#-hugo-placeholder-#" }}
+
+{{- /* Render. */}}
+{{- $code := "" }}
+{{- if $config }}
+  {{- $file = $file | default "hugo" }}
+  {{- $sections := (split $config ".") }}
+  {{- $configSection := index $.Site.Data.docs.config $sections }}
+  {{- $code = dict $sections $configSection }}
+  {{- if $skipHeader }}
+    {{- $code = $configSection }}
+  {{- end }}
+{{- else if $dataKey }}
+  {{- $file = $file | default $dataKey }}
+  {{- $sections := (split $dataKey ".") }}
+  {{- $code = index $.Site.Data.docs $sections }}
+{{- else }}
+  {{- $code = $.Inner }}
+{{- end }}
+<div x-data class="shortcode-code not-prose relative p-0 mt-2 mb-4 sm:mb-8">
+  <svg
+    class="absolute right-2 top-0 z-30 text-blue-600 hover:text-blue-500 cursor-pointer w-8"
+    @click="$copy($refs[$store.nav.userSettings.settings.configFileType])">
+    <use href="#icon--copy"></use>
+  </svg>
+  <nav class="relative flex" aria-label="Tabs">
+    {{ with $file }}
+      <div
+        class="flex-none text-sm px-2 content-center border-b-1 border-gray-300 dark:border-gray-700"
+        aria-lbabel="Filename">
+        {{ . }}{{ if not $fm }}.{{ end }}
+      </div>
+    {{ end }}
+    {{ range $i, $lang := $langs }}
+      {{ $isLast := eq (add $i 1) (len $langs) }}
+      <button
+        x-on:click="$store.nav.userSettings.settings.configFileType = '{{ index $langs $i }}'"
+        aria-label="{{ printf `Toggle %s` . }}"
+        class="px-3 py-2 font-semibold text-black dark:text-slate-200 border-l-1 border-t-1 {{ if $isLast }}
+          border-r-1
+        {{ end }} border-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 dark:border-gray-700 cursor-pointer relative min-w-0 flex-1 overflow-hidden text-sm no-underline text-center focus:z-10 overflow-x-auto"
+        :class="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}' ? 'border-b-0 bg-light dark:bg-dark' : 'border-b-1'">
+        <span>
+          {{ . }}
+        </span>
+      </button>
+    {{ end }}
+  </nav>
+  {{ if $code }}
+    {{ range $i, $lang := $langs }}
+      <div
+        class="max-h-96 overflow-y-auto border-l-1 border-b-1 border-r-1 border-gray-300 dark:border-gray-700"
+        x-ref="{{ $lang }}"
+        x-cloak
+        x-transition:enter.opacity.duration.300ms
+        x-show="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}'">
+        {{- $hCode := $code | transform.Remarshal . }}
+        {{- if and $fm (in (slice "toml" "yaml") .) }}
+          {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }}
+        {{- end }}
+        {{- $hCode = $hCode | replaceRE `\n+` "\n" }}
+        {{ highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }}
+      </div>
+    {{ end }}
+  {{ end }}
+</div>

docs/layouts/shortcodes/code.html

@@ -0,0 +1,38 @@
+{{- $codeLang := or (.Get "lang") "" }}
+<div
+  x-data
+  class="shortcode-code font-mono not-prose relative mt-6 mb-8 border-1 border-gray-200 dark:border-gray-800 bg-light dark:bg-dark">
+  {{ if (.Get "copy") }}
+    <svg
+      class="absolute right-2 top-2 z-30 text-blue-600 hover:text-blue-500 cursor-pointer w-6 h-6"
+      @click="$copy($refs.code)">
+      <use href="#icon--copy"></use>
+    </svg>
+  {{ end }}
+  {{- with .Get "file" -}}
+    {{- if not $codeLang }}
+      {{- $ext := strings.TrimPrefix "." (path.Ext .) }}
+      {{- $codeLang = cond (eq $ext "html") "go-html-template" $ext }}
+    {{- end }}
+    <div
+      class="san-serif text-sm inline-block leading-none pl-2 py-3 bg-gray-300 dark:bg-slate-700 dark: w-full select-none
+">
+      {{ . }}
+    </div>
+  {{- end -}}
+
+
+  <div class="" x-ref="code">
+    {{ $inner := trim .Inner "\n" | safeHTML }}
+    {{ if .Get "nocode" }}
+      {{ $inner }}
+    {{ else }}
+      {{ with $codeLang }}
+        {{ highlight $inner . "" }}
+      {{ else }}
+        <pre class="overflow-x-auto p-2 w-[93%]"><code>{{ $inner }}</code>
+        </pre>
+      {{ end }}
+    {{ end }}
+  </div>
+</div>

docs/layouts/shortcodes/datatable-filtered.html

@@ -0,0 +1,39 @@
+{{ $package := (index .Params 0) }}
+{{ $listname := (index .Params 1) }}
+{{ $filter := split (index .Params 2) " " }}
+{{ $filter1 := index $filter 0 }}
+{{ $filter2 := index $filter 1 }}
+{{ $filter3 := index $filter 2 }}
+
+{{ $list := (index (index .Site.Data.docs $package) $listname) }}
+{{ $fields := after 3 .Params }}
+{{ $list := where $list $filter1 $filter2 $filter3 }}
+
+<table class="table table-bordered">
+	<tr>
+		{{ range $fields }}
+		<th>{{ . }}</th>
+		{{ end }}
+	</tr>
+	{{ range $list }}
+	<tr>
+		{{ range $k, $v := . }}
+		{{ $.Scratch.Set $k $v }}
+		{{ end }}
+		{{ range $k, $v := $fields }}
+			<td>
+				{{ $tdContent := $.Scratch.Get . }}
+				{{ if eq $k 3 }}
+					{{ printf "%v" $tdContent |
+							strings.ReplaceRE `\[` "<ol><li>" |
+							strings.ReplaceRE `\s` "</li><li>" |
+							strings.ReplaceRE `\]` "</li></ol>" |
+							safeHTML }}
+				{{ else }}
+					{{ $tdContent }}
+				{{ end}}
+			</td>
+		{{ end }}
+	</tr>
+	{{ end }}
+</table>

docs/layouts/shortcodes/datatable.html

@@ -0,0 +1,33 @@
+{{ $package := (index .Params 0) }}
+{{ $listname := (index .Params 1) }}
+{{ $list := (index (index .Site.Data.docs $package) $listname) }}
+{{ $fields := after 2 .Params }}
+
+
+<table class="table table-bordered">
+  <tr>
+    {{ range $fields }}
+      {{ $s := . }}
+      {{ if eq $s "_key" }}
+        {{ $s = "Type" }}
+      {{ end }}
+      <th>{{ $s }}</th>
+    {{ end }}
+  </tr>
+  {{ range $k1, $v1 := $list }}
+    <tr>
+      {{ range $k2, $v2 := . }}
+        {{ $.Scratch.Set $k2 $v2 }}
+      {{ end }}
+      {{ range $fields }}
+        {{ $s := "" }}
+        {{ if eq . "_key" }}
+          {{ $s = $k1 }}
+        {{ else }}
+          {{ $s = $.Scratch.Get . }}
+        {{ end }}
+        <td>{{ $s }}</td>
+      {{ end }}
+    </tr>
+  {{ end }}
+</table>

docs/layouts/shortcodes/deprecated-in.html

@@ -0,0 +1,17 @@
+{{ $_hugo_config := `{ "version": 1 }` }}
+
+{{ with .Get 0 }}
+  {{ $version := printf "v%v" (strings.TrimLeft "vV" .) }}
+  {{ $href := printf "https://github.com/gohugoio/hugo/releases/tag/%s" $version }}
+  {{ $text := (printf `Deprecated in <a href="%s">%s</a>.
+%s` $href $version $.Inner) | safeHTML }}
+
+  {{ partial "layouts/blocks/alert.html" (dict
+  "text" $text
+  "color" "orange"
+  "icon" "exclamation"
+  )
+}}
+{{ else }}
+  {{ errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }}
+{{ end }}

docs/layouts/shortcodes/eturl.html

@@ -0,0 +1,36 @@
+{{- /*
+Renders an absolute URL to the source code for an embedded template.
+
+Accepts either positional or named parameters, and depends on the
+embedded_templates.toml file in the data directory.
+
+@param {string} filename The embedded template's file name, excluding extension.
+
+@returns template.HTML
+
+@example {{% et robots.txt %}}
+@example {{% et filename=robots.txt %}}
+*/}}
+
+{{- /* Get parameters. */}}
+{{- $filename := "" -}}
+{{- if .IsNamedParams -}}
+ {{- $filename = .Get "filename" -}}
+{{- else -}}
+ {{- $filename = .Get 0 -}}
+{{- end -}}
+
+{{- /* Render. */}}
+{{- with $filename -}}
+  {{- with site.Data.embedded_template_urls -}}
+    {{- with index . $filename -}}
+      {{- urls.JoinPath site.Data.embedded_template_urls.base_url . -}}
+    {{- else -}}
+      {{- errorf "The %q shortcode was unable to find a URL for the embedded template named %q. Check the name. See %s" $.Name $filename $.Position -}}
+    {{- end -}}
+  {{- else -}}
+    {{- errorf "The %q shortcode was unable to find the embedded_template_urls data file in the site's data directory. See %s" $.Name $.Position -}}
+  {{- end -}}
+{{- else -}}
+ {{- errorf "The %q shortcodes requires a named or positional parameter, the file name of the embedded template, excluding its extension. See %s" .Name .Position -}}
+{{- end -}}

docs/layouts/shortcodes/glossary-term.html

@@ -9,12 +9,12 @@ Renders the definition of the given glossary term.
 */}}
 
 {{- with .Get 0 }}
-  {{- $path := printf "/getting-started/glossary/%s" (urlize .) }}
+  {{- $path := printf "/quick-reference/glossary/%s" (urlize .) }}
   {{- with site.GetPage $path }}
-{{ .RenderShortcodes }}{{/* Do not indent. */}}
+{{ .RenderShortcodes }} {{/* Do not indent. Do not remove non-breaking space. */}}
   {{- else }}
     {{- errorf "The glossary term (%s) shortcode was unable to find %s: see %s" $.Name $path $.Position }}
   {{- end }}
 {{- else }}
   {{- errorf "The glossary term (%s) shortcode requires one positional parameter: see %s" $.Name $.Position }}
-{{- end }}
+{{- end -}}

docs/layouts/shortcodes/glossary.html

@@ -13,13 +13,12 @@ shortcode.
 
 @example {{% glossary %}}
 */}}
-{{- $path := "/getting-started/glossary" }}
+{{- $path := "/quick-reference/glossary" }}
 {{- with site.GetPage $path }}
-  {{- with $p := .Pages.ByTitle }}
 
     {{- /* Build and render alphabetical index. */}}
     {{- $m := dict }}
-    {{- range $p }}
+    {{- range $p := .Pages.ByTitle }}
       {{- $k := substr .Title 0 1 | strings.ToUpper }}
       {{- if index $m $k }}
         {{- continue }}
@@ -32,12 +31,26 @@ shortcode.
     {{- end }}
 
     {{- /* Render glossary terms. */}}
-    {{- range $p }}
+    {{- range $p := .Pages.ByTitle }}
 ###### {{ .Title }}{{/* Do not indent. */}}
 {{ .RenderShortcodes }}{{/* Do not indent. */}}
+      {{- with .Params.reference }}
+        {{- $destination := "" }}
+        {{- with $u := urls.Parse . }}
+          {{- if $u.IsAbs }}
+            {{- $destination = $u.String }}
+          {{- else }}
+            {{- with site.GetPage $u.Path -}}
+              {{- $destination = .RelPermalink }}
+            {{- else }}
+              {{- errorf "The %q shortcode was unable to find the reference link %s: see %s" $.Name . $p.String }}
+            {{- end }}
+          {{- end }}
+        {{- end -}}
+ See [details]({{ $destination }}).{{/* Do not indent. */}}
+      {{- end }}
     {{- end }}
 
-  {{- end }}
 {{- else }}
   {{- errorf "The %q shortcode was unable to get %s: see %s" .Name $path .Position}}
 {{- end }}

docs/layouts/shortcodes/gomodules-info.html

@@ -0,0 +1,12 @@
+{{ $text := `
+  Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ).
+  If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings.
+
+  For more information about Go Modules, see:
+
+  * https://go.dev/wiki/Modules
+  * https://blog.golang.org/using-go-modules
+  `
+}}
+
+{{ partial "layouts/blocks/alert.html" (dict "title" "Go Modules" "text" ($text | markdownify) "color" "orange" "icon" "exclamation") }}

docs/layouts/shortcodes/hl.html

@@ -0,0 +1,11 @@
+{{- /*
+Returns syntax-highlighted code from the given text.
+
+This is useful as a terse way to highlight inline code snippets. Calling the
+highlight shortcode for inline snippets is verbose.
+*/}}
+
+{{- $code := .Inner | strings.TrimSpace }}
+{{- $lang := or (.Get 0) "go"  }}
+{{- $opts := dict "hl_inline" true "noClasses" true }}
+{{- transform.Highlight $code $lang $opts }}

docs/layouts/shortcodes/img.html

@@ -0,0 +1,391 @@
+{{- /*
+Renders the given image using the given filter, if any.
+
+@param {string} src The path to the image which must be a remote, page, or global resource.
+@param {string} [filter] The filter to apply to the image (case-insensitive).
+@param {string} [filterArgs] A comma-delimited list of arguments to pass to the filter.
+@param {bool} [example=false] If true, renders a before/after example.
+@param {int} [exampleWidth=384] Image width, in pixels, when rendering a before/after example.
+
+@returns {template.HTML}
+
+@examples
+
+  {{< img src="zion-national-park.jpg" >}}
+
+  {{< img src="zion-national-park.jpg" alt="Zion National Park" >}}
+
+  {{< img
+    src="zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="grayscale"
+  >}}
+
+  {{< img
+    src="zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="process"
+    filterArgs="resize 400x webp"
+  >}}
+
+  {{< img
+    src="zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="colorize"
+    filterArgs="180,50,20"
+  >}}
+
+  {{< img
+    src="zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="grayscale"
+    example=true
+  >}}
+
+  {{< img
+    src="zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="grayscale"
+    example=true
+    exampleWidth=400
+  >}}
+
+  When using the text filter, provide the arguments in this order:
+
+    0. The text
+    1. The horizontal offset, in pixels, relative to the left of the image (default 20)
+    2. The vertical offset, in pixels, relative to the top of the image (default 20)
+    3. The font size in pixels (default 64)
+    4. The line height (default 1.2)
+    5. The font color (default #ffffff)
+
+  {{< img
+    src="images/examples/zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="Text"
+    filterArgs="Zion National Park,25,250,56"
+    example=true
+  >}}
+
+  When using the padding filter, provide all arguments in this order:
+
+  0. Padding top
+  1. Padding right
+  2. Padding bottom
+  3. Padding right
+  4. Canvas color
+
+  {{< img
+    src="images/examples/zion-national-park.jpg"
+    alt="Zion National Park"
+    filter="Padding"
+    filterArgs="20,50,20,50,#0705"
+    example=true
+  >}}
+
+*/}}
+
+{{- /* Initialize. */}}
+{{- $alt := "" }}
+{{- $src := "" }}
+{{- $filter := "" }}
+{{- $filterArgs := slice }}
+{{- $example := false }}
+{{- $exampleWidth := 384 }}
+
+{{- /* Default values to use with the text filter. */}}
+{{ $textFilterOpts := dict
+  "xOffset" 20
+  "yOffset" 20
+  "fontSize" 64
+  "lineHeight" 1.2
+  "fontColor" "#ffffff"
+  "fontPath" "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf"
+}}
+
+{{- /* Get and validate parameters. */}}
+{{- with .Get "alt" }}
+  {{- $alt = .}}
+{{- end }}
+
+{{- with .Get "src" }}
+  {{- $src = . }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a file parameter. See %s" .Name .Position }}
+{{- end }}
+
+{{- with .Get "filter" }}
+  {{- $filter = . | lower }}
+{{- end }}
+
+{{- $validFilters := slice
+  "autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
+  "gamma" "gaussianblur" "grayscale" "hue" "invert" "mask" "none" "opacity"
+  "overlay" "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
+  "unsharpmask"
+}}
+
+{{- with $filter }}
+  {{- if not (in $validFilters .) }}
+    {{- errorf "The filter passed to the %q shortcode is invalid. The filter must be one of %s. See %s" $.Name (delimit $validFilters ", " ", or ") $.Position }}
+  {{- end }}
+{{- end }}
+
+{{- with .Get "filterArgs" }}
+  {{- $filterArgs = split . "," }}
+  {{- $filterArgs = apply $filterArgs "trim" "." " " }}
+{{- end }}
+
+{{- if in (slice "false" false 0) (.Get "example") }}
+  {{- $example = false }}
+{{- else if in (slice "true" true 1) (.Get "example")}}
+  {{- $example = true }}
+{{- end }}
+
+{{- with .Get "exampleWidth" }}
+  {{- $exampleWidth = . | int }}
+{{- end }}
+
+{{- /* Get image. */}}
+{{- $ctx := dict "page" .Page "src" $src "name" .Name "position" .Position }}
+{{- $i := partial "inline/get-resource.html" $ctx }}
+
+{{- /* Resize if rendering before/after examples. */}}
+{{- if $example }}
+  {{- $i = $i.Resize (printf "%dx" $exampleWidth) }}
+{{- end }}
+
+{{- /* Create filter. */}}
+{{- $f := "" }}
+{{- $ctx := dict "filter" $filter "args" $filterArgs "name" .Name "position" .Position }}
+{{- if eq $filter "autoorient" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $f = images.AutoOrient }}
+{{- else if eq $filter "brightness" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Brightness (index $filterArgs 0) }}
+{{- else if eq $filter "colorbalance" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage red" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage green" "argValue" (index $filterArgs 1) "min" -100 "max" 500) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage blue" "argValue" (index $filterArgs 2) "min" -100 "max" 500) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.ColorBalance (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- else if eq $filter "colorize" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "hue" "argValue" (index $filterArgs 0) "min" 0 "max" 360) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "saturation" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 2) "min" 0 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Colorize (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- else if eq $filter "contrast" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Contrast (index $filterArgs 0) }}
+{{- else if eq $filter "dither" }}
+  {{- $f = images.Dither }}
+{{- else if eq $filter "gamma" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "gamma" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Gamma (index $filterArgs 0) }}
+{{- else if eq $filter "gaussianblur" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.GaussianBlur (index $filterArgs 0) }}
+{{- else if eq $filter "grayscale" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $f = images.Grayscale }}
+{{- else if eq $filter "hue" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "shift" "argValue" (index $filterArgs 0) "min" -180 "max" 180) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Hue (index $filterArgs 0) }}
+{{- else if eq $filter "invert" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 0) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $f = images.Invert }}
+{{- else if eq $filter "mask" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }}
+  {{- $maskImage := partial "inline/get-resource.html" $ctx }}
+  {{- $f = images.Mask $maskImage }}
+{{- else if eq $filter "opacity" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "opacity" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Opacity (index $filterArgs 0) }}
+{{- else if eq $filter "overlay" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }}
+  {{- $overlayImg := partial "inline/get-resource.html" $ctx }}
+  {{- $f = images.Overlay $overlayImg (index $filterArgs 1 | float ) (index $filterArgs 2 | float) }}
+{{- else if eq $filter "padding" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 5) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $f = images.Padding
+    (index $filterArgs 0 | int)
+    (index $filterArgs 1 | int)
+    (index $filterArgs 2 | int)
+    (index $filterArgs 3 | int)
+    (index $filterArgs 4)
+  }}
+{{- else if eq $filter "pixelate" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "size" "argValue" (index $filterArgs 0) "min" 0 "max" 1000) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Pixelate (index $filterArgs 0) }}
+{{- else if eq $filter "process" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $f = images.Process (index $filterArgs 0) }}
+{{- else if eq $filter "saturation" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" -100 "max" 500) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Saturation (index $filterArgs 0) }}
+{{- else if eq $filter "sepia" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "percentage" "argValue" (index $filterArgs 0) "min" 0 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Sepia (index $filterArgs 0) }}
+{{- else if eq $filter "sigmoid" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 2) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "midpoint" "argValue" (index $filterArgs 0) "min" 0 "max" 1) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "factor" "argValue" (index $filterArgs 1) "min" -10 "max" 10) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.Sigmoid (index $filterArgs 0) (index $filterArgs 1) }}
+{{- else if eq $filter "text" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $ctx := dict "src" $textFilterOpts.fontPath "name" .Name "position" .Position }}
+  {{- $font := or (partial "inline/get-resource.html" $ctx) }}
+  {{- $fontSize := or (index $filterArgs 3 | int) $textFilterOpts.fontSize }}
+  {{- $lineHeight := math.Max (or (index $filterArgs 4 | float) $textFilterOpts.lineHeight) 1 }}
+  {{- $opts := dict
+    "x" (or (index $filterArgs 1 | int) $textFilterOpts.xOffset)
+    "y" (or (index $filterArgs 2 | int) $textFilterOpts.yOffset)
+    "size" $fontSize
+    "linespacing" (mul (sub $lineHeight 1) $fontSize)
+    "color" (or (index $filterArgs 5) $textFilterOpts.fontColor)
+    "font" $font
+  }}
+  {{- $f = images.Text (index $filterArgs 0) $opts }}
+{{- else if eq $filter "unsharpmask" }}
+  {{- $ctx = merge $ctx (dict "argsRequired" 3) }}
+  {{- template "validate-arg-count" $ctx }}
+  {{- $filterArgs = apply $filterArgs "float" "." }}
+  {{- $ctx = merge $ctx (dict "argName" "sigma" "argValue" (index $filterArgs 0) "min" 0 "max" 500) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "amount" "argValue" (index $filterArgs 1) "min" 0 "max" 100) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $ctx = merge $ctx (dict "argName" "threshold" "argValue" (index $filterArgs 2) "min" 0 "max" 1) }}
+  {{- template "validate-arg-value" $ctx }}
+  {{- $f = images.UnsharpMask (index $filterArgs 0) (index $filterArgs 1) (index $filterArgs 2) }}
+{{- end }}
+
+{{- /* Apply filter. */}}
+{{- $fi := $i }}
+{{- with $f }}
+  {{- $fi = $i.Filter . }}
+{{- end }}
+
+{{- /* Render. */}}
+{{- $class := "di va b--black-20" }}
+{{- if eq $filter "mask" }}
+  {{- $class = "di va" }}
+{{- end }}
+{{- if $example }}
+  <p>Original</p>
+  <img class="{{ $class}}" style="width: initial;" src="{{ $i.RelPermalink }}" alt="{{ $alt }}">
+  <p>Processed</p>
+  <img class="{{ $class }}" style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
+{{- else -}}
+  <img class='di' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
+{{- end }}
+
+{{- define "validate-arg-count" }}
+  {{- $msg := "When using the %q filter, the %q shortcode requires an args parameter with %d %s. See %s" }}
+  {{- if lt (len .args) .argsRequired }}
+    {{- $text := "values" }}
+    {{- if eq 1 .argsRequired }}
+      {{- $text = "value" }}
+    {{- end }}
+    {{- errorf $msg .filter .name .argsRequired $text .position }}
+  {{- end }}
+{{- end }}
+
+{{- define "validate-arg-value" }}
+  {{- $msg := "The %q argument passed to the %q shortcode is invalid. Expected a value in the range [%v,%v], but received %v. See %s" }}
+  {{- if or (lt .argValue .min) (gt .argValue .max) }}
+    {{- errorf $msg .argName .name .min .max .argValue .position }}
+  {{- end }}
+{{- end }}
+
+{{- define "partials/inline/get-resource.html" }}
+  {{- $r := "" }}
+  {{- $u := urls.Parse .src }}
+  {{- $msg := "The %q shortcode was unable to resolve %s. See %s" }}
+  {{- if $u.IsAbs }}
+    {{- with try (resources.GetRemote $u.String) }}
+      {{- with .Err }}
+        {{- errorf "%s" . }}
+      {{- else with .Value }}
+        {{- /* This is a remote resource. */}}
+        {{- $r = . }}
+      {{- else }}
+        {{- errorf $msg $.name $u.String $.position }}
+      {{- end }}
+    {{- end }}
+  {{- else }}
+    {{- with .page.Resources.Get (strings.TrimPrefix "./" $u.Path) }}
+      {{- /* This is a page resource. */}}
+      {{- $r = . }}
+    {{- else }}
+      {{- with resources.Get $u.Path }}
+        {{- /* This is a global resource. */}}
+        {{- $r = . }}
+      {{- else }}
+        {{- errorf $msg $.name $u.Path $.position }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+  {{- return $r}}
+{{- end -}}

docs/layouts/shortcodes/imgproc.html

@@ -0,0 +1,37 @@
+{{- /*
+Renders the given image using the given process specification.
+
+@param {string} (positional parameter 0) The path to the image, relative to the current page. The image must be a page resource.
+@param {string}} (positional parameter 1) The image processing specification.
+
+@returns template.HTML
+
+@example {{< imgproc "sunset.jpg" "resize 300x" />}}
+*/}}
+
+{{- with $.Get 0 }}
+  {{- with $i := $.Page.Resources.Get . }}
+    {{- with $spec := $.Get 1 }}
+      {{- with $i.Process . }}
+        <figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
+          <img style="max-width: 100%; width: auto; height: auto;" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+          <figcaption>
+            <small>
+              {{- with $.Inner }}
+                {{ . }}
+              {{- else }}
+                {{ $spec }}
+              {{- end }}
+            </small>
+          </figcaption>
+        </figure>
+      {{- end }}
+    {{- else }}
+      {{- errorf "The %q shortcode requires a positional parameter (1) containing the image processing specification. See %s" $.Name $.Position }}
+    {{- end }}
+  {{- else }}
+    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+  {{- end }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a positional parameter (0) indicating the image path, relative to the current page. See %s" $.Name $.Position }}
+{{- end }}

docs/layouts/shortcodes/include.html

@@ -0,0 +1,21 @@
+{{- /*
+Renders the page using the RenderShortcode method on the Page object.
+
+You must call this shortcode using the {{% %}} notation.
+
+@param {string} (positional parameter 0) The path to the page, relative to the content directory.
+@returns template.HTML
+
+@example {{% include "functions/_common/glob-patterns" %}}
+*/}}
+
+{{- with .Get 0 }}
+  {{- with or ($.Page.GetPage .) (site.GetPage .) }}
+    {{- .RenderShortcodes }}
+  {{- else }}
+    {{/* TODO1 make error */}}
+    {{- warnf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+  {{- end }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a positional parameter indicating the path of the file to include. See %s" .Name .Position }}
+{{- end }}

docs/layouts/shortcodes/list-pages-in-section.html

@@ -0,0 +1,96 @@
+{{- /*
+Renders a description list of the pages in the given section.
+
+Render a subset of the pages in the section by specifying a predefined filter,
+and whether to include those pages.
+
+Filters are defined in the data directory, in the file named page_filters. Each
+filter is an array of paths to a file, relative to the root of the content
+directory. Hugo will throw an error if the specified filter does not exist, or
+if any of the pages in the filter do not exist.
+
+The definition term elements (dt) have an id attribute derived from the title
+of the page. This is probably unique, because pages of the same title in the
+same section is unlikely.
+
+If you render a complete list on a page, then call the shortcode again to
+render a subset, you will generate duplicate element ids. In this case, set
+omitElementIDs to true for the subset.
+
+@param {string} path The path to the section.
+@param {string} [filter=""] The name of filter list.
+@param {string} [filterType=""] The type of filter, either include or exclude.
+@param {string} [omitElementIDs=false] Whether to omit dt element ids.
+@param {string} [titlePrefix=""] The string to prepend to the link title.
+
+@returns template.HTML
+
+@example {{< list-pages-in-section path=/methods/resources >}}
+@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude >}}
+@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo >}}
+@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo omitElementIDs=true >}}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $filter := or "" (.Get "filter" | lower)}}
+{{- $filterType := or (.Get "filterType") "none" | lower }}
+{{- $filteredPages := slice }}
+{{- $titlePrefix := or (.Get "titlePrefix") "" }}
+{{- $omitElementIDs := false }}
+
+{{- /* Get boolean parameters. */}}
+{{- if in (slice "false" false 0) (.Get "omitElementIDs") }}
+  {{- $omitElementIDs = false }}
+{{- else if in (slice "true" true 1) (.Get "omitElementIDs")}}
+  {{- $omitElementIDs = true }}
+{{- end }}
+
+{{- /* Build slice of filtered pages. */}}
+{{- with $filter }}
+  {{- with index site.Data.page_filters . }}
+    {{- range . }}
+      {{- with site.GetPage . }}
+        {{- $filteredPages = $filteredPages | append . }}
+      {{- else }}
+        {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
+      {{- end }}
+    {{- end }}
+  {{- else }}
+    {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
+  {{- end }}
+{{- end }}
+
+{{- /* Render */}}
+{{- with $sectionPath := .Get "path" }}
+  {{- with site.GetPage . }}
+    {{- with .RegularPages }}
+      <dl>
+        {{- range $page := .ByTitle }}
+          {{- if or
+            (and (eq $filterType "include") (in $filteredPages $page))
+            (and (eq $filterType "exclude") (not (in $filteredPages $page)))
+            (eq $filterType "none")
+          }}
+            {{- $linkTitle := .LinkTitle }}
+            {{- with $titlePrefix }}
+            {{- $linkTitle = printf "%s%s" . $linkTitle }}
+            {{- end }}
+            {{- $idAttribute := "" }}
+            {{- if not $omitElementIDs }}
+              {{- $id := path.Join .File.Dir .File.ContentBaseName | replaceRE `[\|/]` ":" | lower }}
+              {{- $idAttribute = printf " id=%q" $id }}
+            {{- end }}
+            <dt {{- $idAttribute | safeHTMLAttr }}><a href="{{ $page.RelPermalink }}">{{ $linkTitle }}</a></dt>
+            <dd>{{- $page.Description | $page.RenderString }}</dd>
+          {{- end }}
+        {{- end }}
+      </dl>
+    {{- else }}
+      {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
+    {{- end }}
+  {{- else }}
+    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
+  {{- end }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
+{{- end }}

docs/layouts/shortcodes/module-mounts-note.html

@@ -0,0 +1 @@
+Also see [Module Mounts Config](/hugo-modules/configuration/#module-configuration-mounts) for an alternative way to configure this directory.

docs/layouts/shortcodes/new-in.html

@@ -0,0 +1,66 @@
+{{- /*
+  Renders a "new in" button indicating the version in which a feature was added.
+
+  When comparing the current version to the specified version, the "new in"
+  button will be hidden if any of the following conditions is true:
+
+  - The major version difference exceeds the majorVersionDiffThreshold
+  - The minor version difference exceeds the minorVersionDiffThreshold
+
+  @param {string} version The semantic version string, with or without a leading v.
+  @returns {template.HTML}
+
+  @examples {{< new-in 0.100.0 /
+>}}
+
+{{< new-in 0.100.0 >}}
+Some descriptive text here.
+{{< /new-in >}}
+*/}}
+{{ $_hugo_config := `{ "version": 1 }` }}
+
+{{- /* Set defaults. */}}
+{{- $majorVersionDiffThreshold := 0 }}
+{{- $minorVersionDiffThreshold := 30 }}
+{{- $displayExpirationWarning := true }}
+
+{{- /* Render. */}}
+{{- with $version := .Get 0 | strings.TrimPrefix "v" }}
+  {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }}
+  {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }}
+  {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }}
+    {{- if $displayExpirationWarning }}
+      {{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
+    {{- end }}
+  {{- else }}
+    {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}
+    {{- with $.Inner }}
+      {{ $text := printf `<p class="fon-semibold">New in <a href=%q>v%s</a>.</p>%s`
+        $href $version (. | $.Page.RenderString (dict "display" "block"))
+      }}
+
+      {{ partial "layouts/blocks/alert.html" (dict
+        "text" ($text | safeHTML)
+        "color" "green"
+        "icon" "exclamation"
+        )
+      }}
+    {{- else }}
+      <span
+        class="not-prose inline-flex items-center px-2 mr-1 rounded text-sm font-medium bg-green-200 dark:bg-green-400 fill-green-600">
+        <svg class="mr-1.5 h-2 w-2" viewBox="0 0 8 8">
+          <circle cx="4" cy="4" r="3" />
+        </svg>
+        <a
+          class="text-green-800 dark:text-black hover:text-green-600 no-underline"
+          href="{{ $href }}"
+          target="_blank">
+          New in
+          v{{ $version }}
+        </a>
+      </span>
+    {{- end }}
+  {{- end }}
+{{- else }}
+  {{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
+{{- end -}}

docs/layouts/shortcodes/note.html

@@ -0,0 +1,7 @@
+{{ $_hugo_config := `{ "version": 1 }` }}
+{{ partial "layouts/blocks/alert.html" (dict
+  "text" .Inner
+  "color" "blue"
+  "icon" "exclamation"
+  )
+}}

docs/layouts/shortcodes/quick-reference.html

@@ -0,0 +1,39 @@
+{{/*
+Renders the child sections of the given top-level section, listing each child's immediate descendants.
+
+@param {string} section The top-level section to render.
+@returns template.HTML
+
+@example {{% quick-reference section="functions" %}}
+*/}}
+
+{{ $section := "" }}
+{{ with .Get "section" }}
+  {{ $section = . }}
+{{ else }}
+  {{ errorf "The %q shortcodes requires a 'section' parameter. See %s" .Name .Position }}
+{{ end }}
+
+{{/* Do not change the markdown indentation, and do not remove blank lines. */}}
+{{ with site.GetPage $section }}
+  {{ range .Sections }}
+
+## {{ .LinkTitle }}
+{{ .RawContent }}
+
+    {{ range .Pages }}
+      {{ $aliases := "" }}
+      {{ if eq .Section "functions" }}
+        {{ with .Params.action.aliases }}
+          {{ $aliases = delimit . " or " }}
+        {{ end }}
+      {{ end }}
+
+[{{ .LinkTitle }}]({{ .RelPermalink }}) {{ with $aliases }}({{ . }}){{ end }}
+: {{ .Description }}
+
+    {{ end }}
+  {{ end }}
+{{ else }}
+  {{ errorf "The %q shortcodes was unable to find the %q section. See %s" .Name $section .Position }}
+{{ end }}

docs/layouts/shortcodes/readfile.html

@@ -0,0 +1 @@
+TODO readfile.html