google · chalin · Jun 12, 2025 · Jun 11, 2025 · Jun 11, 2025 · Jun 11, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -26,8 +26,16 @@ For the full list of changes, see the [0.x.y] release notes.
 
 **Breaking changes**:
 
+- **Shortcodes**:
+  - The alert shortcode has been reworked to address [#906] and [#939]. It can
+    now be used with Markdown content, and it can contain calls to other
+    shortcodes. For details, see [Shortcode helpers > alert][] ([#941])
 - ...
 
+[#941]: https://github.com/google/docsy/pull/941
+[Shortcode helpers > alert]:
+  https://www.docsy.dev/docs/adding-content/shortcodes/#alert
+
 **New**:
 
 **Other changes**:

diff --git a/assets/scss/_alerts.scss b/assets/scss/_alerts.scss
@@ -5,12 +5,15 @@
   color: inherit;
   border-radius: 0;
 
+  :last-child {
+    margin-bottom: 0;
+  }
+
   @each $color, $value in $theme-colors {
     &-#{$color} {
       & .alert-heading {
         color: $value;
       }
-
       border-style: solid;
       border-color: $value;
       border-width: 0 0 0 4px;

diff --git a/layouts/_shortcodes/alert.html b/layouts/_shortcodes/alert.html
@@ -1,10 +1,30 @@
-{{ $_hugo_config := `{ "version": 1 }` }}
-{{ $color := .Get "color" | default "primary" }}
+{{/*
+
+@param {string} [title=""] HTML rendered as a Bootstrap alert heading.
+@param {string} [color="primary"] Suffix used for the Bootstrap alert class
+                `alert-{color}`.
+
+For details, see https://www.docsy.dev/docs/adding-content/shortcodes/#alert.
+
+*/ -}}
+
+{{ $color := .Get "color" | default "primary" -}}
+
 <div class="alert alert-{{ $color }}" role="alert">
-{{ with .Get "title" }}<h4 class="alert-heading">{{ . | safeHTML }}</h4>{{ end }}
-{{ if eq .Page.File.Ext "md" }}
-    {{ .Inner | markdownify }}
-{{ else }}
-    {{ .Inner | htmlUnescape | safeHTML }}
-{{ end }}
+{{- with .Get "title" -}}
+  <div class="h4 alert-heading" role="heading">
+    {{- . | safeHTML -}}
+  </div>
+{{- end }}
+
+{{/* Do NOT remove the blank line above. It ends the previous HTML block and
+ensures that any Markdown in .Inner will be treated as Markdown. For details,
+see https://spec.commonmark.org/0.31.2/#html-blocks, 7. */ -}}
+
+{{ .Inner }}
+
+{{- /* Do NOT remove this space trimming comment. It ensures that any Markdown
+that _follows_ this shortcode remains correctly indented, in contexts where this
+is necessary. */ -}}
+
 </div>
diff --git a/userguide/content/en/docs/adding-content/content.md b/userguide/content/en/docs/adding-content/content.md
@@ -1,8 +1,8 @@
 ---
 title: Adding Content
 weight: 1
-description: >
-  Add different types of content to your Docsy site.
+description: Add different types of content to your Docsy site.
+cSpell:ignore: goldmark Riona MacNamara
 ---
 
 So you've got a new Hugo website with Docsy, now it's time to add some content!
@@ -311,9 +311,7 @@ By default you create pages in a Docsy site as simple
 [Goldmark](https://github.com/yuin/goldmark/) is the only Markdown parser
 supported by Hugo.
 
-<div class="alert alert-primary" role="alert">
-
-<h4 class="alert-heading">Tip</h4>
+{{% alert title="Tip" %}}
 
 If you've been using versions of Hugo before 0.60 that use
 [`BlackFriday`](https://github.com/russross/blackfriday) as its Markdown parser,
@@ -351,7 +349,7 @@ markup:
 {{< /tabpane >}}
 <!-- prettier-ignore-end -->
 
-</div>
+{{% /alert %}}
 
 In addition to your marked-up text, you can also use Hugo and Docsy's
 [shortcodes](/docs/adding-content/shortcodes): reusable chunks of HTML that you
@@ -852,9 +850,7 @@ disableKinds: [RSS]
 {{< /tabpane >}}
 <!-- prettier-ignore-end -->
 
-<div class="alert alert-info" role="alert">
-
-<h4 class="alert-heading">Note</h4>
+{{% alert title=Note color=info %}}
 
 If you have enabled our [print feature](/docs/adding-content/print/) or
 otherwise specified section-level output formats in
@@ -892,7 +888,8 @@ outputs:
 {{< /tab >}}
 {{< /tabpane >}}
 <!-- prettier-ignore-end -->
-</div>
+
+{{% /alert %}}
 
 ## Sitemap
 

diff --git a/userguide/content/en/docs/adding-content/feedback.md b/userguide/content/en/docs/adding-content/feedback.md
@@ -35,7 +35,7 @@ configuration file. For details, see [Configure Google Analytics][].
 
 {{% alert title="Deprecation note and warning" color="warning" %}}
 
-  <!-- Remove this warning once the Hugo docs have been updated to include it. -->
+<!-- Remove this warning once the Hugo docs have been updated to include it. -->
 
 While you can configure your project's analytics ID by setting either the
 top-level `googleAnalytics` config parameter or `services.googleAnalytics.id`,

diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md
@@ -3,12 +3,14 @@ title: Docsy Shortcodes
 linkTitle: Shortcodes
 date: 2017-01-05
 weight: 5
-description: >
-  Use Docsy's Hugo shortcodes to quickly build site pages.
+description: Use Docsy's Hugo shortcodes to quickly build site pages.
 resources:
   - src: '**spruce*.jpg'
     params:
       byline: '*Photo*: Bjørn Erik Pedersen / CC-BY-SA'
+params:
+  message: Some _message_.
+cSpell:ignore: imgproc pageinfo Bjørn Pedersen
 ---
 
 Rather than writing all your site pages from scratch, Hugo lets you define and
@@ -172,22 +174,74 @@ section. It's meant to be used in combination with the other blocks shortcodes.
 
 ### alert
 
-The **alert** shortcode creates an alert block that can be used to display
-notices or warnings.
+Use the **alert** shortcode to display notices and warnings. The shortcode
+renders a [Bootstrap alert component][bs-alert]. It can be used with Markdown
+content and contain other shortcodes. For example:
 
-```go-html-template
-{{%/* alert title="Warning" color="warning" */%}}
-This is a warning.
-{{%/* /alert */%}}
+```go-template
+{{%/* alert title="Welcome" */%}} **Hello**, world! {{%/* /alert */%}}
 ```
 
-Renders to:
+Renders as:
 
-{{% alert title="Warning" color="warning" %}} This is a warning. {{% /alert %}}
+{{% alert title="Welcome" %}} **Hello**, world! {{% /alert %}}
 
-| Parameter | Default | Description                                                   |
-| --------- | ------- | ------------------------------------------------------------- |
-| color     | primary | One of the theme colors, eg `primary`, `info`, `warning` etc. |
+Parameters:
+
+- `title` (optional): Use this to specify a title for your alert. The title
+  renders as a Bootstrap [alert heading][bs-alert], at heading level 4, using
+  the `h4` Bootstrap class over a `<div>` element. This prevents the title from
+  appearing in a page's table of contents.
+- `color` (optional): Use this parameter to specify one of Bootstrap's
+  predefined [alert variants][bs-alert], each of which has their own color.
+  These include `primary`, `info`, and `warning`.
+
+#### Alerts and indentation
+
+When the `alert` shortcode is used in a Markdown context that requires
+indentation, such as a list, then the alert _content_ (whether specified as
+text/Markdown or a shortcode) must be indented accordingly. For example:
+
+```go-template
+- The following note is part of this list item:
+  {{%/* alert title="Celebrate!" color=success */%}}
+  This alert content is properly rendered.
+
+  > {{%/* param message */%}}
+  {{%/* /alert */%}}
+  The first list item continues.
+
+- **Don't put content on the same line** as the opening tag, it breaks rendering:
+  {{%/* alert title="Misformed alert!" color=warning */%}} **This content appears outside of
+  the list!** {{%/* /alert */%}}
+```
+
+This renders as:
+
+{{< comment >}}
+
+<!--
+IMPORTANT: the following lone opening div tag prevents the mis-formatted alert example below from breaking all the rest of the page. DO NOT remove it.
+-->
+
+{{< /comment >}}
+
+<div class="td-max-width-on-larger-screens">
+
+<!-- prettier-ignore -->
+- The following note is part of this list item:
+  {{% alert title="Celebrate!" color=success %}}
+  This alert content is properly rendered.
+
+  > {{% param message %}}
+  {{% /alert %}}
+  The first list item continues.
+
+- **Don't put content on the same line** as the opening tag, it breaks rendering:
+  {{% alert title="Misformed alert!" color=warning %}} **This alert content appears outside of
+  the list!** {{% /alert %}}
+
+[bs-alert]: https://getbootstrap.com/docs/5.3/components/alerts/
 
 ### pageinfo
 
@@ -196,7 +250,7 @@ information for a page: for example, letting users know that the page contains
 placeholder content, that the content is deprecated, or that it documents a beta
 feature.
 
-```go-html-template
+```go-template
 {{%/* pageinfo color="info" */%}}
 This is placeholder content.
 {{%/* /pageinfo */%}}
@@ -220,7 +274,7 @@ The **imgproc** shortcode finds an image in the current
 [Page Bundle](/docs/adding-content/content/#page-bundles) and scales it given a
 set of processing instructions.
 
-```go-html-template
+```go-template
 {{%/* imgproc spruce Fill "400x450" */%}}
 Norway Spruce *Picea abies* shoot with foliage buds.
 {{%/* /imgproc */%}}

diff --git a/userguide/content/en/docs/get-started/other-options.md b/userguide/content/en/docs/get-started/other-options.md
@@ -181,9 +181,12 @@ your project's root directory:
     echo 'theme: docsy' >> hugo.yaml
     ```
 
-    {{% alert title="Tip" %}}As of Hugo 0.110.0, the default config base
+    {{% alert title="Tip" %}}
+
+    As of Hugo 0.110.0, the default config base
     filename was changed to `hugo.*` from `config.*`. If you are using hugo
     0.110 or above, consider renaming your `config.*` to `hugo.*`.
+
     {{% /alert %}}
 
 3.  Get Docsy dependencies:
@@ -270,15 +273,21 @@ You can use Docsy as an NPM module as follows:
     npm install --save-dev google/docsy#semver:{{% param version %}} --omit=peer
     ```
 
-    {{% alert title="Hugo-module compatibility" color="warning" %}} Installing
+    {{% alert title="Hugo-module compatibility" color="warning" %}}
+
+    Installing
     Docsy using NPM creates an empty `github.com` sibling folder. For details,
-    see [Docsy NPM install side-effect](#docsy-npm-install-side-effect). {{%
-    /alert %}}
+    see [Docsy NPM install side-effect](#docsy-npm-install-side-effect).
+
+    {{% /alert %}}
 
-    {{% alert title="Hugo install tip" color="info" %}} You can install Docsy's
+    {{% alert title="Hugo install tip" %}}
+
+    You can install Docsy's
     officially supported version of [Hugo using NPM](#hugo-extended-npm) at the
-    same time as Docsy. Just omit the `--omit` flag from the command above. {{%
-    /alert %}}
+    same time as Docsy. Just omit the `--omit` flag from the command above.
+
+    {{% /alert %}}
 
 3.  Build or serve your new site using the usual Hugo commands, specifying the
     path to the Docsy theme files. For example, build your site as follows:
@@ -291,21 +300,21 @@ You can use Docsy as an NPM module as follows:
 
     {{% alert title="Error: failed to load modules" color="warning" %}}
 
-If Hugo reports the following error when building your site ([#2116]):
+    If Hugo reports the following error when building your site ([#2116]):
 
-```
-Error: failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found in ".../myproject/node_modules/github.com/FortAwesome/Font-Awesome" ...
-```
+    ```
+    Error: failed to load modules: module "github.com/FortAwesome/Font-Awesome" not found in ".../myproject/node_modules/github.com/FortAwesome/Font-Awesome" ...
+    ```
 
-Then run the following command and try again:
+    Then run the following command and try again:
 
-```sh
-npm rebuild
-```
+    ```sh
+    npm rebuild
+    ```
 
-[#2116]: https://github.com/google/docsy/issues/2116
+    [#2116]: https://github.com/google/docsy/issues/2116
 
-{{% /alert %}}
+    {{% /alert %}}
 
 As an alternative to specifying a `themesDir`, on some platforms, you can
 instead create a symbolic link to the Docsy theme directory as follows (Linux

diff --git a/userguide/static/refcache.json b/userguide/static/refcache.json
@@ -411,6 +411,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-11-06T12:03:46.341081-05:00"
   },
+  "https://getbootstrap.com/docs/5.3/components/alerts/": {
+    "StatusCode": 206,
+    "LastSeen": "2025-06-10T21:33:38.654894-04:00"
+  },
   "https://getbootstrap.com/docs/5.3/content/tables/": {
     "StatusCode": 206,
     "LastSeen": "2025-05-16T09:20:45.464085-04:00"
@@ -1119,6 +1123,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-05-22T19:21:14.104646-04:00"
   },
+  "https://github.com/google/docsy/pull/941": {
+    "StatusCode": 206,
+    "LastSeen": "2025-06-10T18:59:25.465236-04:00"
+  },
   "https://github.com/google/docsy/pulls": {
     "StatusCode": 200,
     "LastSeen": "2024-11-06T12:03:15.642661-05:00"
@@ -2355,6 +2363,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-11-06T12:06:43.680938-05:00"
   },
+  "https://www.docsy.dev/docs/adding-content/shortcodes/#alert": {
+    "StatusCode": 206,
+    "LastSeen": "2025-06-10T21:43:28.870112-04:00"
+  },
   "https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature": {
     "StatusCode": 206,
     "LastSeen": "2024-11-06T12:05:17.284993-05:00"