--- title: "Hextra v0.10" date: 2025-08-14 authors: - name: imfing link: https://github.com/imfing image: https://github.com/imfing.png tags: - Release draft: true --- Hextra v0.10.0 is the most significant release yet, delivering new capabilities, architectural upgrades, and quality-of-life improvements. It also includes contributions from 10 [new contributors](#contributors) and addresses many long-standing requests. To upgrade to v0.10.0, update the Hugo module: ```bash hugo mod get -u github.com/imfing/hextra@v0.10.0 ``` > [!IMPORTANT] > **Breaking Changes**: This release includes several breaking changes that may affect your site. Please review the [Migration Guide](#migration-guide) section before upgrading. ## New Features #### 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) #### 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 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) #### 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 Kudos 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. #### 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) #### 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 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 - Improved CSS loading logic for both production and development environments ## Quality of Life Improvements ### User Experience - **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 ## 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 ### Breaking Changes #### 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` | **Migration steps:** 1. Search your custom CSS files for any of the "Before" class names 2. Replace them with the corresponding "After" class names 3. Test your site's styling after the update #### 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 #### 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 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 - Utitlity classes now prefix with `hx:` rather than `hx-` ### Automatic Features The following improvements are enabled automatically with no configuration required: - Table of Contents scroll highlighting - Enhanced search across all heading levels - Dynamic favicon switching based on color scheme - Improved component styling consistency ## 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