Hextra v0.13

Hextra v0.13.0 brings a brand-new search experience that works smoothly on both mobile and desktop, an image gallery shortcode with a lightbox, foldable alerts, remote icon packs, and better Jupyter notebook rendering, plus a round of search improvements and bug fixes.

Upgrade Guide

No breaking changes are expected for most sites. Update using Hugo Modules:

hugo mod get -u github.com/imfing/hextra

If you’ve styled the search UI with custom CSS, see Search CSS changes.

Highlights

• A brand-new search experience that works smoothly on both mobile and desktop
• Gallery shortcode with PhotoSwipe lightbox and grid, carousel, and mosaic layouts
• Foldable alerts with custom titles, compatible with Obsidian callouts
• Remote icon packs: Lucide, Tabler Icons, and Simple Icons
• Improved Jupyter notebook rendering with In/Out prompts and more output types
• Custom partials for adding content before and after each page
• Cleaner search results and a fingerprinted search index

New Features

New Search Experience

Search has been completely redesigned as a command palette dialog, and it works smoothly on both mobile and desktop. On desktop, press ⌘+K (Ctrl+K on Windows and Linux) or / on any page to open it. On mobile, tap the search icon in the navbar to open the same full search dialog.

Results show breadcrumbs so you can tell where each match lives, the whole dialog works from the keyboard, and it opens and closes with smooth animations. To use the icon-only trigger on desktop as well, set params.icon on the search menu item:

menu:
  main:
    - name: Search
      weight: 5
      params:
        type: search
        icon: search

Results are cleaner too: excerpts no longer contain stray HTML tags, and headings with inline markup now link to the right anchor. In production, the search index file is fingerprinted, so visitors get the updated index right after a deploy instead of a stale cached copy.

Gallery Shortcode

The new gallery shortcode displays a set of images and opens them in a PhotoSwipe lightbox, with full-screen viewing, previous/next navigation, captions, and keyboard support. Click any image below to try it:

{{< gallery >}}
  {{< gallery-item src="https://picsum.photos/id/1015/1600/1200" thumb="https://picsum.photos/id/1015/800/600" width="1600" height="1200" caption="River valley" >}}
  {{< gallery-item src="https://picsum.photos/id/1018/1600/1200" thumb="https://picsum.photos/id/1018/800/600" width="1600" height="1200" caption="Mountain lake" >}}
  {{< gallery-item src="https://picsum.photos/id/1019/1600/1200" thumb="https://picsum.photos/id/1019/800/600" width="1600" height="1200" caption="Forest trail" >}}
{{< /gallery >}}

Use the type parameter to pick a layout: grid (the default), carousel for a horizontally scrolling strip, or mosaic, where items can span multiple rows or columns. Images can come from page bundles, global assets, static files, or remote URLs.

Foldable Alerts

Alerts can now be folded and given custom titles. Add + after the alert type to make it foldable and expanded by default, or - to start it collapsed, then write an optional title after the marker. The syntax follows Obsidian callouts.

> [!TIP]- Are alerts foldable?
> Yes. Foldable alerts hide their content when collapsed.

Remote Icon Packs

In addition to the built-in Heroicons, you can now use icons from remote icon packs by adding a provider prefix to the icon name:

Supported providers are Lucide, Tabler Icons, and Simple Icons. Icons are fetched at build time and work anywhere Hextra accepts an icon name, including cards, tabs, badges, callouts, and navbar menu items.

For example, in badges and cards:

{{< badge content="Hugo" icon="simple:hugo" >}}
{{< badge content="Markdown" icon="simple:markdown" >}}

{{< cards >}}
  {{< card link="https://lucide.dev/icons/" title="Lucide" icon="lucide:feather" >}}
  {{< card link="https://tabler.io/icons" title="Tabler Icons" icon="tabler:brand-tabler" >}}
  {{< card link="https://simpleicons.org/" title="Simple Icons" icon="simple:simpleicons" >}}
{{< /cards >}}

Improved Jupyter Notebook Rendering

The jupyter shortcode now renders many more kinds of notebook content: error tracebacks, stderr streams, SVG, Markdown, LaTeX, JSON, raw cells, and attachments. It also respects output metadata and cell visibility metadata. To show Jupyter-style In [N]:/Out[N]: prompts, set the new prompts parameter:

{{< jupyter src="notebook.ipynb" prompts=true >}}

Custom Page Sections

New customization hooks let you add your own content before and after each page and its body. Create any of these partials in your site:

layouts/_partials/custom/page-begin.html
layouts/_partials/custom/content-begin.html
layouts/_partials/custom/content-end.html
layouts/_partials/custom/page-end.html

Each partial receives the current Hugo page as context.

Search CSS Changes

The inline search box has been replaced by a dialog, so the hextra-search-wrapper class no longer exists. If you’ve styled the search UI with custom CSS, target the new hextra-search-trigger and hextra-search-dialog classes instead. The custom CSS documentation has the full list of search classes.

Fixes

• Mermaid diagrams that are visible on page load now render immediately
• Fix Mermaid diagram scaling when reduced motion is enabled
• Load KaTeX CSS that is compatible with Hugo’s built-in math renderer
• The mobile menu falls back to the page tree when the sidebar has no page-backed entries
• Resolve page-relative Markdown links correctly
• Fix search result links to headings that contain inline markup
• Use Hugo’s current language configuration keys
• Navbar icon menu items now work with tel: and other non-HTTP links
• Fix missing spaces between HTML attributes in cards and links, and unclosed tags in nested hero shortcodes
• Fix gallery shortcode build errors on Windows

Contributors

Thanks to everyone who contributed to this release:

• @bombsimon - Strip HTML tags from search results
• @yuri1969 - Fix Mermaid diagram scaling with reduced motion
• @muhammadkholidb - Add Roled documentation to the showcase
• @farmacia-cambie - Support tel: links in navbar icon menu items
• @hoshsadiq - Fix HTML attribute spacing and nested hero shortcodes
• @avighnac - Fix gallery shortcode build on Windows

Full Changelog: https://github.com/imfing/hextra/compare/v0.12.3...v0.13.0