Add support for blockquote alerts in layout files #3073
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
New Issues (1)Checkmarx found the following issues in this Pull Request
|
|
LGTM 👍 |
|
@Wryhder do you plan to update this PR? If not, ok to move it out of Draft? |
|
@psiinon It still needs some finishing touches. I should have it out of draft by next weekend. |
Wryhder
force-pushed
the
alert-template
branch
2 times, most recently
from
03a8a11 to
5ab75e2
Compare
Signed-off-by: chibbyalucard <[email protected]>
Wryhder
commented
Jun 16, 2025
Comment on lines
+9
to
+12
| {{ $type := .type | default "note" }} | ||
| {{ $title := .title | default "" }} | ||
| {{ $content := .content | default "" }} | ||
| {{ $html := .html | default "" }} |
There was a problem hiding this comment.
This got a bit more complex than I intended. I was looking for a way to pass the alert string in layout files without having to write so many HTML tags as in this example (while ensuring Markdown and HTML still got parsed correctly whether coming from the partial or shortcode):
(sample conversion from download.html)
{{ $alertContent := add
"<p>On <strong>Windows</strong>, you will see a message like: "
"<code>ZAP_<version>_windows.exe isn't commonly downloaded. Make sure you trust ZAP_<version>_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>"ZAP.app" 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> > <strong>Security & Privacy</strong> at "
"the bottom of the dialog. You will see a message saying that "ZAP" was blocked. Next to it, if you trust the "
"downloaded installer, you can click <strong>Open anyway</strong>.</p>"
}}
{{ partial "blockquote-alert.html" (dict
"type" "warning"
"html" $alertContent
) }}
I ended up creating two separate content parameters for the partial. html for HTML and content for markdown (this is also the parameter used for the shortcode).
| @@ -122,24 +122,156 @@ 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)). | |||
|
|
|||
| The examples below use the same syntax as in Github Markdown. The template responsible for rendering them is at `site/layouts/_default/_markup/render-blockquote.html` | |||
There was a problem hiding this comment.
Also, I haven't deleted the render hook. So, it's still possible to use the old syntax. Please confirm that I can remove it. Or let me know if you'd like to keep it.
Signed-off-by: chibbyalucard <[email protected]>
Wryhder
commented
Jun 17, 2025
README.md
Outdated
Comment on lines
125
to
256
| > [!TIP] | ||
| > Helpful advice for doing things better or more easily. | ||
| 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: | ||
|
|
||
| > [!IMPORTANT] | ||
| > Key information users need to know to achieve their goal. | ||
| ```html | ||
| <!-- Partials in layout files --> | ||
|
|
||
| <!-- Anything passed via `content` is interpreted as Markdown --> | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "note" | ||
| "title" "Optional custom title" | ||
| "content" "Useful information that users should know, even when skimming content." | ||
| ) }} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "tip" | ||
| "title" "Optional custom title" | ||
| "content" "Helpful advice for doing things better or more easily." | ||
| ) }} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "important" | ||
| "title" "Optional custom title" | ||
| "content" "Key information users need to know to achieve their goal." | ||
| ) }} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "warning" | ||
| "title" "Optional custom title" | ||
| "content" "Urgent info that needs immediate user attention to avoid problems." | ||
| ) }} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "caution" | ||
| "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: | ||
|
|
||
| > [!WARNING] | ||
| > Urgent info that needs immediate user attention to avoid problems. | ||
| ```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. | ||
|
|
||
| - List item 1 | ||
| - List item 2 | ||
| `}} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "tip" | ||
| "title" "Optional custom title" | ||
| "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" | ||
| "- List item 1\n" | ||
| "- List item 2\n\n" | ||
| "`Here's some text in backticks.`" | ||
| }} | ||
|
|
||
| {{ partial "blockquote-alert.html" (dict | ||
| "type" "tip" | ||
| "title" "Optional custom title" | ||
| "content" $alertContent | ||
| ) }} | ||
|
|
||
| <!-- Pass HTML with nested elements --> | ||
| {{ partial "blockquote-alert" (dict | ||
| "type" "caution" | ||
| "title" "Be Careful!" | ||
| "html" "<p>This is a <strong>caution</strong> message.</p><p>It has multiple paragraphs.</p>" | ||
| ) }} | ||
| ``` |
There was a problem hiding this comment.
Came back to this and realized it's overly verbose. I'll take a look again within the next few days and trim it down a bit.
Signed-off-by: chibbyalucard <[email protected]>
|
I'm done with this. Please let me know if you'd like me to make any changes. |
|
Hey @Wryhder just dropping in to let you know these haven't been forgotten we just haven't been able to put time into dealing with them yet. Thanks for the work, please know it is appreciated, and we will deal with it. Just might take a while longer. |
|
@kingthorin No worries, I assumed as much. Thanks! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I'd previously suggested using short codes as an upgrade from the current render hook template (which only works in Markdown content), to add support for blockquote alerts in both HTML/Markdown content and layout files. But it turns out short codes don't work in layout files.
So this PR includes a partial template that can be used directly in layout files. Then, a short code that calls the partial can be used in Markdown content files. I've included documentation (
work-in-progress) in the README on how to use both the partial and the short code.Just for reference, here's what the alerts look like again (image borrowed from PR #2977 ). They'll be pretty much the same as before:
TODO:I've tested the short code in a Markdown content file, and the partial in a layout file. Probably need to test the short code in HTML content files, and the partial in other partials.It makes sense to remove the current render hook template and update any existing alerts to use the new syntax, but please let me know if it should stay, so that it's also possible to keep using the current syntax.PS: I'm still learning my way around Hugo, so please let me know if I've got anything mixed up.