chore(scripts): generic way to build scripts (#829)

* chore: move core scripts

* chore: extract head scripts

.github/CONTRIBUTING.md

@@ -31,7 +31,7 @@ Use [Conventional Commits][conventional commits] message to make it easier to un
 
 Similar to contributing code, you can also contribute to the documentation by submitting a pull request.
 
-The documentation site is located in the [`exampleSite`](../exampleSite/) folder.
+The documentation site is located in the [`docs`](../docs/) folder.
 You can make changes to the documentation and create a pull request. A preview of the new documentation will be automatically generated and displayed in the pull request comment via [Netlify][netlify deploy preview].
 
 ### 💬 GitHub Discussions
@@ -71,7 +71,7 @@ npm i
 
 - [`assets`](../assets/): CSS styles and JavaScript files.
 - [`data`](../data/): The theme data files. Now only contains the `icons.yaml` file.
-- [`exampleSite`](../exampleSite/): The documentation site for the theme.
+- [`docs`](../docs/): The documentation site for the theme.
 - [`i18n`](../i18n/): The theme translation files.
 - [`layouts`](../layouts/): The theme layouts.
 - [`static`](../static/): The static files for the theme. For example, the favicon and the site logo.
@@ -84,7 +84,7 @@ Please refer to the [Hugo documentation][hugo] for more information.
 npm run dev:theme
 ```
 
-It will start the Hugo server on `http://localhost:1313/` for the `exampleSite` content.
+It starts the Hugo server on `http://localhost:1313/` for the `docs` content.
 
 ### Compile the styles
 

CLAUDE.md

@@ -84,12 +84,12 @@ assets/
 
 ### Example Site Development
 
-The `exampleSite/` directory serves as both documentation and testing ground:
+The `docs/` directory serves as both documentation and testing ground:
 
 - Test new features here before releasing
-- Configuration examples in `exampleSite/hugo.yaml` showing multi-language setup
+- Configuration examples in `docs/hugo.yaml` showing multi-language setup
 - Content examples demonstrate all theme capabilities
-- Run from exampleSite with: `hugo server --themesDir=../..`
+- Run from docs with: `hugo server --themesDir=../..`
 
 ### CSS Development Workflow
 
@@ -115,7 +115,7 @@ The `exampleSite/` directory serves as both documentation and testing ground:
 
 ### Key Configuration Files
 
-- `exampleSite/hugo.yaml` - Example Hugo configuration with multi-language setup
+- `docs/hugo.yaml` - Example Hugo configuration with multi-language setup
 - `postcss.config.mjs` - PostCSS configuration for CSS processing
 - `package.json` - Node.js dependencies and build scripts
 - `taskfile.yaml` - Task runner configuration
@@ -155,7 +155,7 @@ The `exampleSite/` directory serves as both documentation and testing ground:
 
 ### Testing & Quality Assurance
 
-- Test all changes in `exampleSite/` before releasing
+- Test all changes in `docs/` before releasing
 - Use `npm run dev:theme` for theme development with hot reloading
 - Format code with `npx prettier --write .` before committing
 - Verify multi-language functionality across supported languages

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/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 */
 }
 
@@ -48,6 +49,7 @@ body {
 @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/core/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/core/lang.js

@@ -0,0 +1,26 @@
+(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';
+
+      toggleMenu(switcher);
+    });
+  });
+
+  window.addEventListener("resize", () => languageSwitchers.forEach(resizeMenu))
+
+  // Dismiss language switcher when clicking outside
+  document.addEventListener('click', (e) => {
+    if (e.target.closest('.hextra-language-switcher') === null) {
+      languageSwitchers.forEach((switcher) => {
+        switcher.dataset.state = 'closed';
+        const optionsElement = switcher.nextElementSibling;
+        optionsElement.classList.add('hx:hidden');
+      });
+    }
+  });
+})();

assets/js/core/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/core/theme.js

@@ -0,0 +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");
+
+  function applyTheme(theme) {
+    theme = themes.includes(theme) ? theme : "system";
+
+    themeToggleButtons.forEach((btn) => btn.parentElement.dataset.theme = theme );
+
+    localStorage.setItem("color-theme", theme);
+  }
+
+  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((toggler) => {
+    toggler.addEventListener("click", function (e) {
+      e.preventDefault();
+
+      toggleMenu(toggler);
+    });
+  });
+
+  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", () => {
+    if (localStorage.getItem("color-theme") === "system") {
+      setTheme("system");
+    }
+  });
+})();

assets/js/head/banner.js

@@ -0,0 +1,6 @@
+// The section must not be in the banner.js (body) 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");
+}

assets/js/head/theme.js

