Docs: 新增文档 “配置 FixIt”

hugo-fixit · Mar 23, 2024 · f603aee · f603aee
1 parent 612fa74
commit f603aee
Show file tree

Hide file tree

Showing 8 changed files with 1,173 additions and 780 deletions.
diff --git a/content/en/documentation/content-management/introduction/index.md b/content/en/documentation/content-management/introduction/index.md
@@ -468,7 +468,7 @@ Use [Front Matter parameter](https://gohugo.io/content-management/multilingual#t
 
 Translations strings are used for common default values used in the theme. Translations are available in [some languages](#language-compatibility), but you may use another language or want to override default values.
 
-To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/FixIt/i18n/en.toml`.
+To override these values, create a new file in your local I18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/FixIt/i18n/en.toml`.
 
 By the way, as these translations could be used by other people, please take the time to propose a translation by [making a PR :(fa-solid fa-code-branch fa-fw):][pulls] to the theme!
 

diff --git a/content/en/documentation/getting-started/configuration/index.md b/content/en/documentation/getting-started/configuration/index.md
@@ -100,13 +100,13 @@ Here is a `yaml` example:
 
 ```yaml
 ---
-title: Theme Documentation - Basics
+title: Configure FixIt
 author: Lruihao
 menu:
   main:
-    name: Basics
-    title: Discover what the Hugo - FixIt theme is all about and the core-concepts behind it.
+    title: Find out how to configure your Hugo FixIt site.
     parent: documentation
+    weight: 3
     params:
       icon: fa-brands fa-readme
 # ...
@@ -1064,7 +1064,7 @@ height
 
 {{< version 0.2.17 >}}
 
-`map` Progress bar in the top during page loading.
+`map` Progress bar in the top during page loading, based on [Pace.js][pacejs].
 
 ```toml
 [params]
@@ -1576,6 +1576,7 @@ They're easily created via <https://realfavicongenerator.net/>.
 [fusejs-options]: https://fusejs.io/api/options.html
 [mermaid-themes]: https://mermaid.js.org/config/theming.html#available-themes
 [watermark]: https://github.com/Lruihao/watermark#readme
+[pacejs]: https://github.com/CodeByZach/pace
 [configuration-markup]: https://gohugo.io/getting-started/configuration-markup/
 [necessary-configuration-for-theme]: https://github.com/hugo-fixit/FixIt/issues/43
 [hugo-output-formats]: https://gohugo.io/templates/output-formats/
diff --git a/content/zh-cn/documentation/advanced/index.md b/content/zh-cn/documentation/advanced/index.md
@@ -170,5 +170,5 @@ Hugo 允许你通过覆盖主题模板来改造主题，例如：你可以创建
 这部分内容在 [PWA 支持页面][pwa-support] 中介绍。
 
 <!-- link reference definition -->
-[theme-config]: {{< relref path="/documentation/basics#theme-configuration" >}}
+[theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
 [pwa-support]: {{< relref path="/guides/pwa-support" >}}
diff --git a/content/zh-cn/documentation/content-management/introduction/index.md b/content/zh-cn/documentation/content-management/introduction/index.md
@@ -1,5 +1,5 @@
 ---
-weight: 5
+weight: 4
 title: 内容管理概述
 date: 2023-02-24T17:27:22+08:00
 type: posts
@@ -64,7 +64,7 @@ reward: true
 
 {{< admonition >}}
 **不是所有**的以下前置参数都必须在你的每篇文章中设置。
-只有在文章的参数和你的 [主题配置]({{< relref path="/documentation/basics#theme-configuration" >}}) 中的 `page` 部分不一致时才有必要这么做。
+只有在文章的参数和你的 [主题配置]({{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}) 中的 `page` 部分不一致时才有必要这么做。
 {{< /admonition >}}
 
 - **title**: 文章标题
@@ -322,8 +322,160 @@ hugo new friends/index.md
 
 这部分内容在 [Shortcodes 页面][shortcodes] 中介绍。
 
-[theme-config]: {{< relref path="/documentation/basics#theme-configuration" >}}
-[content-to-menu]: {{< relref path="/documentation/basics#content-to-menu" >}}
+## 多语言和 I18n
+
+**FixIt** 主题完全兼容 Hugo 的多语言模式，并且支持在网页上切换语言。
+
+![语言切换](/documentation/content-management/introduction/language-switch.gif '语言切换')
+
+### 兼容性 {#language-compatibility}
+
+{{< version 0.2.10 changed >}}
+
+| 语言         | Hugo 代码 | HTML `lang` 属性 | 主题文档                             |
+| :----------- | :-------: | :--------------: | :----------------------------------: |
+| 英语         | `en`      | `en`             | :(fa-regular fa-check-square fa-fw): |
+| 简体中文     | `zh-cn`   | `zh-CN`          | :(fa-regular fa-check-square fa-fw): |
+| 繁体中文     | `zh-tw`   | `zh-TW`          | :(fa-regular fa-square fa-fw):       |
+| 法语         | `fr`      | `fr`             | :(fa-regular fa-square fa-fw):       |
+| 波兰语       | `pl`      | `pl`             | :(fa-regular fa-square fa-fw):       |
+| 巴西葡萄牙语 | `pt-br`   | `pt-BR`          | :(fa-regular fa-square fa-fw):       |
+| 意大利语     | `it`      | `it`             | :(fa-regular fa-square fa-fw):       |
+| 西班牙语     | `es`      | `es`             | :(fa-regular fa-square fa-fw):       |
+| 德语         | `de`      | `de`             | :(fa-regular fa-square fa-fw):       |
+| 塞尔维亚语   | `sr`      | `sr`             | :(fa-regular fa-square fa-fw):       |
+| 俄语         | `ru`      | `ru`             | :(fa-regular fa-square fa-fw):       |
+| 罗马尼亚语   | `ro`      | `ro`             | :(fa-regular fa-square fa-fw):       |
+| 越南语       | `vi`      | `vi`             | :(fa-regular fa-square fa-fw):       |
+
+### 基本配置
+
+学习了 [Hugo 如何处理多语言网站][multilingual] 之后，请在站点配置中定义你的网站语言。
+
+例如，一个支持英语，中文和法语的网站配置：
+
+```toml
+# [en, zh-cn, fr, pl, ...] 设置默认的语言
+defaultContentLanguage = "zh-cn"
+
+[languages]
+  [languages.en]
+    weight = 1
+    title = "My Hugo FixIt Site"
+    languageCode = "en"
+    languageName = "English"
+    [[languages.en.menu.main]]
+      identifier = "posts"
+      pre = ""
+      post = ""
+      name = "Posts"
+      url = "/posts/"
+      title = ""
+      weight = 1
+    [[languages.en.menu.main]]
+      identifier = "tags"
+      pre = ""
+      post = ""
+      name = "Tags"
+      url = "/tags/"
+      title = ""
+      weight = 2
+    [[languages.en.menu.main]]
+      identifier = "categories"
+      pre = ""
+      post = ""
+      name = "Categories"
+      url = "/categories/"
+      title = ""
+      weight = 3
+
+  [languages.zh-cn]
+    weight = 2
+    title = "我的 Hugo FixIt 网站"
+    # 网站语言，仅在这里 CN 大写
+    languageCode = "zh-CN"
+    languageName = "简体中文"
+    # 是否包括中日韩文字
+    hasCJKLanguage = true
+    [[languages.zh-cn.menu.main]]
+      identifier = "posts"
+      pre = ""
+      post = ""
+      name = "文章"
+      url = "/posts/"
+      title = ""
+      weight = 1
+    [[languages.zh-cn.menu.main]]
+      identifier = "tags"
+      pre = ""
+      post = ""
+      name = "标签"
+      url = "/tags/"
+      title = ""
+      weight = 2
+    [[languages.zh-cn.menu.main]]
+      identifier = "categories"
+      pre = ""
+      post = ""
+      name = "分类"
+      url = "/categories/"
+      title = ""
+      weight = 3
+
+  [languages.fr]
+    weight = 3
+    title = "Mon nouveau site Hugo FixIt"
+    languageCode = "fr"
+    languageName = "Français"
+    [[languages.fr.menu.main]]
+      identifier = "posts"
+      pre = ""
+      post = ""
+      name = "Postes"
+      url = "/posts/"
+      title = ""
+      weight = 1
+    [[languages.fr.menu.main]]
+      identifier = "tags"
+      pre = ""
+      post = ""
+      name = "Balises"
+      url = "/tags/"
+      title = ""
+      weight = 2
+    [[languages.fr.menu.main]]
+      identifier = "categories"
+      pre = ""
+      post = ""
+      name = "Catégories"
+      url = "/categories/"
+      title = ""
+      weight = 3
+```
+
+然后，对于每个新页面，将语言代码附加到文件名中。
+
+单个文件 `my-page.md` 需要分为三个文件：
+
+- 英语：`my-page.en.md`
+- 中文：`my-page.zh-cn.md`
+- 法语：`my-page.fr.md`
+
+{{< admonition tip >}}
+也可以使用 [文章前置参数](https://gohugo.io/content-management/multilingual#translate-your-content) 来翻译网址。
+{{< /admonition >}}
+
+#### 修改默认的翻译字符串
+
+翻译字符串用于在主题中使用的常见默认值。
+目前提供 [一些语言](#language-compatibility) 的翻译，但你可能自定义其他语言或覆盖默认值。
+
+要覆盖默认值，请在你项目的 I18n 目录 `i18n/<languageCode>.toml` 中创建一个新文件，并从 `themes/FixIt/i18n/en.toml` 中获得提示。
+
+另外，由于你的翻译可能会帮助到其他人，请花点时间通过 [创建一个 PR :(fa-solid fa-code-branch fa-fw):][pulls] 来贡献主题翻译，谢谢！
+
+[theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
+[content-to-menu]: {{< relref path="/documentation/getting-started/configuration#content-to-menu" >}}
 [ruby-syntax]: {{< relref path="/documentation/content-management/markdown-syntax/extended#ruby" >}}
 [fraction-syntax]: {{< relref path="/documentation/content-management/markdown-syntax/extended#fraction" >}}
 [fontawesome-syntax]: {{< relref path="/documentation/content-management/markdown-syntax/extended#fontawesome" >}}
@@ -332,3 +484,5 @@ hugo new friends/index.md
 [basic-markdown-syntax]: {{< relref path="/documentation/content-management/markdown-syntax/basics" >}}
 [extended-markdown-syntax]: {{< relref path="/documentation/content-management/markdown-syntax/extended" >}}
 [shortcodes]: {{< relref path="/documentation/content-management/shortcodes" >}}
+[multilingual]: https://gohugo.io/content-management/multilingual
+[pulls]: https://github.com/hugo-fixit/FixIt/pulls
diff --git a/content/zh-cn/documentation/content-management/markdown-syntax/extended/index.md b/content/zh-cn/documentation/content-management/markdown-syntax/extended/index.md
@@ -185,7 +185,7 @@ $$ c = \pm\sqrt{a^2 + b^2} $$
 \end{CD}
 
 {{< admonition tip >}}
-你可以在 [主题配置]({{< relref path="/documentation/basics#theme-configuration" >}}) 中自定义行内公式和公式块的分割符。
+你可以在 [主题配置]({{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}) 中自定义行内公式和公式块的分割符。
 {{< /admonition >}}
 
 ### Copy-tex
@@ -388,7 +388,7 @@ console.log('hello FixIt!');
 
 [emoji-support]: {{< relref path="/guides/emoji-support" >}}
 [katex]: https://katex.org/
-[theme-config]: {{< relref path="/documentation/basics#theme-configuration" >}}
+[theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
 [copy-tex]: https://github.com/Khan/KaTeX/tree/master/contrib/copy-tex
 [mhchem]: https://github.com/Khan/KaTeX/tree/master/contrib/mhchem
 [fontawesome]: https://fontawesome.com/

diff --git a/content/zh-cn/documentation/content-management/shortcodes/extended/mapbox/index.md b/content/zh-cn/documentation/content-management/shortcodes/extended/mapbox/index.md
@@ -106,7 +106,7 @@ mapbox:
 [mapbox]: https://docs.mapbox.com/mapbox-gl-js
 [vector-tiles]: https://docs.mapbox.com/help/glossary/vector-tiles/
 [style-spec]: https://docs.mapbox.com/mapbox-gl-js/style-spec/
-[theme-config]: {{< relref path="/documentation/basics#theme-configuration" >}}
+[theme-config]: {{< relref path="/documentation/getting-started/configuration#theme-configuration" >}}
 [front-matter]: {{< relref path="/documentation/content-management/introduction#front-matter" >}}
 [navigationcontrol]: https://docs.mapbox.com/mapbox-gl-js/api#navigationcontrol
 [geolocatecontrol]: https://docs.mapbox.com/mapbox-gl-js/api#geolocatecontrol

diff --git a/...sics/full-configuration-preview.zh-cn.png → ...tion/full-configuration-preview.zh-cn.png b/...sics/full-configuration-preview.zh-cn.png → ...tion/full-configuration-preview.zh-cn.png