docs: shortcodes tweaks and consistency changes

site/content/docs/5.1/content/tables.md

@@ -559,7 +559,7 @@ A `<caption>` functions like a heading for a table. It helps users with screen r
 <div class="bd-example">
   <table class="table">
     <caption>List of users</caption>
-    {{< partial "table-content.html" >}}
+    {{< partial "table-content" >}}
   </table>
 </div>
 

site/content/docs/5.1/forms/validation.md

@@ -103,7 +103,7 @@ Custom feedback styles apply custom colors, borders, focus styles, and backgroun
 
 {{< example lang="js" show_preview="false" >}}
 {{< js.inline >}}
-{{- readFile (printf "site/static/docs/%s/assets/js/validate-forms.js" .Site.Params.docs_version) -}}
+{{- readFile (path.Join "site/static/docs" .Site.Params.docs_version "assets/js/validate-forms.js") -}}
 {{< /js.inline >}}
 {{< /example >}}
 

site/layouts/partials/home/masthead.html

@@ -23,6 +23,6 @@ <h1 class="mb-3">Build fast, responsive sites with Bootstrap</h1>
         </p>
       </div>
     </div>
-    {{ partial "ads.html" . }}
+    {{ partial "ads" . }}
   </div>
 </div>

site/layouts/partials/scripts.html

@@ -10,7 +10,7 @@
 
 {{- $vendor := resources.Match "js/vendor/*.js" -}}
 {{- $js := resources.Match "js/*.js" -}}
-{{- $targetDocsJSPath := printf "/docs/%s/assets/js/docs.js" .Site.Params.docs_version -}}
+{{- $targetDocsJSPath := path.Join "/docs" .Site.Params.docs_version "assets/js/docs.js" -}}
 {{- $docsJs := append $js $vendor | resources.Concat $targetDocsJSPath -}}
 
 {{- if eq hugo.Environment "production" -}}

site/layouts/partials/stylesheet.html

@@ -10,7 +10,7 @@
 {{- end }}
 
 {{- if (ne .Page.Layout "examples") }}
-{{- $targetDocsCssPath := printf "/docs/%s/assets/css/docs.css" .Site.Params.docs_version -}}
+{{- $targetDocsCssPath := path.Join "/docs" .Site.Params.docs_version "assets/css/docs.css" -}}
 {{- $sassOptions := dict "targetPath" $targetDocsCssPath "outputStyle" "expanded" "precision" 6 -}}
 {{- $postcssOptions := dict "use" "autoprefixer" "noMap" true -}}
 

site/layouts/shortcodes/bs-table.html

@@ -1,6 +1,5 @@
 {{- /*
-  Usage: `bs-table "class class-foo"`,
-  where class can be anything
+  Usage: `bs-table "class class-foo"`, where class can be any string
 */ -}}
 
 {{- $css_class := .Get 0 | default "table" -}}

site/layouts/shortcodes/callout.html

@@ -1,6 +1,5 @@
 {{- /*
-  Usage: `callout "type"`,
-  where type is one of info (default), danger, warning
+  Usage: `callout "type"`, where `type` is one of info (default), danger, or warning
 */ -}}
 
 {{- $css_class := .Get 0 | default "info" -}}

site/layouts/shortcodes/docsref.html

@@ -1 +1 @@
-{{- relref . ((printf "docs/%s%s" $.Site.Params.docs_version (.Get 0)) | relURL) -}}
+{{- relref . ((path.Join "docs" $.Site.Params.docs_version (.Get 0)) | relURL) -}}

site/layouts/shortcodes/example.html

@@ -1,26 +1,28 @@
 {{- /*
-  Usage: `example [args]`
+  Usage: `example args`
 
-  `args` are optional and can be one of the following:
-    id: the `div`'s id - default: ""
-    class: any extra class(es) to be added to the `div` - default ""
-    show_preview: if the preview should be output in the HTML - default: `true`
-    show_markup: if the markup should be output in the HTML - default: `true`
+  `args` are all optional and can be one of the following:
+    * id: the `div`'s id - default: ""
+    * class: any extra class(es) to be added to the `div` - default: ""
+    * show_preview: if the preview should be output in the HTML - default: `true`
+    * show_markup: if the markup should be output in the HTML - default: `true`
 */ -}}
 
+{{- $id := .Get "id" -}}
+{{- $class := .Get "class" -}}
 {{- $lang := .Get "lang" | default "html" -}}
 {{- $show_preview := .Get "show_preview" | default true -}}
 {{- $show_markup := .Get "show_markup" | default true -}}
 {{- $input := .Inner -}}
 
 {{- if eq $show_preview true -}}
