Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

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

Important

Breaking Changes: This release includes several breaking changes. Please review the checklist and the 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 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.

hugo.yaml

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.

hugo.yaml

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

hugo.yaml

params:
 page:
 tabs:
 sync: true

Blog List Pagination

Basic pagination controls have been added to blog listing pages.

hugo.yaml

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.

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 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:

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

Markdown Syntax Guide

Wed, 01 Jan 2020 00:00:00 +0000

This article offers a sample of basic Markdown syntax that can be used in Hugo content files.

Basic Syntax

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

This text will be italic

This will also be italic

This text will be bold

This will also be bold

You can combine them

Lists

Unordered

* Item 1
* Item 2
* Item 2a
* Item 2b

Item 1
Item 2
- Item 2a
- Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
1. Item 3a
2. Item 3b

Images

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

Links

[Hugo](https://gohugo.io)

Hugo

Blockquotes

As Newton said:

> If I have seen further it is by standing on the shoulders of Giants.

If I have seen further it is by standing on the shoulders of Giants.

Inline Code

Inline `code` has `back-ticks around` it.

Inline code has back-ticks around it.

Code Blocks

Syntax Highlighting

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

Tables

| Syntax | Description |
| --------- | ----------- |
| Header | Title |
| Paragraph | Text |

Syntax	Description
Header	Title
Paragraph	Text

Hextra – Blog

Hextra v0.10

Upgrade Guide

New Features

Dropdown Menu Support in Navbar

Enhanced Search Experience

llms.txt Support

Table of Contents Scroll Highlighting

Synchronized Tab Switching

Blog List Pagination

MathJax Support

Technical Improvements

Framework and Build System

Quality of Life Improvements

Bug Fixes and Stability

Migration Guide

Hugo Version Requirements

CSS Class Prefix Changes

Asset Management for KaTeX and Mermaid

Tailwind CSS v4

Contributors

Markdown Syntax Guide

Basic Syntax

Headings

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Emphasis

Lists

Unordered

Ordered

Images

Links

Blockquotes

Inline Code

Code Blocks

Syntax Highlighting

Tables

References