chore: add rel="me" attribute to Mastodon navbar icon (#243)

* Add rel="me" attribute to Mastodon navbar icon

The rel="me" attribute enables verified links on the linked Mastodon profile

* Set $rel based on icon name

.devcontainer/devcontainer.json

@@ -3,7 +3,7 @@
   "features": {
     "ghcr.io/devcontainers/features/hugo:1": {
       "extended": true,
-      "version": "0.116.1"
+      "version": "0.119.0"
     },
     "ghcr.io/devcontainers/features/node:1": {}
   },

.github/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contribute to Hextra
+
+👋 Thank you for being interested in contributing to Hextra! As an open source project, we welcome contributions of many forms including bug reports, feature requests, documentation improvements, and code contributions.
+
+<!-- omit in toc -->
+## Table of Contents
+
+- [Guidelines](#guidelines)
+  - [Contributing Code](#contributing-code)
+  - [Contributing Documentation](#contributing-documentation)
+  - [💬 GitHub Discussions](#-github-discussions)
+  - [GitHub Issues](#github-issues)
+- [Development](#development)
+  - [Local development setup](#local-development-setup)
+  - [Project structure](#project-structure)
+  - [Start the development server](#start-the-development-server)
+  - [Compile the styles](#compile-the-styles)
+
+
+## Guidelines
+
+### Contributing Code
+
+To contribute, please follow the ["Fork and Pull Request"][fork and pull] workflow：
+
+Fork the repository, make your changes, and then submit a pull request.
+Please make sure to include a description of the changes you made and why you made them.
+Use [Conventional Commits][conventional commits] message to make it easier to understand the changes you made.
+
+### Contributing Documentation
+
+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.
+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
+
+We’re using [Discussions][discussions] as a place to connect with other members using Hextra:
+
+- Ask questions you’re wondering about.
+- Share ideas.
+- Engage with other users.
+
+### GitHub Issues
+
+If you find a bug or have a feature request, please [open an issue][issues].
+
+Please make sure to include a description of the bug or feature you are requesting. If you are reporting a bug, please include steps to reproduce the bug.
+
+We recommend that you search existing [issues][issues] or discussions before opening a new one to prevent duplicates.
+
+## Development
+
+> **Note**
+> You can start developing on [GitHub Codespaces][open in codespaces] or use [devcontainer][devcontainer] locally without installing any dependencies.
+
+### Local development setup
+
+- [Hugo][hugo] >= v0.115.0 (extended version)
+- [Node.js][nodejs]
+- [Go][go]
+
+Install dependencies:
+
+```bash
+npm i
+```
+
+### Project structure
+
+- [`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.
+- [`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.
+
+Please refer to the [Hugo documentation][hugo] for more information.
+
+### Start the development server
+
+```bash
+npm run dev:theme
+```
+
+It will start the Hugo server on `http://localhost:1313/` for the `exampleSite` content.
+
+### Compile the styles
+
+For development preview, we compile the Tailwind CSS styles on the fly. But for production, we need to compile the styles first.
+
+```bash
+npm run build:css
+```
+
+It will compile the Tailwind CSS styles and generate the `assets/css/compiled/main.css` file.
+
+<!--links-->
+
+[fork and pull]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
+[conventional commits]: https://www.conventionalcommits.org
+[issues]: https://github.com/imfing/hextra/issues
+[discussions]: https://github.com/imfing/hextra/discussions
+[nodejs]: https://nodejs.org/en/
+[hugo]: https://gohugo.io/
+[go]: https://golang.org/doc/install
+[devcontainer]: https://code.visualstudio.com/docs/devcontainers/containers
+[open in codespaces]: https://codespaces.new/imfing/hextra
+[netlify deploy preview]: https://docs.netlify.com/site-deploys/deploy-previews/

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Description**
+
+<!-- Provide a clear and concise description of the bug -->
+
+**Steps To Reproduce**
+
+1. 
+2. 
+3. 
+
+**Expected Behavior**
+
+<!-- What should have happened? -->
+
+**Actual Behavior**
+
+<!-- What happened instead? -->
+
+**Screenshots**
+
+<!-- If applicable, add screenshots to help explain your problem -->
+
+**Environment**
+
+- Hugo Version: [e.g., 0.85.0]
+- Browser/OS: [e.g., Chrome, MacOS]
+- Theme Version: [e.g., v2.0]
+
+**Additional Context**
+
+<!-- Add any other context about the problem here -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Feature Description**
+
+<!-- Provide a clear and concise description of the feature -->
+
+**Problem/Solution**
+
+<!-- What problem will this feature solve? Or what new capability will it add? -->
+
+**Alternatives Considered**
+
+<!-- Have you considered any alternative solutions or workarounds? -->
+
+**Additional Context**
+
+<!-- Add any other context or screenshots about the feature request here -->

.github/workflows/pages.yml

@@ -34,7 +34,9 @@ jobs:
       HUGO_VERSION: 0.117.0
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
       - name: Setup Go
         uses: actions/setup-go@v4
         with:
@@ -42,7 +44,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v2
         with:
-          hugo-version: '0.117.0'
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: Build with Hugo
         env:
@@ -53,7 +55,7 @@ jobs:
           hugo \
             --minify \
             --themesDir=../.. --source=exampleSite \
-            --baseURL "https://imfing.github.io/hextra/"
+            --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
   "editor.tabSize": 2,
-  "css.customData": [".vscode/tailwind.json"]
+  "css.customData": [".vscode/tailwind.json"],
+  "markdown.extension.toc.levels": "2..6"
 }

README.md

@@ -1,15 +1,26 @@
-<p align="center">
+<div align="center">
   <h1 align="center">Hextra</h1>
   <p align="center">Modern, responsive, batteries-included Hugo theme for creating beautiful static websites.</p>
-</p>
+
+Demo → [imfing.github.io/hextra](https://imfing.github.io/hextra/)
+</div>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/5097752/263550533-c18343ca-3848-4230-b5c0-ee989d7916da.png">
+  <img alt="Hextra" src="https://user-images.githubusercontent.com/5097752/263550528-663599f9-17a1-4686-b5c4-3da233b5034d.png">
+</picture>
+
+<div align="right">
+<a href="https://github.com/imfing/hextra/actions/workflows/pages.yml"><img alt="GitHub Actions Status" src="https://github.com/imfing/hextra/actions/workflows/pages.yml/badge.svg"></a> <a href="https://app.netlify.com/sites/hugo-hextra/deploys"><img alt="Netlify Status" src="https://api.netlify.com/api/v1/badges/61d6e55a-2447-487e-b59f-c9537e5df175/deploy-status"></a>
+</div>
 
 ## Features
 
 - **Beautiful Design** - Inspired by Nextra, Hextra utilizes Tailwind CSS to offer a modern design that makes your site look outstanding.
-- **Responsive Layout and Dark Mode** - It looks great on all devices, from mobile, tablet to desktop. Dark mode is also supported to accomodate various lighting conditions.
-- **Fast and Lightweight** - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No Javascript or Node.js are needed to use it.
-- **Full-text Search** - Built-in offline full-text search powered by FlexSearch, no additional configuration required.
-- **Battery-included** - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcumbs, pagination, sidebar navigation and more are all automatically generated.
+- **Responsive Layout and Dark Mode** - It looks great on all devices, from mobile to desktop. Dark mode is also supported to accommodate various lighting conditions.
+- **Fast and Lightweight** - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No JavaScript or Node.js are needed to use it.
+- **Full-text Search** - Built-in offline full-text search powered by FlexSearch, no extra configuration required.
+- **Battery-included** - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcrumbs, pagination, sidebar navigation and more are all automatically generated.
 - **Multi-language and SEO Ready** - Multi-language sites made easy with Hugo's multilingual mode. Out-of-the-box support is included for SEO tags, Open Graph, and Twitter Cards.
 
 ## Quick Start
@@ -20,13 +31,16 @@ Using the [Hextra Starter Template](https://github.com/imfing/hextra-starter-tem
 
 The template repository also includes a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) for deploying your website to GitHub Pages.
 
+<img alt="Hextra Starter Template" src="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" width=600/>
+
 ### Usage
 
 Refer to the [documentation](https://imfing.github.io/hextra/docs) for more information.
 
 ## Contributing
 
-This project is actively under development. Contributions are welcome!
+Contributions are welcome.
+Check out the [contributing guide](.github/CONTRIBUTING.md) to get started.
 
 ## License
 

README.zh-cn.md

@@ -0,0 +1,44 @@
+<div align="center">
+  <h1 align="center">Hextra</h1>
+  <p align="center">用于创建美观的静态站点的现代化, 响应式, 功能强大的 Hugo 主题.</p>
+
+演示 → [imfing.github.io/hextra](https://imfing.github.io/hextra/)
+</div>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/5097752/263550533-c18343ca-3848-4230-b5c0-ee989d7916da.png">
+  <img alt="Hextra" src="https://user-images.githubusercontent.com/5097752/263550528-663599f9-17a1-4686-b5c4-3da233b5034d.png">
+</picture>
+
+<div align="right">
+<a href="https://github.com/imfing/hextra/actions/workflows/pages.yml"><img alt="GitHub Actions Status" src="https://github.com/imfing/hextra/actions/workflows/pages.yml/badge.svg"></a> <a href="https://app.netlify.com/sites/hugo-hextra/deploys"><img alt="Netlify Status" src="https://api.netlify.com/api/v1/badges/61d6e55a-2447-487e-b59f-c9537e5df175/deploy-status"></a>
+</div>
+
+## 特性
+
+- **美观的设计** - 受 Nextra 的启发，Hextra 利用 Tailwind CSS 提供现代化的设计，使您的网站看起来美观有加.
+- **响应式布局和深色模式支持** - 在任何设备上看起来都足够美观, 无论是手机, 平板电脑或者电脑. 深色模式的支持使 Hextra 可以应对各种照明环境.
+- **快速且轻量** - 由 Hugo 强力支持, Hugo 是一个快如闪电的静态站点生成器, 这一切都只需一个可执行文件, Hextra 始终保持最小化, 无需 Javascript 或者 Node.js.
+- **全文搜索** - 集成了 Flexsearch 的全文搜索, 无需额外的配置.
+- **网站中的瑞士军刀** - Markdown, 代码高亮, LaTex 数学公式, diagrams 图表和 Shortcodes 都可以用于丰富你的内容. 目录, 面包屑导航, 分页, 侧边栏等均由 Hextra 自动生成。
+- **多语言和 SEO Ready** - Hugo 的多语言模式使得构建多语言网站更简单. 具有 SEO tags, Open Graph, 和 Twitter Cards 等诸多开箱即用的功能.
+
+## 快速开始
+
+### 使用模板
+
+使用 [Hextra stater template](https://github.com/imfing/hextra-starter-template) 是使用 Hextra 主题的最简单方法. 点击仓库页面上的 `Use this template` 按钮开始使用.
+
+此仓库中包含一个 [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) 来帮助你免费在 GitHub Pages 上自动构建和部署网站.
+
+### 使用
+
+转至[文档](https://imfing.github.io/hextra/zh-cn/docs)
+
+## 贡献
+
+该项目正在积极开发中. 欢迎贡献!
+
+## 许可证
+
+[MIT License](./LICENSE)

assets/css/components/code-copy.css

@@ -0,0 +1,7 @@
+@supports (
+  (-webkit-backdrop-filter: blur(1px)) or (backdrop-filter: blur(1px))
+) {
+  .code-copy-btn {
+    @apply backdrop-blur-md bg-opacity-[.85] dark:bg-opacity-80;
+  }
+}

assets/css/components/navbar.css

@@ -4,6 +4,14 @@ nav {
   }
 }
 
+@supports (
+  (-webkit-backdrop-filter: blur(1px)) or (backdrop-filter: blur(1px))
+) {
+  .nav-container-blur {
+    @apply backdrop-blur-md bg-white/[.85] dark:!bg-dark/80;
+  }
+}
+
 .hamburger-menu svg {
   g {
     @apply origin-center;

assets/css/components/scrollbar.css

@@ -0,0 +1,21 @@
+.hextra-scrollbar {
+  scrollbar-width: thin; /* Firefox */
+  scrollbar-color: oklch(55.55% 0 0 / 40%) transparent; /* Firefox */
+
+  scrollbar-gutter: stable;
+  &::-webkit-scrollbar {
+    @apply w-3 h-3;
+  }
+  &::-webkit-scrollbar-track {
+    @apply bg-transparent;
+  }
+  &::-webkit-scrollbar-thumb {
+    @apply rounded-[10px];
+  }
+  &:hover::-webkit-scrollbar-thumb {
+    border: 3px solid transparent;
+    background-color: var(--tw-shadow-color);
+    background-clip: content-box;
+    @apply shadow-neutral-500/20 hover:shadow-neutral-500/40;
+  }
+}

assets/css/components/sidebar.css

@@ -13,7 +13,7 @@
     @apply h-0;
   }
   li.open > div {
-    @apply h-auto;
+    @apply h-auto pt-1;
   }
   li.open > a > span > svg > path {
     @apply rotate-90;

assets/css/highlight.css

@@ -32,7 +32,7 @@
   }
   .ln,
   .lnt:not(.hl > .lnt),
-  .hl {
+  .hl:not(.line) {
     @apply pl-4 pr-4 min-w-[2.6rem] text-neutral-600 dark:text-neutral-300;
   }
   .lntd {

assets/css/styles.css

@@ -1,3 +1,5 @@
+@import "tailwind.css";
+
 @import "typography.css";
 @import "highlight.css";
 @import "components/cards.css";
@@ -5,10 +7,8 @@
 @import "components/search.css";
 @import "components/sidebar.css";
 @import "components/navbar.css";
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "components/scrollbar.css";
+@import "components/code-copy.css";
 
 html {
   @apply text-base antialiased;
@@ -22,10 +22,12 @@ body {
 
 :root {
   --primary-hue: 212deg;
+  --primary-saturation: 100%;
   --navbar-height: 4rem;
   --menu-height: 3.75rem;
 }
 
 .dark {
   --primary-hue: 204deg;
+  --primary-saturation: 100%;
 }

assets/css/tailwind.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

assets/css/typography.css

@@ -1,41 +1,38 @@
 .content {
-  h1 {
+  :where(h1):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mt-2 text-4xl font-bold tracking-tight text-slate-900 dark:text-slate-100;
   }
-  h2 {
+  :where(h2):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply font-semibold tracking-tight text-slate-900 dark:text-slate-100 mt-10 border-b pb-1 text-3xl border-neutral-200/70 contrast-more:border-neutral-400 dark:border-primary-100/10 contrast-more:dark:border-neutral-400;
   }
-  h3 {
+  :where(h3):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply font-semibold tracking-tight text-slate-900 dark:text-slate-100 mt-8 text-2xl;
   }
-  h4 {
+  :where(h4):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply font-semibold tracking-tight text-slate-900 dark:text-slate-100 mt-8 text-xl;
   }
-  h5 {
+  :where(h5):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply font-semibold tracking-tight text-slate-900 dark:text-slate-100 mt-8 text-lg;
   }
-  h6 {
+  :where(h6):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply font-semibold tracking-tight text-slate-900 dark:text-slate-100 mt-8 text-base;
   }
-  p {
+  :where(p):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mt-6 leading-7 first:mt-0;
   }
-  a {
+  :where(a):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply text-primary-600 underline decoration-from-font [text-underline-position:from-font];
   }
-  .not-prose a {
-    @apply text-current no-underline;
-  }
-  blockquote {
+  :where(blockquote):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mt-6 border-gray-300 italic text-gray-700 dark:border-gray-700 dark:text-gray-400 first:mt-0 ltr:border-l-2 ltr:pl-6 rtl:border-r-2 rtl:pr-6;
   }
-  pre:not(.code-block pre) {
+  :where(pre):not(:where(.code-block pre, [class~=not-prose],[class~=not-prose] *)) {
     @apply bg-primary-700/5 mb-4 overflow-x-auto rounded-xl font-medium subpixel-antialiased dark:bg-primary-300/10 text-[.9em] contrast-more:border contrast-more:border-primary-900/20 contrast-more:contrast-150 contrast-more:dark:border-primary-100/40 py-4;
   }
-  code:not(.code-block code) {
+  :where(code):not(:where(.code-block code, [class~=not-prose],[class~=not-prose] *)) {
     @apply border-black border-opacity-[0.04] bg-opacity-[0.03] bg-black break-words rounded-md border py-0.5 px-[.25em] text-[.9em] dark:border-white/10 dark:bg-white/10;
   }
-  table:not(.code-block table) {
+  :where(table):not(:where(.code-block table, [class~=not-prose],[class~=not-prose] *)) {
     @apply block overflow-x-auto mt-6 p-0 first:mt-0;
 
     tr {
@@ -48,37 +45,28 @@
       @apply m-0 border border-gray-300 px-4 py-2 dark:border-gray-600;
     }
   }
-  ol {
+  :where(ol):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mt-6 list-decimal first:mt-0 ltr:ml-6 rtl:mr-6;
     li {
       @apply my-2;
     }
   }
-  ul {
+  :where(ul):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mt-6 list-disc first:mt-0 ltr:ml-6 rtl:mr-6;
     li {
       @apply my-2;
     }
   }
-  .not-prose ul, .not-prose ol {
-    @apply m-0 list-none;
-    li {
-      @apply m-0;
-    }
-  }
-  kbd {
+  :where(kbd):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply border-black border-opacity-[0.04] bg-opacity-[0.03] bg-black break-words rounded-md border py-0.5 px-[.25em] text-[.9em] dark:border-white/10 dark:bg-white/10;
   }
-  pre:not(.code-block pre).mermaid {
+  :where(pre.mermaid):not(:where(.code-block pre, [class~=not-prose],[class~=not-prose] *)) {
     @apply bg-transparent rounded-none dark:bg-transparent;
   }
-  img {
+  :where(img):not(:where([class~=not-prose],[class~=not-prose] *)) {
     @apply mx-auto my-4 rounded-md;
   }
-  .not-prose img {
-    @apply m-0 rounded-none;
-  }
-  figure {
+  :where(figure):not(:where([class~=not-prose],[class~=not-prose] *)) {
     figcaption {
       @apply text-sm text-gray-500 dark:text-gray-400 mt-2 block text-center;
     }
@@ -112,35 +100,6 @@
   }
 }
 
-article.typesetting-article {
-  font-size: 17px;
-  font-feature-settings:
-    'rlig' 1,
-    'calt' 1;
-  h1 {
-    @apply mt-6 mb-4 text-center;
-    font-size: 2.5rem;
-  }
-  h2 {
-    @apply border-none;
-  }
-  a {
-    @apply no-underline hover:underline;
-  }
-  p {
-    @apply leading-8;
-  }
-  code {
-    @apply border-none dark:bg-neutral-700;
-  }
-  pre code {
-    @apply dark:bg-transparent;
-  }
-  .subheading-anchor + a {
-    @apply no-underline hover:no-underline after:hidden;
-  }
-}
-
 article details > summary {
   &::-webkit-details-marker {
     @apply hidden;

assets/js/back-to-top.js

@@ -0,0 +1,22 @@
+// Back to top button
+
+document.addEventListener("DOMContentLoaded", function () {
+  const backToTop = document.querySelector("#backToTop");
+  if (backToTop) {
+    document.addEventListener("scroll", (e) => {
+      if (window.scrollY > 300) {
+        backToTop.classList.remove("opacity-0");
+      } else {
+        backToTop.classList.add("opacity-0");
+      }
+    });
+  }
+});
+
+function scrollUp() {
+  window.scroll({
+    top: 0,
+    left: 0,
+    behavior: "smooth",
+  });
+}

assets/js/code-copy.js

@@ -1,30 +1,66 @@
-document.querySelectorAll('.code-copy-btn').forEach(function (button) {
-  button.addEventListener('click', function (e) {
-    e.preventDefault();
-    const targetId = button.getAttribute('data-clipboard-target');
-    const target = document.querySelector(targetId);
-    let codeElement;
-    if (target.tagName === 'CODE') {
-      codeElement = target;
-    } else {
-      // Select the last code element in case line numbers are present
-      const codeElements = target.querySelectorAll('code');
-      codeElement = codeElements[codeElements.length - 1];
-    }
-    if (codeElement) {
-      // Replace double newlines with single newlines in the innerText
-      // as each line inside <span> has trailing newline '\n'
-      const code = codeElement.innerText.replace(/\n\n/g, '\n');
-      navigator.clipboard.writeText(code).then(function () {
-        button.classList.add('copied');
-        setTimeout(function () {
-          button.classList.remove('copied');
-        }, 500);
-      }).catch(function (err) {
-        console.error('Failed to copy text: ', err);
-      });
-    } else {
-      console.error('Target element not found');
-    }
+// Copy button for code blocks
+
+document.addEventListener('DOMContentLoaded', function () {
+  const getCopyIcon = () => {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.innerHTML = `
+      <path stroke-linecap="round" stroke-linejoin="round" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+    `;
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '2');
+    return svg;
+  }
+
+  const getSuccessIcon = () => {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.innerHTML = `
+      <path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" />
+    `;
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '2');
+    return svg;
+  }
+
+  document.querySelectorAll('.code-copy-btn').forEach(function (button) {
+    // Add copy and success icons
+    button.querySelector('.copy-icon')?.appendChild(getCopyIcon());
+    button.querySelector('.success-icon')?.appendChild(getSuccessIcon());
+
+    // Add click event listener for copy button
+    button.addEventListener('click', function (e) {
+      e.preventDefault();
+      // Get the code target
+      const target = button.parentElement.previousElementSibling;
+      let codeElement;
+      if (target.tagName === 'CODE') {
+        codeElement = target;
+      } else {
+        // Select the last code element in case line numbers are present
+        const codeElements = target.querySelectorAll('code');
+        codeElement = codeElements[codeElements.length - 1];
+      }
+      if (codeElement) {
+        let code = codeElement.innerText;
+        // Replace double newlines with single newlines in the innerText
+        // as each line inside <span> has trailing newline '\n'
+        if ("lang" in codeElement.dataset) {
+          code = code.replace(/\n\n/g, '\n');
+        }
+        navigator.clipboard.writeText(code).then(function () {
+          button.classList.add('copied');
+          setTimeout(function () {
+            button.classList.remove('copied');
+          }, 1000);
+        }).catch(function (err) {
+          console.error('Failed to copy text: ', err);
+        });
+      } else {
+        console.error('Target element not found');
+      }
+    });
   });
 });

assets/js/flexsearch.js

@@ -1,5 +1,16 @@
 // Search functionality using FlexSearch.
 
+// Change shortcut key to cmd+k on Mac, iPad or iPhone.
+document.addEventListener("DOMContentLoaded", function () {
+  if (/iPad|iPhone|Macintosh/.test(navigator.userAgent)) {
+    // select the kbd element under the .search-wrapper class
+    const keys = document.querySelectorAll(".search-wrapper kbd");
+    keys.forEach(key => {
+      key.innerHTML = '<span class="text-xs">⌘</span>K';
+    });
+  }
+});
+
 // Render the search data as JSON.
 // {{ $searchDataFile := printf "%s.search-data.json" .Language.Lang }}
 // {{ $searchData := resources.Get "json/search-data.json" | resources.ExecuteAsTemplate $searchDataFile . }}

assets/js/menu.js

@@ -1,19 +1,49 @@
 // Hamburger menu for mobile navigation
 
-const menu = document.querySelector('.hamburger-menu');
-
-menu.addEventListener('click', (e) => {
-  e.preventDefault();
+document.addEventListener('DOMContentLoaded', function () {
+  const menu = document.querySelector('.hamburger-menu');
+  const overlay = document.querySelector('.mobile-menu-overlay');
   const sidebarContainer = document.querySelector('.sidebar-container');
 
-  // Toggle the hamburger menu
-  menu.querySelector('svg').classList.toggle('open');
+  // Initialize the overlay
+  const overlayClasses = ['fixed', 'inset-0', 'z-10', 'bg-black/80', 'dark:bg-black/60'];
+  overlay.classList.add('bg-transparent');
+  overlay.classList.remove("hidden", ...overlayClasses);
 
-  // When the menu is open, we want to show the navigation sidebar
-  sidebarContainer.classList.toggle('max-md:[transform:translate3d(0,-100%,0)]');
-  sidebarContainer.classList.toggle('max-md:[transform:translate3d(0,0,0)]');
+  function toggleMenu() {
+    // Toggle the hamburger menu
+    menu.querySelector('svg').classList.toggle('open');
 
-  // When the menu is open, we want to prevent the body from scrolling
-  document.body.classList.toggle('overflow-hidden');
-  document.body.classList.toggle('md:overflow-auto');
+    // When the menu is open, we want to show the navigation sidebar
+    sidebarContainer.classList.toggle('max-md:[transform:translate3d(0,-100%,0)]');
+    sidebarContainer.classList.toggle('max-md:[transform:translate3d(0,0,0)]');
+
+    // When the menu is open, we want to prevent the body from scrolling
+    document.body.classList.toggle('overflow-hidden');
+    document.body.classList.toggle('md:overflow-auto');
+  }
+
+  menu.addEventListener('click', (e) => {
+    e.preventDefault();
+    toggleMenu();
+
+    if (overlay.classList.contains('bg-transparent')) {
+      // Show the overlay
+      overlay.classList.add(...overlayClasses);
+      overlay.classList.remove('bg-transparent');
+    } else {
+      // Hide the overlay
+      overlay.classList.remove(...overlayClasses);
+      overlay.classList.add('bg-transparent');
+    }
+  });
+
+  overlay.addEventListener('click', (e) => {
+    e.preventDefault();
+    toggleMenu();
+
+    // Hide the overlay
+    overlay.classList.remove(...overlayClasses);
+    overlay.classList.add('bg-transparent');
+  });
 });

assets/js/theme.js

@@ -1,36 +1,51 @@
-// Dark theme toggle
+// Light / Dark theme toggle
+(function () {
+  const defaultTheme = '{{ site.Params.theme.default | default `system`}}'
 
-const themeToggleButtons = document.querySelectorAll(".theme-toggle");
+  const themeToggleButtons = document.querySelectorAll(".theme-toggle");
 
-// Change the icons inside the button based on previous settings
-if (
-  localStorage.getItem("color-theme") === "dark" ||
-  (!("color-theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches)
-) {
-  themeToggleButtons.forEach((el) => el.dataset.theme = "dark");
-} else {
-  themeToggleButtons.forEach((el) => el.dataset.theme = "light");
-}
+  // 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");
+  }
 
-themeToggleButtons.forEach((el) => {
-  el.addEventListener("click", function () {
-    if (localStorage.getItem("color-theme")) {
-      if (localStorage.getItem("color-theme") === "light") {
-        document.documentElement.classList.add("dark");
-        localStorage.setItem("color-theme", "dark");
+  // 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 {
-        document.documentElement.classList.remove("dark");
-        localStorage.setItem("color-theme", "light");
+        if (document.documentElement.classList.contains("dark")) {
+          setLightTheme();
+          localStorage.setItem("color-theme", "light");
+        } else {
+          setDarkTheme();
+          localStorage.setItem("color-theme", "dark");
+        }
       }
-    } else {
-      if (document.documentElement.classList.contains("dark")) {
-        document.documentElement.classList.remove("dark");
-        localStorage.setItem("color-theme", "light");
-      } else {
-        document.documentElement.classList.add("dark");
-        localStorage.setItem("color-theme", "dark");
-      }
-    }
-    el.dataset.theme = document.documentElement.classList.contains("dark") ? "dark" : "light";
+      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"
+      );
+    }
+  });
+})();

assets/json/search-data.json

@@ -1,3 +1,10 @@
+{{/* FlexSearch Index Data */}}
+{{- $indexType := site.Params.search.flexsearch.index | default "content" -}}
+
+{{- if not (in (slice "content" "summary" "heading" "title" ) $indexType) -}}
+  {{- errorf "unknown flexsearch index type: %s" $indexType -}}
+{{- end -}}
+
 {{- $pages := where .Site.Pages "Kind" "in" (slice "page" "section") -}}
 {{- $pages = where $pages "Params.excludeSearch" "!=" true -}}
 {{- $pages = where $pages "Content" "!=" "" -}}
@@ -7,7 +14,7 @@
 {{- range $index, $page := $pages -}}
   {{- $pageTitle := $page.LinkTitle | default $page.File.BaseFileName -}}
   {{- $pageLink := $page.RelPermalink -}}
-  {{- $data := partial "utils/fragments" $page -}}
+  {{- $data := partial "utils/fragments" (dict "context" $page "type" $indexType) -}}
   {{- $output = $output | merge (dict $pageLink (dict "title" $pageTitle "data" $data)) -}}
 {{- end -}}
 

config.yaml

@@ -1,30 +0,0 @@
-build:
-  buildStats:
-    enable: true
-    disableIDs: true
-  cacheBusters:
-  - source: assets/watching/hugo_stats\.json
-    target: styles\.css
-  - source: assets/.*\.(js|ts|jsx|tsx)
-    target: (js|scripts|javascript)
-  - source: assets/.*\.(css|sass|scss)$
-    target: (css|styles|scss|sass)
-  - source: (postcss|tailwind)\.config\.js
-    target: (css|styles|scss|sass)
-  - source: assets/.*\.(.*)$
-    target: $1
-
-module:
-  mounts:
-  - source: static
-    target: static
-  - source: layouts
-    target: layouts
-  - source: data
-    target: data
-  - source: assets
-    target: assets
-  - source: i18n
-    target: i18n
-  - source: archetypes
-    target: archetypes

data/icons.yaml

@@ -9,6 +9,11 @@ github: >
     <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>
   </svg>
 
+codeberg: >
+  <svg fill="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <path d="M11.955.49A12 12 0 0 0 0 12.49a12 12 0 0 0 1.832 6.373L11.838 5.928a.187.14 0 0 1 .324 0l10.006 12.935A12 12 0 0 0 24 12.49a12 12 0 0 0-12-12 12 12 0 0 0-.045 0zm.375 6.467 4.416 16.553a12 12 0 0 0 5.137-4.213z"/>
+  </svg>
+
 hextra: <svg viewBox="0 0 180 180" xmlns="http://www.w3.org/2000/svg" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="m 105.50024,22.224647 c -9.59169,-5.537563 -21.40871,-5.537563 -31.000093,0 L 39.054693,42.689119 C 29.463353,48.226675 23.55484,58.460531 23.55484,69.535642 v 40.928918 c 0,11.07542 5.908513,21.3092 15.499853,26.84652 l 35.445453,20.46446 c 9.591313,5.53732 21.408404,5.53732 31.000094,0 l 35.44507,-20.46446 c 9.59131,-5.53732 15.49985,-15.7711 15.49985,-26.84652 V 69.535642 c 0,-11.075111 -5.90854,-21.308967 -15.49985,-26.846523 z M 34.112797,85.737639 c -1.384445,2.397827 -1.384445,5.352099 0,7.749927 l 24.781554,42.922974 c 1.38437,2.39783 3.942853,3.87496 6.711592,3.87496 h 49.563107 c 2.76905,0 5.3273,-1.47713 6.71144,-3.87496 l 24.78194,-42.922974 c 1.38414,-2.397828 1.38414,-5.3521 0,-7.749927 L 121.88049,42.814746 c -1.38414,-2.397828 -3.94239,-3.874964 -6.71144,-3.874964 H 65.605944 c -2.768739,0 -5.327223,1.477059 -6.711592,3.874964 z" style="stroke-width:0.774993" /></svg>
 
 hugo: <svg viewBox="0 0 370 391" xmlns="http://www.w3.org/2000/svg"><g clip-rule="evenodd" fill-rule="evenodd"><path d="m207.5 22.4 114.4 66.6c13.5 7.9 21.9 22.4 21.9 38v136.4c0 17.3-9.3 33.3-24.5 41.8l-113.5 63.9a49.06 49.06 0 0 1 -48.5-.2l-104.5-60.1c-16.4-9.5-26.6-27-26.6-45.9v-129.5c0-19.1 9.9-36.8 26.1-46.8l102.8-63.5c16-9.9 36.2-10.1 52.4-.7z" fill="#ff4088" stroke="#c9177e" stroke-width="27" /><path d="m105.6 298.2v-207.2h43.4v75.5h71.9v-75.5h43.5v207.2h-43.5v-90.6h-71.9v90.6z" fill="#fff" /></g></svg>
@@ -270,3 +275,4 @@ twitter: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill=
 mastodon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.67 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z"></path></svg>
 youtube: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="currentColor" d="M8.051 1.999h.089c.822.003 4.987.033 6.11.335a2.01 2.01 0 0 1 1.415 1.42c.101.38.172.883.22 1.402l.01.104l.022.26l.008.104c.065.914.073 1.77.074 1.957v.075c-.001.194-.01 1.108-.082 2.06l-.008.105l-.009.104c-.05.572-.124 1.14-.235 1.558a2.007 2.007 0 0 1-1.415 1.42c-1.16.312-5.569.334-6.18.335h-.142c-.309 0-1.587-.006-2.927-.052l-.17-.006l-.087-.004l-.171-.007l-.171-.007c-1.11-.049-2.167-.128-2.654-.26a2.007 2.007 0 0 1-1.415-1.419c-.111-.417-.185-.986-.235-1.558L.09 9.82l-.008-.104A31.4 31.4 0 0 1 0 7.68v-.123c.002-.215.01-.958.064-1.778l.007-.103l.003-.052l.008-.104l.022-.26l.01-.104c.048-.519.119-1.023.22-1.402a2.007 2.007 0 0 1 1.415-1.42c.487-.13 1.544-.21 2.654-.26l.17-.007l.172-.006l.086-.003l.171-.007A99.788 99.788 0 0 1 7.858 2h.193zM6.4 5.209v4.818l4.157-2.408L6.4 5.209z"/></svg>
 x-twitter: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="currentColor" d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8L200.7 275.5 26.8 48H172.4L272.9 180.9 389.2 48zM364.4 421.8h39.1L151.1 88h-42L364.4 421.8z"/></svg>
+linkedin: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037c-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85c3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 0 1-2.063-2.065a2.064 2.064 0 1 1 2.063 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z"/></svg>

dev.toml

@@ -0,0 +1,26 @@
+# Theme development config for exampleSite
+# https://gohugo.io/getting-started/configuration/#configure-cache-busters
+[build]
+  [build.buildStats]
+    enable = true
+    disableIDs = true
+  [[build.cachebusters]]
+    source = 'assets/watching/hugo_stats\.json'
+    target = 'styles\.css'
+  [[build.cachebusters]]
+    source = '(postcss|tailwind)\.config\.js'
+    target = 'css'
+  [[build.cachebusters]]
+    source = 'assets/.*\.(js|ts|jsx|tsx)'
+    target = 'js'
+  [[build.cachebusters]]
+    source = 'assets/.*\.(.*)$'
+    target = '$1'
+
+[module]
+  [[module.mounts]]
+    source = "assets"
+    target = "assets"
+  [[module.mounts]]
+    source = "hugo_stats.json"
+    target = "assets/watching/hugo_stats.json"

exampleSite/content/_index.md

@@ -2,3 +2,75 @@
 title: Hextra Theme
 layout: hextra-home
 ---
+
+{{< hextra/hero-badge >}}
+  <div class="w-2 h-2 rounded-full bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+<div class="mt-6 mb-6">
+{{< hextra/hero-headline >}}
+  Build modern websites&nbsp;<br class="sm:block hidden" />with Markdown and Hugo
+{{< /hextra/hero-headline >}}
+</div>
+
+<div class="mb-12">
+{{< hextra/hero-subtitle >}}
+  Fast, batteries-included Hugo theme&nbsp;<br class="sm:block hidden" />for creating beautiful static websites
+{{< /hextra/hero-subtitle >}}
+</div>
+
+<div class="mb-6">
+{{< hextra/hero-button text="Get Started" link="docs" >}}
+</div>
+
+<div class="mt-6"></div>
+
+{{< hextra/feature-grid >}}
+  {{< hextra/feature-card
+    title="Fast and Full-featured"
+    subtitle="Simple and easy to use, yet powerful and feature-rich."
+    class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
+    image="images/hextra-doc.webp"
+    imageClass="top-[40%] left-[24px] w-[180%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="Markdown is All You Need"
+    subtitle="Compose with just Markdown. Enrich with Shortcode components."
+    class="aspect-auto md:aspect-[1.1/1] max-lg:min-h-[340px]"
+    image="images/hextra-markdown.webp"
+    imageClass="top-[40%] left-[36px] w-[180%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="Full Text Search"
+    subtitle="Built-in full text search with FlexSearch, no extra setup required."
+    class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
+    image="images/hextra-search.webp"
+    imageClass="top-[40%] left-[36px] w-[110%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="Lightweight as a Feather"
+    subtitle="No dependency or Node.js is needed to use Hextra. Powered by Hugo, one of *the fastest* static site generators, building your site in just seconds with a single binary."
+  >}}
+  {{< hextra/feature-card
+    title="Responsive with Dark Mode Included"
+    subtitle="Looks great on different screen sizes. Built-in dark mode support, with auto-switching based on user's system preference."
+  >}}
+  {{< hextra/feature-card
+    title="Build and Host for Free"
+    subtitle="Build with GitHub Actions, and host for free on GitHub Pages. Alternatively it can be hosted on any static hosting service."
+  >}}
+  {{< hextra/feature-card
+    title="Multi-Language Made Easy"
+    subtitle="Create multi-language pages by just adding locales suffix to the Markdown file. Adding i18n support to your site is intuitive."
+  >}}
+  {{< hextra/feature-card
+    title="And Much More..."
+    icon="sparkles"
+    subtitle="Syntax highlighting / Table of contents / SEO / RSS / LaTeX / Mermaid / Customizable / and more..."
+  >}}
+{{< /hextra/feature-grid >}}

exampleSite/content/_index.zh-cn.md

@@ -0,0 +1,76 @@
+---
+title: Hextra 主题
+layout: hextra-home
+---
+
+{{< hextra/hero-badge >}}
+  <div class="w-2 h-2 rounded-full bg-primary-400"></div>
+  <span>免费 开源</span>
+  {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+<div class="mt-6 mb-6">
+{{< hextra/hero-headline >}}
+  创建现代化网站&nbsp;<br class="sm:block hidden" />由 Markdown 和 Hugo 驱动
+{{< /hextra/hero-headline >}}
+</div>
+
+<div class="mb-12">
+{{< hextra/hero-subtitle >}}
+  极速且全能的 Hugo 主题框架&nbsp;<br class="sm:block hidden" />为构建现代化的静态网站而生
+{{< /hextra/hero-subtitle >}}
+</div>
+
+<div class="mb-6">
+{{< hextra/hero-button text="现在开始" link="docs" >}}
+</div>
+
+<div class="mt-6"></div>
+
+{{< hextra/feature-grid >}}
+  {{< hextra/feature-card
+    title="快速且功能全面"
+    subtitle="简单易用，功能强大丰富。"
+    class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
+    image="/images/hextra-doc.webp"
+    imageClass="top-[40%] left-[24px] w-[180%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="Markdown 写作"
+    subtitle="只需使用 Markdown 进行编辑。多样的 Shortcode 组件开箱即用。"
+    class="aspect-auto md:aspect-[1.1/1] max-lg:min-h-[340px]"
+    image="/images/hextra-markdown.webp"
+    imageClass="top-[40%] left-[36px] w-[180%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="全文搜索"
+    subtitle="内置 FlexSearch 全文搜索，无需额外设置。"
+    class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
+    image="/images/hextra-search.webp"
+    imageClass="top-[40%] left-[36px] w-[110%] sm:w-[110%] dark:opacity-80"
+    style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
+  >}}
+  {{< hextra/feature-card
+    title="轻如羽毛"
+    subtitle="使用 Hextra 无需依赖 Node.js。由 Hugo 提供支持，Hugo 是最快的静态网站生成器之一，只需一个二进制文件即可在数秒内创建网站。"
+  >}}
+  {{< hextra/feature-card
+    title="响应式布局，暗黑模式"
+    subtitle="适应不同的屏幕尺寸。内置暗黑模式支持，并根据用户的系统偏好自动切换。"
+  >}}
+  {{< hextra/feature-card
+    title="免费构建和托管"
+    subtitle="使用 GitHub Actions 进行构建，并在 GitHub Pages 上免费托管。也可以托管在任何静态托管服务上。"
+  >}}
+  {{< hextra/feature-card
+    title="多语言轻松实现"
+    subtitle="仅需通过在 Markdown 文件后添加语言代码即可创建多语言页面。向您的站点添加 i18n 支持直观易行。"
+  >}}
+  {{< hextra/feature-card
+    title="还有更多..."
+    icon="sparkles"
+    subtitle="代码高亮 / 目录 / SEO / RSS / LaTeX 公式 / Mermaid 图标 / 自定义 / 等等..."
+  >}}
+{{< /hextra/feature-grid >}}

exampleSite/content/about/index.ja.md

@@ -1,20 +0,0 @@
----
-title: "このサイトについて"
-toc: false
----
-
-Hextraは、現代的な静的ウェブサイトを構築するためのシンプルで高速で柔軟なテーマとして設計されています。特にドキュメンテーションウェブサイトに適していますが、ブログ、ポートフォリオなどのさまざまなタイプのサイトにも使用できます。
-
-Hugoは、Jekyllと同様に静的サイトジェネレーターです。Hugoの特徴は、単一のバイナリであることで、さまざまなプラットフォームで簡単にインストールして実行できることです。また、数千ページのサイトをミリ秒単位でレンダリングできるほど非常に高速で信頼性があります。
-
-Hextraは、最小限のフットプリントに焦点を当てた考え方で構築されています。始めるためには、Node.jsのような追加の依存関係は必要ありません。必要なのは、単一のYAML設定ファイルと、Markdownのコンテンツだけです。そのため、ツールのセットアップではなく、質の高いコンテンツの作成に集中できます。
-
-## クレジット
-
-Hextraをビルドするには、次のツールとインスピレーションが必要です：
-
-- [Hugo](https://gohugo.io/)
-- [Tailwind CSS](https://tailwindcss.com/)
-- [Heroicons](https://heroicons.com/)
-- [Nextra](https://nextra.vercel.app/)
-- [Next.js](https://nextjs.org/)

exampleSite/content/about/index.zh-cn.md

@@ -0,0 +1,20 @@
+---
+title: 关于
+toc: false
+---
+
+Hextra 是一款简洁、快速、灵活的主题，适用于构建现代化静态站点。Hextra 特别适用于文档网站，但也可用于构建博客、个人网站等各种类型的网站。
+
+Hugo 和 Jekyll 类似，是一个静态网站生成器。但与其他生成器不同，Hugo 只有单个可执行文件，这使得它可以轻松地在各种平台上安装和运行。Hugo 的运行速度非常快且可靠性高，能够在几毫秒内渲染数千页的网站。
+
+Hextra 被设计为轻量级，具有最小化的内存占用。使用 Hextra 无需安装繁杂的依赖，比如 Node.js；相反，你只需要一个简单的 YAML 配置文件和 Markdown 内容。因此，我们可以专注于内容而非在配置环境上浪费精力。
+
+## 鸣谢
+
+Hextra 的设计离不开这些项目的支持和其提供的灵感：
+
+- [Hugo](https://gohugo.io/)
+- [Tailwind CSS](https://tailwindcss.com/)
+- [Heroicons](https://heroicons.com/)
+- [Nextra](https://nextra.vercel.app/)
+- [Next.js](https://nextjs.org/)

exampleSite/content/blog/_index.md

@@ -1,3 +1,10 @@
 ---
 title: "Blog"
 ---
+
+<div style="text-align: center; margin-top: 1em;">
+{{< hextra/hero-badge link="index.xml" >}}
+  <span>RSS Feed</span>
+  {{< icon name="rss" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+</div>

exampleSite/content/blog/_index.zh-cn.md

@@ -0,0 +1,3 @@
+---
+title: "博客"
+---

exampleSite/content/blog/markdown.md

@@ -2,8 +2,16 @@
 title: Markdown Syntax Guide
 date: 2020-01-01
 authors:
-  - name: John Doe
-    link: https://example.com/johndoe
+  - name: imfing
+    link: https://github.com/imfing
+    image: https://github.com/imfing.png
+  - name: Octocat
+    link: https://github.com/octocat
+    image: https://github.com/octocat.png
+tags:
+  - Markdown
+  - Example
+  - Guide
 excludeSearch: true
 ---
 

exampleSite/content/blog/markdown.zh-cn.md

@@ -0,0 +1,137 @@
+---
+title: Markdown 语法指南
+date: 2020-01-01
+authors:
+  - name: John Doe
+    link: https://example.com/johndoe
+excludeSearch: true
+---
+
+这篇文章提供了一些基础的 Markdown 语法样例，这些可以在 Hugo 的内容文件中使用。
+
+<!--more-->
+
+## 基础语法
+
+### 标题
+
+```
+# 一级标题
+## 二级标题
+### 三级标题
+#### 四级标题
+##### 五级标题
+###### 六级标题
+```
+
+## 二级标题
+### 三级标题
+#### 四级标题
+##### 五级标题
+###### 六级标题
+
+```text
+*这段文字将是斜体*
+_这也将是斜体_
+
+**这段文字将是粗体**
+__这也将是粗体__
+
+_你 **可以** 组合它们_
+```
+
+*这段文字将是斜体*
+_这也将是斜体_
+
+**这段文字将是粗体**
+__这也将是粗体__
+
+_你 **可以** 组合它们_
+
+### 列表
+
+#### 无序列表
+
+* 项目 1
+* 项目 2
+  * 项目 2a
+  * 项目 2b
+
+#### 有序列表
+
+1. 项目 1
+2. 项目 2
+3. 项目 3
+   1. 项目 3a
+   2. 项目 3b
+
+### 图片
+
+```markdown
+![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)
+```
+
+![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)
+
+### 链接
+
+```markdown
+[Hugo](https://gohugo.io)
+```
+
+[Hugo](https://gohugo.io)
+
+### 块引用
+
+```markdown
+牛顿曾说：
+
+> 如果我看得更远，那是因为我站在巨人的肩膀上。
+```
+
+> 如果我看得更远，那是因为我站在巨人的肩膀上。
+
+### 行内代码
+
+```markdown
+行内 `代码` 有 `反引号` 包围。
+```
+
+行内 `代码` 有 `反引号` 包围。
+
+### 代码块
+
+#### 语法高亮
+
+````markdown
+```go
+func main() {
+    fmt.Println("Hello World")
+}
+```
+````
+
+```go
+func main() {
+    fmt.Println("Hello World")
+}
+```
+
+### 表格
+
+```markdown
+| Syntax    | Description |
+| --------- | ----------- |
+| Header    | Title       |
+| Paragraph | Text        |
+```
+
+| Syntax    | Description |
+| --------- | ----------- |
+| Header    | Title       |
+| Paragraph | Text        |
+
+## 参考
+
+- [Markdown Syntax](https://www.markdownguide.org/basic-syntax/)
+- [Hugo Markdown](https://gohugo.io/content-management/formats/#markdown)

exampleSite/content/docs/_index.ja.md

@@ -1,15 +0,0 @@
----
-linkTitle: "ドキュメンテーション"
-title: Hextraへようこそ
----
-
-👋 こんにちは！Hextraドキュメンテーションへようこそ！
-
-## Hextraとは？
-
-Hextraは、[Hugo][hugo]テーマの一つで、[Tailwind CSS][tailwind-css]を使用して作られた、現代的で高速なバッテリー内蔵のテーマです。
-ドキュメンテーション、ブログ、ウェブサイトの美しいウェブサイトを構築するために設計され、様々な要件に対応するための機能と柔軟性を提供します。
-
-[hugo]: https://gohugo.io/
-[flex-search]: https://github.com/nextapps-de/flexsearch
-[tailwind-css]: https://tailwindcss.com/

exampleSite/content/docs/_index.md

@@ -5,18 +5,20 @@ title: Introduction
 
 👋 Hello! Welcome to the Hextra documentation!
 
+<!--more-->
+
 ## What is Hextra?
 
 Hextra is a modern, fast and batteries-included [Hugo][hugo] theme built with [Tailwind CSS][tailwind-css].
-Designed for building beautiful websites for documentation, blogs and websites, it provides out-of-the-box features and flexibility to meet various requirements.
+Designed for building beautiful websites for documentation, blogs, and websites, it provides out-of-the-box features and flexibility to meet various requirements.
 
 ## Features
 
 - **Beautiful Design** - Inspired by Nextra, Hextra utilizes Tailwind CSS to offer a modern design that makes your site look outstanding.
-- **Responsive Layout and Dark Mode** - It looks great on all devices, from mobile, tablet to desktop. Dark mode is also supported to accomodate various lighting conditions.
-- **Fast and Lightweight** - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No Javascript or Node.js are needed to use it.
+- **Responsive Layout and Dark Mode** - It looks great on all devices, from mobile, tablet to desktop. Dark mode is also supported to accommodate various lighting conditions.
+- **Fast and Lightweight** - Powered by Hugo, a lightning-fast static-site generator housed in a single binary file, Hextra keeps its footprint minimal. No JavaScript or Node.js are needed to use it.
 - **Full-text Search** - Built-in offline full-text search powered by FlexSearch, no additional configuration required.
-- **Battery-included** - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcumbs, pagination, sidebar navigation and more are all automatically generated.
+- **Battery-included** - Markdown, syntax highlighting, LaTeX math formulae, diagrams and Shortcodes elements to enhance your content. Table of contents, breadcrumbs, pagination, sidebar navigation and more are all automatically generated.
 - **Multi-language and SEO Ready** - Multi-language sites made easy with Hugo's multilingual mode. Out-of-the-box support is included for SEO tags, Open Graph, and Twitter Cards.
 
 ## Questions or Feedback?

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

@@ -0,0 +1,40 @@
+---
+linkTitle: "文档"
+title: 介绍
+---
+
+👋 你好！欢迎来到 Hextra 文档！
+
+<!--more-->
+
+## Hextra 是什么？
+
+Hextra 是一款现代、快速且内置丰富功能的 [Hugo][hugo] 主题，它是用 [Tailwind CSS][tailwind-css] 构建的。该主题旨在创建美观的文档、博客和网站，提供了开箱即用的功能和灵活性以满足各种需求。
+
+## 功能特点
+
+- **优美的设计** - 受到 Nextra 的启发，Hextra 利用 Tailwind CSS 提供了一种现代设计，使您的网站看起来出色。
+- **响应式布局和深色模式** - 无论是在移动设备、平板还是桌面上，都表现出色。同时支持深色模式以适应各种光线条件。
+- **快速和轻量级** - 由 Hugo 驱动，一个轻量级且超快的静态网站生成器，封装在一个单一的二进制文件中，Hextra 保持其占用极小。使用它不需要 Javascript 或 Node.js。
+- **全文搜索** - 内置的离线全文搜索由 FlexSearch 提供支持，无需额外配置。
+- **功能全面** - 支持 Markdown、语法高亮、LaTeX 数学公式、图表以及 Shortcodes 元素以增强您的内容。目录、面包屑、分页、侧边栏导航等都会自动生成。
+- **多语言和 SEO 支持** - Hugo 的多语言模式轻松支持多语言网站。对于 SEO 标签、Open Graph 和 Twitter 卡片，也提供了开箱即用的支持。
+
+## 有问题或反馈？
+
+{{< callout emoji="❓" >}}
+  Hextra 仍在积极开发中。
+  有问题或反馈？请随时[提出问题](https://github.com/imfing/hextra/issues)！
+{{< /callout >}}
+
+## 接下来
+
+直接进入以下部分开始：
+
+{{< cards >}}
+  {{< card link="getting-started" title="入门指南" icon="document-text" subtitle="学习如何使用 Hextra 创建网站" >}}
+{{< /cards >}}
+
+[hugo]: https://gohugo.io/
+[flex-search]: https://github.com/nextapps-de/flexsearch
+[tailwind-css]: https://tailwindcss.com/

exampleSite/content/docs/advanced/_index.md

@@ -1,6 +1,8 @@
 ---
 linkTitle: Advanced
 title: Advanced Topics
+prev: /docs/guide/shortcodes/tabs
+next: /docs/advanced/multi-language
 ---
 
 This section covers some advanced topics of the theme.
@@ -10,4 +12,5 @@ This section covers some advanced topics of the theme.
 {{< cards >}}
   {{< card link="multi-language" title="Multi-language" icon="translate" >}}
   {{< card link="customization" title="Customization" icon="pencil" >}}
+  {{< card link="comments" title="Comments System" icon="chat-alt" >}}
 {{< /cards >}}

exampleSite/content/docs/advanced/_index.zh-cn.md

@@ -0,0 +1,15 @@
+---
+linkTitle: 高级配置
+title: 高级配置
+prev: /docs/guide/shortcodes/tabs
+next: /docs/advanced/multi-language
+---
+
+此部分提供了 Hextra 的一些高级配置。
+
+<!--more-->
+
+{{< cards >}}
+  {{< card link="multi-language" title="多语言" icon="translate" >}}
+  {{< card link="customization" title="定制化" icon="pencil" >}}
+{{< /cards >}}

exampleSite/content/docs/advanced/comments.md

@@ -0,0 +1,39 @@
+---
+title: Comments System
+linkTitle: Comments
+---
+
+Hextra supports adding comments system to your site.
+Currently [giscus](https://giscus.app/) is supported.
+
+<!--more-->
+
+## giscus
+
+[giscus](https://giscus.app/) is a comments system powered by [GitHub Discussions](https://docs.github.com/en/discussions). It is free and open source.
+
+To enable giscus, you need to add the following to the site configuration file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  comments:
+    enable: false
+    type: giscus
+
+    giscus:
+      repo: <repository>
+      repoId: <repository ID>
+      category: <category>
+      categoryId: <category ID>
+```
+
+The giscus configurations can be constructed from the [giscus.app](https://giscus.app/) website. More details can also be found there.
+
+Comments can be enabled or disabled for a specific page in the page front matter:
+
+```yaml {filename="content/docs/about.md"}
+---
+title: About
+comments: true
+---
+```

exampleSite/content/docs/advanced/comments.zh-cn.md

@@ -0,0 +1,39 @@
+---
+title: 评论系统
+linkTitle: Comments
+---
+
+Hextra 支持在你的网站中添加评论系统。
+目前已经支持 [giscus](https://giscus.app/).
+
+<!--more-->
+
+## giscus
+
+[giscus](https://giscus.app/) 是由 [GitHub Discussions](https://docs.github.com/en/discussions)驱动的评论系统。Giscus 免费并且开源。
+
+如需启用 Giscus, 你需要在配置文件中添加以下内容：
+
+```yaml {filename="hugo.yaml"}
+params:
+  comments:
+    enable: false
+    type: giscus
+
+    giscus:
+      repo: <repository>
+      repoId: <repository ID>
+      category: <category>
+      categoryId: <category ID>
+```
+
+Giscus 配置可以参考 [giscus.app](https://giscus.app/)，还可以在那里找到更多详细信息。
+
+可以在 front matter 中启用或禁用特定页面的评论：
+
+```yaml {filename="content/docs/about.md"}
+---
+title: About
+comments: true
+---
+```

exampleSite/content/docs/advanced/customization.md

@@ -10,7 +10,11 @@ This page describes the available options and how to customize the theme further
 
 ## Custom CSS
 
-To add custom CSS, we need to create a file `assets/css/custom.css` in our site. Hextra will automatically load this file. For example, customize the font family of the content:
+To add custom CSS, we need to create a file `assets/css/custom.css` in our site. Hextra will automatically load this file.
+
+### Font Family
+
+The font family of the content can be customized using:
 
 ```css {filename="assets/css/custom.css"}
 .content {
@@ -18,13 +22,24 @@ To add custom CSS, we need to create a file `assets/css/custom.css` in our site.
 }
 ```
 
+### Inline Code Element
+
+The color of text mixed with `other text` can customized with:
+
+```css {filename="assets/css/custom.css"}
+.content code:not(.code-block code) {
+  color: #c97c2e;
+}
+```
+
 ### Primary Color
 
-The primary color of the theme can be customized by setting the `--primary-hue` variable:
+The primary color of the theme can be customized by setting the `--primary-hue` and `--primary-saturation` variables:
 
 ```css {filename="assets/css/custom.css"}
 :root {
   --primary-hue: 100deg;
+  --primary-saturation: 90%;
 }
 ```
 
@@ -32,8 +47,8 @@ The primary color of the theme can be customized by setting the `--primary-hue`
 
 List of available syntax highlighting themes are available at [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html). The stylesheet can be generated using the command:
 
-```bash
-$ hugo gen chromastyles --style=github
+```shell
+hugo gen chromastyles --style=github
 ```
 
 To override the default syntax highlighting theme, we can add the generated styles to the custom CSS file.
@@ -55,4 +70,4 @@ For further information, refer to the [Hugo Templates](https://gohugo.io/templat
 
 ## Further Customization
 
-Didn't find what you were looking for? Feel free to [open an issue](https://github.com/imfing/hextra/issues) or make a contribution to the theme!
+Didn't find what you were looking for? Feel free to [open a discussion](https://github.com/imfing/hextra/discussions) or make a contribution to the theme!

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

@@ -0,0 +1,58 @@
+---
+title: 自定义 Hextra
+linkTitle: 自定义
+---
+
+Hextra 在 `hugo.yaml` 中提供了一些自定义选项来配置主题。
+本页介绍了可用选项以及如何进一步自定义主题。
+
+<!--more-->
+
+## 自定义 CSS
+
+要添加自定义 CSS，我们需要在站点中创建一个文件 `assets/css/custom.css`。Hextra 将自动加载该文件，比如自定义字体：
+
+```css {filename="assets/css/custom.css"}
+.content {
+  font-family: "Times New Roman", Times, serif;
+}
+```
+
+### 主题色
+
+主题色可以通过设置 `--primary-hue` 变量来自定义：
+
+```css {filename="assets/css/custom.css"}
+:root {
+  --primary-hue: 100deg;
+}
+```
+
+### 代码高亮
+
+代码高亮风格的详细信息可在 [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html) 中找到。可以使用以下命令生成样式表：
+
+```shell
+hugo gen chromastyles --style=github
+```
+
+可将生成的样式添加到自定义 CSS 文件中以覆盖默认代码高亮样式。
+
+## 自定义 Script
+
+你可以添加以下文件以自定义 `script` 添加到每页的 `head` 最后：
+
+```
+layouts/partials/custom/head-end.html
+```
+
+## 自定义布局
+
+可以在站点的 `layouts` 目录中创建同名文件来覆盖主题的默认布局。
+例如，要覆盖文档的 `single.html` 布局，在站点中创建文件 `layouts/docs/single.html`。
+
+如需或许更多信息，转至 [Hugo Templates](https://gohugo.io/templates/)。
+
+## 进一步定制 Hextra
+
+没有找到你想修改的内容？在 GitHub 上[创建 Discussion](https://github.com/imfing/hextra/discussions) 或为 Hextra 贡献你的智慧！

exampleSite/content/docs/advanced/multi-language.md

@@ -1,6 +1,7 @@
 ---
 title: "Multi-language"
 weight: 1
+prev: /docs/advanced
 ---
 
 Hextra supports creating site with multiple languages using Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/).

exampleSite/content/docs/advanced/multi-language.zh-cn.md

@@ -0,0 +1,74 @@
+---
+title: "多语言"
+weight: 1
+prev: /docs/advanced
+---
+
+Hextra 支持使用 Hugo 的[多语言模式](https://gohugo.io/content-management/multilingual/) 创建多语言的网站。
+
+<!--more-->
+
+## 启用多语言支持
+
+为了使我们的网站支持多语言，我们需要告诉 Hugo 需要支持的语言。 在站点配置文件中添加：
+
+```yaml {filename="hugo.yaml"}
+defaultContentLanguage: en
+languages:
+  en:
+    languageName: English
+    weight: 1
+  fr:
+    languageName: Français
+    weight: 2
+  ja:
+    languageName: 日本語
+    weight: 3
+```
+
+## 按文件名管理翻译
+
+Hugo 支持按文件名管理翻译。例如，如果我们有一个英文文件 `content/docs/_index.md`，我们可以创建一个翻译为法语的文件 `content/docs/_index.fr.md`。
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" state="open" >}}
+      {{< filetree/file name="_index.md" >}}
+      {{< filetree/file name="_index.fr.md" >}}
+      {{< filetree/file name="_index.ja.md" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+注意：Hugo 还支持[按内容目录管理翻译](https://gohugo.io/content-management/multilingual/#translation-by-content-directory)。
+
+## 翻译菜单项
+
+要翻译导航栏中的菜单项，我们需要设置 `identifier` 字段：
+
+```yaml {filename="hugo.yaml"}
+menu:
+  main:
+    - identifier: documentation
+      name: Documentation
+      pageRef: /docs
+      weight: 1
+    - identifier: blog
+      name: Blog
+      pageRef: /blog
+      weight: 2
+```
+
+## 翻译字符串
+
+要翻译其他地方的字符串，我们需要将翻译添加到相应的 `i18n` 文件中：
+
+```yaml {filename="i18n/fr.yaml"}
+readMore: Lire la suite
+```
+
+## 更多参考
+
+- [Hugo Multilingual Mode](https://gohugo.io/content-management/multilingual/)
+- [Hugo Multilingual Part 1: Content translation](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/)
+- [Hugo Multilingual Part 2: Strings localization](https://www.regisphilibert.com/blog/2018/08/hugo-multilingual-part-2-i18n-string-localization/)

exampleSite/content/docs/getting-started.ja.md

@@ -1,6 +0,0 @@
----
-title: はじめに
-weight: 1
----
-
-プロジェクトの紹介。

exampleSite/content/docs/getting-started.md

@@ -7,45 +7,57 @@ prev: /docs
 
 ## Quick Start from Template
 
-{{< icon "github" >}} [imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
+{{< icon "github" >}}&nbsp;[imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
 
-You will be able to quickly get started by using the above template repository.
+You could quickly get started by using the above template repository.
 
 <img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
 
 We have provided a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) which can help automatically build and deploy your site to GitHub Pages, and host it for free.
+For more options, check out [Deploy Site](../guide/deploy-site).
 
 [🌐 Demo ↗](https://imfing.github.io/hextra-starter-template/)
 
 ## Start as New Project
 
-### Prerequisites
+There are two main ways to add the Hextra theme to your Hugo project:
 
-Before we start, make sure we have [Hugo](https://gohugo.io/) installed.
-Please refer to Hugo's [official installation guide](https://gohugo.io/installation/) for more details.
+1. **Hugo Modules (Recommended)**: The simplest and recommended method. [Hugo modules](https://gohugo.io/hugo-modules/) let you pull in the theme directly from its online source. Theme is downloaded automatically and managed by Hugo.
 
-[Hugo modules](https://gohugo.io/hugo-modules/) are the recommended way to manage Hugo themes. To use Hugo modules, we need to install [Git](https://git-scm.com/) and [Go](https://go.dev/).
+2. **Git Submodule**: Alternatively, add Hextra as a [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). The theme is downloaded by Git and stored in your project's `themes` folder.
+
+### Setup Hextra as Hugo module
+
+#### Prerequisites
+
+Before starting, you need to have the following software installed:
+
+- [Hugo (extended version)](https://gohugo.io/installation/)
+- [Git](https://git-scm.com/)
+- [Go](https://go.dev/)
+
+#### Steps
 
 {{% steps %}}
 
 ### Initialize a new Hugo site
 
-```bash
-$ hugo new site my-site --format=yaml
+```shell
+hugo new site my-site --format=yaml
 ```
 
 ### Configure Hextra theme via module
 
 ```shell
 # initialize hugo module
-$ cd my-site
-$ hugo mod init github.com/username/my-site
+cd my-site
+hugo mod init github.com/username/my-site
 
 # add Hextra theme
-$ hugo mod get github.com/imfing/hextra
+hugo mod get github.com/imfing/hextra
 ```
 
-Edit `hugo.yaml` to enable Hextra theme:
+Configure `hugo.yaml` to use Hextra theme by adding the following:
 
 ```yaml
 module:
@@ -55,24 +67,120 @@ module:
 
 ### Create your first content pages
 
-Let's create a new content page for the home page and the documentation page:
+Create new content page for the home page and the documentation page:
 
 ```shell
-$ hugo new content/_index.md
-$ hugo new content/docs/_index.md
+hugo new content/_index.md
+hugo new content/docs/_index.md
 ```
 
 ### Preview the site locally
 
 ```shell
-$ hugo server
+hugo server --buildDrafts --disableFastRender
 ```
 
-Voila! You can see your new site at `http://localhost:1313/`.
+Voila, your new site preview is available at `http://localhost:1313/`.
 
 {{% /steps %}}
 
 
+{{% details title="How to update theme?" %}}
+
+To update all Hugo modules in your project to their latest versions, run the following command:
+
+```shell
+hugo mod get -u
+```
+
+To update Hextra to the [latest released version](https://github.com/imfing/hextra/releases), run the following command:
+
+```shell
+hugo mod get -u github.com/imfing/hextra
+```
+
+See [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) for more details.
+
+{{% /details %}}
+
+### Setup Hextra as Git submodule
+
+#### Prerequisites
+
+Before starting, you need to have the following software installed:
+
+- [Hugo (extended version)](https://gohugo.io/installation/)
+- [Git](https://git-scm.com/)
+
+#### Steps
+
+{{% steps %}}
+
+### Initialize a new Hugo site
+
+```shell
+hugo new site my-site --format=yaml
+```
+
+### Add Hextra theme as a Git submodule
+
+```shell
+git submodule add https://github.com/imfing/hextra.git themes/hextra
+```
+
+Configure `hugo.yaml` to use Hextra theme by adding the following:
+
+```yaml
+theme: hextra
+```
+
+### Create your first content pages
+
+Create new content page for the home page and the documentation page:
+
+```shell
+hugo new content/_index.md
+hugo new content/docs/_index.md
+```
+
+### Preview the site locally
+
+```shell
+hugo server --buildDrafts --disableFastRender
+```
+
+Your new site preview is available at `http://localhost:1313/`.
+
+{{% /steps %}}
+
+
+When using [CI/CD](https://en.wikipedia.org/wiki/CI/CD) for Hugo website deployment, it's essential to ensure that the following command is executed before running the `hugo` command.
+
+```shell
+git submodule update --init
+```
+
+Failure to run this command results in the theme folder not being populated with Hextra theme files, leading to a build failure.
+
+
+{{% details title="How to update theme?" %}}
+
+To update all submodules in your repository to their latest commits, run the following command:
+
+```shell
+git submodule update --remote
+```
+
+To update Hextra to the latest commit, run the following command:
+
+```shell
+git submodule update --remote themes/hextra
+```
+
+See [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more details.
+
+{{% /details %}}
+
 ## Next
 
 Explore the following sections to start adding more contents:

exampleSite/content/docs/getting-started.zh-cn.md

@@ -0,0 +1,142 @@
+---
+title: 快速开始
+weight: 1
+next: /docs/guide
+prev: /docs
+---
+
+## 使用模板快速开始
+
+{{< icon "github" >}}&nbsp;[imfing/hextra-starter-template](https://github.com/imfing/hextra-starter-template)
+
+通过使用上面的模板仓库，您将能够快速地开始。
+
+<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
+
+我们提供了一个 [GitHub Actions 工作流](https://docs.github.com/cn/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，它可以帮助您自动构建并部署您的网站到 GitHub Pages，并免费托管。
+
+[🌐 演示 ↗](https://imfing.github.io/hextra-starter-template/)
+
+## 作为新项目开始
+
+### 前提条件
+
+在开始之前，请确保我们已经安装了 [Hugo](https://gohugo.io/)。
+请参考 Hugo 的[官方安装指南](https://gohugo.io/installation/)以获取更多详情。
+
+[Hugo 模块](https://gohugo.io/hugo-modules/)是管理 Hugo 主题的推荐方式。要使用 Hugo 模块，我们需要安装 [Git](https://git-scm.com/) 和 [Go](https://go.dev/)。
+
+### 初始化 Hugo 站点
+
+```shell
+hugo new site my-site --format=yaml
+```
+
+### 通过 Hugo Module 安装
+
+```shell
+# 初始化 Hugo 模块
+cd my-site
+hugo mod init github.com/username/my-site
+
+# 添加 Hextra 
+hugo mod get github.com/imfing/hextra
+```
+
+编辑 `hugo.yaml` 以启用 Hextra：
+
+```yaml
+module:
+  imports:
+    - path: github.com/imfing/hextra
+```
+
+### 通过 Git Submodule 安装
+
+#### 先决条件
+
+在我们开始之前，你必须先确保以下软件已经安装：
+
+- [Hugo (extended version)](https://gohugo.io/installation/)
+- [Git](https://git-scm.com/)
+
+#### 步骤
+
+{{% steps %}}
+
+### 初始化 Hugo 站点
+
+```shell
+hugo new site my-site --format=yaml
+```
+
+### 将 Hextra 添加为 Git Submodule
+
+```shell
+git submodule add https://github.com/imfing/hextra.git themes/hextra
+```
+
+添加以下内容来配置 `hugo.yaml` 以使用 Hextra：
+
+```yaml
+theme: hextra
+```
+
+### 创建你的第一个内容页
+
+让我们为主页和文档页面创建一个新的内容页面：
+
+```shell
+hugo new content/_index.md
+hugo new content/docs/_index.md
+```
+
+### 在本地预览站点
+
+```shell
+hugo server --buildDrafts --disableFastRender
+```
+
+瞧！你现在可以在 `http://localhost:1313/` 看到你的新站点。
+
+{{% /steps %}}
+
+
+
+
+使用 [CI/CD](https://en.wikipedia.org/wiki/CI/CD) 进行部署时，必须确保在运行 `hugo` 命令之前执行以下命令。
+
+```shell
+git submodule update --init
+```
+
+如果不运行此命令，theme 中将不会存在 Hextra 文件，进而导致构建失败。
+
+
+{{% details title="如何更新主题？" %}}
+
+如需把项目中所有的 Hugo Modules 都升级到最新，在终端中运行此命令：
+
+```shell
+hugo mod get -u
+```
+
+如需把 Hextra 升级到[最新的发行版本](https://github.com/imfing/hextra/releases), 在终端中运行此命令：
+
+```shell
+hugo mod get -u github.com/imfing/hextra
+```
+
+如果你需要获得更多信息，参见 [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules).
+
+{{% /details %}}
+
+## 接下来
+
+探索这些文档以便添加更多内容：
+
+{{< cards >}}
+  {{< card link="../guide/organize-files" title="Organize Files" icon="document-duplicate" >}}
+  {{< card link="../guide/configuration" title="Configuration" icon="adjustments" >}}
+  {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
+{{< /cards >}}

exampleSite/content/docs/guide/_index.md

@@ -1,12 +1,15 @@
 ---
 title: Guide
 weight: 2
+prev: /docs/getting-started
 next: /docs/guide/organize-files
 sidebar:
   open: true
 ---
 
-Explore the following sections to learn to compose content using Hextra:
+Explore the following sections to learn how to use Hextra:
+
+<!--more-->
 
 {{< cards >}}
   {{< card link="organize-files" title="Organize Files" icon="document-duplicate" >}}
@@ -16,4 +19,5 @@ Explore the following sections to learn to compose content using Hextra:
   {{< card link="latex" title="LaTeX" icon="variable" >}}
   {{< card link="diagrams" title="Diagrams" icon="chart-square-bar" >}}
   {{< card link="shortcodes" title="Shortcodes" icon="template" >}}
+  {{< card link="deploy-site" title="Deploy Site" icon="server" >}}
 {{< /cards >}}

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

@@ -0,0 +1,22 @@
+---
+title: 指南
+weight: 2
+prev: /docs/getting-started
+next: /docs/guide/organize-files
+sidebar:
+  open: true
+---
+
+探索以下各节以学习如何使用 Hextra 编写内容：
+
+<!--more-->
+
+{{< cards >}}
+  {{< card link="organize-files" title="目录结构" icon="document-duplicate" >}}
+  {{< card link="configuration" title="配置" icon="adjustments" >}}
+  {{< card link="markdown" title="Markdown" icon="markdown" >}}
+  {{< card link="syntax-highlighting" title="代码高亮" icon="sparkles" >}}
+  {{< card link="latex" title="LaTeX 公式" icon="variable" >}}
+  {{< card link="diagrams" title="图表" icon="chart-square-bar" >}}
+  {{< card link="shortcodes" title="短代码" icon="template" >}}
+{{< /cards >}}

exampleSite/content/docs/guide/configuration.md

@@ -5,7 +5,9 @@ weight: 2
 
 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.
-You can find the config file for this site in `exampleSite/hugo.yaml` as a good starting point.
+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.
+
+<!--more-->
 
 ## Navigation
 
@@ -63,6 +65,24 @@ There are different types of menu items:
 
 These menu items can be sorted by setting the `weight` parameter.
 
+### Logo and Title
+
+To modify the default logo, edit `hugo.yaml` and add the path to your logo file under `static` directory.
+Optionally, you can change the link that users are redirected to when clicking on your logo, as well as set the width & height of the logo in pixels.
+
+```yaml {filename="hugo.yaml"}
+params:
+  navbar:
+    displayTitle: true
+    displayLogo: true
+    logo:
+      path: images/logo.svg
+      dark: images/logo-dark.svg
+      link: /
+      width: 40
+      height: 20
+```
+
 ## Sidebar
 
 ### Main Sidebar
@@ -70,6 +90,16 @@ These menu items can be sorted by setting the `weight` parameter.
 For the main sidebar, it is automatically generated from the structure of the content directory.
 See the [Organize Files](/docs/guide/organize-files) page for more details.
 
+To exclude a single page from the left sidebar, set the `sidebar.exclude` parameter in the front matter of the page:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+sidebar:
+  exclude: true
+---
+```
+
 ### Extra Links
 
 Sidebar extra links are defined under the `menu.sidebar` section in the config file:
@@ -109,16 +139,133 @@ To configure the page edit link, we can set the `params.editURL.base` parameter
 ```yaml {filename="hugo.yaml"}
 params:
   editURL:
+    enable: true
     base: "https://github.com/your-username/your-repo/edit/main"
 ```
 
-The edit links will be automatically generated for each page.
-If you want to set edit link for a specific page, you can set the `params.editURL` parameter in the front matter of the page:
+The edit links will be automatically generated for each page based on the provided url as root directory.
+If you want to set edit link for a specific page, you can set the `editURL` parameter in the front matter of the page:
 
 ```yaml {filename="content/docs/guide/configuration.md"}
 ---
 title: Configuration
-params:
-  editURL: "https://example.com/edit/this/page"
+editURL: "https://example.com/edit/this/page"
 ---
 ```
+
+## Footer
+
+### Copyright
+
+To modify the copyright text displayed in your website's footer, you'll need to create a file named `i18n/en.yaml`.
+In this file, specify your new copyright text as shown below:
+
+```yaml {filename="i18n/en.yaml"}
+copyright: "© 2023 YOUR TEXT HERE"
+```
+
+For your reference, an example [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) file can be found in the GitHub repository. Additionally, you could use Markdown format in the copyright text.
+
+## Others
+
+### Favicon
+
+To customize the [favicon](https://en.wikipedia.org/wiki/Favicon) for your site, place icon files under the `static` folder to override the [default favicons from the theme](https://github.com/imfing/hextra/tree/main/static):
+
+{{< filetree/container >}}
+  {{< filetree/folder name="static" >}}
+    {{< filetree/file name="android-chrome-192x192.png" >}}
+    {{< filetree/file name="android-chrome-512x512.png" >}}
+    {{< filetree/file name="apple-touch-icon.png" >}}
+    {{< filetree/file name="favicon-16x16.png" >}}
+    {{< filetree/file name="favicon-32x32.png" >}}
+    {{< filetree/file name="favicon-dark.svg" >}}
+    {{< filetree/file name="favicon.ico" >}}
+    {{< filetree/file name="favicon.svg" >}}
+    {{< filetree/file name="site.webmanifest" >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Include both `favicon.ico` and `favicon.svg` files in your project to ensure your site's favicons display correctly.
+
+While `favicon.ico` is generally for older browsers, `favicon.svg` is supported by modern ones. The optional `favicon-dark.svg` can be included for a tailored experience in dark mode.
+Feel free to use tools like [favicon.io](https://favicon.io/) or [favycon](https://github.com/ruisaraiva19/favycon) to generate these icons.
+
+### Theme Configuration
+
+Use the `theme` setting to configure the default theme mode and toggle button, allowing visitors to switch between light or dark mode.
+
+```yaml {filename="hugo.yaml"}
+params:
+  theme:
+    # light | dark | system
+    default: system
+    displayToggle: true
+```
+
+Options for `theme.default`:
+
+- `light` - always use light mode
+- `dark` - always use dark mode
+- `system` - sync with the operating system setting (default)
+
+The `theme.displayToggle` parameter allows you to display a toggle button for changing themes.
+When set to `true`, visitors can switch between light or dark mode, overriding the default setting.
+
+### Page Width
+
+The width of the page can be customized by the `params.page.width` parameter in the config file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  page:
+    # full (100%), wide (90rem), normal (1280px)
+    width: wide
+```
+
+There are three available options: `full`, `wide`, and `normal`. By default, the page width is set to `normal`.
+
+Similarly, the width of the navbar and footer can be customized by the `params.navbar.width` and `params.footer.width` parameters.
+
+### Search Index
+
+Full-text search powered by [FlexSearch](https://github.com/nextapps-de/flexsearch) is enabled by default.
+To customize the search index, set the `params.search.flexsearch.index` parameter in the config file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  # Search
+  search:
+    enable: true
+    type: flexsearch
+
+    flexsearch:
+      # index page by: content | summary | heading | title
+      index: content
+```
+
+Options for `flexsearch.index`:
+
+- `content` - full content of the page (default)
+- `summary` - summary of the page, see [Hugo Content Summaries](https://gohugo.io/content-management/summaries/) for more details
+- `heading` - level 1 and level 2 headings
+- `title` - only include the page title
+
+To exclude a page from the search index, set the `excludeSearch: true` in the front matter of the page:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+excludeSearch: true
+---
+```
+
+### Google Analytics
+
+To enable [Google Analytics](https://marketingplatform.google.com/about/analytics/), set `services.googleAnalytics.ID` flag in `hugo.yaml`:
+
+```yaml {filename="hugo.yaml"}
+services:
+  googleAnalytics:
+    ID: G-MEASUREMENT_ID
+```

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

@@ -0,0 +1,239 @@
+---
+title: 配置文件
+weight: 2
+---
+
+Hugo 从 Hugo 网站根目录下的 `hugo.yaml` 读取配置。
+在配置文件中，您可以配置站点的所有选项。
+你可以在 `exampleSite/hugo.yaml` 中找到此站点的配置文件作为开始。
+
+<!--more-->
+
+## 导航栏
+
+### 菜单
+
+右上角的菜单在配置文件的 `menu.main` 中配置：
+
+```yaml {filename="hugo.yaml"}
+menu:
+  main:
+    - name: Documentation
+      pageRef: /docs
+      weight: 1
+    - name: Blog
+      pageRef: /blog
+      weight: 2
+    - name: About
+      pageRef: /about
+      weight: 3
+    - name: Search
+      weight: 4
+      params:
+        type: search
+    - name: GitHub
+      weight: 5
+      url: "https://github.com/imfing/hextra"
+      params:
+        icon: github
+```
+
+有几种不同类型的菜单项：
+
+1. Link to a page in the site with `pageRef`
+    ```yaml
+    - name: Documentation
+      pageRef: /docs
+    ```
+2. Link to an external URL with `url`
+    ```yaml
+    - name: GitHub
+      url: "https://github.com"
+    ```
+3. Search bar with `type: search`
+    ```yaml
+    - name: Search
+      params:
+        type: search
+    ```
+4. Icon
+    ```yaml
+    - name: GitHub
+      params:
+        icon: github
+    ```
+
+这些菜单项可以通过设置 `weight` 进行排序。
+
+## 侧边栏
+
+### 主侧边栏
+
+主侧边栏是自动从 `content` 目录结构生成的。
+有关更多详细信息，转至 [目录结构](/docs/guide/organize-files)。
+
+### 额外链接
+
+侧边栏的额外链接在配置文件的 `menu.sidebar` 部分中配置：
+
+```yaml {filename="hugo.yaml"}
+menu:
+  sidebar:
+    - name: More
+      params:
+        type: separator
+      weight: 1
+    - name: "About"
+      pageRef: "/about"
+      weight: 2
+    - name: "Hugo Docs ↗"
+      url: "https://gohugo.io/documentation/"
+      weight: 3
+```
+
+## 右侧边栏
+
+### 目录
+
+目录是根据内容文件中的标题自动生成的，可以在 `front matter` 设置 `toc：false` 来禁用它。
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+toc: false
+---
+```
+
+### 编辑此页链接
+
+要配置编辑此页链接，我们可以在配置文件中设置 `params.editURL.base`：
+```yaml {filename="hugo.yaml"}
+params:
+  editURL:
+    base: "https://github.com/your-username/your-repo/edit/main"
+```
+
+将为每个页面自动生成编辑链接。
+如需为特定页面设置编辑链接，可以在页面的 `front matter` 中设置 `editURL`：
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+editURL: "https://example.com/edit/this/page"
+---
+```
+## Footer
+
+### 版权声明
+
+如需修改网站页脚中显示的版权文本，您需要创建一个名为“i18n/en.yaml”的文件。
+在此文件中，填写新的版权文本，像这样：
+
+```yaml {filename="i18n/en.yaml"}
+copyright: "© 2023 YOUR TEXT HERE"
+```
+你可以在 GitHub 存储库中找到示例 [`i18n/en.yaml`](https://github.com/imfing/hextra/blob/main/i18n/en.yaml) 文件。另外，你可以在版权文本中使用 Markdown 格式。
+
+## 其他
+
+### Favicon
+
+如需自定义 [favicon](https://en.wikipedia.org/wiki/Favicon)，请将图标文件放在 `static` 文件夹下以覆盖 [主题中的默认 favicon](https://github.com/imfing/hextra/tree/main/static)：
+
+{{< filetree/container >}}
+  {{< filetree/folder name="static" >}}
+    {{< filetree/file name="android-chrome-192x192.png" >}}
+    {{< filetree/file name="android-chrome-512x512.png" >}}
+    {{< filetree/file name="apple-touch-icon.png" >}}
+    {{< filetree/file name="favicon-16x16.png" >}}
+    {{< filetree/file name="favicon-32x32.png" >}}
+    {{< filetree/file name="favicon-dark.svg" >}}
+    {{< filetree/file name="favicon.ico" >}}
+    {{< filetree/file name="favicon.svg" >}}
+    {{< filetree/file name="site.webmanifest" >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+在您的项目中包含 `favicon.ico` 和 `favicon.svg` 文件，以确保网站的网站图标正确显示。
+
+虽然 `favicon.ico` 通常适用于较旧的浏览器，但 `favicon.svg` 受到现代浏览器的支持，所以更现代的做法是添加 `favicon-dark.svg` 以便在黑暗模式下提供较好的体验体验。
+
+请随意使用 [favicon.io](https://favicon.io/) 或 [favycon](https://github.com/ruisaraiva19/favycon) 等工具来生成这些图标。
+
+### 颜色主题配置
+
+使用`theme`设置来配置默认主题模式和切换按钮，允许访问者在浅色或深色模式之间切换。
+
+```yaml {filename="hugo.yaml"}
+params:
+  theme:
+    # light | dark | system
+    default: system
+    displayToggle: true
+```
+
+`theme.default` 的可选项：
+
+- `light` - 仅使用浅色模式
+- `dark` - 仅使用神色模式
+- `system` - 跟随系统
+
+`theme.displayToggle` 控制显示用于更改主题的切换按钮。
+当设置为“true”时，访问者可以在浅色或深色模式之间切换，覆盖默认设置。
+
+### 页宽
+
+页面的宽度可以通过配置文件中的`params.page.width`参数来调整：
+
+```yaml {filename="hugo.yaml"}
+params:
+  page:
+    # full (100%), wide (90rem), normal (1280px)
+    width: wide
+```
+
+有三个可选项：`full`, `wide`, and `normal`. 默认的页宽模式是 `normal`.
+
+同样的，导航栏和 `footer` 的宽度也可通过 `params.navbar.width` 和 `params.footer.width` 调整。
+
+### 搜索
+
+默认情况下启用由 [FlexSearch](https://github.com/nextapps-de/flexsearch) 提供全文搜索。
+要自定义搜索索引，请在配置文件中设置 `params.search.flexsearch.index` ：
+
+```yaml {filename="hugo.yaml"}
+params:
+  # Search
+  search:
+    enable: true
+    type: flexsearch
+
+    flexsearch:
+      # index page by: content | summary | heading | title
+      index: content
+```
+`flexsearch.index` 的可选项：
+
+- `content` - 全内容搜索
+- `summary` - 概述 [Hugo Content Summaries](https://gohugo.io/content-management/summaries/)
+- `heading` - 一级和二级标题
+- `title` - 仅搜索标题
+
+要从搜索索引中排除页面，更改 front matter 中的 `excludeSearch: true`:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+excludeSearch: true
+---
+```
+
+### Google Analytics
+
+要启用 [Google Analytics](https://marketingplatform.google.com/about/analytics/)，设置 `services.googleAnalytics.ID`:
+
+```yaml {filename="hugo.yaml"}
+services:
+  googleAnalytics:
+    ID: G-MEASUREMENT_ID
+```

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

@@ -0,0 +1,161 @@
+---
+title: Deploy Site
+prev: /docs/guide/shortcodes
+next: /docs/advanced
+---
+
+Hugo generates static websites, allowing for flexible hosting options.
+This page provides guides for deploying your Hextra site on various platforms.
+
+<!--more-->
+
+
+## GitHub Pages
+
+[GitHub Pages](https://docs.github.com/pages) is the recommended way to deploy and host your website for free.
+
+If you bootstrap the site using [hextra-starter-template](https://github.com/imfing/hextra-starter-template), it has provided GitHub Actions workflow out-of-the-box that helps automatically deploy to GitHub Pages.
+
+{{% details title="GitHub Actions Configuration" closed="true" %}}
+
+Below is an example configuration from [hextra-starter-template](https://github.com/imfing/hextra-starter-template):
+
+```yaml {filename=".github/workflows/pages.yaml"}
+# Sample workflow for building and deploying a Hugo site to GitHub Pages
+name: Deploy Hugo site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.117.0
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.117.0'
+          extended: true
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: |
+          hugo \
+            --gc --minify \
+            --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./public
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+```
+
+{{% /details %}}
+
+
+{{< callout >}}
+  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 >}}
+
+By default, the above GitHub Actions workflow `.github/workflows/pages.yaml` assumes that the site is deploying to `https://<USERNAME>.github.io/<REPO>/`.
+
+If you are deploying to `https://<USERNAME>.github.io/` then modify the `--baseURL`:
+
+```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]}
+run: |
+  hugo \
+    --gc --minify \
+    --baseURL "https://${{ github.repository_owner }}.github.io/"
+```
+
+If you are deploying to your own domain, please change the `--baseURL` value accordingly.
+
+
+## Cloudflare Pages
+
+1. Put your site source code in a Git repository (e.g. GitHub)
+2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account
+3. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**
+4. Select the repository, and in the **Set up builds and deployments** section, provide the following information:
+
+| Configuration     | Value                |
+| ----------------- | -------------------- |
+| Production branch | `main`               |
+| Build command     | `hugo --gc --minify` |
+| Build directory   | `public`             |
+
+For more details, check out:
+- [Deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages).
+- [Language support and tools](https://developers.cloudflare.com/pages/platform/language-support-and-tools/).
+
+
+## Netlify
+
+1. Push your code to your Git repository (GitHub, GitLab, etc.)
+2. [Import the project](https://app.netlify.com/start) to Netlify
+3. If you are not using [hextra-starter-template][hextra-starter-template], configure the following manually:
+   - Configure the Build command to `hugo --gc --minify`
+   - Specify the Publish directory to `public`
+   - Add Environment variable `HUGO_VERSION` and set to `0.119.0`
+4. Deploy!
+
+Check [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) for more details.
+
+
+## Vercel
+
+1. Push your code to your Git repository (GitHub, GitLab, etc.)
+2. Go to [Vercel Dashboard](https://vercel.com/dashboard) and import your Hugo project
+3. Configure the project, select Hugo as Framework Preset
+4. Override the Build Command and Install command:
+   1. Set Build Command to `hugo --gc --minify`
+   2. Set Install Command to `yum install golang`
+
+![Vercel Deployment Configuration](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3)

exampleSite/content/docs/guide/diagrams.md

@@ -1,6 +1,7 @@
 ---
 title: Diagrams
 weight: 6
+next: /docs/guide/shortcodes
 ---
 
 Currently, Hextra supports [Mermaid](#mermaid) for diagrams.

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

@@ -0,0 +1,53 @@
+---
+title: 图表
+weight: 6
+next: /docs/guide/shortcodes
+---
+
+目前，Hextra 支持 [Mermaid](#mermaid) 的图表。
+
+<!--more-->
+
+## Mermaid
+
+[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它的文本定义和 Markdown 类似，可在浏览器中动态创建图表。例如：流程图、序列图、饼图等。
+
+在 Hextra 中使用 Mermaid 就像使用代码块一样简单：
+
+````markdown
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+````
+
+将呈现为：
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+Sequence diagram：
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->>John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail!
+    John-->>Alice: Great!
+    John->>Bob: How about you?
+    Bob-->>John: Jolly good!
+```
+
+如需获取更多信息，转至 [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/)。

exampleSite/content/docs/guide/latex.md

@@ -6,6 +6,8 @@ math: true
 
 $\KaTeX$ is used for rendering LaTeX math expressions. It can be enabled per page by setting `math` to `true` in the page front matter.
 
+<!--more-->
+
 ```yaml {filename="Markdown"}
 ---
 title: "My Page with LaTeX"

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

@@ -0,0 +1,59 @@
+---
+title: "LaTeX 公式"
+weight: 4
+math: true
+---
+
+$\KaTeX$ 用于呈现 LaTeX 数学表达式。可在 `frontmatter` 将 `math` 设置为 `true` 来启用。
+
+<!--more-->
+
+```yaml {filename="Markdown"}
+---
+title: "My Page with LaTeX"
+math: true
+---
+```
+
+启用后，KaTeX 中的脚本，样式表和字体将自动包含在你的网站中。这样就可以在 Markdown 内容中使用 LaTeX 数学表达式。
+
+## 示例
+
+Markdown 内容支持行内和独立段落的 LaTeX 数学表达式。
+
+### 行内
+
+```markdown {filename="page.md"}
+This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
+```
+
+This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
+
+### 独立段落
+
+```markdown {filename="page.md"}
+$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+```
+
+将被渲染为：
+
+$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+
+
+## 支持的功能
+
+有关支持的符号列表，转至 [KaTeX 支持的公式](https://katex.org/docs/supported.html)。
+
+## 化学表达式
+
+通过 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 支持化学表达式。
+
+行内：$\ce{H2O}$ 是水。
+
+独立段落：
+
+```markdown {filename="page.md"}
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$

exampleSite/content/docs/guide/markdown.md

@@ -46,7 +46,7 @@ Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-
 ### Code Blocks
 
 {{< cards >}}
-    {{< card link="syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
+  {{< card link="../../guide/syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
 {{< /cards >}}
 
 ### Lists

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

@@ -0,0 +1,105 @@
+---
+title: Markdown
+weight: 2
+---
+
+Hugo 支持 [Markdown](https://en.wikipedia.org/wiki/Markdown) 来书写内容，创建列表等。本页将向你展示一些最常见的 Markdown 语法示例。
+
+<!--more-->
+
+## Markdown 示例
+
+### 文本样式
+
+| Style   | Syntax     | Example   | Output   |
+| --------  | -------- | ------ | ------ |
+| Bold | `**bold text**` | `**bold text**` | **bold text** |
+| Italic | `*italicized text*` | `*italicized text* | *italicized text* |
+| Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ |
+| Subscript | `<sub></sub>` | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
+| Superscript | `<sup></sup>` | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
+
+### 引用
+
+带角标的块引用：
+
+> Don't communicate by sharing memory, share memory by communicating.<br>
+> — <cite>Rob Pike[^1]</cite>
+
+[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
+
+### 表格
+
+表格并非核心 Markdown 规范，但 Hugo 支持开箱即用的表格：
+
+   Name | Age
+--------|------
+    Bob | 27
+  Alice | 23
+
+#### Markdown 表格中的内联
+
+| Italics   | Bold     | Code   |
+| --------  | -------- | ------ |
+| *italics* | **bold** | `code` |
+
+### 代码块
+
+{{< cards >}}
+  {{< card link="../../guide/syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
+{{< /cards >}}
+
+### 列表
+
+#### 有序列表
+
+1. First item
+2. Second item
+3. Third item
+
+#### 无序列表
+
+* List item
+* Another item
+* And another item
+
+#### 嵌套列表
+
+* Fruit
+  * Apple
+  * Orange
+  * Banana
+* Dairy
+  * Milk
+  * Cheese
+
+### 图片
+
+![](https://source.unsplash.com/featured/800x600?landscape)
+
+带有标题：
+
+![](https://source.unsplash.com/featured/800x600?landscape "Unsplash Landscape")
+
+## 配置
+
+Hugo 使用 [Goldmark](https://github.com/yuin/goldmark) 解析 Markdown。
+Markdown 渲染可以在 `hugo.yaml` 中的 `markup.goldmark` 中配置。以下是Hextra的默认配置：
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    renderer:
+      unsafe: true
+  highlight:
+    noClasses: false
+```
+
+如需了解更多选项，转至 [Configure Markup](https://gohugo.io/getting-started/configuration-markup/)。
+
+## 参考资料
+
+* [Markdown Guide](https://www.markdownguide.org/)
+* [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+* [Markdown Tutorial](https://www.markdowntutorial.com/)
+* [Markdown Reference](https://commonmark.org/help/)

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

@@ -1,12 +1,15 @@
 ---
 title: Organize Files
 weight: 1
+prev: /docs/guide
 ---
 
 ## Directory Structure
 
 By default, Hugo searches for Markdown files in the `content` directory, and the structure of the directory determines the final output structure of your website.
-Take the example site as an example:
+Take this site as an example:
+
+<!--more-->
 
 {{< filetree/container >}}
   {{< filetree/folder name="content" >}}
@@ -42,6 +45,28 @@ content
     └── post-1.md // <- /blog/post-1/
 ```
 
+## Layouts
+
+Hextra offers three layouts for different content types:
+
+| Layout    | Directory             | Features                                                         |
+| :-------- | :-------------------- | :--------------------------------------------------------------- |
+| `docs`    | `content/docs/`       | Ideal for structured documentation, same as this section.        |
+| `blog`    | `content/blog/`       | For blog postings, with both listing and detailed article views. |
+| `default` | All other directories | Single-page article view without sidebar.                        |
+
+To customize a section to mirror the behavior of a built-in layout, specify the desired type in the front matter of the section's `_index.md`.
+
+```yaml {filename="content/my-docs/_index.md"}
+---
+title: My Docs
+cascade:
+  type: docs
+---
+```
+
+The above example configuration ensures that the content files inside `content/my-docs/` will be treated as documentation (`docs` type) by default.
+
 ## Sidebar Navigation
 
 The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the `weight` parameter in the front matter of the Markdown files.
@@ -59,4 +84,65 @@ weight: 2
 
 ## Configure Content Directory
 
-If we need to use a different directory for our content, we can do so by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in our site configuration file.
+By default, the root `content/` directory is used by Hugo to build the site.
+If you need to use a different directory for content, for example `docs/`, this can be done by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in the site configuration `hugo.yaml`.
+
+## Add Images
+
+To add images, the easiest way is to put the image files in the same directory as the Markdown file.
+For example, add an image file `image.png` alongside the `my-page.md` file:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/file name="my-page.md" >}}
+        {{< filetree/file name="image.png" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Then, we can use the following Markdown syntax to add the image to the content:
+
+```markdown {filename="content/docs/my-page.md"}
+![](image.png)
+```
+
+We can also utilize the [page bundles][page-bundles] feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the `my-page.md` file into a directory `my-page` and put the content into a file named `index.md`, and put the image files inside the `my-page` directory:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/folder name="my-page" >}}
+            {{< filetree/file name="index.md" >}}
+            {{< filetree/file name="image.png" >}}
+        {{< /filetree/folder >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+```markdown {filename="content/docs/my-page/index.md"}
+![](image.png)
+```
+
+Alternatively, we can also put the image files in the `static` directory, which will make the images available for all pages:
+
+{{< filetree/container >}}
+  {{< filetree/folder name="static" >}}
+    {{< filetree/folder name="images" >}}
+        {{< filetree/file name="image.png" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/folder name="docs" >}}
+        {{< filetree/file name="my-page.md" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+Note that the image path begins with a slash `/` and is relative to the static directory:
+
+```markdown {filename="content/docs/my-page.md"}
+![](/images/image.png)
+```
+
+[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles

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

@@ -0,0 +1,65 @@
+---
+title: 目录结构
+weight: 1
+prev: /docs/guide
+---
+
+## 目录结构
+
+默认情况下，Hugo 在 `context` 目录中搜索 Markdown 文件，目录的结构决定了网站的最终输出结构。
+以示例网站为例：
+
+<!--more-->
+
+{{< filetree/container >}}
+  {{< filetree/folder name="content" >}}
+    {{< filetree/file name="_index.md" >}}
+    {{< filetree/folder name="docs" state="open" >}}
+      {{< filetree/file name="_index.md" >}}
+      {{< filetree/file name="getting-started.md" >}}
+      {{< filetree/folder name="guide" state="open" >}}
+        {{< filetree/file name="_index.md" >}}
+        {{< filetree/file name="organize-files.md" >}}
+      {{< /filetree/folder >}}
+    {{< /filetree/folder >}}
+    {{< filetree/folder name="blog" state="open" >}}
+      {{< filetree/file name="_index.md" >}}
+      {{< filetree/file name="post-1.md" >}}
+    {{< /filetree/folder >}}
+  {{< /filetree/folder >}}
+{{< /filetree/container >}}
+
+每个 `_index.md` 文件都是相应部分的索引页，其他 Markdown 文件则是常规页面。
+
+```
+content
+├── _index.md // <- /
+├── docs
+│   ├── _index.md // <- /docs/
+│   ├── getting-started.md // <- /docs/getting-started/
+│   └── guide
+│       ├── _index.md // <- /docs/guide/
+│       └── organize-files.md // <- /docs/guide/organize-files/
+└── blog
+    ├── _index.md // <- /blog/
+    └── post-1.md // <- /blog/post-1/
+```
+
+## 侧边栏导航
+
+侧边栏导航是根据内容组织的字母顺序自动生成的。要手动配置侧边栏顺序，可以在 Markdown 文件的 `frontmatter ` 中使用 `weight` 配置。
+
+```yaml {filename="content/docs/guide/_index.md"}
+---
+title: Guide
+weight: 2
+---
+```
+
+{{< callout emoji="ℹ️">}}
+  建议侧边栏不要太深。如果内容太多，请考虑 **将它们分成多个部分**。
+{{< /callout >}}
+
+## 配置内容目录
+
+如果需要为的内容使用不同的目录，可以在站点配置文件中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 来实现。

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

@@ -1,6 +0,0 @@
----
-title: コンポーネント
-weight: 2
----
-
-Hextraは、[Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/)に基づいたさまざまな組み込みコンポーネントを提供しています。

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

@@ -1,6 +1,8 @@
 ---
 title: Shortcodes
 weight: 9
+prev: /docs/guide/diagrams
+next: /docs/guide/shortcodes/callout
 ---
 
 [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/) are simple snippets inside your content files calling built-in or custom templates.
@@ -9,8 +11,9 @@ Hextra provides a collection of beautiful shortcodes to enhance your content.
 
 
 {{< cards >}}
-  {{< card link="callouts" title="Callouts" icon="warning" >}}
+  {{< card link="callout" title="Callout" icon="warning" >}}
   {{< card link="cards" title="Cards" icon="card" >}}
+  {{< card link="details" title="Details" icon="chevron-right" >}}
   {{< card link="filetree" title="FileTree" icon="folder-tree" >}}
   {{< card link="icon" title="Icon" icon="badge-check" >}}
   {{< card link="steps" title="Steps" icon="one" >}}

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

@@ -0,0 +1,19 @@
+---
+title: 短代码
+weight: 9
+prev: /docs/guide/diagrams
+next: /docs/guide/shortcodes/callout
+---
+
+[Hugo 短代码](https://gohugo.io/content-management/shortcodes/) 是你的内容文件中调用内置或自定义模板的简单片段。
+
+Hextra 提供了一系列美观的短代码以增强你的内容。
+
+{{< cards >}}
+  {{< card link="callout" title="注意事项" icon="warning" >}}
+  {{< card link="cards" title="卡片" icon="card" >}}
+  {{< card link="filetree" title="文件树" icon="folder-tree" >}}
+  {{< card link="icon" title="图标" icon="badge-check" >}}
+  {{< card link="steps" title="步骤" icon="one" >}}
+  {{< card link="tabs" title="标签" icon="collection" >}}
+{{< /cards >}}

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

@@ -1,10 +1,15 @@
 ---
 title: Callout Component
 linkTitle: Callout
+aliases:
+- callouts
+prev: /docs/guide/shortcodes
 ---
 
 A built-in component to show important information to the reader.
 
+<!--more-->
+
 ## Example
 
 {{< callout emoji="👾">}}

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

@@ -6,20 +6,21 @@ linkTitle: Cards
 ## Example
 
 {{< cards >}}
-  {{< card link="/" title="Callout" icon="warning" >}}
+  {{< card link="../callout" title="Callout" icon="warning" >}}
   {{< card link="/" title="No Icon" >}}
 {{< /cards >}}
 
 {{< cards >}}
   {{< card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" >}}
+  {{< card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." >}}
+  {{< card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" >}}
 {{< /cards >}}
 
-
 ## Usage
 
 ```
 {{</* cards */>}}
-  {{</* card link="/" title="Callout" icon="warning" */>}}
+  {{</* card link="../callout" title="Callout" icon="warning" */>}}
   {{</* card link="/" title="No Icon" */>}}
 {{</* /cards */>}}
 ```
@@ -27,5 +28,37 @@ linkTitle: Cards
 ```
 {{</* cards */>}}
   {{</* card link="/" title="Image Card" image="https://source.unsplash.com/featured/800x600?landscape" subtitle="Unsplash Landscape" */>}}
+  {{</* card link="/" title="Local Image" image="/images/card-image-unprocessed.jpg" subtitle="Raw image under static directory." */>}}
+  {{</* card link="/" title="Local Image" image="images/space.jpg" subtitle="Image under assets directory, processed by Hugo." method="Resize" options="600x q80 webp" */>}}
 {{</* /cards */>}}
 ```
+
+## Card Parameters
+
+| Parameter  | Description                           |
+|----------- |---------------------------------------|
+| `link`     | URL (internal or external).           |
+| `title`    | Title heading for the card.           |
+| `subtitle` | Subtitle heading (supports Markdown). |
+| `icon`     | Name of the icon.                     |
+
+## Image Card
+
+Additionally, the card supports adding image and processing through these parameters:
+
+| Parameter  | Description                                 |
+|----------- |---------------------------------------------|
+| `image`    | Specifies the image URL for the card.       |
+| `method`   | Sets Hugo's image processing method.        |
+| `options`  | Configures Hugo's image processing options. |
+
+Card supports three kinds of images:
+
+1. Remote image: the full URL in the `image` parameter.
+2. Static image: use the relative path in Hugo's `static/` directory.
+3. Processed image: use the relative path in Hugo's `assets/` directory.
+
+Hextra auto-detects if image processing is needed during build and applies the `options` parameter or default settings (Resize, 800x, Quality 80, WebP Format).
+It currently supports these `method`: `Resize`, `Fit`, `Fill` and `Crop`.
+
+For more on Hugo's built in image processing commands, methods, and options see their [Image Processing Documentation](https://gohugo.io/content-management/image-processing/).

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

@@ -0,0 +1,43 @@
+---
+title: Details
+---
+
+A built-in component to display a collapsible content.
+
+<!--more-->
+
+## Example
+
+{{% details title="Details" %}}
+
+This is the content of the details.
+
+Markdown is **supported**.
+
+{{% /details %}}
+
+{{% details title="Click me to reveal" closed="true" %}}
+
+This will be hidden by default.
+
+{{% /details %}}
+
+## Usage
+
+````markdown
+{{%/* details title="Details" */%}}
+
+This is the content of the details.
+
+Markdown is **supported**.
+
+{{%/* /details */%}}
+````
+
+````markdown
+{{%/* details title="Click me to reveal" closed="true" */%}}
+
+This will be hidden by default.
+
+{{%/* /details */%}}
+````

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

@@ -8,7 +8,9 @@ To use this shortcode inline, inline shortcode needs to be enabled in the config
 enableInlineShortcodes: true
 ```
 
-The list of available icons can be found in `data/icons.yaml`.
+List of available icons can be found in [`data/icons.yaml`](https://github.com/imfing/hextra/blob/main/data/icons.yaml).
+
+<!--more-->
 
 ## Example
 
@@ -25,14 +27,20 @@ The list of available icons can be found in `data/icons.yaml`.
 
 [Heroicons](https://v1.heroicons.com/) v1 outline icons are available out of the box.
 
-You can also add your own icons by adding them to `data/icon.yaml`:
+### How to add your own icons
 
-```yaml {filename="data/icon.yaml"}
+Create `data/icons.yaml` file, then add your own SVG icons in the following format:
+
+```yaml {filename="data/icons.yaml"}
 your-icon: <svg>your icon svg content</svg>
 ```
 
-which can then be used like this:
+It then can be used in the shortcode like this:
 
 ```
 {{</* icon "your-icon" */>}}
+
+{{</* card icon="your-icon" */>}}
 ```
+
+Tip: [Iconify Design](https://iconify.design/) is a great place to find SVG icons for your site.

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

@@ -29,6 +29,7 @@ Put Markdown h3 header within `steps` shortcode.
 
 ```
 {{%/* steps */%}}
+
 ### Step 1
 
 This is the first step.
@@ -36,5 +37,6 @@ This is the first step.
 ### Step 2
 
 This is the second step.
+
 {{%/* /steps */%}}
 ```

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

@@ -1,5 +1,6 @@
 ---
 title: Tabs
+next: /docs/guide/deploy-site
 ---
 
 ## Example
@@ -49,3 +50,44 @@ The `YAML` tab will be selected by default.
 {{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
 
 {{< /tabs >}}
+
+
+### Use Markdown
+
+Markdown syntax including code block is also supported:
+
+````
+{{</* tabs items="JSON,YAML,TOML" */>}}
+
+  {{</* tab */>}}
+  ```json
+  { "hello": "world" }
+  ```
+  {{</* /tab */>}}
+
+  ... add other tabs similarly
+
+{{</* /tabs */>}}
+````
+
+{{< tabs items="JSON,YAML,TOML" >}}
+
+  {{< tab >}}
+  ```json
+  { "hello": "world" }
+  ```
+  {{< /tab >}}
+
+  {{< tab >}}
+  ```yaml
+  hello: world
+  ```
+  {{< /tab >}}
+
+  {{< tab >}}
+  ```toml
+  hello = "world"
+  ```
+  {{< /tab >}}
+
+{{< /tabs >}}

exampleSite/content/docs/guide/syntax-highlighting.md

@@ -6,6 +6,8 @@ weight: 3
 Hugo uses [Chroma](https://github.com/alecthomas/chroma), a general purpose syntax highlighter in pure Go, for syntax highlighting.
 It is recommended to use backticks for code blocks in Markdown content. For example:
 
+<!--more-->
+
 ````markdown {filename="Markdown"}
 ```python
 def say_hello():
@@ -84,4 +86,4 @@ By default, copy button is enabled for code blocks.
 
 ## Supported Languages
 
-For a list of supported languages, please see [Chroma's documentation](https://github.com/alecthomas/chroma#supported-languages).
+For a list of supported languages, please see the [Chroma documentation](https://github.com/alecthomas/chroma#supported-languages).

exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md

@@ -0,0 +1,89 @@
+---
+title: "代码高亮"
+weight: 3
+---
+
+Hugo 使用 [Chroma](https://github.com/alecthomas/chroma)，一种纯 Golang 实现的代码高亮渲染器。
+建议对 Markdown 内容中的代码块使用反引号，例如：
+
+<!--more-->
+
+````markdown {filename="Markdown"}
+```python
+def say_hello():
+    print("Hello!")
+```
+````
+
+将呈现为：
+
+```python
+def say_hello():
+    print("Hello!")
+```
+
+## 特性
+
+### 文件名
+
+要向代码块添加文件名或标题，请设置 `filename`：
+
+````markdown {filename="Markdown"}
+```python {filename="hello.py"}
+def say_hello():
+    print("Hello!")
+```
+````
+
+```python {filename="hello.py"}
+def say_hello():
+    print("Hello!")
+```
+
+### 行号
+
+如需设置行号，将 `linenos` 设置为 `table`，并将 `linenostart` 设置为起始行号：
+
+````markdown {filename="Markdown"}
+```python {linenos=table,linenostart=42}
+def say_hello():
+    print("Hello!")
+```
+````
+
+```python {linenos=table,linenostart=42}
+def say_hello():
+    print("Hello!")
+```
+
+### 高亮行
+
+显示高亮行，设置 `hl_lines` 为行号：
+
+````markdown {filename="Markdown"}
+```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
+def say_hello():
+    print("Hello!")
+
+def main():
+    say_hello()
+```
+````
+
+```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
+def say_hello():
+    print("Hello!")
+
+def main():
+    say_hello()
+```
+
+
+### 复制按钮
+
+默认情况下，代码块复制按钮已自动启用。
+
+
+## 支持的编程语言
+
+如需了解支持的编程语言，转至 [Chroma's documentation](https://github.com/alecthomas/chroma#supported-languages)。

exampleSite/content/showcase/index.md

@@ -0,0 +1,19 @@
+---
+title: Showcase
+description: "Open source projects powered by Hextra."
+toc: false
+layout: wide
+---
+
+<div class="mt-4"></div>
+
+<p class="mb-12 text-center text-lg text-gray-500 dark:text-gray-400">
+Open source projects powered by Hextra.
+</p>
+
+{{< cards >}}
+  {{< card link="https://developers.osuny.org" title="Osuny" image="https://raw.githubusercontent.com/noesya/osuny-developers/main/static/images/showcase-hextra/screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://getporter.org/" title="Porter" image="https://repository-images.githubusercontent.com/155893691/aa249c80-fcf3-11ea-93b0-30079e8d7de4" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://lutheranconfessions.org/" title="LutheranConfessions" image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://github.com/imfing/hextra-starter-template/" title="Hextra Starter Template" image="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+{{< /cards >}}

exampleSite/content/showcase/index.zh-cn.md

@@ -0,0 +1,19 @@
+---
+title: 项目展示
+description: "由 Hextra 驱动的开源网站和项目。"
+toc: false
+layout: wide
+---
+
+<div class="mt-4"></div>
+
+<p class="mb-12 text-center text-lg text-gray-500 dark:text-gray-400">
+由 Hextra 驱动的开源网站和项目。
+</p>
+
+{{< cards >}}
+  {{< card link="https://developers.osuny.org" title="Osuny" image="https://raw.githubusercontent.com/noesya/osuny-developers/main/static/images/showcase-hextra/screenshot.png" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://getporter.org/" title="Porter" image="https://repository-images.githubusercontent.com/155893691/aa249c80-fcf3-11ea-93b0-30079e8d7de4" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://lutheranconfessions.org/" title="LutheranConfessions" image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+  {{< card link="https://github.com/imfing/hextra-starter-template" title="Hextra Starter Template" image="https://user-images.githubusercontent.com/5097752/263551418-c403b9a9-a76c-47a6-8466-513d772ef0b7.jpg" imageStyle="object-fit:cover; aspect-ratio:16/9;" >}}
+{{< /cards >}}

exampleSite/hugo.yaml

@@ -5,7 +5,11 @@ title: "Hextra"
 enableRobotsTXT: true
 enableGitInfo: true
 # enableEmoji: false
-# hasCJKLanguage: true
+hasCJKLanguage: true
+
+# services:
+#   googleAnalytics:
+#     ID: G-MEASUREMENT_ID
 
 outputs:
   home: [HTML]
@@ -18,15 +22,16 @@ languages:
     languageName: English
     weight: 1
     title: Hextra
-  ja:
-    languageName: 日本語
+  zh-cn:
+    languageName: 简体中文
+    languageCode: zh-CN
     weight: 2
-    title: "Hextra テーマ"
+    title: Hextra
 
 module:
   hugoVersion:
     extended: true
-    min: "0.111.0"
+    min: "0.112.0"
 
   workspace: hugo.work
   imports:
@@ -47,57 +52,106 @@ menu:
       name: Documentation
       pageRef: /docs
       weight: 1
+    - identifier: showcase
+      name: Showcase
+      pageRef: /showcase
+      weight: 2
     - identifier: blog
       name: Blog
       pageRef: /blog
-      weight: 2
+      weight: 3
     - identifier: about
       name: About
       pageRef: /about
-      weight: 3
-    - name: Search
       weight: 4
+    - name: Search
+      weight: 5
       params:
         type: search
     - name: GitHub
-      weight: 5
+      weight: 6
       url: "https://github.com/imfing/hextra"
       params:
         icon: github
 
   sidebar:
-    - name: More
+    - identifier: more
+      name: More
       params:
         type: separator
       weight: 1
-    - name: "About"
+    - identifier: about
+      name: "About"
       pageRef: "/about"
       weight: 2
-    - name: "Hugo Docs ↗"
+    - identifier: hugoDocs
+      name: "Hugo Docs ↗"
       url: "https://gohugo.io/documentation/"
       weight: 3
 
 params:
+  description: Modern, responsive, batteries-included Hugo theme for creating beautiful static websites.
+
   navbar:
     displayTitle: true
     displayLogo: true
     logo:
       path: images/logo.svg
       dark: images/logo-dark.svg
-      # link: /
       # width: 40
       # height: 20
+      # link: /
+    width: wide
+
+  page:
+    # full (100%), wide (90rem), normal (1280px)
+    width: normal
+
+  theme:
+    # light | dark | system
+    default: system
+    displayToggle: true
 
   footer:
+    enable: true
     displayCopyright: true
     displayPoweredBy: true
+    width: normal
 
   displayUpdatedDate: true
   dateFormat: "January 2, 2006"
 
+  # Search
+  # flexsearch is enabled by default
   search:
     enable: true
+    type: flexsearch
+
+    flexsearch:
+      # index page by: content | summary | heading | title
+      index: content
 
   editURL:
     enable: true
     base: "https://github.com/imfing/hextra/edit/main/exampleSite/content"
+
+  blog:
+    list:
+      displayTags: true
+
+  comments:
+    enable: false
+    type: giscus
+
+    # https://giscus.app/
+    giscus:
+      repo: imfing/hextra
+      repoId: R_kgDOJ9fJag
+      category: General
+      categoryId: DIC_kwDOJ9fJas4CY7gW
+      # mapping: pathname
+      # strict: 0
+      # reactionsEnabled: 1
+      # emitMetadata: 0
+      # inputPosition: top
+      # lang: en

exampleSite/hugo_stats.json

@@ -11,6 +11,7 @@
       "cite",
       "code",
       "del",
+      "details",
       "div",
       "em",
       "figcaption",
@@ -39,11 +40,11 @@
       "path",
       "pre",
       "script",
-      "section",
       "span",
       "strong",
       "style",
       "sub",
+      "summary",
       "sup",
       "svg",
       "table",
@@ -65,13 +66,14 @@
       "[-webkit-touch-callout:none]",
       "[counter-reset:step]",
       "[hyphens:auto]",
-      "[text-underline-position:from-font]",
+      "[transition:background-color_1.5s_ease]",
       "[word-break:break-word]",
       "absolute",
       "active:bg-gray-400/20",
       "active:opacity-50",
       "active:shadow-gray-200",
       "active:shadow-sm",
+      "align-[-2.5px]",
       "align-text-bottom",
       "appearance-none",
       "aspect-auto",
@@ -80,17 +82,22 @@
       "before:bg-gray-200",
       "before:content-[\"\"]",
       "before:content-['#']",
+      "before:content-['']",
+      "before:inline-block",
       "before:inset-0",
       "before:inset-y-1",
+      "before:mr-1",
       "before:opacity-25",
       "before:pointer-events-none",
+      "before:transition-transform",
       "before:w-px",
+      "bg-black/80",
       "bg-black/[.05]",
       "bg-blue-100",
       "bg-clip-text",
-      "bg-gradient-to-b",
       "bg-gradient-to-r",
       "bg-gray-100",
+      "bg-neutral-50",
       "bg-orange-50",
       "bg-primary-100",
       "bg-primary-400",
@@ -107,6 +114,7 @@
       "border-black/5",
       "border-blue-200",
       "border-gray-200",
+      "border-gray-500",
       "border-l",
       "border-orange-100",
       "border-red-200",
@@ -122,6 +130,7 @@
       "content",
       "contrast-more:border",
       "contrast-more:border-current",
+      "contrast-more:border-gray-800",
       "contrast-more:border-gray-900",
       "contrast-more:border-neutral-400",
       "contrast-more:border-primary-500",
@@ -147,9 +156,12 @@
       "contrast-more:text-gray-800",
       "contrast-more:text-gray-900",
       "contrast-more:underline",
+      "copy-icon",
       "cursor-default",
       "cursor-pointer",
       "dark:before:bg-neutral-800",
+      "dark:before:invert",
+      "dark:bg-black/60",
       "dark:bg-blue-900/30",
       "dark:bg-dark",
       "dark:bg-dark/50",
@@ -165,6 +177,7 @@
       "dark:block",
       "dark:border-blue-200/30",
       "dark:border-gray-100/20",
+      "dark:border-gray-400",
       "dark:border-neutral-700",
       "dark:border-neutral-800",
       "dark:border-orange-400/30",
@@ -178,9 +191,11 @@
       "dark:hidden",
       "dark:hover:bg-gray-100/5",
       "dark:hover:bg-neutral-700",
+      "dark:hover:bg-neutral-800",
       "dark:hover:bg-neutral-900",
       "dark:hover:bg-primary-100/5",
       "dark:hover:bg-primary-700",
+      "dark:hover:border-gray-100",
       "dark:hover:border-gray-600",
       "dark:hover:border-neutral-500",
       "dark:hover:border-neutral-700",
@@ -219,11 +234,14 @@
       "data-[state=selected]:text-primary-600",
       "decoration-from-font",
       "duration-200",
-      "ease-in-out",
+      "duration-75",
+      "ease-in",
       "filename",
       "first:mt-0",
+      "fixed",
       "flex",
       "flex-col",
+      "flex-wrap",
       "focus:bg-white",
       "focus:outline-none",
       "focus:ring-4",
@@ -237,11 +255,12 @@
       "footnote-backref",
       "footnote-ref",
       "footnotes",
-      "from-gray-800",
       "from-gray-900",
       "gap-1",
       "gap-2",
       "gap-4",
+      "gap-x-1.5",
+      "gap-y-2",
       "grid",
       "grid-cols-1",
       "group",
@@ -250,12 +269,15 @@
       "group-data-[theme=dark]:hidden",
       "group-data-[theme=light]:hidden",
       "group-hover/code:opacity-100",
+      "group-hover:underline",
+      "group-open:before:rotate-90",
       "group/code",
       "group/copybtn",
       "grow",
       "h-0",
       "h-16",
       "h-2",
+      "h-3.5",
       "h-4",
       "h-5",
       "h-7",
@@ -264,9 +286,11 @@
       "hamburger-menu",
       "hextra-card",
       "hextra-cards",
+      "hextra-feature-card",
       "hextra-filetree",
       "hextra-filetree-folder",
       "hextra-footer",
+      "hextra-scrollbar",
       "hextra-sidebar-collapsible-button",
       "hextra-toc",
       "hidden",
@@ -279,6 +303,7 @@
       "hover:border-gray-200",
       "hover:border-gray-300",
       "hover:border-gray-400",
+      "hover:border-gray-900",
       "hover:dark:bg-primary-500/10",
       "hover:dark:text-primary-600",
       "hover:opacity-60",
@@ -294,6 +319,7 @@
       "inline",
       "inline-block",
       "inline-flex",
+      "inset-0",
       "inset-x-0",
       "inset-y-0",
       "items-center",
@@ -305,14 +331,15 @@
       "justify-start",
       "language-options",
       "language-switcher",
+      "last-of-type:mb-0",
       "leading-5",
       "leading-6",
       "leading-7",
+      "leading-none",
       "leading-tight",
       "left-[24px]",
       "left-[36px]",
       "lg:grid-cols-3",
-      "lg:leading-[1.1]",
       "line-clamp-3",
       "list-none",
       "lntable",
@@ -356,6 +383,7 @@
       "mb-16",
       "mb-2",
       "mb-4",
+      "mb-6",
       "mb-8",
       "md:aspect-[1.1/1]",
       "md:h-[calc(100vh-var(--navbar-height)-var(--menu-height))]",
@@ -382,7 +410,10 @@
       "min-w-full",
       "ml-1",
       "ml-4",
+      "mobile-menu-overlay",
+      "mr-1",
       "mr-2",
+      "mt-1",
       "mt-1.5",
       "mt-12",
       "mt-16",
@@ -397,6 +428,8 @@
       "mx-auto",
       "my-1.5",
       "my-2",
+      "nav-container",
+      "nav-container-blur",
       "next-error-h1",
       "no-underline",
       "not-prose",
@@ -413,11 +446,11 @@
       "overflow-y-auto",
       "overscroll-contain",
       "p-0.5",
+      "p-1",
       "p-1.5",
       "p-2",
       "p-4",
       "p-6",
-      "pb-6",
       "pb-8",
       "pb-[env(safe-area-inset-bottom)]",
       "pb-px",
@@ -426,12 +459,13 @@
       "pl-[max(env(safe-area-inset-left),1.5rem)]",
       "placeholder:text-gray-500",
       "pointer-events-none",
+      "pr-2",
       "pr-4",
       "pr-[calc(env(safe-area-inset-right)-1.5rem)]",
+      "pr-[max(env(safe-area-inset-left),1.5rem)]",
       "pr-[max(env(safe-area-inset-right),1.5rem)]",
       "print:bg-transparent",
       "print:hidden",
-      "pt-1",
       "pt-4",
       "pt-6",
       "pt-8",
@@ -462,6 +496,7 @@
       "rtl:-ml-4",
       "rtl:-rotate-180",
       "rtl:before:right-0",
+      "rtl:before:rotate-180",
       "rtl:left-1.5",
       "rtl:left-3",
       "rtl:md:right-auto",
@@ -498,7 +533,6 @@
       "sm:flex",
       "sm:grid-cols-2",
       "sm:items-start",
-      "sm:px-4",
       "sm:text-xl",
       "sm:w-[110%]",
       "sr-only",
@@ -524,6 +558,7 @@
       "text-gray-800",
       "text-gray-900",
       "text-left",
+      "text-lg",
       "text-orange-800",
       "text-primary-800",
       "text-red-900",
@@ -561,6 +596,7 @@
       "w-screen",
       "whitespace-nowrap",
       "xl:block",
+      "z-10",
       "z-20",
       "z-[-1]"
     ],

exampleSite/i18n/zh-cn.yaml

@@ -0,0 +1,6 @@
+documentation: "文档"
+showcase: "项目展示"
+blog: "博客"
+about: "关于"
+more: "更多"
+hugoDocs: "Hugo 文档 ↗"

i18n/en.yaml

@@ -1,5 +1,14 @@
-onThisPage: "On this page"
+backToTop: "Scroll to top"
+changeLanguage: "Change language"
+changeTheme: "Change theme"
+copyCode: "Copy code"
+copyright: "© 2023 Hextra Project."
+dark: "Dark"
 editThisPage: "Edit this page on GitHub →"
 lastUpdated: "Last updated on"
-
-copyright: "© 2023 Hextra Project."
+light: "Light"
+noResultsFound: "No results found."
+onThisPage: "On this page"
+poweredBy: "Powered by Hextra"
+readMore: "Read more →"
+searchPlaceholder: "Search..."

i18n/es.yaml

@@ -0,0 +1,13 @@
+backToTop: "Subir al inicio"
+changeLanguage: "Cambiar idioma"
+changeTheme: "Cambiar tema"
+copyright: "© 2023 Proyecto Hextra."
+dark: "Oscuro"
+editThisPage: "Edita esta página en GitHub →"
+lastUpdated: "Última actualización"
+light: "Claro"
+noResultsFound: "No hubo resultados."
+onThisPage: "En esta página"
+poweredBy: "Con tecnología de Hextra"
+readMore: "Leer más →"
+searchPlaceholder: "Buscar..."

i18n/fr.yaml

@@ -0,0 +1,13 @@
+backToTop: "Revenir en haut"
+changeLanguage: "Changer la langue"
+changeTheme: "Thème d'affichage"
+copyright: "© 2023 Hextra Project."
+dark: "Sombre"
+editThisPage: "Modifier cette page sur GitHub →"
+lastUpdated: "Dernière modification"
+light: "Clair"
+noResultsFound: "Pas de résultats trouvés"
+onThisPage: "Sur cette page"
+poweredBy: "Propulsé par Hextra"
+readMore: "Lire plus →"
+searchPlaceholder: "Rechercher..."

i18n/ja.yaml

@@ -1,16 +1,13 @@
-# Navbar
-documentation: "ドキュメンテーション"
-blog: "ブログ"
-about: "このサイトについて"
-
-more: "もっと"
-hugoDocs: "Hugoドキュメント ↗"
-
-searchPlaceholder: "検索ドキュメント..."
-noResultsFound: "検索結果が見つかりませんでした"
-
-onThisPage: "このページでは"
-editThisPage: "このページをGitHubで編集する →"
+backToTop: "トップにスクロール"
+changeLanguage: "言語を変更"
+changeTheme: "テーマを変更"
+copyright: "© 2023 Hextra プロジェクト。"
+dark: "ダーク"
+editThisPage: "このページをGitHubで編集 →"
 lastUpdated: "最終更新日"
-
-copyright: "© 2023 Hextra Project."
+light: "ライト"
+noResultsFound: "結果が見つかりませんでした。"
+onThisPage: "このページの内容"
+poweredBy: "提供元 Hextra"
+readMore: "もっと読む →"
+searchPlaceholder: "検索..."

i18n/ko.yaml

@@ -0,0 +1,13 @@
+backToTop: "맨위로 스크롤"
+changeLanguage: "언어변경"
+changeTheme: "테마변경"
+copyright: "© 2023 Hextra Project."
+dark: "어두운 테마"
+editThisPage: "Github에서 편집하기 →"
+lastUpdated: "마지막 수정일자"
+light: "밝은 테마"
+noResultsFound: "결과 없음"
+onThisPage: "페이지 목차"
+poweredBy: "제공 Hextra"
+readMore: "더보기 →"
+searchPlaceholder: "검색..."

i18n/nb.yaml

@@ -0,0 +1,13 @@
+backToTop: "Gå til toppen"
+changeLanguage: "Endre språk"
+changeTheme: "Endre tema"
+copyright: "© 2023 Hextra-prosjektet."
+dark: "Mørk"
+editThisPage: "Rediger denne siden på GitHub →"
+lastUpdated: "Sist oppdatert"
+light: "Lys"
+noResultsFound: "Fant ingen treff."
+onThisPage: "På denne siden"
+poweredBy: "Powered by Hextra"
+readMore: "Les mer →"
+searchPlaceholder: "Søk..."

i18n/nn.yaml

@@ -0,0 +1,13 @@
+backToTop: "Gå til toppen"
+changeLanguage: "Endre språk"
+changeTheme: "Endre tema"
+copyright: "© 2023 Hextra-prosjektet."
+dark: "Mørk"
+editThisPage: "Rediger denne sida på GitHub →"
+lastUpdated: "Sist oppdatert"
+light: "Ljos"
+noResultsFound: "Fann ingen treff."
+onThisPage: "På denne sida"
+poweredBy: "Powered by Hextra"
+readMore: "Les meir →"
+searchPlaceholder: "Søk..."

i18n/pt.yaml

@@ -0,0 +1,13 @@
+backToTop: "Voltar ao topo"
+changeLanguage: "Mudar a língua"
+changeTheme: "Mudar tema"
+copyright: "© 2023 Projecto Hextra."
+dark: "Escuro"
+editThisPage: "Edita esta página no GitHub →"
+lastUpdated: "Última modificação"
+light: "Claro"
+noResultsFound: "Nenhum resultado encontrado"
+onThisPage: "Nesta página"
+poweredBy: "Com a tecnologia de Hextra"
+readMore: "Ler mais →"
+searchPlaceholder: "Procurar..."

i18n/sw.yaml

@@ -0,0 +1,13 @@
+backToTop: "Tembeza hadi juu"
+changeLanguage: "Badilisha lugha"
+changeTheme: "Badilisha mandhari"
+copyright: "© 2023 Hextra Project."
+dark: "Meusi"
+editThisPage: "Hariri ukurasa huu kwenye GitHub →"
+lastUpdated: "Ilisasishwa mwisho"
+light: "Nuru"
+noResultsFound: "Hakuna matokeo yalipopatikana."
+onThisPage: "Kwenye ukurasa huu"
+poweredBy: "Inaendeshwa na Hextra"
+readMore: "Soma zaidi →"
+searchPlaceholder: "Tafuta..."

i18n/vi.yaml

@@ -0,0 +1,13 @@
+backToTop: "Lướt lên đầu trang"
+changeLanguage: "Đổi ngôn ngữ"
+changeTheme: "Đổi chủ đề"
+copyright: "© 2023 Hextra Project."
+dark: "Tối"
+editThisPage: "Sửa trang này trên GitHub →"
+lastUpdated: "Lần cuối cập nhật lúc"
+light: "Sáng"
+noResultsFound: "Không tìm thấy kết quả."
+onThisPage: "Ở trang này"
+poweredBy: "Chạy bởi Hextra"
+readMore: "Đọc thêm →"
+searchPlaceholder: "Tìm kiếm..."

i18n/zh-cn.yaml

@@ -0,0 +1,13 @@
+backToTop: "返回顶部"
+changeLanguage: "切换语言"
+changeTheme: "切换主题"
+copyright: "© 2023 Hextra Project."
+dark: "深色"
+editThisPage: "在 GitHub 上编辑此页 →"
+lastUpdated: "最后更新于"
+light: "浅色"
+noResultsFound: "无结果"
+onThisPage: "此页上"
+poweredBy: "由 Hextra 驱动"
+readMore: "更多 →"
+searchPlaceholder: "搜索文档..."

i18n/zh-tw.yaml

@@ -0,0 +1,13 @@
+backToTop: "返回頂部"
+changeLanguage: "切換語言"
+changeTheme: "切換主題"
+copyright: "© 2023 Hextra Project."
+dark: "深色"
+editThisPage: "在 GitHub 上編輯此頁 →"
+lastUpdated: "最後更新於"
+light: "淺色"
+noResultsFound: "無結果"
+onThisPage: "此頁上"
+poweredBy: "由 Hextra 驅動"
+readMore: "更多 →"
+searchPlaceholder: "搜尋文檔..."

layouts/_default/_markup/render-codeblock.html

@@ -1,6 +1,7 @@
 {{- $class := .Attributes.class | default "" -}}
 {{- $filename := .Attributes.filename | default "" -}}
 {{- $lang := .Attributes.lang | default .Type -}}
+{{- $copyCode := (T "copyCode") | default "Copy code" -}}
 
 
 <div class="code-block relative mt-6 first:mt-0 group/code">
@@ -8,16 +9,17 @@
     <div class="filename">{{ $filename }}</div>
   {{- end -}}
   {{- if transform.CanHighlight $lang -}}
-    <div id="code-block-{{ .Ordinal }}">
-      {{- highlight .Inner $lang .Options -}}
-    </div>
+    <div>{{- highlight .Inner $lang .Options -}}</div>
   {{- else -}}
-    <pre><code id="code-block-{{ .Ordinal }}">{{ .Inner }}</code></pre>
+    <pre><code>{{ .Inner }}</code></pre>
   {{- end -}}
   <div class="opacity-0 transition group-hover/code:opacity-100 flex gap-1 absolute m-[11px] right-0 {{ if $filename }}top-8{{ else }}top-0{{ end }}">
-    <button class="code-copy-btn group/copybtn transition-all active:opacity-50 bg-primary-700/5 border border-black/5 text-gray-600 hover:text-gray-900 rounded-md p-1.5 dark:bg-primary-300/10 dark:border-white/10 dark:text-gray-400 dark:hover:text-gray-50" title="Copy code" data-clipboard-target="#code-block-{{ .Ordinal }}">
-      {{ partial "utils/icon.html" (dict "name" "copy" "attributes" "class=\"group-[.copied]/copybtn:hidden pointer-events-none h-4 w-4\"") }}
-      {{ partial "utils/icon.html" (dict "name" "check" "attributes" "class=\"hidden group-[.copied]/copybtn:block success-icon pointer-events-none h-4 w-4\"") }}
+    <button
+      class="code-copy-btn group/copybtn transition-all active:opacity-50 bg-primary-700/5 border border-black/5 text-gray-600 hover:text-gray-900 rounded-md p-1.5 dark:bg-primary-300/10 dark:border-white/10 dark:text-gray-400 dark:hover:text-gray-50"
+      title="{{ $copyCode }}"
+    >
+      <div class="group-[.copied]/copybtn:hidden copy-icon pointer-events-none h-4 w-4"></div>
+      <div class="hidden group-[.copied]/copybtn:block success-icon pointer-events-none h-4 w-4"></div>
     </button>
   </div>
 </div>

layouts/_default/_markup/render-image.html

@@ -1,8 +1,27 @@
-{{- if .Title -}}
+{{- $alt := .PlainText | safeHTML -}}
+{{- $lazyLoading := .Page.Site.Params.enableImageLazyLoading | default true -}}
+{{- $dest := .Destination -}}
+
+{{- $isLocal := not (urls.Parse $dest).Scheme -}}
+{{- $isPage := and (eq .Page.Kind "page") (not .Page.BundleType) -}}
+{{- $startsWithSlash := hasPrefix $dest "/" -}}
+{{- $startsWithRelative := hasPrefix $dest "../" -}}
+
+{{- if and $dest $isLocal -}}
+  {{- if $startsWithSlash -}}
+    {{/* Images under static directory */}}
+    {{- $dest = (relURL (strings.TrimPrefix "/" $dest)) -}}
+  {{- else if and $isPage (not $startsWithRelative) -}}
+    {{/* Images that are sibling to the individual page file */}}
+    {{ $dest = (printf "../%s" $dest) }}
+  {{- end -}}
+{{- end -}}
+
+{{- with .Title -}}
   <figure>
-    <img src="{{ .Destination | safeURL }}" title="{{ .Title }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
-    <figcaption>{{ .Title }}</figcaption>
+    <img src="{{ $dest | safeURL }}" title="{{ . }}" alt="{{ $alt }}" {{ if $lazyLoading }}loading="lazy"{{ end }} />
+    <figcaption>{{ . }}</figcaption>
   </figure>
 {{- else -}}
-  <img src="{{ .Destination | safeURL }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
+  <img src="{{ $dest | safeURL }}" alt="{{ $alt }}" {{ if $lazyLoading }}loading="lazy"{{ end }} />
 {{- end -}}

layouts/_default/baseof.html

@@ -1,10 +1,12 @@
 <!DOCTYPE html>
-<html>
+<html lang="{{ .Site.Language.Lang }}">
   {{- partial "head.html" . -}}
   <body dir="ltr">
     {{- partial "navbar.html" . -}}
     {{- block "main" . }}{{ end -}}
-    {{- if not .Site.Params.footer.disabled }}{{ partial "footer.html" . }}{{ end }}
+    {{- if or (eq .Site.Params.footer.enable nil) (.Site.Params.footer.enable) }}
+      {{ partial "footer.html" . }}
+    {{ end }}
   </body>
   {{ partial "scripts.html" . }}
 </html>

layouts/_default/list.html

@@ -1,5 +1,5 @@
 {{ define "main" }}
-  <div class="mx-auto flex max-w-screen-xl">
+  <div class='mx-auto flex {{ partial "utils/page-width" . }}'>
     {{ partial "sidebar.html" (dict "context" .) }}
     {{ partial "toc.html" . }}
     <article class="w-full break-words flex min-h-[calc(100vh-var(--navbar-height))] min-w-0 justify-center pb-8 pr-[calc(env(safe-area-inset-right)-1.5rem)]">
@@ -10,6 +10,7 @@
         </div>
         <div class="mt-16"></div>
         {{ partial "components/last-updated.html" . }}
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/_default/list.rss.xml

@@ -0,0 +1,43 @@
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>{{ .Site.Title }} – {{ .Title }}</title>
+    <link>{{ .Permalink }}</link>
+    <description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
+    <generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
+    <language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
+    <managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
+    <webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
+    <copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
+    <lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
+    {{ with .OutputFormats.Get "RSS" }}
+	  {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
+    {{ end }}
+    {{ if not $.Section }}
+      {{ $sections := .Site.Params.rss.sections | default (slice "blog") }}
+      {{ .Scratch.Set "rssPages" (first 50 (where $.Site.RegularPages "Type" "in" $sections )) }}
+    {{ else }}
+      {{ if $.Parent.IsHome }}
+        {{ .Scratch.Set "rssPages" (first 50 (where $.Site.RegularPages "Type" $.Section )) }}
+      {{ else }}
+        {{ .Scratch.Set "rssPages" (first 50 $.Pages) }}
+      {{ end }}
+    {{ end }}
+    {{ range (.Scratch.Get "rssPages")  }}
+    <item>
+      <title>{{ .Title }}</title>
+      <link>{{ .Permalink }}</link>
+      <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
+      {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
+      <guid>{{ .Permalink }}</guid>
+      <description>
+        {{ $img := (.Resources.ByType "image").GetMatch "*featured*" }}
+        {{ with $img }}
+        {{ $img := .Resize "640x" }}
+        {{ printf "<![CDATA[<img src=\"%s\" width=\"%d\" height=\"%d\"/>]]>" $img.Permalink $img.Width $img.Height | safeHTML }}
+        {{ end }}
+        {{ .Content | html }}
+      </description>
+    </item>
+    {{ end }}
+  </channel>
+</rss>

layouts/_default/single.html

@@ -1,14 +1,17 @@
 {{ define "main" }}
-  <div class="mx-auto flex max-w-screen-xl">
+  <div class='mx-auto flex {{ partial "utils/page-width" . }}'>
     {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }}
     {{ partial "toc.html" . }}
     <article class="w-full break-words flex min-h-[calc(100vh-var(--navbar-height))] min-w-0 justify-center pb-8 pr-[calc(env(safe-area-inset-right)-1.5rem)]">
       <main class="w-full min-w-0 max-w-6xl px-6 pt-4 md:px-12">
+        <br class="mt-1.5 text-sm" />
         <h1 class="text-center mt-2 text-4xl font-bold tracking-tight text-slate-900 dark:text-slate-100">{{ .Title }}</h1>
         <div class="mb-16"></div>
         <div class="content">
           {{ .Content }}
         </div>
+        <div class="mt-16"></div>
+        {{ partial "components/comments.html" . }}
       </main>
     </article>
   </div>

layouts/_default/wide.html

@@ -0,0 +1,12 @@
+{{ define "main" }}
+  <div class="mx-auto flex max-w-[90rem]">
+    {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" false) }}
+    <article class="w-full break-words min-h-[calc(100vh-var(--navbar-height))] min-w-0 pt-4 pb-8 pl-[max(env(safe-area-inset-left),1.5rem)] pr-[max(env(safe-area-inset-left),1.5rem)]">
+      <br class="mt-1.5 text-sm" />
+      <h1 class="text-center mt-2 text-4xl font-bold tracking-tight text-slate-900 dark:text-slate-100">{{ .Title }}</h1>
+      <div class="content">
+        {{ .Content }}
+      </div>
+    </article>
+  </div>
+{{ end }}