From 273e1e3db9f812a6291786aefa814dd8f2483e44 Mon Sep 17 00:00:00 2001 From: Xin Date: Thu, 14 Aug 2025 16:28:36 +0800 Subject: [PATCH] Update v0.10.md to enhance upgrade instructions, clarify breaking changes, and improve overall readability. Adjusted formatting for consistency and added details on asset management and user experience improvements. --- exampleSite/content/blog/v0.10.md | 80 ++++++++++++++----------------- 1 file changed, 37 insertions(+), 43 deletions(-) diff --git a/exampleSite/content/blog/v0.10.md b/exampleSite/content/blog/v0.10.md index ba3607b..35beee8 100644 --- a/exampleSite/content/blog/v0.10.md +++ b/exampleSite/content/blog/v0.10.md @@ -19,13 +19,13 @@ It also includes contributions from 10 [new contributors](#contributors) and add ## Upgrade Guide > [!IMPORTANT] -> **Breaking Changes**: This release includes several breaking changes. Please review the checklist and [Migration Guide](#migration-guide) before upgrading. +> **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 you have: +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)) -- Ensured build environment has internet access for asset downloads +- Verified that build environment has internet access for asset downloads when LaTeX and/or Mermaid is used Once ready, update the Hugo module: @@ -56,11 +56,11 @@ menu: ### 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 +- **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! +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) @@ -121,39 +121,47 @@ params: ### 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 +- **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 ## 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 +- **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 +- **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 +Here's a list of breaking changes to pay attention before upgrading + +- [**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 @@ -185,20 +193,6 @@ Hextra v0.10.0 introduces consistent `hextra-` prefixing for majority of compone | 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