chore: release blog for Hextra v0.11 (#806)

* feat: release Hextra v0.11 with new features and improvements

- Updated banner key to 'announcement-v0.11' with a new message.
- Added new padding option 'hx:px-8' in hugo_stats.json.
- Introduced new blog post for Hextra v0.11 detailing UX enhancements, new components, and stability fixes.
- Added translations for the new blog post in French, Japanese, and Simplified Chinese.
- Updated getting started documentation to include instructions for using the development branch.
- Removed outdated banner HTML for v0.10.

* feat: update language banners for Hextra v0.11 release

- Added localized banner messages for Persian, Japanese, and Simplified Chinese.
- Updated the main announcement message format in the configuration file.

* Update exampleSite/content/blog/v0.11.md

Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>

* Update exampleSite/content/blog/v0.11.md

Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>

* Update blog post for Hextra v0.11 release

- Refined upgrade guide and removed unnecessary breaking change note.
- Enhanced descriptions for new features including the top banner, callouts, and analytics configuration.
- Improved clarity in code examples and added links to documentation for new components.
- Updated navbar enhancements and breadcrumbs enablement instructions.
- Fixed formatting inconsistencies and improved overall readability.

* Add blog post for Hextra v0.11 in Persian, Japanese, and Simplified Chinese

- Introduced new features including a site-wide top banner, redesigned callouts, and analytics support for Umami and Matomo.
- Enhanced navigation with icon support and improved layout.
- Added Asciinema shortcode for terminal recordings and external link decoration options.
- Updated upgrade guide and documentation for new components.
- Included stability fixes and quality of life improvements.

---------

Co-authored-by: Ludovic Fernandez <ldez@users.noreply.github.com>

assets/css/components/banner.css

@@ -0,0 +1,12 @@
+.hextra-banner-hidden .hextra-banner {
+  display: none;
+}
+
+.hextra-banner {
+  :where(a):not(:where([class~=not-prose],[class~=not-prose] *)) {
+    @apply hx:underline hx:decoration-from-font;
+  }
+  :where(p):not(:where([class~=not-prose],[class~=not-prose] *)) {
+    @apply hx:leading-7 hx:first:mt-0;
+  }
+}

assets/css/components/cards.css

@@ -10,11 +10,11 @@
   user-select: none;
 }
 
