feat(navbar): language switcher (#760)

* feat(navbar): language switcher

* docs: add language-switch

* chore: just for the demo

* fix: drop conflicting CSS

* fix: use constant

* fix: pre-existing bug with rtl on mobile

* docs: add comment to explain the algo

* chore: more readable algo

* review

Co-authored-by: Xin <5097752+imfing@users.noreply.github.com>

* feat: different icons

* feat: icon as param

* fix: inconsitency with rtl

* fix: render inside the sidebar

* chore: remove the demo

---------

Co-authored-by: Xin <5097752+imfing@users.noreply.github.com>

assets/css/components/search.css

@@ -2,7 +2,7 @@
   li {
     @apply hx:mx-2.5 hx:break-words hx:rounded-md hx:contrast-more:border hx:text-gray-800 hx:contrast-more:border-transparent hx:dark:text-gray-300;
     a {
-      @apply hx:block hx:scroll-m-12 hx:px-2.5 hx:py-2;
+      @apply hx:focus-visible:outline-none hx:focus:outline-none hx:block hx:scroll-m-12 hx:px-2.5 hx:py-2;
     }
 
     .hextra-search-title {

assets/css/styles.css

@@ -38,6 +38,10 @@ body {
   --primary-lightness: 50%;
 }
 
+@utility hextra-focus {
+  @apply hx:outline-none hx:ring-2 hx:ring-primary-200 hx:ring-offset-1 hx:ring-offset-primary-300 hx:dark:ring-primary-800 hx:dark:ring-offset-primary-700;
+}
+
 @import "./typography.css";
 @import "./highlight.css";
 @import "./components/cards.css";

assets/js/lang.js

@@ -7,11 +7,32 @@
       const optionsElement = switcher.nextElementSibling;
       optionsElement.classList.toggle('hx:hidden');
 
-      // Calculate position of language options element
+      // Calculate the position of a language options element.
       const switcherRect = switcher.getBoundingClientRect();
-      const translateY = switcherRect.top - window.innerHeight - 15;
-      optionsElement.style.transform = `translate3d(${switcherRect.left}px, ${translateY}px, 0)`;
+
+      // Must be called before optionsElement.clientWidth.
       optionsElement.style.minWidth = `${Math.max(switcherRect.width, 50)}px`;
+
+      const isOnTop = switcher.dataset.location === 'top';
+      const isRTL = document.body.dir === 'rtl'
+
+      // Stuck on the left side of the switcher.
+      let translateX = switcherRect.left;
+
+      if (isOnTop && !isRTL || !isOnTop && isRTL) {
+        // Stuck on the right side of the switcher.
+        translateX = switcherRect.right - optionsElement.clientWidth;
+      }
+
+      // Stuck on the top of the switcher.
+      let translateY = switcherRect.top - window.innerHeight - 15;
+
+      if (isOnTop) {
+        // Stuck on the bottom of the switcher.
+        translateY = switcherRect.top - window.innerHeight + 180;
+      }
+
+      optionsElement.style.transform = `translate3d(${translateX}px, ${translateY}px, 0)`;
     });
   });
 

assets/js/toc-scroll.js

