10 files changed, 187 insertions, 25 deletions
diff --git a/site/layouts/shortcodes/added-in.html b/site/layouts/shortcodes/added-in.html
new file mode 100644
index 000000000..abd8dc4f3
--- /dev/null
+++ b/site/layouts/shortcodes/added-in.html
@@ -0,0 +1,5 @@
+{{- /* Outputs badge to identify the first version something was added */ -}}
+
+{{- $version := .Get 0 -}}
+
+<small class="d-inline-flex mb-3 px-2 py-1 fw-semibold text-success-emphasis bg-success-subtle border border-success-subtle rounded-2">Added in v{{ $version }}</small>
diff --git a/site/layouts/shortcodes/bs-table.html b/site/layouts/shortcodes/bs-table.html
index 42a18d578..9eec109cb 100644
--- a/site/layouts/shortcodes/bs-table.html
+++ b/site/layouts/shortcodes/bs-table.html
@@ -4,5 +4,6 @@
 
 {{- $css_class := .Get 0 | default "table" -}}
 {{- $html_table := .Inner | markdownify -}}
-{{- $html_table = replace $html_table "<table>" (printf `<table class="%s">` $css_class) -}}
+{{- $html_table = replace $html_table "<table>" (printf `<div class="table-responsive"><table class="%s">` $css_class) -}}
+{{- $html_table = replace $html_table "</table>" "</table></div>" -}}
 {{- $html_table | safeHTML -}}
diff --git a/site/layouts/shortcodes/callout-deprecated-dark-variants.html b/site/layouts/shortcodes/callout-deprecated-dark-variants.html
new file mode 100644
index 000000000..e682a7fbe
--- /dev/null
+++ b/site/layouts/shortcodes/callout-deprecated-dark-variants.html
@@ -0,0 +1,9 @@
+{{- /* Outputs message about dark mode component variants being deprecated in v5.3. */ -}}
+
+{{- $component := .Get 0 -}}
+
+<div class="bd-callout bd-callout-warning">
+  <p>
+    <strong>Heads up!</strong> Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of adding <code>.{{ $component }}-dark</code>, set <code>data-bs-theme="dark"</code> on the root element, a parent wrapper, or the component itself.
+  </p>
+</div>
diff --git a/site/layouts/shortcodes/deprecated-in.html b/site/layouts/shortcodes/deprecated-in.html
new file mode 100644
index 000000000..b353368df
--- /dev/null
+++ b/site/layouts/shortcodes/deprecated-in.html
@@ -0,0 +1,5 @@
+{{- /* Outputs badge to identify the version something was deprecated */ -}}
+
+{{- $version := .Get 0 -}}
+
+<small class="d-inline-flex mb-3 px-2 py-1 fw-semibold text-warning-emphasis bg-warning-subtle border border-warning-subtle rounded-2">Deprecated in v{{ $version }}</small>
diff --git a/site/layouts/shortcodes/docsref.html b/site/layouts/shortcodes/docsref.html
index 2379de2b1..06523d859 100644
--- a/site/layouts/shortcodes/docsref.html
+++ b/site/layouts/shortcodes/docsref.html
@@ -1 +1,2 @@
-{{- relref . ((path.Join "docs" $.Site.Params.docs_version (.Get 0)) | relURL) -}}
+{{- $pageToReference := path.Join "docs" $.Site.Params.docs_version (.Get 0) -}}
+{{- relref . $pageToReference | relURL -}}
diff --git a/site/layouts/shortcodes/example.html b/site/layouts/shortcodes/example.html
index 0592adc6b..5b398e681 100644
--- a/site/layouts/shortcodes/example.html
+++ b/site/layouts/shortcodes/example.html
@@ -4,25 +4,46 @@
   `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`
+    * lang: language used to display the code - default: "html"
     * show_markup: if the markup should be output in the HTML - default: `true`
