i18n: Add some zh-cn translation of exampleSite(docs) (#12)

--------- Co-authored-by: Xin <xin@imfing.com>
2025-07-04 12:37:10 -04:00 · 2023-08-31 04:21:31 +08:00
parent 392c6f8dde
commit e1a2109a68
16 changed files with 859 additions and 0 deletions
--- a/exampleSite/content/docs/guide/_index.zh-cn.md
+++ b/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="代码高Liam和" icon="sparkles" >}}
+  {{< card link="latex" title="LaTeX" icon="variable" >}}
+  {{< card link="diagrams" title="Diagrams" icon="chart-square-bar" >}}
+  {{< card link="shortcodes" title="Shortcodes" icon="template" >}}
+{{< /cards >}}
--- a/exampleSite/content/docs/guide/configuration.zh-cn.md
+++ b/exampleSite/content/docs/guide/configuration.zh-cn.md
@ -0,0 +1,124 @@
+---
+title: 配置文件
+weight: 2
+---
+
+Hugo 从 Hugo 网站根目录下的 `hugo.yaml` 读取配置.
+在配置文件中, 您可以配置站点的所有选项.
+你可以在 `exampleSite/hugo.yaml` 中找到此站点的配置文件作为开始.
+<!--more-->
+
+## Navigation
+
+### Menu
+
+右上角的菜单在配置文件的 `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"
+---
+```
--- a/exampleSite/content/docs/guide/diagrams.zh-cn.md
+++ b/exampleSite/content/docs/guide/diagrams.zh-cn.md
@ -0,0 +1,53 @@
+---
+title: Diagrams
+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/#/).
--- a/exampleSite/content/docs/guide/latex.zh-cn.md
+++ b/exampleSite/content/docs/guide/latex.zh-cn.md
@ -0,0 +1,60 @@
+---
+title: "LaTeX"
+weight: 4
+math: true
+---
+
+$\KaTeX$ 用于呈现 LaTeX 数学表达式. 可在 `front matter` 将 `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$$
+```
+
+will be rendered as:
+
+$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
+
+
+## 支持的功能
+
+有关支持的函数列表, 转至 [KaTeX supported functions](https://katex.org/docs/supported.html).
+
+## 化学表达式
+
+通过 [mhchem](https://mhchem.github.io/MathJax-mhchem/) 支持化学表达式。
+
+内联: $\ce{H2O}$ is water.
+
+单独的:
+
+```markdown {filename="page.md"}
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
+```
+
+$$\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$$
--- a/exampleSite/content/docs/guide/markdown.zh-cn.md
+++ b/exampleSite/content/docs/guide/markdown.zh-cn.md
@ -0,0 +1,106 @@
+---
+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)
+
+With caption:
+
+![](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/)
--- a/exampleSite/content/docs/guide/organize-files.zh-cn.md
+++ b/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 文件的 `front matter ` 中使用 `weight` 配置.
+
+```yaml {filename="content/docs/guide/_index.md"}
+---
+title: Guide
+weight: 2
+---
+```
+
+{{< callout emoji="ℹ️">}}
+  建议侧边栏不要太深. 如果内容太多, 请考虑 **将它们分成多个部分**.
+{{< /callout >}}
+
+## 配置 `context` 目录
+
+如果需要为的内容使用不同的目录, 可以在站点配置文件中设置 [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) 来实现.
--- a/exampleSite/content/docs/guide/syntax-highlighting.zh-cn.md
+++ b/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).