Using Admonitions in Clean Hugo Theme

The Clean Hugo theme includes an admonition shortcode that lets you create beautiful, color-coded callout boxes in your content. These callouts are perfect for highlighting important information.

About admonitions

Admonitions are visual callout boxes that draw attention to specific types of content. They’re commonly used in documentation and tutorials to highlight:

• Info - General information or tips
• Success - Positive outcomes or achievements
• Warning - Cautions or important notices
• Danger - Critical warnings or errors
• Note - Additional context or side notes

Basic usage

To add an admonition to a page, you can use the following syntax:

{{< admonition type="info" title="Optional Title" >}}
Your content here
{{< /admonition >}}

Exach admonition type has a custom color. you can override these colors in your hugo.toml configuration file under [params.theme.colors].

All admonition types

Info admonition

Use info admonitions for general tips, helpful information, or useful context.

Code example:

{{< admonition type="info" title="Tip" >}}
You can customize admonition colors by adding them to your hugo.toml configuration file.
{{< admonition >}}

Success admonition

Success admonitions are perfect for highlighting achievements, completed tasks, or positive outcomes.

Code example:

{{< admonition type="success" title="Installation Complete!" >}}
Great! Your Clean Hugo theme is now installed and ready to use.
{{< /admonition >}}

Warning admonition

Use warning admonitions to alert readers about potential issues or important cautions.

Code example:

{{< admonition type="warning" title="Important Notice" >}}
Make sure to run `npm install` before building your site.
{{< /admonition >}}

Danger admonition

Danger admonitions should be used sparingly for critical warnings or potential data loss scenarios.

Code example:

{{< admonition type="danger" title="Data Loss Warning" >}}
**Warning:** This action cannot be undone. Make sure you have backups!
{{< /admonition >}}

Note admonition

Note admonitions are great for additional context, side notes, or supplementary information.

Code example:

{{< admonition type="note" >}}
The default admonition type is "note" if you don't specify a type.
{{< /admonition >}}

Advanced usage

Without a title

You can omit the title parameter if you don’t need one:

{{< admonition type="info" >}}
This is an info admonition without a title.
{{< /admonition >}}

With markdown content

Admonitions support full Markdown syntax, including:

• Bold text
• Italic text
• Links
• Lists
• Code blocks

Code examples in different languages

Here are some examples showing how code blocks work with syntax highlighting:

Python example

def create_admonition(admonition_type, title=None, content=""):
    """Create an admonition shortcode string."""
    title_part = f' title="{title}"' if title else ""
    return f'{{{{< admonition type="{admonition_type}"{title_part} >}}}}\n{content}\n{{{{< /admonition >}}}}'

# Usage
info_box = create_admonition("info", "Pro Tip", "This is helpful information!")
print(info_box)

Bash/shell example

#!/bin/bash
# Script to generate Hugo admonition examples

echo "Creating admonition examples..."

cat > example.md << EOF
{{< admonition type="warning" title="Important" >}}
Make sure to backup your files before running this script!
{{< /admonition >}}
EOF

echo "Example file created!"

Console output example

$ hugo new blog/my-post.md
Creating new blog post: content/blog/my-post.md

$ hugo server
Start building sites …
Built in 234 ms
Web Server is available at http://localhost:1313/

Markdown example

# Blog Post Title

Here's how to use admonitions in your content:

{{< admonition type="info" title="Remember" >}}
Always escape shortcodes in code blocks using `{{< >}}` syntax.
{{< /admonition >}}

## More content

Your regular content goes here...

Customizing colors

All admonition colors can be customized in your hugo.toml file. Here’s an example configuration:

[params.theme.colors]
  # Info colors (blue)
  admonitionInfoBg = "#EFF6FF"
  admonitionInfoBorder = "#3B82F6"
  admonitionInfoText = "#1E40AF"
  admonitionInfoIcon = "#2563EB"
  
  # Success colors (green)
  admonitionSuccessBg = "#F0FDF4"
  admonitionSuccessBorder = "#22C55E"
  admonitionSuccessText = "#166534"
  admonitionSuccessIcon = "#16A34A"
  
  # ... and so on for other types

Blog post front matter configuration

Every blog post in Clean Hugo uses front matter (the YAML or TOML section at the top of the file) to configure how the post appears on your site. Here’s a complete guide to all available front matter options:

Required fields

title - The title of your blog post

title: "My Amazing Blog Post"

date - Publication date in YYYY-MM-DD format (controls sorting - most recent first)

date: 2024-12-22

Optional fields

draft - Set to true to hide the post from listings (default: false)

draft: false

excerpt - Short summary displayed in blog listings and meta descriptions

excerpt: "A brief description of what this post is about."

image - Featured image with alt text and optional photo credit (nested format)

image:
  src: "images/my-featured-image.jpg"
  alt: "Description of the image for accessibility"
  credit: "Photo by Jane Doe on Unsplash"  # optional

category - Single category for organizing posts (used for filtering on blog listing page)

category: "Tutorial"

tags - Array of tags for additional organization (displayed at bottom of single post)

tags:
  - hugo
  - tutorial
  - web-development

show_author - Set to true to display author name in listings (default: false)

show_author: false

hideDate - Set to true to hide the publication date on the single post page

hideDate: false

Complete front matter example

Here’s a complete example showing all available front matter options:

---
title: "Get Started with Clean Hugo Theme"
date: 2024-12-22
draft: false
excerpt: "Learn how to set up and customize the Clean Hugo theme for your website."
image:
  src: "images/hero-image.jpg"
  alt: "Modern workspace with laptop and coffee"
  credit: "Photo by Jane Smith on Unsplash"
category: "Tutorial"
show_author: false
hideDate: false
tags:
  - hugo
  - theme
  - web-development
  - tutorial
---

How front matter affects display

Blog Listing Page:

• Featured Post - The most recent post (by date) appears as a large featured card
• Sidebar Posts - Next 2 posts (configurable via sidebar_count in hugo.toml) appear in the sidebar
• Remaining Posts - All other posts appear in a grid below
• Category Filters - Buttons automatically generated from unique categories
• Post Cards - Display title, excerpt, category, date, and featured image

Single Post Page:

• Hero Section - Shows featured image (if provided) as header
• Title - Displayed prominently at the top
• Date - Shown below title (unless hideDate: true)
• Author - Shown if show_author: true
• Content - Full post content with proper typography
• Tags - Displayed at the bottom of the post

Front matter best practices

Configuration options in hugo.toml

You can customize blog listing behavior in your site’s hugo.toml:

[params.blog]
  sidebar_count = 2      # Number of posts shown in sidebar (right column)
  excerpt_length = 200   # Character length for excerpts in featured card

[params]
  blog_title = "My Blog"  # Title shown at top of blog listing page

Best practices

1. Use sparingly - Too many admonitions can overwhelm readers
2. Choose the right type - Match the admonition type to the content’s importance
3. Keep titles concise - Short, descriptive titles work best
4. Use markdown - Take advantage of formatting options within admonitions
5. Test accessibility - Ensure color contrast meets WCAG standards

Conclusion

Admonitions are a powerful way to make your content more engaging and easier to scan. The Clean Hugo theme makes it easy to add these beautiful callout boxes to any page or post.

Try adding some admonitions to your next blog post and see how they can improve your content’s readability!