Edits

Wryhder · Wryhder · commit 5ab75e2c6a5e · 2025-06-16T03:44:40.000+01:00
diff --git a/README.md b/README.md
@@ -122,50 +122,51 @@ icon:
 > [!NOTE]
 > You can highlight important information in your articles or docs using different types of callouts (also known as admonitions – or alerts, as used in [the Hugo docs](https://gohugo.io/render-hooks/blockquotes/#alerts)).
 
-For compatibility with both content and layout files, we use a mix of shortcodes and partials to display blockquote alerts. Partials work in layout, but not content files. Shortcodes work in content, but not layout files. So you'll want to call the partial in layout files but use the shortcode (it calls the partial) in content files.
+For compatibility with both content and layout files, we use a mix of shortcodes and partials to display blockquote alerts. Partials work in layout, but not content files. Shortcodes work in content, but not layout files. Use the partial in layout files, and the shortcode (which internally calls the partial) in content files.
 
 The partial is at `site/layouts/partials/blockquote-alert.html`, and the shortcode is at `site/layouts/shortcodes/blockquote-alert.html`.
 
-There are five alert types as shown in the examples below. Omit the `title` parameter to keep the alert type as the default title (for example, a note alert will have "Note" as its title). The descriptions for the alert types are borrowed from the Hugo docs:
+There are five available alert types as shown in the examples below:
 
-```
-# Shortcodes in content files
+- note
+- tip
+- important
+- warning
+- caution
+
+Omit the `title` parameter to keep the alert type as the default title (for example, a note alert will have "Note" as its title):
+
+```md
+<!-- Shortcodes in content files -->
 
 {{< blockquote-alert type="note" title="Optional custom title">}}
 Useful information that users should know, even when skimming content.
 {{< /blockquote-alert >}}
 
-----------------
-
 {{< blockquote-alert type="tip" title="Optional custom title">}}
 Helpful advice for doing things better or more easily.
 {{< /blockquote-alert >}}
 
-----------------
-
 {{< blockquote-alert type="important" title="Optional custom title">}}
 Key information users need to know to achieve their goal.
 {{< /blockquote-alert >}}
 
-----------------
-
 {{< blockquote-alert type="warning" title="Optional custom title">}}
 Urgent info that needs immediate user attention to avoid problems.
 {{< /blockquote-alert >}}
 
-----------------
-
 {{< blockquote-alert type="caution" title="Optional custom title">}}
 Advises about risks or negative outcomes.
 {{< /blockquote-alert >}}
 ```
 
-For layout files, you can call the partial as shown in the examples below. Just like in the shortcode examples, any string passed into the `content` parameter is interpreted as markdown. Use `html` instead `to pass in HTML. Again, the title parameter is optional and will default to the alert type:
+In layout files, call the partial directly. Just like shortcode content, anything passed to the  `content` parameter is parsed as Markdown. To pass raw HTML instead, use the `html` parameter. Again, the title parameter is optional and will default to the alert type:
 
-```
-# Partials in layout files
+```html
+<!-- Partials in layout files -->
+
+<!-- Anything passed via `content` is interpreted as Markdown -->
 
-{{/* These are interpreted as Markdown */}}
 {{ partial "blockquote-alert.html" (dict
     "type" "note"
     "title" "Optional custom title"
@@ -195,9 +196,28 @@ For layout files, you can call the partial as shown in the examples below. Just
     "title" "Optional custom title"
     "content" "Advises about risks or negative outcomes."
 ) }}
+```
+
+In addition to simple string content as shown above, you can also pass in complex nested content with multiple paragraphs and elements:
 
-These are also valid:
+```md
+<!-- Shortcode example with more complex content -->
 
+{{< blockquote-alert type="tip" title="Optional custom Title" >}}
+This is a tip with **bold text** and _italic_ text.
+
+This is a second paragraph in the same alert.
+
+- List item 1
+- List item 2
+{{< /blockquote-alert >}}
+```
+
+You can do similar in partials. These are all valid options. Additionally, you can assign content to a variable before passing it in, which helps with formatting in longer templates:
+
+```html
+<!-- You can wrap your markdown content in backticks if it doesn't itself contain backticks -->
+<!-- Note that indented lines could be interpreted as a preformatted code block. -->
 {{ $alertContent := `This is a tip with **bold text** and _italic_ text.
 
 This is a second paragraph in the same alert.
@@ -212,7 +232,7 @@ This is a second paragraph in the same alert.
   "content" $alertContent
 ) }}
 
-
+<!-- Concatenate multi-line strings (markdown) -->
 {{ $alertContent := add
   "This is a tip with **bold text** and _italic_ text.\n\n"
   "This is a second paragraph in the same alert.\n"
@@ -226,151 +246,33 @@ This is a second paragraph in the same alert.
   "title" "Optional custom title"
   "content" $alertContent
 ) }}
-```
-
-You can include simple string content, as shown above, or complex nested content with multiple paragraphs and HTML elements:
-
-```
-# Shortcode in content files
-
-{{< blockquote-alert type="tip" title="Optional custom Title" >}}
-This is a tip with **bold text** and _italic_ text.
-
-This is a second paragraph in the same alert.
-
-- List item 1
-- List item 2
-{{< /blockquote-alert >}}
-
-# Partial in layout files
-
-{{ partial "blockquote-alert.html" (dict
-    "type" "tip"
-    "title" "Optional custom title"
-    "content" "<p>Helpful advice for doing things better or more easily.</p>"
-) }}
 
+<!-- Pass HTML with nested elements -->
 {{ partial "blockquote-alert" (dict 
     "type" "caution" 
     "title" "Be Careful!" 
-    "content" "<p>This is a <strong>caution</strong> message.</p><p>It has multiple paragraphs.</p>"
+    "html" "<p>This is a <strong>caution</strong> message.</p><p>It has multiple paragraphs.</p>"
 ) }}
 ```
 
-```
-{{ $alertContent := `This is a tip with **bold text** and _italic_ text.
-
-This is a second paragraph in the same alert.
-            
-- List item 1
-- List item 2
-`}}
-
-
-{{ $alertContent := add
-  "This is a tip with **bold text** and _italic_ text.\n\n"
-  "This is a second paragraph in the same alert.\n"
-  "- List item 1\n"
-  "- List item 2\n\n"
-  "`Here's some text in backticks.`"
-}}
-
-**NOTE:**
 
-You'll want to handle line breaks properly within the content string in partials when working with complex content. For example, the following will throw a parse error (`html: overlay: parse failed unterminated quoted string in action`):
+> [!IMPORTANT]
+> When working with complex content, make sure to handle line breaks properly within the strings passed to the `content` or `html` parameters. For example, the following will throw a parse error (`html: overlay: parse failed unterminated quoted string in action`):
 
 ```
 {{ partial "blockquote-alert" (dict
     "type" "caution"
     "title" "Be Careful!"
-    "content" "<p>This is a <strong>caution</strong> message.</p>
+    "html" "<p>This is a <strong>caution</strong> message.</p>
     <p>It has multiple paragraphs.</p>"
 ) }}
 ```
 
-To fix this, use either of these options:
+To avoid this, you can use either of the following options:
 
 - Keep everything on a single line
 - Use string concatenation (whether in a variable or directly)
 
-```
-<!-- Option #1: Keep everything on a single line -->
-{{ partial "blockquote-alert" (dict
-    "type" "caution"
-    "title" "Be Careful!"
-    "content" "<p>This is a <strong>caution</strong> message.</p><p>It has multiple paragraphs.</p>"
-) }}
-
----------------
-<!-- Option #2: Use string concatenation (whether in a variable or directly) -->
-
-{{ $alertContent := add
-  "<p>This is a <strong>caution</strong> message.</p>"
-  "<p>It has multiple paragraphs.</p>"
-}}
-
-{{ partial "blockquote-alert.html" (dict
-  "type" "caution"
-  "title" "Be Careful!"
-  "content" $alertContent
-) }}
-
-This is a tip with **bold text** and _italic_ text.
-
-This is a second paragraph in the same alert.
-
-- List item 1
-- List item 2
-```\
-
-
--------------------------------------------------------
-You can pass Markdown through the shortcode or the partial. In fact, if you use the `content` parameter, it's assumed
-you've passed either plain text or markdown and your content is treated as such (passed through markdownify).
-To pass and have your content be treated as HTML, use the `html` parameter instead.
-
-(Looking for a cleaner, more readable way to format the content so it doesn't include so many tags)
-
-{{ $alertContent := add
-  "On **Windows**, you will see a message like:\n\n"
-  "`ZAP_<version>_windows.exe isn't commonly downloaded.`\n\n"
-  "To circumvent this warning, click **...** → **Keep** → **Show more** → **Keep anyway**.\n\n"
-  "On **macOS**, you will see a message like:\n\n"
-  "`\"ZAP.app\" cannot be opened because the developer cannot be verified.`\n\n"
-  "To circumvent this warning, go to **System Preferences** > **Security & Privacy**. "
-  "You will see a message saying that \"ZAP\" was blocked. Click **Open anyway** if you trust the installer.\n"
-}}
-
-{{ $alertContent := `
-On **Windows**, you will see a message like:
-
-`ZAP_<version>_windows.exe isn't commonly downloaded. Make sure you trust ZAP_<version>_windows.exe before you open it.`
-
-To circumvent this warning, you would need to click on **...** and then **Keep**,  
-then **Show more** and then **Keep anyway**.
-
-On **macOS**, you will see a message like:
-
-`"ZAP.app" cannot be opened because the developer cannot be verified.`
-
-To circumvent this warning, go to **System Preferences** > **Security & Privacy** at the bottom of the dialog.  
-You will see a message saying that "ZAP" was blocked. If you trust the installer, click **Open anyway**.
-` }}
-
-{{ $alertContent := add
-  "<p><strong>The ZAP releases are currently unsigned</strong></p>"
-  "<p>On <strong>Windows</strong>, you will see a message like: "
-  "<code>ZAP_&lt;version&gt;_windows.exe isn't commonly downloaded. Make sure you trust ZAP_&lt;version&gt;_windows.exe before you open it.</code><br>"
-  "To circumvent this warning, you would need to click on <strong>...</strong> and then <strong>Keep</strong>, then "
-  "<strong>Show more</strong> and then <strong>Keep anyway</strong>.</p>"
-  "<p>On <strong>macOS</strong>, you will see a message like: "
-  "<code>&quot;ZAP.app&quot; cannot be opened because the developer cannot be verified.</code><br>"
-  "To circumvent this warning, you would need to go to <strong>System Preferences</strong> &gt; <strong>Security & Privacy</strong> at "
-  "the bottom of the dialog. You will see a message saying that &quot;ZAP&quot; was blocked. Next to it, if you trust the "
-  "downloaded installer, you can click <strong>Open anyway</strong>.</p>"
-}}
--------------------------------------------------------
-
 #### Layouts
 For controlling what HTML is rendered, you need to work with the site templates. In the directory, `site/layouts/`, you'll find a number of HTML files with various template tags. The first file to check out is `site/layouts/_default/baseof.html` - this is the base layout Hugo uses to build your site that templates extend. Hugo has a lookup order for associating a content entry to a template. A single entry whose type is post (`type: post`), Hugo will look for a layout in `site/layouts/post/single.html`, and if that does not exist, it will fallback to `site/layouts/_default/single.html`. 
 
