Beautiful Hugo provides several CSS classes that extend standard Markdown with theme-dependent visibility and layout utilities. There are two ways to use them:
Use standard HTML tags with the CSS classes directly in your Markdown. This requires enabling markup.goldmark.renderer.unsafe = true in your site config:
[markup.goldmark.renderer]
unsafe = true
Without this setting, Hugo’s Goldmark renderer strips raw HTML from Markdown files.
Apply CSS classes to Markdown blocks using the {.class} attribute syntax. This requires enabling markup.goldmark.parser.attribute.block = true in your site config:
[markup.goldmark.parser.attribute]
block = true
The {.class} attribute must be on its own line immediately after the block. This only works for block-level elements.
Both options can be enabled together. The examples below show each approach — switch tabs to see the alternative syntax.
Callout Boxes
Callout boxes are now available as a callout shortcode supporting multiple paragraphs and an optional title. See Shortcodes for full documentation and live examples.
For backward compatibility, the legacy CSS classes (.box-note, .box-warning, .box-error, .box-success) still work with raw HTML or block attributes, but the shortcode is recommended.
Content Section
The .content-section class wraps content in a rounded gray box:
.content-section div. It's useful for highlighting a block of content or separating it from the surrounding text.<div class="content-section">
Wrapped content goes here.
</div>
Wrapped content goes here.
{.content-section}
Theme-Dependent Content
Use .theme-light and .theme-dark to show content only in a specific color scheme. Try toggling the theme with the button in the navbar — the blocks below will swap.
<div class="theme-light">
Visible only in light mode.
</div>
<div class="theme-dark">
Visible only in dark mode.
</div>
Visible only in light mode.
{.theme-light}
Visible only in dark mode.
{.theme-dark}
This is particularly useful for images or diagrams that need different versions for light and dark backgrounds. Mermaid diagrams use this mechanism internally for dual-rendering.
Centered Images
Use the .center class to center a block element (like an image) with display: block; margin: 0 auto:
A centered image with a caption
<img src="/img/global-ike.png" alt="A globe" class="center" style="max-width: 400px;" />
<em class="caption">A centered image with a caption</em>
Block attributes only work for block-level elements, so inline elements like <img> without a block wrapper still require raw HTML. You can combine both approaches:
{.center}
*A centered image with a caption*
{.caption}
Note: applying .center to a Markdown image via block attributes centers the <figure> wrapper Hugo generates, not the <img> directly.
White Background for Dark Mode
Add the .white class to a <figure> or <p> element to give it a white background. This is useful for images with transparent backgrounds that would otherwise look odd in dark mode.
<figure class="white">
<img src="/img/global-ike.png" alt="Globe with transparency" />
</figure>
{.white}
When block attributes are enabled, Hugo wraps Markdown images in a <figure>. The .white class is applied to that <figure> wrapper.
Hidden Elements
The .hideme class applies display: none:
<div class="hideme">This content is hidden.</div>
This content is hidden.
{.hideme}
Full-Width Image
The .img-title class makes an image span the full width:
<img src="/img/global-ike.png" class="img-title" alt="Full width image" />
{.img-title}