hextra_mirror/exampleSite/content/blog/v0.10.fa.md

---
title: "Hextra v0.10"
date: 2025-08-14
authors:
  - name: imfing
    link: https://github.com/imfing
    image: https://github.com/imfing.png
tags:
  - انتشار
---

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

<!--more-->

همچنین شامل مشارکت‌های 10 [مشارکت‌کننده جدید](#contributors) بوده و درخواست‌های دیرینه جامعه را برطرف می‌کند.

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

> [!IMPORTANT]
> **تغییرات شکست‌آمیز**: این انتشار شامل چندین تغییر شکست‌آمیز است. لطفاً قبل از ارتقا، چک‌لیست و [راهنمای مهاجرت](#migration-guide) را بررسی کنید.

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

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

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

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

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

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

- [**پشتیبانی از منوی کشویی در نوار ناوبری**](#dropdown-menu-support-in-navbar): ایجاد منوهای ناوبری سلسله‌مراتبی
- [**تجربه جستجوی بهبودیافته**](#enhanced-search-experience): جستجوی بهبودیافته در تمام سرتیترها با دقت بهتر
- [**پشتیبانی از llms.txt**](#llmstxt-support): تولید خلاصه سایت مناسب برای هوش مصنوعی
- [**هایلایت کردن اسکرول فهرست مطالب**](#table-of-contents-scroll-highlighting): هایلایت کردن خودکار سرتیترها هنگام اسکرول صفحه
- [**تبدیل همگام تب‌ها**](#synchronized-tab-switching): همگام‌سازی انتخاب تب‌ها در چندین گروه تب
- [**صفحه‌بندی لیست وبلاگ**](#blog-list-pagination): اضافه کردن کنترل‌های صفحه‌بندی به صفحات لیست وبلاگ
- [**پشتیبانی از MathJax**](#mathjax-support): موتور رندر ریاضی جایگزین در کنار KaTeX

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

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

```yaml {filename="hugo.yaml"}
menu:
  main:
    - identifier: products
      name: "محصولات"
    - name: "محصول الف"
      parent: products
      url: "/product-a"
    - name: "محصول ب"
      parent: products
      url: "/product-b"
```

![ناوبری منوی کشویی](https://github.com/user-attachments/assets/1816f9b9-7fe3-46e8-9546-f15e43e9914a)

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

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

با تشکر ویژه از [@ldez](https://github.com/ldez) برای پیشبرد قابلیت‌های جستجو!

![نتایج جستجوی بهبودیافته](https://github.com/user-attachments/assets/f819652a-95d4-4843-b7e2-c7953a8cabe8)

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

Hextra اکنون از فرمت خروجی [llms.txt](https://llmstxt.org/) برای سایت شما پشتیبانی می‌کند، که سایت شما را برای ابزارهای هوش مصنوعی و مدل‌های زبانی برای زمینه و مرجع قابل دسترس‌تر می‌سازد.

```yaml {filename="hugo.yaml"}
outputs:
  home: [html, llms]
```

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

![مثال llms txt](https://github.com/user-attachments/assets/c6e929bb-0fce-4ab2-af15-a71c5a38b22c)

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

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

![هایلایت اسکرول ToC](https://github.com/user-attachments/assets/d623fb99-7000-428b-af95-384eb722f0eb)

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

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

```yaml {filename="hugo.yaml"}
params:
  page:
    tabs:
      sync: true
```

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

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

```yaml {filename="hugo.yaml"}
params:
  blog:
    list:
      pagerSize: 20 # پست‌ها در هر صفحه
```

![صفحه‌بندی وبلاگ](https://github.com/user-attachments/assets/60405fb4-ec36-4733-ba13-b4066396b5c5)

### پشتیبانی از MathJax

عبارات ریاضی را با [MathJax](https://www.mathjax.org/) در کنار پشتیبانی پیش‌فرض KaTeX رندر کنید. موتوری را انتخاب کنید که بهترین تناسب را با نیازهای شما دارد.

```yaml {filename="hugo.yaml"}
params:
  math:
    engine: "mathjax" # پیش‌فرض "katex" است
```

## بهبودهای فنی

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

- **مهاجرت به Tailwind CSS v4**: مهاجرت کامل به [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4) با پشتیبانی بهبودیافته سفارشی‌سازی.
- **سیستم قالب Hugo**: سازگار با [سیستم قالب جدید Hugo](https://gohugo.io/templates/new-templatesystem-overview/) (v0.146.0+) برای سازگاری آینده.
- **رندر سمت سرور ریاضی**: مدیریت بهتر رندر معادلات ریاضی با استفاده از رندر بومی Hugo به‌صورت پیش‌فرض.
- **ارتقای FlexSearch 0.8**: ارتقای موتور جستجو [FlexSearch](https://github.com/nextapps-de/flexsearch) برای نتایج سریع‌تر و دقیق‌تر با رمزگذاری بهبودیافته محتوای CJK (چینی، ژاپنی، کرهای).
- **مدیریت بهبودیافته دارایی‌ها**: دارایی‌های KaTeX و Mermaid از بارگیری از CDN یا محلی پشتیبانی می‌کنند

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

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

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

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

---

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

- [**نیازمندی‌های نسخه Hugo**](#hugo-version-requirements): نیاز به Hugo v0.146.0+ (نسخه extended) دارد
- [**تغییرات پیشوند کلاس‌های CSS**](#css-class-prefix-changes): کلاس‌های CSS کامپوننت اکنون از پیشوند سازگار `hextra-` استفاده می‌کنند
- [**مدیریت دارایی‌ها**](#asset-management-for-katex-and-mermaid): دارایی‌های KaTeX و Mermaid اکنون در زمان ساخت دانلود می‌شوند
- [**Tailwind CSS v4**](#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](https://github.com/oosquare) - فونت‌های KaTeX، قلاب‌های رندر تصویر، بهبودهای مدیریت پیوند
- [@Zabriskije](https://github.com/Zabriskije) - رفع اسکرول فانتوم
- [@miniwater](https://github.com/miniwater) - مرکزسازی پاورقی سفارشی، بهبودهای متن alt تصویر
- [@MattDodsonEnglish](https://github.com/MattDodsonEnglish) - کنترل‌های نمایه‌سازی گوگل، مستندات OpenGraph
- [@KStocky](https://github.com/KStocky) - ویژگی صفحه‌بندی معکوس
- [@PrintN](https://github.com/PrintN) - اضافه شدن نمایش مستندات
- [@hobobandy](https://github.com/hobobandy) - بهبودهای فاصله عنوان
- [@dlwocks31](https://github.com/dlwocks31) - به‌روزرسانی ترجمه کرهای
- [@TwoAnts](https://github.com/TwoAnts) - رفع تغییر تم Giscus
- [@ldez](https://github.com/ldez) - بهبودهای جستجو و رفع اشکالات

با تشکر ویژه از مشارکت‌کنندگان بازگشتی [@deining](https://github.com/deining) و [@yuri1969](https://github.com/yuri1969) برای حمایت مستمرشان در مستندات، ترجمه‌ها و بهبودهای فنی.

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