+    * show_preview: if the preview should be output in the HTML - default: `true`
+    * stackblitz_add_js: if extra JS snippet should be added to StackBlitz - default: `false`
 */ -}}
 
 {{- $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 -}}
+{{- $show_preview := .Get "show_preview" | default true -}}
+{{- $stackblitz_add_js := .Get "stackblitz_add_js" | default false -}}
 
-{{- if eq $show_preview true -}}
-<div{{ with $id }} id="{{ . }}"{{ end }} class="bd-example{{ with $class }} {{ . }}{{ end }}">
-  {{- $input -}}
-</div>
-{{- end -}}
+{{- $content := .Inner -}}
+
+<div class="bd-example-snippet bd-code-snippet">
+  {{- if eq $show_preview true }}
+  <div{{ with $id }} id="{{ . }}"{{ end }} class="bd-example m-0 border-0{{ with $class }} {{ . }}{{ end }}">
+    {{ $content }}
+  </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 ` (class=" *?")` "" $content -}}
-  {{- highlight (trim $content "\n") $lang "" -}}
-{{- end -}}
+  {{- if eq $show_markup true -}}
+    {{- if eq $show_preview true -}}
+      <div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-0 border-top border-bottom">
+        <small class="font-monospace text-body-secondary text-uppercase">{{ $lang }}</small>
+        <div class="d-flex ms-auto">
+          <button type="button" class="btn-edit text-nowrap"{{ with $stackblitz_add_js }} data-sb-js-snippet="{{ $stackblitz_add_js }}"{{ end }} title="Try it on StackBlitz">
+            <svg class="bi" aria-hidden="true"><use xlink:href="#lightning-charge-fill"/></svg>
+          </button>
+          <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+            <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg>
+          </button>
+        </div>
+      </div>
+    {{- end -}}
+
+    {{- $content = replaceRE `<svg class="bd-placeholder-img(?:-lg)?(?: *?bd-placeholder-img-lg)? ?(.*?)".*?<\/svg>` `<img src="..." class="$1" alt="...">` $content -}}
+    {{- $content = replaceRE `<img class="bd-placeholder-img(?:-lg)?(?: *?bd-placeholder-img-lg)? ?(.*?)".*?>` `<img src="..." class="$1" alt="...">` $content -}}
+    {{- $content = replaceRE ` (class=" *?")` "" $content -}}
+    {{- highlight (trim $content "\n") $lang "" -}}
+  {{- end }}
+</div>
diff --git a/site/layouts/shortcodes/js-dismiss.html b/site/layouts/shortcodes/js-dismiss.html
index 45d72d0eb..3d0c27883 100644
--- a/site/layouts/shortcodes/js-dismiss.html
+++ b/site/layouts/shortcodes/js-dismiss.html
@@ -2,13 +2,13 @@
 
 {{- $name := .Get 0 -}}
 
-Dismissal can be achieved with the `data` attribute on a button **within the {{ $name }}** as demonstrated below:
+Dismissal can be achieved with the `data-bs-dismiss` attribute on a button **within the {{ $name }}** as demonstrated below:
 
 ```html
 <button type="button" class="btn-close" data-bs-dismiss="{{ $name }}" aria-label="Close"></button>
 ```
 