-<div{{ with .Get "id" }} id="{{ . }}"{{ end }} class="bd-example{{ with .Get "class" }} {{ . }}{{ end }}">
+<div{{ with $id }} id="{{ . }}"{{ end }} class="bd-example{{ with $class }} {{ . }}{{ end }}">
   {{- $input -}}
 </div>
 {{- end -}}
 
 {{- if eq $show_markup true -}}
-  {{- $content := replaceRE `<svg class="bd\-placeholder\-img(?:\-lg)?(?: *?bd\-placeholder\-img\-lg)? ?(.*?)".*?<\/svg>\n` `<img src="..." class="$1" alt="...">` $input -}}
+  {{- $content := replaceRE `<svg class="bd-placeholder-img(?:-lg)?(?: *?bd-placeholder-img-lg)? ?(.*?)".*?<\/svg>\n` `<img src="..." class="$1" alt="...">` $input -}}
   {{- $content = replaceRE ` (class=" *?")` "" $content -}}
   {{- highlight (trim $content "\n") $lang "" -}}
 {{- end -}}

site/layouts/shortcodes/param.html

@@ -1,11 +1,13 @@
 {{- /*
   Work around wrong escapes in integrity attributes.
+  Original: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/shortcodes/param.html
 */ -}}
 
 {{- $name := .Get 0 -}}
 {{- with $name -}}
 {{- $value := $.Page.Param . -}}
-{{- if in $name "_hash" -}}
+{{- /* If any parameter ends with `_hash`, mark the string as safe HTML */ -}}
+{{- if (strings.HasSuffix $name "_hash") -}}
   {{- $value = $value | safeHTML -}}
 {{- end -}}
 {{- with $value }}{{ . }}{{ else }}{{ errorf "Param %q not found: %s" $name $.Position }}{{ end -}}

site/layouts/shortcodes/placeholder.html

@@ -1,21 +1,24 @@
 {{- /*
   Usage: `placeholder args`
 
-  args can be one of the following:
-    title: Used in the SVG `title` tag, default "Placeholder"
-    text: The text to show in the image - default: "width x height"
-    class: default: "bd-placeholder-img"
-    color: The text color (foreground) - default: "#dee2e6"
-    background: The background color - default: "#868e96"
-    width: default: 100%
-    height: default: 180px
+  `args` are all optional and can be one of the following:
+    * title: Used in the SVG `title` tag - default: "Placeholder"
+    * text: The text to show in the image - default: "width x height"
+    * class: Class to add to the `svg` - default: "bd-placeholder-img"
+    * color: The text color (foreground) - default: "#dee2e6"
+    * background: The background color - default: "#868e96"
+    * width: default: "100%"
+    * height: default: "180px"
 */ -}}
 
 {{- $grays := $.Site.Data.grays -}}
+{{- $default_color := (index $grays 2).hex -}}
+{{- $default_background := (index $grays 5).hex -}}
+
 {{- $title := .Get "title" | default "Placeholder" -}}
 {{- $class := .Get "class" -}}
-{{- $color := .Get "color" | default (index $grays 2).hex -}}
-{{- $background := .Get "background" | default (index $grays 5).hex -}}
+{{- $color := .Get "color" | default $default_color -}}
+{{- $background := .Get "background" | default $default_background -}}
 {{- $width := .Get "width" | default "100%" -}}
 {{- $height := .Get "height" | default "180" -}}
 {{- $text := .Get "text" | default (printf "%sx%s" $width $height) -}}
@@ -24,7 +27,7 @@
 {{- $show_text := not (eq $text "false") -}}
 
 <svg class="bd-placeholder-img{{ with $class }} {{ . }}{{ end }}" width="{{ $width }}" height="{{ $height }}" xmlns="http://www.w3.org/2000/svg"{{ if (or $show_title $show_text) }} role="img" aria-label="{{ if $show_title }}{{ $title }}{{ if $show_text }}: {{ end }}{{ end }}{{ if ($show_text) }}{{ $text }}{{ end }}"{{ else }} aria-hidden="true"{{ end }} preserveAspectRatio="xMidYMid slice" focusable="false">
-  {{- if $show_title -}}<title>{{ $title }}</title>{{- end -}}
+  {{- if $show_title }}<title>{{ $title }}</title>{{ end -}}
   <rect width="100%" height="100%" fill="{{ $background }}"/>
