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/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`}}')

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

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/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/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-->
 
@@ -164,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
@@ -456,19 +471,41 @@ 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
 

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"
-```
+```