diff --git a/exampleSite/content/blog/v0.10.md b/exampleSite/content/blog/v0.10.md index 76e9bf3..b2b4afd 100644 --- a/exampleSite/content/blog/v0.10.md +++ b/exampleSite/content/blog/v0.10.md @@ -1,5 +1,5 @@ --- -title: "Hextra v0.10.0 is released" +title: "Hextra v0.10" date: 2025-08-14 authors: - name: imfing @@ -10,23 +10,144 @@ tags: draft: true --- +Hextra v0.10.0 is the most significant release yet, delivering new capabilities, architectural upgrades, and quality-of-life improvements. + -## What's New - -TODO - -To upgrade to v0.10.0, update your Hugo module: +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 -### CSS class prefix +### Breaking Changes -This release includes a comprehensive CSS class naming refactor to improve consistency and avoid potential conflicts. Most Hextra components CSS classes now use the `hextra-` prefix. +#### 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 | | -------------------- | ---------------------------- | ------------------------------------------------- | @@ -50,6 +171,71 @@ This release includes a comprehensive CSS class naming refactor to improve consi | Success icon | `.success-icon` | `.hextra-success-icon` | | Steps | `.steps` | `.hextra-steps` | ---- +**Migration steps:** -_This is a draft release announcement. The actual release date and features may vary._ +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