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

tips & tricks
1

Hey Hugo community! :wave:

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
light-callout1920×1743 170 KB

hugo-admontions also supports dark mode! :waxing_crescent_moon:

Example Usage:

> [!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

You can check out more examples and documentation on the GitHub repo.

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!:grin:

4 Likes
2

A style element outside of the head element won’t pass validation:
image

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

Version your module (semver).

2 Likes
4

Thank you so much for your detailed feedback! :pray: 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. :blush:

Thanks again for helping improve the code quality! :blush:

5

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.

1 Like
6

Another solution, using CSS: Hugo: add custom infoboxes | Roneo.org
(Does not support dark mode)

2 Likes
7

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 to prevent dead-ends such as:

    ERROR Rebuild failed: render: failed to render pages: render of “home” failed: “/home/jmooring/code/hugo-testing/layouts/_default/home.html:11:5”: execute of template failed at <.Content>: error calling Content: “/home/jmooring/code/hugo-testing/content/_index.md:11:3”: “/home/jmooring/.cache/hugo_cache/modules/filecache/modules/pkg/mod/github.com/!k!k!k!z!o!z/hugo-admonitions@v0.1.0/layouts/_default/_markup/render-blockquote.html:20:11”: execute of template failed at <partial (printf “icons/%!s(MISSING).svg” $type) .>: error calling partial: partial “icons/note.svg” not found

    In the above, your GitHub user name is represented as k!k!k!z!o!z because your GitHub user name contains capital letters. This is undesirable but expected. See Go documentation.

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

    [[module.imports]]
path = 'github.com/KKKZOZ/hugo-admonitions'

    And this:

    hugo mod get -u

  1. For example, see related GitHub documentation. ↩︎

2 Likes
8

Think about supporting extended syntax or mention limitations in the README of your project.

2 Likes
9

Thank you so much for your detailed suggestions! :pray: 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:

:sparkles: 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!:rocket:

10

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

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

11

The github.com/KKKZOZ/hugo-admonitions module has evolved a bit since the original post.

Take it for a spin:

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, Obsidian, and Typora
  • The admonition types (e.g., “Warning”, “Note”) are easily localized[1]
  • Override styles by copying the source into assets/sass/vendors/_admonitions.scss

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

hugo mod init foo

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

Then add this to your site configuration:

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

To update as new versions are released:

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.

  1. The project welcomes PRs to add new languages ↩︎

2 Likes
12

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

3 Likes