CapBase – Blog

Hextra v0.12

Fri, 20 Feb 2026 00:00:00 +0000

Hextra v0.12.0 مجموعه‌ای غنی از ویژگی‌های جدید شامل منوی زمینه صفحه، زوم تصویر، تب‌های بازطراحی‌شده و موارد بیشتر، به همراه بهبودهای جامع دسترس‌پذیری WCAG 2.2 AA و رفع اشکالات متعدد ارائه می‌دهد.

راهنمای ارتقا

برای بیشتر سایت‌ها تغییر شکست‌آمیزی وجود ندارد. با استفاده از Hugo Modules به‌روزرسانی کنید:

hugo mod get -u github.com/imfing/hextra

نکات برجسته

منوی زمینه صفحه برای کپی/مشاهده سورس Markdown
بازطراحی شورت‌کد تب‌ها با نام‌گذاری هر تب و پشتیبانی از آیکون
زوم با کلیک برای تصاویر Markdown
پشتیبانی از تحلیل‌گر GoatCounter
گزینه مخفی‌کردن نوار کناری اصلی در دسکتاپ
نمایش آخرین نویسنده ویرایش‌کننده از طریق GitInfo
گزینه غیرفعال‌سازی ناوبری قبلی/بعدی
صفحه آرشیو داخلی برای فهرست زمانی نوشته‌های وبلاگ
شورت‌کد و چیدمان واژه‌نامه
حذف صفحات/بخش‌ها از llms.txt
ترتیب و برچسب‌های نوار کناری موبایل هم‌راستا با menu.main
عرض محتوای پایدار با پشتیبانی از بازنویسی متغیر CSS
بهبودهای جامع دسترس‌پذیری WCAG 2.2 AA

ویژگی‌های جدید

منوی زمینه صفحه

منوی زمینه صفحه دکمه‌ای کشویی فراهم می‌کند که با آن می‌توانید محتوای صفحه را به‌صورت Markdown کپی کنید یا سورس خام Markdown را مشاهده نمایید. با افزایش کاربرانی که مستندات را به ابزارهای هوش مصنوعی مولّد می‌دهند، دسترسی سریع به Markdown تمیز بسیار مفید است. پیوندهای سفارشی با متغیرهای قالب ({url}، {title}، {markdown_url}) به شما امکان می‌دهند میان‌برهای «از AI بپرس» یا سایر یکپارچه‌سازی‌ها را مستقیماً در منو ایجاد کنید.

برای استفاده از قابلیت‌های «مشاهده به‌صورت Markdown» و {markdown_url}، فرمت خروجی Markdown را در پیکربندی سایت فعال کنید:

hugo.yaml

outputs:
 page: [html, markdown]
 section: [html, rss, markdown]

سپس منوی زمینه را پیکربندی کنید:

hugo.yaml

params:
 page:
 contextMenu:
 enable: true
 links:
 - name: "Ask AI"
 url: "https://example.com?content={markdown_url}"
 icon: "sparkles"

بازطراحی تب‌ها و پشتیبانی از آیکون

شورت‌کد تب‌ها بازطراحی شده است. اکنون می‌توان نام تب‌ها را مستقیماً روی هر شورت‌کد tab تنظیم کرد و پارامتر اختیاری icon یک آیکون قبل از برچسب تب نمایش می‌دهد. نحو قبلی همچنان پشتیبانی می‌شود.

{{< tabs >}}
 {{< tab name="Photos" icon="photograph" >}}مدیریت و سازماندهی کتابخانه عکس‌های شما.{{< /tab >}}
 {{< tab name="Music" icon="music-note" >}}مرور و پخش آهنگ‌های مورد علاقه شما.{{< /tab >}}
 {{< tab name="Videos" icon="film" >}}تماشا و پخش محتوای ویدیویی.{{< /tab >}}
{{< /tabs >}}

زوم تصویر

با یک گزینه پیکربندی جدید، زوم با کلیک را روی تصاویر Markdown فعال کنید. این قابلیت از medium-zoom استفاده می‌کند.

hugo.yaml

params:
 imageZoom:
 enable: true

تحلیل‌گر GoatCounter

پشتیبانی داخلی از تحلیل‌گر GoatCounter در کنار یکپارچه‌سازی‌های موجود Google Analytics، Umami و Matomo.

مخفی‌کردن نوار کناری اصلی

یک پارامتر جدید فرانت‌متر امکان مخفی‌کردن نوار کناری اصلی در دسکتاپ را فراهم می‌کند تا صفحات محتوا عرض کامل داشته باشند.

content/my-page.md

---
title: My Page
sidebar:
 hide: true
---

آخرین نویسنده ویرایش‌کننده

با استفاده از GitInfo هوگو، آخرین نویسنده کامیت را در کنار تاریخ «آخرین به‌روزرسانی» نمایش دهید.

hugo.yaml

params:
 displayUpdatedAuthor: true

غیرفعال‌سازی ناوبری قبلی/بعدی

دکمه‌های ناوبری قبلی/بعدی را در سطح سایت غیرفعال کنید:

hugo.yaml

params:
 page:
 displayPagination: false

حذف از LLMs.txt

با تنظیم llms: false در فرانت‌متر، صفحات یا بخش‌های کامل را از خروجی llms.txt حذف کنید.

content/private-page.md

---
title: "Private Page"
llms: false
---

صفحه آرشیو

چیدمان جدید داخلی archives نوشته‌های وبلاگ را در یک خط زمانی گروه‌بندی‌شده بر اساس سال نمایش می‌دهد و برچسب‌ها به‌صورت درون‌خطی پس از عنوان هر نوشته نشان داده می‌شوند.

content/archives/_index.md

---
title: Archives
layout: archives
---

واژه‌نامه

یک واژه‌نامه اصطلاحات سراسری سایت با صفحه فهرست اختصاصی و شورت‌کد term برای تعاریف درون‌خطی.

دسترس‌پذیری