-or on a button **outside the {{ $name }}** using the `data-bs-target` as demonstrated below:
+or on a button **outside the {{ $name }}** using the additional `data-bs-target` as demonstrated below:
 
 ```html
 <button type="button" class="btn-close" data-bs-dismiss="{{ $name }}" data-bs-target="#my-{{ $name }}" aria-label="Close"></button>
diff --git a/site/layouts/shortcodes/js-docs.html b/site/layouts/shortcodes/js-docs.html
new file mode 100644
index 000000000..8eed4a0eb
--- /dev/null
+++ b/site/layouts/shortcodes/js-docs.html
@@ -0,0 +1,70 @@
+{{- /*
+  Usage: `js-docs name="name" file="file/_location.js`
+
+  Prints everything between `// js-docs-start "name"` and `// js-docs-end "name"`
+  comments in the docs.
+*/ -}}
+
+{{- $name := .Get "name" -}}
+{{- $file := .Get "file" -}}
+
+{{- /* 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 "// js-docs-start %s\n" $name -}}
+  {{- $capture_end := printf "// js-docs-end %s\n" $name -}}
+  {{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}}
+  {{- $regex_nested := printf `// js-docs-.*\n` -}}
+
+  {{- $match := findRE $regex (readFile $file) -}}
+  {{- $match = index $match 0 -}}
+
+  {{- if not $match -}}
+    {{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}}
+  {{- end -}}
+
+  {{- $match = replace $match $capture_start "" -}}
+  {{- $match = replace $match $capture_end "" -}}
+
+  {{- $match_nested := findRE $regex_nested $match -}}
+  {{- range $to_remove := $match_nested -}}
+    {{- $match = replace $match $to_remove "" -}}
+  {{- end -}}
+
+  <div class="bd-example-snippet bd-code-snippet bd-file-ref">
+    <div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
+      <a class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small" href="{{ .Site.Params.repo }}/blob/v{{ .Site.Params.current_version }}/{{ $file | replaceRE `\\` "/" }}">
+        {{- $file -}}
+      </a>
+      <div class="d-flex ms-auto">
+        <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+          <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg>
+        </button>
+      </div>
+    </div>
+
+    {{- $unindent := 0 -}}
+    {{- $found := false -}}
+    {{- $first_line:= index (split $match "\n") 0 -}}
+    {{- range $char := split $first_line "" -}}
+      {{- if and (eq $char " ") (not $found) -}}
+        {{- $unindent = add $unindent 1 -}}
+      {{- else -}}
+        {{- $found = true -}}
+      {{- end -}}
+    {{- end -}}
+    {{- $output := "" -}}
+    {{- if (gt $unindent 0) -}}
+      {{- $prefix := (strings.Repeat $unindent " ") -}}
+      {{- range $line := split $match "\n" -}}
+        {{- $line = strings.TrimPrefix $prefix $line -}}
+        {{ $output = printf "%s%s\n" $output $line }}
+      {{- end -}}
+      {{- $output = chomp $output -}}
+    {{- else -}}
+      {{- $output = $match -}}
+    {{- end -}}
+    {{- highlight $output "js" "" -}}
+  </div>
+{{- end -}}
diff --git a/site/layouts/shortcodes/placeholder.html b/site/layouts/shortcodes/placeholder.html
index c267bf4a7..9cc639435 100644
--- a/site/layouts/shortcodes/placeholder.html
+++ b/site/layouts/shortcodes/placeholder.html
@@ -4,11 +4,12 @@
   `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"
+    * class: Class to add to the `svg` or `img` - default: "bd-placeholder-img"
     * color: The text color (foreground) - default: "#dee2e6"
     * background: The background color - default: "#868e96"
     * width: default: "100%"
     * height: default: "180px"
+    * markup: If it should render `svg` or `img` tags - default: "svg"
 */ -}}
 
 {{- $grays := $.Site.Data.grays -}}
@@ -26,8 +27,18 @@
 {{- $show_title := not (eq $title "false") -}}
 {{- $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 -}}
