Tabpane shortcodes: improved reporting of warnings and errors (#1478)

layouts/shortcodes/blocks/lead.html

@@ -2,7 +2,7 @@
 {{ $height := .Get "height" | default "auto" -}}
 {{ with .Get "height" -}}
   {{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}}
-    {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
+    {{ errorf "shortcode 'lead': parameter height is %q, must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}}
   {{ end -}}
 {{ end -}}
 

layouts/shortcodes/imgproc.html

@@ -1,17 +1,17 @@
-{{ $original := .Page.Resources.GetMatch (printf "**%s*" (.Get 0)) }}
-{{ $command := .Get 1 }}
-{{ $options := .Get 2 }}
-{{ if eq $command "Fit"}}
-{{ .Scratch.Set "image" ($original.Fit $options) }}
-{{ else if eq $command "Resize"}}
-{{ .Scratch.Set "image" ($original.Resize $options) }}
-{{ else if eq $command "Fill"}}
-{{ .Scratch.Set "image" ($original.Fill $options) }}
-{{ else if eq $command "Crop"}}
-{{ .Scratch.Set "image" ($original.Crop $options) }}
-{{ else }}
-{{ errorf "Invalid image processing command: Must be one of Fit, Fill, Crop or Resize."}}
-{{ end }}
+{{ $original := .Page.Resources.GetMatch (printf "**%s*" (.Get 0)) -}}
+{{ $command := .Get 1 -}}
+{{ $options := .Get 2 -}}
+{{ if eq $command "Fit" -}}
+{{ .Scratch.Set "image" ($original.Fit $options) -}}
+{{ else if eq $command "Resize" -}}
+{{ .Scratch.Set "image" ($original.Resize $options) -}}
+{{ else if eq $command "Fill" -}}
+{{ .Scratch.Set "image" ($original.Fill $options) -}}
+{{ else if eq $command "Crop" -}}
+{{ .Scratch.Set "image" ($original.Crop $options) -}}
+{{ else -}}
+{{ errorf "Invalid image processing command %q: must be one of Fit, Fill, Crop or Resize." $command -}}
+{{ end -}}
 {{ $image := .Scratch.Get "image" }}
 <figure class="card rounded p-2 td-post-card mb-4 mt-4" style="max-width: {{ add $image.Width 10 }}px">
 	<img class="card-img-top" src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">

layouts/shortcodes/tab.html

@@ -1,8 +1,11 @@
 {{- /* Make sure that we are enclosed within a tabpane shortcode block */ -}}
+
 {{ with $.Parent -}}
-{{ if ne $.Parent.Name "tabpane" -}}
-    {{ errorf "shortcode 'tab' must be used within a 'tabpane' block" -}}
+  {{ if ne $.Parent.Name "tabpane" -}}
+    {{ errorf "Found shortcode %q enclosed inside a %q block, must be enclosed inside a %q block. Error position: %s" $.Name $.Parent.Name "tabpane" $.Position  -}}
   {{ end -}}
+{{ else -}}
+  {{ errorf "shortcode %q must be enclosed inside a %q block, but no parent block was found. Error position: %s" $.Name "tabpane" $.Position  -}}
 {{ end -}}
 
 {{ $header := "Tab" -}}
@@ -23,19 +26,19 @@
 {{ end -}}
 {{ with $.Get "text" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-  {{ errorf "shortcode tab: parameter 'text' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position  -}}
   {{ end -}}
   {{ $tab = merge $tab (dict "text" ($.Get "text")) -}}
 {{ end -}}
 {{ with $.Get "right" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-  {{ errorf "shortcode tab: parameter 'right' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position  -}}
   {{ end -}}
   {{ $tab = merge $tab (dict "rightpush" ($.Get "right")) -}}
 {{ end -}}
 {{ with $.Get "disabled" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-  {{ errorf "shortcode tab: parameter 'disabled' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "disabled" (printf "%T" .) $.Position  -}}
   {{ end -}}
   {{ $tab = merge $tab (dict "disabled" ($.Get "disabled")) -}}
 {{ end -}}

layouts/shortcodes/tabpane.html

@@ -1,25 +1,25 @@
 {{/* Check parameter types */ -}}
 {{ with .Get "langEqualsHeader" -}}
-  {{ if ne ( printf "%T" . ) "bool" -}}
-    {{ errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}}
+  {{ if ne ( printf "%T" . )  "bool" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "langEqualsHeader" (printf "%T" .) $.Position  -}}
   {{ end -}}
 {{ end -}}
 
 {{ with .Get "text" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-    {{ errorf "shortcode tabpane: parameter 'text' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position  -}}
   {{ end -}}
 {{ end -}}
 
 {{ with .Get "persistLang" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-    {{ errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "persistLang" (printf "%T" .) $.Position  -}}
   {{ end -}}
 {{ end -}}
 
 {{ with .Get "right" -}}
   {{ if ne ( printf "%T" . ) "bool" -}}
-    {{ errorf "shortcode tabpane: parameter 'right' must be either true or false" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position  -}}
   {{ end -}}
 {{ end -}}
 
@@ -101,7 +101,7 @@
 </ul>
 
 {{ if $duplicate -}}
-  {{ warnf "Tabpane on page '%s': duplicate language '%s' detected, disabling persistance of language to avoid multiple tab display." .Page.RelPermalink $duplicateLang  -}}
+  {{ warnf "Shortcode %q: duplicate language %q detected, disabling persistance of language to avoid multiple tab display. Position: %s" $.Name $duplicateLang $.Position -}}
 {{ end -}}
 {{ $duplicate = false -}}
 {{ $langs = slice -}}

userguide/content/en/docs/adding-content/shortcodes/index.md

@@ -428,7 +428,7 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome!
 Tabbed panes are implemented using two shortcodes:
 
 * The `tabpane` shortcode, which is the container element for the tabs. This shortcode can hold the optional named parameters `lang`, `highlight` and `right`. The value of the optional parameters `lang` and `highlight` are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code blocks of the individual tabs. Specify `right=true` if you want to right align your tabs. In case the header text of the tab equals the language used in the tab's code block (as in the first tabbed pane example above), you may specify `langEqualsHeader=true` in the surrounding `tabpane` shortcode. Then, the header text of the individual tab is automatically set as `lang` parameter of the respective tab.
-* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{{< tab "My header" >}} … {{< /tab >}}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation:
+* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{{</* tab "My header" */>}} … {{</* /tab */>}}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation:
   * By default, the tab's content is rendered as `code block`. In order to get proper syntax highlighting, specify the named parameter `lang` --and optionally the parameter `highlight`-- for each tab. Parameters set in the parent `tabpane` shortcode will be overwritten.
   * If the contents of your tabs should be rendered as text with different styles and with optional images, specify `text=true` as parameter of your `tabpane` (or your `tab`). If your content is markdown, use the percent sign `%` as outermost delimiter of your `tab` shortcode, your markup should look like `{{%/* tab */%}}Your **markdown** content{{%/* /tab */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{</* tab */>}}Your <b>HTML</b> content{{</* /tab */>}}`.