@@ -16,7 +16,7 @@ document.addEventListener("DOMContentLoaded", function () {
 
   const headingIds = Array.from(tocLinks).map((link) => link.getAttribute("href").substring(1));
 
-  const headings = headingIds.map((id) => document.getElementById(id)).filter(Boolean);
+  const headings = headingIds.map((id) => document.getElementById(decodeURIComponent(id))).filter(Boolean);
   if (headings.length === 0) return;
 
   let currentActiveLink = null;
@@ -39,7 +39,8 @@ document.addEventListener("DOMContentLoaded", function () {
         return Math.abs(headingTop) < Math.abs(closestTop) ? heading : closest;
       });
 
-      const targetId = topMostHeading.id;
+      // Encode the id and make it lowercase to match the TOC link
+      const targetId = encodeURIComponent(topMostHeading.id).toLowerCase();
       const targetLink = toc.querySelector(`a[href="#${targetId}"]`);
 
       if (targetLink && targetLink !== currentActiveLink) {
@@ -64,7 +65,7 @@ document.addEventListener("DOMContentLoaded", function () {
 
   // Handle direct navigation to page with hash
   function handleHashNavigation() {
-    const hash = window.location.hash;
+    const hash = window.location.hash; // already url encoded
     if (hash) {
       const targetLink = toc.querySelector(`a[href="${hash}"]`);
       if (targetLink) {

build.sh

@@ -8,7 +8,7 @@ echo "Using base URL: $BASE_URL"
 
 # Version configuration - modify these arrays to specify versions to build
 # Format: "ref:display_name" (ref can be tag, branch, or commit hash, display name is what will appear in URL)
-MAIN_VERSION="v0.10.0:latest"
+MAIN_VERSION="v0.10.1:latest"
 VERSIONS=(
   "main:latest" # latest version always builds from main
   "v0.9.6:v0.9"

exampleSite/content/docs/guide/configuration.fa.md

@@ -64,6 +64,21 @@ menu:
      params:
        icon: github
    ```
+5. تبديل السمة
+   ```yaml
+    - name: Theme Toggle
+      params:
+        type: theme-toggle
+        label: true # optional, default is false
+   ```
+6. مُبدِّل اللغة
+   ```yaml
+    - name: مُبدِّل اللغة
+      params:
+        type: language-switch
+        label: true # optional, default is false
+        icon: "globe-alt" # optional, default is "translate"
+   ```
 
 این آیتم‌های منو را می‌توان با تنظیم پارامتر `weight` مرتب کرد.
 

exampleSite/content/docs/guide/configuration.ja.md

@@ -64,6 +64,21 @@ menu:
      params:
        icon: github
    ```
+5. テーマ切り替え
+   ```yaml
+    - name: Theme Toggle
+      params:
+        type: theme-toggle
+        label: true # optional, default is false
+   ```
+6. 言語スイッチャー
+   ```yaml
+    - name: 言語スイッチャー
+      params:
+        type: language-switch
+        label: true # optional, default is false
+        icon: "globe-alt" # optional, default is "translate"
+   ```
 
 これらのメニュー項目は `weight` パラメータを設定することで並べ替えられます。
 

exampleSite/content/docs/guide/configuration.md

@@ -64,6 +64,21 @@ There are different types of menu items:
      params:
        icon: github
    ```
+5. Theme Toggle
+   ```yaml
+    - name: Theme Toggle
+      params:
+        type: theme-toggle
+        label: true # optional, default is false
+   ```
+6. Language Switcher
+   ```yaml
+    - name: Language Switcher
+      params:
+        type: language-switch
+        label: true # optional, default is false
+        icon: "globe-alt" # optional, default is "translate"
+   ```
 
 These menu items can be sorted by setting the `weight` parameter.
 

exampleSite/content/docs/guide/configuration.zh-cn.md

@@ -64,6 +64,21 @@ menu:
      params:
        icon: github
    ```
+5. 主题切换
+   ```yaml
+    - name: Theme Toggle
+      params:
+        type: theme-toggle
+        label: true # optional, default is false
+   ```
+6. 语言切换器
+   ```yaml
+    - name: 语言切换器
+      params:
+        type: language-switch
+        label: true # optional, default is false
+        icon: "globe-alt" # optional, default is "translate"
+   ```
 
 通过设置 `weight` 参数可以调整菜单项的排序。
 

exampleSite/content/docs/guide/shortcodes/callout.fa.md

@@ -14,70 +14,60 @@ prev: /docs/guide/shortcodes
 > [هشدارهای سبک GitHub](../../markdown#alerts) از [نسخه 0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0) پشتیبانی می‌شوند.
 > این ویژگی از سینتکس Markdown برای رندر کردن callout استفاده می‌کند که باعث بهبود قابلیت حمل و خوانایی محتوا می‌شود.
 
-## مثال
+##   أمثلة
 
-{{< callout emoji="👾">}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
-{{< /callout >}}
-
-{{< callout type="info" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
-{{< /callout >}}
-
-{{< callout type="warning" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
-{{< /callout >}}
-
-{{< callout type="error" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
-{{< /callout >}}
-
-## نحوه استفاده
-
-### پیش‌فرض
+### تقصير
 
 {{< callout emoji="🌐">}}
-  Hugo می‌تواند برای ایجاد انواع مختلف وب‌سایت‌ها از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندات و غیره استفاده شود.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{< /callout >}}
 
 ```markdown
 {{</* callout emoji="🌐" */>}}
-  Hugo می‌تواند برای ایجاد انواع مختلف وب‌سایت‌ها از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندات و غیره استفاده شود.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{</* /callout */>}}
 ```
 
-### اطلاعات
+### معلومات
 
 {{< callout type="info" >}}
-  لطفاً برای مشاهده آخرین نسخه‌ها به GitHub مراجعه کنید.
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="info" */>}}
-  لطفاً برای مشاهده آخرین نسخه‌ها به GitHub مراجعه کنید.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{</* /callout */>}}
 ```
 
-### هشدار
+### تحذير
 
 {{< callout type="warning" >}}
-  این API در نسخه بعدی منسوخ خواهد شد.
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="warning" */>}}
-  این API در نسخه بعدی منسوخ خواهد شد.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{</* /callout */>}}
 ```
 
-### خطا
+### خطأ
 
 {{< callout type="error" >}}
-  مشکلی پیش آمده و قرار است منفجر شود.
+ **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه. 
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="error" */>}}
-  مشکلی پیش آمده و قرار است منفجر شود.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{</* /callout */>}}
 ```
+
+## خيارات
+
+| المعلمة | وصف                                                                 |
+|---------|---------------------------------------------------------------------|
+| `type`  | نوع الاستدعاء. (افتراضي، `info`، `warning`، `error`)                |
+| `emoji` | الرمز التعبيري الذي يظهر قبل المكالمة.                              |
+| `icon`  | رمز تعبيري للنداء (مرتبط بالنوع أو يمكن أن يكون رمز تعبيري مخصصًا). |

exampleSite/content/docs/guide/shortcodes/callout.ja.md

@@ -16,68 +16,58 @@ prev: /docs/guide/shortcodes
 
 ## 例
 
-{{< callout emoji="👾">}}
-  **コールアウト**とは、注意を引くための短いテキストです。
-{{< /callout >}}
-
-{{< callout type="info" >}}
-  **コールアウト**とは、注意を引くための短いテキストです。
-{{< /callout >}}
-
-{{< callout type="warning" >}}
-  **コールアウト**とは、注意を引くための短いテキストです。
-{{< /callout >}}
-
-{{< callout type="error" >}}
-  **コールアウト**とは、注意を引くための短いテキストです。
-{{< /callout >}}
-
-## 使用方法
-
 ### デフォルト
 
 {{< callout emoji="🌐">}}
-  Hugoはブログ、ポートフォリオ、ドキュメントサイトなど、様々な種類のウェブサイト作成に使用できます。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{< /callout >}}
 
 ```markdown
 {{</* callout emoji="🌐" */>}}
-  Hugoはブログ、ポートフォリオ、ドキュメントサイトなど、様々な種類のウェブサイト作成に使用できます。
+    **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{</* /callout */>}}
 ```
 
 ### 情報
 
 {{< callout type="info" >}}
-  最新リリースについてはGitHubをご覧ください。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="info" */>}}
-  最新リリースについてはGitHubをご覧ください。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{</* /callout */>}}
 ```
 
 ### 警告
 
 {{< callout type="warning" >}}
-  このAPIは次のバージョンで非推奨になります。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="warning" */>}}
-  このAPIは次のバージョンで非推奨になります。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{</* /callout */>}}
 ```
 
 ### エラー
 
 {{< callout type="error" >}}
-  問題が発生しました。まもなく爆発します。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="error" */>}}
-  問題が発生しました。まもなく爆発します。
+  **コールアウト** は注目を集めることを目的とした短いテキストです。
 {{</* /callout */>}}
 ```
+
+## オプション
+
+| パラメータ   | 説明                                          |
+|---------|---------------------------------------------|
+| `type`  | コールアウトのタイプ。(デフォルト、`info`、`warning`、`error`) |
+| `emoji` | コールアウトの前に表示される絵文字。                          |
+| `icon`  | コールアウトの絵文字 (タイプに関連、またはカスタム絵文字にすることもできます)。   |

exampleSite/content/docs/guide/shortcodes/callout.md

@@ -14,54 +14,36 @@ A built-in component to show important information to the reader.
 > [GitHub-style alerts](../../markdown#alerts) are supported since [v0.9.0](https://github.com/imfing/hextra/releases/tag/v0.9.0).
 > It leverages Markdown syntax to render the callout which ensures better portability and readability of the content.
 
-## Example
-
-{{< callout emoji="👾">}}
-  A **callout** is a short piece of text intended to attract attention.
-{{< /callout >}}
-
-{{< callout type="info" >}}
-  A **callout** is a short piece of text intended to attract attention.
-{{< /callout >}}
-
-{{< callout type="warning" >}}
-  A **callout** is a short piece of text intended to attract attention.
-{{< /callout >}}
-
-{{< callout type="error" >}}
-  A **callout** is a short piece of text intended to attract attention.
-{{< /callout >}}
-
-## Usage
+## Examples
 
 ### Default
 
 {{< callout emoji="🌐">}}
-  Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.
+  A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
 ```markdown
 {{</* callout emoji="🌐" */>}}
-  Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.
+    A **callout** is a short piece of text intended to attract attention.
 {{</* /callout */>}}
 ```
 
 ### Info
 
 {{< callout type="info" >}}
-  Please visit GitHub to see the latest releases.
+  A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="info" */>}}
-  Please visit GitHub to see the latest releases.
+  A **callout** is a short piece of text intended to attract attention.
 {{</* /callout */>}}
 ```
 
 ### Warning
 
 {{< callout type="warning" >}}
-  This API will be deprecated in the next version.
+  A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
 ```markdown
@@ -73,11 +55,19 @@ A built-in component to show important information to the reader.
 ### Error
 
 {{< callout type="error" >}}
-  Something went wrong and it's going to explode.
+  A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="error" */>}}
-  Something went wrong and it's going to explode.
+  A **callout** is a short piece of text intended to attract attention.
 {{</* /callout */>}}
 ```
+
+## Options
+
+| Parameter | Description                                                          |
+|-----------|----------------------------------------------------------------------|
+| `type`    | The type of callout. (default, `info`, `warning`, `error`)           |
+| `emoji`   | The emoji to show before the callout.                                |
+| `icon`    | The emoji of the callout (related to type or can be a custom emoji). |

exampleSite/content/docs/guide/shortcodes/callout.zh-cn.md

@@ -16,68 +16,58 @@ prev: /docs/guide/shortcodes
 
 ## 示例
 
-{{< callout emoji="👾">}}
-  **提示框**是一段旨在吸引注意力的简短文本。
-{{< /callout >}}
-
-{{< callout type="info" >}}
-  **提示框**是一段旨在吸引注意力的简短文本。
-{{< /callout >}}
-
-{{< callout type="warning" >}}
-  **提示框**是一段旨在吸引注意力的简短文本。
-{{< /callout >}}
-
-{{< callout type="error" >}}
-  **提示框**是一段旨在吸引注意力的简短文本。
-{{< /callout >}}
-
-## 使用方法
-
-### 默认样式
+### 默认
 
 {{< callout emoji="🌐">}}
-  Hugo可用于创建各种类型的网站，包括博客、作品集、文档站点等。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{< /callout >}}
 
 ```markdown
 {{</* callout emoji="🌐" */>}}
-  Hugo可用于创建各种类型的网站，包括博客、作品集、文档站点等。
+    **标注** 是一小段旨在吸引注意力的文字。
 {{</* /callout */>}}
 ```
 
-### 信息提示
+### 信息
 
 {{< callout type="info" >}}
-  请访问GitHub查看最新发布版本。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="info" */>}}
-  请访问GitHub查看最新发布版本。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{</* /callout */>}}
 ```
 
-### 警告提示
+### 警告
 
 {{< callout type="warning" >}}
-  此API将在下一版本中弃用。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="warning" */>}}
-  此API将在下一版本中弃用。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{</* /callout */>}}
 ```
 
-### 错误提示
+### 错误
 
 {{< callout type="error" >}}
-  出现错误，系统即将崩溃。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="error" */>}}
-  出现错误，系统即将崩溃。
+  **标注** 是一小段旨在吸引注意力的文字。
 {{</* /callout */>}}
 ```
