hextra_mirror/v0.10.md at cc6d7e6e94ae102a95a6e4794503f46ef9baa42e

drowl87/hextra_mirror

Fork 1

mirror of https://github.com/imfing/hextra.git synced 2025-08-23 06:26:44 -04:00

Files

Xin cc6d7e6e94 Update v0.10.md

2025-08-14 01:48:52 +08:00

9.9 KiB

Raw Blame History

title, date, authors, tags, draft

title

date

authors

New Features

Create dropdown menus in your navigation bar for better navigation items organization.

menu:
  main:
    - identifier: products
      name: "Products"
    - name: "Product A"
      parent: products
      url: "/product-a"
    - name: "Product B"
      parent: products
      url: "/product-b"

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

params:
  page:
    tabs:
      sync: true

Blog List Pagination

Pagination controls have been added to blog listing pages.

params:
  blog:
    list:
      pagerSize: 20 # Posts per page

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 for pushing the search capabilities forward!

llms.txt Support

Hextra now supports llms.txt output format for your site, making your site more accessible to AI tools and language models for context and reference.

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.

MathJax Support

Render mathematical expressions with MathJax alongside the default KaTeX support. Choose the engine that best fits your needs.

params:
  math:
    engine: "mathjax" # default is "katex"

Technical Improvements

Framework and Build System

Tailwind CSS v4 Migration: Complete migration to Tailwind CSS v4 with improved customization support.
Hugo Template System: Adapted to Hugo's new template system (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

Breaking Changes

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`

Migration steps:

Search your custom CSS files for any of the "Before" class names
Replace them with the corresponding "After" class names
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.