-  {{- if $show_text -}}<text x="50%" y="50%" fill="{{ $color }}" dy=".3em">{{ $text }}</text>{{- end -}}
+  {{- if $show_text }}<text x="50%" y="50%" fill="{{ $color }}" dy=".3em">{{ $text }}</text>{{ end -}}
 </svg>

site/layouts/shortcodes/scss-docs.html

@@ -1,33 +1,43 @@
 {{- /*
   Usage: `scss-docs name="name" file="file/_location.scss"`
 
-    Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
-    comments in the docs.
+  Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
+  comments in the docs.
 
-    Optional parameters:
-    strip-default: Remove the ` !default` flag from variable assignments - default: `true`
+  Optional parameters:
+    * strip-default: Remove the ` !default` flag from variable assignments - default: `true`
 */ -}}
 
 {{- $name := .Get "name" -}}
 {{- $file := .Get "file" -}}
 {{- $strip_default := .Get "strip-default" | default "true" -}}
 
-{{- $start := printf "// scss-docs-start %s\n" $name -}}
-{{- $end := printf "// scss-docs-end %s" $name -}}
-{{- $regex := printf "%s(.|\n)*%s" $start $end -}}
+{{- /* If any parameters are missing, print an error and exit */ -}}
+{{- if or (not $name) (not $file) -}}
+  {{- errorf "%s: %q: Missing required parameters! Got: name=%q file=%q!" .Position .Name $name $file -}}
+{{- else -}}
+  {{- $capture_start := printf "// scss-docs-start %s\n" $name -}}
+  {{- $capture_end := printf "// scss-docs-end %s" $name -}}
+  {{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}}
 
-{{- $css := readFile $file -}}
-{{- $match := findRE $regex $css 1 -}}
+  {{- /*
+    TODO: figure out why we can't do the following and get the first group (the only capturing one)...
+    $regex := printf `(?:// scss-docs-start %s\n)((?:.|\n)*)(?:\n// scss-docs-end %s)` $name $name
+  */ -}}
 
-{{- if (eq (len $match) 0) -}}
-  {{- errorf "Got no matches for %q in %q! (called in %q)" $name $file $.Page.Path -}}
-{{- end -}}
+  {{- $match := findRE $regex (readFile $file) -}}
+  {{- $match = index $match 0 -}}
 
-{{- $remove_start := replace (index $match 0) $start "" -}}
-{{- $result := replace $remove_start $end "" -}}
+  {{- if not $match -}}
+    {{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}}
+  {{- end -}}
 
-{{- if (ne $strip_default "false") -}}
-  {{- $result = replace $result " !default" "" -}}
-{{- end -}}
+  {{- $match = replace $match $capture_start "" -}}
+  {{- $match = replace $match $capture_end "" -}}
 
-{{- highlight $result "scss" "" -}}
+  {{- if (ne $strip_default "false") -}}
+    {{- $match = replace $match " !default" "" -}}
+  {{- end -}}
+
+  {{- highlight $match "scss" "" -}}
+{{- end -}}

site/layouts/shortcodes/table.html

@@ -2,27 +2,28 @@
   Usage: `table [args]`
 
   `args` are optional and can be one of the following:
-  class: any class(es) to be added to the `table` - default ""
-  simplified: show a simplified version in the examples - default `true`
+    * class: any class(es) to be added to the `table` - default ""
+    * simplified: show a simplified version in the examples - default `true`
 */ -}}
 
+{{- $class := .Get "class" -}}
 {{- $simplified := .Get "simplified" | default true -}}
 
 {{- $table_attributes := "" -}}
 {{- $table_content := "  ...\n" -}}
 
-{{- with .Get "class" -}}
-{{- $table_attributes = printf ` class="%s"` . -}}
+{{- with $class -}}
+  {{- $table_attributes = printf ` class="%s"` . -}}
 {{- end -}}
 
 {{- if eq $simplified "false" -}}
-{{- $table_content = partialCached "table-content" . -}}
+  {{- $table_content = partialCached "table-content" . -}}
 {{- end -}}
 
 {{- $table := printf "<table%s>\n%s</table>" $table_attributes $table_content -}}
 
 <div class="bd-example">
-  <table{{ with .Get "class" }} class="{{ . }}"{{ end }}>
+  <table{{ with $class }} class="{{ . }}"{{ end }}>
     {{ partialCached "table-content" . }}
   </table>
 </div>

site/layouts/shortcodes/year.html

@@ -1,5 +1,3 @@
-{{- /*
-  Output the current year
-*/ -}}
+{{- /* Outputs the current year */ -}}
 
 {{- now.Format "2006" -}}