fix: use relURL only for link starts with slash (#54)

* fix: cards links should not redirect to 404

* docs: update card links

* fix: use relURL for card link

.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/workflows/pages.yml

@@ -35,6 +35,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
       - name: Setup Go
         uses: actions/setup-go@v4
         with:
@@ -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

@@ -31,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/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/styles.css

@@ -1,3 +1,5 @@
+@import "tailwind.css";
+
 @import "typography.css";
 @import "highlight.css";
 @import "components/cards.css";
@@ -6,10 +8,6 @@
 @import "components/sidebar.css";
 @import "components/navbar.css";
 
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
 html {
   @apply text-base antialiased;
   font-feature-settings: "rlig" 1, "calt" 1, "ss01" 1;

assets/css/tailwind.css

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

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

dev.toml

@@ -0,0 +1,23 @@
+# 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 = "hugo_stats.json"
+    target = "assets/watching/hugo_stats.json"

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.zh-cn.md

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

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

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/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) 中找到。 可以使用以下命令生成样式表：
+
+```bash
+$ 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 上[创建 Issues](https://github.com/imfing/hextra/issues) 或为 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.md

@@ -7,7 +7,7 @@ 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.
 
@@ -65,7 +65,7 @@ $ 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/`.
@@ -73,6 +73,21 @@ Voila! You can see your new site at `http://localhost:1313/`.
 {{% /steps %}}
 
 
+## Update Theme
+
+{{% details title="How to update theme?" %}}
+
+To update the theme to the [latest released version](https://github.com/imfing/hextra/releases), run the following command:
+
+```shell
+$ hugo mod get -u
+```
+
+See [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) 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,83 @@
+---
+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/)。
+
+{{% steps %}}
+
+### 初始化 Hugo 站点
+
+```bash
+$ hugo new site my-site --format=yaml
+```
+
+### 通过模块配置 Hextra 主题
+
+```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
+```
+
+### 创建你的第一个内容页
+
+让我们为主页和文档页面创建一个新的内容页面：
+
+```shell
+$ hugo new content/_index.md
+$ hugo new content/docs/_index.md
+```
+
+### 在本地预览站点
+
+```shell
+$ hugo server --buildDrafts --disableFastRender
+```
+
+瞧！你现在可以在 `http://localhost:1313/` 看到你的新站点。
+
+{{% /steps %}}
+
+## 接下来
+
+你可以探索以下部分来添加更多内容：
+
+{{< cards >}}
+  {{< card link="../guide/organize-files" title="目录结构" icon="document-duplicate" >}}
+  {{< card link="../guide/configuration" title="配置文件指南" icon="adjustments" >}}
+  {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
+{{< /cards >}}

exampleSite/content/docs/guide/_index.md

@@ -1,6 +1,7 @@
 ---
 title: Guide
 weight: 2
+prev: /docs/getting-started
 next: /docs/guide/organize-files
 sidebar:
   open: true

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

@@ -65,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
@@ -124,3 +142,41 @@ params:
   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.

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

@@ -0,0 +1,125 @@
+---
+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` 中设置 `params.editURL`：
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+params:
+  editURL: "https://example.com/edit/this/page"
+---
+```

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 支持 [Mermain](#mermaid) 的图表。
+
+<!--more-->
+
+## Mermaid
+
+[Mermaid](https://github.com/mermaid-js/mermaid#readme) 是一个基于 JavaScript 的图表绘制工具，它的文本定义和 Markdown 类似，可在浏览器中动态创建图表。例如：流程图、序列图、饼图等。
+
+在 Hextra 中使用 Mermain 就像使用代码块一样简单：
+
+````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.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="/docs/guide/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,6 +1,7 @@
 ---
 title: Organize Files
 weight: 1
+prev: /docs/guide
 ---
 
 ## Directory Structure

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.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,7 +6,7 @@ linkTitle: Cards
 ## Example
 
 {{< cards >}}
-  {{< card link="/" title="Callout" icon="warning" >}}
+  {{< card link="../callout" title="Callout" icon="warning" >}}
   {{< card link="/" title="No Icon" >}}
 {{< /cards >}}
 
@@ -19,7 +19,7 @@ linkTitle: Cards
 
 ```
 {{</* cards */>}}
-  {{</* card link="/" title="Callout" icon="warning" */>}}
+  {{</* card link="../callout" title="Callout" icon="warning" */>}}
   {{</* card link="/" title="No Icon" */>}}
 {{</* /cards */>}}
 ```

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
+
+````
+{{%/* 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 */%}}
+````

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/advanced/
 ---
 
 ## 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.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/hugo.yaml

@@ -5,7 +5,7 @@ title: "Hextra"
 enableRobotsTXT: true
 enableGitInfo: true
 # enableEmoji: false
-# hasCJKLanguage: true
+hasCJKLanguage: true
 
 outputs:
   home: [HTML]
@@ -22,6 +22,10 @@ languages:
     languageName: 日本語
     weight: 2
     title: "Hextra テーマ"
+  zh-cn:
+    languageName: 简体中文
+    weight: 3
+    title: Hextra
 
 module:
   hugoVersion:

exampleSite/hugo_stats.json

@@ -11,6 +11,7 @@
       "cite",
       "code",
       "del",
+      "details",
       "div",
       "em",
       "figcaption",
@@ -44,6 +45,7 @@
       "strong",
       "style",
       "sub",
+      "summary",
       "sup",
       "svg",
       "table",
@@ -80,10 +82,14 @@
       "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/[.05]",
       "bg-blue-100",
@@ -91,6 +97,7 @@
       "bg-gradient-to-b",
       "bg-gradient-to-r",
       "bg-gray-100",
+      "bg-neutral-50",
       "bg-orange-50",
       "bg-primary-100",
       "bg-primary-400",
@@ -150,6 +157,7 @@
       "cursor-default",
       "cursor-pointer",
       "dark:before:bg-neutral-800",
+      "dark:before:invert",
       "dark:bg-blue-900/30",
       "dark:bg-dark",
       "dark:bg-dark/50",
@@ -178,6 +186,7 @@
       "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",
@@ -250,6 +259,7 @@
       "group-data-[theme=dark]:hidden",
       "group-data-[theme=light]:hidden",
       "group-hover/code:opacity-100",
+      "group-open:before:rotate-90",
       "group/code",
       "group/copybtn",
       "grow",
@@ -305,6 +315,7 @@
       "justify-start",
       "language-options",
       "language-switcher",
+      "last-of-type:mb-0",
       "leading-5",
       "leading-6",
       "leading-7",
@@ -312,7 +323,6 @@
       "left-[24px]",
       "left-[36px]",
       "lg:grid-cols-3",
-      "lg:leading-[1.1]",
       "line-clamp-3",
       "list-none",
       "lntable",
@@ -397,6 +407,8 @@
       "mx-auto",
       "my-1.5",
       "my-2",
+      "nav-container",
+      "nav-container-blur",
       "next-error-h1",
       "no-underline",
       "not-prose",
@@ -413,11 +425,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",
@@ -462,6 +474,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",
@@ -524,6 +537,7 @@
       "text-gray-800",
       "text-gray-900",
       "text-left",
+      "text-lg",
       "text-orange-800",
       "text-primary-800",
       "text-red-900",

i18n/zh-cn.yaml

@@ -0,0 +1,15 @@
+documentation: "文档"
+blog: "博客"
+about: "关于"
+
+more: "更多"
+hugoDocs: "Hugo 文档 ↗"
+
+searchPlaceholder: "搜索文档..."
+noResultsFound: "无结果"
+
+onThisPage: "此页上"
+editThisPage: "在 GitHub 上编辑此页 →"
+lastUpdated: "最后更新于"
+
+copyright: "© 2023 Hextra Project."

i18n/zh-tw.yaml

@@ -0,0 +1,15 @@
+documentation: "文檔"
+blog: "博客"
+about: "關於"
+
+more: "更多"
+hugoDocs: "Hugo 文檔 ↗"
+
+searchPlaceholder: "搜索文檔..."
+noResultsFound: "無結果"
+
+onThisPage: "此頁上"
+editThisPage: "在 GitHub 上編輯此頁 →"
+lastUpdated: "最後更新於"
+
+copyright: "© 2023 Hextra Project."

layouts/_default/baseof.html

@@ -4,7 +4,7 @@
   <body dir="ltr">
     {{- partial "navbar.html" . -}}
     {{- block "main" . }}{{ end -}}
-    {{- if not .Site.Params.footer.disabled }}{{ partial "footer.html" . }}{{ end }}
+    {{- if (.Site.Params.footer.enable | default true) }}{{ partial "footer.html" . }}{{ end }}
   </body>
   {{ partial "scripts.html" . }}
 </html>

layouts/_default/single.html

@@ -4,6 +4,7 @@
     {{ 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">

layouts/blog/list.html

@@ -3,7 +3,8 @@
     {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }}
     <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">
-        <h1 class="text-4xl tracking-tighter text-center font-extrabold md:text-5xl mt-8 pb-6">{{ .Title }}</h1>
+        <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>
         {{ range .Pages.ByDate }}
           <div class="mb-10">

layouts/hextra-home.html

@@ -14,7 +14,7 @@
           {{- partial "utils/icon" (dict "name" "arrow-circle-right" "attributes" "height=14") -}}
         </a>
         <h1
-          class="text-4xl font-bold leading-tight tracking-tighter md:text-5xl lg:leading-[1.1] mt-6 bg-clip-text text-transparent bg-gradient-to-r from-gray-900 to-gray-600 dark:from-gray-100 dark:to-gray-400"
+          class="text-4xl font-bold leading-tight tracking-tighter md:text-5xl mt-6 bg-clip-text text-transparent bg-gradient-to-r from-gray-900 to-gray-600 dark:from-gray-100 dark:to-gray-400"
         >
           Build modern websites&nbsp;<br class="sm:block hidden" />
           with Markdown and Hugo

layouts/index.html

@@ -1,5 +1,5 @@
 {{ define "main" }}
-  <div class="mx-auto flex max-w-screen-xl">
+  <div class="mx-auto flex max-w-[90rem]">
     {{ 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)]">

layouts/partials/footer.html

@@ -16,7 +16,7 @@
   >
     <div class="flex w-full flex-col items-center sm:items-start">
       {{- if (.Site.Params.footer.displayPoweredBy | default true) }}<div class="font-semibold">{{ template "theme-credit" . }}</div>{{ end }}
-      {{- if .Site.Params.footer.displayCopyright }}<p class="mt-6 text-xs">{{ $copyright }}</p>{{ end }}
+      {{- if .Site.Params.footer.displayCopyright }}<p class="mt-6 text-xs">{{ $copyright | markdownify }}</p>{{ end }}
     </div>
   </div>
 </footer>

layouts/partials/head-css.html

@@ -1,14 +1,25 @@
-{{ if and (not hugo.IsProduction) (eq hugo.Environment "theme")}}
-  {{ $styles := resources.Get "css/styles.css" }}
-  {{ $styles = $styles | resources.PostCSS (dict "inlineImports" true) }}
+{{- if and (not hugo.IsProduction) (eq hugo.Environment "theme") }}
+  {{- $styles := resources.Get "css/styles.css" }}
+  {{- $styles = $styles | resources.PostCSS (dict "inlineImports" true) }}
   <link href="{{ $styles.RelPermalink }}" rel="stylesheet" />
-{{ else }}
-  {{ $styles := resources.Get "css/compiled/main.css" }}
-  {{ $styles = $styles | minify | fingerprint | resources.PostProcess }}
-  <link rel="preload" href="{{ $styles.RelPermalink }}" as="style" />
-  <link href="{{ $styles.RelPermalink }}" rel="stylesheet" integrity="{{ $styles.Data.Integrity }}" />
-{{ end }}
+{{- else }}
+  {{- $styles := resources.Get "css/compiled/main.css" -}}
 
-{{ $custom := resources.Get "css/custom.css" }}
-{{ $custom = $custom | minify | fingerprint }}
-<link href="{{ $custom.RelPermalink }}" rel="stylesheet" integrity="{{ $custom.Data.Integrity }}" />
+  {{- if hugo.IsProduction }}
+    {{- $styles = $styles | minify | fingerprint }}
+    <link rel="preload" href="{{ $styles.RelPermalink }}" as="style" />
+    <link href="{{ $styles.RelPermalink }}" rel="stylesheet" integrity="{{ $styles.Data.Integrity }}" />
+  {{- else }}
+    <link href="{{ $styles.RelPermalink }}" rel="stylesheet" />
+  {{- end }}
+{{- end }}
+
+
+<!-- Custom CSS -->
+{{- $custom := resources.Get "css/custom.css" }}
+{{- if hugo.IsProduction -}}
+  {{- $custom = $custom | minify | fingerprint }}
+  <link href="{{ $custom.RelPermalink }}" rel="stylesheet" integrity="{{ $custom.Data.Integrity }}" />
+{{- else }}
+  <link href="{{ $custom.RelPermalink }}" rel="stylesheet" />
+{{- end }}

layouts/partials/navbar.html

@@ -5,8 +5,8 @@
 {{- $logoDarkPath := .Site.Params.navbar.logo.dark | default $logoPath -}}
 
 
-<div class="sticky top-0 z-20 w-full bg-transparent print:hidden">
-  <div class="pointer-events-none absolute z-[-1] h-full w-full bg-white shadow-[0_2px_4px_rgba(0,0,0,.02),0_1px_0_rgba(0,0,0,.06)] contrast-more:shadow-[0_0_0_1px_#000] dark:bg-dark dark:shadow-[0_-1px_0_rgba(255,255,255,.1)_inset] contrast-more:dark:shadow-[0_0_0_1px_#fff]"></div>
+<div class="nav-container sticky top-0 z-20 w-full bg-transparent print:hidden">
+  <div class="nav-container-blur pointer-events-none absolute z-[-1] h-full w-full bg-white dark:bg-dark shadow-[0_2px_4px_rgba(0,0,0,.02),0_1px_0_rgba(0,0,0,.06)] contrast-more:shadow-[0_0_0_1px_#000] dark:shadow-[0_-1px_0_rgba(255,255,255,.1)_inset] contrast-more:dark:shadow-[0_0_0_1px_#fff]"></div>
 
   <nav class="mx-auto flex items-center justify-end gap-2 h-16 px-6 max-w-[90rem]">
     <a class="flex items-center hover:opacity-75 ltr:mr-auto rtl:ml-auto" href="{{ $logoLink }}">

layouts/partials/toc.html

@@ -49,7 +49,7 @@
     {{- if .Title }}
       <li class="my-2 scroll-my-6 scroll-py-6">
         <a class="{{ $class }} inline-block text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-300 contrast-more:text-gray-900 contrast-more:underline contrast-more:dark:text-gray-50 w-full break-words" href="#{{ anchorize .ID }}">
-          {{- .Title -}}
+          {{- .Title | safeHTML }}
         </a>
       </li>
     {{- end -}}

layouts/shortcodes/card.html

@@ -11,24 +11,25 @@
 {{- end -}}
 
 {{- $external := strings.HasPrefix $link "http" -}}
+{{- $href := cond (strings.HasPrefix $link "/") ($link | relURL) $link -}}
 
 <a
   class="hextra-card group flex flex-col justify-start overflow-hidden rounded-lg border border-gray-200 text-current no-underline dark:shadow-none hover:shadow-gray-100 dark:hover:shadow-none shadow-gray-100 active:shadow-sm active:shadow-gray-200 transition-all duration-200 {{ $linkClass }}"
-  href="{{ $link }}"
-  {{- if $external -}}
-    target="_blank"
-    rel="noreferrer"
+  href="{{ $href }}"
+  {{- if $external }}
+    target="_blank" rel="noreferrer"
   {{- end -}}
 >
   {{- with $image -}}
-    <img alt="{{ $title }}" loading="lazy" decoding="async" style="color: transparent;" src="{{ $image }}" />
+    <img alt="{{ $title }}" loading="lazy" decoding="async" style="color: transparent;" src="{{ $image | safeURL }}" />
   {{- end -}}
 
-  {{ $padding := "p-4"}}
+  {{- $padding := "p-4" -}}
   {{- with $subtitle -}}
-    {{ $padding = "pt-4 px-4"}}
+    {{- $padding = "pt-4 px-4" -}}
   {{- end -}}
 
+
   <span class="flex font-semibold items-start gap-2 {{ $padding }} text-gray-700 hover:text-gray-900 dark:text-neutral-200 dark:hover:text-neutral-50">
     {{- with $icon }}{{ partial "utils/icon.html" (dict "name" $icon) -}}{{ end -}}
     {{- $title -}}

layouts/shortcodes/details.html

@@ -1,8 +1,8 @@
 {{- $title := .Get "title" | default "" -}}
 {{- $closed := eq (.Get "closed") "true" | default false -}}
 
-<details class="last-of-type:mb-0 rounded-lg bg-neutral-50 dark:bg-neutral-800 p-2 mt-4" data-expanded="true" {{ if not $closed }}open{{ end }}>
-  <summary class="flex items-center cursor-pointer select-none list-none p-1 transition-colors hover:bg-gray-100 dark:hover:bg-neutral-800 before:mr-1 before:inline-block before:transition-transform before:content-[''] dark:before:invert rtl:before:rotate-180 [[data-expanded]>&]:before:rotate-90">
+<details class="last-of-type:mb-0 rounded-lg bg-neutral-50 dark:bg-neutral-800 p-2 mt-4 group" {{ if not $closed }}open{{ end }}>
+  <summary class="flex items-center cursor-pointer select-none list-none p-1 rounded transition-colors hover:bg-gray-100 dark:hover:bg-neutral-800 before:mr-1 before:inline-block before:transition-transform before:content-[''] dark:before:invert rtl:before:rotate-180 group-open:before:rotate-90">
     <strong class="text-lg">{{ $title | markdownify }}</strong>
   </summary>
   <div class="p-2 overflow-hidden">

package.json

@@ -1,6 +1,6 @@
 {
   "scripts": {
-    "dev:theme": "hugo server --logLevel debug --environment=theme --source=exampleSite --themesDir=../.. --disableFastRender -D --port 1313",
+    "dev:theme": "hugo server --logLevel=debug --config=hugo.yaml,../dev.toml --environment=theme --source=exampleSite --themesDir=../.. --disableFastRender -D --port 1313",
     "dev": "hugo server --source=exampleSite --themesDir=../.. --disableFastRender -D --port 1313",
     "build:css": "npx postcss --config postcss.config.js --env production assets/css/styles.css -o assets/css/compiled/main.css",
     "build": "hugo --gc --minify --themesDir=../.. --source=exampleSite"

postcss.config.js

@@ -3,10 +3,10 @@ const tailwind = require('tailwindcss')(tailwindConfig);
 const autoprefixer = require('autoprefixer');
 
 module.exports = {
-	plugins: [
-		require('postcss-import'),
-		require('@tailwindcss/nesting'),
-		tailwind,
-		autoprefixer
-	],
+  plugins: [
+    require('postcss-import'),
+    require('@tailwindcss/nesting'),
+    tailwind,
+    autoprefixer
+  ],
 };