-.hextra-card:hover svg {
+.hextra-card:hover .hextra-card-icon svg {
   color: currentColor;
 }
 
-.hextra-card svg {
+.hextra-card .hextra-card-icon svg {
   width: 1.5rem;
   color: #00000033;
   transition: color 0.3s ease;
@@ -25,17 +25,22 @@
   position: relative;
 }
 
-.dark .hextra-card svg {
+.dark .hextra-card .hextra-card-icon svg {
   color: #ffffff66;
 }
 
-.dark .hextra-card:hover svg {
+.dark .hextra-card:hover .hextra-card-icon svg {
   color: currentColor;
 }
 
 .hextra-card-tag {
   position: absolute;
-  top: 5px;
-  right: 5px;
   z-index: 10;
+  top: 5px;
+  &:where(:dir(ltr)) {
+    right: 5px;
+  }
+  &:where(:dir(rtl)) {
+    left: 5px;
+  }
 }

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/components/sidebar.css

@@ -1,6 +1,6 @@
 @media (max-width: 48rem) {
   .hextra-sidebar-container {
-    @apply hx:fixed hx:pt-[calc(var(--navbar-height))] hx:top-0 hx:w-full hx:bottom-0 hx:z-[15] hx:overscroll-contain hx:bg-white hx:dark:bg-dark;
+    @apply hx:fixed hx:pt-[calc(var(--navbar-height)+var(--hextra-banner-height))] hx:top-0 hx:w-full hx:bottom-0 hx:z-[15] hx:overscroll-contain hx:bg-white hx:dark:bg-dark;
     transition: transform 0.4s cubic-bezier(0.52, 0.16, 0.04, 1);
     will-change: transform, opacity;
     contain: layout style;

assets/css/styles.css

@@ -29,6 +29,7 @@ body {
   --primary-saturation: 100%;
   --primary-lightness: 50%;
   --navbar-height: 4rem;
+  --hextra-banner-height: 2rem;
   --menu-height: 3.75rem; /* 60px */
 }
 
@@ -38,12 +39,17 @@ 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";
 @import "./components/steps.css";
 @import "./components/search.css";
 @import "./components/sidebar.css";
+@import "./components/banner.css";
 @import "./components/navbar.css";
 @import "./components/scrollbar.css";
 @import "./components/code-copy.css";

assets/css/typography.css

@@ -60,6 +60,10 @@
       @apply hx:my-2;
     }
   }
+  /* Task lists - hide list markers for lists containing checkboxes */
+  :where(ul):not(:where([class~=not-prose],[class~=not-prose] *)):has(li input[type="checkbox"]) {
+    @apply hx:list-none;
+  }
   /* This CSS rule targets the first nested unordered (ul) or ordered (ol) list
      inside the list item (li) of any parent ul or ol.
      The rule sets the top margin of the selected list to zero. */

assets/js/banner.js

@@ -0,0 +1,15 @@
+// {{- if site.Params.banner }}
+(function () {
+  const banner = document.querySelector(".hextra-banner")
+  document.documentElement.style.setProperty("--hextra-banner-height", banner.clientHeight+"px");
+
+  const closeBtn = banner.querySelector(".hextra-banner-close-button");
+
+  closeBtn.addEventListener("click", () => {
+    document.documentElement.classList.add("hextra-banner-hidden");
+    document.documentElement.style.setProperty("--hextra-banner-height", "0px");
+
+    localStorage.setItem('{{ site.Params.banner.key | default `banner-closed` }}', "0");
+  });
+})();
+// {{- end -}}

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

@@ -1,20 +1,18 @@
 (function () {
   const languageSwitchers = document.querySelectorAll('.hextra-language-switcher');
+
   languageSwitchers.forEach((switcher) => {
     switcher.addEventListener('click', (e) => {
       e.preventDefault();
-      switcher.dataset.state = switcher.dataset.state === 'open' ? 'closed' : 'open';
-      const optionsElement = switcher.nextElementSibling;
-      optionsElement.classList.toggle('hx:hidden');
 
-      // Calculate position of language options element
+      switcher.dataset.state = switcher.dataset.state === 'open' ? 'closed' : 'open';
-      const switcherRect = switcher.getBoundingClientRect();
+
-      const translateY = switcherRect.top - window.innerHeight - 15;
+      toggleMenu(switcher);
-      optionsElement.style.transform = `translate3d(${switcherRect.left}px, ${translateY}px, 0)`;
-      optionsElement.style.minWidth = `${Math.max(switcherRect.width, 50)}px`;
     });
   });
 
+  window.addEventListener("resize", () => languageSwitchers.forEach(resizeMenu))
+
   // Dismiss language switcher when clicking outside
   document.addEventListener('click', (e) => {
     if (e.target.closest('.hextra-language-switcher') === null) {

assets/js/switcher-menu.js

@@ -0,0 +1,52 @@
+function computeMenuTranslation(switcher, optionsElement) {
+  // Calculate the position of a language options element.
+  const switcherRect = switcher.getBoundingClientRect();
+
+  // Must be called before optionsElement.clientWidth.
+  optionsElement.style.minWidth = `${Math.max(switcherRect.width, 50)}px`;
+
+  const isOnTop = switcher.dataset.location === 'top';
+  const isOnBottom = switcher.dataset.location === 'bottom';
+  const isOnBottomRight = switcher.dataset.location === 'bottom-right';
+  const isRTL = document.documentElement.dir === 'rtl'
+
+  // Stuck on the left side of the switcher.
+  let x = switcherRect.left;
+
+  if (isOnTop && !isRTL || isOnBottom && isRTL || isOnBottomRight && !isRTL) {
+    // Stuck on the right side of the switcher.
+    x = switcherRect.right - optionsElement.clientWidth;
+  }
+
+  // Stuck on the top of the switcher.
+  let y = switcherRect.top - window.innerHeight - 10;
+
+  if (isOnTop) {
+    // Stuck on the bottom of the switcher.
+    y = switcherRect.top - window.innerHeight + optionsElement.clientHeight + switcher.clientHeight + 4;
+  }
+
+  return { x: x, y: y };
+}
+
+function toggleMenu(switcher) {
+  const optionsElement = switcher.nextElementSibling;
+
+  optionsElement.classList.toggle('hx:hidden');
+
+  // Calculate the position of a language options element.
+  const translate = computeMenuTranslation(switcher, optionsElement);
+
+  optionsElement.style.transform = `translate3d(${translate.x}px, ${translate.y}px, 0)`;
+}
+
+function resizeMenu(switcher) {
+  const optionsElement = switcher.nextElementSibling;
+
+  if (optionsElement.classList.contains('hx:hidden')) return;
+
+  // Calculate the position of a language options element.
+  const translate = computeMenuTranslation(switcher, optionsElement);
+
+  optionsElement.style.transform = `translate3d(${translate.x}px, ${translate.y}px, 0)`;
+}

assets/js/theme.js

@@ -1,51 +1,61 @@
 // Light / Dark theme toggle
 (function () {
   const defaultTheme = '{{ site.Params.theme.default | default `system`}}'
+  const themes = ["light", "dark"];
 
   const themeToggleButtons = document.querySelectorAll(".hextra-theme-toggle");
+  const themeToggleOptions = document.querySelectorAll(".hextra-theme-toggle-options p");
 
-  // Change the icons of the buttons based on previous settings or system theme
+  function applyTheme(theme) {
-  if (
+    theme = themes.includes(theme) ? theme : "system";
-    localStorage.getItem("color-theme") === "dark" ||
+
-    (!("color-theme" in localStorage) &&
+    themeToggleButtons.forEach((btn) => btn.parentElement.dataset.theme = theme );
-      ((window.matchMedia("(prefers-color-scheme: dark)").matches && defaultTheme === "system") || defaultTheme === "dark"))
+
-  ) {
+    localStorage.setItem("color-theme", theme);
-    themeToggleButtons.forEach((el) => el.dataset.theme = "dark");
-  } else {
-    themeToggleButtons.forEach((el) => el.dataset.theme = "light");
   }
 
+  function switchTheme(theme) {
+    setTheme(theme);
+    applyTheme(theme);
+  }
+
+  const colorTheme = "color-theme" in localStorage ? localStorage.getItem("color-theme") : defaultTheme;
+  switchTheme(colorTheme);
+
+  // Add click event handler to the menu items.
+  themeToggleOptions.forEach((option) => {
+    option.addEventListener("click", function (e) {
+      e.preventDefault();
+
+      switchTheme(option.dataset.item);
+    })
+  })
+
   // Add click event handler to the buttons
-  themeToggleButtons.forEach((el) => {
+  themeToggleButtons.forEach((toggler) => {
-    el.addEventListener("click", function () {
+    toggler.addEventListener("click", function (e) {
-      if (localStorage.getItem("color-theme")) {
+      e.preventDefault();
-        if (localStorage.getItem("color-theme") === "light") {
+
-          setDarkTheme();
+      toggleMenu(toggler);
-          localStorage.setItem("color-theme", "dark");
-        } else {
-          setLightTheme();
-          localStorage.setItem("color-theme", "light");
-        }
-      } else {
-        if (document.documentElement.classList.contains("dark")) {
-          setLightTheme();
-          localStorage.setItem("color-theme", "light");
-        } else {
-          setDarkTheme();
-          localStorage.setItem("color-theme", "dark");
-        }
-      }
-      el.dataset.theme = document.documentElement.classList.contains("dark") ? "dark" : "light";
     });
   });
 
+  window.addEventListener("resize", () => themeToggleButtons.forEach(resizeMenu))
+
+  // Dismiss the menu when clicking outside
+  document.addEventListener('click', (e) => {
+    if (e.target.closest('.hextra-theme-toggle') === null) {
+      themeToggleButtons.forEach((toggler) => {
+        toggler.dataset.state = 'closed';
+        toggler.nextElementSibling.classList.add('hx:hidden');
+      });
+    }
+  });
+
   // Listen for system theme changes
-  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", () => {
-    if (defaultTheme === "system" && !("color-theme" in localStorage)) {
+    if (localStorage.getItem("color-theme") === "system") {
-      e.matches ? setDarkTheme() : setLightTheme();
+      setTheme("system");
-      themeToggleButtons.forEach((el) =>
-        el.dataset.theme = document.documentElement.classList.contains("dark") ? "dark" : "light"
-      );
     }
   });
 })();

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
+  // Handle direct navigation to page with hash
-  setTimeout(() => {
+  function handleHashNavigation() {
-    if (!currentActiveLink && tocLinks.length > 0) {
+    const hash = window.location.hash; // already url encoded
-      tocLinks[0].classList.add("hextra-toc-active");
+    if (hash) {
-      currentActiveLink = tocLinks[0];
+      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"

data/icons.yaml

@@ -4,6 +4,11 @@
 #
 # {{ partial "utils/icon.html" (dict "name" "github" "attributes" "height=24") }}
 
+contrast: >
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"  fill="currentColor">
+    <path d="M 11.996094,2 C 6.4986225,2.0192368 2.03125,6.5024993 2.03125,12 c 0,5.497501 4.4673725,9.980763 9.964844,10 H 12 12.0039 c 5.497471,-0.01924 9.964844,-4.502499 9.964844,-10 0,-5.4975007 -4.467373,-9.9807632 -9.964844,-10 H 12 Z M 12,4 c 4.417218,0.017598 7.96875,3.5822356 7.96875,8 0,4.417764 -3.551532,7.982402 -7.96875,8 z" />
+  </svg>
+
 github: >
   <svg fill="currentColor" viewBox="3 3 18 18">
     <path d="M12 3C7.0275 3 3 7.12937 3 12.2276C3 16.3109 5.57625 19.7597 9.15374 20.9824C9.60374 21.0631 9.77249 20.7863 9.77249 20.5441C9.77249 20.3249 9.76125 19.5982 9.76125 18.8254C7.5 19.2522 6.915 18.2602 6.735 17.7412C6.63375 17.4759 6.19499 16.6569 5.8125 16.4378C5.4975 16.2647 5.0475 15.838 5.80124 15.8264C6.51 15.8149 7.01625 16.4954 7.18499 16.7723C7.99499 18.1679 9.28875 17.7758 9.80625 17.5335C9.885 16.9337 10.1212 16.53 10.38 16.2993C8.3775 16.0687 6.285 15.2728 6.285 11.7432C6.285 10.7397 6.63375 9.9092 7.20749 9.26326C7.1175 9.03257 6.8025 8.08674 7.2975 6.81794C7.2975 6.81794 8.05125 6.57571 9.77249 7.76377C10.4925 7.55615 11.2575 7.45234 12.0225 7.45234C12.7875 7.45234 13.5525 7.55615 14.2725 7.76377C15.9937 6.56418 16.7475 6.81794 16.7475 6.81794C17.2424 8.08674 16.9275 9.03257 16.8375 9.26326C17.4113 9.9092 17.76 10.7281 17.76 11.7432C17.76 15.2843 15.6563 16.0687 13.6537 16.2993C13.98 16.5877 14.2613 17.1414 14.2613 18.0065C14.2613 19.2407 14.25 20.2326 14.25 20.5441C14.25 20.7863 14.4188 21.0746 14.8688 20.9824C16.6554 20.364 18.2079 19.1866 19.3078 17.6162C20.4077 16.0457 20.9995 14.1611 21 12.2276C21 7.12937 16.9725 3 12 3Z"></path>
@@ -47,6 +52,15 @@ markdown: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill
 folder-tree: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path fill="currentColor" d="m 114.47781,81.538059 c 0,-13.785609 -11.07754,-24.923135 -24.78889,-24.923135 -13.711352,0 -24.788885,11.137526 -24.788885,24.923135 V 355.69254 c 0,27.49333 22.232532,49.84627 49.577775,49.84627 H 263.21112 V 355.69254 H 114.47781 V 181.2306 H 263.21112 V 131.38433 H 114.47781 Z M 288,206.15373 c 0,13.78561 11.07753,24.92314 24.78888,24.92314 h 173.5222 c 13.71135,0 24.78888,-11.13753 24.78888,-24.92314 v -99.69254 c 0,-13.785605 -11.07753,-24.923131 -24.78888,-24.923131 h -76.45822 c -6.58454,0 -12.85923,-2.648083 -17.50715,-7.321171 L 382.04283,63.936095 c -4.64791,-4.673088 -10.9226,-7.321171 -17.50715,-7.321171 h -51.7468 C 299.07753,56.614924 288,67.75245 288,81.538059 Z m 0,224.30821 c 0,13.78561 11.07753,24.92314 24.78888,24.92314 h 173.5222 c 13.71135,0 24.78888,-11.13753 24.78888,-24.92314 V 330.7694 c 0,-13.78561 -11.07753,-24.92313 -24.78888,-24.92313 h -76.45822 c -6.58454,0 -12.85923,-2.64808 -17.50715,-7.32117 l -10.30288,-10.35868 c -4.64791,-4.67309 -10.9226,-7.32117 -17.50715,-7.32117 h -51.7468 C 299.07753,280.84525 288,291.98278 288,305.76838 Z" style="stroke-width:0.776747" /></svg>
 card: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 15 15"><path fill="currentColor" fill-rule="evenodd" d="M14 11V4H1v7h13Zm1-7v7a1 1 0 0 1-1 1H1a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h13a1 1 0 0 1 1 1ZM2 5.25A.25.25 0 0 1 2.25 5h3.5a.25.25 0 0 1 .25.25v4.5a.25.25 0 0 1-.25.25h-3.5A.25.25 0 0 1 2 9.75v-4.5ZM7.5 7a.5.5 0 0 0 0 1h3a.5.5 0 0 0 0-1h-3ZM7 9.5a.5.5 0 0 1 .5-.5h5a.5.5 0 0 1 0 1h-5a.5.5 0 0 1-.5-.5ZM7.5 5a.5.5 0 0 0 0 1h4a.5.5 0 0 0 0-1h-4Z" clip-rule="evenodd"/></svg>
 
+arrow-up-right: >-
+  <svg fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+   <path d="m9.1716 7.7574h7.0711m0 0v7.0711m0-7.0711-8.4853 8.4853" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>
+arrow-up-left: >-
+  <svg fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <path d="m7.7574 14.828v-7.0711m0 0 7.0711 1e-7m-7.0711-1e-7 8.4853 8.4853" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>
+
 # Icons from heroicons v1 outlined https://github.com/tailwindlabs/heroicons/tree/v1
 academic-cap: <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true"><path d="M12 14l9-5-9-5-9 5 9 5z"/><path d="M12 14l6.16-3.422a12.083 12.083 0 01.665 6.479A11.952 11.952 0 0012 20.055a11.952 11.952 0 00-6.824-2.998 12.078 12.078 0 01.665-6.479L12 14z"/><path stroke-linecap="round" stroke-linejoin="round" d="M12 14l9-5-9-5-9 5 9 5zm0 0l6.16-3.422a12.083 12.083 0 01.665 6.479A11.952 11.952 0 0012 20.055a11.952 11.952 0 00-6.824-2.998 12.078 12.078 0 01.665-6.479L12 14zm-4 6v-7.5l4-2.222"/></svg>
 adjustments: <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M12 6V4m0 2a2 2 0 100 4m0-4a2 2 0 110 4m-6 8a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4m6 6v10m6-2a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4"/></svg>

exampleSite/content/blog/v0.11.fa.md

@@ -0,0 +1,128 @@
+---
+title: "Hextra v0.11"
+date: 2025-08-30
+authors:
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+tags:
+  - انتشار
+---
+
+Hextra v0.11.0 بر صیقل UX و مؤلفه‌های جدید کاربردی تمرکز دارد: بنر سراسری سایت، کال‌اوت‌ها و بج‌های بهبودیافته، کارت‌های غنی‌تر، یکپارچه‌سازی تحلیل‌گرها، و چند بهبود ناوبری. همچنین شامل رفع اشکالات پایداری و به‌روزرسانی‌های مستندات است.
+
+<!--more-->
+
+## راهنمای ارتقا
+
+برای بیشتر سایت‌ها تغییر شکست‌آمیزی وجود ندارد. با استفاده از [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) به‌روزرسانی کنید:
+
+```bash
+hugo mod get -u github.com/imfing/hextra
+```
+
+## نکات برجسته
+
+- مؤلفه بنر بالایی برای اعلان‌ها
+- بازطراحی کال‌اوت‌ها با سبک‌های شفاف‌تر
+- پشتیبانی از تحلیل‌گرهای Umami و Matomo
+- شورت‌کد Asciinema برای ضبط‌های ترمینال
+- گزینهٔ تزئین پیوندهای خارجی
+- مسیر راهنما برای صفحات تکی (غیرِ مستندات/غیرِ وبلاگ)
+- بهبودهای نوار ناوبری: مورد پیوند با آیکون و جای‌گذاری بهتر
+- سفارشی‌سازی بهتر بج‌ها و کارت‌ها
+- کلید تغییر تم از گزینه «System» پشتیبانی می‌کند
+
+## ویژگی‌های جدید
+
+### بنر بالایی
+
+یک بنر سراسری و قابلِ بستن برای اعلان‌ها، لانچ‌ها یا پیام‌های وضعیت اضافه کنید.
+
+```yaml {filename="hugo.yaml"}
+params:
+  banner:
+    key: "announcement"
+    message: Welcome!
+```
+
+![بنر بالایی](https://github.com/user-attachments/assets/33a08c9b-db84-4200-b37c-1a53c1bef08d)
+
+### بازطراحی Callout
+
+[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) برای خوانایی بهتر و تأکید مناسب در تمام تم‌ها بازطراحی شده است.
+
+![بازطراحی Callout](https://github.com/user-attachments/assets/b3154dbb-e582-4c84-a8b8-1ecb02c3464d)
+
+### تحلیل‌گرها: Umami و Matomo
+
+پیکربندی داخلی برای فراهم‌کنندگان تحلیل‌گر:
+- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
+- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
+
+### شورت‌کد Asciinema
+
+با استفاده از [Asciinema](https://www.asciinema.org/) و [شورت‌کد Asciinema]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) ضبط‌های ترمینال را درون‌گذاری کنید.
+
+```md
+{{</* asciinema id="123456" autoplay=true loop=true */>}}
+```
+
+![Asciinema](https://github.com/user-attachments/assets/3c33a8ef-3c01-4e30-9832-3ccb784ec538)
+
+### بهبودهای نوار ناوبری
+
+- پشتیبانی از آیکون برای موارد پیوند در نوار ناوبری
+- بهبود موقعیت منو برای هماهنگی با سوییچر زبان و سایر موارد
+
+![نوار ناوبری با مورد آیکون](https://github.com/user-attachments/assets/6c035eee-cd7d-44d8-bcf7-9cbd7f92ab42)
+
+قابل ذکر است، نسخه [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) امکان افزودن سوییچر زبان و کلید تغییر تم به نوار ناوبری را فراهم می‌کند.
+
+### تزئین پیوند خارجی
+
+به‌صورت اختیاری یک تزئین ظریفِ «پیوند خارجی» به پیوندهای خروجی اضافه کنید.
+
+```yaml {filename="hugo.yaml"}
+params:
+  externalLinkDecoration: true
+```
+
+### فعال‌سازی مسیر راهنما
+
+با قرار دادن `breadcrumbs: true` در فرانت‌متر، مسیر راهنما را روی صفحات تکی (غیرِ مستندات/وبلاگ) فعال کنید.
+
+```yaml {filename="content/about.md"}
+---
+title: About
+breadcrumbs: true
+---
+```
+
+### بهبود کارت‌ها و بج‌ها
+
+- [کارت‌ها]({{% relref "docs/guide/shortcodes/cards.md" %}}): گزینه‌های جدید `tagIcon` و `tagBorder`.
+- [بج‌ها]({{% relref "docs/guide/shortcodes/others.md" %}}): رنگ‌ها و سبک‌های حاشیهٔ جدید.
+
+## بهبودهای کیفیت زندگی
+
+- تغییر تم: افزودن گزینه «System»
+  ![کلید تغییر تم](https://github.com/user-attachments/assets/54a1d315-9243-4814-9154-6e63af9ea2e8)
+- تایپوگرافی: سبک‌های بهتر فهرست کار با چک‌باکس
+  ![فهرست کار](https://github.com/user-attachments/assets/53722651-63b6-4469-95e7-326849a30306)
+- سوییچر زبان: ترتیب‌دهی بهبود یافته همراه با موارد منوییِ آیکون‌دار
+
+## رفع اشکالات
+
+- Giscus: همگام‌سازی صحیح تم و زبان
+- کارت‌ها: رفع رندر بج در حالت RTL
+- نوار ناوبری: بهبود موقعیت و تعاملات منو
+
+## مستندات و بومی‌سازی
+
+- مستندات: صفحهٔ جدیدی دربارهٔ شورت‌کدهای Hextra
+- i18n: افزودن ترجمه‌های `copyCode` و `system` به `zh-cn`
+
+---
+
+**تغییرات کامل**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

exampleSite/content/blog/v0.11.ja.md

@@ -0,0 +1,128 @@
+---
+title: "Hextra v0.11"
+date: 2025-08-30
+authors:
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+tags:
+  - Release
+---
+
+Hextra v0.11.0 は、UX の磨き込みと便利な新コンポーネントに注力したリリースです。サイト全体バナー、改良されたコールアウトとバッジ、よりリッチなカード、アナリティクス連携、そしていくつかのナビゲーション改善を含みます。安定性の修正とドキュメント更新も同梱しています。
+
+<!--more-->
+
+## アップグレードガイド
+
+ほとんどのサイトで破壊的変更はありません。[Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) を使って更新してください:
+
+```bash
+hugo mod get -u github.com/imfing/hextra
+```
+
+## ハイライト
+
+- お知らせ用のトップバナーコンポーネント
+- より見やすくなったコールアウトの刷新
+- Umami と Matomo のアナリティクス対応
+- 端末録画のための Asciinema ショートコード
+- 外部リンク装飾オプション
+- 単一ページ（ドキュメント・ブログ以外）向けのパンくずリスト
+- ナビバー改善: アイコン付きリンク項目と配置の改善
+- バッジとカードのカスタマイズ性向上
+- テーマ切り替えに「System」オプションを追加
+
+## 新機能
+
+### トップバナー
+
+告知やリリース、ステータスメッセージ向けに、サイト全体で表示できる閉じられるバナーを追加します。
+
+```yaml {filename="hugo.yaml"}
+params:
+  banner:
+    key: "announcement"
+    message: Welcome!
+```
+
+![トップバナー](https://github.com/user-attachments/assets/33a08c9b-db84-4200-b37c-1a53c1bef08d)
+
+### コールアウト刷新
+
+[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) のデザインを刷新し、テーマを問わず可読性と強調表現を向上しました。
+
+![コールアウト刷新](https://github.com/user-attachments/assets/b3154dbb-e582-4c84-a8b8-1ecb02c3464d)
+
+### アナリティクス: Umami と Matomo
+
+以下のアナリティクスプロバイダに組み込み設定で対応:
+- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
+- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
+
+### Asciinema ショートコード
+
+[Asciinema](https://www.asciinema.org/) の端末録画を、新しい [Asciinema ショートコード]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) で埋め込みできます。
+
+```md
+{{</* asciinema id="123456" autoplay=true loop=true */>}}
+```
+
+![Asciinema](https://github.com/user-attachments/assets/3c33a8ef-3c01-4e30-9832-3ccb784ec538)
+
+### ナビバーの改善
+
+- ナビバーのリンク項目でアイコンをサポート
+- 言語スイッチャー等との兼ね合いを考慮してメニュー配置を最適化
+
+![アイコン付き項目のナビバー](https://github.com/user-attachments/assets/6c035eee-cd7d-44d8-bcf7-9cbd7f92ab42)
+
+特に、[0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) ではナビバーに言語スイッチャーとテーマトグルを追加可能になりました。
+
+### 外部リンク装飾
+
+外部リンクに控えめな装飾をオプションで付与できます。
+
+```yaml {filename="hugo.yaml"}
+params:
+  externalLinkDecoration: true
+```
+
+### パンくずリストの有効化
+
+フロントマターで `breadcrumbs: true` を設定すると、単一ページ（ドキュメント・ブログ以外）でパンくずリストを有効化できます。
+
+```yaml {filename="content/about.md"}
+---
+title: About
+breadcrumbs: true
+---
+```
+
+### カードとバッジの改善
+
+- [カード]({{% relref "docs/guide/shortcodes/cards.md" %}}): 新オプション `tagIcon` と `tagBorder`
+- [バッジ]({{% relref "docs/guide/shortcodes/others.md" %}}): 新しい色とボーダースタイル
+
+## 利便性の向上
+
+- テーマ切り替え: 「System」オプションを追加
+  ![テーマ切り替え](https://github.com/user-attachments/assets/54a1d315-9243-4814-9154-6e63af9ea2e8)
+- タイポグラフィ: チェックボックス付きタスクリストのスタイル改善
+  ![タスクリスト](https://github.com/user-attachments/assets/53722651-63b6-4469-95e7-326849a30306)
+- 言語スイッチャー: アイコンメニュー項目との並び順を改善
+
+## 修正
+
+- Giscus: テーマと言語の同期を適切に実施
+- カード: RTL でのバッジ描画を修正
+- ナビバー: メニュー配置とインタラクションを調整
+
+## ドキュメントと i18n
+
+- Docs: Hextra のショートコードをまとめた新ページ
+- i18n: `zh-cn` に `copyCode` と `system` の翻訳を追加
+
+---
+
+**完全な変更履歴**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

exampleSite/content/blog/v0.11.md

@@ -0,0 +1,128 @@
+---
+title: "Hextra v0.11"
+date: 2025-08-30
+authors:
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+tags:
+  - Release
+---
+
+Hextra v0.11.0 focuses on UX polish and useful new components: site-wide banner, improved callouts and badges, richer cards, analytics integrations, and several navigation refinements. It also ships stability fixes and documentation updates.
+
+<!--more-->
+
+## Upgrade Guide
+
+No breaking changes are expected for most sites. Update using [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/):
+
+```bash
+hugo mod get -u github.com/imfing/hextra
+```
+
+## Highlights
+
+- Top banner component for announcements
+- Revamped callouts with clearer styles
+- Umami and Matomo analytics support
+- Asciinema shortcode for terminal recordings
+- External link decoration option
+- Breadcrumbs for single pages (non-docs, non-blogs)
+- Navbar enhancements: icon link item and improved positions
+- Improved badges and cards customization
+- Theme toggle supports "System"
+
+## New Features
+
+### Top Banner
+
+Add a site-wide, dismissible banner for announcements, launches, or status messages.
+
+```yaml {filename="hugo.yaml"}
+params:
+  banner:
+    key: "announcement"
+    message: Welcome!
+```
+
+![Top Banner](https://github.com/user-attachments/assets/33a08c9b-db84-4200-b37c-1a53c1bef08d)
+
+### Callout Revamp
+
+[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) receive a design refresh for better readability and emphasis across themes.
+
+![Callout refresh](https://github.com/user-attachments/assets/b3154dbb-e582-4c84-a8b8-1ecb02c3464d)
+
+### Analytics: Umami and Matomo
+
+Built-in configuration for analytics providers:
+- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
+- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
+
+### Asciinema Shortcode
+
+Embed terminal recordings from [Asciinema](https://www.asciinema.org/) using the new [Asciinema shortcode]({{% relref "docs/guide/shortcodes/asciinema.md" %}}).
+
+```md
+{{</* asciinema id="123456" autoplay=true loop=true */>}}
+```
+
+![Asciinema](https://github.com/user-attachments/assets/3c33a8ef-3c01-4e30-9832-3ccb784ec538)
+
+### Navbar Enhancements
+
+- Support icons for link items in the navbar
+- Refine menu positions to play nicely with the language switcher and other items
+
+![Navbar with icon item](https://github.com/user-attachments/assets/6c035eee-cd7d-44d8-bcf7-9cbd7f92ab42)
+
+Notably, version [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) enables the addition of language switchers and theme toggles to the navbar.
+
+### External Link Decoration
+
+Optionally add a subtle external-link decoration to outbound links.
+
+```yaml {filename="hugo.yaml"}
+params:
+  externalLinkDecoration: true
+```
+
+### Breadcrumbs Enablement
+
+Enable breadcrumbs on single pages (non-docs, non-blogs) by setting `breadcrumbs: true` in front matter.
+
+```yaml {filename="content/about.md"}
+---
+title: About
+breadcrumbs: true
+---
+```
+
+### Cards and Badges Improvements
+
+- [Cards]({{% relref "docs/guide/shortcodes/cards.md" %}}): new `tagIcon` and `tagBorder` options.
+- [Badges]({{% relref "docs/guide/shortcodes/others.md" %}}): new colors and border styles.
+
+## Quality of Life
+
+- Theme toggle: add "System" option
+  ![Theme toggle](https://github.com/user-attachments/assets/54a1d315-9243-4814-9154-6e63af9ea2e8)
+- Typography: better task list styles with checkboxes
+  ![Task list](https://github.com/user-attachments/assets/53722651-63b6-4469-95e7-326849a30306)
+- Language switcher: improved ordering with icon menu items
+
+## Fixes
+
+- Giscus: sync theme and language properly
+- Cards: fix badge rendering with RTL
+- Navbar: refine menu positions and interactions
+
+## Documentation & i18n
+
+- Docs: new page covering Hextra shortcodes
+- i18n: add `copyCode` and `system` translations to `zh-cn`
+
+---
+
+**Full Changelog**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0

exampleSite/content/blog/v0.11.zh-cn.md

@@ -0,0 +1,129 @@
+---
+title: "Hextra v0.11"
+date: 2025-08-30
+authors:
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+tags:
+  - Release
+---
+
+Hextra v0.11.0 专注于打磨使用体验并带来数个实用新组件：站点级顶部横幅、改进的提示框与徽章、更丰富的卡片、分析工具集成，以及多项导航优化。同时包含稳定性修复和文档更新。
+
+<!--more-->
+
+## 升级指南
+
+对大多数站点而言没有破坏性变更。使用 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/) 更新：
+
+```bash
+hugo mod get -u github.com/imfing/hextra
+```
+
+## 亮点
+
+- 用于公告的顶栏横幅组件
+- 重新设计的提示框，样式更清晰
+- 支持 Umami 与 Matomo 分析
+- Asciinema 短代码用于终端录屏
+- 外链装饰选项
+- 单页（非文档、非博客）支持面包屑
+- 导航栏增强：图标链接项与更优布局
+- 徽章与卡片的自定义能力提升
+- 主题切换增加「System」选项
+
+## 新功能
+
+### 顶部横幅
+
+为公告、发布或状态消息添加一个站点级、可关闭的横幅。
+
+```yaml {filename="hugo.yaml"}
+params:
+  banner:
+    key: "announcement"
+    message: Welcome!
+```
+
+![顶部横幅](https://github.com/user-attachments/assets/33a08c9b-db84-4200-b37c-1a53c1bef08d)
+
+### 提示框重设计
+
+[Callout]({{% relref "docs/guide/shortcodes/callout" %}}) 获得样式刷新，在各主题下具备更好的可读性与强调效果。
+
+![提示框刷新](https://github.com/user-attachments/assets/b3154dbb-e582-4c84-a8b8-1ecb02c3464d)
+
+### 分析：Umami 与 Matomo
+
+内置以下分析平台的配置支持：
+- [Umami]({{% relref "docs/guide/configuration.md#umami-analytics" %}})
+- [Matomo]({{% relref "docs/guide/configuration.md#matomo-analytics" %}})
+
+### Asciinema 短代码
+
+使用全新的 [Asciinema 短代码]({{% relref "docs/guide/shortcodes/asciinema.md" %}}) 嵌入 [Asciinema](https://www.asciinema.org/) 终端录屏。
+
+```md
+{{</* asciinema id="123456" autoplay=true loop=true */>}}
+```
+
+![Asciinema](https://github.com/user-attachments/assets/3c33a8ef-3c01-4e30-9832-3ccb784ec538)
+
+### 导航栏增强
+
+- 支持在导航栏链接项中使用图标
+- 优化菜单的相对位置，使其与语言切换器等项协同更佳
+
+![带图标项的导航栏](https://github.com/user-attachments/assets/6c035eee-cd7d-44d8-bcf7-9cbd7f92ab42)
+
+值得一提的是，版本 [0.10.2](https://github.com/imfing/hextra/releases/tag/v0.10.2) 已支持在导航栏添加语言切换器与主题切换。
+
+### 外链装饰
+
+可选地为外部链接添加轻量的外链标识装饰。
+
+```yaml {filename="hugo.yaml"}
+params:
+  externalLinkDecoration: true
+```
+
+### 启用面包屑
+
+在单页（非文档、非博客）上，通过在 Front Matter 中设置 `breadcrumbs: true` 启用面包屑。
+
+```yaml {filename="content/about.md"}
+---
+title: About
+breadcrumbs: true
+---
+```
+
+### 卡片与徽章的改进
+
+- [卡片]({{% relref "docs/guide/shortcodes/cards.md" %}})：新增 `tagIcon` 与 `tagBorder` 选项。
+- [徽章]({{% relref "docs/guide/shortcodes/others.md" %}})：新增颜色与边框样式。
+
+## 使用体验优化
+
+- 主题切换：增加「System」选项
+  ![主题切换](https://github.com/user-attachments/assets/54a1d315-9243-4814-9154-6e63af9ea2e8)
+- 字体排版：改进带复选框的任务列表样式
+  ![任务列表](https://github.com/user-attachments/assets/53722651-63b6-4469-95e7-326849a30306)
+- 语言切换器：与图标菜单项的排序更合理
+
+## 修复
+
+- Giscus：正确同步主题与语言
+- 卡片：修复 RTL 场景下的徽章渲染
+- 导航栏：优化菜单位置与交互
+
+## 文档与 i18n
+
+- 文档：新增页面介绍 Hextra 的短代码
+- i18n：为 `zh-cn` 增加 `copyCode` 与 `system` 翻译
+
+---
+
+**完整变更日志**: https://github.com/imfing/hextra/compare/v0.10.2...v0.11.0
+

exampleSite/content/docs/getting-started.md

@@ -102,10 +102,17 @@ To update Hextra to the [latest released version](https://github.com/imfing/hext
 hugo mod get -u github.com/imfing/hextra
 ```
 
+If you want to try the most recent changes before the next release, update the module to the development branch directly (⚠️ may contain unstable/breaking changes):
+
+```shell
+hugo mod get -u github.com/imfing/hextra@main
+```
+
 See [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) for more details.
 
 {{% /details %}}
 
+
 ### Setup Hextra as Git submodule
 
 #### Prerequisites

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

@@ -58,12 +58,34 @@ There are different types of menu items:
      params:
        type: search
    ```
-4. Icon
+4. Icon Only
    ```yaml
    - name: GitHub
      params:
        icon: github
    ```
+5. Link with Icon
+   ```yaml
+   - name: Blog
+     params:
+       type: link
+       icon: rss
+   ```
+6. Theme Toggle
+   ```yaml
+    - name: Theme Toggle
+      params:
+        type: theme-toggle
+        label: true # optional, default is false
+   ```
+7. 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.
 
@@ -372,6 +394,45 @@ To exclude an entire directory, use the [`cascade`](https://gohugo.io/configurat
 > To block search crawlers, you can make a [`robots.txt` template](https://gohugo.io/templates/robots/).
 > However, `robots.txt` instructions do not necessarily keep a page out of Google search results.
 
+### Umami Analytics
+
+To enable [Umami](https://umami.is/docs/), set `params.analytics.umami.serverURL` and `params.analytics.umami.websiteID` flag in `hugo.yaml`:
+
+```yaml {filename="hugo.yaml"}
+params:
+  analytics:
+    umami:
+      serverURL: "https://example.com"
+      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
+      # scriptName: "umami.js" # optional (default: umami.js)
+      # https://umami.is/docs/tracker-configuration#data-host-url
+      # hostURL: "http://stats.example.org" # optional
+      # https://umami.is/docs/tracker-configuration#data-auto-track
+      # autoTrack: "false" # optional
+      # https://umami.is/docs/tracker-configuration#data-tag
+      # domains: "example.net,example.org" # optional
+      # https://umami.is/docs/tracker-configuration#data-exclude-search
+      # tag: "umami-eu" # optional
+      # https://umami.is/docs/tracker-configuration#data-exclude-hash
+      # excludeSearch: "true" # optional
+      # https://umami.is/docs/tracker-configuration#data-do-not-track
+      # excludeHash: "true" # optional
+      # https://umami.is/docs/tracker-configuration#data-domains
+      # doNotTrack: "true" # optional
+```
+
+### Matomo Analytics
+
+To enable [Matomo](https://matomo.org/), set `params.analytics.matomo.URL` and `params.analytics.matomo.ID` flag in `hugo.yaml`:
+
+```yaml {filename="hugo.yaml"}
+params:
+  analytics:
+    matomo:
+      serverURL: "https://example.com"
+      websiteID: "94db1cb1-74f4-4a40-ad6c-962362670409"
+```
+
 ### LLMS.txt Support
 
 To enable [llms.txt](https://llmstxt.org/) output format for your site, which provides a structured text outline for [large language models](https://en.wikipedia.org/wiki/Large_language_model) and AI agents, add the `llms` output format to your site's `hugo.yaml`:
@@ -408,3 +469,31 @@ params:
     - "/img/config-image.jpg"
   audio: "config-talk.mp3"
 ```
+
+### Banner
+
+To add a banner to your site, add the following to your `hugo.yaml`:
+
+```yaml
+params:
+  banner:
+    key: 'announcement-xxx'
+    message: |
+      🎉 Welcome! [Hextra](https://github.com/hextra/hextra) is a static site generator that helps you build modern websites.
+```
+
+The banner will be displayed on all pages.
+
+The field `message` supports Markdown syntax.
+
+If you want to use template syntax, you can define the partial in `layouts/_partials/custom/banner.html`.
+In this case, the field `message` will be ignored.
+
+### External Link Decoration
+
+Adds an arrow icon to external links (default: false) when rendering links from Markdown.
+
+```yaml
+params:
+  externalLinkDecoration: true
+```

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/deploy-site.ja.md

@@ -101,7 +101,7 @@ jobs:
 {{% /details %}}
 
 
-{{< callout >}}
+{{< callout type="warning" >}}
   リポジトリ設定で、**Pages** > **Build and deployment** > **Source** を **GitHub Actions** に設定してください:
   ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png)
 {{< /callout >}}

exampleSite/content/docs/guide/deploy-site.md

@@ -102,7 +102,7 @@ jobs:
 {{% /details %}}
 
 
-{{< callout >}}
+{{< callout type="warning" >}}
   In your repository settings, set the **Pages** > **Build and deployment** > **Source** to **GitHub Actions**:
   ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png)
 {{< /callout >}}

exampleSite/content/docs/guide/deploy-site.zh-cn.md

@@ -102,7 +102,7 @@ jobs:
 {{% /details %}}
 
 
-{{< callout >}}
+{{< callout type="warning" >}}
   在仓库设置中，将 **Pages** > **构建与部署** > **源** 设为 **GitHub Actions**：
   ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png)
 {{< /callout >}}

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

@@ -155,6 +155,18 @@ Hugo از [Markdown](https://en.wikipedia.org/wiki/Markdown) برای قالب
   - پنیر
 ```
 
+#### لیست وظایف
+
+- [x] نوشتن مستندات
+- [ ] بازبینی کد
+- [ ] استقرار تغییرات
+
+```markdown {filename=Markdown}
+- [x] نوشتن مستندات
+- [ ] بازبینی کد
+- [ ] استقرار تغییرات
+```
+
 ### تصاویر
 
 ![منظره](https://picsum.photos/800/600)

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

@@ -155,6 +155,18 @@ Hugo はテキストの書式設定やリスト作成などに [Markdown](https:
   - チーズ
 ```
 
+#### タスクリスト
+
+- [x] ドキュメント作成
+- [ ] コードレビュー
+- [ ] 変更のデプロイ
+
+```markdown {filename=Markdown}
+- [x] ドキュメント作成
+- [ ] コードレビュー
+- [ ] 変更のデプロイ
+```
+
 ### 画像
 
 ![風景](https://picsum.photos/800/600)

exampleSite/content/docs/guide/markdown.md

@@ -155,6 +155,18 @@ Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-
   - Cheese
 ```
 
+#### Task list
+
+- [x] Write documentation
+- [ ] Review code
+- [ ] Deploy changes
+
+```markdown {filename=Markdown}
+- [x] Write documentation
+- [ ] Review code
+- [ ] Deploy changes
+```
+
 ### Images
 
 ![landscape](https://picsum.photos/800/600)

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

@@ -155,6 +155,18 @@ Hugo 支持使用 [Markdown](https://en.wikipedia.org/wiki/Markdown) 语法来
   - 奶酪
 ```
 
+#### 任务列表
+
+- [x] 编写文档
+- [ ] 代码审查
+- [ ] 部署更改
+
+```markdown {filename=Markdown}
+- [x] 编写文档
+- [ ] 代码审查
+- [ ] 部署更改
+```
+
 ### 图片
 
 ![风景](https://picsum.photos/800/600)

exampleSite/content/docs/guide/organize-files.fa.md

@@ -78,7 +78,7 @@ weight: 2
 ---
 ```
 
-{{< callout emoji="ℹ️">}}
+{{< callout type="info" >}}
   توصیه می‌شود نوار کناری را خیلی عمیق نگه ندارید. اگر محتوای زیادی دارید، **آن‌ها را به چند بخش تقسیم کنید**.
 {{< /callout >}}
 

exampleSite/content/docs/guide/organize-files.ja.md

@@ -78,7 +78,7 @@ weight: 2
 ---
 ```
 
-{{< callout emoji="ℹ️">}}
+{{< callout type="info" >}}
   サイドバーを深くしすぎないことをお勧めします。多くのコンテンツがある場合は、**複数のセクションに分割する**ことを検討してください。
 {{< /callout >}}
 

exampleSite/content/docs/guide/organize-files.md

@@ -78,7 +78,7 @@ weight: 2
 ---
 ```
 
-{{< callout emoji="ℹ️">}}
+{{< callout type="info" >}}
   It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**.
 {{< /callout >}}
 
@@ -180,9 +180,17 @@ This would now generate the following breadcrumbs:
 Documentation > Guide > Foo Bar
 ```
 
-### Hiding Breadcrumbs
+### Enabling and Disabling Breadcrumbs
 
-You can hide breadcrumbs completely from a page by specifying `breadcrumbs: false` in its front matter:
+Whether breadcrumbs are enabled, or disabled, by default for a page, is determined by its [content type](https://gohugo.io/quick-reference/glossary/#content-type) and [page kind](https://gohugo.io/quick-reference/glossary/#page-kind):
+
+|  Content Type   | Section  | Page      |
+|:----------------|:--------:|:----------|
+| `docs`          | Enabled  | Enabled   |
+| `blog`          | Disabled | Enabled   |
+| Any other type  | Disabled | Disabled  |
+
+You can override these defaults on a page by setting `breadcrumbs` in its front matter:
 
 ```yaml {filename="content/docs/guide/organize-files.md"}
 ---
@@ -191,6 +199,18 @@ title: Organize Files
 ---
 ```
 
+Similarly you can use [cascade](https://gohugo.io/content-management/front-matter/#cascade-1) to override the defaults on a page and its decendents:
+
+```yaml {filename="content/portfolio/_index.md"}
+---
+title: "Portfolio"
+
+cascade:
+  params:
+    breadcrumbs: true
+---
+```
+
 ## Configure Content Directory
 
 By default, the root `content/` directory is used by Hugo to build the site.

exampleSite/content/docs/guide/organize-files.zh-cn.md

@@ -78,7 +78,7 @@ weight: 2
 ---
 ```
 
-{{< callout emoji="ℹ️">}}
+{{< callout type="info" >}}
   建议不要让侧边栏过深。如果有大量内容，可以考虑**将其拆分为多个部分**。
 {{< /callout >}}
 

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

@@ -26,4 +26,5 @@ Hextra مجموعه‌ای از شورت‌کدهای زیبا را برای ب
 {{< cards >}}
   {{< card link="jupyter" title="نوت‌بوک Jupyter" icon="jupyter" tag="alpha" >}}
   {{< card link="others" title="سایر" icon="view-grid" >}}
+  {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
 {{< /cards >}}

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

@@ -26,4 +26,5 @@ Hugo と Hextra が提供する追加のショートコード:
 {{< cards >}}
   {{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
   {{< card link="others" title="Others" icon="view-grid" >}}
+  {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
 {{< /cards >}}

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

@@ -26,4 +26,6 @@ Additional shortcodes provided by Hugo and Hextra:
 {{< cards >}}
   {{< card link="jupyter" title="Jupyter Notebook" icon="jupyter" tag="alpha" >}}
   {{< card link="others" title="Others" icon="view-grid" >}}
+  {{< card link="hextra" title="Hextra" icon="view-grid" >}}
+  {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
 {{< /cards >}}

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

@@ -26,4 +26,5 @@ Hugo 和 Hextra 提供的其他短代码：
 {{< cards >}}
   {{< card link="jupyter" title="Jupyter 笔记本" icon="jupyter" tag="alpha" >}}
   {{< card link="others" title="其他" icon="view-grid" >}}
+  {{< card link="asciinema" title="Asciinema Player" icon="terminal" >}}
 {{< /cards >}}

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

@@ -0,0 +1,121 @@
+---
+title: "Asciinema Player کامپوننت"
+linktitle: "Asciinema Player"
+sidebar:
+  exclude: true
+---
+
+shortcode asciinema به شما امکان می‌دهد تا ضبط‌های ترمینال ایجاد شده با [asciinema](https://asciinema.org/) را در سایت Hugo خود جاسازی کنید. این یک پخش‌کننده ترمینال غنی با ویژگی‌هایی مانند کنترل پخش، تنظیم سرعت و سفارشی‌سازی تم ارائه می‌دهد.
+
+## استفاده پایه
+
+shortcode asciinema از فایل‌های `.cast` محلی و URL های راه دور پشتیبانی می‌کند. روش‌های مختلف استفاده از فایل‌های محلی به شرح زیر است:
+
+### فایل‌های محلی
+
+**روش 1: دایرکتوری Assets (توصیه شده)**
+فایل‌های cast را در دایرکتوری `assets/` سایت Hugo خود قرار دهید:
+
+```
+your-site/
+├── assets/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+در فایل markdown خود:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**روش 2: دایرکتوری Static**
+فایل‌های cast را در دایرکتوری `static/` قرار دهید:
+
+```
+your-site/
+├── static/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+در فایل markdown خود:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**روش 3: بسته صفحه**
+برای بسته‌های صفحه، فایل‌های cast را همراه با فایل markdown قرار دهید:
+
+```
+your-site/
+└── content/
+    └── my-page/
+        ├── index.md
+        └── demo.cast
+```
+
+در فایل markdown خود:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+{{< asciinema file="casts/demo.cast" >}}
+
+### فایل‌های راه دور
+
+همچنین می‌توانید از فایل‌های cast از هر URL راه دور استفاده کنید:
+
+```markdown
+{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
+{{</* asciinema file="https://example.com/demo.cast" */>}}
+```
+
+{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
+
+### نحوه کارکرد جستجوی فایل
+
+shortcode به ترتیب زیر فایل‌های cast شما را به طور خودکار پیدا می‌کند:
+1. **منابع بسته صفحه** (اگر از بسته صفحه استفاده می‌کنید)
+2. **دایرکتوری assets جهانی** (`assets/`)
+3. **دایرکتوری Static** (`static/`)
+4. **URL های راه دور** (اگر مسیر با `http://` یا `https://` شروع شود)
+
+اگر فایل پیدا نشود، Hugo پیام خطای مفیدی نمایش می‌دهد که به شما می‌گوید فایل را کجا قرار دهید.
+
+## نمایش پیشرفته
+
+این یک مثال پیشرفته است که تمام پارامترهای موجود را نشان می‌دهد:
+
+```markdown
+{{</* asciinema 
+  file="demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+*/>}}
+```
+
+{{< asciinema 
+  file="casts/demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+>}}
+
+## پارامترها
+
+| پارامتر | نوع | پیش‌فرض | توضیحات |
+|---------|-----|---------|---------|
+| `file` | string | - | مسیر فایل .cast (ضروری). از فایل‌های محلی، مسیرهای مطلق و URL های راه دور پشتیبانی می‌کند |
+| `theme` | string | `"asciinema"` | تم پخش‌کننده |
+| `speed` | number | `1` | ضریب سرعت پخش |
+| `autoplay` | boolean | `false` | شروع خودکار پخش |
+| `loop` | boolean | `false` | پخش حلقه‌ای |
+| `poster` | string | `""` | پوستر (فریم پیش‌نمایش) برای نمایش تا زمان شروع پخش. از نمادگذاری NPT پشتیبانی می‌کند (مثل "npt:1:23") |
+| `markers` | string | `""` | نشانگرهای زمانی جدا شده با کاما. فرمت: "زمان:برچسب" یا فقط "زمان" (مثل "1.5:Installation,3.2:Configuration,5.8") |

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

@@ -0,0 +1,121 @@
+---
+title: "Asciinema Player コンポーネント"
+linktitle: "Asciinema Player"
+sidebar:
+  exclude: true
+---
+
+asciinema shortcode を使用すると、[asciinema](https://asciinema.org/) で作成されたターミナル録画を Hugo サイトに埋め込むことができます。再生制御、速度調整、テーマカスタマイズなどの機能を備えたリッチなターミナルプレイヤーを提供します。
+
+## 基本的な使用方法
+
+asciinema shortcode はローカルの `.cast` ファイルとリモート URL の両方をサポートしています。ローカルファイルを使用する方法は以下の通りです：
+
+### ローカルファイル
+
+**方法 1：Assets ディレクトリ（推奨）**
+cast ファイルを Hugo サイトの `assets/` ディレクトリに配置：
+
+```
+your-site/
+├── assets/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+markdown ファイル内：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 2：Static ディレクトリ**
+cast ファイルを `static/` ディレクトリに配置：
+
+```
+your-site/
+├── static/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+markdown ファイル内：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 3：ページバンドル**
+ページバンドルの場合、cast ファイルを markdown ファイルと一緒に配置：
+
+```
+your-site/
+└── content/
+    └── my-page/
+        ├── index.md
+        └── demo.cast
+```
+
+markdown ファイル内：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+{{< asciinema file="casts/demo.cast" >}}
+
+### リモートファイル
+
+任意のリモート URL からの cast ファイルも使用できます：
+
+```markdown
+{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
+{{</* asciinema file="https://example.com/demo.cast" */>}}
+```
+
+{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
+
+### ファイル検索の仕組み
+
+shortcode は以下の順序で cast ファイルを自動的に検索します：
+1. **ページバンドルリソース**（ページバンドルを使用している場合）
+2. **グローバル assets ディレクトリ**（`assets/`）
+3. **Static ディレクトリ**（`static/`）
+4. **リモート URL**（パスが `http://` または `https://` で始まる場合）
+
+ファイルが見つからない場合、Hugo はファイルをどこに配置すべきかを示す有用なエラーメッセージを表示します。
+
+## 高度なデモ
+
+利用可能なすべてのパラメータを紹介する高度な例：
+
+```markdown
+{{</* asciinema 
+  file="demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+*/>}}
+```
+
+{{< asciinema 
+  file="casts/demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+>}}
+
+## パラメータ
+
+| パラメータ | 型 | デフォルト | 説明 |
+|-----------|----|-----------|------|
+| `file` | string | - | .cast ファイルパス（必須）。ローカルファイル、絶対パス、リモート URL をサポート |
+| `theme` | string | `"asciinema"` | プレイヤーテーマ |
+| `speed` | number | `1` | 再生速度倍率 |
+| `autoplay` | boolean | `false` | 自動再生 |
+| `loop` | boolean | `false` | ループ再生 |
+| `poster` | string | `""` | 再生開始前に表示されるポスター（プレビューフレーム）。NPT表記法をサポート（例："npt:1:23"） |
+| `markers` | string | `""` | カンマ区切りの時間マーカー。形式："時間:ラベル" または "時間"のみ（例："1.5:Installation,3.2:Configuration,5.8"） |

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

@@ -0,0 +1,124 @@
+---
+title: "Asciinema Player Component"
+linktitle: "Asciinema Player"
+sidebar:
+  exclude: true
+---
+
+## Overview
+
+The asciinema shortcode allows you to embed terminal recordings created with [asciinema](https://asciinema.org/) in your Hugo site. It provides a rich terminal player with features like playback controls, speed adjustment, and theme customization.
+
+## Basic Usage
+
+The asciinema shortcode supports both local `.cast` files and remote URLs. Here are the different ways to use local files:
+
+### Local Files
+
+**Method 1: Assets directory (recommended)**
+Place your cast files in the `assets/` directory of your Hugo site:
+
+```
+your-site/
+├── assets/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+In your markdown file:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**Method 2: Static directory**
+Place your cast files in the `static/` directory:
+
+```
+your-site/
+├── static/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+In your markdown file:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**Method 3: Page bundle**
+For page bundles, place cast files alongside your markdown file:
+
+```
+your-site/
+└── content/
+    └── my-page/
+        ├── index.md
+        └── demo.cast
+```
+
+In your markdown file:
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+{{< asciinema file="casts/demo.cast" >}}
+
+### Remote Files
+
+You can also use cast files from any remote URL:
+
+```markdown
+{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
+{{</* asciinema file="https://example.com/demo.cast" */>}}
+```
+
+{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
+
+### How File Lookup Works
+
+The shortcode automatically finds your cast files by looking in this order:
+1. **Page bundle resources** (if using page bundles)
+2. **Global assets directory** (`assets/`)
+3. **Static directory** (`static/`)
+4. **Remote URLs** (if the path starts with `http://` or `https://`)
+
+If a file is not found, Hugo will show a helpful error message telling you where to place the file.
+
+## Advanced Demo
+
+Here's a more advanced example showcasing all available parameters:
+
+```markdown
+{{</* asciinema 
+  file="demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+*/>}}
+```
+
+{{< asciinema 
+  file="casts/demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+>}}
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `file` | string | - | Path to the .cast file (required). Supports local files, absolute paths, and remote URLs |
+| `theme` | string | `"asciinema"` | Player theme |
+| `speed` | number | `1` | Playback speed multiplier |
+| `autoplay` | boolean | `false` | Start playing automatically |
+| `loop` | boolean | `false` | Loop the recording |
+| `poster` | string | `""` | Poster (a preview frame) to display until the playback is started. Supports NPT notation (e.g., "npt:1:23") |
+| `markers` | string | `""` | Comma-separated time markers. Format: "time:label" or just "time" (e.g., "1.5:Installation,3.2:Configuration,5.8") |
+

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

@@ -0,0 +1,121 @@
+---
+title: "Asciinema Player 组件"
+linktitle: "Asciinema Player"
+sidebar:
+  exclude: true
+---
+
+asciinema shortcode 允许你在 Hugo 站点中嵌入使用 [asciinema](https://asciinema.org/) 创建的终端录制。它提供了一个功能丰富的终端播放器，具有播放控制、速度调整和主题自定义等功能。
+
+## 基本用法
+
+asciinema shortcode 支持本地 `.cast` 文件和远程 URL。以下是使用本地文件的不同方法：
+
+### 本地文件
+
+**方法 1：Assets 目录（推荐）**
+将你的 cast 文件放在 Hugo 站点的 `assets/` 目录中：
+
+```
+your-site/
+├── assets/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 2：Static 目录**
+将你的 cast 文件放在 `static/` 目录中：
+
+```
+your-site/
+├── static/
+│   └── demo.cast
+└── content/
+    └── my-page.md
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+**方法 3：页面包**
+对于页面包，将 cast 文件与你的 markdown 文件放在一起：
+
+```
+your-site/
+└── content/
+    └── my-page/
+        ├── index.md
+        └── demo.cast
+```
+
+在你的 markdown 文件中：
+```markdown
+{{</* asciinema file="demo.cast" */>}}
+```
+
+{{< asciinema file="casts/demo.cast" >}}
+
+### 远程文件
+
+你也可以使用来自任何远程 URL 的 cast 文件：
+
+```markdown
+{{</* asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" */>}}
+{{</* asciinema file="https://example.com/demo.cast" */>}}
+```
+
+{{< asciinema file="https://asciinema.org/a/85R4jTtjKVRIYXTcKCNq0vzYH.cast" >}}
+
+### 文件查找机制
+
+shortcode 会按以下顺序自动查找你的 cast 文件：
+1. **页面包资源**（如果使用页面包）
+2. **全局 assets 目录**（`assets/`）
+3. **Static 目录**（`static/`）
+4. **远程 URL**（如果路径以 `http://` 或 `https://` 开头）
+
+如果找不到文件，Hugo 会显示有用的错误信息，告诉你应该将文件放在哪里。
+
+## 高级演示
+
+这是一个展示所有可用参数的高级示例：
+
+```markdown
+{{</* asciinema 
+  file="demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+*/>}}
+```
+
+{{< asciinema 
+  file="casts/demo.cast"
+  theme="dracula"
+  speed="2"
+  autoplay="true"
+  loop="true"
+  markers="1.5:Installation,3.2:Configuration,5.8:Testing"
+>}}
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `file` | string | - | .cast 文件路径（必需）。支持本地文件、绝对路径和远程 URL |
+| `theme` | string | `"asciinema"` | 播放器主题 |
+| `speed` | number | `1` | 播放速度倍数 |
+| `autoplay` | boolean | `false` | 自动开始播放 |
+| `loop` | boolean | `false` | 循环播放 |
+| `poster` | string | `""` | 播放开始前显示的海报（预览帧）。支持 NPT 表示法（如 "npt:1:23"） |
+| `markers` | string | `""` | 逗号分隔的时间标记。格式："时间:标签" 或仅 "时间"（如 "1.5:Installation,3.2:Configuration,5.8"） |

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

@@ -14,70 +14,136 @@ 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 >}}
 
 {{< callout type="info" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 {{< callout type="warning" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 {{< callout type="error" >}}
-  یک **callout** متن کوتاهی است که برای جلب توجه طراحی شده است.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
-## نحوه استفاده
+{{< callout type="important" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
 
-### پیش‌فرض
+### تقصير
 
-{{< callout emoji="🌐">}}
+{{< callout >}}
-  Hugo می‌تواند برای ایجاد انواع مختلف وب‌سایت‌ها از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندات و غیره استفاده شود.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 ```markdown
-{{</* callout emoji="🌐" */>}}
+{{</* callout */>}}
-  Hugo می‌تواند برای ایجاد انواع مختلف وب‌سایت‌ها از جمله وبلاگ‌ها، نمونه‌کارها، سایت‌های مستندات و غیره استفاده شود.
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{</* /callout */>}}
 ```
 
-### اطلاعات
+### Info
 
 {{< callout type="info" >}}
-  لطفاً برای مشاهده آخرین نسخه‌ها به GitHub مراجعه کنید.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="info" */>}}
-  لطفاً برای مشاهده آخرین نسخه‌ها به GitHub مراجعه کنید.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.  
 {{</* /callout */>}}
 ```
 
-### هشدار
+### Warning
 
 {{< callout type="warning" >}}
-  این API در نسخه بعدی منسوخ خواهد شد.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="warning" */>}}
-  این API در نسخه بعدی منسوخ خواهد شد.
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{</* /callout */>}}
 ```
 
-### خطا
+### Error
 
 {{< callout type="error" >}}
-  مشکلی پیش آمده و قرار است منفجر شود.
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{< /callout >}}
 
 ```markdown
 {{</* callout type="error" */>}}
-  مشکلی پیش آمده و قرار است منفجر شود.
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
 {{</* /callout */>}}
 ```
+
+### Important
+
+{{< callout type="important" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="important" */>}} 
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{</* /callout */>}}
+```
+
+### أيقونة مخصصة
+
+{{< callout icon="sparkles" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
+
+```markdown
+{{</* callout icon="sparkles" */>}}
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{</* /callout */>}}
+```
+
+{{< callout type="important" icon="sparkles" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="important" icon="sparkles" */>}}
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{</* /callout */>}}
+```
+
+### الرموز التعبيرية
+
+{{< callout emoji="🌐" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
+
+```markdown
+{{</* callout emoji="🌐" */>}}
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{</* /callout */>}}
+```
+
+{{< callout type="info" emoji="ℹ️" >}}
+**الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="info" emoji="ℹ️" */>}}
+  **الإشارة** عبارة عن جزء قصير من النص يهدف إلى جذب الانتباه.
+{{</* /callout */>}}
+```
+
+## خيارات
+
+| المعلمة | وصف                                                                 |
+|---------|---------------------------------------------------------------------|
+| `type`  | نوع الاستدعاء. (افتراضي، `info`، `warning`، `error`)                |
+| `emoji` | الرمز التعبيري الذي يظهر قبل المكالمة.                              |
+| `icon`  | رمز تعبيري للنداء (مرتبط بالنوع أو يمكن أن يكون رمز تعبيري مخصصًا). |

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

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

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

@@ -14,9 +14,9 @@ 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
+## Examples
 
-{{< callout emoji="👾">}}
+{{< callout >}}
   A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
@@ -32,36 +32,38 @@ A built-in component to show important information to the reader.
   A **callout** is a short piece of text intended to attract attention.
 {{< /callout >}}
 
-## Usage
+{{< callout type="important" >}}
+  A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
 
 ### Default
 
-{{< callout emoji="🌐">}}
+{{< callout >}}
-  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="🌐" */>}}
+{{</* callout */>}}
-  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 +75,75 @@ 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 */>}}
 ```
+
+### Important
+
+{{< callout type="important" >}}
+  A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="important" */>}} 
+  A **callout** is a short piece of text intended to attract attention.
+{{</* /callout */>}}
+```
+
+### Custom Icon
+
+{{< callout icon="sparkles" >}}
+A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
+
+```markdown
+{{</* callout icon="sparkles" */>}}
+  A **callout** is a short piece of text intended to attract attention.
+{{</* /callout */>}}
+```
+
+{{< callout type="important" icon="sparkles" >}}
+A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="important" icon="sparkles" */>}}
+  A **callout** is a short piece of text intended to attract attention.
+{{</* /callout */>}}
+```
+
+### Emoji
+
+{{< callout emoji="🌐" >}}
+A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
+
+```markdown
+{{</* callout emoji="🌐" */>}}
+  A **callout** is a short piece of text intended to attract attention.
+{{</* /callout */>}}
+```
+
+{{< callout type="info" emoji="ℹ️" >}}
+A **callout** is a short piece of text intended to attract attention.
+{{< /callout >}}
+
+```markdown
+{{</* callout type="info" emoji="ℹ️" */>}}
+  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`, `important`)         |
+| `emoji`   | The emoji to show before the callout.                                           |
+| `icon`    | The icon to show before the callout. (related to type or can be a custom icon). |

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

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

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

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

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

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

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

@@ -37,24 +37,23 @@ linkTitle: Cards
 
 ## Card Parameters
 
-| Parameter  | Description                                                     |
+| Parameter   | Description                                                                            |
-|----------- |-----------------------------------------------------------------|
+|-------------|----------------------------------------------------------------------------------------|
-| `link`     | URL (internal or external).                                     |
+| `link`      | URL (internal or external).                                                            |
-| `title`    | Title heading for the card.                                     |
+| `title`     | Title heading for the card.                                                            |
-| `subtitle` | Subtitle heading (supports Markdown).                           |
+| `subtitle`  | Subtitle heading (supports Markdown).                                                  |
-| `icon`     | Name of the icon.                                               |
+| `icon`      | Name of the icon. See [icons]({{% relRef "icon" %}}) for more information.             |
-| `tag`      | Text in tag.                                                    |
-| `tagColor` | Color of the tag: `gray` (default), `yellow`, `red` and `blue`. |
 
 ## Image Card
 
 Additionally, the card supports adding image and processing through these parameters:
 
-| Parameter  | Description                                 |
+| Parameter    | Description                                        |
-|----------- |---------------------------------------------|
+|--------------|----------------------------------------------------|
-| `image`    | Specifies the image URL for the card.       |
+| `image`      | Specifies the image URL for the card.              |
-| `method`   | Sets Hugo's image processing method.        |
+| `method`     | Sets Hugo's image processing method.               |
-| `options`  | Configures Hugo's image processing options. |
+| `options`    | Configures Hugo's image processing options.        |
+| `imageStyle` | Used to fill the style attribute of the image tag. |
 
 Card supports three kinds of images:
 
@@ -71,20 +70,30 @@ For more on Hugo's built in image processing commands, methods, and options see
 
 Card supports adding tags which could be useful to show extra status information.
 
+| Parameter   | Description                                                                            |
+|-------------|----------------------------------------------------------------------------------------|
+| `tag`       | Text in tag.                                                                           |
+| `tagColor`  | Color of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information.  |
+| `tagIcon`   | Icon of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information.   |
+| `tagBorder` | Border of the tag. See [badges]({{% relRef "others/#badges" %}}) for more information. |
+
 {{< cards >}}
   {{< card link="../callout" title="Card with default tag" tag="tag text" >}}
-  {{< card link="../callout" title="Card with error tag" tag="tag text" tagType="error" >}}
+  {{< card link="../callout" title="Card with red tag" tag="tag text" tagColor="red" >}}
-  {{< card link="../callout" title="Card with info tag" tag="tag text" tagType="info" >}}
+  {{< card link="../callout" title="Card with blue tag" tag="tag text" tagColor="blue" >}}
-  {{< card link="../callout" title="Card with warning tag" tag="tag text" tagType="warning" >}}
+  {{< card link="../callout" title="Card with yellow tag" tag="tag text" tagColor="yellow" tagIcon="sparkles" tagBorder=false >}}
-  {{< card link="/" title="Image Card" image="https://github.com/user-attachments/assets/71b7e3ec-1a8d-4582-b600-5425c6cc0407" subtitle="Internet Image" tag="tag text" tagType="error" >}}
+  {{< card link="/" title="Image Card" image="/images/card-image-unprocessed.jpg" subtitle="Image" tag="tag text" tagColor="green" >}}
+  {{< card link="/" title="Image Card" image="images/space.jpg" subtitle="Image" tag="tag text" tagColor="purple" tagIcon="sparkles" tagBorder=false >}}
 {{< /cards >}}
 
 ```
 {{</* cards */>}}
   {{</* card link="../callout" title="Card with default tag color" tag="tag text" */>}}
-  {{</* card link="../callout" title="Card with default red tag" tag="tag text" tagType="error" */>}}
+  {{</* card link="../callout" title="Card with red tag" tag="tag text" tagColor="red" */>}}
-  {{</* card link="../callout" title="Card with blue tag" tag="tag text" tagType="info" */>}}
+  {{</* card link="../callout" title="Card with blue tag" tag="tag text" tagColor="blue" */>}}
-  {{</* card link="../callout" title="Card with yellow tag" tag="tag text" tagType="warning" */>}}
+  {{</* card link="../callout" title="Card with yellow tag" tag="tag text" tagColor="yellow" tagIcon="sparkles" tagBorder=false */>}}
+  {{</* card link="/" title="Image Card" image="/images/card-image-unprocessed.jpg" subtitle="Image" tag="tag text" tagColor="green" */>}}
+  {{</* card link="/" title="Image Card" image="images/space.jpg" subtitle="Image" tag="tag text" tagColor="purple" tagIcon="sparkles" tagBorder=false */>}}
 {{</* /cards */>}}
 ```
 

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

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

@@ -0,0 +1,175 @@
+---
+title: Hextra Shortcodes
+linkTitle: Hextra
+sidebar:
+  exclude: true
+next: /docs/guide/deploy-site
+---
+
+الاستخدام الرئيسي لهذه الرموز المختصرة هو داخل التخطيط `hextra-home`.
+
+## `hextra/feature-card`
+
+رمز مختصر لعرض بطاقة مميزة.
+
+### Usage
+
+```
+{{</* hextra/feature-card title="Title" subtitle="Subtitle" */>}}
+```
+
+### Options
+
+| Parameter    | Description             |
+|--------------|-------------------------|
+| `title`      | عنوان البطاقة.          |
+| `subtitle`   | العنوان الفرعي للبطاقة. |
+| `class`      | فئة البطاقة.            |
+| `image`      | صورة البطاقة.           |
+| `imageClass` | فئة الصورة.             |
+| `style`      | نمط البطاقة.            |
+| `icon`       | أيقونة البطاقة.         |
+| `link`       | رابط البطاقة.           |
+
+## `hextra/feature-grid`
+
+رمز مختصر لعرض شبكة الميزات.
+
+### Usage
+
+```
+{{</* hextra/feature-grid cols="3" */>}}
+  {{</* hextra/feature-card title="One" */>}}
+  {{</* hextra/feature-card title="Two" */>}}
+  {{</* hextra/feature-card title="Three" */>}}
+{{</* /hextra/feature-grid */>}}
+```
+
+### Options
+
+| Parameter | Description  |
+|-----------|--------------|
+| `cols`    | عدد الأعمدة. |
+| `style`   | نمط الشبكة.  |
+
+## `hextra/hero-badge`
+
+رمز مختصر لعرض شارة تحتوي على رابط.
+
+### Usage
+
+```
+{{</* hextra/hero-badge */>}}
+  <div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{</* icon name="arrow-circle-right" attributes="height=14" */>}}
+{{</* /hextra/hero-badge */>}}
+```
+
+### Options
+
+| Parameter | Description  |
+|-----------|--------------|
+| `link`    | رابط الشارة. |
+| `class`   | فئة الشارة.  |
+| `style`   | شكل الشارة.  |
+
+## `hextra/hero-button`
+
+رمز مختصر لعرض زر يحتوي على رابط.
+
+### Usage
+
+```
+{{</* hextra/hero-button text="Get Started" link="/docs" */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `link`    | رابط الزر.  |
+| `text`    | نص الزر.    |
+| `style`   | شكل الزر.   |
+
+## `hextra/hero-container`
+
+حاوية بطل بسيطة مع صورة على الجانب الأيسر.
+
+### Usage
+
+```
+{{</* hextra/hero-container image="images/logo.svg"  imageTitle="title" */>}}
+    Content
+{{</* /hextra/hero-container */>}}
+```
+
+### Options
+
+| Parameter     | Description                             |
+|---------------|-----------------------------------------|
+| `class`       | فئة الحاوية.                            |
+| `cols`        | عدد الأعمدة (الافتراضي: `2`).           |
+| `image`       | صورة الحاوية.                           |
+| `imageCard`   | عرض الصورة كبطاقة (الافتراضي: `false`). |
+| `imageClass`  | فئة الصورة.                             |
+| `imageLink`   | رابط الصورة.                            |
+| `imageStyle`  | شكل الصورة.                             |
+| `imageTitle`  | عنوان الصورة.                           |
+| `imageWidth`  | عرض الصورة (الافتراضي: `350`).          |
+| `imageHeight` | ارتفاع الصورة (الافتراضي: `350`).       |
+| `style`       | شكل الحاوية.                            |
+
+## `hextra/hero-headline`
+
+رمز مختصر لعرض عنوان رئيسي.
+
+### Usage
+
+```
+{{</* hextra/hero-headline */>}}
+  Build modern websites&nbsp;<br class="hx:sm:block hx:hidden" />with Markdown and Hugo
+{{</* /hextra/hero-headline */>}}
+```
+
+### Options
+
+| Parameter | Description    |
+|-----------|----------------|
+| `style`   | أسلوب العنوان. |
+
+## `hextra/hero-section`
+
+قسم بطل بسيط مع عنوان ونمط اختياري.
+
+### Usage
+
+```
+{{</* hextra/hero-section heading="h3" */>}}Title{{</* /hextra/hero-section */>}}>
+```
+
+### Options
+
+| Parameter | Description                    |
+|-----------|--------------------------------|
+| `heading` | مستوى العنوان (افتراضي: `h2`). |
+| `style`   | نمط العنوان.                   |
+| `content` | محتوى العنوان.                 |
+
+## `hextra/hero-subtitle`
+
+رمز مختصر لعرض عنوان فرعي للبطل.
+
+### Usage
+
+```
+{{</* hextra/hero-subtitle */>}}
+  Fast, batteries-included Hugo theme&nbsp;<br class="hx:sm:block hx:hidden" />for creating beautiful static websites
+{{</* /hextra/hero-subtitle */>}}
+```
+
+### Options
+
+| Parameter | Description    |
+|-----------|----------------|
+| `style`   | أسلوب الترجمة. |

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

@@ -0,0 +1,175 @@
+---
+title: Hextra Shortcodes
+linkTitle: Hextra
+sidebar:
+  exclude: true
+next: /docs/guide/deploy-site
+---
+
+これらのショートコードの主な使用場所は、レイアウト `hextra-home` 内です。
+
+## `hextra/feature-card`
+
+機能カードを表示するためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/feature-card title="Title" subtitle="Subtitle" */>}}
+```
+
+### Options
+
+| Parameter    | Description |
+|--------------|-------------|
+| `title`      | カードのタイトル。   |
+| `subtitle`   | カードのサブタイトル。 |
+| `class`      | カードのクラス。    |
+| `image`      | カードの画像。     |
+| `imageClass` | 画像のクラス。     |
+| `style`      | カードのスタイル。   |
+| `icon`       | カードのアイコン。   |
+| `link`       | カードのリンク。    |
+
+## `hextra/feature-grid`
+
+機能グリッドを表示するためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/feature-grid cols="3" */>}}
+  {{</* hextra/feature-card title="One" */>}}
+  {{</* hextra/feature-card title="Two" */>}}
+  {{</* hextra/feature-card title="Three" */>}}
+{{</* /hextra/feature-grid */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `cols`    | 列の数。        |
+| `style`   | グリッドのスタイル。  |
+
+## `hextra/hero-badge`
+
+リンク付きのバッジをレンダリングするためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/hero-badge */>}}
+  <div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{</* icon name="arrow-circle-right" attributes="height=14" */>}}
+{{</* /hextra/hero-badge */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `link`    | バッジのリンク。    |
+| `class`   | バッジのクラス。    |
+| `style`   | バッジのスタイル。   |
+
+## `hextra/hero-button`
+
+リンク付きのボタンをレンダリングするためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/hero-button text="Get Started" link="/docs" */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `link`    | ボタンのリンク。    |
+| `text`    | ボタンのテキスト。   |
+| `style`   | ボタンのスタイル。   |
+
+## `hextra/hero-container`
+
+左側に画像があるシンプルなヒーロー コンテナー。
+
+### Usage
+
+```
+{{</* hextra/hero-container image="images/logo.svg"  imageTitle="title" */>}}
+    Content
+{{</* /hextra/hero-container */>}}
+```
+
+### Options
+
+| Parameter     | Description                       |
+|---------------|-----------------------------------|
+| `class`       | コンテナのクラス。                         |
+| `cols`        | 列数（デフォルト：`2`）。                    |
+| `image`       | コンテナの画像。                          |
+| `imageCard`   | 画像をカードとして表示するかどうか（デフォルト：`false`）。 |
+| `imageClass`  | 画像のクラス。                           |
+| `imageLink`   | 画像のリンク。                           |
+| `imageStyle`  | 画像のスタイル。                          |
+| `imageTitle`  | 画像のタイトル。                          |
+| `imageWidth`  | 画像の幅（デフォルト：`350`）。                |
+| `imageHeight` | 画像の高さ（デフォルト：`350`）。               |
+| `style`       | コンテナのスタイル。                        |
+
+## `hextra/hero-headline`
+
+ヒーローの見出しを表示するためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/hero-headline */>}}
+  Build modern websites&nbsp;<br class="hx:sm:block hx:hidden" />with Markdown and Hugo
+{{</* /hextra/hero-headline */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `style`   | 見出しのスタイル。   |
+
+## `hextra/hero-section`
+
+見出しとオプションのスタイルを備えたシンプルなヒーロー セクション。
+
+### Usage
+
+```
+{{</* hextra/hero-section heading="h3" */>}}Title{{</* /hextra/hero-section */>}}>
+```
+
+### Options
+
+| Parameter | Description          |
+|-----------|----------------------|
+| `heading` | 見出しレベル（デフォルト: `h2`）。 |
+| `style`   | 見出しのスタイル。            |
+| `content` | 見出しの内容。              |
+
+## `hextra/hero-subtitle`
+
+ヒーローのサブタイトルを表示するためのショートコード。
+
+### Usage
+
+```
+{{</* hextra/hero-subtitle */>}}
+  Fast, batteries-included Hugo theme&nbsp;<br class="hx:sm:block hx:hidden" />for creating beautiful static websites
+{{</* /hextra/hero-subtitle */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `style`   | 字幕のスタイル。    |

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

@@ -0,0 +1,175 @@
+---
+title: Hextra Shortcodes
+linkTitle: Hextra
+sidebar:
+  exclude: true
+next: /docs/guide/deploy-site
+---
+
+The main usage of these shortcodes are within the layout `hextra-home`.
+
+## `hextra/feature-card`
+
+A shortcode for displaying a feature card.
+
+### Usage
+
+```
+{{</* hextra/feature-card title="Title" subtitle="Subtitle" */>}}
+```
+
+### Options
+
+| Parameter    | Description               |
+|--------------|---------------------------|
+| `title`      | The title of the card.    |
+| `subtitle`   | The subtitle of the card. |
+| `class`      | The class of the card.    |
+| `image`      | The image of the card.    |
+| `imageClass` | The class of the image.   |
+| `style`      | The style of the card.    |
+| `icon`       | The icon of the card.     |
+| `link`       | The link of the card.     |
+
+## `hextra/feature-grid`
+
+A shortcode for displaying a feature grid.
+
+### Usage
+
+```
+{{</* hextra/feature-grid cols="3" */>}}
+  {{</* hextra/feature-card title="One" */>}}
+  {{</* hextra/feature-card title="Two" */>}}
+  {{</* hextra/feature-card title="Three" */>}}
+{{</* /hextra/feature-grid */>}}
+```
+
+### Options
+
+| Parameter | Description            |
+|-----------|------------------------|
+| `cols`    | The number of columns. |
+| `style`   | The style of the grid. |
+
+## `hextra/hero-badge`
+
+A shortcode for rendering a badge with a link.
+
+### Usage
+
+```
+{{</* hextra/hero-badge */>}}
+  <div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{</* icon name="arrow-circle-right" attributes="height=14" */>}}
+{{</* /hextra/hero-badge */>}}
+```
+
+### Options
+
+| Parameter | Description             |
+|-----------|-------------------------|
+| `link`    | The link of the badge.  |
+| `class`   | The class of the badge. |
+| `style`   | The style of the badge. |
+
+## `hextra/hero-button`
+
+A shortcode for rendering a button with a link.
+
+### Usage
+
+```
+{{</* hextra/hero-button text="Get Started" link="/docs" */>}}
+```
+
+### Options
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `link`    | The link of the button.  |
+| `text`    | The text of the button.  |
+| `style`   | The style of the button. |
+
+## `hextra/hero-container`
+
+A simple hero container with an image on the left side.
+
+### Usage
+
+```
+{{</* hextra/hero-container image="images/logo.svg"  imageTitle="title" */>}}
+    Content
+{{</* /hextra/hero-container */>}}
+```
+
+### Options
+
+| Parameter     | Description                                                |
+|---------------|------------------------------------------------------------|
+| `class`       | The class of the container.                                |
+| `cols`        | The number of columns (default: `2`).                      |
+| `image`       | The image of the container.                                |
+| `imageCard`   | Whether to display the image as a card (default: `false`). |
+| `imageClass`  | The class of the image.                                    |
+| `imageLink`   | The link of the image.                                     |
+| `imageStyle`  | The style of the image.                                    |
+| `imageTitle`  | The title of the image.                                    |
+| `imageWidth`  | The width of the image (default: `350`).                   |
+| `imageHeight` | The height of the image (default: `350`).                  |
+| `style`       | The style of the container.                                |
+
+## `hextra/hero-headline`
+
+A shortcode for displaying a hero headline.
+
+### Usage
+
+```
+{{</* hextra/hero-headline */>}}
+  Build modern websites&nbsp;<br class="hx:sm:block hx:hidden" />with Markdown and Hugo
+{{</* /hextra/hero-headline */>}}
+```
+
+### Options
+
+| Parameter | Description                |
+|-----------|----------------------------|
+| `style`   | The style of the headline. |
+
+## `hextra/hero-section`
+
+A simple hero section with a heading and optional style.
+
+### Usage
+
+```
+{{</* hextra/hero-section heading="h3" */>}}Title{{</* /hextra/hero-section */>}}>
+```
+
+### Options
+
+| Parameter | Description                        |
+|-----------|------------------------------------|
+| `heading` | The heading level (default: `h2`). |
+| `style`   | The style of the heading.          |
+| `content` | The content of the heading.        |
+
+## `hextra/hero-subtitle`
+
+A shortcode for displaying a hero subtitle.
+
+### Usage
+
+```
+{{</* hextra/hero-subtitle */>}}
+  Fast, batteries-included Hugo theme&nbsp;<br class="hx:sm:block hx:hidden" />for creating beautiful static websites
+{{</* /hextra/hero-subtitle */>}}
+```
+
+### Options
+
+| Parameter | Description                |
+|-----------|----------------------------|
+| `style`   | The style of the subtitle. |

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

@@ -0,0 +1,175 @@
+---
+title: Hextra Shortcodes
+linkTitle: Hextra
+sidebar:
+  exclude: true
+next: /docs/guide/deploy-site
+---
+
+这些短代码的主要用途是在布局`hextra-home`内。
+
+## `hextra/feature-card`
+
+显示功能卡的短代码。
+
+### Usage
+
+```
+{{</* hextra/feature-card title="Title" subtitle="Subtitle" */>}}
+```
+
+### Options
+
+| Parameter    | Description |
+|--------------|-------------|
+| `title`      | 卡片的标题。      |
+| `subtitle`   | 卡片的副标题。     |
+| `class`      | 卡片的类别。      |
+| `image`      | 卡片的图片。      |
+| `imageClass` | 图片的类别。      |
+| `style`      | 卡片的样式。      |
+| `icon`       | 卡片的图标。      |
+| `link`       | 卡片的链接。      |
+
+## `hextra/feature-grid`
+
+用于显示特征网格的短代码。
+
+### Usage
+
+```
+{{</* hextra/feature-grid cols="3" */>}}
+  {{</* hextra/feature-card title="One" */>}}
+  {{</* hextra/feature-card title="Two" */>}}
+  {{</* hextra/feature-card title="Three" */>}}
+{{</* /hextra/feature-grid */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `cols`    | 列数。         |
+| `style`   | 网格的样式。      |
+
+## `hextra/hero-badge`
+
+用于呈现带有链接的徽章的短代码。
+
+### Usage
+
+```
+{{</* hextra/hero-badge */>}}
+  <div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{</* icon name="arrow-circle-right" attributes="height=14" */>}}
+{{</* /hextra/hero-badge */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `link`    | 徽章的链接。      |
+| `class`   | 徽章的类别。      |
+| `style`   | 徽章的样式。      |
+
+## `hextra/hero-button`
+
+用于呈现带有链接的按钮的短代码。
+
+### Usage
+
+```
+{{</* hextra/hero-button text="Get Started" link="/docs" */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `link`    | 按钮的链接。      |
+| `text`    | 按钮的文本。      |
+| `style`   | 按钮的样式。      |
+
+## `hextra/hero-container`
+
+一个简单的英雄容器，左侧有一个图像。
+
+### Usage
+
+```
+{{</* hextra/hero-container image="images/logo.svg"  imageTitle="title" */>}}
+    Content
+{{</* /hextra/hero-container */>}}
+```
+
+### Options
+
+| Parameter     | Description              |
+|---------------|--------------------------|
+| `class`       | 容器的类。                    |
+| `cols`        | 列数（默认值：`2`）。             |
+| `image`       | 容器的图片。                   |
+| `imageCard`   | 是否将图片显示为卡片（默认值：`false`）。 |
+| `imageClass`  | 图片的类。                    |
+| `imageLink`   | 图片的链接。                   |
+| `imageStyle`  | 图片的样式。                   |
+| `imageTitle`  | 图片的标题。                   |
+| `imageWidth`  | 图片的宽度（默认值：`350`）。        |
+| `imageHeight` | 图片的高度（默认值：`350`）。        |
+| `style`       | 容器的样式。                   |
+
+## `hextra/hero-headline`
+
+显示英雄标题的短代码。
+
+### Usage
+
+```
+{{</* hextra/hero-headline */>}}
+  Build modern websites&nbsp;<br class="hx:sm:block hx:hidden" />with Markdown and Hugo
+{{</* /hextra/hero-headline */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `style`   | 标题的样式。      |
+
+## `hextra/hero-section`
+
+带有标题和可选样式的简单英雄部分。
+
+### Usage
+
+```
+{{</* hextra/hero-section heading="h3" */>}}Title{{</* /hextra/hero-section */>}}>
+```
+
+### Options
+
+| Parameter | Description     |
+|-----------|-----------------|
+| `heading` | 标题级别（默认值：`h2`）。 |
+| `style`   | 标题的样式。          |
+| `content` | 标题的内容。          |
+
+## `hextra/hero-subtitle`
+
+显示英雄字幕的短代码。
+
+### Usage
+
+```
+{{</* hextra/hero-subtitle */>}}
+  Fast, batteries-included Hugo theme&nbsp;<br class="hx:sm:block hx:hidden" />for creating beautiful static websites
+{{</* /hextra/hero-subtitle */>}}
+```
+
+### Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `style`   | 字幕的样式。      |

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/jupyter.fa.md

@@ -6,7 +6,7 @@ sidebar:
   exclude: true
 ---
 
-{{< callout >}}ویژگی آزمایشی برای گنجاندن Jupyter Notebookها از طریق یک شورتکد. توجه داشته باشید که همه انواع سلول‌ها پشتیبانی نمی‌شوند.{{< /callout >}}
+{{< callout type="warning" >}}ویژگی آزمایشی برای گنجاندن Jupyter Notebookها از طریق یک شورتکد. توجه داشته باشید که همه انواع سلول‌ها پشتیبانی نمی‌شوند.{{< /callout >}}
 
 [Jupyter Notebook](https://jupyter.org/) یک برنامه نوت‌بوک HTML مستقل از زبان برای [پروژه Jupyter](https://jupyter.org/) است. این برنامه به شما امکان می‌دهد اسنادی ایجاد و به اشتراک بگذارید که شامل کد زنده، معادلات، تصاویر و متن روایی هستند.
 

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

@@ -6,7 +6,7 @@ sidebar:
   exclude: true
 ---
 
-{{< callout >}}Jupyter Notebook をショートコード経由で組み込む実験的機能です。すべてのセルタイプがサポートされているわけではありません。{{< /callout >}}
+{{< callout type="warning" >}}Jupyter Notebook をショートコード経由で組み込む実験的機能です。すべてのセルタイプがサポートされているわけではありません。{{< /callout >}}
 
 [Jupyter Notebook](https://jupyter.org/) は [Project Jupyter](https://jupyter.org/) の言語非依存な HTML ノートブックアプリケーションです。ライブコード、数式、可視化、説明文を含むドキュメントを作成・共有できます。
 

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

@@ -6,7 +6,7 @@ sidebar:
   exclude: true
 ---
 
-{{< callout >}}Experimental feature to include Jupyter Notebooks via a shortcode. Note that not all cell types are supported.{{< /callout >}}
+{{< callout type="warning" >}}Experimental feature to include Jupyter Notebooks via a shortcode. Note that not all cell types are supported.{{< /callout >}}
 
 [Jupyter Notebook](https://jupyter.org/) is a language-agnostic HTML notebook application for [Project Jupyter](https://jupyter.org/). It allows you to create and share documents that contain live code, equations, visualizations, and narrative text.
 

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

@@ -6,7 +6,7 @@ sidebar:
   exclude: true
 ---
 
-{{< callout >}}实验性功能：通过短代码嵌入 Jupyter Notebook。注意并非所有单元格类型都受支持。{{< /callout >}}
+{{< callout type="warning" >}}实验性功能：通过短代码嵌入 Jupyter Notebook。注意并非所有单元格类型都受支持。{{< /callout >}}
 
 [Jupyter Notebook](https://jupyter.org/) 是 [Project Jupyter](https://jupyter.org/) 推出的语言无关的 HTML 笔记本应用。它允许你创建和分享包含动态代码、数学公式、可视化图表和叙述性文本的文档。
 

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

@@ -1,49 +1,98 @@
 ---
 title: سایر شورتکدها
 linkTitle: سایر
-sidebar:
-  exclude: true
 next: /docs/guide/deploy-site
 ---
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   برخی از این‌ها شورتکدهای داخلی Hugo هستند.
   این شورتکدها کمتر پایدار در نظر گرفته می‌شوند و ممکن است هر زمان تغییر کنند.
 {{< /callout >}}
 
-## نشان
+### أمثلة
+
+{{< badge "default" >}}&nbsp;
+{{< badge content="border" border=false >}}&nbsp;
+{{< badge content="color" color="green" >}}&nbsp;
+{{< badge content="link" link="https://github.com/imfing/hextra/releases" >}}&nbsp;
+{{< badge content="icon" icon="sparkles" >}}&nbsp;
+
+### الاستخدام
+
+#### تقصير
+
+{{< badge "Badge" >}}&nbsp;
 
 ```
-{{</* badge "نشان" */>}}
+{{</* badge "Badge" */>}}
 ```
 
-نتیجه:
+#### الألوان
 
-{{< badge "نشان" >}}
+{{< badge content="Badge" >}}&nbsp;
-
+{{< badge content="Badge" color="purple" >}}&nbsp;
-انواع مختلف:
+{{< badge content="Badge" color="indigo" >}}&nbsp;
+{{< badge content="Badge" color="blue" >}} &nbsp;
+{{< badge content="Badge" color="green" >}} &nbsp;
+{{< badge content="Badge" color="yellow" >}} &nbsp;
+{{< badge content="Badge" color="amber" >}} &nbsp;
+{{< badge content="Badge" color="orange" >}} &nbsp;
+{{< badge content="Badge" color="red" >}}&nbsp;
 
 ```
-{{</* badge content="اطلاعات" type="info" */>}}
+{{</* badge content="Badge" */>}}
-{{</* badge content="هشدار" type="warning" */>}}
+{{</* badge content="Badge" color="purple" */>}}
-{{</* badge content="خطا" type="error" */>}}
+{{</* badge content="Badge" color="indigo" */>}}
+{{</* badge content="Badge" color="blue" */>}}
+{{</* badge content="Badge" color="green" */>}}
+{{</* badge content="Badge" color="yellow" */>}}
+{{</* badge content="Badge" color="amber" */>}}
+{{</* badge content="Badge" color="orange" */>}}
+{{</* badge content="Badge" color="red" */>}}
 ```
 
-نتیجه:
+{{< badge content="Badge" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="purple" border=false >}} &nbsp;
-{{< badge content="اطلاعات" type="info" >}} &nbsp;
+{{< badge content="Badge" color="indigo" border=false >}} &nbsp;
-{{< badge content="هشدار" type="warning" >}} &nbsp;
+{{< badge content="Badge" color="blue" border=false >}} &nbsp;
-{{< badge content="خطا" type="error" >}}
+{{< badge content="Badge" color="green" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="yellow" border=false >}} &nbsp;
-با لینک و آیکون:
+{{< badge content="Badge" color="amber" border=false >}} &nbsp;
+{{< badge content="Badge" color="orange" border=false >}}&nbsp;
+{{< badge content="Badge" color="red" border=false >}}&nbsp;
 
 ```
-{{</* badge content="انتشارها" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
+{{</* badge content="Badge" border=false */>}}
+{{</* badge content="Badge" color="purple" border=false */>}}
+{{</* badge content="Badge" color="indigo" border=false */>}}
+{{</* badge content="Badge" color="blue" border=false */>}}
+{{</* badge content="Badge" color="green" border=false */>}}
+{{</* badge content="Badge" color="yellow" border=false */>}}
+{{</* badge content="Badge" color="amber" border=false */>}}
+{{</* badge content="Badge" color="orange" border=false */>}}
+{{</* badge content="Badge" color="red" border=false */>}}
 ```
 
-نتیجه:
+#### المتغيرات
 
-{{< badge content="انتشارها" link="https://github.com/imfing/hextra/releases" icon="github" >}}
+{{< badge content="Badge" icon="sparkles" >}}&nbsp;
+{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}&nbsp;
+
+```
+{{</* badge content="Badge" icon="sparkles" */>}}
+{{</* badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
+```
+
+### خيارات
+
+| المعلمة   | وصف                                                                                                       |
+|-----------|-----------------------------------------------------------------------------------------------------------|
+| `content` | نص الشارة.                                                                                                |
+| `link`    | رابط الشارة.                                                                                              |
+| `icon`    | رمز الشارة.                                                                                               |
+| `color`   | `gray` (تقصير), `purple`, `indigo`, `blue`, `green`, `yellow`, `amber`, `orange`, `red`.<br/> لون الشارة. |
+| `class`   | فئة الشارة.                                                                                               |
+| `border`  | إضافة أو إزالة الحدود (افتراضي: true                                                                      |
 
 ## یوتیوب
 

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

@@ -1,49 +1,98 @@
 ---
 title: その他のショートコード
 linkTitle: その他
-sidebar:
-  exclude: true
 next: /docs/guide/deploy-site
 ---
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   これらの一部は Hugo 組み込みのショートコードです。
   これらのショートコードは安定性が低く、いつでも変更される可能性があります。
 {{< /callout >}}
 
-## バッジ
+### 例
+
+{{< badge "default" >}}&nbsp;
+{{< badge content="border" border=false >}}&nbsp;
+{{< badge content="color" color="green" >}}&nbsp;
+{{< badge content="link" link="https://github.com/imfing/hextra/releases" >}}&nbsp;
+{{< badge content="icon" icon="sparkles" >}}&nbsp;
+
+### 使用法
+
+#### デフォルト
+
+{{< badge "Badge" >}}&nbsp;
 
 ```
 {{</* badge "Badge" */>}}
 ```
 
-結果:
+#### 色
 
-{{< badge "Badge" >}}
+{{< badge content="Badge" >}}&nbsp;
-
+{{< badge content="Badge" color="purple" >}}&nbsp;
-バリエーション:
+{{< badge content="Badge" color="indigo" >}}&nbsp;
+{{< badge content="Badge" color="blue" >}} &nbsp;
+{{< badge content="Badge" color="green" >}} &nbsp;
+{{< badge content="Badge" color="yellow" >}} &nbsp;
+{{< badge content="Badge" color="amber" >}} &nbsp;
+{{< badge content="Badge" color="orange" >}} &nbsp;
+{{< badge content="Badge" color="red" >}}&nbsp;
 
 ```
-{{</* badge content="info" type="info" */>}}
+{{</* badge content="Badge" */>}}
-{{</* badge content="warning" type="warning" */>}}
+{{</* badge content="Badge" color="purple" */>}}
-{{</* badge content="error" type="error" */>}}
+{{</* badge content="Badge" color="indigo" */>}}
+{{</* badge content="Badge" color="blue" */>}}
+{{</* badge content="Badge" color="green" */>}}
+{{</* badge content="Badge" color="yellow" */>}}
+{{</* badge content="Badge" color="amber" */>}}
+{{</* badge content="Badge" color="orange" */>}}
+{{</* badge content="Badge" color="red" */>}}
 ```
 
-結果:
+{{< badge content="Badge" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="purple" border=false >}} &nbsp;
-{{< badge content="info" type="info" >}} &nbsp;
+{{< badge content="Badge" color="indigo" border=false >}} &nbsp;
-{{< badge content="warning" type="warning" >}} &nbsp;
+{{< badge content="Badge" color="blue" border=false >}} &nbsp;
-{{< badge content="error" type="error" >}}
+{{< badge content="Badge" color="green" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="yellow" border=false >}} &nbsp;
-リンクとアイコン付き:
+{{< badge content="Badge" color="amber" border=false >}} &nbsp;
+{{< badge content="Badge" color="orange" border=false >}}&nbsp;
+{{< badge content="Badge" color="red" border=false >}}&nbsp;
 
 ```
+{{</* badge content="Badge" border=false */>}}
+{{</* badge content="Badge" color="purple" border=false */>}}
+{{</* badge content="Badge" color="indigo" border=false */>}}
+{{</* badge content="Badge" color="blue" border=false */>}}
+{{</* badge content="Badge" color="green" border=false */>}}
+{{</* badge content="Badge" color="yellow" border=false */>}}
+{{</* badge content="Badge" color="amber" border=false */>}}
+{{</* badge content="Badge" color="orange" border=false */>}}
+{{</* badge content="Badge" color="red" border=false */>}}
+```
+
+#### 変種
+
+{{< badge content="Badge" icon="sparkles" >}}&nbsp;
+{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}&nbsp;
+
+```
+{{</* badge content="Badge" icon="sparkles" */>}}
 {{</* badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
 ```
 
-結果:
+### オプション
 
-{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}
+| パラメータ     | 説明                                                                                                                       |
+|-----------|--------------------------------------------------------------------------------------------------------------------------|
+| `content` | バッジのテキスト。                                                                                                                |
+| `link`    | バッジのリンク。                                                                                                                 |
+| `icon`    | バッジのアイコン。                                                                                                                |
+| `color`   | The color of the badge. <br/> `gray` (default), `purple`, `indigo`, `blue`, `green`, `yellow`, `amber`, `orange`, `red`. |
+| `class`   | バッジのクラス。                                                                                                                 |
+| `border`  | 境界線を追加または削除します (デフォルト: true)。                                                                                            |
 
 ## YouTube
 

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

@@ -1,49 +1,100 @@
 ---
 title: Other Shortcodes
 linkTitle: Others
-sidebar:
-  exclude: true
 next: /docs/guide/deploy-site
 ---
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   Some of these are Hugo built-in shortcodes.
   These shortcodes are considered less stable and may be changed anytime.
 {{< /callout >}}
 
 ## Badge
 
+### Examples
+
+{{< badge "default" >}}&nbsp;
+{{< badge content="border" border=false >}}&nbsp;
+{{< badge content="color" color="green" >}}&nbsp;
+{{< badge content="link" link="https://github.com/imfing/hextra/releases" >}}&nbsp;
+{{< badge content="icon" icon="sparkles" >}}&nbsp;
+
+### Usage
+
+#### Default
+
+{{< badge "Badge" >}}&nbsp;
+
 ```
 {{</* badge "Badge" */>}}
 ```
 
-Result:
+#### Colors
 
-{{< badge "Badge" >}}
+{{< badge content="Badge" >}}&nbsp;
-
+{{< badge content="Badge" color="purple" >}}&nbsp;
-Variants:
+{{< badge content="Badge" color="indigo" >}}&nbsp;
+{{< badge content="Badge" color="blue" >}} &nbsp;
+{{< badge content="Badge" color="green" >}} &nbsp;
+{{< badge content="Badge" color="yellow" >}} &nbsp;
+{{< badge content="Badge" color="amber" >}} &nbsp;
+{{< badge content="Badge" color="orange" >}} &nbsp;
+{{< badge content="Badge" color="red" >}}&nbsp;
 
 ```
-{{</* badge content="info" type="info" */>}}
+{{</* badge content="Badge" */>}}
-{{</* badge content="warning" type="warning" */>}}
+{{</* badge content="Badge" color="purple" */>}}
-{{</* badge content="error" type="error" */>}}
+{{</* badge content="Badge" color="indigo" */>}}
+{{</* badge content="Badge" color="blue" */>}}
+{{</* badge content="Badge" color="green" */>}}
+{{</* badge content="Badge" color="yellow" */>}}
+{{</* badge content="Badge" color="amber" */>}}
+{{</* badge content="Badge" color="orange" */>}}
+{{</* badge content="Badge" color="red" */>}}
 ```
 
-Result:
+{{< badge content="Badge" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="purple" border=false >}} &nbsp;
-{{< badge content="info" type="info" >}} &nbsp;
+{{< badge content="Badge" color="indigo" border=false >}} &nbsp;
-{{< badge content="warning" type="warning" >}} &nbsp;
+{{< badge content="Badge" color="blue" border=false >}} &nbsp;
-{{< badge content="error" type="error" >}}
+{{< badge content="Badge" color="green" border=false >}} &nbsp;
-
+{{< badge content="Badge" color="yellow" border=false >}} &nbsp;
-With link and icon:
+{{< badge content="Badge" color="amber" border=false >}} &nbsp;
+{{< badge content="Badge" color="orange" border=false >}}&nbsp;
+{{< badge content="Badge" color="red" border=false >}}&nbsp;
 
 ```
+{{</* badge content="Badge" border=false */>}}
+{{</* badge content="Badge" color="purple" border=false */>}}
+{{</* badge content="Badge" color="indigo" border=false */>}}
+{{</* badge content="Badge" color="blue" border=false */>}}
+{{</* badge content="Badge" color="green" border=false */>}}
+{{</* badge content="Badge" color="yellow" border=false */>}}
+{{</* badge content="Badge" color="amber" border=false */>}}
+{{</* badge content="Badge" color="orange" border=false */>}}
+{{</* badge content="Badge" color="red" border=false */>}}
+```
+
+#### Variants
+
+{{< badge content="Badge" icon="sparkles" >}}&nbsp;
+{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}&nbsp;
+
+```
+{{</* badge content="Badge" icon="sparkles" */>}}
 {{</* badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
 ```
 
-Result:
+### Options
 
-{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}
+| Name      | Description                                                                                                              |
+|-----------|--------------------------------------------------------------------------------------------------------------------------|
+| `content` | The text of the badge.                                                                                                   |
+| `link`    | The link of the badge.                                                                                                   |
+| `icon`    | The icon of the badge.                                                                                                   |
+| `color`   | The color of the badge. <br/> `gray` (default), `purple`, `indigo`, `blue`, `green`, `yellow`, `amber`, `orange`, `red`. |
+| `class`   | The class of the badge.                                                                                                  |
+| `border`  | Adds or removes the border (default: true).                                                                              |
  
 ## YouTube
 

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

@@ -1,49 +1,98 @@
 ---
 title: 其他短代码
 linkTitle: 其他
-sidebar:
-  exclude: true
 next: /docs/guide/deploy-site
 ---
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   其中部分为Hugo内置短代码。
   这些短代码稳定性较低，可能随时变更。
 {{< /callout >}}
 
-## 徽章
+### 示例
+
+{{< badge "default" >}}&nbsp;
+{{< badge content="border" border=false >}}&nbsp;
+{{< badge content="color" color="green" >}}&nbsp;
+{{< badge content="link" link="https://github.com/imfing/hextra/releases" >}}&nbsp;
+{{< badge content="icon" icon="sparkles" >}}&nbsp;
+
+### 使用
+
+#### 默认
+
+{{< badge "徽章" >}}&nbsp;
 
 ```
 {{</* badge "徽章" */>}}
 ```
 
-效果：
+#### 颜色
 
-{{< badge "徽章" >}}
+{{< badge content="徽章" >}}&nbsp;
-
+{{< badge content="徽章" color="purple" >}}&nbsp;
-变体：
+{{< badge content="徽章" color="indigo" >}}&nbsp;
+{{< badge content="徽章" color="blue" >}} &nbsp;
+{{< badge content="徽章" color="green" >}} &nbsp;
+{{< badge content="徽章" color="yellow" >}} &nbsp;
+{{< badge content="徽章" color="amber" >}} &nbsp;
+{{< badge content="徽章" color="orange" >}} &nbsp;
+{{< badge content="徽章" color="red" >}}&nbsp;
 
 ```
-{{</* badge content="信息" type="info" */>}}
+{{</* badge content="徽章" */>}}
-{{</* badge content="警告" type="warning" */>}}
+{{</* badge content="徽章" color="purple" */>}}
-{{</* badge content="错误" type="error" */>}}
+{{</* badge content="徽章" color="indigo" */>}}
+{{</* badge content="徽章" color="blue" */>}}
+{{</* badge content="徽章" color="green" */>}}
+{{</* badge content="徽章" color="yellow" */>}}
+{{</* badge content="徽章" color="amber" */>}}
+{{</* badge content="徽章" color="orange" */>}}
+{{</* badge content="徽章" color="red" */>}}
 ```
 
-效果：
+{{< badge content="徽章" border=false >}} &nbsp;
-
+{{< badge content="徽章" color="purple" border=false >}} &nbsp;
-{{< badge content="信息" type="info" >}} &nbsp;
+{{< badge content="徽章" color="indigo" border=false >}} &nbsp;
-{{< badge content="警告" type="warning" >}} &nbsp;
+{{< badge content="徽章" color="blue" border=false >}} &nbsp;
-{{< badge content="错误" type="error" >}}
+{{< badge content="徽章" color="green" border=false >}} &nbsp;
-
+{{< badge content="徽章" color="yellow" border=false >}} &nbsp;
-带链接和图标：
+{{< badge content="徽章" color="amber" border=false >}} &nbsp;
+{{< badge content="徽章" color="orange" border=false >}}&nbsp;
+{{< badge content="徽章" color="red" border=false >}}&nbsp;
 
 ```
-{{</* badge content="版本发布" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
+{{</* badge content="徽章" border=false */>}}
+{{</* badge content="徽章" color="purple" border=false */>}}
+{{</* badge content="徽章" color="indigo" border=false */>}}
+{{</* badge content="徽章" color="blue" border=false */>}}
+{{</* badge content="徽章" color="green" border=false */>}}
+{{</* badge content="徽章" color="yellow" border=false */>}}
+{{</* badge content="徽章" color="amber" border=false */>}}
+{{</* badge content="徽章" color="orange" border=false */>}}
+{{</* badge content="徽章" color="red" border=false */>}}
 ```
 
-效果：
+#### 变体
 
-{{< badge content="版本发布" link="https://github.com/imfing/hextra/releases" icon="github" >}}
+{{< badge content="徽章" icon="sparkles" >}}&nbsp;
+{{< badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" >}}&nbsp;
+
+```
+{{</* badge content="徽章" icon="sparkles" */>}}
+{{</* badge content="Releases" link="https://github.com/imfing/hextra/releases" icon="github" */>}}
+```
+
+### 选项
+
+| 姓名        | 描述                                                                                                 |
+|-----------|----------------------------------------------------------------------------------------------------|
+| `content` | 徽章的文字。                                                                                             |
+| `link`    | 徽章的链接。                                                                                             |
+| `icon`    | 徽章的图标。                                                                                             |
+| `color`   | 徽章的颜色。 <br/> `gray` (默认), `purple`, `indigo`, `blue`, `green`, `yellow`, `amber`, `orange`, `red`. |
+| `class`   | 徽章的等级。                                                                                             |
+| `border`  | 添加或删除边框 (默认：true).                                                                                 |
 
 ## YouTube
 

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

@@ -25,7 +25,7 @@ title: مراحل
 
 ## نحوه استفاده
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   لطفاً توجه داشته باشید که این شورتکد **فقط برای محتوای Markdown** طراحی شده است.
   اگر محتوای HTML یا شورتکدهای دیگر را به عنوان محتوای مرحله قرار دهید، ممکن است به درستی نمایش داده نشود.
 {{< /callout >}}

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

@@ -25,7 +25,7 @@ title: ステップ
 
 ## 使い方
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   このショートコードは **Markdown コンテンツ専用** であることに注意してください。
   HTML コンテンツや他のショートコードをステップの内容として含めると、期待通りにレンダリングされない場合があります。
 {{< /callout >}}

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

@@ -25,7 +25,7 @@ This is the third step.
 
 ## Usage
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   Please note that this shortcode is intended **only for Markdown content**.
   If you put HTML content or other shortcodes as step content, it may not render as expected.
 {{< /callout >}}

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

@@ -25,7 +25,7 @@ title: 步骤
 
 ## 使用方法
 
-{{< callout emoji="ℹ️" >}}
+{{< callout type="warning" >}}
   请注意，此短代码**仅适用于Markdown内容**。
   如果在步骤内容中放入HTML或其他短代码，可能无法按预期渲染。
 {{< /callout >}}

exampleSite/hugo.yaml

@@ -29,16 +29,28 @@ languages:
     languageDirection: rtl
     weight: 2
     title: هگزترا
+    params:
+      banner:
+        message: |
+          هگزترا **v0.11** منتشر شد! 🎉 [تازه‌ها را ببینید]({{% relref `blog/v0.11` %}})
   ja:
     languageName: 日本語
-    languageCode: ja
+    languageCode: ja-JP
     weight: 3
     title: Hextra
+    params:
+      banner:
+        message: |
+          Hextra **v0.11** がリリースされました！🎉 [新着情報はこちら]({{% relref `blog/v0.11` %}})
   zh-cn:
     languageName: 简体中文
     languageCode: zh-CN
     weight: 4
     title: Hextra
+    params:
+      banner:
+        message: |
+          Hextra **v0.11** 发布啦！🎉 查看[更新内容]({{% relref `blog/v0.11` %}})
 
 module:
   hugoVersion:
@@ -85,6 +97,9 @@ menu:
       name: Showcase
       pageRef: /showcase
       weight: 5
+      params:
+        type: link
+        icon: collection
     - name: Search
       weight: 6
       params:
@@ -98,6 +113,9 @@ menu:
       name: Development ↗
       url: https://imfing.github.io/hextra/versions/latest/
       parent: versions
+      params:
+        type: link
+        icon: beaker
     - identifier: v0.9
       name: v0.9 ↗
       url: https://imfing.github.io/hextra/versions/v0.9/
@@ -121,6 +139,13 @@ menu:
 params:
   description: Modern, responsive, batteries-included Hugo theme for creating beautiful static websites.
 
+  externalLinkDecoration: true
+
+  banner:
+    key: 'announcement-v0.11'
+    message: |
+      Hextra **v0.11** is here! 🎉 Discover [what's new]({{% relref `blog/v0.11` %}})
+
   navbar:
     displayTitle: true
     displayLogo: true

exampleSite/hugo_stats.json

@@ -83,6 +83,7 @@
       "[counter-reset:step]",
       "[hyphens:auto]",
       "[word-break:break-word]",
+      "asciinema-player",
       "base",
       "chroma",
       "col-align-l",
@@ -97,6 +98,8 @@
       "footnotes",
       "frac-line",
       "hextra-badge",
+      "hextra-banner",
+      "hextra-banner-close-button",
       "hextra-card",
       "hextra-card-icon",
       "hextra-card-image",
@@ -143,6 +146,7 @@
       "hextra-tabs-panel",
       "hextra-tabs-toggle",
       "hextra-theme-toggle",
+      "hextra-theme-toggle-options",
       "hextra-toc",
       "hide-tail",
       "highlight",
@@ -156,6 +160,7 @@
       "hx:active:shadow-gray-200",
       "hx:active:shadow-sm",
       "hx:align-[-2.5px]",
+      "hx:align-baseline",
       "hx:align-middle",
       "hx:align-text-bottom",
       "hx:appearance-none",
@@ -183,11 +188,13 @@
       "hx:bg-green-100",
       "hx:bg-indigo-100",
       "hx:bg-neutral-50",
+      "hx:bg-neutral-900",
       "hx:bg-orange-50",
       "hx:bg-primary-100",
       "hx:bg-primary-400",
       "hx:bg-primary-600",
       "hx:bg-primary-700/5",
+      "hx:bg-purple-100",
       "hx:bg-red-100",
       "hx:bg-transparent",
       "hx:bg-white",
@@ -204,6 +211,7 @@
       "hx:border-green-200",
       "hx:border-indigo-200",
       "hx:border-orange-100",
+      "hx:border-purple-200",
       "hx:border-red-200",
       "hx:border-t",
       "hx:border-transparent",
@@ -256,6 +264,7 @@
       "hx:dark:bg-primary-300/10",
       "hx:dark:bg-primary-400/10",
       "hx:dark:bg-primary-600",
+      "hx:dark:bg-purple-900/30",
       "hx:dark:bg-red-900/30",
       "hx:dark:bg-yellow-700/30",
       "hx:dark:block",
@@ -268,6 +277,7 @@
       "hx:dark:border-neutral-700",
       "hx:dark:border-neutral-800",
       "hx:dark:border-orange-400/30",
+      "hx:dark:border-purple-200/30",
       "hx:dark:border-red-200/30",
       "hx:dark:border-white/10",
       "hx:dark:border-yellow-200/30",
@@ -313,8 +323,10 @@
       "hx:dark:text-neutral-400",
       "hx:dark:text-orange-300",
       "hx:dark:text-primary-600",
+      "hx:dark:text-purple-200",
       "hx:dark:text-red-200",
       "hx:dark:text-slate-100",
+      "hx:dark:text-white",
       "hx:dark:text-yellow-200",
       "hx:dark:to-gray-400",
       "hx:data-[state=closed]:hidden",
@@ -334,6 +346,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",
@@ -358,6 +371,7 @@
       "hx:group-[.copied]/copybtn:hidden",
       "hx:group-data-[theme=dark]:hidden",
       "hx:group-data-[theme=light]:hidden",
+      "hx:group-data-[theme=system]:hidden",
       "hx:group-hover/code:opacity-100",
       "hx:group-hover:underline",
       "hx:group-open:before:rotate-90",
@@ -365,6 +379,7 @@
       "hx:group/copybtn",
       "hx:grow",
       "hx:h-0",
+      "hx:h-10",
       "hx:h-16",
       "hx:h-2",
       "hx:h-3.5",
@@ -449,6 +464,7 @@
       "hx:max-md:[transform:translate3d(0,-100%,0)]",
       "hx:max-md:hidden",
       "hx:max-md:min-h-[340px]",
+      "hx:max-md:sticky",
       "hx:max-sm:grid-cols-1",
       "hx:max-w-6xl",
       "hx:max-w-[50%]",
@@ -468,8 +484,10 @@
       "hx:md:h-[calc(100vh-var(--navbar-height)-var(--menu-height))]",
       "hx:md:hidden",
       "hx:md:inline-block",
+      "hx:md:inline-flex",
       "hx:md:justify-start",
       "hx:md:max-h-[min(calc(100vh-5rem-env(safe-area-inset-bottom)),400px)]",
+      "hx:md:mr-0",
       "hx:md:pt-12",
       "hx:md:px-12",
       "hx:md:self-start",
@@ -534,6 +552,7 @@
       "hx:pr-[calc(env(safe-area-inset-right)-1.5rem)]",
       "hx:pr-[max(env(safe-area-inset-left),1.5rem)]",
       "hx:pr-[max(env(safe-area-inset-right),1.5rem)]",
+      "hx:print:[display:none]",
       "hx:print:bg-transparent",
       "hx:print:hidden",
       "hx:pt-4",
@@ -545,6 +564,7 @@
       "hx:px-3",
       "hx:px-4",
       "hx:px-6",
+      "hx:px-8",
       "hx:py-1",
       "hx:py-1.5",
       "hx:py-12",
@@ -586,6 +606,7 @@
       "hx:rtl:pr-5",
       "hx:rtl:pr-6",
       "hx:rtl:pr-8",
+      "hx:rtl:rotate-270",
       "hx:rtl:text-left",
       "hx:scroll-my-6",
       "hx:scroll-py-6",
@@ -630,7 +651,9 @@
       "hx:text-lg",
       "hx:text-orange-800",
       "hx:text-primary-800",
+      "hx:text-purple-900",
       "hx:text-red-900",
+      "hx:text-slate-50",
       "hx:text-slate-900",
       "hx:text-sm",
       "hx:text-transparent",
@@ -653,6 +676,7 @@
       "hx:transition-transform",
       "hx:underline",
       "hx:underline-offset-2",
+      "hx:w-10",
       "hx:w-2",
       "hx:w-3.5",
       "hx:w-4",

i18n/en.yaml

@@ -7,11 +7,12 @@ dark: "Dark"
 editThisPage: "Edit this page on GitHub →"
 lastUpdated: "Last updated on"
 light: "Light"
+next: "Next"
 noResultsFound: "No results found."
 onThisPage: "On this page"
-tags: "Tags"
 poweredBy: "Powered by Hextra"
+previous: "Prev"
 readMore: "Read more →"
 searchPlaceholder: "Search..."
-previous: "Prev"
+system: "System"
-next: "Next"
+tags: "Tags"

i18n/es.yaml

@@ -1,14 +1,18 @@
 backToTop: "Subir al inicio"
 changeLanguage: "Cambiar idioma"
 changeTheme: "Cambiar tema"
+copyCode: "Copiar código"
 copyright: "© 2025 Proyecto Hextra."
 dark: "Oscuro"
 editThisPage: "Edita esta página en GitHub →"
 lastUpdated: "Última actualización"
 light: "Claro"
+next: "Siguiente"
 noResultsFound: "No hubo resultados."
 onThisPage: "En esta página"
-tags: "Etiquetas"
 poweredBy: "Con tecnología de Hextra"
+previous: "Anterior"
 readMore: "Leer más →"
 searchPlaceholder: "Buscar..."
+system: "Sistema"
+tags: "Etiquetas"

i18n/fr.yaml

@@ -1,14 +1,18 @@
 backToTop: "Revenir en haut"
 changeLanguage: "Changer la langue"
 changeTheme: "Thème d'affichage"
+copyCode: "Copier le code"
 copyright: "© 2025 Hextra Project."
 dark: "Sombre"
 editThisPage: "Modifier cette page sur GitHub →"
 lastUpdated: "Dernière modification"
 light: "Clair"
+next: "Suivant"
 noResultsFound: "Pas de résultats trouvés"
 onThisPage: "Sur cette page"
-tags: "Étiquettes"
 poweredBy: "Propulsé par Hextra"
+previous: "Précdent"
 readMore: "Lire plus →"
 searchPlaceholder: "Rechercher..."
+system: "Système"
+tags: "Étiquettes"

i18n/zh-cn.yaml

@@ -1,6 +1,7 @@
 backToTop: "返回顶部"
 changeLanguage: "切换语言"
 changeTheme: "切换主题"
+copyCode: "复制代码"
 copyright: "© 2025 Hextra Project."
 dark: "深色"
 editThisPage: "在 GitHub 上编辑此页 →"
@@ -14,3 +15,4 @@ readMore: "更多 →"
 searchPlaceholder: "搜索文档..."
 previous: "上一页"
 next: "下一页"
+system: "跟随系统"

layouts/_markup/render-link.html

@@ -12,5 +12,14 @@
 {{- end -}}
 
 {{- with . -}}
-  <a href="{{ $dest | safeURL }}" {{ with .Title }}title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }}target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
+{{- $isExternal := strings.HasPrefix .Destination "http" -}}
+<a href="{{ $dest | safeURL }}"
+   {{- with .Title -}}title="{{ . }}"{{- end -}}
+   {{- if $isExternal -}}target="_blank" rel="noopener"{{- end -}}
+>
+  {{- .Text | safeHTML -}}
+  {{- if and .Page.Site.Params.externalLinkDecoration $isExternal -}}
+    {{- partial "utils/icon.html" (dict "name" "arrow-up-right" "attributes" `class="hx:inline hx:rtl:rotate-270 hx:align-baseline" height="1em"`) -}}
+  {{- end -}}
+</a>
 {{- end -}}

layouts/_partials/banner.html

@@ -0,0 +1,18 @@
+{{- if site.Params.banner }}
+<div class="hextra-banner hx:max-md:sticky hx:top-0 hx:z-20 hx:px-6 hx:text-center hx:text-slate-50 hx:dark:text-white hx:bg-neutral-900 hx:dark:bg-neutral-800 hx:print:[display:none]">
+  <div class="hx:relative hx:flex hx:items-center hx:justify-center hx:font-medium hx:text-sm hx:py-2.5">
+    {{- with partial "custom/banner.html" . -}}
+      {{- . -}}
+    {{- else -}}
+      <div style="white-space: pre-wrap" class="hx:px-8">
+        {{- site.Params.banner.message | default "🎉 Welcome! This is a banner message." | .RenderString -}}
+      </div>
+    {{- end -}}
+    <button
+      class="hextra-banner-close-button hx:cursor-pointer hx:absolute hx:right-0 hx:text-white hx:font-bold hx:leading-none hx:hover:opacity-75 hx:transition hx:w-10 hx:h-10 hx:-mr-2 hx:md:mr-0 hx:flex hx:items-center hx:justify-center"
+    >
+      {{- partial "utils/icon.html" (dict "name" "x" "attributes" "height=16") -}}
+    </button>
+  </div>
+</div>
+{{- end -}}

layouts/_partials/breadcrumb.html

@@ -1,6 +1,8 @@
-{{- if (default true .Params.breadcrumbs) }}
+{{- $page := .page -}}
+{{- $enable := .enable -}}
+{{- if (default $enable $page.Params.breadcrumbs) -}}
   <div class="hx:mt-1.5 hx:flex hx:items-center hx:gap-1 hx:overflow-hidden hx:text-sm hx:text-gray-500 hx:dark:text-gray-400 hx:contrast-more:text-current">
-    {{- range .Ancestors.Reverse }}
+    {{- range $page.Ancestors.Reverse }}
       {{- if not .IsHome }}
         <div class="hx:whitespace-nowrap hx:transition-colors hx:min-w-[24px] hx:overflow-hidden hx:text-ellipsis hx:hover:text-gray-900 hx:dark:hover:text-gray-100">
           <a href="{{ .RelPermalink }}">{{- partial "utils/title" . -}}</a>
@@ -9,7 +11,7 @@
       {{ end -}}
     {{ end -}}
     <div class="hx:whitespace-nowrap hx:transition-colors hx:font-medium hx:text-gray-700 hx:contrast-more:font-bold hx:contrast-more:text-current hx:dark:text-gray-100 hx:contrast-more:dark:text-current">
-      {{- partial "utils/title" . -}}
+      {{- partial "utils/title" $page -}}
     </div>
   </div>
 {{ end -}}

layouts/_partials/components/analytics/analytics.html

@@ -0,0 +1,19 @@
+{{- if hugo.IsProduction -}}
+
+<!-- Google Analytics -->
+{{- if .Site.Config.Services.GoogleAnalytics.ID }}
+  <link rel="preconnect" href="https://www.googletagmanager.com" crossorigin />
+  {{ partial "google-analytics.html" . -}}
+{{- end }}
+
+<!-- Umami -->
+{{- if .Site.Params.analytics.umami -}}
+  {{ partial "components/analytics/umami.html" . }}
+{{- end }}
+
+<!-- Matomo -->
+{{- if .Site.Params.analytics.matomo -}}
+  {{ partial "components/analytics/matomo.html" . }}
+{{- end }}
+
+{{- end }}

layouts/_partials/components/analytics/google-analytics.html

@@ -0,0 +1,13 @@
+{{- with site.Config.Services.GoogleAnalytics.ID }}
+<!-- Global site tag (gtag.js) - Google Analytics -->
+<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    dataLayer.push(arguments);
+  }
+  gtag("js", new Date());
+
+  gtag("config", "{{ . }}");
+</script>
+{{ end -}}

layouts/_partials/components/analytics/matomo.html

@@ -0,0 +1,19 @@
+{{- /*
+Matomo Analytics.
+https://developer.matomo.org/guides/tracking-javascript-guide
+*/ -}}
+
+<!-- Matomo -->
+<script type="text/javascript">
+  var _paq = window._paq = window._paq || [];
+  _paq.push(['trackPageView']);
+  _paq.push(['enableLinkTracking']);
+  (function() {
+    var u="//{{ .serverURL }}/";
+    _paq.push(['setTrackerUrl', u+'matomo.php']);
+    _paq.push(['setSiteId', {{ .websiteID }}]);
+    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
+    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
+  })();
+</script>
+<!-- End Matomo Code -->

layouts/_partials/components/analytics/umami.html

@@ -0,0 +1,57 @@
+{{- /*
+Umami Analytics
+https://umami.is/docs/tracker-configuration
+*/ -}}
+
+{{- with .Site.Params.analytics.umami -}}
+
+{{- if not .serverURL }}
+  {{- errorf "Missing Umami 'serverURL' configuration. See TODO" -}}
+{{- end -}}
+
+{{- if not .websiteID }}
+  {{- errorf "Missing Umami 'websiteID' configuration. See TODO" -}}
+{{- end -}}
+
+{{- $attributes := newScratch -}}
+
+{{- $attributes.SetInMap "umami" "src" (printf "%s/%s" .serverURL (.scriptName | default "umami.js")) -}}
+{{- $attributes.SetInMap "umami" "data-website-id" .websiteID -}}
+
+{{- if .hostURL -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-host-url */ -}}
+  {{- $attributes.SetInMap "umami" "data-host-url" .hostURL -}}
+{{- end -}}
+
+{{- if .autoTrack -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-auto-track */ -}}
+  {{- $attributes.SetInMap "umami" "data-auto-track" .autoTrack -}}
+{{- end -}}
+
+{{- if .tag -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-tag */ -}}
+  {{- $attributes.SetInMap "umami" "data-tag" .tag -}}
+{{- end -}}
+
+{{- if .excludeSearch -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-exclude-search */ -}}
+  {{- $attributes.SetInMap "umami" "data-exclude-search" .excludeSearch -}}
+{{- end -}}
+
+{{- if .excludeHash -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-exclude-hash */ -}}
+  {{- $attributes.SetInMap "umami" "data-exclude-hash" .excludeHash -}}
+{{- end -}}
+
+{{- if .doNotTrack -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-do-not-track */ -}}
+  {{- $attributes.SetInMap "umami" "data-do-not-track" .doNotTrack -}}
+{{- end -}}
+
+{{- if .domains -}}
+  {{- /* https://umami.is/docs/tracker-configuration#data-domains */ -}}
+  {{- $attributes.SetInMap "umami" "data-domains" .domains -}}
+{{- end -}}
+
+<script async defer {{ range $k, $v := ($attributes.Get "umami" ) }} {{ (printf `%s=%q` $k $v) | safeHTMLAttr }}{{- end -}}></script>
+{{- end -}}

layouts/_partials/components/giscus.html

@@ -1,40 +1,47 @@
-{{- $lang := site.Language.LanguageCode | default `en` -}}
+{{- $lang := site.Language.Lang | default `en` -}}
+{{- if hasPrefix $lang "zh" -}}
+  {{- /* See: https://github.com/giscus/giscus/tree/main/locales */}}
+  {{- $lang = site.Language.LanguageCode | default `zh-CN` -}}
+{{- end -}}
 
 {{- with site.Params.comments.giscus -}}
 <script>
-  /*
-   * "preferred color scheme" theme in giscus works using "prefers-color-scheme" in media query.
-   * but, hugo's theme switch function works by using "color-theme" in local storage.
-   * This solution was created with reference to:
-   * https://github.com/giscus/giscus/issues/336#issuecomment-1214366281
-  */
-  function getHugoTheme() {
-    return localStorage.getItem("color-theme");
-  }
-  
   function getGiscusTheme() {
-    let giscusTheme = "{{ (string .theme) | default `light` }}";
+    const giscusTheme = '{{ .theme }}';
-    let hugoTheme = getHugoTheme();
+    if (giscusTheme === 'light' || giscusTheme === 'dark') {
-    if(hugoTheme == 'light') {
+      return giscusTheme;
-      return giscusTheme.replace('dark', 'light');
     }
-    if(hugoTheme == 'dark') {
+
-      return giscusTheme.replace('light', 'dark');
+    const hugoTheme = localStorage.getItem("color-theme");
+    if (hugoTheme === 'light' || hugoTheme === 'dark') {
+      return hugoTheme;
     }
-    return giscusTheme;
+
+    if (hugoTheme === 'system') {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+
+    const defaultTheme = '{{ site.Params.theme.default }}';
+    if (defaultTheme === 'light' || defaultTheme === 'dark') {
+      return defaultTheme;
+    }
+
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
   }
 
   function setGiscusTheme() {
-    function sendMessage(message) {
+    const iframe = document.querySelector('iframe.giscus-frame');
-      const iframe = document.querySelector('iframe.giscus-frame');
+    if (!iframe) return;
-      if (!iframe) return;
+
-      iframe.contentWindow.postMessage({ giscus: message }, 'https://giscus.app');
+    const msg = {
-    }
+      giscus: {
-    sendMessage({
+        setConfig: {
-      setConfig: {
+          theme: getGiscusTheme(),
-        theme: getGiscusTheme(),
+        },
       },
-    });
+    }
+
+    iframe.contentWindow.postMessage(msg, 'https://giscus.app');
   }
 
   document.addEventListener('DOMContentLoaded', function () {
@@ -58,17 +65,21 @@
     // Dynamically create script tag
     const giscusScript = document.createElement("script");
     Object.entries(giscusAttributes).forEach(([key, value]) => giscusScript.setAttribute(key, value));
-    document.getElementById('giscus').appendChild(giscusScript);
+    // Random hash id to avoid conflicts with titles inside pages.
+    document.getElementById('giscus-hextra-bb112b9f807c37c1752e5da6a1652a29').appendChild(giscusScript);
+
+    // Listen for system theme changes
+    window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", setGiscusTheme);
 
     // Update giscus theme when theme switcher is clicked
-    const toggles = document.querySelectorAll(".hextra-theme-toggle");
+    const themeToggleOptions = document.querySelectorAll(".hextra-theme-toggle-options p");
-    if (toggles) {
+    if (themeToggleOptions) {
-      toggles.forEach(toggle => toggle.addEventListener('click', setGiscusTheme));
+      themeToggleOptions.forEach(toggle => toggle.addEventListener('click', setGiscusTheme));
     }
   });
 </script>
 
-<div id="giscus"></div>
+<div id="giscus-hextra-bb112b9f807c37c1752e5da6a1652a29"></div>
 {{- else -}}
   {{ warnf "giscus is not configured" }}
 {{- end -}}

layouts/_partials/components/github-style-alert.html

@@ -2,33 +2,44 @@
 {{- $alertType := .alertType -}}
 {{- $alertTitle := .alertTitle -}}
 
-{{- $icons := dict
+{{- $styles := newScratch -}}
-  "note" "information-circle"
+{{- $styles.Set "default" (dict
-  "tip" "light-bulb"
+  "icon" "light-bulb"
-  "important" "information-circle"
+  "style" "hx:border-green-200 hx:bg-green-100 hx:text-green-900 hx:dark:border-green-200/30 hx:dark:bg-green-900/30 hx:dark:text-green-200"
-  "warning" "exclamation"
+  )
-  "caution" "exclamation-circle"
+-}}
+{{- $styles.Set "note" (dict
+  "icon" "information-circle"
+  "style" "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"
+  )
+-}}
+{{- $styles.Set "tip" (dict
+  "icon" "light-bulb"
+  "style" "hx:border-green-200 hx:bg-green-100 hx:text-green-900 hx:dark:border-green-200/30 hx:dark:bg-green-900/30 hx:dark:text-green-200"
+  )
+-}}
+{{- $styles.Set "important" (dict
+  "icon" "information-circle"
+  "style" "hx:border-purple-200 hx:bg-purple-100 hx:text-purple-900 hx:dark:border-purple-200/30 hx:dark:bg-purple-900/30 hx:dark:text-purple-200"
+  )
+-}}
+{{- $styles.Set "warning" (dict
+  "icon" "exclamation"
+  "style" "hx:border-amber-200 hx:bg-amber-100 hx:text-amber-900 hx:dark:border-amber-200/30 hx:dark:bg-amber-900/30 hx:dark:text-amber-200"
+  )
+-}}
+{{- $styles.Set "caution" (dict
+  "icon" "exclamation-circle"
+  "style" "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"
+  )
 -}}
 
-{{- $icon := index $icons $alertType -}}
+{{- $style := or ($styles.Get $alertType) ($styles.Get "default") -}}
 {{- $title := or $alertTitle (or (i18n $alertType) (title $alertType)) -}}
 
-{{- $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" }}
+<div class="hx:overflow-x-auto hx:mt-6 hx:flex hx:flex-col hx:rounded-lg hx:border hx:py-4 hx:px-4 hx:border-gray-200 hx:contrast-more:border-current hx:contrast-more:dark:border-current {{ $style.style }}">
-
-{{- $alertClasses := dict
-  "note" "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"
-  "tip" "hx:border-green-200 hx:bg-green-100 hx:text-green-900 hx:dark:border-green-200/30 hx:dark:bg-green-900/30 hx:dark:text-green-200"
-  "important" "hx:border-indigo-200 hx:bg-indigo-100 hx:text-indigo-900 hx:dark:border-indigo-200/30 hx:dark:bg-indigo-900/30 hx:dark:text-indigo-200"
-  "warning" "hx:border-amber-200 hx:bg-amber-100 hx:text-amber-900 hx:dark:border-amber-200/30 hx:dark:bg-amber-900/30 hx:dark:text-amber-200"
-  "caution" "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 := index $alertClasses $alertType | default $defaultClass -}}
-
-
-<div class="hx:overflow-x-auto hx:mt-6 hx:flex hx:flex-col hx:rounded-lg hx:border hx:py-4 hx:px-4 hx:border-gray-200 hx:contrast-more:border-current hx:contrast-more:dark:border-current {{ $class }}">
   <p class="hx:flex hx:items-center hx:font-medium">
-    {{- with $icon -}}
+    {{- with $style.icon -}}
       {{- partial "utils/icon.html" (dict "name" . "attributes" `height=16px class="hx:inline-block hx:align-middle hx:mr-2"`) -}}
     {{- end -}}
     {{- $title -}}

layouts/_partials/google-analytics.html

@@ -1,13 +1,2 @@
-{{- with site.Config.Services.GoogleAnalytics.ID }}
+{{- /* Only for compatibility. */ -}}
-  <!-- Global site tag (gtag.js) - Google Analytics -->
+{{- partial "components/analytics/google-analytics.html" . -}}
-  <script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
-  <script>
-    window.dataLayer = window.dataLayer || [];
-    function gtag() {
-      dataLayer.push(arguments);
-    }
-    gtag("js", new Date());
-
-    gtag("config", "{{ . }}");
-  </script>
-{{ end -}}

layouts/_partials/head.html

@@ -53,32 +53,32 @@
     <link href="{{ $customCss.RelPermalink }}" rel="stylesheet" />
   {{- end }}
 
-  <!-- Google Analytics -->
+  {{ partial "components/analytics/analytics.html" . }}
-  {{- if and hugo.IsProduction .Site.Config.Services.GoogleAnalytics.ID }}
-    <link rel="preconnect" href="https://www.googletagmanager.com" crossorigin />
-    {{ partial "google-analytics.html" . -}}
-  {{- end }}
 
   <script>
-    /* Initialize light/dark mode */
+    // The section must not be in the theme.js file because it can create a quick flash (switch between light and dark).
-    const defaultTheme = '{{ site.Params.theme.default | default `system`}}';
 
-    const setDarkTheme = () => {
+    function setTheme(theme) {
-      document.documentElement.classList.add("dark");
+      document.documentElement.classList.remove("light", "dark");
-      document.documentElement.style.colorScheme = "dark";
-    }
-    const setLightTheme = () => {
-      document.documentElement.classList.remove("dark");
-      document.documentElement.style.colorScheme = "light";
-    }
 
-    if ("color-theme" in localStorage) {
+      if (theme !== "light" && theme !== "dark") {
-      localStorage.getItem("color-theme") === "dark" ? setDarkTheme() : setLightTheme();
+       theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-    } else {
-      defaultTheme === "dark" ? setDarkTheme() : setLightTheme();
-      if (defaultTheme === "system") {
-        window.matchMedia("(prefers-color-scheme: dark)").matches ? setDarkTheme() : setLightTheme();
       }
+
+      document.documentElement.classList.add(theme);
+      document.documentElement.style.colorScheme = theme;
+    }
+
+    setTheme("color-theme" in localStorage ? localStorage.getItem("color-theme") : '{{ site.Params.theme.default | default `system`}}')
+
+  </script>
+
+  <script>
+    // The section must not be in the banner.js file because it can create a quick flash.
+
+    if (localStorage.getItem('{{ site.Params.banner.key | default `banner-closed` }}')) {
+      document.documentElement.style.setProperty("--hextra-banner-height", "0px");
+      document.documentElement.classList.add("hextra-banner-hidden");
     }
   </script>
 

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

@@ -0,0 +1,76 @@
+{{- $currentPage := .currentPage -}}
+{{- $link := .link -}}
+{{- $item := .item -}}
+{{- $icon := .icon -}}
+{{- $external := .external -}}
+
+{{- $active := or ($currentPage.HasMenuCurrent "main" $item) ($currentPage.IsMenuCurrent "main" $item) -}}
+{{- $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" -}}
+
+{{- if $item.HasChildren -}}
+{{- /* Dropdown menu for items with children */ -}}
+<div class="hx:relative hx:hidden hx:md:inline-block">
+  <button
+    title="{{ or (T $item.Identifier) $item.Name | safeHTML }}"
+    data-state="closed"
+    class="hextra-nav-menu-toggle hx:cursor-pointer hx:text-sm hx:contrast-more:text-gray-700 hx:contrast-more:dark:text-gray-100 hx:relative hx:-ml-2 hx:whitespace-nowrap hx:p-2 hx:flex hx:items-center hx:gap-1 {{ $activeClass }}"
+    type="button"
+    aria-label="{{ or (T $item.Identifier) $item.Name | safeHTML }}"
+  >
+    {{- if $icon -}}
+    <span class="hx:inline-flex hx:items-center">
+      {{- partial "utils/icon" (dict "name" $icon "attributes" `height="1em" class="hx:inline-block"`) -}}
+    </span>
+    {{- end -}}
+    <span class="hx:text-center">
+      {{- or (T $item.Identifier) $item.Name | safeHTML -}}
+    </span>
+    {{- partial "utils/icon.html" (dict "name" "chevron-down" "attributes" "height=12 class=\"hx:transition-transform hx:duration-200 hx:ease-in-out\"") -}}
+  </button>
+  <ul
+    class="hextra-nav-menu-items hx:hidden hx:z-20 hx:max-h-64 hx:overflow-auto hx:rounded-md hx:ring-1 hx:ring-black/5 hx:bg-white hx:py-1 hx:text-sm hx:shadow-lg hx:dark:ring-white/20 hx:dark:bg-neutral-800"
+    style="min-width: 100px;"
+  >
+    {{ range $item.Children }}
+    {{- $link := .URL -}}
+    {{- $external := strings.HasPrefix $link "http" -}}
+    {{- with .PageRef -}}
+    {{- if hasPrefix . "/" -}}
+    {{- $link = relLangURL (strings.TrimPrefix "/" .) -}}
+    {{- end -}}
+    {{- end -}}
+    <li class="hextra-nav-menu-item hx:flex hx:flex-col">
+      <a
+        href="{{ $link }}"
+        {{ if $external }}target="_blank" rel="noreferrer"{{ end }}
+        class="hx:text-gray-600 hx:hover:text-gray-800 hx:dark:text-gray-400 hx:dark:hover:text-gray-200 hx:relative hx:cursor-pointer hx:whitespace-nowrap hx:py-1.5 hx:transition-colors hx:ltr:pl-3 hx:ltr:pr-9 hx:rtl:pr-3 hx:rtl:pl-9 hx:flex hx:items-center hx:gap-1"
+      >
+        {{- if and (eq .Params.type "link") .Params.icon -}}
+        <span class="hx:inline-flex hx:items-center">
+          {{- partial "utils/icon" (dict "name" .Params.icon "attributes" `height="1em" class="hx:inline-block"`) -}}
+        </span>
+        {{- end -}}
+        {{- or (T .Identifier) .Name | safeHTML -}}
+      </a>
+    </li>
+    {{- end -}}
+  </ul>
+</div>
+{{- else -}}
+{{- /* Regular menu item without children */ -}}
+<a
+  title="{{ or (T .Identifier) .Name | safeHTML }}"
+  href="{{ $link }}"
+  {{ if $external }}target="_blank" rel="noreferrer"{{ end }}
+  class="hx:text-sm hx:contrast-more:text-gray-700 hx:contrast-more:dark:text-gray-100 hx:relative hx:-ml-2 hx:hidden hx:whitespace-nowrap hx:p-2 hx:md:inline-flex hx:items-center hx:gap-1 {{ $activeClass }}"
+>
+  {{- if $icon -}}
+  <span class="hx:inline-flex hx:items-center">
+    {{- partial "utils/icon" (dict "name" $icon "attributes" `height="1em" class="hx:inline-block"`) -}}
+  </span>
+  {{- end -}}
+  <span class="hx:text-center">
+    {{- or (T $item.Identifier) $item.Name | safeHTML -}}
+  </span>
+</a>
+{{- end -}}

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
@@ -29,72 +31,29 @@
           {{- end -}}
         {{- end -}}
 
-        {{/* Display icon menu item */}}
+        {{- if eq .Params.type "link" -}}
-        {{- if .Params.icon -}}
+          {{- partial "navbar-link.html" (dict "currentPage" $currentPage "link" $link "external" $external "item" . "icon" .Params.icon) -}}
+        {{- else if eq .Params.type "theme-toggle" -}}
+          {{- partial "theme-toggle.html" (dict "iconHeight" $iconHeight "hideLabel" (not .Params.label) "iconHeight" $iconHeight "location" "top" "class" "hx:p-2") -}}
+        {{- 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 if .Params.icon -}}
+          {{- /* Display icon menu item */ -}}
+          {{- if not $link -}}{{ warnf "Icon menu item '%s' has no URL" .Name }}{{- end -}}
           {{- $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 -}}
-          {{- $active := or ($currentPage.HasMenuCurrent "main" .) ($currentPage.IsMenuCurrent "main" .) -}}
+          {{- partial "navbar-link.html" (dict "currentPage" $currentPage "link" $link "external" $external "item" .) -}}
-          {{- $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" -}}
-
-          {{- if .HasChildren -}}
-            {{/* Dropdown menu for items with children */}}
-            <div class="hx:relative hx:hidden hx:md:inline-block">
-              <button
-                title="{{ or (T .Identifier) .Name | safeHTML }}"
-                data-state="closed"
-                class="hextra-nav-menu-toggle hx:cursor-pointer hx:text-sm hx:contrast-more:text-gray-700 hx:contrast-more:dark:text-gray-100 hx:relative hx:-ml-2 hx:whitespace-nowrap hx:p-2 hx:flex hx:items-center hx:gap-1 {{ $activeClass }}"
-                type="button"
-                aria-label="{{ or (T .Identifier) .Name | safeHTML }}"
-              >
-                <span class="hx:text-center">{{ or (T .Identifier) .Name | safeHTML }}</span>
-                {{- partial "utils/icon.html" (dict "name" "chevron-down" "attributes" "height=12 class=\"hx:transition-transform hx:duration-200 hx:ease-in-out\"") -}}
-              </button>
-              <ul
-                class="hextra-nav-menu-items hx:hidden hx:z-20 hx:max-h-64 hx:overflow-auto hx:rounded-md hx:ring-1 hx:ring-black/5 hx:bg-white hx:py-1 hx:text-sm hx:shadow-lg hx:dark:ring-white/20 hx:dark:bg-neutral-800"
-                style="min-width: 100px;"
-              >
-                {{ range .Children }}
-                  {{- $link := .URL -}}
-                  {{- $external := strings.HasPrefix $link "http" -}}
-                  {{- with .PageRef -}}
-                    {{- if hasPrefix . "/" -}}
-                      {{- $link = relLangURL (strings.TrimPrefix "/" .) -}}
-                    {{- end -}}
-                  {{- end -}}
-                  <li class="hextra-nav-menu-item hx:flex hx:flex-col">
-                    <a
-                      href="{{ $link }}"
-                      {{ if $external }}target="_blank" rel="noreferrer"{{ end }}
-                      class="hx:text-gray-600 hx:hover:text-gray-800 hx:dark:text-gray-400 hx:dark:hover:text-gray-200 hx:relative hx:cursor-pointer hx:whitespace-nowrap hx:py-1.5 hx:transition-colors hx:ltr:pl-3 hx:ltr:pr-9 hx:rtl:pr-3 hx:rtl:pl-9"
-                    >
-                      {{- or (T .Identifier) .Name | safeHTML -}}
-                    </a>
-                  </li>
-                {{- end -}}
-              </ul>
-            </div>
-          {{- else -}}
-            {{/* Regular menu item without children */}}
-            <a
-              title="{{ or (T .Identifier) .Name | safeHTML }}"
-              href="{{ $link }}"
-              {{ if $external }}target="_blank" rel="noreferrer"{{ end }}
-              class="hx:text-sm hx:contrast-more:text-gray-700 hx:contrast-more:dark:text-gray-100 hx:relative hx:-ml-2 hx:hidden hx:whitespace-nowrap hx:p-2 hx:md:inline-block {{ $activeClass }}"
-            >
-              <span class="hx:text-center">{{ or (T .Identifier) .Name | safeHTML }}</span>
-            </a>
-          {{- end -}}
         {{- end -}}
       {{- end -}}
     {{- end -}}
 
 
     <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/scripts.html

@@ -8,3 +8,8 @@
 {{- if (.Store.Get "hasMermaid") -}}
   {{- partial "scripts/mermaid.html" . -}}
 {{- end -}}
+
+{{/* Asciinema */}}
+{{- if (.Store.Get "hasAsciinema") -}}
+  {{- partial "scripts/asciinema.html" . -}}
+{{- end -}}

layouts/_partials/scripts/asciinema.html

@@ -0,0 +1,114 @@
+{{- /* Asciinema */ -}}
+
+{{- $asciinemaBase := "" -}}
+{{- $useDefaultCdn := true -}}
+{{- with site.Params.asciinema.base -}}
+  {{- $asciinemaBase = . -}}
+  {{- $useDefaultCdn = false -}}
+{{- end -}}
+
+{{- $asciinemaJsAsset := "" -}}
+{{- with site.Params.asciinema.js -}}
+  {{- $asciinemaJsAsset = . -}}
+{{- end -}}
+
+{{- $asciinemaCssAsset := "" -}}
+{{- with site.Params.asciinema.css -}}
+  {{- $asciinemaCssAsset = . -}}
+{{- end -}}
+
+{{- /* If only js/css is set without base, use local asset loading */ -}}
+{{- if and $useDefaultCdn (or (ne $asciinemaJsAsset "") (ne $asciinemaCssAsset "")) -}}
+  {{- $useDefaultCdn = false -}}
+{{- end -}}
+
+{{- /* Set default CDN base if needed */ -}}
+{{- if $useDefaultCdn -}}
+  {{- $asciinemaBase = "https://cdn.jsdelivr.net/npm/asciinema-player@latest/dist/bundle" -}}
+{{- end -}}
+
+{{- $isRemoteBase := or (strings.HasPrefix $asciinemaBase "http://") (strings.HasPrefix $asciinemaBase "https://") -}}
+{{- $minSuffix := cond hugo.IsProduction ".min" "" -}}
+
+{{- /* CSS retrieval: get raw CSS from either local asset or remote, then process */ -}}
+{{- if $isRemoteBase -}}
+  {{- $cssPath := cond (ne $asciinemaCssAsset "") $asciinemaCssAsset "asciinema-player.css" -}}
+  {{- $asciinemaCssUrl := printf "%s/%s" $asciinemaBase $cssPath -}}
+  {{- with try (resources.GetRemote $asciinemaCssUrl) -}}
+    {{- with .Err -}}
+      {{- errorf "Could not retrieve Asciinema css file from %s. Reason: %s." $asciinemaCssUrl . -}}
+    {{- else with .Value -}}
+      {{- with resources.Copy "css/asciinema-player.css" . -}}
+        {{- $asciinemaCss := . | fingerprint -}}
+        <link rel="stylesheet" href="{{ $asciinemaCss.RelPermalink }}" integrity="{{ $asciinemaCss.Data.Integrity }}" crossorigin="anonymous" />
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- else if $asciinemaCssAsset -}}
+  {{- with resources.Get $asciinemaCssAsset -}}
+    {{- $asciinemaCss := . | fingerprint -}}
+    <link rel="stylesheet" href="{{ $asciinemaCss.RelPermalink }}" integrity="{{ $asciinemaCss.Data.Integrity }}" crossorigin="anonymous" />
+  {{- else -}}
+    {{- errorf "Asciinema css asset not found at %q" $asciinemaCssAsset -}}
+  {{- end -}}
+{{- end -}}
+
+{{- /* JS retrieval: get raw JS from either local asset or remote, then process */ -}}
+{{- if $isRemoteBase -}}
+  {{- $jsPath := cond (ne $asciinemaJsAsset "") $asciinemaJsAsset (printf "asciinema-player%s.js" $minSuffix) -}}
+  {{- $asciinemaJsUrl := printf "%s/%s" $asciinemaBase $jsPath -}}
+  {{- with try (resources.GetRemote $asciinemaJsUrl) -}}
+    {{- with .Err -}}
+      {{- errorf "Could not retrieve Asciinema js file from %s. Reason: %s." $asciinemaJsUrl . -}}
+    {{- else with .Value -}}
+      {{- with resources.Copy (printf "js/asciinema-player%s.js" $minSuffix) . -}}
+        {{- $asciinemaJs := . | fingerprint -}}
+        <script defer src="{{ $asciinemaJs.RelPermalink }}" integrity="{{ $asciinemaJs.Data.Integrity }}" crossorigin="anonymous"></script>
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- else if $asciinemaJsAsset -}}
+  {{- with resources.Get $asciinemaJsAsset -}}
+    {{- $asciinemaJs := . | fingerprint -}}
+    <script defer src="{{ $asciinemaJs.RelPermalink }}" integrity="{{ $asciinemaJs.Data.Integrity }}" crossorigin="anonymous"></script>
+  {{- else -}}
+    {{- errorf "Asciinema js asset not found at %q" $asciinemaJsAsset -}}
+  {{- end -}}
+{{- end -}}
+
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    // Fix play button position issue
+    const style = document.createElement("style");
+    style.textContent = `
+      .ap-player .ap-overlay-start .ap-play-button span > svg {
+        display: inline;
+      }
+    `;
+    document.head.appendChild(style);
+    // Initialize asciinema players
+    document.querySelectorAll(".asciinema-player").forEach((el) => {
+      const castFile = el.dataset.castFile;
+      const theme = el.dataset.theme || "asciinema";
+      const speed = parseFloat(el.dataset.speed) || 1;
+      const autoplay = el.dataset.autoplay === "true";
+      const loop = el.dataset.loop === "true";
+      const poster = el.dataset.poster || "";
+      const markers = el.dataset.markers ? JSON.parse(el.dataset.markers) : [];
+
+      // Create asciinema player
+      if (window.AsciinemaPlayer) {
+        window.AsciinemaPlayer.create(castFile, el, {
+          theme: theme,
+          speed: speed,
+          autoplay: autoplay,
+          loop: loop,
+          poster: poster || undefined,
+          markers: markers.length > 0 ? markers : undefined,
+          controls: true,  // Always show user controls (bottom control bar)
+          idleTimeLimit: 2,  // Limit terminal inactivity to 2 seconds (compress pauses longer than 2s)
+        });
+      }
+    });
+  });
+</script>

layouts/_partials/scripts/core.html

@@ -1,4 +1,6 @@
+{{- $jsSwitcherMenu := resources.Get "js/switcher-menu.js" -}}
 {{- $jsTheme := resources.Get "js/theme.js" | resources.ExecuteAsTemplate "theme.js" . -}}
+{{- $jsBanner := resources.Get "js/banner.js" | resources.ExecuteAsTemplate "banner.js" . -}}
 {{- $jsMenu := resources.Get "js/menu.js" -}}
 {{- $jsTabs := resources.Get "js/tabs.js" -}}
 {{- $jsLang := resources.Get "js/lang.js" -}}
@@ -10,7 +12,7 @@
 {{- $jsTocScroll := resources.Get "js/toc-scroll.js" -}}
 {{- $jsFavicon := resources.Get "js/favicon.js" | resources.ExecuteAsTemplate "favicon.js" . -}}
 
-{{- $scripts := slice $jsTheme $jsMenu $jsCodeCopy $jsTabs $jsLang $jsNavMenu $jsFileTree $jsSidebar $jsBackToTop $jsTocScroll $jsFavicon | resources.Concat "js/main.js" -}}
+{{- $scripts := slice $jsSwitcherMenu $jsTheme $jsBanner $jsMenu $jsCodeCopy $jsTabs $jsLang $jsNavMenu $jsFileTree $jsSidebar $jsBackToTop $jsTocScroll $jsFavicon | resources.Concat "js/main.js" -}}
 {{- if hugo.IsProduction -}}
   {{- $scripts = $scripts | minify | fingerprint -}}
 {{- end -}}