بهبودهای جامع دسترس‌پذیری WCAG 2.2 AA (#924):

پیوند رفتن به محتوا و نقش‌های نشانه‌ای ARIA در تمام صفحات
ویژگی‌های ARIA برای تمام ابزارک‌های تعاملی (کلید تغییر تم، تب‌ها، نوار کناری، درخت فایل، منوهای بازشو، جستجو، منوها)
ناوبری صفحه‌کلیدی برای تب‌ها و کلید تغییر تم (کلیدهای جهتی، Enter، Escape)
پشتیبانی از prefers-reduced-motion و سبک‌های سراسری focus-visible
۱۵ کلید دسترس‌پذیری i18n جدید با ترجمه کامل در تمام ۲۱ محلی‌سازی
جایگزینی تمام رشته‌های انگلیسی aria-label که به‌صورت هاردکد بودند با جستجوی i18n

بهبودهای کیفیت زندگی

بهبود سبک‌های خوانایی جدول
پشتیبانی از ویژگی‌های Markdown برای سرتیترها
تشخیص بهتر پیوند فعال برای صفحات فرود بخش چندزبانه
پشتیبانی شورت‌کد کارت از پارامتر اختیاری alt برای تصاویر
پشتیبانی از تصاویر بسته صفحه در ابرداده OpenGraph
عرض محتوا اکنون به‌صورت پیش‌فرض ثابت است، با پشتیبانی از بازنویسی متغیر CSS برای چیدمان‌های سفارشی

رفع اشکالات

جلوگیری از پیشوند پایه دوگانه relref در render-link
رفع رندر تب‌ها هنگام تودرتوبودن در مراحل
هم‌راستاسازی ترتیب و برچسب‌های نوار کناری موبایل با menu.main
رعایت search.enable در نوار کناری
رعایت پارامتر صفحه toc در منوی بازشو موبایل
بهبود برجسته‌سازی تطبیق FlexSearch و دستکاری امن DOM
رفع موقعیت زیرعنوان کارت
مدیریت اسلش‌های ابتدایی در مسیرهای تصویر OG برای استقرارهای زیرمسیر
رفع بازگرداندن صفحات نتیجه کمتر از حد انتظار توسط FlexSearch
تغییر فایل پیش‌فرض Umami analytics به script.js
رفع جستجوی نویسنده RSS برای Hugo v0.156.0+ (.Site.Params.Author)

مستندات و بومی‌سازی

افزودن بومی‌سازی ایتالیایی
پیوند مستندات KaTeX
به‌روزرسانی مستندات شورت‌کد details به نحو angle bracket

مشارکت‌کنندگان

این انتشار با مشارکت ۱۱ مشارکت‌کننده جدید ممکن شد:

@ghac101 - رفع Umami analytics، غیرفعال‌سازی ناوبری قبلی/بعدی
@pmarrapese - پشتیبانی از ویژگی‌های Markdown برای سرتیترها
@Bubbler-4 - مستندات شورت‌کد details
@bloovis - رفع تعداد نتایج FlexSearch
@AntoninPvr - رفع موقعیت زیرعنوان کارت
@illia-v - رفع TOC موبایل و کلید تغییر جستجو
@gallochri - بومی‌سازی ایتالیایی
@MatheusFlausino - حذف از LLMs.txt
@daniseijo - قابلیت آخرین نویسنده ویرایش‌کننده
@confusedkernel - صفحه آرشیو
@Fenyutanchan - رفع سازگاری نویسنده RSS با Hugo v0.156.0

همچنین از مشارکت‌کنندگان بازگشته @KStocky، @ldez، @kowyo، @torbjornbp، @yuri1969 و @PrintN بابت مشارکت‌های مداوم‌شان سپاسگزاریم.

تغییرات کامل: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0

Hextra v0.12

Fri, 20 Feb 2026 00:00:00 +0000

Hextra v0.12.0 は、ページコンテキストメニュー、画像ズーム、刷新されたタブ、その他多くの新機能に加え、包括的な WCAG 2.2 AA アクセシビリティ改善と多数のバグ修正を提供します。

アップグレードガイド

ほとんどのサイトで破壊的変更はありません。Hugo Modules を使って更新してください:

hugo mod get -u github.com/imfing/hextra

ハイライト

Markdown ソースのコピー・表示ができるページコンテキストメニュー
タブ名指定とアイコンをサポートする刷新されたタブショートコード
Markdown 画像のクリックズーム
GoatCounter アナリティクス対応
デスクトップでメインサイドバーを非表示にするオプション
GitInfo による最終更新者の表示
前へ/次へナビゲーションの無効化オプション
ブログ記事の年別アーカイブページ
用語集ショートコードとレイアウト
llms.txt からのページ/セクション除外
モバイルサイドバーの順序とラベルが menu.main に準拠
CSS 変数オーバーライドによる安定したコンテンツ幅
包括的な WCAG 2.2 AA アクセシビリティ改善

新機能

ページコンテキストメニュー

ページコンテキストメニューはドロップダウンボタンを提供し、ページの内容を Markdown としてコピーしたり、生の Markdown ソースを表示できます。ドキュメントを生成 AI ツールに取り込むユーザーが増える中、クリーンな Markdown への素早いアクセスはますます有用です。テンプレート変数（{url}、{title}、{markdown_url}）を使ったカスタムリンクにより、「AI に質問」ショートカットなどのインテグレーションをメニューに直接組み込めます。

「Markdown として表示」および {markdown_url} 機能を利用するには、サイト設定で Markdown 出力フォーマットを有効にしてください:

hugo.yaml

outputs:
 page: [html, markdown]
 section: [html, rss, markdown]

次にコンテキストメニューを設定します:

hugo.yaml

params:
 page:
 contextMenu:
 enable: true
 links:
 - name: "Ask AI"
 url: "https://example.com?content={markdown_url}"
 icon: "sparkles"

タブの刷新とアイコン対応

タブショートコードが刷新されました。各 tab ショートコードでタブ名を直接設定でき、オプションの icon パラメータでラベルの前にアイコンを表示できます。従来の構文も引き続きサポートされています。

{{< tabs >}}
 {{< tab name="Photos" icon="photograph" >}}写真ライブラリを管理・整理します。{{< /tab >}}
 {{< tab name="Music" icon="music-note" >}}お気に入りの曲を閲覧・再生します。{{< /tab >}}
 {{< tab name="Videos" icon="film" >}}動画コンテンツを視聴・ストリーミングします。{{< /tab >}}
{{< /tabs >}}

画像ズーム

medium-zoom を利用した新しい設定オプションで、Markdown 画像のクリックズームを有効にできます。

hugo.yaml

params:
 imageZoom:
 enable: true

GoatCounter アナリティクス

既存の Google Analytics、Umami、Matomo に加え、GoatCounter アナリティクスの組み込みサポートを追加しました。

メインサイドバーの非表示

新しいフロントマターパラメータにより、デスクトップでメインサイドバーを非表示にしてコンテンツを全幅表示できます。

content/my-page.md

---
title: My Page
sidebar:
 hide: true
---

最終更新者の表示

Hugo の GitInfo を使って、「最終更新日」と合わせて最終コミット者を表示します。

hugo.yaml

params:
 displayUpdatedAuthor: true

前へ/次へナビゲーションの無効化

サイト全体で前へ/次へナビゲーションボタンを無効にできます:

hugo.yaml

params:
 page:
 displayPagination: false

LLMs.txt 除外

フロントマターで llms: false を設定すると、個別のページやセクション全体を llms.txt 出力から除外できます。

content/private-page.md

---
title: "Private Page"
llms: false
---

アーカイブページ

新しい組み込み archives レイアウトは、ブログ記事を年ごとにグループ化した時系列タイムラインで表示し、各タイトルの後にタグをインラインで表示します。

content/archives/_index.md

---
title: Archives
layout: archives
---

用語集

サイト全体の用語集。専用のリストページとインライン定義用の term ショートコードを備えています。

アクセシビリティ

包括的な WCAG 2.2 AA アクセシビリティ改善 (#924):

すべてのページに本文へスキップリンクと ARIA ランドマークロール
すべてのインタラクティブウィジェット（テーマトグル、タブ、サイドバー、ファイルツリー、ドロップダウン、検索、メニュー）に ARIA 属性
タブとテーマトグルのキーボードナビゲーション（矢印キー、Enter、Escape）
prefers-reduced-motion サポートとグローバル focus-visible スタイル
全 21 ロケールに完全翻訳された 15 個の新しい i18n アクセシビリティキー
ハードコードされた英語 aria-label 文字列をすべて i18n ルックアップに置き換え

利便性の向上

テーブルの読みやすさ向上のためのスタイル改善
ヘッダーでの Markdown 属性サポート
多言語セクションランディングページでのアクティブリンク検出の改善
カードショートコードで画像に alt パラメータをオプションでサポート
ページバンドル画像が OpenGraph メタデータでサポート
コンテンツ幅がデフォルトで安定し、カスタムレイアウト用の CSS 変数オーバーライドをサポート

修正

render-link での relref ベースプレフィックスの二重付与を修正
ステップ内にネストされたタブの描画を修正
モバイルサイドバーの順序とラベルを menu.main に準拠
サイドバーでの search.enable の尊重
モバイルドロップダウンでの toc ページパラメータの尊重
FlexSearch のマッチハイライトと安全な DOM 操作の改善
カードのサブタイトル位置の修正
サブパスデプロイメントでの OG 画像パスの先頭スラッシュの処理
FlexSearch が期待より少ない結果ページを返す問題の修正
Umami アナリティクスのデフォルトファイルを script.js に変更
Hugo v0.156.0+ での RSS author ルックアップの修正 (.Site.Params.Author)

ドキュメントと i18n

イタリア語ローカリゼーションを追加
KaTeX ドキュメントへのリンクを追加
details ショートコードのドキュメントを angle bracket 構文に更新

コントリビューター

このリリースは 11 名の新しいコントリビューターの貢献により実現しました:

@ghac101 - Umami アナリティクスの修正、前へ/次へナビゲーションの無効化
@pmarrapese - ヘッダーの Markdown 属性サポート
@Bubbler-4 - details ショートコードのドキュメント
@bloovis - FlexSearch の結果件数修正
@AntoninPvr - カードのサブタイトル位置修正
@illia-v - モバイル TOC と検索トグルの修正
@gallochri - イタリア語ローカリゼーション
@MatheusFlausino - LLMs.txt 除外
@daniseijo - 最終更新者機能
@confusedkernel - アーカイブページ
@Fenyutanchan - Hugo v0.156.0 RSS author 互換性修正

さらに、継続的な貢献をいただいている @KStocky、@ldez、@kowyo、@torbjornbp、@yuri1969、@PrintN の各コントリビューターに感謝いたします。

完全な変更履歴: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0

Hextra v0.12

Fri, 20 Feb 2026 00:00:00 +0000

Hextra v0.12.0 delivers a rich set of new features including page context menus, image zoom, redesigned tabs, and more, plus comprehensive WCAG 2.2 AA accessibility improvements and numerous bug fixes.

Upgrade Guide

No breaking changes are expected for most sites. Update using Hugo Modules:

hugo mod get -u github.com/imfing/hextra

Highlights

Page context menu for copying/viewing Markdown source
Redesigned tabs shortcode with per-tab naming and icon support
Click-to-zoom for Markdown images
GoatCounter analytics support
Option to hide the main sidebar on desktop
Display last modified author via GitInfo
Option to disable prev/next navigation
Built-in archives page for chronological blog post listings
Term glossary shortcode and layout
Exclude pages/sections from llms.txt
Mobile sidebar ordering and labels aligned with menu.main
Stable content width with CSS variable override support
Comprehensive WCAG 2.2 AA accessibility improvements

New Features

Page Context Menu

The page context menu provides a dropdown button that lets you copy the page content as Markdown or view the raw Markdown source. As more users feed documentation into generative AI tools, having quick access to clean Markdown is increasingly useful. Custom links with template variables ({url}, {title}, {markdown_url}) let you wire up “Ask AI” shortcuts or other integrations directly in the menu.

To use the “View as Markdown” and {markdown_url} features, enable the Markdown output format in your site configuration:

hugo.yaml

outputs:
 page: [html, markdown]
 section: [html, rss, markdown]

Then configure the context menu:

hugo.yaml

params:
 page:
 contextMenu:
 enable: true
 links:
 - name: "Ask AI"
 url: "https://example.com?content={markdown_url}"
 icon: "sparkles"

Tabs Revamp and Icon Support

The tabs shortcode has been redesigned. Tab names can now be set directly on each tab shortcode, and an optional icon parameter displays an icon before the tab label. The previous syntax is still supported.

{{< tabs >}}
 {{< tab name="Photos" icon="photograph" >}}Manage and organize your photo library.{{< /tab >}}
 {{< tab name="Music" icon="music-note" >}}Browse and play your favorite tracks.{{< /tab >}}
 {{< tab name="Videos" icon="film" >}}Watch and stream video content.{{< /tab >}}
{{< /tabs >}}

Image Zoom

Enable click-to-zoom on Markdown images with a new configuration option, powered by medium-zoom.

hugo.yaml

params:
 imageZoom:
 enable: true

GoatCounter Analytics

Built-in support for GoatCounter analytics alongside existing Google Analytics, Umami, and Matomo integrations.

Hide Main Sidebar

A new front matter parameter allows hiding the main sidebar on desktop to give content pages the full width.

content/my-page.md

---
title: My Page
sidebar:
 hide: true
---

Last Modified Author

Display the last commit author alongside the “last updated” date using Hugo’s GitInfo.

hugo.yaml

params:
 displayUpdatedAuthor: true

Disable Prev/Next Navigation

Disable the previous/next navigation buttons site-wide:

hugo.yaml

params:
 page:
 displayPagination: false

LLMs.txt Exclusion

Exclude individual pages or entire sections from llms.txt output by setting llms: false in front matter.

content/private-page.md

---
title: "Private Page"
llms: false
---

Archives Page

A new built-in archives layout displays blog posts in a chronological timeline grouped by year, with tags shown inline after each post title.

content/archives/_index.md

---
title: Archives
layout: archives
---

Glossary

A site-wide terminology glossary with a dedicated listing page and a term shortcode for inline definitions.

Accessibility

Comprehensive WCAG 2.2 AA accessibility improvements (#924):

Skip-to-content link and ARIA landmark roles on all pages
ARIA attributes on all interactive widgets (theme toggle, tabs, sidebar, filetree, dropdowns, search, menus)
Keyboard navigation for tabs and theme toggle (arrow keys, Enter, Escape)
prefers-reduced-motion support and global focus-visible styles
15 new i18n accessibility keys with full translations across all 21 locales
Replaced all hardcoded English aria-label strings with i18n lookups

Quality of Life

Improved table readability styles
Markdown attribute support for headers
Better active link detection for multilingual section landing pages
Card shortcode supports optional alt parameter for images
Page bundle images supported in OpenGraph metadata
Content width now stays consistent by default, with CSS variable override support for custom layouts

Fixes

Prevent relref double base-prefix in render-link
Fix tabs rendering when nested inside steps
Align mobile sidebar ordering and labels with menu.main
Respect search.enable in the sidebar
Respect the toc page parameter in mobile dropdown
Enhance FlexSearch match highlighting and safe DOM manipulation
Fix card subtitle positioning
Handle leading slashes in OG image paths for subpath deployments
Fix FlexSearch returning fewer than expected result pages
Change default Umami analytics file to script.js
Fix RSS author lookup for Hugo v0.156.0+ (.Site.Params.Author)

Documentation & i18n

Add Italian localization
Link KaTeX documentation
Update details shortcode docs to angle bracket syntax

Contributors

This release was made possible by contributions from 11 new contributors:

@ghac101 - Umami analytics fix, disable prev/next navigation
@pmarrapese - Markdown attribute support for headers
@Bubbler-4 - Details shortcode documentation
@bloovis - FlexSearch result count fix
@AntoninPvr - Card subtitle positioning fix
@illia-v - Mobile TOC and search toggle fixes
@gallochri - Italian localization
@MatheusFlausino - LLMs.txt exclusion
@daniseijo - Last modified author feature
@confusedkernel - Archives page
@Fenyutanchan - Hugo v0.156.0 RSS author compatibility fix

Additional thanks to returning contributors @KStocky, @ldez, @kowyo, @torbjornbp, @yuri1969, and @PrintN for their continued contributions.

Full Changelog: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0

Hextra v0.12

Fri, 20 Feb 2026 00:00:00 +0000

Hextra v0.12.0 带来了丰富的新功能，包括页面上下文菜单、图片缩放、全新设计的标签页等，同时提供全面的 WCAG 2.2 AA 无障碍改进和大量错误修复。

升级指南

对大多数站点而言没有破坏性变更。使用 Hugo Modules 更新：

hugo mod get -u github.com/imfing/hextra

亮点

页面上下文菜单，可复制/查看 Markdown 源码
全新设计的标签页短代码，支持单独命名和图标
Markdown 图片点击缩放
GoatCounter 分析支持
桌面端隐藏主侧边栏选项
通过 GitInfo 显示最后修改作者
禁用上一篇/下一篇导航选项
内置归档页面，按时间顺序列出博客文章
术语表短代码和布局
从 llms.txt 中排除页面/章节
移动端侧边栏排序和标签与 menu.main 对齐
通过 CSS 变量覆盖支持稳定的内容宽度
全面的 WCAG 2.2 AA 无障碍改进

新功能

页面上下文菜单

页面上下文菜单提供下拉按钮，可将页面内容复制为 Markdown 或查看原始 Markdown 源码。随着越来越多用户将文档输入生成式 AI 工具，快速获取干净的 Markdown 变得越来越有用。通过模板变量（{url}、{title}、{markdown_url}）添加自定义链接，可以在菜单中直接集成“询问 AI”快捷方式或其他功能。

要使用“以 Markdown 查看”和 {markdown_url} 功能，请在站点配置中启用 Markdown 输出格式：

hugo.yaml

outputs:
 page: [html, markdown]
 section: [html, rss, markdown]

然后配置页面上下文菜单：

hugo.yaml

params:
 page:
 contextMenu:
 enable: true
 links:
 - name: "Ask AI"
 url: "https://example.com?content={markdown_url}"
 icon: "sparkles"

标签页重设计与图标支持

标签页短代码经过重新设计。现在可以直接在每个 tab 短代码上设置标签名称，可选的 icon 参数可在标签文字前显示图标。之前的语法仍然支持。

{{< tabs >}}
 {{< tab name="Photos" icon="photograph" >}}管理和整理您的照片库。{{< /tab >}}
 {{< tab name="Music" icon="music-note" >}}浏览和播放您喜爱的曲目。{{< /tab >}}
 {{< tab name="Videos" icon="film" >}}观看和串流视频内容。{{< /tab >}}
{{< /tabs >}}

图片缩放

通过新的配置选项，启用 Markdown 图片的点击缩放功能，基于 medium-zoom 实现。

hugo.yaml

params:
 imageZoom:
 enable: true

GoatCounter 分析

在现有的 Google Analytics、Umami 和 Matomo 集成之外，新增 GoatCounter 分析的内置支持。

隐藏主侧边栏

新的 Front Matter 参数允许在桌面端隐藏主侧边栏，使内容页面获得全宽显示。

content/my-page.md

---
title: My Page
sidebar:
 hide: true
---

最后修改作者

使用 Hugo 的 GitInfo 功能，在"最后更新"日期旁显示最后提交的作者。

hugo.yaml

params:
 displayUpdatedAuthor: true

hugo.yaml

params:
 page:
 displayPagination: false

LLMs.txt 排除

通过在 Front Matter 中设置 llms: false，将单个页面或整个章节从 llms.txt 输出中排除。

content/private-page.md

---
title: "Private Page"
llms: false
---

归档页面

新的内置 archives 布局按年份分组，以时间线形式展示博客文章，每篇文章标题后内联显示标签。

content/archives/_index.md

---
title: Archives
layout: archives
---

术语表

站点级术语表，提供专用列表页面和用于内联定义的 term 短代码。

无障碍

全面的 WCAG 2.2 AA 无障碍改进 (#924)：

所有页面添加跳转到内容链接和 ARIA 地标角色
所有交互组件（主题切换、标签页、侧边栏、文件树、下拉菜单、搜索、菜单）添加 ARIA 属性
标签页和主题切换的键盘导航（方向键、Enter、Escape）
支持 prefers-reduced-motion 和全局 focus-visible 样式
15 个新的 i18n 无障碍键，在全部 21 个语言环境中提供完整翻译
将所有硬编码的英文 aria-label 字符串替换为 i18n 查找

使用体验优化

改进表格可读性样式
标题支持 Markdown 属性
多语言章节着陆页的活动链接检测改进
卡片短代码支持可选的图片 alt 参数
OpenGraph 元数据支持页面资源包图片
内容宽度默认保持一致，支持通过 CSS 变量覆盖自定义布局

修复

修复 render-link 中 relref 基础前缀重复问题
修复嵌套在步骤中的标签页渲染
移动端侧边栏排序和标签与 menu.main 对齐
侧边栏中遵循 search.enable 设置
移动端下拉菜单中遵循 toc 页面参数
增强 FlexSearch 匹配高亮和安全的 DOM 操作
修复卡片副标题定位
处理子路径部署中 OG 图片路径的前导斜杠
修复 FlexSearch 返回结果页数少于预期的问题
将 Umami 分析的默认文件改为 script.js
修复 Hugo v0.156.0+ 的 RSS 作者查找 (.Site.Params.Author)

文档与 i18n

添加意大利语本地化
链接 KaTeX 文档
将 details 短代码文档更新为尖括号语法

贡献者

此版本由 11 位新贡献者共同参与完成：

@ghac101 - Umami 分析修复、禁用上一篇/下一篇导航
@pmarrapese - 标题 Markdown 属性支持
@Bubbler-4 - details 短代码文档
@bloovis - FlexSearch 结果计数修复
@AntoninPvr - 卡片副标题定位修复
@illia-v - 移动端目录和搜索切换修复
@gallochri - 意大利语本地化
@MatheusFlausino - LLMs.txt 排除
@daniseijo - 最后修改作者功能
@confusedkernel - 归档页面
@Fenyutanchan - Hugo v0.156.0 RSS 作者兼容性修复

同时感谢回归贡献者 @KStocky、@ldez、@kowyo、@torbjornbp、@yuri1969 和 @PrintN 的持续贡献。

完整变更日志: https://github.com/imfing/hextra/compare/v0.11.1...v0.12.0

Hextra v0.11

Sat, 30 Aug 2025 00:00:00 +0000

Hextra v0.11.0 بر صیقل UX و مؤلفه‌های جدید کاربردی تمرکز دارد: بنر سراسری سایت، کال‌اوت‌ها و بج‌های بهبودیافته، کارت‌های غنی‌تر، یکپارچه‌سازی تحلیل‌گرها، و چند بهبود ناوبری. همچنین شامل رفع اشکالات پایداری و به‌روزرسانی‌های مستندات است.

راهنمای ارتقا

برای بیشتر سایت‌ها تغییر شکست‌آمیزی وجود ندارد. با استفاده از Hugo Modules به‌روزرسانی کنید:

hugo mod get -u github.com/imfing/hextra

نکات برجسته

مؤلفه بنر بالایی برای اعلان‌ها
بازطراحی کال‌اوت‌ها با سبک‌های شفاف‌تر
پشتیبانی از تحلیل‌گرهای Umami و Matomo
شورت‌کد Asciinema برای ضبط‌های ترمینال
گزینهٔ تزئین پیوندهای خارجی
مسیر راهنما برای صفحات تکی (غیرِ مستندات/غیرِ وبلاگ)
بهبودهای نوار ناوبری: مورد پیوند با آیکون و جای‌گذاری بهتر
سفارشی‌سازی بهتر بج‌ها و کارت‌ها
کلید تغییر تم از گزینه «System» پشتیبانی می‌کند

ویژگی‌های جدید

بنر بالایی

یک بنر سراسری و قابلِ بستن برای اعلان‌ها، لانچ‌ها یا پیام‌های وضعیت اضافه کنید.

hugo.yaml

params:
 banner:
 key: "announcement"
 message: Welcome!

بازطراحی Callout

Callout برای خوانایی بهتر و تأکید مناسب در تمام تم‌ها بازطراحی شده است.

تحلیل‌گرها: Umami و Matomo

پیکربندی داخلی برای فراهم‌کنندگان تحلیل‌گر:

Umami
Matomo

شورت‌کد Asciinema

با استفاده از Asciinema و شورت‌کد Asciinema ضبط‌های ترمینال را درون‌گذاری کنید.

{{< asciinema id="123456" autoplay=true loop=true >}}

بهبودهای نوار ناوبری

پشتیبانی از آیکون برای موارد پیوند در نوار ناوبری
بهبود موقعیت منو برای هماهنگی با سوییچر زبان و سایر موارد

قابل ذکر است، نسخه 0.10.2 امکان افزودن سوییچر زبان و کلید تغییر تم به نوار ناوبری را فراهم می‌کند.

تزئین پیوند خارجی

به‌صورت اختیاری یک تزئین ظریفِ «پیوند خارجی» به پیوندهای خروجی اضافه کنید.

hugo.yaml

params:
 externalLinkDecoration: true

فعال‌سازی مسیر راهنما

با قرار دادن breadcrumbs: true در فرانت‌متر، مسیر راهنما را روی صفحات تکی (غیرِ مستندات/وبلاگ) فعال کنید.

content/about.md

---
title: About
breadcrumbs: true
---

بهبود کارت‌ها و بج‌ها

کارت‌ها: گزینه‌های جدید tagIcon و tagBorder.
بج‌ها: رنگ‌ها و سبک‌های حاشیهٔ جدید.

بهبودهای کیفیت زندگی

تغییر تم: افزودن گزینه «System»
تایپوگرافی: سبک‌های بهتر فهرست کار با چک‌باکس
سوییچر زبان: ترتیب‌دهی بهبود یافته همراه با موارد منوییِ آیکون‌دار

رفع اشکالات

Giscus: همگام‌سازی صحیح تم و زبان
کارت‌ها: رفع رندر بج در حالت RTL
نوار ناوبری: بهبود موقعیت و تعاملات منو

مستندات و بومی‌سازی

مستندات: صفحهٔ جدیدی دربارهٔ شورت‌کدهای Hextra
i18n: افزودن ترجمه‌های copyCode و system به zh-cn

تغییرات کامل: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

Hextra v0.11

Sat, 30 Aug 2025 00:00:00 +0000

Hextra v0.11.0 は、UX の磨き込みと便利な新コンポーネントに注力したリリースです。サイト全体バナー、改良されたコールアウトとバッジ、よりリッチなカード、アナリティクス連携、そしていくつかのナビゲーション改善を含みます。安定性の修正とドキュメント更新も同梱しています。

アップグレードガイド

ほとんどのサイトで破壊的変更はありません。Hugo Modules を使って更新してください:

hugo mod get -u github.com/imfing/hextra

ハイライト

お知らせ用のトップバナーコンポーネント
より見やすくなったコールアウトの刷新
Umami と Matomo のアナリティクス対応
端末録画のための Asciinema ショートコード
外部リンク装飾オプション
単一ページ（ドキュメント・ブログ以外）向けのパンくずリスト
ナビバー改善: アイコン付きリンク項目と配置の改善
バッジとカードのカスタマイズ性向上
テーマ切り替えに「System」オプションを追加

新機能

トップバナー

告知やリリース、ステータスメッセージ向けに、サイト全体で表示できる閉じられるバナーを追加します。

hugo.yaml

params:
 banner:
 key: "announcement"
 message: Welcome!

コールアウト刷新

Callout のデザインを刷新し、テーマを問わず可読性と強調表現を向上しました。

アナリティクス: Umami と Matomo

以下のアナリティクスプロバイダに組み込み設定で対応:

Umami
Matomo

Asciinema ショートコード

Asciinema の端末録画を、新しい Asciinema ショートコードで埋め込みできます。

{{< asciinema id="123456" autoplay=true loop=true >}}

ナビバーの改善

ナビバーのリンク項目でアイコンをサポート
言語スイッチャー等との兼ね合いを考慮してメニュー配置を最適化

特に、0.10.2 ではナビバーに言語スイッチャーとテーマトグルを追加可能になりました。

外部リンク装飾

外部リンクに控えめな装飾をオプションで付与できます。

hugo.yaml

params:
 externalLinkDecoration: true

パンくずリストの有効化

フロントマターで breadcrumbs: true を設定すると、単一ページ（ドキュメント・ブログ以外）でパンくずリストを有効化できます。

content/about.md

---
title: About
breadcrumbs: true
---

カードとバッジの改善

カード: 新オプション tagIcon と tagBorder
バッジ: 新しい色とボーダースタイル

利便性の向上

テーマ切り替え: 「System」オプションを追加
タイポグラフィ: チェックボックス付きタスクリストのスタイル改善
言語スイッチャー: アイコンメニュー項目との並び順を改善

修正

Giscus: テーマと言語の同期を適切に実施
カード: RTL でのバッジ描画を修正
ナビバー: メニュー配置とインタラクションを調整

ドキュメントと i18n

Docs: Hextra のショートコードをまとめた新ページ
i18n: zh-cn に copyCode と system の翻訳を追加

完全な変更履歴: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

Hextra v0.11

Sat, 30 Aug 2025 00:00:00 +0000

Hextra v0.11.0 focuses on UX polish and useful new components: site-wide banner, improved callouts and badges, richer cards, analytics integrations, and several navigation refinements. It also ships stability fixes and documentation updates.

Upgrade Guide

No breaking changes are expected for most sites. Update using Hugo Modules:

hugo mod get -u github.com/imfing/hextra

Highlights

Top banner component for announcements
Revamped callouts with clearer styles
Umami and Matomo analytics support
Asciinema shortcode for terminal recordings
External link decoration option
Breadcrumbs for single pages (non-docs, non-blogs)
Navbar enhancements: icon link item and improved positions
Improved badges and cards customization
Theme toggle supports “System”

New Features

Top Banner

Add a site-wide, dismissible banner for announcements, launches, or status messages.

hugo.yaml

params:
 banner:
 key: "announcement"
 message: Welcome!

Callout Revamp

Callout receive a design refresh for better readability and emphasis across themes.

Analytics: Umami and Matomo

Built-in configuration for analytics providers:

Umami
Matomo

Asciinema Shortcode

Embed terminal recordings from Asciinema using the new Asciinema shortcode.

{{< asciinema id="123456" autoplay=true loop=true >}}

Navbar Enhancements

Support icons for link items in the navbar
Refine menu positions to play nicely with the language switcher and other items

Notably, version 0.10.2 enables the addition of language switchers and theme toggles to the navbar.

External Link Decoration

Optionally add a subtle external-link decoration to outbound links.

hugo.yaml

params:
 externalLinkDecoration: true

Breadcrumbs Enablement

Enable breadcrumbs on single pages (non-docs, non-blogs) by setting breadcrumbs: true in front matter.

content/about.md

---
title: About
breadcrumbs: true
---

Cards and Badges Improvements

Cards: new tagIcon and tagBorder options.
Badges: new colors and border styles.

Quality of Life

Theme toggle: add “System” option
Typography: better task list styles with checkboxes
Language switcher: improved ordering with icon menu items

Fixes

Giscus: sync theme and language properly
Cards: fix badge rendering with RTL
Navbar: refine menu positions and interactions

Documentation & i18n

Docs: new page covering Hextra shortcodes
i18n: add copyCode and system translations to zh-cn

Full Changelog: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

Hextra v0.11

Sat, 30 Aug 2025 00:00:00 +0000

Hextra v0.11.0 专注于打磨使用体验并带来数个实用新组件：站点级顶部横幅、改进的提示框与徽章、更丰富的卡片、分析工具集成，以及多项导航优化。同时包含稳定性修复和文档更新。

升级指南

对大多数站点而言没有破坏性变更。使用 Hugo Modules 更新：

hugo mod get -u github.com/imfing/hextra

亮点

用于公告的顶栏横幅组件
重新设计的提示框，样式更清晰
支持 Umami 与 Matomo 分析
Asciinema 短代码用于终端录屏
外链装饰选项
单页（非文档、非博客）支持面包屑
导航栏增强：图标链接项与更优布局
徽章与卡片的自定义能力提升
主题切换增加「System」选项

新功能

顶部横幅

为公告、发布或状态消息添加一个站点级、可关闭的横幅。

hugo.yaml

params:
 banner:
 key: "announcement"
 message: Welcome!

提示框重设计

Callout 获得样式刷新，在各主题下具备更好的可读性与强调效果。

分析：Umami 与 Matomo

内置以下分析平台的配置支持：

Umami
Matomo

Asciinema 短代码

使用全新的 Asciinema 短代码嵌入 Asciinema 终端录屏。

{{< asciinema id="123456" autoplay=true loop=true >}}

导航栏增强

支持在导航栏链接项中使用图标
优化菜单的相对位置，使其与语言切换器等项协同更佳

值得一提的是，版本 0.10.2 已支持在导航栏添加语言切换器与主题切换。

外链装饰

可选地为外部链接添加轻量的外链标识装饰。

hugo.yaml

params:
 externalLinkDecoration: true

启用面包屑

在单页（非文档、非博客）上，通过在 Front Matter 中设置 breadcrumbs: true 启用面包屑。

content/about.md

---
title: About
breadcrumbs: true
---

卡片与徽章的改进

卡片：新增 tagIcon 与 tagBorder 选项。
徽章：新增颜色与边框样式。

使用体验优化

主题切换：增加「System」选项
字体排版：改进带复选框的任务列表样式
语言切换器：与图标菜单项的排序更合理

修复

Giscus：正确同步主题与语言
卡片：修复 RTL 场景下的徽章渲染
导航栏：优化菜单位置与交互

文档与 i18n

文档：新增页面介绍 Hextra 的短代码
i18n：为 zh-cn 增加 copyCode 与 system 翻译

完整变更日志: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

Hextra v0.10.0 یک انتشار بزرگ است که مملو از قابلیت‌های جدید، ارتقاهای معماری و بهبودهای کیفیت زندگی می‌باشد.

همچنین شامل مشارکت‌های 10 مشارکت‌کننده جدید بوده و درخواست‌های دیرینه جامعه را برطرف می‌کند.

راهنمای ارتقا

Important

تغییرات شکست‌آمیز: این انتشار شامل چندین تغییر شکست‌آمیز است. لطفاً قبل از ارتقا، چک‌لیست و راهنمای مهاجرت را بررسی کنید.

قبل از ارتقا به v0.10.0، مطمئن شوید که:

Hugo v0.146.0+ (نسخه extended) نصب شده است
CSS سفارشی را برای تغییرات نام کلاس بررسی کرده‌اید (به تغییرات پیشوند کلاس‌های CSS و Tailwind CSS v4 مراجعه کنید)
تأیید کرده‌اید که محیط ساخت دسترسی به اینترنت برای دانلود دارایی‌ها هنگام استفاده از LaTeX و/یا Mermaid دارد

پس از آماده‌سازی، ماژول Hugo را به‌روزرسانی کنید:

hugo mod get -u github.com/imfing/hextra@v0.10.0

ویژگی‌های جدید

در زیر لیستی از ویژگی‌های جدید قابل توجه در این انتشار آمده است:

پشتیبانی از منوی کشویی در نوار ناوبری: ایجاد منوهای ناوبری سلسله‌مراتبی
تجربه جستجوی بهبودیافته: جستجوی بهبودیافته در تمام سرتیترها با دقت بهتر
پشتیبانی از llms.txt: تولید خلاصه سایت مناسب برای هوش مصنوعی
هایلایت کردن اسکرول فهرست مطالب: هایلایت کردن خودکار سرتیترها هنگام اسکرول صفحه
تبدیل همگام تب‌ها: همگام‌سازی انتخاب تب‌ها در چندین گروه تب
صفحه‌بندی لیست وبلاگ: اضافه کردن کنترل‌های صفحه‌بندی به صفحات لیست وبلاگ
پشتیبانی از MathJax: موتور رندر ریاضی جایگزین در کنار KaTeX

پشتیبانی از منوی کشویی در نوار ناوبری

منوهای کشویی را در نوار ناوبری خود برای سازماندهی بهتر موارد ناوبری ایجاد کنید.

hugo.yaml

menu:
 main:
 - identifier: products
 name: "محصولات"
 - name: "محصول الف"
 parent: products
 url: "/product-a"
 - name: "محصول ب"
 parent: products
 url: "/product-b"

تجربه جستجوی بهبودیافته

جستجو در تمام سرتیترها: یافتن محتوا در تمام سطوح سرتیترها، نه فقط عنوان صفحات
دقت بهتر نتایج: مدیریت بهتر عنوان‌ها و دقت پیونددهی
ناوبری ثابت نتایج: نتایج جستجو اکنون به بخش‌های صحیح صفحه پیوند می‌خورند

با تشکر ویژه از @ldez برای پیشبرد قابلیت‌های جستجو!

پشتیبانی از llms.txt

Hextra اکنون از فرمت خروجی llms.txt برای سایت شما پشتیبانی می‌کند، که سایت شما را برای ابزارهای هوش مصنوعی و مدل‌های زبانی برای زمینه و مرجع قابل دسترس‌تر می‌سازد.

hugo.yaml

outputs:
 home: [html, llms]

این یک فایل llms.txt در ریشه سایت شما ایجاد می‌کند.

هایلایت کردن اسکرول فهرست مطالب

فهرست مطالب اکنون به‌طور خودکار بخش فعلی را هنگام اسکرول صفحه هایلایت می‌کند، که ناوبری را شهودی‌تر می‌سازد.

تبدیل همگام تب‌ها

تب‌هایی با موارد یکسان اکنون در سراسر صفحه همگام می‌شوند. هنگامی که همگام‌سازی فعال است، انتخاب یک تب تمام گروه‌های تب که لیست موارد یکسانی دارند را به‌روزرسانی می‌کند (و انتخاب شما به خاطر سپرده می‌شود).

hugo.yaml

params:
 page:
 tabs:
 sync: true

صفحه‌بندی لیست وبلاگ

کنترل‌های صفحه‌بندی پایه به صفحات لیست وبلاگ اضافه شده‌اند.

hugo.yaml

params:
 blog:
 list:
 pagerSize: 20 # پست‌ها در هر صفحه

پشتیبانی از MathJax

عبارات ریاضی را با MathJax در کنار پشتیبانی پیش‌فرض KaTeX رندر کنید. موتوری را انتخاب کنید که بهترین تناسب را با نیازهای شما دارد.

hugo.yaml

params:
 math:
 engine: "mathjax" # پیش‌فرض "katex" است

بهبودهای فنی

چارچوب و سیستم ساخت

مهاجرت به Tailwind CSS v4: مهاجرت کامل به Tailwind CSS v4 با پشتیبانی بهبودیافته سفارشی‌سازی.
سیستم قالب Hugo: سازگار با سیستم قالب جدید Hugo (v0.146.0+) برای سازگاری آینده.
رندر سمت سرور ریاضی: مدیریت بهتر رندر معادلات ریاضی با استفاده از رندر بومی Hugo به‌صورت پیش‌فرض.
ارتقای FlexSearch 0.8: ارتقای موتور جستجو FlexSearch برای نتایج سریع‌تر و دقیق‌تر با رمزگذاری بهبودیافته محتوای CJK (چینی، ژاپنی، کرهای).
مدیریت بهبودیافته دارایی‌ها: دارایی‌های KaTeX و Mermaid از بارگیری از CDN یا محلی پشتیبانی می‌کنند

بهبودهای کیفیت زندگی

تغییر دینامیک favicon: به‌روزرسانی خودکار favicon بر اساس ترجیحات طرح رنگ
صفحه‌بندی معکوس: نویسندگان اکنون می‌توانند reversePagination را در front matter صفحه تنظیم کنند
کنترل نمایه‌سازی گوگل: پارامتر صفحه جدید برای مسدود کردن نمایه‌سازی گوگل در صورت نیاز
بهبودهای مدیریت عرض: کنترل‌های طراحی پاسخگو بهتر از طریق متغیرهای CSS
بهبودهای استایل: استایل‌های مدرن برای جدول Markdown و خط افقی

رفع اشکالات و پایداری

همگام‌سازی تم Giscus: نظرات اکنون به درستی تغییرات حالت تاریک/روشن را دنبال می‌کنند
دقت نتایج جستجو: رفع مشکلات پیونددهی و فرار عنوان در نتایج جستجو
تبدیل تب‌ها: رفع مشکلات ناوبری در حالت غیرهمگام تب
اسکرول فانتوم: رفع رفتار ناخواسته اسکرول هنگام غیرفعال بودن پاورقی
دسترسی تصویر: جلوگیری از رندر تکراری متن alt
رندر پیوند: بهبود مدیریت URL پایه برای ساختارهای پیچیده سایت

راهنمای مهاجرت

نیازمندی‌های نسخه Hugo: نیاز به Hugo v0.146.0+ (نسخه extended) دارد
تغییرات پیشوند کلاس‌های CSS: کلاس‌های CSS کامپوننت اکنون از پیشوند سازگار hextra- استفاده می‌کنند
مدیریت دارایی‌ها: دارایی‌های KaTeX و Mermaid اکنون در زمان ساخت دانلود می‌شوند
Tailwind CSS v4: کامپایل CSS داخلی اکنون از Tailwind CSS v4.x با پیشوند hx: استفاده می‌کند

نیازمندی‌های نسخه Hugo

تأثیر: سایت‌هایی که از نسخه‌های قدیمی Hugo استفاده می‌کنند

Hextra v0.10.0 به دلیل پذیرش سیستم قالب جدید، نیاز به Hugo v0.146.0 یا بالاتر (نسخه extended) دارد.

اقدام مورد نیاز: قبل از ارتقای Hextra، Hugo را به v0.146.0+ به‌روزرسانی کنید

تغییرات پیشوند کلاس‌های CSS

تأثیر: سایت‌هایی با CSS سفارشی که کلاس‌های کامپوننت Hextra را هدف قرار می‌دهند

Hextra v0.10.0 پیشوند سازگار hextra- را برای اکثر کلاس‌های CSS کامپوننت معرفی می‌کند تا قابلیت نگهداری را بهبود بخشد و از تداخل با استایل‌های کاربر جلوگیری کند.

اقدام مورد نیاز: اگر CSS سفارشی دارید که کامپوننت‌های Hextra را هدف قرار می‌دهد، نام کلاس‌های زیر را به‌روزرسانی کنید:

حوزه	قبل	بعد
جستجو (ظرف)	`.search-wrapper`	`.hextra-search-wrapper`
جستجو (ورودی)	`.search-input`	`.hextra-search-input`
جستجو (نتایج)	`.search-results`	`.hextra-search-results`
جستجو (عنوان)	`.search-wrapper .title`	`.hextra-search-wrapper .hextra-search-title`
جستجو (مورد فعال)	`.search-wrapper .active`	`.hextra-search-wrapper .hextra-search-active`
جستجو (بدون نتیجه)	`.search-wrapper .no-result`	`.hextra-search-wrapper .hextra-search-no-result`
جستجو (پیشوند)	`.search-wrapper .prefix`	`.hextra-search-wrapper .hextra-search-prefix`
جستجو (گزیده)	`.search-wrapper .excerpt`	`.hextra-search-wrapper .hextra-search-excerpt`
جستجو (مطابقت)	`.search-wrapper .match`	`.hextra-search-wrapper .hextra-search-match`
تارنما محو	`.nav-container-blur`	`.hextra-nav-container-blur`
منوی همبرگر	`.hamburger-menu`	`.hextra-hamburger-menu`
تغییر تم	`.theme-toggle`	`.hextra-theme-toggle`
تغییر زبان	`.language-switcher`	`.hextra-language-switcher`
ظرف نوار کناری	`.sidebar-container`	`.hextra-sidebar-container`
مورد فعال نوار کناری	`.sidebar-active-item`	`.hextra-sidebar-active-item`
نام فایل کد	`.filename`	`.hextra-code-filename`
آیکون کپی	`.copy-icon`	`.hextra-copy-icon`
آیکون موفقیت	`.success-icon`	`.hextra-success-icon`
مراحل	`.steps`	`.hextra-steps`

مدیریت دارایی‌ها برای KaTeX و Mermaid

تأثیر: سایت‌هایی که از KaTeX یا Mermaid استفاده می‌کنند

Hextra v0.10.0 اکنون دارایی‌های KaTeX و Mermaid را از CDN در زمان ساخت دانلود می‌کند.

چه چیزی تغییر کرده است:

فرآیند ساخت اکنون نیاز به دسترسی به اینترنت برای دانلود این دارایی‌ها دارد
دیگر پس از ساخت، فراخوانی CDN خارجی برای این دارایی‌ها وجود ندارد

اقدام مورد نیاز:

مطمئن شوید که محیط ساخت شما دسترسی به اینترنت برای دانلود دارایی‌ها دارد
سایت‌های در محیط‌های ایزوله ممکن است نیاز به پیش‌دانلود این دارایی‌ها و پیکربندی Hextra برای بارگیری آنها داشته باشند

Tailwind CSS v4

تأثیر: سایت‌هایی با CSS سفارشی گسترده که کلاس‌های Tailwind Hextra hx-* را هدف قرار می‌دهند

در حالی که Hextra مهاجرت Tailwind CSS v4 را به صورت داخلی مدیریت می‌کند، سایت‌هایی با سفارشی‌سازی‌های سنگین ممکن است نیاز به تنظیمات بیشتری داشته باشند.

چه چیزی تغییر کرده است:

کامپایل CSS داخلی اکنون از Tailwind CSS v4.x استفاده می‌کند
کلاس‌های ابزار اکنون با پیشوند hx: به جای hx- هستند

مشارکت‌کنندگان

این انتشار با مشارکت‌های 10 مشارکت‌کننده جدید ممکن شد:

@oosquare - فونت‌های KaTeX، قلاب‌های رندر تصویر، بهبودهای مدیریت پیوند
@Zabriskije - رفع اسکرول فانتوم
@miniwater - مرکزسازی پاورقی سفارشی، بهبودهای متن alt تصویر
@MattDodsonEnglish - کنترل‌های نمایه‌سازی گوگل، مستندات OpenGraph
@KStocky - ویژگی صفحه‌بندی معکوس
@PrintN - اضافه شدن نمایش مستندات
@hobobandy - بهبودهای فاصله عنوان
@dlwocks31 - به‌روزرسانی ترجمه کرهای
@TwoAnts - رفع تغییر تم Giscus
@ldez - بهبودهای جستجو و رفع اشکالات

با تشکر ویژه از مشارکت‌کنندگان بازگشتی @deining و @yuri1969 برای حمایت مستمرشان در مستندات، ترجمه‌ها و بهبودهای فنی.

تغییرات کامل: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0

Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

Hextra v0.10.0 は、新機能、アーキテクチャの刷新、利便性向上を詰め込んだ大きなリリースです。

また、10名の新規コントリビューターからの貢献と、長らく要望のあった機能の実装も含まれています。

アップグレードガイド

Important

破壊的変更: このリリースにはいくつかの破壊的変更が含まれています。アップグレード前にチェックリストと移行ガイドを確認してください。

v0.10.0 にアップグレードする前に、以下を確認してください:

Hugo v0.146.0+ (extended 版) がインストールされていること
カスタムCSSのクラス名変更を確認 ( CSSクラスプレフィックス変更と Tailwind CSS v4 を参照)
LaTeX や Mermaid を使用する場合、ビルド環境がアセットダウンロードのためインターネットに接続できること

準備が整ったら、Hugoモジュールを更新します:

hugo mod get -u github.com/imfing/hextra@v0.10.0

新機能

このリリースの主な新機能は以下の通りです:

ナビゲーションバーのドロップダウンメニューサポート: 階層型ナビゲーションメニューの作成
検索機能の強化: すべての見出しを対象にした精度向上した検索
llms.txt サポート: AI向けサイトアウトラインの生成
目次のスクロールハイライト: ページスクロール中の見出し自動ハイライト
タブの同期切り替え: 複数のタブグループ間でのタブ選択の同期
ブログ一覧のページネーション: ブログ一覧ページへのページネーションコントロール追加
MathJax サポート: KaTeXに加えてMathJaxを数式レンダリングエンジンとして選択可能

ナビゲーションバーのドロップダウンメニューサポート

ナビゲーションバーにドロップダウンメニューを作成し、ナビゲーション項目を整理できます。

hugo.yaml

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

検索機能の強化

すべての見出しを検索: ページタイトルだけでなく、すべてのレベルの見出しからコンテンツを検索
検索結果の精度向上: タイトル処理とリンク精度の改善
結果ナビゲーションの修正: 検索結果が正しいページセクションにリンクするようになりました

検索機能の強化に貢献してくださった @ldez に感謝します!

llms.txt サポート

Hextra はサイトの llms.txt 出力形式をサポートし、AIツールや言語モデルがコンテキストや参照のためにサイトをよりアクセスしやすくします。

hugo.yaml

outputs:
 home: [html, llms]

これにより、サイトのルートに llms.txt ファイルが生成されます。

目次のスクロールハイライト

ページをスクロールする際に、目次が現在のセクションを自動的にハイライトするようになり、ナビゲーションがより直感的になりました。

タブの同期切り替え

同じ項目を持つタブはページ全体で同期されるようになりました。同期が有効な場合、タブを選択すると同じ項目リストを共有するすべてのタブグループが更新されます（選択内容は記憶されます）。

hugo.yaml

params:
 page:
 tabs:
 sync: true

ブログ一覧のページネーション

ブログ一覧ページに基本的なページネーションコントロールが追加されました。

hugo.yaml

params:
 blog:
 list:
 pagerSize: 20 # 1ページあたりの投稿数

MathJax サポート

デフォルトのKaTeXサポートに加えて、MathJax で数式をレンダリングできるようになりました。ニーズに合ったエンジンを選択できます。

hugo.yaml

params:
 math:
 engine: "mathjax" # デフォルトは "katex"

技術的改善

フレームワークとビルドシステム

Tailwind CSS v4 移行: Tailwind CSS v4 への完全移行とカスタマイズサポートの改善
Hugoテンプレートシステム: Hugoの新しいテンプレートシステム (v0.146.0+) への対応
数式のサーバーサイドレンダリング: Hugoネイティブレンダリングを使用した数式レンダリングの改善
FlexSearch 0.8 アップグレード: 検索エンジン FlexSearch のアップグレードにより、CJK (中国語、日本語、韓国語) コンテンツのエンコーディング改善と高速化・精度向上
アセット管理の強化: KaTeXとMermaidアセットのCDNまたはローカルからの読み込みサポート

利便性の向上

動的ファビコン切り替え: カラースキーム設定に基づくファビコンの自動更新
逆順ページネーション: ページフロントマターで reversePagination を設定可能に
Googleインデックス制御: Googleのインデックスをブロックする新しいページパラメータ
幅の処理改善: CSS変数によるレスポンシブデザイン制御の強化
スタイリング改善: Markdownテーブルと水平線のモダンなスタイル

バグ修正と安定性

Giscusテーマ同期: コメントがダーク/ライトモードの切り替えに正しく追従
検索結果の精度: 検索結果のリンク問題とタイトルエスケープの修正
タブ切り替え: 非同期タブモードでのナビゲーション問題の解決
ファントムスクロール: フッター無効時の不要なスクロール動作の修正
画像アクセシビリティ: 重複したaltテキストレンダリングの防止
リンクレンダリング: 複雑なサイト構造におけるベースURL処理の改善

移行ガイド

Hugoバージョン要件: Hugo v0.146.0+ (extended版) が必要
CSSクラスプレフィックス変更: コンポーネントCSSクラスに一貫した hextra- プレフィックスを採用
アセット管理: KaTeXとMermaidアセットはビルド時にダウンロード
Tailwind CSS v4: 内部CSSコンパイルにTailwind CSS v4.xを採用し hx: プレフィックスを使用

Hugoバージョン要件

影響: 古いHugoバージョンで動作しているサイト

Hextra v0.10.0 は新しいテンプレートシステムを採用しているため、Hugo v0.146.0以降 (extended版) が必要です。

必要な対応: Hextraをアップグレードする前にHugoをv0.146.0+に更新

CSSクラスプレフィックス変更

影響: HextraコンポーネントクラスをターゲットにしたカスタムCSSがあるサイト

Hextra v0.10.0 では、メンテナンス性向上とユーザースタイルとの衝突防止のため、ほとんどのコンポーネントCSSクラスに一貫した hextra- プレフィックスを導入しました。

必要な対応: HextraコンポーネントをターゲットにしたカスタムCSSがある場合、以下のクラス名を更新してください:

領域	変更前	変更後
検索 (コンテナ)	`.search-wrapper`	`.hextra-search-wrapper`
検索 (入力)	`.search-input`	`.hextra-search-input`
検索 (結果)	`.search-results`	`.hextra-search-results`
検索 (タイトル)	`.search-wrapper .title`	`.hextra-search-wrapper .hextra-search-title`
検索 (アクティブ項目)	`.search-wrapper .active`	`.hextra-search-wrapper .hextra-search-active`
検索 (結果なし)	`.search-wrapper .no-result`	`.hextra-search-wrapper .hextra-search-no-result`
検索 (プレフィックス)	`.search-wrapper .prefix`	`.hextra-search-wrapper .hextra-search-prefix`
検索 (抜粋)	`.search-wrapper .excerpt`	`.hextra-search-wrapper .hextra-search-excerpt`
検索 (マッチ)	`.search-wrapper .match`	`.hextra-search-wrapper .hextra-search-match`
ナビバーブラー	`.nav-container-blur`	`.hextra-nav-container-blur`
ハンバーガーメニュー	`.hamburger-menu`	`.hextra-hamburger-menu`
テーマトグル	`.theme-toggle`	`.hextra-theme-toggle`
言語スイッチャー	`.language-switcher`	`.hextra-language-switcher`
サイドバーコンテナ	`.sidebar-container`	`.hextra-sidebar-container`
サイドバーアクティブ項目	`.sidebar-active-item`	`.hextra-sidebar-active-item`
コードファイル名	`.filename`	`.hextra-code-filename`
コピーアイコン	`.copy-icon`	`.hextra-copy-icon`
成功アイコン	`.success-icon`	`.hextra-success-icon`
ステップ	`.steps`	`.hextra-steps`

KaTeXとMermaidのアセット管理

影響: KaTeXまたはMermaidを使用しているサイト

Hextra v0.10.0 では、KaTeXとMermaidアセットをビルド時にCDNからダウンロードするようになりました。

変更点:

これらのアセットをダウンロードするため、ビルドプロセスでインターネットアクセスが必要
ビルド後はこれらのアセットに対する外部CDN呼び出しが不要

必要な対応:

アセットをダウンロードするため、ビルド環境がインターネットに接続できることを確認
エアギャップ環境のサイトでは、これらのアセットを事前にダウンロードし、Hextraがそれらを読み込むように設定する必要がある場合があります

Tailwind CSS v4

影響: HextraのTailwindクラス hx-* を広範囲にカスタマイズしているサイト

HextraはTailwind CSS v4移行を内部で処理しますが、高度にカスタマイズされたサイトでは追加の調整が必要な場合があります。

変更点:

内部CSSコンパイルにTailwind CSS v4.xを使用
ユーティリティクラスのプレフィックスが hx- から hx: に変更

コントリビューター

このリリースは、10名の新規コントリビューターの貢献によって実現されました:

@oosquare - KaTeXフォント、画像レンダーフック、リンク処理の改善
@Zabriskije - ファントムスクロールの修正
@miniwater - カスタムフッターの中央揃え、画像altテキストの改善
@MattDodsonEnglish - Googleインデックス制御、OpenGraphドキュメント
@KStocky - 逆順ページネーション機能
@PrintN - ドキュメントショーケースの追加
@hobobandy - タイトル間隔の改善
@dlwocks31 - 韓国語翻訳の更新
@TwoAnts - Giscusテーマ切り替えの修正
@ldez - 検索機能の改善とバグ修正

継続的なサポート、ドキュメント、翻訳、技術的改善を提供してくださった @deining と @yuri1969 にも感謝します。

完全な変更履歴: https://github.com/imfing/hextra/compare/v0.9.7...v0.10.0

Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

Hextra v0.10.0 is a big release packed with new capabilities, architectural upgrades, and quality-of-life improvements.

It also includes contributions from 10 new 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 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 and 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:

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: create hierarchical navigation menus
Enhanced Search Experience: improved search across all headings with better accuracy
llms.txt Support: generate AI-friendly site outline
Table of Contents Scroll Highlighting: automatic heading highlighting during page scroll
Synchronized Tab Switching: synchronize tab selections across multiple tab groups
Blog List Pagination: add pagination controls to blog listing pages
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.

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

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

hugo.yaml

params:
 page:
 tabs:
 sync: true

Blog List Pagination

Basic pagination controls have been added to blog listing pages.

hugo.yaml

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

MathJax Support

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

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 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 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: Requires Hugo v0.146.0+ (extended version)
CSS Class Prefix Changes: Component CSS classes now use consistent hextra- prefixing
Asset Management: KaTeX and Mermaid assets now download during build time
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 - KaTeX fonts, image render hooks, link handling improvements
@Zabriskije - Phantom scroll fix
@miniwater - Custom footer centering, image alt text improvements
@MattDodsonEnglish - Google indexing controls, OpenGraph documentation
@KStocky - Reverse pagination feature
@PrintN - Documentation showcase additions
@hobobandy - Title spacing improvements
@dlwocks31 - Korean translation updates
@TwoAnts - Giscus theme switching fix
@ldez - Search improvements and bug fixes

Additional thanks to returning contributors @deining and @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

Hextra v0.10

Thu, 14 Aug 2025 00:00:00 +0000

Hextra v0.10.0 是一个重大版本更新，包含多项新功能、架构升级和使用体验优化。

本次更新还包含了来自 10 位新贡献者的代码提交，并解决了社区长期期待的功能需求。

升级指南

Important

破坏性变更：此版本包含多项不兼容改动。升级前请仔细阅读检查清单和迁移指南。

升级至 v0.10.0 前，请确保：

已安装 Hugo v0.146.0+（扩展版）
检查自定义 CSS 的类名变更（参见 CSS 类前缀变更和 Tailwind CSS v4）
确认构建环境可访问互联网以下载 LaTeX 和/或 Mermaid 资源

准备就绪后，更新 Hugo 模块：

hugo mod get -u github.com/imfing/hextra@v0.10.0

新功能

以下是本版本值得关注的新特性：

导航栏下拉菜单支持：创建层级导航菜单
增强搜索体验：改进全标题搜索精度
llms.txt 支持：生成 AI 友好的站点大纲
目录滚动高亮：滚动时自动高亮当前章节
同步标签页切换：跨多组标签页同步选择状态
博客列表分页：为博客列表添加分页控件
MathJax 支持：在 KaTeX 外新增数学公式渲染引擎

导航栏下拉菜单支持

在导航栏中创建下拉菜单，优化导航项组织方式。

hugo.yaml

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

增强搜索体验

全标题搜索：可搜索所有层级标题内容，不限于页面标题
提升结果精度：改进标题处理和链接准确性
修复结果导航：搜索结果现在能正确跳转到对应章节

特别感谢 @ldez 推动搜索功能升级！

llms.txt 支持

现支持生成 llms.txt 格式输出，使站点内容更便于 AI 工具和语言模型获取上下文参考。

hugo.yaml

outputs:
 home: [html, llms]

这将在站点根目录生成 llms.txt 文件。

目录滚动高亮

滚动页面时，目录会自动高亮当前章节，使导航更加直观。

同步标签页切换

相同内容的标签页现在支持跨组同步。启用同步后，选择某个标签会更新所有包含相同项目的标签组（且会记住选择状态）。

hugo.yaml

params:
 page:
 tabs:
 sync: true

博客列表分页

为博客列表页面添加基础分页控件。

hugo.yaml

params:
 blog:
 list:
 pagerSize: 20 # 每页文章数

MathJax 支持

除默认的 KaTeX 外，新增 MathJax 数学公式渲染引擎支持，可按需选择。

hugo.yaml

params:
 math:
 engine: "mathjax" # 默认为 "katex"

技术改进

框架与构建系统

Tailwind CSS v4 迁移：完整迁移至 Tailwind CSS v4，提供更好的定制支持
Hugo 模板系统：适配 Hugo 新版模板系统（v0.146.0+）以确保未来兼容性
数学公式服务端渲染：默认使用 Hugo 原生渲染改进数学公式处理
FlexSearch 0.8 升级：搜索引擎升级至 FlexSearch 0.8，提升 CJK（中日韩）内容编码处理能力
增强资源管理：KaTeX 和 Mermaid 资源支持从 CDN 或本地加载

使用体验优化

动态 favicon 切换：根据色彩偏好自动更新网站图标
反向分页：支持通过页面 front matter 设置 reversePagination
Google 索引控制：新增页面参数控制是否允许 Google 索引
宽度处理改进：通过 CSS 变量优化响应式设计控制
样式改进：现代化 Markdown 表格和水平线样式

错误修复与稳定性

Giscus 主题同步：评论模块现在正确跟随暗黑/明亮模式切换
搜索结果准确性：修复搜索结果链接和标题转义问题
标签页切换：解决非同步模式下的导航问题
幽灵滚动：修复禁用页脚时出现的异常滚动行为
图片可访问性：避免重复渲染 alt 文本
链接渲染：改进复杂站点结构下的基础 URL 处理

迁移指南

Hugo 版本要求：需 Hugo v0.146.0+（扩展版）
CSS 类前缀变更：组件 CSS 类现统一使用 hextra- 前缀
资源管理：KaTeX 和 Mermaid 资源改为构建时下载
Tailwind CSS v4：内部 CSS 编译现使用 Tailwind CSS v4.x 并采用 hx: 前缀

Hugo 版本要求

影响：使用旧版 Hugo 的站点

Hextra v0.10.0 因采用新模板系统，要求 Hugo v0.146.0 或更高版本（扩展版）。

需执行操作：升级 Hextra 前先更新 Hugo 至 v0.146.0+

CSS 类前缀变更

影响：自定义 CSS 中引用了 Hextra 组件类的站点

v0.10.0 为大多数组件 CSS 类引入统一的 hextra- 前缀，以提高可维护性并避免与用户样式冲突。

需执行操作：如果自定义 CSS 中引用了 Hextra 组件，请更新以下类名：

区域	旧类名	新类名
搜索（容器）	`.search-wrapper`	`.hextra-search-wrapper`
搜索（输入框）	`.search-input`	`.hextra-search-input`
搜索（结果）	`.search-results`	`.hextra-search-results`
搜索（标题）	`.search-wrapper .title`	`.hextra-search-wrapper .hextra-search-title`
搜索（活动项）	`.search-wrapper .active`	`.hextra-search-wrapper .hextra-search-active`
搜索（无结果）	`.search-wrapper .no-result`	`.hextra-search-wrapper .hextra-search-no-result`
搜索（前缀）	`.search-wrapper .prefix`	`.hextra-search-wrapper .hextra-search-prefix`
搜索（摘要）	`.search-wrapper .excerpt`	`.hextra-search-wrapper .hextra-search-excerpt`
搜索（匹配项）	`.search-wrapper .match`	`.hextra-search-wrapper .hextra-search-match`
导航栏模糊效果	`.nav-container-blur`	`.hextra-nav-container-blur`
汉堡菜单	`.hamburger-menu`	`.hextra-hamburger-menu`
主题切换	`.theme-toggle`	`.hextra-theme-toggle`
语言切换器	`.language-switcher`	`.hextra-language-switcher`
侧边栏容器	`.sidebar-container`	`.hextra-sidebar-container`
侧边栏活动项	`.sidebar-active-item`	`.hextra-sidebar-active-item`
代码文件名	`.filename`	`.hextra-code-filename`
复制图标	`.copy-icon`	`.hextra-copy-icon`
成功图标	`.success-icon`	`.hextra-success-icon`
步骤组件	`.steps`	`.hextra-steps`

KaTeX 和 Mermaid 资源管理

影响：使用 KaTeX 或 Mermaid 的站点

v0.10.0 改为在构建时从 CDN 下载 KaTeX 和 Mermaid 资源。

变更内容：

构建过程需要联网下载这些资源
构建后不再需要外部 CDN 调用

需执行操作：

确保构建环境可访问互联网以下载资源
隔离环境中的站点需预下载资源并配置 Hextra 加载路径

Tailwind CSS v4

影响：大量自定义 CSS 引用了 hx-* 类名的站点

虽然 Hextra 内部已处理 Tailwind CSS v4 迁移，但深度定制的站点可能需要额外调整。

变更内容：

内部 CSS 编译使用 Tailwind CSS v4.x
工具类前缀改为 hx: 而非 hx-

贡献者

本次发布得益于 10 位新贡献者的代码提交：

@oosquare - KaTeX 字体、图片渲染钩子、链接处理改进
@Zabriskije - 修复幽灵滚动问题
@miniwater - 自定义页脚居中、图片 alt 文本优化
@MattDodsonEnglish - Google 索引控制、OpenGraph 文档
@KStocky - 反向分页功能
@PrintN - 文档展示增强
@hobobandy - 标题间距优化
@dlwocks31 - 韩语翻译更新
@TwoAnts - 修复 Giscus 主题切换
@ldez - 搜索功能改进与错误修复

同时感谢长期贡献者 @deining 和 @yuri1969 在文档、翻译和技术改进方面的持续支持。

完整更新日志：https://github.com/imfing/hextra/compare/v0.9.7…v0.10.0

Markdown Syntax Guide

Wed, 01 Jan 2020 00:00:00 +0000

This article offers a sample of basic Markdown syntax that can be used in Hugo content files.

Basic Syntax

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Emphasis

*This text will be italic*
_This will also be italic_

**This text will be bold**
__This will also be bold__

_You **can** combine them_

This text will be italic

This will also be italic

This text will be bold

This will also be bold

You can combine them

Lists

Unordered

* Item 1
* Item 2
* Item 2a
* Item 2b

Item 1
Item 2
- Item 2a
- Item 2b

Ordered

1. Item 1
2. Item 2
3. Item 3
1. Item 3a
2. Item 3b

Images

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

Links

[Hugo](https://gohugo.io)

Hugo

Blockquotes

As Newton said:

> If I have seen further it is by standing on the shoulders of Giants.

If I have seen further it is by standing on the shoulders of Giants.

Inline Code

Inline `code` has `back-ticks around` it.

Inline code has back-ticks around it.

Code Blocks

Syntax Highlighting

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

Tables

| Syntax | Description |
| --------- | ----------- |
| Header | Title |
| Paragraph | Text |

Syntax	Description
Header	Title
Paragraph	Text

References

Markdown 構文ガイド

Wed, 01 Jan 2020 00:00:00 +0000

この記事では、Hugo のコンテンツファイルで使用できる基本的な Markdown 構文のサンプルを紹介します。

基本構文

見出し

# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6

見出し2

見出し3

見出し4

見出し5

見出し6

強調

*このテキストは斜体になります*
_これも斜体になります_

**このテキストは太字になります**
__これも太字になります__

_これらを**組み合わせる**こともできます_

このテキストは斜体になります

これも斜体になります

このテキストは太字になります

これも太字になります

これらを組み合わせることもできます

画像

![GitHub ロゴ](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

リンク

[Hugo](https://gohugo.io)

Hugo

ブロッククォート

ニュートンはこう言いました:

> 私が遠くを見渡せたとしたら、それは巨人の肩の上に立っていたからです。

私が遠くを見渡せたとしたら、それは巨人の肩の上に立っていたからです。

インラインコード

インライン `コード` は `バッククォートで囲みます`。

インライン コード は バッククォートで囲みます。

コードブロック

シンタックスハイライト

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

テーブル

| 構文 | 説明 |
| --------- | ----------- |
| 見出し | タイトル |
| 段落 | テキスト |

構文	説明
見出し	タイトル
段落	テキスト

参考資料

Markdown 语法指南

Wed, 01 Jan 2020 00:00:00 +0000

本文展示了 Hugo 内容文件中可用的基础 Markdown 语法示例。

基础语法

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

二级标题

三级标题

四级标题

五级标题

六级标题

强调

*这段文字会显示为斜体*
_这段文字也会显示为斜体_

**这段文字会显示为粗体**
__这段文字也会显示为粗体__

_你可以**组合**使用_

这段文字会显示为斜体

这段文字也会显示为斜体

这段文字会显示为粗体

这段文字也会显示为粗体

你可以组合使用

列表

无序列表

* 项目1
* 项目2
* 子项目2a
* 子项目2b

项目1
项目2
- 子项目2a
- 子项目2b

有序列表

1. 项目1
2. 项目2
3. 项目3
1. 子项目3a
2. 子项目3b

图片

![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

链接

[Hugo](https://gohugo.io)

Hugo

引用块

正如牛顿所说：

> 如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。

如果说我看得比别人更远些，那是因为我站在巨人的肩膀上。

行内代码

行内`代码`会用`反引号包裹`起来。

行内代码会用反引号包裹起来。

代码块

语法高亮

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

表格

| 语法 | 描述 |
| --------- | ----------- |
| 标题 | 标题文本 |
| 段落 | 正文内容 |

语法	描述
标题	标题文本
段落	正文内容

参考资料

راهنمای نحو Markdown

Wed, 01 Jan 2020 00:00:00 +0000

این مقاله نمونه‌ای از نحو پایه‌ای Markdown را ارائه می‌دهد که می‌توان در فایل‌های محتوای Hugo استفاده کرد.

نحو پایه

سرتیترها

# سرتیتر 1
## سرتیتر 2
### سرتیتر 3
#### سرتیتر 4
##### سرتیتر 5
###### سرتیتر 6

سرتیتر 2

سرتیتر 3

سرتیتر 4

سرتیتر 5

سرتیتر 6

تأکید

*این متن به صورت ایتالیک نمایش داده می‌شود*
_این نیز به صورت ایتالیک نمایش داده می‌شود_

**این متن به صورت پررنگ نمایش داده می‌شود**
__این نیز به صورت پررنگ نمایش داده می‌شود__

_شما می‌توانید **آن‌ها را ترکیب** کنید_

این متن به صورت ایتالیک نمایش داده می‌شود

این نیز به صورت ایتالیک نمایش داده می‌شود

این متن به صورت پررنگ نمایش داده می‌شود

این نیز به صورت پررنگ نمایش داده می‌شود

شما می‌توانید آن‌ها را ترکیب کنید

فهرست‌ها

بدون ترتیب

* مورد ۱
* مورد ۲
* مورد ۲الف
* مورد ۲ب

مورد ۱
مورد ۲
- مورد ۲الف
- مورد ۲ب

با ترتیب

۱. مورد ۱
۲. مورد ۲
۳. مورد ۳
۱. مورد ۳الف
۲. مورد ۳ب

تصاویر

![لوگوی GitHub](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)

پیوندها

[Hugo](https://gohugo.io)

Hugo

نقل‌قول‌ها

همان‌طور که نیوتن گفت:

> اگر من دورتر را دیده‌ام، به این دلیل است که بر شانه‌های غول‌ها ایستاده‌ام.

اگر من دورتر را دیده‌ام، به این دلیل است که بر شانه‌های غول‌ها ایستاده‌ام.

کد درون‌خطی

کد `درون‌خطی` با `علامت back-tick` احاطه شده است.

کد درون‌خطی با علامت back-tick احاطه شده است.

بلوک‌های کد

هایلایت سینتکس

```go
func main() {
 fmt.Println("Hello World")
}
```

func main() {
 fmt.Println("Hello World")
}

جداول

| سینتکس | توضیحات |
| --------- | ----------- |
| هدر | عنوان |
| پاراگراف | متن |

سینتکس	توضیحات
هدر	عنوان
پاراگراف	متن

منابع

وبلاگ

Mon, 01 Jan 0001 00:00:00 +0000

فید RSS

ブログ

Mon, 01 Jan 0001 00:00:00 +0000

RSS フィード

博客

Mon, 01 Jan 0001 00:00:00 +0000

RSS 订阅

CapBase – Blog

Hextra v0.12

راهنمای ارتقا

نکات برجسته

ویژگی‌های جدید

منوی زمینه صفحه

بازطراحی تب‌ها و پشتیبانی از آیکون

زوم تصویر

تحلیل‌گر GoatCounter

مخفی‌کردن نوار کناری اصلی

آخرین نویسنده ویرایش‌کننده

غیرفعال‌سازی ناوبری قبلی/بعدی

حذف از LLMs.txt

صفحه آرشیو

واژه‌نامه

دسترس‌پذیری

بهبودهای کیفیت زندگی

رفع اشکالات

مستندات و بومی‌سازی

مشارکت‌کنندگان

Hextra v0.12

アップグレードガイド

ハイライト

新機能

ページコンテキストメニュー

タブの刷新とアイコン対応

画像ズーム

GoatCounter アナリティクス

メインサイドバーの非表示

最終更新者の表示

前へ/次へナビゲーションの無効化

LLMs.txt 除外

アーカイブページ

用語集

アクセシビリティ

利便性の向上

修正

ドキュメントと i18n

コントリビューター

Hextra v0.12

Upgrade Guide

Highlights

New Features

Page Context Menu

Tabs Revamp and Icon Support

Image Zoom

GoatCounter Analytics

Hide Main Sidebar

Last Modified Author

Disable Prev/Next Navigation

LLMs.txt Exclusion

Archives Page

Glossary

Accessibility

Quality of Life

Fixes

Documentation & i18n

Contributors

Hextra v0.12

升级指南

亮点

新功能

页面上下文菜单

标签页重设计与图标支持

图片缩放

GoatCounter 分析

隐藏主侧边栏

最后修改作者

禁用上一篇/下一篇导航

LLMs.txt 排除

归档页面

术语表

无障碍

使用体验优化

修复

文档与 i18n

贡献者

Hextra v0.11

راهنمای ارتقا

نکات برجسته