-  <rect width="100%" height="100%" fill="{{ $background }}"/>
-  {{- if $show_text }}<text x="50%" y="50%" fill="{{ $color }}" dy=".3em">{{ $text }}</text>{{ end -}}
-</svg>
+{{- $markup := .Get "markup" | default "svg" -}}
+
+{{- if eq $markup "img" -}}
+  <img class="bd-placeholder-img{{ with $class }} {{ . }}{{ end }}" alt="{{ $title }} : {{ $text }}" width="{{ $width }}" height="{{ $height }}" src="data:image/svg+xml,%3Csvg%20style='font-size:%201.125rem;%20font-family:system-ui,-apple-system,%22Segoe%20UI%22,Roboto,%22Helvetica%20Neue%22,%22Noto%20Sans%22,%22Liberation%20Sans%22,Arial,sans-serif,%22Apple%20Color%20Emoji%22,%22Segoe%20UI%20Emoji%22,%22Segoe%20UI%20Symbol%22,%22Noto%20Color%20Emoji%22;%20-webkit-user-select:%20none;%20-moz-user-select:%20none;%20user-select:%20none;%20text-anchor:%20middle;'%20width='200'%20height='200'%20xmlns='http://www.w3.org/2000/svg'%3E
+      {{- if $show_title }}%3Ctitle%3E{{ $title }}%3C/title%3E{{ end -}}
+      %3Crect%20width='100%25'%20height='100%25'%20fill='{{ replace $background "#" "%23" }}'%3E%3C/rect%3E
+      {{- if $show_text }}%3Ctext%20x='50%25'%20y='50%25'%20fill='{{ replace $color "#" "%23" }}'%20dy='.3em'%3E{{ $text }}%3C/text%3E{{ end -}}
+    %3C/svg%3E">
+{{- else -}}
+  <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">
+    {{- 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 -}}
+  </svg>
+{{- end -}}
diff --git a/site/layouts/shortcodes/scss-docs.html b/site/layouts/shortcodes/scss-docs.html
index 3d1cd09a5..6e7c129f4 100644
--- a/site/layouts/shortcodes/scss-docs.html
+++ b/site/layouts/shortcodes/scss-docs.html
@@ -17,8 +17,9 @@
   {{- 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 -}}
+  {{- $capture_end := printf "// scss-docs-end %s\n" $name -}}
   {{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}}
+  {{- $regex_nested := printf `// scss-docs-.*\n` -}}
 
   {{- /*
     TODO: figure out why we can't do the following and get the first group (the only capturing one)...
@@ -35,9 +36,47 @@
   {{- $match = replace $match $capture_start "" -}}
   {{- $match = replace $match $capture_end "" -}}
 
+  {{- $match_nested := findRE $regex_nested $match -}}
+  {{- range $to_remove := $match_nested -}}
+    {{- $match = replace $match $to_remove "" -}}
+  {{- end -}}
+
   {{- if (ne $strip_default "false") -}}
     {{- $match = replace $match " !default" "" -}}
   {{- end -}}
 
-  {{- highlight $match "scss" "" -}}
+  <div class="bd-example-snippet bd-code-snippet bd-file-ref">
+    <div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
+      <a class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small" href="{{ .Site.Params.repo }}/blob/v{{ .Site.Params.current_version }}/{{ $file | replaceRE `\\` "/" }}">
+        {{- $file -}}
+      </a>
+      <div class="d-flex ms-auto">
+        <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+          <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg>
+        </button>
+      </div>
+    </div>
+    {{- $unindent := 0 -}}
+    {{- $found := false -}}
+    {{- $first_line:= index (split $match "\n") 0 -}}
+    {{- range $char := split $first_line "" -}}
+      {{- if and (eq $char " ") (not $found) -}}
+        {{- $unindent = add $unindent 1 -}}
+      {{- else -}}
+        {{- $found = true -}}
+      {{- end -}}
+    {{- end -}}
+    {{- $output := "" -}}
+    {{- if (gt $unindent 0) -}}
+      {{- $prefix := (strings.Repeat $unindent " ") -}}
+      {{- range $line := split $match "\n" -}}
+        {{- $line = strings.TrimPrefix $prefix $line -}}
+        {{ $output = printf "%s%s\n" $output $line }}
+      {{- end -}}
+      {{- $output = chomp $output -}}
+    {{- else -}}
+      {{- $output = $match -}}
+    {{- end -}}
+    {{- highlight $output "scss" "" -}}
+  </div>
 {{- end -}}