@@ -0,0 +1,14 @@
+// The section must not be in the theme.js (body) file because it can create a quick flash (switch between light and dark).
+
+function setTheme(theme) {
+  document.documentElement.classList.remove("light", "dark");
+
+  if (theme !== "light" && theme !== "dark") {
+    theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+
+  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`}}')

assets/js/lang.js

@@ -1,49 +0,0 @@
-(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 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 isRTL = document.body.dir === 'rtl'
-
-      // Stuck on the left side of the switcher.
-      let translateX = switcherRect.left;
-
-      if (isOnTop && !isRTL || !isOnTop && isRTL) {
-        // Stuck on the right side of the switcher.
-        translateX = switcherRect.right - optionsElement.clientWidth;
-      }
-
-      // Stuck on the top of the switcher.
-      let translateY = switcherRect.top - window.innerHeight - 15;
-
-      if (isOnTop) {
-        // Stuck on the bottom of the switcher.
-        translateY = switcherRect.top - window.innerHeight + 180;
-      }
-
-      optionsElement.style.transform = `translate3d(${translateX}px, ${translateY}px, 0)`;
-    });
-  });
-
-  // Dismiss language switcher when clicking outside
-  document.addEventListener('click', (e) => {
-    if (e.target.closest('.hextra-language-switcher') === null) {
-      languageSwitchers.forEach((switcher) => {
-        switcher.dataset.state = 'closed';
-        const optionsElement = switcher.nextElementSibling;
-        optionsElement.classList.add('hx:hidden');
-      });
-    }
-  });
-})();

assets/js/theme.js

@@ -1,51 +0,0 @@
-// Light / Dark theme toggle
-(function () {
-  const defaultTheme = '{{ site.Params.theme.default | default `system`}}'
-
-  const themeToggleButtons = document.querySelectorAll(".hextra-theme-toggle");
-
-  // Change the icons of the buttons based on previous settings or system theme
-  if (
-    localStorage.getItem("color-theme") === "dark" ||
-    (!("color-theme" in localStorage) &&
-      ((window.matchMedia("(prefers-color-scheme: dark)").matches && defaultTheme === "system") || defaultTheme === "dark"))
-  ) {
-    themeToggleButtons.forEach((el) => el.dataset.theme = "dark");
-  } else {
-    themeToggleButtons.forEach((el) => el.dataset.theme = "light");
-  }
-
-  // Add click event handler to the buttons
-  themeToggleButtons.forEach((el) => {
-    el.addEventListener("click", function () {
-      if (localStorage.getItem("color-theme")) {
-        if (localStorage.getItem("color-theme") === "light") {
-          setDarkTheme();
-          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";
-    });
-  });
-
-  // Listen for system theme changes
-  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
-    if (defaultTheme === "system" && !("color-theme" in localStorage)) {
-      e.matches ? setDarkTheme() : setLightTheme();
-      themeToggleButtons.forEach((el) =>
-        el.dataset.theme = document.documentElement.classList.contains("dark") ? "dark" : "light"
-      );
-    }
-  });
-})();

build.sh

@@ -7,16 +7,17 @@ BASE_URL=${1:-"http://localhost:1313"}
 echo "Using base URL: $BASE_URL"
 
 # Version configuration - modify these arrays to specify versions to build
-# Format: "ref:display_name" (ref can be tag, branch, or commit hash, display name is what will appear in URL)
-MAIN_VERSION="v0.10.1:latest"
+# MAIN_VERSION format: "ref:display_name:source_dir"
+# VERSIONS format: "ref:display_name:source_dir" where source_dir is either "docs" or "exampleSite"
+MAIN_VERSION="v0.11.1:latest:docs"
 VERSIONS=(
-  "main:latest" # latest version always builds from main
-  "v0.9.6:v0.9"
-  "v0.8.6:v0.8"
+  "main:latest:docs" # latest version always builds from main
+  "v0.10.2:v0.10:exampleSite"
+  "v0.9.6:v0.9:exampleSite"
 )
 
 # Parse main version
-IFS=':' read -r MAIN_REF MAIN_NAME <<< "$MAIN_VERSION"
+IFS=':' read -r MAIN_REF MAIN_NAME MAIN_DIR <<< "$MAIN_VERSION"
 
 # Ensure clean public directory
 rm -rf public
@@ -29,13 +30,13 @@ GIT_HASH=$(git rev-parse --short HEAD)
 echo "Building main site from $MAIN_REF (commit: $GIT_HASH)"
 hugo \
   --minify \
-  --themesDir=../.. --source=exampleSite \
+  --themesDir=../.. --source=$MAIN_DIR \
   --baseURL "$BASE_URL/" \
   --destination=../public
 
 # Build all versions
 for VERSION in "${VERSIONS[@]}"; do
-  IFS=':' read -r REF NAME <<< "$VERSION"
+  IFS=':' read -r REF NAME DIR <<< "$VERSION"
 
   git checkout $REF
   GIT_HASH=$(git rev-parse --short HEAD)
@@ -44,7 +45,7 @@ for VERSION in "${VERSIONS[@]}"; do
   mkdir -p "public/versions/$NAME"
   hugo \
     --minify \
-    --themesDir=../.. --source=exampleSite \
+    --themesDir=../.. --source=$DIR \
     --baseURL "$BASE_URL/versions/$NAME/" \
     --destination="../public/versions/$NAME"
 done

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>

dev.toml

@@ -1,4 +1,4 @@
-# Theme development config for exampleSite
+# Theme development config for documentation site
 # https://gohugo.io/configuration/build/#cache-busters
 [build]
   [build.buildStats]

docs/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

docs/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

docs/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

docs/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
+

docs/content/docs/advanced/customization.fa.md

@@ -221,14 +221,14 @@ hugo gen chromastyles --style=github
 می‌توانید اسکریپت‌های سفارشی را به انتهای head برای هر صفحه با افزودن فایل زیر اضافه کنید:
 
 ```
-layouts/partials/custom/head-end.html
+layouts/_partials/custom/head-end.html
 ```
 
 ## بخش اضافی سفارشی در پاورقی
 
-می‌توانید بخش اضافی در پاورقی با ایجاد یک فایل `layouts/partials/custom/footer.html` در سایت خود اضافه کنید.
+می‌توانید بخش اضافی در پاورقی با ایجاد یک فایل `layouts/_partials/custom/footer.html` در سایت خود اضافه کنید.
 
-```html {filename="layouts/partials/custom/footer.html"}
+```html {filename="layouts/_partials/custom/footer.html"}
 <!-- عنصر پاورقی شما اینجا -->
 ```
 

docs/content/docs/advanced/customization.ja.md

@@ -221,14 +221,14 @@ hugo gen chromastyles --style=github
 すべてのページのheadの終わりにカスタムスクリプトを追加するには、以下のファイルを作成します:
 
 ```
-layouts/partials/custom/head-end.html
+layouts/_partials/custom/head-end.html
 ```
 
 ## フッターへのカスタムセクション追加
 
-フッターに追加セクションを追加するには、サイト内に`layouts/partials/custom/footer.html`ファイルを作成します。
+フッターに追加セクションを追加するには、サイト内に`layouts/_partials/custom/footer.html`ファイルを作成します。
 
-```html {filename="layouts/partials/custom/footer.html"}
+```html {filename="layouts/_partials/custom/footer.html"}
 <!-- ここにフッター要素を追加 -->
 ```
 

docs/content/docs/advanced/customization.md

@@ -221,14 +221,14 @@ To override the default syntax highlighting theme, we can add the generated styl
 You may add custom scripts to the end of the head for every page by adding the following file:
 
 ```
-layouts/partials/custom/head-end.html
+layouts/_partials/custom/head-end.html
 ```
 
 ## Custom Extra Section in Footer
 
-You can add extra section in the footer by creating a file `layouts/partials/custom/footer.html` in your site.
+You can add extra section in the footer by creating a file `layouts/_partials/custom/footer.html` in your site.
 
-```html {filename="layouts/partials/custom/footer.html"}
+```html {filename="layouts/_partials/custom/footer.html"}
 <!-- Your footer element here -->
 ```
 

docs/content/docs/advanced/customization.zh-cn.md

@@ -221,14 +221,14 @@ hugo gen chromastyles --style=github
 您可以通过添加以下文件在每个页面的 head 末尾添加自定义脚本：
 
 ```
-layouts/partials/custom/head-end.html
+layouts/_partials/custom/head-end.html
 ```
 
 ## 自定义页脚额外部分
 
-您可以通过在站点中创建 `layouts/partials/custom/footer.html` 文件来添加页脚的额外部分。
+您可以通过在站点中创建 `layouts/_partials/custom/footer.html` 文件来添加页脚的额外部分。
 
-```html {filename="layouts/partials/custom/footer.html"}
+```html {filename="layouts/_partials/custom/footer.html"}
 <!-- 您的页脚元素放在这里 -->
 ```
 

docs/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

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

@@ -7,7 +7,7 @@ tags:
 
 Hugo تنظیمات خود را از فایل `hugo.yaml` در ریشه سایت شما می‌خواند.
 فایل پیکربندی جایی است که می‌توانید تمام جنبه‌های سایت خود را تنظیم کنید.
-برای آشنایی جامع با تنظیمات موجود و بهترین روش‌ها، فایل پیکربندی این سایت [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) را در GitHub بررسی کنید.
+برای آشنایی جامع با تنظیمات موجود و بهترین روش‌ها، فایل پیکربندی این سایت [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) را در GitHub بررسی کنید.
 
 <!--more-->
 
@@ -416,4 +416,4 @@ outputs:
 سایر ویژگی‌های Open Graph می‌توانند فقط یک مقدار داشته باشند.
 به عنوان مثال، این صفحه یک تگ `og:image` (که تصویری برای پیش‌نمایش در اشتراک‌گذاری‌های اجتماعی پیکربندی می‌کند) و یک تگ `og:audio` دارد.
 
-```yaml {filename
+```yaml {filename

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

@@ -7,7 +7,7 @@ tags:
 
 Hugo はサイトのルートにある `hugo.yaml` から設定を読み込みます。
 この設定ファイルであなたのサイトのあらゆる側面を設定できます。
-利用可能な設定項目とベストプラクティスを網羅的に理解するには、GitHub 上のこのサイトの設定ファイル [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) を参照してください。
+利用可能な設定項目とベストプラクティスを網羅的に理解するには、GitHub 上のこのサイトの設定ファイル [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) を参照してください。
 
 <!--more-->
 
@@ -422,4 +422,4 @@ params:
   images:
     - "/img/config-image.jpg"
   audio: "config-talk.mp3"
-```
+```

docs/content/docs/guide/configuration.md

@@ -7,7 +7,7 @@ tags:
 
 Hugo reads its configuration from `hugo.yaml` in the root of your Hugo site.
 The config file is where you can configure all aspects of your site.
-Check out the config file for this site [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) on GitHub to get a comprehensive idea of available settings and best practices.
+Check out the config file for this site [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) on GitHub to get a comprehensive idea of available settings and best practices.
 
 <!--more-->
 
@@ -58,20 +58,27 @@ There are different types of menu items:
      params:
        type: search
    ```
-4. Icon
+4. Icon Only
    ```yaml
    - name: GitHub
      params:
        icon: github
    ```
-5. Theme Toggle
+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
    ```
-6. Language Switcher
+7. Language Switcher
    ```yaml
     - name: Language Switcher
       params:
@@ -157,6 +164,21 @@ menu:
       weight: 3
 ```
 
+### Hiding
+
+Hiding the sidebar can be done using front matter:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+sidebar:
+  hide: true
+---
+```
+
+This will hide the main sidebar from the page, freeing up space for the main content of the page.
+
+
 ## Right Sidebar
 
 ### Table of Contents
@@ -387,6 +409,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`:
@@ -410,16 +471,66 @@ The llms.txt file is automatically generated from your content structure and mak
 
 ### Open Graph
 
-To add [Open Graph](https://ogp.me/) metadata to a page, add values in the frontmatter params.
+To add [Open Graph](https://ogp.me/) metadata, you can:
+- add values in the front-matter params of a page
+- or add values in the Hugo configuration file
 
 As a page can have multiple `image` and `video` tags, place their values in an array.
 Other Open Graph properties can have only one value.
-For example, this page has an `og:image` tag (which configures an image to preview on social shares) and an `og:audio` tag.
 
-```yaml {filename="content/docs/guide/configuration.md"}
-title: "Configuration"
+{{< tabs items="Page Level, Global Level" >}}
+{{< tab >}}
+
+```md {filename="mypage.md"}
+---
+title: "My Page"
 params:
   images:
-    - "/img/config-image.jpg"
-  audio: "config-talk.mp3"
+    - "/images/image01.jpg"
+  audio: "podcast02.mp3"
+  videos:
+    - "video01.mp4"
+---
+
+Page content.
+```
+{{< /tab >}}
+{{< tab >}}
+```yaml {filename="hugo.yaml"}
+params:
+  images:
+    - "/images/image01.jpg"
+  audio: "podcast02.mp3"
+  videos:
+    - "video01.mp4"
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### 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
 ```

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

@@ -7,7 +7,7 @@ tags:
 
 Hugo 从站点根目录的 `hugo.yaml` 读取配置。
 配置文件可用来调整站点的所有方面。
-查看本网站的示例配置文件 [`exampleSite/hugo.yaml`](https://github.com/imfing/hextra/blob/main/exampleSite/hugo.yaml) 以全面了解可用设置和最佳实践。
+查看本网站的示例配置文件 [`docs/hugo.yaml`](https://github.com/imfing/hextra/blob/main/docs/hugo.yaml) 以全面了解可用设置和最佳实践。
 
 <!--more-->
 
@@ -422,4 +422,4 @@ params:
   images:
     - "/img/config-image.jpg"
   audio: "config-talk.mp3"
-```
+```

docs/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 >}}

docs/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 >}}

docs/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 >}}

docs/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)

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

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