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/navbar.css

@@ -1,5 +1,5 @@
 nav {
-  .search-wrapper {
+  .hextra-search-wrapper {
     @apply hx:hidden hx:md:inline-block;
   }
 }

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/flexsearch.js

@@ -392,7 +392,7 @@ document.addEventListener("DOMContentLoaded", function () {
     function highlightMatches(text, query) {
       const escapedQuery = query.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&');
       const regex = new RegExp(escapedQuery, 'gi');
-      return text.replace(regex, (match) => `<span class="match">${match}</span>`);
+      return text.replace(regex, (match) => `<span class="hextra-search-match">${match}</span>`);
     }
 
     // Create a DOM element from the HTML string.
@@ -405,11 +405,11 @@ document.addEventListener("DOMContentLoaded", function () {
     function handleMouseMove(e) {
       const target = e.target.closest('a');
       if (target) {
-        const active = resultsElement.querySelector('a.active');
+        const active = resultsElement.querySelector('a.hextra-search-active');
         if (active) {
-          active.classList.remove('active');
+          active.classList.remove('hextra-search-active');
         }
-        target.classList.add('active');
+        target.classList.add('hextra-search-active');
       }
     }
 

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,14 +16,18 @@ 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;
+  let isHashNavigation = false;
 
   // Create intersection observer
   const observer = new IntersectionObserver(
     (entries) => {
+      // Skip observer updates during hash navigation
+      if (isHashNavigation) return;
+
       const visibleHeadings = entries.filter((entry) => entry.isIntersecting).map((entry) => entry.target);
 
       if (visibleHeadings.length === 0) return;
@@ -35,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) {
@@ -50,7 +55,7 @@ document.addEventListener("DOMContentLoaded", function () {
       }
     },
     {
-      rootMargin: "-20px 0px -80% 0px", // Adjust sensitivity
+      rootMargin: "-20px 0px -60% 0px", // Adjust sensitivity
       threshold: [0, 0.1, 0.5, 1],
     }
   );
@@ -58,11 +63,31 @@ document.addEventListener("DOMContentLoaded", function () {
   // Observe all headings
   headings.forEach((heading) => observer.observe(heading));
 
-  // Handle edge case: if no headings are visible on initial load
-  setTimeout(() => {
-    if (!currentActiveLink && tocLinks.length > 0) {
-      tocLinks[0].classList.add("hextra-toc-active");
-      currentActiveLink = tocLinks[0];
+  // Handle direct navigation to page with hash
+  function handleHashNavigation() {
+    const hash = window.location.hash; // already url encoded
+    if (hash) {
+      const targetLink = toc.querySelector(`a[href="${hash}"]`);
+      if (targetLink) {
+        // Disable observer temporarily during hash navigation
+        isHashNavigation = true;
+
+        if (currentActiveLink) {
+          currentActiveLink.classList.remove("hextra-toc-active");
+        }
+        targetLink.classList.add("hextra-toc-active");
+        currentActiveLink = targetLink;
+
+        // Re-enable observer after scroll settles
+        setTimeout(() => { isHashNavigation = false; }, 500);
+        return;
+      }
     }
-  }, 100);
+  }
+
+  // Handle hash changes navigation
+  window.addEventListener("hashchange", handleHashNavigation);
+
+  // Handle initial load
+  setTimeout(handleHashNavigation, 100);
 });

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.9.6: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/badge.html

@@ -1,3 +1,19 @@
+{{- /*
+A shortcode to create a badge.
+
+@param {string} content The content of the badge.
+@param {string} type The type of the badge.
+@param {string} class The class of the badge.
+@param {string} link The link of the badge.
+@param {string} icon The icon of the badge.
+
+or
+
+@param {string} 0 The content of the badge.
+
+@example {{< badge content="info" type="info" >}}
+*/ -}}
+
 {{- if .IsNamedParams -}}
   {{- $content := .Get "content" -}}
   {{- $type := .Get "type" | default "" -}}

layouts/_shortcodes/callout.html

@@ -1,3 +1,14 @@
+{{- /*
+A shortcode to create a callout.
+
+@param {string} type The type of the callout (default, info, warning, error).
+@param {string} content The content of the callout.
+@param {string} emoji The emoji of the callout (related to type or can be a custom emoji).
+@param {string} icon The icon of the callout.
+
+@example {{< callout type="info" >}}Content{{< /callout >}}
+*/ -}}
+
 {{- $calloutEmojiDict := dict "info" "ℹ️" "warning" "⚠️" "error" "🚫" -}}
 {{- $type := .Get "type" | default "default" -}}
 {{/* If emoji is not set, use the emoji from dict */}}
@@ -10,10 +21,12 @@
 {{- $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

@@ -1,4 +1,20 @@
-{{- $context := . -}}
+{{- /*
+A shortcode to create a card.
+
+@param {string} link The link to the card.
+@param {string} title The title of the card.
+@param {string} icon The icon of the card.
+@param {string} subtitle The subtitle of the card.
+@param {string} tag The tag of the card.
+@param {string} tagType The type of the tag.
+@param {string} image The image of the card.
+@param {string} method The method to process the image.
+@param {string} options The options to process the image.
+@param {string} imageStyle The style of the image.
+
+@example {{< card link="/" title="Image Card" }}
+*/ -}}
+
 {{- $link := .Get "link" -}}
 {{- $title := .Get "title" -}}
 {{- $icon := .Get "icon" -}}

layouts/_shortcodes/cards.html

@@ -1,3 +1,11 @@
+{{- /*
+A shortcode for creating cards.
+
+@param {string} cols The number of columns.
+
+@example {{< cards cols="3" >}}{{< /cards >}}
+*/ -}}
+
 {{- $cols := .Get "cols" | default 3 -}}
 
 {{- partial "shortcodes/cards" (dict "cols" $cols "content" .Inner) -}}

layouts/_shortcodes/details.html

@@ -1,3 +1,12 @@
+{{- /*
+A built-in component to display a collapsible content.
+
+@param {string} title The title of the details.
+@param {string} closed Whether the details are closed or not (default: false).
+
+@example {{% details title="Details" %}}Content{{% /details %}}
+*/ -}}
+
 {{- $title := .Get "title" | default "" -}}
 {{- $closed := eq (.Get "closed") "true" | default false -}}
 

layouts/_shortcodes/filetree/container.html

@@ -1,3 +1,9 @@
+{{- /*
+A file tree container.
+
+@example {{< filetree/container >}}{{< /filetree/container >}}
+*/ -}}
+
 <div class="hextra-filetree hx:mt-6 hx:select-none hx:text-sm hx:text-gray-800 hx:dark:text-gray-300 not-prose">
   <div class="hx:inline-block hx:rounded-lg hx:px-4 hx:py-2 hx:border hx:border-gray-200 hx:dark:border-neutral-800">
     {{- .InnerDeindent -}}

layouts/_shortcodes/filetree/file.html

@@ -1,5 +1,12 @@
-{{- $name := .Get "name" -}}
+{{- /*
+A file in a file tree.
 
+@param {string} name The name of the file.
+
+@example {{< filetree/file name="_index.md" >}}
+*/ -}}
+
+{{- $name := .Get "name" -}}
 
 <li class="hx:flex hx:list-none">
   <span class="hx:inline-flex hx:cursor-default hx:items-center hx:py-1">

layouts/_shortcodes/filetree/folder.html

@@ -1,3 +1,12 @@
+{{- /*
+A folder in a file tree.
+
+@param {string} name The name of the folder.
+@param {string} state The state of the folder.
+
+@example {{< filetree/folder name="docs" state="closed" >}}
+*/ -}}
+
 {{- $name := .Get "name" -}}
 {{- $state := .Get "state" | default "open" }}
 

layouts/_shortcodes/hextra/feature-card.html

@@ -1,3 +1,18 @@
+{{- /*
+A shortcode for displaying a feature card.
+
+@param {string} title The title of the card.
+@param {string} subtitle The subtitle of the card.
+@param {string} class The class of the card.
+@param {string} image The image of the card.
+@param {string} imageClass The class of the image.
+@param {string} style The style of the card.
+@param {string} icon The icon of the card.
+@param {string} link The link of the card.
+
+@example {{< hextra/feature-card title="Feature Card" subtitle="This is a feature card." >}}
+*/ -}}
+
 {{- $title := .Get "title" -}}
 {{- $subtitle := .Get "subtitle" -}}
 {{- $class := .Get "class" -}}

layouts/_shortcodes/hextra/feature-grid.html

@@ -1,3 +1,12 @@
+{{- /*
+A shortcode for displaying a feature grid.
+
+@param {string} cols The number of columns.
+@param {string} style The style of the grid.
+
+@example {{< hextra/feature-grid cols="3" >}}{{< /hextra/feature-grid >}}
+*/ -}}
+
 {{- $cols := .Get "cols" | default 3 -}}
 {{- $style := .Get "style" | default "" -}}
 

layouts/_shortcodes/hextra/hero-badge.html

@@ -1,10 +1,19 @@
+{{- /*
+A shortcode for rendering a badge with a link.
+
+@param {string} link The link of the badge.
+@param {string} class The class of the badge.
+@param {string} style The style of the badge.
+
+@example {{< hextra/hero-badge >}}{{< /hextra/hero-badge >}}
+*/ -}}
+
 {{- $link := .Get "link" -}}
 {{- $external := hasPrefix $link "http" -}}
 {{- $href := cond (hasPrefix $link "/") ($link | relURL) $link -}}
 {{- $class := .Get "class" }}
 {{- $style := .Get "style" -}}
 
-
 <a
   {{ if $link }}href="{{ $href }}"{{ end }}
   class="{{ $class }} not-prose hx:inline-flex hx:items-center hx:rounded-full hx:gap-2 hx:px-3 hx:py-1 hx:text-xs hx:text-gray-600 hx:dark:text-gray-400 hx:bg-gray-100 hx:dark:bg-neutral-800 hx:border-gray-200 hx:dark:border-neutral-800 hx:border hx:hover:border-gray-400 hx:dark:hover:text-gray-50 hx:dark:hover:border-gray-600 hx:transition-all hx:ease-in hx:duration-200"

layouts/_shortcodes/hextra/hero-button.html

@@ -1,3 +1,13 @@
+{{- /*
+A shortcode for rendering a button with a link.
+
+@param {string} link The link of the button.
+@param {string} text The text of the button.
+@param {string} style The style of the button.
+
+@example {{< hextra/hero-button text="Get Started" link="docs" >}}
+*/ -}}
+
 {{- $link := .Get "link" -}}
 {{- $text := .Get "text" -}}
 {{- $style := .Get "style" -}}

layouts/_shortcodes/hextra/hero-container.html

@@ -1,3 +1,21 @@
+{{- /*
+A simple hero container with an image on the left side.
+
+@param {string} class The class of the container.
+@param {string} cols The number of columns (default: 2).
+@param {string} image The image of the container.
+@param {bool} imageCard Whether to display the image as a card (default: false).
+@param {string} imageClass The class of the image.
+@param {string} imageLink The link of the image.
+@param {string} imageStyle The style of the image.
+@param {string} imageTitle The title of the image.
+@param {int} imageWidth The width of the image (default: 350).
+@param {int} imageHeight The height of the image (default: 350).
+@param {string} style The style of the container.
+
+@example {{< hextra/hero-container image="image.png" imageLink="https://example.com" imageTitle="Example Image" >}}
+*/ -}}
+
 {{- $class := .Get "class" -}}
 {{- $cols := .Get "cols" | default 2 -}}
 {{- $image := .Get "image" -}}

layouts/_shortcodes/hextra/hero-headline.html

@@ -1,5 +1,12 @@
-{{- $style := .Get "style" -}}
+{{- /*
+A shortcode for displaying a hero headline.
 
+@param {string} style The style of the headline.
+
+@example {{< hextra/hero-headline >}}{{< /hextra/hero-headline >}}
+*/ -}}
+
+{{- $style := .Get "style" -}}
 
 <h1
   class="not-prose hx:text-4xl hx:font-bold hx:leading-none hx:tracking-tighter hx:md:text-5xl hx:py-2 hx:bg-clip-text hx:text-transparent hx:bg-gradient-to-r hx:from-gray-900 hx:to-gray-600 hx:dark:from-gray-100 hx:dark:to-gray-400"

layouts/_shortcodes/hextra/hero-section.html

@@ -1,3 +1,13 @@
+{{- /*
+A simple hero section with a heading and optional style.
+
+@param {string} heading The heading level (default: h2).
+@param {string} style The style of the heading.
+@param {string} content The content of the heading.
+
+@example {{< hextra/hero-section heading="h3" >}}{{< /hextra/hero-section >}}>
+*/ -}}
+
 {{- $style := .Get "style" -}}
 {{- $heading := int (strings.TrimPrefix "h" (.Get "heading" | default "h2")) -}}
 {{- $size := cond (ge $heading 4) "xl" (cond (eq $heading 3) "2xl" "4xl") -}}

layouts/_shortcodes/hextra/hero-subtitle.html

@@ -1,5 +1,12 @@
-{{- $style := .Get "style" -}}
+{{- /*
+A shortcode for displaying a hero subtitle.
 
+@param {string} style The style of the subtitle.
+
+@example {{< hextra/hero-subtitle >}}{{< /hextra/hero-subtitle >}}
+*/ -}}
+
+{{- $style := .Get "style" -}}
 
 <p
   class="not-prose hx:text-xl hx:text-gray-600 hx:dark:text-gray-400 hx:sm:text-xl"

layouts/_shortcodes/icon.html

@@ -1,3 +1,17 @@
+{{- /*
+Create an icon.
+
+@param {string} name The name of the icon.
+@param {string} attributes The attributes of the icon.
+
+or
+
+@param {string} 0 The name of the icon.
+
+@example {{< icon name="github" >}}
+@example {{< icon "github" >}}
+*/ -}}
+
 {{- $name := .Get "name" | default (.Get 0) -}}
 {{- $icon := index site.Data.icons $name -}}
 {{- $attributes := .Get "attributes" | default "height=1em"}}

layouts/_shortcodes/jupyter.html

@@ -1,4 +1,11 @@
-{{/* Render Jupyter Notebook */}}
+{{- /*
+Render Jupyter Notebook
+
+@param {string} 0 The path of the Jupyter Notebook.
+
+@example {{% jupyter "notebook.ipynb" %}}
+*/ -}}
+
 {{- $path := .Get 0 -}}
 {{- $data := "" -}}
 {{- $page := .Page -}}

layouts/_shortcodes/pdf.html

@@ -1,4 +1,10 @@
-{{/* Shortcode to include a PDF file in a page. */}}
+{{- /*
+Shortcode to include a PDF file in a page.
+
+@param {string} 0 The path to the PDF file.
+
+@example {{< pdf "path/to/file.pdf" >}}
+*/ -}}
 
 {{- $path := .Get 0 -}}
 {{- $url := partial "utils/file-path" (dict "page" .Page "path" $path) -}}

layouts/_shortcodes/steps.html

@@ -1,3 +1,9 @@
+{{- /*
+A shortcode for creating a step list.
+
+@example {{% steps %}}{{% /steps %}}
+*/ -}}
+
 <div class="hextra-steps hx:ml-4 hx:mb-12 hx:ltr:border-l hx:rtl:border-r hx:border-gray-200 hx:ltr:pl-6 hx:rtl:pr-6 hx:dark:border-neutral-800 [counter-reset:step]">
   {{- .Inner -}}
 </div>

layouts/_shortcodes/tab.html

@@ -1,3 +1,9 @@
+{{- /*
+Create a tab.
+
+@example {{< tab >}}content{{< /tab >}}
+*/ -}}
+
 {{- $defaultIndex := int ((.Parent.Get "defaultIndex") | default "0") -}}
 
 <div

layouts/_shortcodes/tabs.html

@@ -1,3 +1,12 @@
+{{- /*
+Create a tabbed interface with the given items.
+
+@param {string} items The items to display in the tabs.
+@param {string} defaultIndex The index of the default tab.
+
+@example {{< tabs items="JSON,YAML,TOML" >}}{{< /tabs >}}
+*/ -}}
+
 {{- $items := split (.Get "items") "," -}}
 {{- $defaultIndex := int ((.Get "defaultIndex") | default "0") -}}