From f603aeedb212832ae274d19819de586772d59f76 Mon Sep 17 00:00:00 2001 From: Cell <1024@lruihao.cn> Date: Sat, 23 Mar 2024 21:47:43 +0800 Subject: [PATCH] =?UTF-8?q?Docs:=20=E6=96=B0=E5=A2=9E=E6=96=87=E6=A1=A3=20?= =?UTF-8?q?=E2=80=9C=E9=85=8D=E7=BD=AE=20FixIt=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../content-management/introduction/index.md | 2 +- .../getting-started/configuration/index.md | 9 +- content/zh-cn/documentation/advanced/index.md | 2 +- .../content-management/introduction/index.md | 162 +- .../markdown-syntax/extended/index.md | 4 +- .../shortcodes/extended/mapbox/index.md | 2 +- .../full-configuration-preview.zh-cn.png | Bin .../configuration}/index.md | 1772 ++++++++++------- 8 files changed, 1173 insertions(+), 780 deletions(-) rename content/zh-cn/documentation/{basics => getting-started/configuration}/full-configuration-preview.zh-cn.png (100%) rename content/zh-cn/documentation/{basics => getting-started/configuration}/index.md (51%) diff --git a/content/en/documentation/content-management/introduction/index.md b/content/en/documentation/content-management/introduction/index.md index 6ef636de..5da58808 100644 --- 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/.toml` and inspire yourself from `themes/FixIt/i18n/en.toml`. +To override these values, create a new file in your local I18n folder `i18n/.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 index c5e2ee52..ff19ec42 100644 --- 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 . [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 index 2853898e..42d2197a 100644 --- a/content/zh-cn/documentation/advanced/index.md +++ b/content/zh-cn/documentation/advanced/index.md @@ -170,5 +170,5 @@ Hugo 允许你通过覆盖主题模板来改造主题，例如：你可以创建 这部分内容在 [PWA 支持页面][pwa-support] 中介绍。 -[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 index 601ab949..58e923b9 100644 --- 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/.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 index 9dbfa870..fa894767 100644 --- 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 index 8a9e48c6..dccb0708 100644 --- 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/content/zh-cn/documentation/basics/full-configuration-preview.zh-cn.png b/content/zh-cn/documentation/getting-started/configuration/full-configuration-preview.zh-cn.png similarity index 100% rename from content/zh-cn/documentation/basics/full-configuration-preview.zh-cn.png rename to content/zh-cn/documentation/getting-started/configuration/full-configuration-preview.zh-cn.png diff --git a/content/zh-cn/documentation/basics/index.md b/content/zh-cn/documentation/getting-started/configuration/index.md similarity index 51% rename from content/zh-cn/documentation/basics/index.md rename to content/zh-cn/documentation/getting-started/configuration/index.md index a4cef50f..1f4d79d0 100644 --- a/content/zh-cn/documentation/basics/index.md +++ b/content/zh-cn/documentation/getting-started/configuration/index.md @@ -1,14 +1,16 @@ --- weight: 3 -title: 基础使用 -date: 2023-02-23T16:04:22+08:00 +title: 配置 FixIt +linkTitle: 配置 +date: 2024-03-07T15:37:59+08:00 type: posts aliases: - /zh-cn/theme-documentation-basics/ + - /zh-cn/documentation/basics/ author: name: Lruihao link: https://lruihao.cn -description: 探索 Hugo - FixIt 主题的的基础知识和背后的核心概念。 +description: 了解如何配置你的 Hugo FixIt 站点。 resources: - name: featured-image src: featured-image.png @@ -18,94 +20,42 @@ tags: - Basics categories: - Documentation +collections: + - Getting Started lightgallery: true reward: true toc: auto: false menu: main: - title: 探索 Hugo - FixIt 主题的的基础知识和背后的核心概念。 + title: 了解如何配置你的 Hugo FixIt 站点。 parent: documentation weight: 2 params: icon: fa-brands fa-readme --- -探索 Hugo - **FixIt** 主题的的基础知识和背后的核心概念。 +了解如何配置你的 Hugo **FixIt** 站点。 -## 安装方式 {#install-theme} +## 配置文件 {#configuration-file} - -{{< link "https://github.com/hugo-fixit/FixIt" "FixIt 主题的仓库" "" true >}} - -实际上有多种方式可以快速安装主题，选择其中 **一种** 即可（推荐 [Git 子模块](#git-submodule) 或者 [Hugo 模块](#hugo-module)）。 - -### 手动下载 - -你可以下载主题的 [最新版本 :(fa-regular fa-file-archive fa-fw): .zip 文件][releases] 并且解压放到 `themes` 目录。 - -### Git 克隆 - -或者，也可以直接把这个主题克隆到 `themes` 目录： - -```bash -git clone https://github.com/hugo-fixit/FixIt.git themes/FixIt -``` - -### Git 子模块 {#git-submodule} - - -{{< link "https://github.com/hugo-fixit/hugo-fixit-blog-git" "基于 Git 子模块的快速入门模板" "" true >}} - -另外，在你的项目目录初始化一个空的 Git 存储库，将 [FixIt][fixit] 主题克隆到 `themes` 目录中，将其作为 [Git 子模块][git-submodule] 添加到你的项目中。 - -```bash -git init -git submodule add https://github.com/hugo-fixit/FixIt.git themes/FixIt -``` - -如果你想使用 `dev` 分支上的版本，可以使用以下命令： - -```bash -git submodule add -b dev https://github.com/hugo-fixit/FixIt.git themes/FixIt -``` - -或者将子模块分支从 `master` 切换到 `dev`： - -```bash -git submodule set-branch -b dev themes/FixIt -``` - -### Hugo 模块 {#hugo-module} - - -{{< link "https://github.com/hugo-fixit/hugo-fixit-blog-go" "基于 Hugo 模块的快速入门模板" "" true >}} - -> 以这种方式，无需要在 `hugo.toml` 中配置 `theme = "FixIt"`。 - -将 [Hugo 模块][hugo-modules] 用于主题的最简单方法是将其导入配置中。请参阅 [使用 Hugo 模块][use-hugo-modules]。 - -1. 初始化 Hugo 模块系统：`hugo mod init github.com//` -2. 导入主题： - - ```toml - [module] - [[module.imports]] - path = "github.com/hugo-fixit/FixIt" - ``` - -## 完整配置 +Hugo 有一些全局配置设置，但这不在本文的讨论范围之内。 在开始配置之前，建议你执行以下命令，将主题的默认 [hugo.toml][config] 复制到你的项目中： ```bash -mv hugo.toml config.old.toml +mv hugo.toml hugo.old.toml cp themes/FixIt/hugo.toml hugo.toml +echo "theme = 'FixIt'" >> hugo.toml ``` -### 菜单配置 {#menu-configuration} +作为进阶使用，你也可以将你的配置按环境、根配置键和语言拆分，而不是一个单独的站点配置文件。 + +更多细节可以在 [配置 Hugo][hugo-config] 页面找到。 + +## 菜单配置 {#menu-configuration} Hugo 有一个简单而强大的 [菜单系统][menu-system]。 @@ -152,117 +102,230 @@ Hugo 有一个简单而强大的 [菜单系统][menu-system]。 ```yaml --- -title: 入门篇 +title: 配置 Fixit author: Lruihao menu: main: - title: 探索 Hugo - FixIt 主题的的基础知识和背后的核心概念。 + title: 了解如何配置你的 Hugo FixIt 站点。 parent: documentation + weight: 3 params: icon: fa-brands fa-readme # ... --- ``` -### 主题配置 {#theme-configuration} +## 主题配置 {#theme-configuration} -除了 [Hugo 全局配置][hugo-config] 和 [菜单配置](#menu-configuration) 之外，**FixIt** 主题还允许你在网站配置中定义以下参数。 +除了 Hugo 全局配置外，FixIt 还通过根配置键 `params` 提供了一些主题配置。 -请打开下面的代码块查看完整的 `hugo.toml` 示例配置 :(fa-regular fa-hand-point-down fa-fw):: +一个简单的例子： -```toml +```toml {title="hugo.toml"} +baseURL = 'https://example.org/' +languageCode = 'en' +title = 'ABC Widgets, Inc.' [params] - # {{< version 0.2.15 changed >}} FixIt 主题版本 - version = "0.2.X" # 例如："0.2.X", "0.2.15", "v0.2.15" 等 - # 网站描述 - description = "这是我的 Hugo FixIt 网站" - # 网站关键词 + version = "0.3.X" + description = "This is my new Hugo FixIt site" keywords = ["Hugo", "FixIt"] - # 网站默认主题样式 ["light", "dark", "auto"] - defaultTheme = "auto" - # {{< version 0.1.1 >}} 哪种哈希函数用来 SRI, 为空时表示不使用 SRI - # ["sha256", "sha384", "sha512", "md5"] - fingerprint = "" - # {{< version 0.2.0 >}} 日期格式 - dateFormat = "2006-01-02" - # 网站图片，用于 Open Graph 和 Twitter Cards - images = ["/logo.png"] - # {{< version 0.2.12 >}} 开启 PWA 支持 - enablePWA = true - # {{< version 0.2.14 >}} 是否自动显示外链图标 - externalIcon = false - # {{< version 0.3.0 >}} 是否反转导航菜单的顺序 - navigationReverse = false - # {{< version 0.3.0 >}} 是否在每个页面标题中添加网站标题 - # 请记得在 `hugo.toml` 中设置网站标题 (例如 title = "title") - withSiteTitle = true - # {{< version 0.3.0 >}} 当网站标题被添加到每个页面标题时的标题分隔符 - titleDelimiter = "-" - # {{< version 0.3.0 >}} 是否在主页标题中添加网站副标题 - # 请记得通过 `params.header.subtitle.name` 设置网站副标题 - indexWithSubtitle = false - # {{< version 0.2.14 >}} 默认情况下，FixIt 只会在主页的 HTML 头中注入主题元标记 - # 你可以将其关闭，但如果你不这样做，我们将不胜感激，因为这是观察 FixIt 受欢迎程度上升的好方法 - disableThemeInject = false - - # 作者配置 + # ... +``` + +All theme configuration settings are as follows: + +所有 FixIt 主题配置设置如下： + +### version + +`string` FixIt 主题版本，例如：`0.3.X`, `0.3.0`, `v0.3.0` 等。 + +### description + +`string` 网站描述。 + +### keywords + +`string array` 网站关键词。 + +### defaultTheme + +`string` 网站默认主题样式，默认：`auto`，可选值可以是以下之一： + +light +: 浅色主题 + +dark +: 深色主题 + +auto +: 根据用户的系统主题自动选择 + +### fingerprint + +`string` 哪种哈希函数用来 SRI, 为空时表示不使用 SRI，可选值：`["sha256", "sha384", "sha512", "md5"]`。 + +### dateFormat + +`string` 日期格式，默认：`2006-01-02`。 + +### images + +`string array` 网站图片，用于 Open Graph 和 Twitter Cards。 + +### enablePWA + +{{< version 0.2.12 >}} + +`bool` 开启 PWA 支持，默认：`false`。 + +### externalIcon + +{{< version 0.2.14 >}} + +`bool` 是否自动显示外链图标，默认：`false`。 + +### navigationReverse + +{{< version 0.3.0 >}} + +`bool` 是否反转导航菜单的顺序，默认：`false`。 + +### withSiteTitle + +{{< version 0.3.0 >}} + +`bool` 是否在每个页面标题中添加网站标题，默认：`true`。请记得在 `hugo.toml` 中设置网站标题 (例如 `title = "title"`)。 + +### titleDelimiter + +{{< version 0.3.0 >}} + +`string` 当网站标题被添加到每个页面标题时的标题分隔符，默认：`-`。 + +### indexWithSubtitle + +{{< version 0.3.0 >}} + +`bool` 是否在主页标题中添加网站副标题，默认：`false`。请记得通过 `params.header.subtitle.name` 设置网站副标题。 + +### disableThemeInject + +{{< version 0.2.14 >}} + +`bool` 默认情况下，FixIt 只会在主页的 HTML 头中注入主题元标记。你可以将其关闭，但如果你不这样做，我们将不胜感激，因为这是观察 FixIt 受欢迎程度上升的好方法。 + +### author + +`map` 作者配置。 + +```toml +[params] [params.author] name = "" email = "" link = "" avatar = "" +``` + +name +: `string` 作者名称 - # {{< version 0.3.0 >}} 公共 Git 仓库信息，仅在 enableGitInfo 设为 true 时有效 +email +: `string` 作者邮箱 + +link +: `string` 作者链接 + +avatar +: `string` 作者头像 + +### gitInfo + +{{< version 0.3.0 >}} + +`map` 公共 Git 仓库信息，仅在 `enableGitInfo` 设为 `true` 时有效。 + +```toml +[params] [params.gitInfo] - # 例如 "https://github.com/hugo-fixit/docs" repo = "" branch = "main" - # 相对于仓库根目录的内容目录路径 dir = "content" - # 用于报告文章问题的 issue 模板 - # 可用模板参数：{title} {URL} {sourceURL} issueTpl = "title=[BUG]%20{title}&body=|Field|Value|%0A|-|-|%0A|Title|{title}|%0A|URL|{URL}|%0A|Filename|{sourceURL}|" +``` + +repo +: `string` 公开 Git 仓库的 URL，例如 `https://github.com/hugo-fixit/docs`。 + +branch +: `string` 仓库分支，默认：`main`。 + +dir +: `string` 相对于仓库根目录的内容目录路径。 - # {{< version 0.2.0 >}} 应用图标配置 +issueTpl +: `string` 用于报告文章问题的 issue 模板，可用模板参数：`{title}`, `{URL}`, `{sourceURL}`。 + +### app + +`map` 应用图标配置。 + +```toml +[params] [params.app] - # 当添加到 iOS 主屏幕或者 Android 启动器时的标题，覆盖默认标题 - title = "FixIt" - # 是否隐藏网站图标资源链接 + name = "" + shortName = "" noFavicon = false - # 更现代的 SVG 网站图标，可替代旧的 .png 和 .ico 文件 svgFavicon = "" - # Safari 图标颜色 iconColor = "#5bbad5" - # Windows v8-10 磁贴颜色 tileColor = "#da532c" - # {{< version 0.2.12 changed >}} Android 浏览器主题色 [params.app.themeColor] light = "#f8f8f8" dark = "#252627" +``` + +title +: `string` 当添加到 iOS 主屏幕或者 Android 启动器时的标题，覆盖默认标题。 + +noFavicon +: `bool` 是否隐藏网站图标资源链接。 + +svgFavicon +: `string` 更现代的 SVG 网站图标，可替代旧的 `.png` 和 `.ico` 文件。 + +iconColor +: `string` Safari 图标颜色。 + +tileColor +: `string` Windows v8-10 磁贴颜色。 - # {{< version 0.2.0 >}} 搜索配置 +themeColor +: `map` Android 浏览器主题色。 + +- light: `string` 浅色主题颜色，默认：`#f8f8f8`。 +- dark: `string` 深色主题颜色，默认：`#252627`。 + +### search + +`map` 搜索配置。 + +```toml +[params] [params.search] - enable = true - # 搜索引擎的类型 ["algolia", "fuse"] + enable = false type = "fuse" - # 文章内容最长索引长度 contentLength = 4000 - # 搜索框的占位提示语 placeholder = "" - # {{< version 0.2.1 >}} 最大结果数目 maxResultLength = 10 - # {{< version 0.2.3 >}} 结果内容片段长度 - snippetLength = 50 - # {{< version 0.2.1 >}} 搜索结果中高亮部分的 HTML 标签 + snippetLength = 30 highlightTag = "em" - # {{< version 0.2.4 >}} 是否在搜索索引中使用基于 baseURL 的绝对路径 absoluteURL = false [params.search.algolia] index = "" appID = "" searchKey = "" [params.search.fuse] - # {{< version 0.2.17 >}} https://fusejs.io/api/options.html isCaseSensitive = false minMatchCharLength = 2 findAllMatches = false @@ -272,226 +335,801 @@ menu: ignoreLocation = false useExtendedSearch = false ignoreFieldNorm = false +``` + +enable +: `bool` 是否启用搜索。 + +type +: `string` 搜索引擎的类型，可选值：`algolia`、`fuse`，默认：`fuse`。 + +contentLength +: `int` 文章内容最长索引长度。 + +placeholder +: `string` 搜索框的占位提示语。 + +maxResultLength +: `int` 最大结果数目。 + +snippetLength +: `int` 结果内容片段长度。 + +highlightTag +: `string` 搜索结果中高亮部分的 HTML 标签。 + +absoluteURL +: `bool` 是否在搜索索引中使用基于 `baseURL` 的绝对路径。 + +algolia +: `map` Algolia 搜索配置。 + +- index: `string` Algolia 索引。 +- appID: `string` Algolia App ID。 +- searchKey: `string` Algolia Search Key。 + +fuse +: {{< version 0.2.17 >}}\ +`map` [Fuse 搜索配置][fusejs-options]。 + +- isCaseSensitive: `bool` 是否区分大小写，默认：`false`。 +- minMatchCharLength: `int` 最小匹配字符长度，默认：`2`。 +- findAllMatches: `bool` 是否查找所有匹配项，默认：`false`。 +- location: `int` 位置，默认：`0`。 +- threshold: `float` 阈值，默认：`0.3`。 +- distance: `int` 距离，默认：`100`。 +- ignoreLocation: `bool` 是否忽略位置，默认：`false`。 +- useExtendedSearch: `bool` 是否使用扩展搜索，默认：`false`。 +- ignoreFieldNorm: `bool` 是否忽略字段规范化，默认：`false`。 + +--- + +基于 [algolia][algolia] 或 [Fuse.js][fusejs]，**FixIt** 主题支持搜索功能。 - # 页面头部导航栏配置 +为了生成搜索功能所需要的 `index.json`, 请在你的站点配置中添加 `JSON` 输出文件类型到 `outputs` 部分的 `home` 字段中。 + +```toml +[outputs] + home = ["HTML", "RSS", "JSON"] +``` + +{{< link href="/zh-cn/guides/algolia-atomic/" content="关于 algolia 的使用技巧" card=true >}} + +### header + +`map` 页面头部导航栏配置。 + +```toml +[params] [params.header] - # {{< version 0.2.13 changed >}} 桌面端导航栏模式 ["sticky", "normal", "auto"] desktopMode = "sticky" - # {{< version 0.2.13 changed >}} 移动端导航栏模式 ["sticky", "normal", "auto"] mobileMode = "auto" - # {{< version 0.2.0 >}} 页面头部导航栏标题配置 [params.header.title] - # LOGO 的 URL - logo = "/images/fixit.min.svg" - # 标题名称 - name = "我的 Hugo FixIt 网站" - # 你可以在名称（允许 HTML 格式）之前添加其他信息，例如图标 + logo = "" + name = "" pre = "" - # 你可以在名称（允许 HTML 格式）之后添加其他信息，例如图标 post = "" - # {{< version 0.2.5 >}} 是否为标题显示打字机动画 typeit = false - # {{< version 0.2.12 >}} 页面头部导航栏副标题配置 [params.header.subtitle] - # 副标题名称 name = "" - # 是否为副标题显示打字机动画 typeit = false +``` + +desktopMode +: {{< version 0.2.13 changed >}}\ +`string` 桌面端导航栏模式，可选值：`sticky`、`normal`、`auto`, 默认：`sticky`。 + +mobileMode +: {{< version 0.2.13 changed >}}\ +`string` 移动端导航栏模式，可选值：`sticky`、`normal`、`auto`, 默认：`auto`。 + +title +: `map` 页面头部导航栏标题配置。 + +- logo: `string` LOGO 的 URL。 +- name: `string` 标题名称。 +- pre: `string` 在名称之前添加其他信息。 +- post: `string` 在名称之后添加其他信息。 +- typeit: `bool` 是否为标题显示打字机动画。 + +subtitle +: {{< version 0.2.12 >}}\ +`map` 页面头部导航栏副标题配置。 + +- name: `string` 副标题名称。 +- typeit: `bool` 是否为副标题显示打字机动画。 + +### breadcrumb + +{{< version 0.2.18 >}} + +`map` 面包屑导航配置。 + +enable +: `bool` 是否启用面包屑导航。 + +sticky +: `bool` 是否固定面包屑导航。 + +showHome +: `bool` 是否显示主页链接。 + +### footer + +`map` 页面底部信息配置。 + +```toml +[params] + [params.footer] + enable = true + custom = "" + copyright = true + author = true + since = "" + gov = "" + icp = "" + license = "" + [params.footer.powered] + enable = true + hugoLogo = true + themeLogo = true + [params.footer.siteTime] + enable = false + animate = true + icon = "fa-solid fa-heartbeat" + pre = "" + value = "" + [params.footer.order] + powered = 0 + copyright = 0 + statistics = 0 + visitor = 0 + beian = 0 +``` + +enable +: `bool` 是否启用页面底部信息。 + +custom +: {{< version 0.2.17 changed >}}\ +`string` 自定义内容（支持 HTML 格式）。 + +copyright +: `bool` 是否显示版权信息。 + +author +: `bool` 是否显示作者。 + +since +: `int` 网站创立年份。 + +gov +: {{< version 0.2.12 >}}\ +`string` 公网安备信息，仅在中国使用（支持 HTML 格式）。 + +icp +: {{< version 0.2.12 changed >}}\ +`string` ICP 备案信息，仅在中国使用（支持 HTML 格式）。 + +license +: `string` 许可协议信息（支持 HTML 格式）。 + +powered +: `map` Hugo 和主题信息。 + +- enable: `bool` 是否显示 Hugo 和主题信息。 +- hugoLogo: `bool` 是否显示 Hugo Logo。 +- themeLogo: `bool` 是否显示主题 Logo。 + +siteTime +: {{< version 0.2.17 >}}\ +`map` 网站创立时间。 + +- enable: `bool` 是否显示网站创立时间。 +- animate: `bool` 是否显示动画。 +- icon: `string` 图标。 +- pre: `string` 前缀。 +- value: `string` 网站创立时间，例如：`2021-12-18T16:15:22+08:00`。 + +order +: {{< version 0.2.17 >}}\ +`map` 页面底部行排序。 + +- powered: `int` Hugo 和主题信息。 +- copyright: `int` 版权信息。 +- statistics: `int` 统计信息。 +- visitor: `int` 访客信息。 +- beian: `int` 备案信息。 + +### archives + +{{< version 0.3.0 >}} + +`map` 归档页面配置。 + +```toml +[params] + [params.archives] + paginate = 20 + dateFormat = "01-02" +``` + +paginate +: `int` 归档页面每页显示文章数量，默认：`20`。 + +dateFormat +: `string` 日期格式，默认：`01-02`。 + +### section + +`map` Section（所有文章）页面配置。 + +```toml +[params] + [params.section] + paginate = 20 + dateFormat = "01-02" + rss = 10 + [params.section.recentlyUpdated] + enable = false + rss = false + days = 30 + maxCount = 10 +``` + +paginate +: `int` section 页面每页显示文章数量，默认：`20`。 + +dateFormat +: `string` 日期格式，默认：`01-02`。 + +rss +: `int` RSS 文章数目，默认：`10`。 + +recentlyUpdated +: {{< version 0.2.13 >}}\ +`map` 最近更新文章设置。 + +- enable: `bool` 是否启用最近更新文章，默认：`false`。 +- rss: `bool` 是否在 RSS 中显示最近更新文章，默认：`false`。 +- days: `int` 最近更新文章的天数，默认：`30`。 +- maxCount: `int` 最大文章数目，默认：`10`。 + +### list + +`map` List（目录或标签）页面配置。 + +```toml +[params] + [params.list] + paginate = 20 + dateFormat = "01-02" + rss = 10 +``` + +paginate +: `int` list 页面每页显示文章数量，默认：`20`。 + +dateFormat +: `string` 日期格式，默认：`01-02`。 + +rss +: `int` RSS 文章数目，默认：`10`。 + +### tagcloud + +{{< version 0.2.17 >}} + +`map` 标签云配置。 + +```toml +[params] + [params.tagcloud] + enable = false + min = 14 + max = 32 + peakCount = 10 + orderby = "name" +``` + +enable +: `bool` 是否启用标签云，默认：`false`。 + +min +: `int` 最小字体大小，单位：px，默认：`14`。 + +max +: `int` 最大字体大小，单位：px，默认：`32`。 + +peakCount +: `int` 每个标签的最大文章数，默认：`10`。 + +orderby +: `string` 标签排序方式，可选值：`name`、`count`，默认：`name`。 + +### home + +`map` 主页配置。 + +```toml +[params] + [params.home] + paginate = 10 + [params.home.profile] + enable = false + gravatarEmail = "" + avatarURL = "" + avatarMenu = "" + title = "" + subtitle = "" + typeit = true + social = true + disclaimer = "" + [params.home.posts] + enable = true + paginate = 6 +``` + +rss +: `int` RSS 文章数目，默认：`10`。 + +profile +: `map` 主页个人信息配置。 + +- enable: `bool` 是否显示个人信息，默认：`false`。 +- gravatarEmail: `string`Gravatar 邮箱，用于优先在主页显示的头像。 +- avatarURL: `string` 主页显示头像的 URL。{{< version 0.2.17 >}} +- avatarMenu: `string` 头像菜单链接的 identifier。 +- title: `string` 主页显示的网站标题（支持 HTML 格式）。 +- subtitle: `string` 主页显示的网站副标题。 +- typeit: `bool` 是否为副标题显示打字机动画，默认：`true`。 +- social: `bool` 是否显示社交账号，默认：`true`。 +- disclaimer: `string` 免责声明（支持 HTML 格式）。 + +posts +: `map` 主页文章列表配置。 + +- enable: `bool` 是否显示文章列表，默认：`true`。 +- paginate: `int` 主页每页显示文章数量，默认：`6`。 + +### social + +`map` 作者的社交信息设置。 + +你可以参考位于 `themes/FixIt/assets/data/social.yaml` 的默认数据来配置你的社交链接。 + +你可以直接配置你的社交 ID 来生成一个默认社交链接和图标： + +```toml +[params.social] + Mastodon = "@xxxx" +``` + +生成的社交链接是 `https://mastodon.technology/@xxxx`。 + +或者你可以通过一个字典来设置更多的选项： + +```toml +[params.social] + [params.social.Mastodon] + # 排列图标时的权重（权重越大，图标的位置越靠后） + weight = 0 + # 你的社交 ID + id = "@xxxx" + # 你的社交链接的前缀 + prefix = "https://mastodon.social/" + # 当鼠标停留在图标上时的提示内容 + title = "Mastodon" +``` + +所有支持的社交链接的默认数据位于 `themes/FixIt/assets/data/social.yaml`。 +你可以参考它来配置你的社交链接。 + +### typeit + +`map` 打字机动画配置。 + +```toml +[params] + [params.typeit] + speed = 100 + cursorSpeed = 1000 + cursorChar = "|" + duration = -1 + loop = false +``` + +speed +: `int` 打字速度，默认：`100`。 + +cursorSpeed +: `int` 光标速度，默认：`1000`。 + +cursorChar +: `string` 光标字符，默认：`|`。 + +duration +: `int` 动画持续时间，默认：`-1`。 + +loop +: {{< version 0.2.18 >}}\ +`bool` 是否循环播放，默认：`false`。 + +### mermaid + +{{< version 0.2.15 >}} + +`map` Mermaid 配置。 + +```toml +[params] + [params.mermaid] + themes = ["default", "dark"] +``` + +themes +`string array(2)` Mermaid 主题，详见 [Mermaid Themes][mermaid-themes]。 + +### pangu + +{{< version 0.2.12 >}} + +`map` PanguJS 配置。 + +```toml +[params] + [params.pangu] + enable = false + selector = "article" +``` + +enable +: `bool` 是否启用 PanguJS，默认：`false`。 + +selector +: {{< version 0.2.17 >}}\ +`string` 选择器，默认：`article`。 + +### watermark + +{{< version 0.2.13 changed >}} + +`map` 水印配置，详见 [Watermark][watermark] 文档。 + +```toml +[params] + [params.watermark] + enable = false + content = "" + opacity = 0.1 + width = 150 + height = 20 + rowSpacing = 60 + colSpacing = 30 + rotate = 15 + fontSize = 0.85 + fontFamily = "inherit" +``` + +### ibruce + +{{< version 0.2.12 >}} + +`map` 不蒜子计数器配置。 + +```toml +[params] + [params.ibruce] + enable = false + enablePost = false +``` + +enable +: `bool` 是否启用不蒜子计数器，默认：`false`。 + +enablePost +: `bool` 是否在文章中启用不蒜子计数器，默认：`false`。 + +### verification + +`map` 网站验证代码，用于 Google/Bing/Yandex/Pinterest/Baidu/360/Sogou。 + +```toml +[params] + [params.verification] + google = "" + bing = "" + yandex = "" + pinterest = "" + baidu = "" + so = "" + sogou = "" +``` + +### seo + +`map` SEO 配置。 + +```toml +[params] + [params.seo] + image = "" + thumbnailUrl = "" +``` + +image +: `string` 网站默认图片。 + +thumbnailUrl +: `string` 网站缩略图 URL。 + +### analytics + +`map` 网站分析配置。 + +```toml +[params] + [params.analytics] + enable = false + [params.analytics.google] + id = "" + anonymizeIP = true + [params.analytics.fathom] + id = "" + server = "" +``` + +enable +: `bool` 是否启用网站分析，默认：`false`。 + +google +: `map` Google Analytics 配置。 + +- id: `string` Google Analytics ID。 +- anonymizeIP: `bool` 是否匿名化 IP，默认：`true`。 + +fathom +: `map` Fathom Analytics 配置。 + +- id: `string` Fathom Analytics ID。 +- server: `string` Fathom Analytics 服务器地址。 + +### cookieconsent + +`map` Cookie 许可配置。 + +```toml +[params] + [params.cookieconsent] + enable = true + [params.cookieconsent.content] + message = "" + dismiss = "" + link = "" +``` + +enable +: `bool` 是否启用 Cookie Consent，默认：`true`。 + +content +: `map` 用于 Cookie 许可横幅的文本字符串。 + +- message: `string` Cookie 许可横幅的消息。 +- dismiss: `string` Cookie 许可横幅的关闭按钮文本。 +- link: `string` Cookie 许可横幅的链接文本。 + +### cdn + +`map` CDN 配置。 + +```toml +[params.cdn] + data = "" +``` + +data +: `string` CDN 数据文件名称，默认不启用。位于 `themes/FixIt/assets/data/cdn/` 目录，你可以在你的项目下相同路径存放你自己的数据文件：`assets/data/cdn/`。可选值：`jsdelivr.yml`、`unpkg.yml` 等。 + +### compatibility + +`map` 兼容性设置。 + +```toml +[params] + [params.compatibility] + polyfill = false + objectFit = false +``` + +polyfill +: `bool` 是否使用 Polyfill.io 来兼容旧式浏览器，默认：`false`。 + +objectFit +: `bool` 是否使用 object-fit-images 来兼容旧式浏览器，默认：`false`。 + +### githubCorner + +{{< version 0.2.14 >}} + +`map` 在左上角或者右上角显示 GitHub 开源链接。 + +```toml +[params] + [params.githubCorner] + enable = false + permalink = "" + title = "View source on GitHub" + position = "right" +``` + +enable +: `bool` 是否启用 GitHub 横幅。默认为 `false`。 + +permalink +: `string` GitHub 仓库的 URL。例如：`https://github.com/hugo-fixit/FixIt` + +title +: `string` GitHub 横幅的标题。 + +position +: `string` GitHub 横幅的位置。`left` 或 `right`。默认为 `right`。 + +### gravatar + +{{< version 0.2.18 changed >}} + +`map` Gravatar 配置。 + +```toml +[params] + [params.gravatar] + enable = false + host = "www.gravatar.com" + style = "" +``` + +enable +: `bool` 是否启用 Gravatar，默认：`false`。 + +host +: `string` Gravatar 主机，例如：`www.gravatar.com`、`cn.gravatar.com` 等，默认：`www.gravatar.com`。 + +style +: `string` Gravatar 样式，例如：`mp`、`identicon`、`monsterid`、`wavatar`、`retro`、`robohash`、`blank` 等，默认：`""`。 + +### backToTop + +{{< version 0.2.16 >}} + +`map` 返回顶部按钮配置。 + +```toml +[params] + [params.backToTop] + enable = true + scrollpercent = false +``` + +enable +: `bool` 是否启用返回顶部按钮，默认：`true`。 + +scrollpercent +: `bool` 是否显示滚动百分比，默认：`false`。 + +### readingProgress + +{{< version 0.2.16 >}} + +`map` 阅读进度条配置。 + +```toml +[params] + [params.readingProgress] + enable = false + start = "left" + position = "top" + reversed = false + light = "" + dark = "" + height = "2px" +``` + +enable +: `bool` 是否启用阅读进度条，默认：`false`。 + +start +: `string` 阅读进度条开始位置，可选值：`left`、`right`，默认：`left`。 + +position +: `string` 阅读进度条位置，可选值：`top`、`bottom`，默认：`top`。 + +reversed +: `bool` 是否反转阅读进度条，默认：`false`。 + +light +: `string` 浅色主题颜色，默认：`""`。 + +dark +: `string` 深色主题颜色，默认：`""`。 + +height +: `string` 阅读进度条高度，默认：`2px`。 + +### pace + +{{< version 0.2.17 >}} + +`map` 页面加载期间顶部的进度条，详见 [Pace.js][pacejs]。 + +```toml +[params] + [params.pace] + enable = false + color = "blue" + theme = "minimal" +``` + +enable +: `bool` 是否启用 Pace.js，默认：`false`。 + +color +: `string` 进度条颜色，可选值：`black`、`blue`、`green`、`orange`、`pink`、`purple`、`red`、`silver`、`white`、`yellow`，默认：`blue`。 + +theme +: `string` 进度条主题，可选值：`barber-shop`、`big-counter`、`bounce`、`center-atom`、`center-circle`、`center-radar`、`center-simple`、`corner-indicator`、`fill-left`、`flash`、`flat-top`、`loading-bar`、`mac-osx`、`material`、`minimal`，默认：`minimal`。 + +### customFilePath + +{{< version 0.2.17 >}} + +`string` 定义自定义文件路径，并在站点目录 `layouts/partials/custom` 中创建自定义文件。 + +```toml +[params] + [params.customFilePath] + aside = "custom/aside.html" + profile = "custom/profile.html" + footer = "custom/footer.html" +``` + +### dev + +{{< version 0.2.15 >}} + +`map` 开发者选项。 + +```toml +[params] + [params.dev] + enable = false + c4u = false + githubToken = "" + [params.dev.mDevtools] + enable = false + type = "vConsole" +``` - # {{< version 0.2.18 >}} 面包屑导航配置 - [params.breadcrumb] - enable = false - sticky = false - showHome = false +enable +: `bool` 是否启用开发者选项，默认：`false`。 - # 页面底部信息配置 - [params.footer] - enable = true - # {{< version 0.2.17 changed >}} 自定义内容（支持 HTML 格式） - # 进阶使用，见参数 `params.customFilePath.footer` - custom = "" - # {{< version 0.2.0 >}} 是否显示版权信息 - copyright = true - # {{< version 0.2.0 >}} 是否显示作者 - author = true - # 网站创立年份 - since = 2021 - # {{< version 0.2.12 >}} 公网安备信息，仅在中国使用（支持 HTML 格式） - gov = "" - # {{< version 0.2.12 changed >}} ICP 备案信息，仅在中国使用（支持 HTML 格式） - icp = "" - # 许可协议信息（支持 HTML 格式） - license = 'CC BY-NC-SA 4.0' - # {{< version 0.3.o >}} 是否显示 Hugo 和主题信息 - [params.footer.powered] - enable = true - hugoLogo = true - themeLogo = true - # {{< version 0.2.17 changed >}} 网站创立时间 - [params.footer.siteTime] - enable = false - animate = true - icon = "fa-solid fa-heartbeat" - pre = "" - value = "" # e.g. "2021-12-18T16:15:22+08:00" - # {{< version 0.2.17 >}} 页面底部行排序，可选值：["first", 0, 1, 2, 3, 4, 5, "last"] - [params.footer.order] - powered = 0 - copyright = 0 - statistics = 0 - visitor = 0 - beian = 0 +c4u +: `bool` 是否启用检查功能，默认：`false`。 - # {{< version 0.2.0 >}} Section（所有文章）页面配置 - [params.section] - # section 页面每页显示文章数量 - paginate = 20 - # 日期格式（月和日） - dateFormat = "01-02" - # RSS 文章数目 - rss = 10 - # {{< version 0.2.13 >}} 最近更新文章设置 - [params.section.recentlyUpdated] - enable = false - rss = false - days = 30 - maxCount = 10 +githubToken +: `string` GitHub Token。 - # {{< version 0.2.0 >}} List（目录或标签）页面配置 - [params.list] - # list 页面每页显示文章数量 - paginate = 20 - # 日期格式（月和日） - dateFormat = "01-02" - # RSS 文章数目 - rss = 10 +mDevtools +: `map` 移动端开发者工具。 - # {{< version 0.2.17 >}} 标签云配置 - [params.tagcloud] - enable = false - min = 14 # 最小字体大小，单位：px - max = 32 # 最大字体大小，单位：px - peakCount = 10 # 每个标签的最大文章数 - orderby = "name" # 标签排序方式，可选值：["name", "count"] +- enable: `bool` 是否启用移动端开发者工具，默认：`false`。 +- type: `string` 移动端开发者工具类型，可选值：`vConsole`、`eruda`，默认：`vConsole`。 - # 主页配置 - [params.home] - # {{< version 0.2.0 >}} RSS 文章数目 - rss = 10 - # 主页个人信息 - [params.home.profile] - enable = true - # Gravatar 邮箱，用于优先在主页显示的头像 - gravatarEmail = "" - # 主页显示头像的 URL - avatarURL = "/images/avatar.png" - # {{< version 0.2.17 >}} 头像菜单链接的 identifier - avatarMenu = "" - # {{< version 0.2.7 changed >}} 主页显示的网站标题（支持 HTML 格式） - title = "" - # 主页显示的网站副标题 - subtitle = "这是我的 Hugo FixIt 网站" - # 是否为副标题显示打字机动画 - typeit = true - # 是否显示社交账号 - social = true - # {{< version 0.2.0 >}} 免责声明（支持 HTML 格式） - disclaimer = "" - # 主页文章列表 - [params.home.posts] - enable = true - # 主页每页显示文章数量 - paginate = 6 +### page - # {{< version 0.2.16 changed >}} 作者的社交信息设置 - [params.social] - GitHub = "Lruihao" - Linkedin = "" - Twitter = "" - Instagram = "" - Facebook = "" - Telegram = "" - Medium = "" - Gitlab = "" - Youtubelegacy = "" - Youtubecustom = "" - Youtubechannel = "" - Tumblr = "" - Quora = "" - Keybase = "" - Pinterest = "" - Reddit = "" - Codepen = "" - FreeCodeCamp = "" - Bitbucket = "" - Stackoverflow = "" - Weibo = "" - Odnoklassniki = "" - VK = "" - Flickr = "" - Xing = "" - Snapchat = "" - Soundcloud = "" - Spotify = "" - Bandcamp = "" - Paypal = "" - Fivehundredpx = "" - Mix = "" - Goodreads = "" - Lastfm = "" - Foursquare = "" - Hackernews = "" - Kickstarter = "" - Patreon = "" - Steam = "" - Twitch = "" - Strava = "" - Skype = "" - Whatsapp = "" - Zhihu = "" - Douban = "" - Angellist = "" - Slidershare = "" - Jsfiddle = "" - Deviantart = "" - Behance = "" - Dribbble = "" - Wordpress = "" - Vine = "" - Googlescholar = "" - Researchgate = "" - Mastodon = "" - Thingiverse = "" - Devto = "" - Gitea = "" - XMPP = "" - Matrix = "" - Bilibili = "" - ORCID = "" - Liberapay = "" - Ko-Fi = "" - BuyMeaCoffee = "" - Linktree = "" - QQ = "" - QQGroup = "awbwdTtSQ_-H5QGzeJxdWgv6JMbNehNM" # https://qun.qq.com/join.html - Diaspora = "" - CSDN = "" - Discord = "" - DiscordInvite = "" - Lichess = "" - Pleroma = "" - Kaggle = "" - MediaWiki= "" - Plume = "" - HackTheBox = "" - RootMe = "" - Feishu = "" - TryHackMe = "" - Phone = "" - Email = "" - RSS = true - - # {{< version 0.2.0 changed >}} 文章页面配置 +`map` 文章页面配置。 + +```toml +[params] [params.page] # {{< version 0.2.18 >}} 是否启用文章作者头像 authorAvatar = true @@ -827,226 +1465,30 @@ menu: name = "" logoUrl = "" - # {{< version 0.2.5 >}} TypeIt 配置 - [params.typeit] - # 每一步的打字速度（单位是毫秒） - speed = 100 - # 光标的闪烁速度（单位是毫秒） - cursorSpeed = 1000 - # 光标的字符（支持 HTML 格式） - cursorChar = "|" - # 打字结束之后光标的持续时间（单位是毫秒，"-1" 代表无限大） - duration = -1 - # {{< version 0.2.18 >}} 打字完成后是否会连续循环 - loop = false - - # {{< version 0.2.15 >}} Mermaid 配置 - [params.mermaid] - # 取值详见 https://mermaid.js.org/config/theming.html#available-themes - themes = ["default", "dark"] - - # {{< version 0.2.12 >}} 盘古之白配置 - [params.pangu] - # 适用于中文写作用户 - enable = false - selector = "article" # {{< version 0.2.17 >}} - - # {{< version 0.2.12 >}} 水印配置 - # 详细参数见 https://github.com/Lruihao/watermark#readme - [params.watermark] - enable = false - # 水印内容（允许 HTML 格式） - content = "" - # 水印透明度 - opacity = 0.1 - # 单水印宽度 单位：px - width = 150 - # 单水印高度 单位：px - height = 20 - # 水印行间距 单位：px - rowSpacing = 60 - # 水印列间距 单位：px - colSpacing = 30 - # 水印旋转角度 单位：deg - rotate = 15 - # 水印字体大小，单位：rem - fontSize = 0.85 - # {{< version 0.2.13 >}} 水印字体 - fontFamily = "inherit" - - # {{< version 0.2.12 >}} 不蒜子统计 - [params.ibruce] - enable = true - # 在文章中开启 - enablePost = false - - # 网站验证代码，用于 Google/Bing/Yandex/Pinterest/Baidu/360/Sogou - [params.verification] - google = "" - bing = "" - yandex = "" - pinterest = "" - baidu = "" - so = "" - sogou = "" - - # {{< version 0.2.10 >}} 网站 SEO 配置 - [params.seo] - # 图片 URL - image = "" - # 缩略图 URL - thumbnailUrl = "" - - # {{< version 0.2.0 >}} 网站分析配置 - [params.analytics] - enable = false - # Google Analytics - [params.analytics.google] - id = "" - # 是否匿名化用户 IP - anonymizeIP = true - # Fathom Analytics - [params.analytics.fathom] - id = "" - # 自行托管追踪器时的主机路径 - server = "" - - # {{< version 0.2.7 >}} Cookie 许可配置 - [params.cookieconsent] - enable = true - # 用于 Cookie 许可横幅的文本字符串 - [params.cookieconsent.content] - message = "" - dismiss = "" - link = "" - - # {{< version 0.2.7 changed >}} 第三方库文件的 CDN 设置 - [params.cdn] - # CDN 数据文件名称，默认不启用 ["jsdelivr.yml", "unpkg.yml", ...] - # 位于 "themes/FixIt/assets/data/cdn/" 目录 - # 可以在你的项目下相同路径存放你自己的数据文件："assets/data/cdn/" - # data = "unpkg.yml" - - # {{< version 0.2.8 >}} 兼容性设置 - [params.compatibility] - # 是否使用 Polyfill.io 来兼容旧式浏览器 - polyfill = false - # 是否使用 object-fit-images 来兼容旧式浏览器 - objectFit = false - - # {{< version 0.2.14 >}} 在左上角或者右上角显示 GitHub 开源链接 - [params.githubCorner] - enable = false - permalink = "https://github.com/hugo-fixit/FixIt" - title = "在 GitHub 上查看源代码" - position = "right" # ["left", "right"] - - # {{< version 0.2.14 >}} Gravatar 设置 - [params.gravatar] - # {{< version 0.2.18 >}} 取决于作者邮箱，作者邮箱未设置则使用本地头像 - enable = false - # Gravatar 主机，默认：“www.gravatar.com” - host = "www.gravatar.com" # ["cn.gravatar.com", "gravatar.loli.net", ...] - style = "" # ["", "mp", "identicon", "monsterid", "wavatar", "retro", "blank", "robohash"] - - # {{< version 0.2.16 >}} 返回顶部 - [params.backToTop] - enable = true - # 在 b2t 按钮中显示滚动百分比 - scrollpercent = false - - # {{< version 0.2.16 >}} 阅读进度条 - [params.readingProgress] - enable = false - # 可用值：["left", "right"] - start = "left" - # 可用值：["top", "bottom"] - position = "top" - reversed = false - light = "" - dark = "" - height = "2px" +``` - # {{< version 0.2.17 >}} 页面加载期间顶部的进度条 - # 有关详细信息：https://github.com/CodeByZach/pace - [params.pace] - enable = false - # 所有可用颜色： - # ["black", "blue", "green", "orange", "pink", "purple", "red", "silver", "white", "yellow"] - color = "blue" - # 所有可用主题： - # ["barber-shop", "big-counter", "bounce", "center-atom", "center-circle", "center-radar", "center-simple", - # "corner-indicator", "fill-left", "flash", "flat-top", "loading-bar", "mac-osx", "material", "minimal"] - theme = "minimal" +## 解析配置 {#markup-configuration} - # {{< version 0.2.17 >}} 定义自定义文件路径 - # 在站点目录 `layouts/partials/custom` 中创建你的自定义文件，并取消注释下面需要的文件 - [params.customFilePath] - # aside = "custom/aside.html" - # profile = "custom/profile.html" - # footer = "custom/footer.html" +通过根配置键 `markup` 配置将标记语言转为 HTML。 - # {{< version 0.2.15 >}} 开发者选项 - [params.dev] - enable = false - # 检查更新 - c4u = false - # 请勿公开展示！ - githubToken = "" - # 移动端开发者工具配置 - [params.dev.mDevtools] - enable = false - # 支持 "vConsole", "eruda" - type = "vConsole" +本节仅记录**FixIt**主题的一些 [必要配置][necessary-configuration-for-theme]。有关更多详细信息，请参阅 [Configure markup][configuration-markup] 页面。 -# Hugo 解析文档的配置 +```toml [markup] - # {{< link "https://gohugo.io/content-management/syntax-highlighting" "语法高亮设置" >}} (https://gohugo.io/content-management/syntax-highlighting) [markup.highlight] - ################## 必要的配置 ################## - # {{< link "https://github.com/hugo-fixit/FixIt/issues/43" >}} codeFences = true lineNos = true lineNumbersInTable = true noClasses = false - ################## 必要的配置 ################## - guessSyntax = true - # Goldmark 是 Hugo 0.60 以来的默认 Markdown 解析库 - [markup.goldmark] - [markup.goldmark.extensions] - definitionList = true - footnote = true - linkify = true - strikethrough = true - table = true - taskList = true - typographer = true - [markup.goldmark.renderer] - # 是否在文档中直接使用 HTML 标签 - unsafe = true - # 目录设置 - [markup.tableOfContents] - startLevel = 2 - endLevel = 6 - -# 网站地图配置 -[sitemap] - changefreq = "weekly" - filename = "sitemap.xml" - priority = 0.5 - -# {{< link "https://gohugo.io/content-management/urls#permalinks" "Permalinks 配置" >}} (https://gohugo.io/content-management/urls#permalinks) -[Permalinks] - # posts = ":year/:month/:filename" - posts = ":filename" - -# {{< link "https://gohugo.io/about/hugo-and-gdpr/" "隐私信息配置" >}} (https://gohugo.io/about/hugo-and-gdpr/) -[privacy] - [privacy.twitter] - enableDNT = true - [privacy.youtube] - privacyEnhanced = true +``` + +## Custom output formats + +Hugo 可以输出多种格式的内容，**FixIt** 主题利用了这个功能。为了完全配置主题，请将以下选项配置到 `hugo.toml` 中。 + +有关输出格式配置的更多详细信息，请参阅 [自定义输出格式][hugo-output-formats] 页面。 +```toml # {{< version 0.2.15 changed >}} [mediaTypes] # 用于输出 Markdown 格式文档的设置 @@ -1105,237 +1547,33 @@ menu: term = ["HTML", "RSS"] ``` -![完整配置下的预览](full-configuration-preview.zh-cn.png "完整配置下的预览") - -#### CDN 配置 - -```toml -[params.cdn] - # CDN 数据文件名称，默认不启用 ["jsdelivr.yml", "unpkg.yml", ...] - data = "" -``` - -默认的 CDN 数据文件位于 `themes/FixIt/assets/data/cdn/` 目录。 -可以在你的项目下相同路径存放你自己的数据文件：`assets/data/cdn/`。 - -#### 社交链接配置 - -你可以直接配置你的社交 ID 来生成一个默认社交链接和图标： - -```toml -[params.social] - Mastodon = "@xxxx" -``` - -生成的社交链接是 `https://mastodon.technology/@xxxx`。 - -或者你可以通过一个字典来设置更多的选项： - -```toml -[params.social] - [params.social.Mastodon] - # 排列图标时的权重（权重越大，图标的位置越靠后） - weight = 0 - # 你的社交 ID - id = "@xxxx" - # 你的社交链接的前缀 - prefix = "https://mastodon.social/" - # 当鼠标停留在图标上时的提示内容 - title = "Mastodon" -``` - -所有支持的社交链接的默认数据位于 `themes/FixIt/assets/data/social.yaml`。 -你可以参考它来配置你的社交链接。 - -#### 搜索配置 - -基于 [algolia][algolia] 或 [Fuse.js][fusejs]，**FixIt** 主题支持搜索功能，详见 [主题配置](#theme-configuration) 的 `params.search` 配置。 - -为了生成搜索功能所需要的 `index.json`, 请在你的站点配置中添加 `JSON` 输出文件类型到 `outputs` 部分的 `home` 字段中。 - -```toml -[outputs] - home = ["HTML", "RSS", "JSON"] -``` - -{{< link href="/zh-cn/guides/algolia-atomic/" content="关于 algolia 的使用技巧" card=true >}} - -### 网站图标，浏览器配置，网站清单 - -强烈建议你把： - -- apple-touch-icon.png (180x180) -- favicon-32x32.png (32x32) -- favicon-16x16.png (16x16) -- mstile-150x150.png (150x150) -- android-chrome-192x192.png (192x192) -- android-chrome-512x512.png (512x512) - -放在 `/static` 目录。利用 [https://realfavicongenerator.net/](https://realfavicongenerator.net/) 可以很容易地生成这些文件。 - -可以自定义 `browserconfig.xml` 和 `site.webmanifest` 文件来设置 `theme-color` 和 `background-color`。 - -### 多语言和 i18n - -**FixIt** 主题完全兼容 Hugo 的多语言模式，并且支持在网页上切换语言。 - -![语言切换](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` 需要分为三个文件： +## Favicon 生成 -- 英语：`my-page.en.md` -- 中文：`my-page.zh-cn.md` -- 法语：`my-page.fr.md` +强烈建议你把你自己的网站图标，`browserconfig.xml` 和 `site.webmanifest` 文件放在 `/static` 目录。 -{{< admonition tip >}} -也可以使用 [文章前置参数](https://gohugo.io/content-management/multilingual#translate-your-content) 来翻译网址。 -{{< /admonition >}} - -#### 修改默认的翻译字符串 +- android-chrome-192x192.png +- android-chrome-512x512.png +- apple-touch-icon.png +- browserconfig.xml +- favicon-32x32.png +- favicon-16x16.png +- favicon.ico +- mstile-150x150.png +- safari-pinned-tab.svg -翻译字符串用于在主题中使用的常见默认值。 -目前提供 [一些语言](#language-compatibility) 的翻译，但你可能自定义其他语言或覆盖默认值。 +利用 可以很容易地生成这些文件。 -要覆盖默认值，请在你项目的 i18n 目录 `i18n/.toml` 中创建一个新文件，并从 `themes/FixIt/i18n/en.toml` 中获得提示。 - -另外，由于你的翻译可能会帮助到其他人，请花点时间通过 [创建一个 PR :(fa-solid fa-code-branch fa-fw):][pulls] 来贡献主题翻译，谢谢！ +![完整配置下的预览](full-configuration-preview.zh-cn.png "完整配置下的预览") -[fixit]: https://github.com/hugo-fixit/FixIt -[releases]: https://github.com/hugo-fixit/FixIt/releases -[git-submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[hugo-modules]: https://gohugo.io/hugo-modules/ -[use-hugo-modules]: https://gohugo.io/hugo-modules/use-modules/ [config]: https://github.com/hugo-fixit/FixIt/blob/master/hugo.toml [menu-system]: https://gohugo.io/content-management/menus/ -[hugo-config]: https://gohugo.io/overview/configuration/ +[hugo-config]: https://gohugo.io/getting-started/configuration/ [algolia]: https://www.algolia.com/ [fusejs]: https://fusejs.io/ -[multilingual]: https://gohugo.io/content-management/multilingual -[pulls]: https://github.com/hugo-fixit/FixIt/pulls +[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/