+
+## 选项
+
+| 范围      | 描述                         |
+|---------|----------------------------|
+| `type`  | 标注的类型。（默认、“信息”、“警告”、“错误”）  |
+| `emoji` | 标注前显示的表情符号。                |
+| `icon`  | 标注的表情符号（与类型相关或可以是自定义表情符号）。 |

exampleSite/content/docs/guide/shortcodes/cards.fa.md

@@ -37,24 +37,25 @@ linkTitle: کارت‌ها
 
 ## پارامترهای کارت
 
-| پارامتر    | توضیحات                                                     |
-|----------- |-----------------------------------------------------------------|
+| پارامتر    | توضیحات                                                   |
+|------------|-----------------------------------------------------------|
 | `link`     | URL (داخلی یا خارجی).                                     |
-| `title`    | عنوان کارت.                                     |
-| `subtitle` | زیرعنوان (پشتیبانی از Markdown).                           |
-| `icon`     | نام آیکون.                                               |
-| `tag`      | متن تگ.                                                    |
-| `tagColor` | رنگ تگ: `gray` (پیش‌فرض), `yellow`, `red` و `blue`. |
+| `title`    | عنوان کارت.                                               |
+| `subtitle` | زیرعنوان (پشتیبانی از Markdown).                          |
+| `icon`     | نام آیکون.                                                |
+| `tag`      | متن تگ.                                                   |
+| `tagType`  | نوع العلامة: default (رمادي)، `info`، `warning` و`error`. |
   
 ## کارت تصویری
 
 علاوه بر این، کارت از افزودن تصویر و پردازش آن از طریق این پارامترها پشتیبانی می‌کند:
 
