Docs: 更新自定义输出格式文档

hugo-fixit · Aug 25, 2024 · 40abda0 · 40abda0
1 parent 13c67e5
commit 40abda0
Show file tree

Hide file tree

Showing 17 changed files with 89 additions and 109 deletions.
diff --git a/README.en.md b/README.en.md
@@ -2,7 +2,7 @@
 
 [![Production environment](https://img.shields.io/github/deployments/hugo-fixit/docs/Production?style=flat&label=Production&logo=vercel)](https://fixit.lruihao.cn/)
 [![Preview environment](https://img.shields.io/github/deployments/hugo-fixit/docs/Preview?style=flat&label=Preview&logo=vercel)](https://pre.fixit.lruihao.cn/)
-[![Hugo](https://img.shields.io/badge/Hugo-%5E0.127.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
+[![Hugo](https://img.shields.io/badge/Hugo-%5E0.129.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
 
 👉 [中文](README.md) | English
 
@@ -12,7 +12,7 @@
 
 - [Node.js](https://nodejs.org/): >= 18.0.0
 - [Go](https://go.dev/dl/)
-- [Hugo](https://gohugo.io/installation/): >= 0.127.0 (extended version)
+- [Hugo](https://gohugo.io/installation/): >= 0.129.0 (extended version)
 
 ## Contributing
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![Production environment](https://img.shields.io/github/deployments/hugo-fixit/docs/Production?style=flat&label=Production&logo=vercel)](https://fixit.lruihao.cn/)
 [![Preview environment](https://img.shields.io/github/deployments/hugo-fixit/docs/Preview?style=flat&label=Preview&logo=vercel)](https://pre.fixit.lruihao.cn/)
-[![Hugo](https://img.shields.io/badge/Hugo-%5E0.127.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
+[![Hugo](https://img.shields.io/badge/Hugo-%5E0.129.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
 
 👉 中文 | [English](README.en.md)
 
@@ -12,7 +12,7 @@
 
 - [Node.js](https://nodejs.org/): >= 18.0.0
 - [Go](https://go.dev/dl/)
-- [Hugo](https://gohugo.io/installation/): >= 0.127.0 (extended version)
+- [Hugo](https://gohugo.io/installation/): >= 0.129.0 (extended version)
 
 ## 贡献文档
 

diff --git a/config/_default/module.toml b/config/_default/module.toml
@@ -14,4 +14,4 @@
 
 [hugoVersion]
   extended = true
-  min = "0.127.0"
+  min = "0.129.0"
diff --git a/content/en/contributing/development/index.md b/content/en/contributing/development/index.md
@@ -33,7 +33,7 @@ For a complete guide to contributing to FixIt, see the [Contribution Guide][cont
 ## Prerequisites
 
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/hugo-fixit/FixIt?style=flat)](https://github.com/hugo-fixit/FixIt/releases)
-[![Hugo](https://img.shields.io/badge/Hugo-%5E0.127.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
+[![Hugo](https://img.shields.io/badge/Hugo-%5E0.129.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
 [![License](https://img.shields.io/github/license/hugo-fixit/FixIt?style=flat)](https://github.com/hugo-fixit/FixIt/blob/master/LICENSE)
 {style="font-size: 1.25em;"}
 

diff --git a/content/en/documentation/getting-started/configuration/index.md b/content/en/documentation/getting-started/configuration/index.md
@@ -401,7 +401,7 @@ In order to generate `search.json` for searching, add `search` output file type
 
 ```toml
 [outputs]
-  home = ["html", "rss", "archives", "search"]
+  home = ["html", "rss", "archives", "offline", "search"]
 ```
 
 {{< link href="/guides/algolia-atomic" content="Tips about algolia" card=true >}}
@@ -1542,21 +1542,11 @@ Hugo can output content in multiple formats. The **FixIt** theme takes advantage
 More details about the configuration of output formats can be found in the [Custom output formats][hugo-output-formats] page.
 
 ```toml
-# {{< version 0.2.15 changed >}}
 [mediaTypes]
-  # Options to make output .md files
   [mediaTypes."text/markdown"]
     suffixes = ["md"]
-  # Options to make output .txt files
-  [mediaTypes."text/plain"]
-    suffixes = ["txt"]
 
 [outputFormats]
-  # Options to make output .md files
-  [outputFormats.MarkDown]
-    mediaType = "text/markdown"
-    isPlainText = true
-    isHTML = false
   # {{< version 0.3.0 >}} Options to make output /archives/index.html file
   [outputFormats.archives]
     path = "archives"
@@ -1574,7 +1564,7 @@ More details about the configuration of output formats can be found in the [Cust
     isHTML = true
     permalinkable = true
   # {{< version 0.3.0 >}} Options to make output readme.md file
-  [outputFormats.README]
+  [outputFormats.readme]
     baseName = "readme"
     mediaType = "text/markdown"
     isPlainText = true
@@ -1585,21 +1575,37 @@ More details about the configuration of output formats can be found in the [Cust
     mediaType = "text/plain"
     isPlainText = true
     isHTML = false
+  # {{< version 0.3.10 >}} Options to make output search.json file
+  [outputFormats.search]
+    baseName = "search"
+    mediaType = "application/json"
+    rel = "search"
+    isPlainText = true
+    isHTML = false
+    permalinkable = true
+```
+
+You only need to configure the root configuration key `outputs`, because the **FixIt** theme has already configured the `mediaTypes` and `outputFormats` for you.
 
+```toml
 # Options to make hugo output files, the optional values are below:
-# home: ["HTML", "RSS", "JSON", "archives", "offline", "README", "baidu_urls"]
-# page: ["HTML", "MarkDown"]
-# section: ["HTML", "RSS"]
-# taxonomy: ["HTML", "RSS"]
-# term: ["HTML", "RSS"]
+# home = ["html", "rss", "archives", "offline", "readme", "baidu_urls", "search"]
+# page = ["html", "markdown"]
+# section = ["html", "rss"]
+# taxonomy = ["html"]
+# term = ["html", "rss"]
 [outputs]
-  home = ["HTML", "RSS", "JSON", "archives", "offline"]
-  page = ["HTML", "MarkDown"]
-  section = ["HTML", "RSS"]
-  taxonomy = ["HTML"]
-  term = ["HTML", "RSS"]
+  home = ["html", "rss", "archives", "offline", "search"]
+  page = ["html", "markdown"]
+  section = ["html", "rss"]
+  taxonomy = ["html"]
+  term = ["html", "rss"]
 ```
 
+{{< admonition tip >}}
+If you want the `outputs` configuration to always be consistent with the theme, you can set `outputs._merge` to `shallow`.
+{{< /admonition >}}
+
 ## Favicon Generation
 
 It is recommended to put your own favicons, `browserconfig.xml` and `site.webmanifest` files into the `/static` directory.

diff --git a/content/en/documentation/getting-started/quick-start/index.md b/content/en/documentation/getting-started/quick-start/index.md
@@ -41,7 +41,7 @@ If this is your first time using [Hugo](https://gohugo.io/), we strongly suggest
 
 Before you begin this tutorial you must:
 
-1. [Install Hugo][hugo-installing] (extended edition, v0.127.0 or later)
+1. [Install Hugo][hugo-installing] (extended edition, v0.129.0 or later)
 2. [Install Git][git-install]
 
 You must also be comfortable working from the command line.
@@ -50,7 +50,7 @@ You must also be comfortable working from the command line.
 
 ### Commands
 
-Verify that you have installed Hugo v0.127.0 or later.
+Verify that you have installed Hugo v0.129.0 or later.
 
 ```bash
 hugo version

diff --git a/content/en/documentation/installation/index.md b/content/en/documentation/installation/index.md
@@ -50,7 +50,7 @@ Node.js is required to:
 
 Please refer to the relevant documentation for installation instructions:
 
-- [Hugo][hugo-install] (extended edition, v0.127.0 or later)
+- [Hugo][hugo-install] (extended edition, v0.129.0 or later)
 - [Git][git-install]
 - [Go][go-install]
 - _[Dart Sass][dart-sass-install] (not used yet)_

diff --git a/content/en/guides/algolia-atomic/index.md b/content/en/guides/algolia-atomic/index.md
@@ -55,7 +55,7 @@ In order to generate `search.json` for searching, add `search` output file type
 
 ```toml
 [outputs]
-  home = ["html", "rss", "archives", "search"]
+  home = ["html", "rss", "archives", "offline", "search"]
 ```
 
 ## Upload Index

diff --git a/content/en/guides/pwa-support/index.md b/content/en/guides/pwa-support/index.md
@@ -102,33 +102,15 @@ Here is a sample `site.webmanifest` file from this documentation site.
 
 The offline page will be served to your visitor when they are offline.
 
-You only need to follow a few steps to configure the offline page.
-
-1. Add `outputFormats.offline` as below:
-
-    ```toml
-    [outputFormats]
-      # ...
-      # {{< version 0.3.0 >}} Options to make output /offline/index.html file
-      [offline]
-        path = "offline"
-        baseName = "index"
-        mediaType = "text/html"
-        isPlainText = false
-        isHTML = true
-        permalinkable = true
-    ```
-
-2. Add "offline" in `outputs.home` as below:
-
-    ```toml
-    [outputs]
-      home = ["HTML", "RSS", "JSON", "BaiduUrls", "offline"]
-      # ...
-    ```
+You only need to add "offline" in `outputs.home` as below:
+
+```toml
+[outputs]
+  home = ["html", "rss", "archives", "offline", "search"]
+```
 
 {{< admonition type=tip title="I18n" open=true >}}
-Currently, i18n is supported for the offline page, but only for English and Chinese. Of course, you can [Contribute with a new language](https://github.com/hugo-fixit/FixIt/pulls) to the theme!
+Currently, I18n is supported for the offline page, but only for English and Chinese. Of course, you can [Contribute with a new language](https://github.com/hugo-fixit/FixIt/pulls) to the theme!
 {{< /admonition >}}
 
 ### Enable the `enablePWA` option {#enable-pwa}

diff --git a/content/zh-cn/contributing/development/index.md b/content/zh-cn/contributing/development/index.md
@@ -33,7 +33,7 @@ menu:
 ## 先决条件
 
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/hugo-fixit/FixIt?style=flat)](https://github.com/hugo-fixit/FixIt/releases)
-[![Hugo](https://img.shields.io/badge/Hugo-%5E0.127.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
+[![Hugo](https://img.shields.io/badge/Hugo-%5E0.129.0-ff4088?style=flat&logo=hugo)](https://gohugo.io/)
 [![License](https://img.shields.io/github/license/hugo-fixit/FixIt?style=flat)](https://github.com/hugo-fixit/FixIt/blob/master/LICENSE)
 {style="font-size: 1.25em;"}
 

diff --git a/content/zh-cn/documentation/getting-started/configuration/index.md b/content/zh-cn/documentation/getting-started/configuration/index.md
@@ -403,7 +403,7 @@ fuse
 
 ```toml
 [outputs]
-  home = ["html", "rss", "archives", "search"]
+  home = ["html", "rss", "archives", "offline", "search"]
 ```
 
 {{< link href="/zh-cn/guides/algolia-atomic/" content="关于 algolia 的使用技巧" card=true >}}
@@ -1533,21 +1533,11 @@ Hugo 可以输出多种格式的内容，**FixIt** 主题利用了这个功能
 有关输出格式配置的更多详细信息，请参阅 [自定义输出格式][hugo-output-formats] 页面。
 
 ```toml
-# {{< version 0.2.15 changed >}}
 [mediaTypes]
-  # 用于输出 Markdown 格式文档的设置
   [mediaTypes."text/markdown"]
     suffixes = ["md"]
-  # 用于输出 txt 格式文档的设置
-  [mediaTypes."text/plain"]
-    suffixes = ["txt"]
 
 [outputFormats]
-  # 用于输出 Markdown 格式文档的设置
-  [outputFormats.MarkDown]
-    mediaType = "text/markdown"
-    isPlainText = true
-    isHTML = false
   # {{< version 0.3.0 >}} 用于输出 /archives/index.html 文件的设置
   [outputFormats.archives]
     path = "archives"
@@ -1565,7 +1555,7 @@ Hugo 可以输出多种格式的内容，**FixIt** 主题利用了这个功能
     isHTML = true
     permalinkable = true
   # {{< version 0.3.0 >}} 用于输出 readme.md 文件的设置
-  [outputFormats.README]
+  [outputFormats.readme]
     baseName = "readme"
     mediaType = "text/markdown"
     isPlainText = true
@@ -1576,21 +1566,37 @@ Hugo 可以输出多种格式的内容，**FixIt** 主题利用了这个功能
     mediaType = "text/plain"
     isPlainText = true
     isHTML = false
+  # {{< version 0.3.10 >}} 用于输出 search.json 文件的设置
+  [outputFormats.search]
+    baseName = "search"
+    mediaType = "application/json"
+    rel = "search"
+    isPlainText = true
+    isHTML = false
+    permalinkable = true
+```
+
+基本上你无需配置 `mediaTypes` 和 `outputFormats` 的配置，因为 **FixIt** 主题已经为你配置好了。你只需要配置 `outputs` 部分即可。
 
+```toml
 # 用于 Hugo 输出文档的设置，可选值如下：
-# home: ["HTML", "RSS", "JSON", "archives", "offline", "README", "baidu_urls"]
-# page: ["HTML", "MarkDown"]
-# section: ["HTML", "RSS"]
-# taxonomy: ["HTML", "RSS"]
-# term: ["HTML", "RSS"]
+# home = ["html", "rss", "archives", "offline", "readme", "baidu_urls", "search"]
+# page = ["html", "markdown"]
+# section = ["html", "rss"]
+# taxonomy = ["html"]
+# term = ["html", "rss"]
 [outputs]
-  home = ["HTML", "RSS", "JSON", "archives", "offline"]
-  page = ["HTML", "MarkDown"]
-  section = ["HTML", "RSS"]
-  taxonomy = ["HTML"]
-  term = ["HTML", "RSS"]
+  home = ["html", "rss", "archives", "offline", "search"]
+  page = ["html", "markdown"]
+  section = ["html", "rss"]
+  taxonomy = ["html"]
+  term = ["html", "rss"]
 ```
 
+{{< admonition tip >}}
+如果你希望 `outputs` 配置始终保持和主题一致，你可以设置 `outputs._merge` 为 `shallow`。
+{{< /admonition >}}
+
 ## Favicon 生成
 
 强烈建议你把你自己的网站图标，`browserconfig.xml` 和 `site.webmanifest` 文件放在 `/static` 目录。

diff --git a/content/zh-cn/documentation/getting-started/quick-start/index.md b/content/zh-cn/documentation/getting-started/quick-start/index.md
@@ -41,7 +41,7 @@ toc:
 
 在开始本教程之前，你必须：
 
-1. [安装 Hugo][hugo-installing]（扩展版，v0.127.0 或更高版本）
+1. [安装 Hugo][hugo-installing]（扩展版，v0.129.0 或更高版本）
 2. [安装 Git][git-install]
 
 你还必须熟悉使用命令行。
@@ -50,7 +50,7 @@ toc:
 
 ### 命令
 
-验证你是否安装了 Hugo v0.127.0 或更高版本。
+验证你是否安装了 Hugo v0.129.0 或更高版本。
 
 ```bash
 hugo version

diff --git a/content/zh-cn/documentation/installation/index.md b/content/zh-cn/documentation/installation/index.md
@@ -50,7 +50,7 @@ Node.js 用于：
 
 请参考相关文档以获取安装说明：
 
-- [Hugo][hugo-install]（扩展版，v0.127.0 或更高版本）
+- [Hugo][hugo-install]（扩展版，v0.129.0 或更高版本）
 - [Git][git-install]
 - [Go][go-install]
 - _[Dart Sass][dart-sass-install]（尚未使用）_

diff --git a/content/zh-cn/guides/algolia-atomic/index.md b/content/zh-cn/guides/algolia-atomic/index.md
@@ -55,7 +55,7 @@ description: 在 FixIt 主题中使用 algolia 的技巧。
 
 ```toml
 [outputs]
-  home = ["html", "rss", "archives", "search"]
+  home = ["html", "rss", "archives", "offline", "search"]
 ```
 
 ## 上传索引

diff --git a/content/zh-cn/guides/pwa-support/index.md b/content/zh-cn/guides/pwa-support/index.md
@@ -100,33 +100,15 @@ repost:
 
 ### 配置离线页面 {#offline-page}
 
-离线页面将在访客离线访问未缓存的页面时显示，你只需要简单几步就可以配置离线页面。
-
-1. 增加 `outputFormats.offline` 配置：
-
-    ```toml
-    [outputFormats]
-      # ...
-      # {{< version 0.3.0 >}} 用于输出 /offline/index.html 文件的设置
-      [offline]
-        path = "offline"
-        baseName = "index"
-        mediaType = "text/html"
-        isPlainText = false
-        isHTML = true
-        permalinkable = true
-    ```
-
-2. 添加 "offline" 到 `outputs.home` 配置中：
-
-    ```toml
-    [outputs]
-      home = ["HTML", "RSS", "JSON", "BaiduUrls", "offline"]
-      # ...
-    ```
+离线页面将在访客离线访问未缓存的页面时显示，你只需要添加 "offline" 到 `outputs.home` 配置中：
+
+```toml
+[outputs]
+  home = ["html", "rss", "archives", "offline", "search"]
+```
 
 {{< admonition type=tip title="I18n" open=true >}}
-目前，离线页面支持 i18n 多语言，但只支持英文和中文。当然，你可以给主题 [贡献一种新的语言](https://github.com/hugo-fixit/FixIt/pulls)！
+目前，离线页面支持 I18n 多语言，但只支持英文和中文。当然，你可以给主题 [贡献一种新的语言](https://github.com/hugo-fixit/FixIt/pulls)！
 {{< /admonition >}}
 
 ### 开启 `enablePWA` 选项 {#enable-pwa}

diff --git a/data/projects.en.yml b/data/projects.en.yml
@@ -12,6 +12,8 @@
 - title: 🧩 Layout components
   repos:
     - hugo-fixit/component-projects
+    - hugo-fixit/hugo-atom-feed
+    - hugo-fixit/hugo-json-feed
 - title: 🛠️ Tools
   repos:
     - hugo-fixit/component-skeleton