mirror of
https://github.com/imfing/hextra.git
synced 2025-10-31 17:24:52 -04:00
chore(docs): rename exampleSite to docs and create examples (#813)
* chore(docs): rename `exampleSite` to `docs` and create `examples` * chore(build): update build script to support new version format and source directories; add v0.10 to documentation menu
This commit is contained in:
Xin
247
docs/content/blog/v0.10.md
Normal file
247
docs/content/blog/v0.10.md
Normal file
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Hextra v0.10"
|
||||
date: 2025-08-14
|
||||
authors:
|
||||
- name: imfing
|
||||
link: https://github.com/imfing
|
||||
image: https://github.com/imfing.png
|
||||
tags:
|
||||
- Release
|
||||
---
|
||||
|
||||
Hextra v0.10.0 is a big release packed with new capabilities, architectural upgrades, and quality-of-life improvements.
|
||||
|
||||
<!--more-->
|
||||
|
||||
It also includes contributions from 10 [new contributors](#contributors) and addresses long-standing community requests.
|
||||
|
||||
## Upgrade Guide
|
||||
|
||||
> [!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"
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 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!
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
- [**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
|
||||
|
||||
**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 |
|
||||
| -------------------- | ---------------------------- | ------------------------------------------------- |
|
||||
| Search (container) | `.search-wrapper` | `.hextra-search-wrapper` |
|
||||
| Search (input) | `.search-input` | `.hextra-search-input` |
|
||||
| Search (results) | `.search-results` | `.hextra-search-results` |
|
||||
| Search (title) | `.search-wrapper .title` | `.hextra-search-wrapper .hextra-search-title` |
|
||||
| Search (active item) | `.search-wrapper .active` | `.hextra-search-wrapper .hextra-search-active` |
|
||||
| Search (no result) | `.search-wrapper .no-result` | `.hextra-search-wrapper .hextra-search-no-result` |
|
||||
| Search (prefix) | `.search-wrapper .prefix` | `.hextra-search-wrapper .hextra-search-prefix` |
|
||||
| Search (excerpt) | `.search-wrapper .excerpt` | `.hextra-search-wrapper .hextra-search-excerpt` |
|
||||
| Search (match) | `.search-wrapper .match` | `.hextra-search-wrapper .hextra-search-match` |
|
||||
| Navbar blur | `.nav-container-blur` | `.hextra-nav-container-blur` |
|
||||
| Hamburger menu | `.hamburger-menu` | `.hextra-hamburger-menu` |
|
||||
| Theme toggle | `.theme-toggle` | `.hextra-theme-toggle` |
|
||||
| Language switcher | `.language-switcher` | `.hextra-language-switcher` |
|
||||
| Sidebar container | `.sidebar-container` | `.hextra-sidebar-container` |
|
||||
| Sidebar active item | `.sidebar-active-item` | `.hextra-sidebar-active-item` |
|
||||
| Code filename | `.filename` | `.hextra-code-filename` |
|
||||
| Copy icon | `.copy-icon` | `.hextra-copy-icon` |
|
||||
| Success icon | `.success-icon` | `.hextra-success-icon` |
|
||||
| Steps | `.steps` | `.hextra-steps` |
|
||||
|
||||
#### 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 `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
|
||||
Reference in New Issue
Block a user