Hextra v0.10

Hextra v0.10.0 is a big release packed with new capabilities, architectural upgrades, and quality-of-life improvements.

It also includes contributions from 10 new contributors and addresses long-standing community requests.

Upgrade Guide

Before upgrading to v0.10.0, ensure that you have:

• Hugo v0.146.0+ (extended version) installed
• Reviewed custom CSS for class name changes (see CSS Class Prefix Changes and Tailwind CSS v4)
• Verified that build environment has internet access for asset downloads when LaTeX and/or Mermaid is used

Once ready, update the Hugo module:

hugo mod get -u github.com/imfing/hextra@v0.10.0

New Features

Here is a list of notable new features in this release:

• Dropdown Menu Support in Navbar: create hierarchical navigation menus
• Enhanced Search Experience: improved search across all headings with better accuracy
• llms.txt Support: generate AI-friendly site outline
• Table of Contents Scroll Highlighting: automatic heading highlighting during page scroll
• Synchronized Tab Switching: synchronize tab selections across multiple tab groups
• Blog List Pagination: add pagination controls to blog listing pages
• MathJax Support: alternative math rendering engine alongside KaTeX

Dropdown Menu Support in Navbar

Create dropdown menus in your navigation bar for better navigation items organization.

menu:
  main:
    - identifier: products
      name: "Products"
    - name: "Product A"
      parent: products
      url: "/product-a"
    - name: "Product B"
      parent: products
      url: "/product-b"

Enhanced Search Experience

• Search in all headings: find content across all heading levels, not just page titles
• Improved result accuracy: better title handling and linking precision
• Fixed result navigation: search results now link to the correct page sections

Huge thanks to @ldez for pushing the search capabilities forward!

llms.txt Support

Hextra now supports llms.txt output format for your site, making your site more accessible to AI tools and language models for context and reference.

outputs:
  home: [html, llms]

This will generate an llms.txt file at your site’s root.

Table of Contents Scroll Highlighting

The table of contents now automatically highlights the current section as you scroll through the page, making navigation more intuitive.

Synchronized Tab Switching

Tabs with the same items now synchronize across the page. When sync is enabled, selecting a tab updates all tab groups that share the same items list (and your selection is remembered).

params:
  page:
    tabs:
      sync: true

Blog List Pagination

Basic pagination controls have been added to blog listing pages.

params:
  blog:
    list:
      pagerSize: 20 # Posts per page

MathJax Support

Render mathematical expressions with MathJax alongside the default KaTeX support. Choose the engine that best fits your needs.

params:
  math:
    engine: "mathjax" # default is "katex"

Technical Improvements

Framework and Build System

• Tailwind CSS v4 Migration: complete migration to Tailwind CSS v4 with improved customization support.
• Hugo Template System: adapted to Hugo’s new template system (v0.146.0+) for future compatibility.
• Math Server-Side Rendering: better handling of math equation rendering using Hugo native rendering by default.
• FlexSearch 0.8 Upgrade: upgraded search engine FlexSearch for faster, more accurate results with improved CJK (Chinese, Japanese, Korean) content encoding.
• Enhanced Asset Management: KaTeX and Mermaid assets support loading from CDN or local

Quality of Life Improvements

• Dynamic favicon switching: automatic favicon updates based on color scheme preferences
• Reverse pagination: authors can now set reversePagination in page front matter
• Google indexing control: new page parameter to block Google indexing when needed
• Width handling improvements: better responsive design controls via CSS variables
• Styling improvements: modern styles for Markdown table and horizontal line

Bug Fixes and Stability

• Giscus theme synchronization: comments now properly follow dark/light mode switches
• Search result accuracy: fixed linking issues and title escaping in search results
• Tab switching: resolved navigation issues in non-synced tab mode
• Phantom scrolling: fixed unwanted scroll behavior when footer is disabled
• Image accessibility: prevented duplicate alt text rendering
• Link rendering: improved base URL handling for complex site structures

Migration Guide

• Hugo Version Requirements: Requires Hugo v0.146.0+ (extended version)
• CSS Class Prefix Changes: Component CSS classes now use consistent hextra- prefixing
• Asset Management: KaTeX and Mermaid assets now download during build time
• Tailwind CSS v4: Internal CSS compilation now uses Tailwind CSS v4.x with hx: prefix

Hugo Version Requirements

Impact: Sites running older Hugo versions

Hextra v0.10.0 requires Hugo v0.146.0 or later (extended version) due to the new template system adoption.

Action required: Update Hugo to v0.146.0+ before upgrading Hextra

CSS Class Prefix Changes

Impact: Sites with custom CSS targeting Hextra component classes

Hextra v0.10.0 introduces consistent hextra- prefixing for majority of component CSS classes to improve maintainability and prevent conflicts with user styles.

Action required: If you have custom CSS targeting Hextra components, update the following class names:

Asset Management for KaTeX and Mermaid

Impact: Sites using KaTeX or Mermaid

Hextra v0.10.0 now downloads KaTeX and Mermaid assets from CDN during build time.

What’s changed:

• Build process now requires internet access to download these assets
• No more external CDN calls for these assets after build

Action required:

• Ensure your build environment has internet access to download assets
• Sites in air-gapped environments may need to pre-download these assets and configure Hextra to load them

Tailwind CSS v4

Impact: Sites with extensive custom CSS targeting Hextra Tailwind classes hx-*

While Hextra handles the Tailwind CSS v4 migration internally, sites with heavy customizations may need further adjustments.

What’s changed:

• Internal CSS compilation now uses Tailwind CSS v4.x
• Utility classes now prefix with hx: rather than hx-

Contributors

This release was made possible by contributions from 10 new contributors:

• @oosquare - KaTeX fonts, image render hooks, link handling improvements
• @Zabriskije - Phantom scroll fix
• @miniwater - Custom footer centering, image alt text improvements
• @MattDodsonEnglish - Google indexing controls, OpenGraph documentation
• @KStocky - Reverse pagination feature
• @PrintN - Documentation showcase additions
• @hobobandy - Title spacing improvements
• @dlwocks31 - Korean translation updates
• @TwoAnts - Giscus theme switching fix
• @ldez - Search improvements and bug fixes

Additional thanks to returning contributors @deining and @yuri1969 for their continued support with documentation, translations, and technical improvements.

Full Changelog: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0