-| پارامتر    | توضیحات                                 |
-|----------- |---------------------------------------------|
-| `image`    | آدرس تصویر کارت را مشخص می‌کند.       |
-| `method`   | روش پردازش تصویر هوگو را تنظیم می‌کند.        |
-| `options`  | تنظیمات پردازش تصویر هوگو را پیکربندی می‌کند. |
+| پارامتر      | توضیحات                                           |
+|--------------|---------------------------------------------------|
+| `image`      | آدرس تصویر کارت را مشخص می‌کند.                   |
+| `method`     | روش پردازش تصویر هوگو را تنظیم می‌کند.            |
+| `options`    | تنظیمات پردازش تصویر هوگو را پیکربندی می‌کند.     |
+| `imageStyle` | يتم استخدامه لملء سمة النمط الخاصة بعلامة الصورة. |
 
 کارت از سه نوع تصویر پشتیبانی می‌کند:
 

exampleSite/content/docs/guide/shortcodes/cards.ja.md

@@ -37,24 +37,25 @@ linkTitle: カード
 
 ## カードパラメータ
 
-| パラメータ  | 説明                                                     |
-|----------- |-----------------------------------------------------------------|
-| `link`     | URL（内部または外部）。                                     |
-| `title`    | カードのタイトル見出し。                                     |
-| `subtitle` | サブタイトル見出し（Markdown対応）。                           |
-| `icon`     | アイコン名。                                               |
-| `tag`      | タグのテキスト。                                                    |
-| `tagColor` | タグの色: `gray`（デフォルト）、`yellow`、`red`、`blue`。 |
+| パラメータ      | 説明                                            |
+|------------|-----------------------------------------------|
+| `link`     | URL（内部または外部）。                                 |
+| `title`    | カードのタイトル見出し。                                  |
+| `subtitle` | サブタイトル見出し（Markdown対応）。                        |
+| `icon`     | アイコン名。                                        |
+| `tag`      | タグのテキスト。                                      |
+| `tagType`  | タグのタイプ: デフォルト (グレー)、`info`、`warning`、`error`。 |
   
 ## 画像カード
 
 さらに、カードには画像の追加と以下のパラメータを通じた処理がサポートされています:
 
-| パラメータ  | 説明                                 |
-|----------- |---------------------------------------------|
-| `image`    | カードの画像URLを指定します。       |
-| `method`   | Hugoの画像処理方法を設定します。        |
-| `options`  | Hugoの画像処理オプションを設定します。 |
+| パラメータ        | 説明                         |
+|--------------|----------------------------|
+| `image`      | カードの画像URLを指定します。           |
+| `method`     | Hugoの画像処理方法を設定します。         |
+| `options`    | Hugoの画像処理オプションを設定します。      |
+| `imageStyle` | 画像タグのスタイル属性を入力するために使用されます。 |
 
 カードは3種類の画像をサポートします:
 

exampleSite/content/docs/guide/shortcodes/cards.md

@@ -38,23 +38,24 @@ linkTitle: Cards
 ## Card Parameters
 
 | Parameter  | Description                                                     |
-|----------- |-----------------------------------------------------------------|
+|------------|-----------------------------------------------------------------|
 | `link`     | URL (internal or external).                                     |
 | `title`    | Title heading for the card.                                     |
 | `subtitle` | Subtitle heading (supports Markdown).                           |
 | `icon`     | Name of the icon.                                               |
 | `tag`      | Text in tag.                                                    |
-| `tagColor` | Color of the tag: `gray` (default), `yellow`, `red` and `blue`. |
+| `tagType`  | Type of the tag: default (gray), `info`, `warning` and `error`. |
   
 ## Image Card
 
 Additionally, the card supports adding image and processing through these parameters:
 
-| Parameter  | Description                                 |
-|----------- |---------------------------------------------|
-| `image`    | Specifies the image URL for the card.       |
-| `method`   | Sets Hugo's image processing method.        |
-| `options`  | Configures Hugo's image processing options. |
+| Parameter    | Description                                        |
+|--------------|----------------------------------------------------|
+| `image`      | Specifies the image URL for the card.              |
+| `method`     | Sets Hugo's image processing method.               |
+| `options`    | Configures Hugo's image processing options.        |
+| `imageStyle` | Used to fill the style attribute of the image tag. |
 
 Card supports three kinds of images:
 

exampleSite/content/docs/guide/shortcodes/cards.zh-cn.md

@@ -37,24 +37,25 @@ linkTitle: 卡片
 
 ## 卡片参数
 
