A lightweight Hugo module that adds beautiful and customizable admonition blocks to your content.

Inspiration from mdbook-admonish.

If you find this project useful, please consider giving it a star! ⭐

• Hugo-admonitions
  • Table of Contents
  • Features ✨
  • Overview of all admonitions
    • Light Mode
    • Dark Mode
    • Header Only Mode
    • Foldable Admonitions
    • Nested Admonitions
  • Installation
    • Hugo Module
    • Git Clone
  • Usage
  • Customization
    • Variable Overrides (Recommended)
      • Global Theme Colors
      • Admonition Type Base Colors
      • Header Text & Icon Colors (Per-Type Override)
    • Dark Mode Support
    • Advanced SCSS Override (Modifying Rendering Logic)
  • Contributing
  • License
  • Star History

• Various beautiful and simple callout available 🎨

• Blockquote style 💬

  • Portable Markdown style (GitHub, Obsidian, Typora, etc.) 📝

  • > [!WARNING]
    > Warning: This operation will delete all data.

• Dark Mode Support 🌙

• Header Only Mode 📑

• Foldable Admonitions 📂

• Multi-language Support 🌐

  • English
  • Chinese
  • French
  • German
  • Swahili
  • Czech
  • Polish
  • Localization PRs are always welcome!

1. Install the Go programming language.

2. Initialize your own hugo module:

   hugo mod init YOUR_OWN_GIT_REPOSITORY

3. Add hugo-admonitions in your site's configuration file:

   With hugo.yaml:

   module:
     imports:
       - path: github.com/KKKZOZ/hugo-admonitions
       - path: my-theme

   With hugo.toml:

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

4. Finally update by running:

   hugo mod get -u

1. Inside the folder of your Hugo site, run:

   git clone git@github.com:KKKZOZ/hugo-admonitions.git themes/hugo-admonitions --depth=1

2. Add hugo-admonitions as the left-most element of the theme list variable in your site's or theme's configuration file hugo.yaml or hugo.toml.

   With hugo.yaml:

   theme: ["hugo-admonitions", "my-theme"]

   With hugo.toml:

   theme = ["hugo-admonitions", "my-theme"]

See demo.md for examples.

Use the blockquote in this way:

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

Or you can customize the title by using any of them:

> [!IDEA] Summary
> This is a summary using the `IDEA` callout!

> [!MEMO] Summary
> This is a summary using the `MEMO` callout!

Use the Header Only mode by including a title only:

> [!TIP] You can choose to only to show the header!

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

> [!SUCCESS] Congratulations! Your code has been successfully deployed to production

> [!WARNING] Warning: This operation will delete all data. 

Use the extended syntax:

> [!TIP]- Click here to view the tips

> [!TIP]+ Click here to view the tips

You can use nested admonitions too:

> [!QUESTION] Can admonitions be nested?
> > [!TODO] Yes!, they can.
> > > [!EXAMPLE]  You can even use multiple layers of nesting.

There are two main ways to customize the styles:

1. Variable Overrides (Recommended for most users): Modify colors, opacities, dark mode selectors, etc., by overriding SASS variables. This method is update-friendly.
2. Advanced SCSS Override: For deep changes to the styling logic and CSS rules, you can override the main SCSS file.

This is the simplest and most common way to customize admonition styles. You only need to create a single SASS file in your project to specify your custom variable values.

1. Create the user settings SASS file:

In your Hugo project's root directory, create the following file (including the directories if they don't exist): assets/sass/vendors/_admonitions-user-settings.scss

You can use these commands from the root of your project:

mkdir -p assets/sass/vendors
touch assets/sass/vendors/_admonitions-user-settings.scss

The resulting directory structure in your project will look like this:

your-hugo-project/
└── assets/
    └── sass/
        └── vendors/
            └── _admonitions-user-settings.scss  <-- Your custom settings file

2. Define your custom variables in this file

Open assets/sass/vendors/_admonitions-user-settings.scss and add your SASS variable overrides.

This file contains a minimal example to get you started.

In _admonitions-user-settings.scss, you have several levels of customization available:

You can override the general colors for all admonitions in both light and dark modes. These variables control the background, text, and code block colors.

// assets/sass/vendors/_admonitions-user-settings.scss

// --- Theme Colors ---
// Define the colors used for admonition elements in both light and dark modes.

// Light Mode Colors
$admonition-light-bg: #ffffff;                 // Content background
$admonition-light-text: #000000;                // Content text
$admonition-light-code-bg: #f5f5f5;             // Inline code & code block background
$admonition-light-code-text: #24292e;           // Inline code & code block text
$admonition-light-blockquote-border: #e0e0e0;  // Blockquote left border

