# Hugo-admonitions: A simple way to add beautiful Callouts to hugo site

**URL:** <https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576>\
**Category:** tips & tricks\
**Tags:** modules\
**Created:** [November 28, 2024, 3:36pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576 "2024-11-28T15:36:13Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [November 28, 2024, 3:36pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/1 "2024-11-28T15:36:13Z")

</div>

Hey Hugo community! 👋

I wanted to share a little project I’ve been working on - `hugo-admonitions`. It’s a Hugo module that helps you create beautiful admonition/callout blocks in your content using simple markdown syntax.

**Key Features:**

- Multiple predefined types: note, info, warning, etc.
- Built-in color themes that match your site’s style
- No JavaScript dependencies
- Works with any Hugo theme
- Dark Mode support

## Overview of all admonitions

 ![light-callout](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/3X/5/0/503b215195b2fae8e7423cfed4234adede557558.jpeg)

> `hugo-admontions` also supports dark mode! 🌒

**Example Usage:**

```go
> [!NOTIFY]
> System notification: Your password will expire in 30 days.

```

I created this because I wanted something lightweight and easy to use.  
The styling is inspired by [mdbook-admonish](https://tommilligan.github.io/mdbook-admonish/)

You can check out more examples and documentation on the [GitHub repo](https://github.com/KKKZOZ/hugo-admonitions).

I’d love to hear your feedback and suggestions for improvements! Feel free to open issues or contribute if you find it useful.

Would this be something useful for your Hugo sites? Let me know what you think!😁

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [November 28, 2024, 3:53pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/2 "2024-11-28T15:53:23Z")

</div>

A `style` element outside of the `head` element won’t pass validation:  
 ![image](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/3X/5/6/563dbb5a9f935d11b20784fc18804ff9a51b2062.png)

Use an external stylesheet instead, and add instructions to your module’s README.

To write portable Markdown (GitHub, Obsidian, Typora, etc.) use blockquotes instead:  
[https://gohugo.io/render-hooks/blockquotes/#alerts](https://gohugo.io/render-hooks/blockquotes/#alerts)

Version your module (semver).

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [November 29, 2024, 2:31am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/4 "2024-11-29T02:31:36Z")

</div>

Thank you so much for your detailed feedback! 🙏 I really appreciate you taking the time to point out these important issues. I will fix these problems as soon as possible, especially moving the styles to an external stylesheet for better compatibility.

By the way, I’m curious about the validation you mentioned - which validation system or standard were you referring to? This will help me ensure the fixes meet the right requirements. 😊

Thanks again for helping improve the code quality! 😊

---

<div class="post-metadata">

**Author:** ![chrillek](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/chrillek/32/19797_2.png) [@chrillek](https://discourse.gohugo.io/u/chrillek)\
**Post date:** [November 29, 2024, 6:34am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/5 "2024-11-29T06:34:09Z")

</div>

Search for HTML validator. The W3C’s one should be one of the first hits. They also offer CSS validation, though that’s something your browser’s developer tools does, too.

---

<div class="post-metadata">

**Author:** ![iaeiou](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/iaeiou/32/15332_2.png) [@iaeiou](https://discourse.gohugo.io/u/iaeiou)\
**Post date:** [November 29, 2024, 11:15am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/6 "2024-11-29T11:15:29Z")

</div>

Another solution, using CSS: [Hugo: add custom infoboxes | Roneo.org](https://roneo.org/en/hugo-custom-warning-infoboxes/)  
(Does not support dark mode)

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [November 29, 2024, 2:27pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/7 "2024-11-29T14:27:57Z")

</div>

Regarding your recent changes:

1. Use the `Store` method instead of `Scratch`

2. The `AlertType` is already lowercase… no need to convert it again

3. Use `render-blockquote-alert.html` instead of `render-blockquote.html` to reduce chance of template overrides

4. Internationalize (use `T` function and create at least one i18n file)

5. Support portable\[1\] Markdown by adding alert types `note`, `important`, and `caution`

6. Do some error checking/recovery with [`templates.Exists`](https://gohugo.io/functions/templates/exists/) to prevent dead-ends such as:

7. Initialize as a Go module, use semver tags, and create releases. That will allow users to do this:

* * *

1. For example, see [related GitHub documentation](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).

---

<div class="post-metadata">

**Author:** ![McShelby](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/mcshelby/32/15112_2.png) [@McShelby](https://discourse.gohugo.io/u/McShelby)\
**Post date:** [November 29, 2024, 2:48pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/8 "2024-11-29T14:48:05Z")

</div>

Think about supporting [extended syntax](https://gohugo.io/render-hooks/blockquotes/#extended-syntax) or mention limitations in the README of your project.

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [November 30, 2024, 4:35am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/9 "2024-11-30T04:35:03Z")

</div>

Thank you so much for your detailed suggestions! 🙏 I really appreciate you taking the time to help improve hugo-admonitions. I’m happy to let you know that I’ve implemented all the changes you recommended:

✨ Major improvements include:

- Switched to using Store method instead of Scratch
- Renamed to render-blockquote-alert.html for better template handling
- Added internationalization support with i18n files
- Included new alert types: note, important, and caution
- Implemented error checking using templates.Exists for icon files
- Initialized as a Go module with proper versioning

Your suggestions have significantly improved the module’s reliability and user experience. Thanks again for taking the time to provide such comprehensive feedback!🚀

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [November 30, 2024, 4:38am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/10 "2024-11-30T04:38:20Z")

</div>

Really appreciate your attention to detail and the suggestion about documenting syntax features.🙏

I’m currently working on implementing support for extended syntax!

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 2, 2024, 5:56pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/11 "2024-12-02T17:56:29Z")

</div>

The [github.com/KKKZOZ/hugo-admonitions](https://github.com/KKKZOZ/hugo-admonitions) module has evolved a bit since the original post.

Take it for a spin:

```plaintext
git clone --single-branch -b hugo-forum-topic-52576 https://github.com/jmooring/hugo-testing hugo-forum-topic-52576
cd hugo-forum-topic-52576
hugo server

```

Notes:

- The Markdown syntax is compatible with [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts), [Obsidian](https://help.obsidian.md/Editing+and+formatting/Callouts), and [Typora](https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts)
- The admonition types (e.g., “Warning”, “Note”) are easily localized\[1\]
- Override styles by copying the [source](https://github.com/KKKZOZ/hugo-admonitions/blob/main/assets/sass/vendors/_admonitions.scss) into `assets/sass/vendors/_admonitions.scss`

To add this module to your project, initialize your project as a Hugo module:

```auto
hugo mod init foo

```

In the above, `foo` is typically something like `github.com/user/project`.

Then add this to your site configuration:

```plaintext
[[module.imports]]
path = "github.com/KKKZOZ/hugo-admonitions"

```

To update as new versions are released:

```plaintext
hugo mod get -u github.com/KKKZOZ/hugo-admonitions

```

Many thanks to @KKKZOZ for putting this together. It’s a great example of using a [block quote render hook](https://gohugo.io/render-hooks/blockquotes/).

* * *

1. The project welcomes PRs to add new languages

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [December 3, 2024, 12:23pm UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/12 "2024-12-03T12:23:48Z")

</div>

I’ve learned a lot from this project, thanks for your help @jmooring

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [April 24, 2025, 8:30am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/13 "2025-04-24T08:30:28Z")

</div>

I’ve updated the code to support dark mode for different themes. Feel free to try it out and give feedback!

---

<div class="post-metadata">

**Author:** ![KKKZOZ](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/kkkzoz/32/23431_2.png) [@KKKZOZ](https://discourse.gohugo.io/u/KKKZOZ)\
**Post date:** [April 25, 2025, 1:00am UTC](https://discourse.gohugo.io/t/hugo-admonitions-a-simple-way-to-add-beautiful-callouts-to-hugo-site/52576/14 "2025-04-25T01:00:20Z")

</div>

Finally, hugo-admonitions now supports this feature! 🚀