-| 参数       | 描述                                                     |
-|----------- |-----------------------------------------------------------------|
-| `link`     | 链接地址（内部或外部）。                                     |
-| `title`    | 卡片的标题。                                     |
-| `subtitle` | 卡片的副标题（支持Markdown）。                           |
-| `icon`     | 图标名称。                                               |
-| `tag`      | 标签文本。                                                    |
-| `tagColor` | 标签颜色：`gray`（默认）、`yellow`、`red` 和 `blue`。 |
+| 参数         | 描述                                      |
+|------------|-----------------------------------------|
+| `link`     | 链接地址（内部或外部）。                            |
+| `title`    | 卡片的标题。                                  |
+| `subtitle` | 卡片的副标题（支持Markdown）。                     |
+| `icon`     | 图标名称。                                   |
+| `tag`      | 标签文本。                                   |
+| `tagType`  | 标签类型：默认（灰色）、`info`、`warning` 和 `error`。 |
   
 ## 图片卡片
 
 此外，卡片还支持通过以下参数添加图片并进行处理：
 
-| 参数       | 描述                                 |
-|----------- |---------------------------------------------|
-| `image`    | 指定卡片的图片URL。       |
-| `method`   | 设置Hugo的图片处理方法。        |
-| `options`  | 配置Hugo的图片处理选项。 |
+| 参数           | 描述                |
+|--------------|-------------------|
+| `image`      | 指定卡片的图片URL。       |
+| `method`     | 设置Hugo的图片处理方法。    |
+| `options`    | 配置Hugo的图片处理选项。    |
+| `imageStyle` | 用于填充图片标签的style属性。 |
 
 卡片支持三种类型的图片：
 

exampleSite/content/docs/guide/shortcodes/filetree.fa.md

@@ -32,3 +32,18 @@ linkTitle: FileTree
   {{</* filetree/file name="hugo.toml" */>}}
 {{</* /filetree/container */>}}
 ```
+
+## خيارات
+
+### `filetree/file`
+
+| المعلمة | وصف        |
+|---------|------------|
+| `name`  | اسم الملف. |
+
+### `filetree/folder`
+
+| المعلمة | وصف                                                                       |
+|---------|---------------------------------------------------------------------------|
+| `name`  | اسم الملف.                                                                |
+| `state` | حالة الملف. يمكن أن تكون `open` أو `closed`. القيمة الافتراضية هي `open`. |

exampleSite/content/docs/guide/shortcodes/filetree.ja.md

@@ -32,3 +32,18 @@ linkTitle: FileTree
   {{</* filetree/file name="hugo.toml" */>}}
 {{</* /filetree/container */>}}
 ```
+
+## オプション
+
+### `filetree/file`
+
+| パラメータ  | 説明       |
+|--------|----------|
+| `name` | ファイルの名前。 |
+
+### `filetree/folder`
+
+| パラメータ   | 説明                                                       |
+|---------|----------------------------------------------------------|
+| `name`  | ファイルの名前。                                                 |
+| `state` | ファイルの状態。`open` または `closed` のいずれかになります。デフォルトは `open` です。 |

exampleSite/content/docs/guide/shortcodes/filetree.md

@@ -32,3 +32,18 @@ linkTitle: FileTree
   {{</* filetree/file name="hugo.toml" */>}}
 {{</* /filetree/container */>}}
 ```
+
+## Options
+
+### `filetree/file`
+
+| Parameter | Description                                                          |
+|-----------|----------------------------------------------------------------------|
+| `name`    | The name of the file.                                                |
+
+### `filetree/folder`
+
+| Parameter | Description                                                          |
+|-----------|----------------------------------------------------------------------|
+| `name`    | The name of the file.                                                |
+| `state`   | The state of the file. Can be `open` or `closed`. Default is `open`. |

exampleSite/content/docs/guide/shortcodes/filetree.zh-cn.md

@@ -32,3 +32,18 @@ linkTitle: 文件树
   {{</* filetree/file name="hugo.toml" */>}}
 {{</* /filetree/container */>}}
 ```
+
+## 选项
+
+### `filetree/file`
+
+| 范围     | 描述     |
+|--------|--------|
+| `name` | 文件的名称。 |
+
+### `filetree/folder`
+
+| 范围      | 描述                                  |
+|---------|-------------------------------------|
+| `name`  | 文件的名称。                              |
+| `state` | 文件的状态。可以是`open`或`closed`。默认为`open`。 |

exampleSite/content/docs/guide/shortcodes/icon.fa.md

