drowl87/hextra_mirror
1
0
Fork 1
mirror of https://github.com/imfing/hextra.git synced 2025-08-24 18:59:00 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

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

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

* Update v0.10.md

* Update v0.10.md to refine upgrade instructions and enhance blog features. Added synchronized tab switching and pagination controls, while improving the search experience and table of contents navigation.

* Enhance v0.10 release documentation with detailed upgrade instructions and migration guide. Added Tailwind theme variable customization section and clarified breaking changes. Improved clarity on CSS class prefix changes for better user experience.

* 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.

* Add notable new features to v0.10.md, including dropdown menu support, enhanced search experience, and blog list pagination. Updated FlexSearch upgrade details for clarity and improved migration guide by removing redundant breaking change notes.

* chore: update zh-cn translation

* chore: update ja translation

* chore: update fa and ja translations

* chore: prepare release
This commit is contained in:
Xin
2025-08-14 23:49:06 +08:00
committed by GitHub
parent eca7665571
commit ec007d73c0
85 changed files with 4172 additions and 1545 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
exampleSite/content/blog/v0.10.md
View File

@@ -1,5 +1,5 @@
---
title: "Hextra v0.10.0 is released"
title: "Hextra v0.10"
date: 2025-08-14
authors:
- name: imfing
@@ -7,26 +7,176 @@ authors:
image: https://github.com/imfing.png
tags:
- Release
draft: true
---
Hextra v0.10.0 is a big release packed with new capabilities, architectural upgrades, and quality-of-life improvements.
<!--more-->
## What's New
It also includes contributions from 10 [new contributors](#contributors) and addresses long-standing community requests.
TODO
## Upgrade Guide
To upgrade to v0.10.0, update your Hugo module:
> [!IMPORTANT]
> **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 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))
- Verified that build environment has internet access for asset downloads when LaTeX and/or Mermaid is used
Once ready, update the Hugo module:
```bash
hugo mod get -u github.com/imfing/hextra@v0.10.0
```
## New Features
Here is a list of notable new features in this release:
- [**Dropdown Menu Support in Navbar**](#dropdown-menu-support-in-navbar): create hierarchical navigation menus
- [**Enhanced Search Experience**](#enhanced-search-experience): improved search across all headings with better accuracy
- [**llms.txt Support**](#llmstxt-support): generate AI-friendly site outline
- [**Table of Contents Scroll Highlighting**](#table-of-contents-scroll-highlighting): automatic heading highlighting during page scroll
- [**Synchronized Tab Switching**](#synchronized-tab-switching): synchronize tab selections across multiple tab groups
- [**Blog List Pagination**](#blog-list-pagination): add pagination controls to blog listing pages
- [**MathJax Support**](#mathjax-support): alternative math rendering engine alongside KaTeX
### 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)
### 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
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)
### 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.
![Example llms txt](https://github.com/user-attachments/assets/c6e929bb-0fce-4ab2-af15-a71c5a38b22c)
### 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)
### 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
Basic 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)
### 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 [FlexSearch](https://github.com/nextapps-de/flexsearch) 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
- **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
---
## Migration Guide
### CSS class prefix
- [**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
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.
#### 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
**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 +200,48 @@ This release includes a comprehensive CSS class naming refactor to improve consi
| Success icon | `.success-icon` | `.hextra-success-icon` |
| Steps | `.steps` | `.hextra-steps` |
---
#### Asset Management for KaTeX and Mermaid
_This is a draft release announcement. The actual release date and features may vary._
**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 `hx-*`
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
- Utility classes now prefix with `hx:` rather than `hx-`
## 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