---
title: "Hextra v0.10"
date: 2025-08-14
authors:
  - name: imfing
    link: https://github.com/imfing
    image: https://github.com/imfing.png
tags:
  - Release
---

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

<!--more-->

It also includes contributions from 10 [new contributors](#contributors) and addresses long-standing community requests.

## Upgrade Guide

> [!IMPORTANT]
> **Breaking Changes**: This release includes several breaking changes. Please review the checklist and the [Migration Guide](#migration-guide) before upgrading.

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](#css-class-prefix-changes) and [Tailwind CSS v4](#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:

```bash
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**](#dropdown-menu-support-in-navbar): create hierarchical navigation menus
- [**Enhanced Search Experience**](#enhanced-search-experience): improved search across all headings with better accuracy
- [**llms.txt Support**](#llmstxt-support): generate AI-friendly site outline
- [**Table of Contents Scroll Highlighting**](#table-of-contents-scroll-highlighting): automatic heading highlighting during page scroll
- [**Synchronized Tab Switching**](#synchronized-tab-switching): synchronize tab selections across multiple tab groups
- [**Blog List Pagination**](#blog-list-pagination): add pagination controls to blog listing pages
- [**MathJax Support**](#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.

```yaml {filename="hugo.yaml"}
menu:
  main:
    - identifier: products
      name: "Products"
    - name: "Product A"
      parent: products
      url: "/product-a"
    - name: "Product B"
      parent: products
      url: "/product-b"
```

![Dropdown menu navigation](https://github.com/user-attachments/assets/1816f9b9-7fe3-46e8-9546-f15e43e9914a)

### 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](https://github.com/ldez) for pushing the search capabilities forward!

![Enhanced search results](https://github.com/user-attachments/assets/f819652a-95d4-4843-b7e2-c7953a8cabe8)

### llms.txt Support

Hextra now supports [llms.txt](https://llmstxt.org/) output format for your site, making your site more accessible to AI tools and language models for context and reference.

```yaml {filename="hugo.yaml"}
outputs:
  home: [html, llms]
```

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

![Example llms txt](https://github.com/user-attachments/assets/c6e929bb-0fce-4ab2-af15-a71c5a38b22c)

### 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.

![ToC scroll highlighting](https://github.com/user-attachments/assets/d623fb99-7000-428b-af95-384eb722f0eb)

### 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).

```yaml {filename="hugo.yaml"}
params:
  page:
    tabs:
      sync: true
```

### Blog List Pagination

Basic pagination controls have been added to blog listing pages.

```yaml {filename="hugo.yaml"}
params:
  blog:
    list:
      pagerSize: 20 # Posts per page
```

![Blog pagination](https://github.com/user-attachments/assets/60405fb4-ec36-4733-ba13-b4066396b5c5)

### MathJax Support

Render mathematical expressions with [MathJax](https://www.mathjax.org/) alongside the default KaTeX support. Choose the engine that best fits your needs.

```yaml {filename="hugo.yaml"}
params:
  math:
    engine: "mathjax" # default is "katex"
```

## Technical Improvements

### Framework and Build System

- **Tailwind CSS v4 Migration**: complete migration to [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4) with improved customization support.
- **Hugo Template System**: adapted to Hugo's [new template system](https://gohugo.io/templates/new-templatesystem-overview/) (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](https://github.com/nextapps-de/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**](#hugo-version-requirements): Requires Hugo v0.146.0+ (extended version)
- [**CSS Class Prefix Changes**](#css-class-prefix-changes): Component CSS classes now use consistent `hextra-` prefixing
- [**Asset Management**](#asset-management-for-katex-and-mermaid): KaTeX and Mermaid assets now download during build time
- [**Tailwind CSS v4**](#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:

| Area                 | Before                       | After                                             |
| -------------------- | ---------------------------- | ------------------------------------------------- |
| Search (container)   | `.search-wrapper`            | `.hextra-search-wrapper`                          |
| Search (input)       | `.search-input`              | `.hextra-search-input`                            |
| Search (results)     | `.search-results`            | `.hextra-search-results`                          |
| Search (title)       | `.search-wrapper .title`     | `.hextra-search-wrapper .hextra-search-title`     |
| Search (active item) | `.search-wrapper .active`    | `.hextra-search-wrapper .hextra-search-active`    |
| Search (no result)   | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
| Search (prefix)      | `.search-wrapper .prefix`    | `.hextra-search-wrapper .hextra-search-prefix`    |
| Search (excerpt)     | `.search-wrapper .excerpt`   | `.hextra-search-wrapper .hextra-search-excerpt`   |
| Search (match)       | `.search-wrapper .match`     | `.hextra-search-wrapper .hextra-search-match`     |
| Navbar blur          | `.nav-container-blur`        | `.hextra-nav-container-blur`                      |
| Hamburger menu       | `.hamburger-menu`            | `.hextra-hamburger-menu`                          |
| Theme toggle         | `.theme-toggle`              | `.hextra-theme-toggle`                            |
| Language switcher    | `.language-switcher`         | `.hextra-language-switcher`                       |
| Sidebar container    | `.sidebar-container`         | `.hextra-sidebar-container`                       |
| Sidebar active item  | `.sidebar-active-item`       | `.hextra-sidebar-active-item`                     |
| Code filename        | `.filename`                  | `.hextra-code-filename`                           |
| Copy icon            | `.copy-icon`                 | `.hextra-copy-icon`                               |
| Success icon         | `.success-icon`              | `.hextra-success-icon`                            |
| Steps                | `.steps`                     | `.hextra-steps`                                   |

#### 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](https://github.com/oosquare) - KaTeX fonts, image render hooks, link handling improvements
- [@Zabriskije](https://github.com/Zabriskije) - Phantom scroll fix
- [@miniwater](https://github.com/miniwater) - Custom footer centering, image alt text improvements
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - Google indexing controls, OpenGraph documentation
- [@KStocky](https://github.com/KStocky) - Reverse pagination feature
- [@PrintN](https://github.com/PrintN) - Documentation showcase additions
- [@hobobandy](https://github.com/hobobandy) - Title spacing improvements
- [@dlwocks31](https://github.com/dlwocks31) - Korean translation updates
- [@TwoAnts](https://github.com/TwoAnts) - Giscus theme switching fix
- [@ldez](https://github.com/ldez) - Search improvements and bug fixes

Additional thanks to returning contributors [@deining](https://github.com/deining) and [@yuri1969](https://github.com/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