@@ -45,3 +45,10 @@ your-icon: <svg>محتوای SVG آیکون شما</svg>
 ```
 
 نکته: [Iconify Design](https://iconify.design/) منبع خوبی برای یافتن آیکون‌های SVG برای سایت شماست.
+
+## خيارات
+
+| المعلمة      | وصف            |
+|--------------|----------------|
+| `name`       | اسم الأيقونة   |
+| `attributes` | سمات الأيقونة. |

exampleSite/content/docs/guide/shortcodes/icon.ja.md

@@ -45,3 +45,10 @@ your-icon: <svg>your icon svg content</svg>
 ```
 
 ヒント: [Iconify Design](https://iconify.design/) はサイト用の SVG アイコンを見つけるのに最適な場所です。
+
+## オプション
+
+| パラメータ        | 説明       |
+|--------------|----------|
+| `name`       | アイコン名    |
+| `attributes` | アイコンの属性。 |

exampleSite/content/docs/guide/shortcodes/icon.md

@@ -45,3 +45,10 @@ It then can be used in the shortcode like this:
 ```
 
 Tip: [Iconify Design](https://iconify.design/) is a great place to find SVG icons for your site.
+
+## Options
+
+| Name         | Description                 |
+|--------------|-----------------------------|
+| `name`       | Icon name                   |
+| `attributes` | The attributes of the icon. |

exampleSite/content/docs/guide/shortcodes/icon.zh-cn.md

@@ -45,3 +45,10 @@ your-icon: <svg>您的图标 SVG 内容</svg>
 ```
 
 提示：[Iconify Design](https://iconify.design/) 是寻找网站 SVG 图标的优质资源平台。
+
+## 选项
+
+| 范围           | 描述     |
+|--------------|--------|
+| `name`       | 图标名称   |
+| `attributes` | 图标的属性。 |

exampleSite/content/docs/guide/shortcodes/others.fa.md

@@ -45,6 +45,16 @@ next: /docs/guide/deploy-site
 
 {{< badge content="انتشارها" link="https://github.com/imfing/hextra/releases" icon="github" >}}
 
+### خيارات
+
+| المعلمة   | وصف                                               |
+|-----------|---------------------------------------------------|
+| `content` | نص الشارة.                                        |
+| `link`    | رابط الشارة.                                      |
+| `icon`    | رمز الشارة.                                       |
+| `type`    | نوع الشارة. (افتراضي، `info`، `warning`، `error`) |
+| `class`   | فئة الشارة.                                       |
+
 ## یوتیوب
 
 تعبیه یک ویدیوی یوتیوب.

exampleSite/content/docs/guide/shortcodes/others.ja.md

@@ -45,6 +45,16 @@ next: /docs/guide/deploy-site
 
 {{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}
 
+### オプション
+
+| パラメータ     | 説明                                      |
+|-----------|-----------------------------------------|
+| `content` | バッジのテキスト。                               |
+| `link`    | バッジのリンク。                                |
+| `icon`    | バッジのアイコン。                               |
+| `type`    | バッジの種類。(デフォルト、`info`、`warning`、`error`) |
+| `class`   | バッジのクラス。                                |
+
 ## YouTube
 
 YouTube 動画を埋め込みます。

exampleSite/content/docs/guide/shortcodes/others.md

@@ -45,6 +45,16 @@ Result:
 
 {{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}
 
+### Options
+
+| Name      | Description                                                  |
+|-----------|--------------------------------------------------------------|
+| `content` | The text of the badge.                                       |
+| `link`    | The link of the badge.                                       |
+| `icon`    | The icon of the badge.                                       |
+| `type`    | The type of the badge. (default, `info`, `warning`, `error`) |
+| `class`   | The class of the badge.                                      |
+
 ## YouTube
 
 Embed a YouTube video.

exampleSite/content/docs/guide/shortcodes/others.zh-cn.md

@@ -45,6 +45,16 @@ next: /docs/guide/deploy-site
 
 {{< badge content="版本发布" link="https://github.com/imfing/hextra/releases" icon="github" >}}
 
+## 选项
+
+| 范围        | 描述                                  |
+|-----------|-------------------------------------|
+| `content` | 徽章的文字。                              |
+| `link`    | 徽章的链接。                              |
+| `icon`    | 徽章的图标。                              |
+| `type`    | 徽章的类型。（默认，`info`，`warning`，`error`） |
+| `class`   | 徽章的等级。                              |
+
 ## YouTube
 
 嵌入YouTube视频。

exampleSite/hugo_stats.json

@@ -334,6 +334,7 @@
       "hx:flex-col",
       "hx:flex-wrap",
       "hx:focus:bg-white",
+      "hx:focus:hextra-focus",
       "hx:focus:outline-hidden",
       "hx:focus:ring-4",
       "hx:focus:ring-primary-300",

layouts/_partials/language-switch.html

@@ -1,4 +1,9 @@
 {{- $page := .context -}}
+{{- $iconName := .iconName | default "globe-alt" -}}
+{{- $iconHeight := .iconHeight | default 12 -}}
+{{- $location := .location -}}
+
+{{- $class := .class | default "hx:h-7 hx:px-2 hx:text-xs hx:text-gray-600 hx:transition-colors hx:dark:text-gray-400 hx:hover:bg-gray-100 hx:hover:text-gray-900 hx:dark:hover:bg-primary-100/5 hx:dark:hover:text-gray-50" -}}
 
 {{- $grow := .grow -}}
 {{- $hideLabel := .hideLabel | default false -}}
@@ -10,12 +15,13 @@
     <button
       title="{{ $changeLanguage }}"
       data-state="closed"
-      class="hextra-language-switcher hx:cursor-pointer hx:h-7 hx:rounded-md hx:px-2 hx:text-left hx:text-xs hx:font-medium hx:text-gray-600 hx:transition-colors hx:dark:text-gray-400 hx:hover:bg-gray-100 hx:hover:text-gray-900 hx:dark:hover:bg-primary-100/5 hx:dark:hover:text-gray-50 hx:grow"
+      data-location="{{ $location }}"
+      class="hextra-language-switcher hx:cursor-pointer hx:rounded-md hx:text-left hx:font-medium {{ $class }} hx:grow"
       type="button"
       aria-label="{{ $changeLanguage }}"
     >
       <div class="hx:flex hx:items-center hx:gap-2 hx:capitalize">
-        {{- partial "utils/icon" (dict "name" "globe-alt" "attributes" "height=12") -}}
+        {{- partial "utils/icon" (dict "name" $iconName "attributes" (printf "height=%d" $iconHeight)) -}}
         {{- if not $hideLabel }}<span>{{ site.Language.LanguageName }}</span>{{ end -}}
       </div>
     </button>

layouts/_partials/navbar.html

@@ -7,6 +7,8 @@
   {{ end -}}
 {{- end -}}
 
+{{- $page := . -}}
+{{- $iconHeight := 24 -}}
 
 <div class="hextra-nav-container hx:sticky hx:top-0 hx:z-20 hx:w-full hx:bg-transparent hx:print:hidden">
   <div
@@ -33,9 +35,13 @@
         {{- if .Params.icon -}}
           {{- $rel := cond (eq .Params.icon "mastodon") "noreferrer me" "noreferrer" }}
           <a class="hx:p-2 hx:text-current" {{ if $external }}target="_blank" rel="{{ $rel }}"{{ end }} href="{{ $link }}" title="{{ or (T .Identifier) .Name | safeHTML }}">
-            {{- partial "utils/icon.html" (dict "name" .Params.icon "attributes" "height=24") -}}
+            {{- partial "utils/icon.html" (dict "name" .Params.icon "attributes" (printf "height=%d" $iconHeight)) -}}
             <span class="hx:sr-only">{{ or (T .Identifier) .Name | safeHTML }}</span>
           </a>
+        {{- else if eq .Params.type "theme-toggle" -}}
+          {{- partial "theme-toggle.html" (dict "iconHeight" $iconHeight "class" "hx:p-2" "hideLabel" (not .Params.label)) -}}
+        {{- else if eq .Params.type "language-switch" -}}
+          {{- partial "language-switch" (dict "context" $page "grow" false "hideLabel" (not .Params.label) "iconName" (.Params.icon | default "translate") "iconHeight" $iconHeight "location" "top" "class" "hx:p-2") -}}
         {{- else -}}
           {{- $active := or ($currentPage.HasMenuCurrent "main" .) ($currentPage.IsMenuCurrent "main" .) -}}
           {{- $activeClass := cond $active "hx:font-medium" "hx:text-gray-600 hx:hover:text-gray-800 hx:dark:text-gray-400 hx:dark:hover:text-gray-200" -}}
@@ -94,7 +100,7 @@
 
 
     <button type="button" aria-label="Menu" class="hextra-hamburger-menu hx:cursor-pointer hx:-mr-2 hx:rounded-sm hx:p-2 hx:active:bg-gray-400/20 hx:md:hidden">
-      {{- partial "utils/icon.html" (dict "name" "hamburger-menu" "attributes" "height=24") -}}
+      {{- partial "utils/icon.html" (dict "name" "hamburger-menu" "attributes" (printf "height=%d" $iconHeight)) -}}
     </button>
   </nav>
 </div>

layouts/_partials/search.html

@@ -5,7 +5,7 @@
   <div class="hx:relative hx:flex hx:items-center hx:text-gray-900 hx:contrast-more:text-gray-800 hx:dark:text-gray-300 hx:contrast-more:dark:text-gray-300">
     <input
       placeholder="{{ $placeholder }}"
-      class="hextra-search-input hx:block hx:w-full hx:appearance-none hx:rounded-lg hx:px-3 hx:py-2 hx:transition-colors hx:text-base hx:leading-tight hx:md:text-sm hx:bg-black/[.05] hx:dark:bg-gray-50/10 hx:focus:bg-white hx:dark:focus:bg-dark hx:placeholder:text-gray-500 hx:dark:placeholder:text-gray-400 hx:contrast-more:border hx:contrast-more:border-current"
+      class="hextra-search-input hx:focus:hextra-focus hx:block hx:w-full hx:appearance-none hx:rounded-lg hx:px-3 hx:py-2 hx:transition-colors hx:text-base hx:leading-tight hx:md:text-sm hx:bg-black/[.05] hx:dark:bg-gray-50/10 hx:focus:bg-white hx:dark:focus:bg-dark hx:placeholder:text-gray-500 hx:dark:placeholder:text-gray-400 hx:contrast-more:border hx:contrast-more:border-current"
       type="search"
       value=""
       spellcheck="false"

layouts/_partials/shortcodes/badge.html

@@ -1,16 +1,18 @@
 {{- $content := .content -}}
-{{- $type := .type -}}
+{{- $type := .type | default "" -}}
 {{- $class := .class | default "" -}}
 {{- $border := .border | default false -}}
 {{- $icon := .icon | default "" -}}
 
 {{- $defaultClass := "hx:text-gray-600 hx:bg-gray-100 hx:dark:bg-neutral-800 hx:dark:text-neutral-200 hx:border-gray-200 hx:dark:border-neutral-700" -}}
-{{- $warningClass := "hx:border-yellow-100 hx:bg-yellow-50 hx:text-yellow-900 hx:dark:border-yellow-200/30 hx:dark:bg-yellow-700/30 hx:dark:text-yellow-200" -}}
-{{- $infoClass := "hx:border-blue-200 hx:bg-blue-100 hx:text-blue-900 hx:dark:border-blue-200/30 hx:dark:bg-blue-900/30 hx:dark:text-blue-200" -}}
-{{- $errorClass := "hx:border-red-200 hx:bg-red-100 hx:text-red-900 hx:dark:border-red-200/30 hx:dark:bg-red-900/30 hx:dark:text-red-200" -}}
+
+{{- $styleClass := newScratch -}}
+{{- $styleClass.Set "info" "hx:border-blue-200 hx:bg-blue-100 hx:text-blue-900 hx:dark:border-blue-200/30 hx:dark:bg-blue-900/30 hx:dark:text-blue-200" -}}
+{{- $styleClass.Set "warning" "hx:border-yellow-100 hx:bg-yellow-50 hx:text-yellow-900 hx:dark:border-yellow-200/30 hx:dark:bg-yellow-700/30 hx:dark:text-yellow-200" -}}
+{{- $styleClass.Set "error" "hx:border-red-200 hx:bg-red-100 hx:text-red-900 hx:dark:border-red-200/30 hx:dark:bg-red-900/30 hx:dark:text-red-200" -}}
 
 {{- $borderClass := cond (eq $border true) "hx:border" "" -}}
-{{- $badgeClass := cond (eq $type "info") $infoClass (cond (eq $type "warning") $warningClass (cond (eq $type "error") $errorClass $defaultClass)) -}}
+{{- $badgeClass := or ($styleClass.Get $type) $defaultClass -}}
 <div class="hextra-badge {{ $class }}">
   <div class="hx:inline-flex hx:gap-1 hx:items-center hx:rounded-full hx:px-2.5 hx:leading-6 hx:text-[.65rem] {{ $borderClass }} {{ $badgeClass }}">
     {{- with $icon -}}{{- partial "utils/icon" (dict "name" . "attributes" "height=12") -}}{{- end -}}

layouts/_partials/shortcodes/card.html

@@ -1,4 +1,3 @@
-{{- $page := .page -}}
 {{- $link := .link -}}
 {{- $title := .title -}}
 {{- $icon := .icon -}}

layouts/_partials/theme-toggle.html

@@ -1,21 +1,22 @@
-{{- $hideLabel := .hideLabel | default false -}}
+{{- $hideLabel := .hideLabel -}}
+{{- $iconHeight := .iconHeight | default 12 -}}
+{{- $class := .class | default "hx:h-7 hx:px-2 hx:text-xs hx:hover:bg-gray-100 hx:hover:text-gray-900 hx:dark:hover:bg-primary-100/5 hx:dark:hover:text-gray-50 hx:font-medium hx:text-gray-600 hx:transition-colors hx:dark:text-gray-400" -}}
 
 {{- $changeTheme := (T "changeTheme") | default "Change theme" -}}
 {{- $light := (T "light") | default "Light" -}}
 {{- $dark := (T "dark") | default "Dark" -}}
 
-
 <button
   title="{{ $changeTheme }}"
   data-theme="light"
-  class="hextra-theme-toggle hx:cursor-pointer hx:group hx:h-7 hx:rounded-md hx:px-2 hx:text-left hx:text-xs hx:font-medium hx:text-gray-600 hx:transition-colors hx:dark:text-gray-400 hx:hover:bg-gray-100 hx:hover:text-gray-900 hx:dark:hover:bg-primary-100/5 hx:dark:hover:text-gray-50"
+  class="hextra-theme-toggle hx:cursor-pointer hx:group hx:rounded-md hx:text-left {{ $class }}"
   type="button"
   aria-label="{{ $changeTheme }}"
 >
   <div class="hx:flex hx:items-center hx:gap-2 hx:capitalize">
-    {{- partial "utils/icon.html" (dict "name" "sun" "attributes" "height=12 class=\"hx:group-data-[theme=light]:hidden\"") -}}
+    {{- partial "utils/icon.html" (dict "name" "sun" "attributes" (printf "height=%d class=\"hx:group-data-[theme=light]:hidden\"" $iconHeight)) -}}
     {{- if not $hideLabel }}<span class="hx:group-data-[theme=light]:hidden">{{ $light }}</span>{{ end -}}
-    {{- partial "utils/icon.html" (dict "name" "moon" "attributes" "height=12 class=\"hx:group-data-[theme=dark]:hidden\"") -}}
+    {{- partial "utils/icon.html" (dict "name" "moon" "attributes" (printf "height=%d class=\"hx:group-data-[theme=dark]:hidden\"" $iconHeight)) -}}
     {{- if not $hideLabel }}<span class="hx:group-data-[theme=dark]:hidden">{{ $dark }}</span>{{ end -}}
   </div>
 </button>

layouts/_shortcodes/callout.html

@@ -21,10 +21,12 @@ A shortcode to create a callout.
 {{- $content := .InnerDeindent | markdownify -}}
 
 {{- $defaultClass := "hx:border-orange-100 hx:bg-orange-50 hx:text-orange-800 hx:dark:border-orange-400/30 hx:dark:bg-orange-400/20 hx:dark:text-orange-300" -}}
-{{- $infoClass := "hx:border-blue-200 hx:bg-blue-100 hx:text-blue-900 hx:dark:border-blue-200/30 hx:dark:bg-blue-900/30 hx:dark:text-blue-200" -}}
-{{- $warningClass := "hx:border-yellow-100 hx:bg-yellow-50 hx:text-yellow-900 hx:dark:border-yellow-200/30 hx:dark:bg-yellow-700/30 hx:dark:text-yellow-200" -}}
-{{- $errorClass := "hx:border-red-200 hx:bg-red-100 hx:text-red-900 hx:dark:border-red-200/30 hx:dark:bg-red-900/30 hx:dark:text-red-200" -}}
 
-{{- $class := cond (eq $type "info") $infoClass (cond (eq $type "warning") $warningClass (cond (eq $type "error") $errorClass $defaultClass)) -}}
+{{- $styleClass := newScratch -}}
+{{- $styleClass.Set "info" "hx:border-blue-200 hx:bg-blue-100 hx:text-blue-900 hx:dark:border-blue-200/30 hx:dark:bg-blue-900/30 hx:dark:text-blue-200" -}}
+{{- $styleClass.Set "warning" "hx:border-yellow-100 hx:bg-yellow-50 hx:text-yellow-900 hx:dark:border-yellow-200/30 hx:dark:bg-yellow-700/30 hx:dark:text-yellow-200" -}}
+{{- $styleClass.Set "error" "hx:border-red-200 hx:bg-red-100 hx:text-red-900 hx:dark:border-red-200/30 hx:dark:bg-red-900/30 hx:dark:text-red-200" -}}
+
+{{- $class := or ($styleClass.Get $type) $defaultClass -}}
 
 {{- partial "shortcodes/callout.html" (dict "content" $content "emoji" $emoji "icon" $icon "class" $class) -}}

layouts/_shortcodes/card.html

@@ -15,7 +15,6 @@ A shortcode to create a card.
 @example {{< card link="/" title="Image Card" }}
 */ -}}
 
-{{- $context := . -}}
 {{- $link := .Get "link" -}}
 {{- $title := .Get "title" -}}
 {{- $icon := .Get "icon" -}}