mirror of
https://github.com/imfing/hextra.git
synced 2025-08-23 10:07:11 -04:00
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.
This commit is contained in:
Xin
@@ -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!
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user