Beautiful Hugo Bootstrap 5 upgrade!

Beautiful Hugo has upgraded to Bootstrap v5, with a modernized feature set with dark mode support, AI summary limit controls, upgraded dependencies, and several new shortcodes.

What’s New

Dark Mode toggle

The theme now supports three color schemes: auto (follows system preference), light, and dark. When set to auto, a toggle button appears in the navbar that cycles between modes. The choice persists via localStorage, and the theme reacts to OS-level dark mode changes in real time.

All dark mode colors use CSS custom properties on [data-theme="dark"], making it easy to override without editing theme files. See Theming for the full variable reference and customization guide.

All theme elements — callout boxes, code blocks, navigation, figures — adapt to the selected scheme. Mermaid diagrams are dual-rendered for both light and dark backgrounds. If you have a transparent figure that doesn’t look good in dark mode, you can add the white class to give it a white background in dark mode.

See Configuration for setup, Theming for customization, and Markdown Extensions for theme-dependent content.

PhotoSwipe 5

Image lightbox support has been upgraded to PhotoSwipe 5, bringing pinch-to-zoom, swipe navigation, and automatic image dimension detection. The beautifulfigure shortcode and gallery shortcode are both integrated. Note that beautifulfigure is new; currently figure maps to beautifulfigure for backward compatibility; see Figure Override Control below.

See Figures & Galleries for details.

New Shortcodes

• tabs / tab: Bootstrap 5 tabbed interface with optional synchronization across tab groups. See Shortcodes.
• mermaid (revamped, not exaclty new): Mermaid diagram rendering with automatic dark mode support. See Math & Diagrams.
• details (not documented before): Collapsible <details> element. See Shortcodes.
• columns / column: Two-column layout. See Shortcodes. This is backward compatible with the previous columns/endcolumns, but you must use the self-closing form of columns for it to work that way.

GitHub Buttons

Add star, watch, fork, and follow buttons to any page via ghRepo and ghBadge front matter. See Comments & Social.

Layout Options

New per-page front matter options: fullWidth, navShort, showAvatar, hidden. See Pages & Layouts.

Figure Override Control

The disableFigureOverride flag lets you use Hugo’s native <figure> shortcode while keeping beautifulfigure available separately. This might be required in the future to allow users to access the native figure in hugo - you can’t access it if it’s overridden by the theme (even disableFigureOverride just provides an approximation of it, the real one is written in go and inaccessable due to the existence of a theme figure shortcode). See Figures & Galleries.

Table of Contents Panel

A slide-out TOC panel is now available on all pages. It shows headings for single pages and a post list for section/home pages. Toggle it with the list icon in the navbar. See Configuration.

Robot Meta Tags & AI Summary Limits

You can now control <meta name="robots"> tags from hugo.toml, _index.md, or page front matter. Supported boolean tags include noindex, nofollow, noai, noimageai, and more. The ai-summary-limit setting lets you restrict how much of your content search engines can use for AI-generated summaries (e.g. nosnippet to block entirely, or a character limit like 50/150/300). A new no-ai-summary shortcode wraps sections in <div data-nosnippet> to exclude specific content from summaries.

See SEO & i18n, Configuration, and Shortcodes for details.

Callout Boxes

Nine styled callout types (primary, secondary, info, warning, danger, success, light, dark, note) powered by Bootstrap alerts, with a new callout shortcode supporting multiple paragraphs and optional titles. The legacy .box-* CSS classes still work for backward compatibility. See Shortcodes and Markdown Extensions.

Small things

• Hugo date formats for translatiosn — Support months in other languages
• Narrow image mode — new narrow class for figures that shouldn’t stretch full width (#661)

Upgraded Dependencies

Breaking Changes

• [author] is deprecated. Use [Params.author] instead. The theme emits an errorf if the old key is present.
• Minimum Hugo version: 0.146.2
• The figure shortcode now routes through beautifulfigure by default. Set disableFigureOverride = true to access (a close approximation of) Hugo’s native figure.

See also