// Dark Mode Colors
$admonition-dark-bg: #1d1e20;                   // Content background
$admonition-dark-text: #e6e6e6;                 // Content text
$admonition-dark-code-bg: #313244;              // Inline code & code block background
$admonition-dark-code-text: #cdd6f4;            // Inline code & code block text
$admonition-dark-blockquote-border: #45475a;   // Blockquote left border

// --- Header Background Opacity ---
// Controls the opacity of the background color tint applied to the whole admonition block.
// Value should be between 0 (transparent) and 1 (opaque).
$admonition-light-header-bg-opacity: 0.1;       // Opacity for light mode background tint
$admonition-dark-header-bg-opacity: 0.1;        // Opacity for dark mode background tint

To change the base color for specific admonition types (e.g., note, tip, warning), define the $admonition-colors-overrides SASS map. This color is used for the left border and as a base for the tinted background. It also serves as the default color for the header text and icon.

This map will be merged with the module's default type colors, with your definitions taking precedence.

// Example: assets/sass/vendors/_admonitions-user-settings.scss

// --- Admonition Type Base Colors ---
// Override the default color for specific admonition types.
$admonition-colors-overrides: (
  note: #007bff,      // Make 'note' admonitions blue
  tip: #28a745,       // Make 'tip' admonitions green
  warning: #ffc107,   // Make 'warning' admonitions yellow
  danger: #dc3545
);

The default types and their base colors can be found in the $admonition-colors-base map within the module's main _admonitions.scss file.

For more granular control, you can specifically override the header text and icon color for different admonition types in both light and dark modes. This is useful when the base color (from $admonition-colors or your override) doesn't provide enough contrast with the tinted background.

Define your overrides in the $admonition-light-header-text-overrides and $admonition-dark-header-text-overrides maps.

// Example: assets/sass/vendors/_admonitions-user-settings.scss

// --- Header Text & Icon Color Overrides ---
// Use these maps to set a specific header text color for certain admonition types,
// overriding the default behavior.

$admonition-light-header-text-overrides: (
  // In light mode, the yellow 'warning' admonition base color (#ffc107)
  // is too light for text. Let's make the header text darker for better readability.
  warning: #a37100
);

$admonition-dark-header-text-overrides: (
  // In dark mode, the default header text for 'danger' might be its base color (#dc3545),
  // which can be hard to read on a dark tinted background. We can brighten it up.
  danger: #ff9e8f,
  // Let's also make the 'note' header text white in dark mode for high contrast.
  note: #ffffff
);

By default, hugo-admonitions attempts to automatically detect and apply dark mode styling to match your website's theme.

How it Works:

Instead of relying on the operating system's preference (prefers-color-scheme), this module checks for the presence of specific CSS selectors on your <html> or <body> tags. The default configuration looks for a wide range of common selectors used by popular Hugo themes and CSS frameworks:

• html[data-theme="dark"], body[data-theme="dark"]
• html[data-bs-theme="dark"]
• html[data-scheme="dark"], body[data-scheme="dark"]
• html[data-color-mode="dark"], body[data-color-mode="dark"]
• body.dark, body.dark-mode, body.theme-dark
• html.dark, html.dark-mode

This list is defined by the $admonition-dark-selector variable within the module's SCSS file.

When Customization is Needed:

If your theme uses a different CSS class or data attribute not included in the default list above, the admonition blocks might remain in light mode even when your site switches to dark mode.

How to Customize the Dark Mode Trigger:

You can easily tell hugo-admonitions which selector(s) your theme uses by overriding the $admonition-dark-selector SCSS variable in _admonitions-user-settings.scss.

If you need to make more fundamental changes to the admonition styles beyond what variables allow (e.g., altering CSS rules for structure, spacing, animations, or adding entirely new CSS), you will need to override the main _admonitions.scss file from the module.

1. Create a copy of the module's main SCSS file: In your Hugo project's root directory, create the following file: assets/sass/vendors/_admonitions.scss

   You can use these commands:

   mkdir -p assets/sass/vendors
   touch assets/sass/vendors/_admonitions.scss

   The resulting directory structure in your project:

   your-hugo-project/
   └── assets/
       └── sass/
           └── vendors/
               └── _admonitions.scss  <-- Your overridden main SCSS file
   

2. Copy the contents of the source file into the file you created.

3. Update the styles as needed.

Contributions are welcome! Please feel free to submit a Pull Request.

Before you submit a pull request, please ensure that you have run npm install. This will install a husky hook that automatically checks if your commit messages adhere to the Conventional Commits specification. Commit messages that do not meet this standard will not pass the automated checks for pull requests.

This project is licensed under the MIT License - see the LICENSE file for details