docs(blog): prepare for v0.10 release post

2025-08-23 06:36:42 -04:00 · 2025-08-14 01:43:35 +08:00
parent 8025de9d9d
commit 7d9d07bfdf
1 changed files with 196 additions and 10 deletions
--- 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.
+
 <!--more-->

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