From edb5533782d71f20101ae0d96c6b0a7d6e4b37fc Mon Sep 17 00:00:00 2001 From: Dillon Date: Tue, 10 May 2022 23:48:28 +0800 Subject: [PATCH] chore(docs): refactor config docs Signed-off-by: Dillon --- config.toml | 30 +++---- exampleSite/config.toml | 54 +++++++------ .../theme-documentation-basics/index.en.md | 72 +++++++++-------- .../theme-documentation-basics/index.zh-cn.md | 79 +++++++++---------- 4 files changed, 122 insertions(+), 113 deletions(-) diff --git a/config.toml b/config.toml index 7f09c72d..d70ee829 100644 --- a/config.toml +++ b/config.toml @@ -4,14 +4,16 @@ min = "0.62.0" [params] - # site default theme ("auto", "light", "dark") - # 网站默认主题 ("auto", "light", "dark") + # site default theme ["auto", "light", "dark"] + # 网站默认主题 ["auto", "light", "dark"] defaultTheme = "auto" # public git repo url only then enableGitInfo is true # 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效 gitRepo = "" - # which hash function used for SRI, when empty, no SRI is used ("sha256", "sha384", "sha512", "md5") - # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI ("sha256", "sha384", "sha512", "md5") + # which hash function used for SRI, when empty, no SRI is used + # ["sha256", "sha384", "sha512", "md5"] + # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI + # ["sha256", "sha384", "sha512", "md5"] fingerprint = "" # date format # 日期格式 @@ -29,11 +31,11 @@ # Header config # 页面头部导航栏配置 [params.header] - # desktop header mode ("fixed", "normal", "auto") - # 桌面端导航栏模式 ("fixed", "normal", "auto") + # desktop header mode ["fixed", "normal", "auto"] + # 桌面端导航栏模式 ["fixed", "normal", "auto"] desktopMode = "fixed" - # mobile header mode ("fixed", "normal", "auto") - # 移动端导航栏模式 ("fixed", "normal", "auto") + # mobile header mode ["fixed", "normal", "auto"] + # 移动端导航栏模式 ["fixed", "normal", "auto"] mobileMode = "auto" # Header title config # 页面头部导航栏标题配置 @@ -132,8 +134,8 @@ # 搜索配置 [params.search] enable = false - # type of search engine ("lunr", "algolia") - # 搜索引擎的类型 ("lunr", "algolia") + # type of search engine ["lunr", "algolia"] + # 搜索引擎的类型 ["lunr", "algolia"] type = "lunr" # max index length of the chunked content # 文章内容最长索引长度 @@ -420,12 +422,12 @@ enableQQ = false serverURLs = "" # emoji data file name, default is "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # located in "themes/LoveIt/assets/data/emoji/" directory # you can store your own data files in the same path under your project: # "assets/data/emoji/" # emoji 数据文件名称, 默认是 "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # 位于 "themes/LoveIt/assets/data/emoji/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/emoji/" @@ -555,12 +557,12 @@ # 第三方库文件的 CDN 设置 [params.cdn] # CDN data file name, disabled by default - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # located in "themes/LoveIt/assets/data/cdn/" directory # you can store your own data files in the same path under your project: # "assets/data/cdn/" # CDN 数据文件名称, 默认不启用 - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # 位于 "themes/LoveIt/assets/data/cdn/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/cdn/" diff --git a/exampleSite/config.toml b/exampleSite/config.toml index 98e47dca..b7eeb4c6 100644 --- a/exampleSite/config.toml +++ b/exampleSite/config.toml @@ -1,7 +1,5 @@ baseURL = "https://example.com" -# determines default content language [en, zh-cn, fr, pl, ...] -# 设置默认的语言 [en, zh-cn, fr, pl, ...] -defaultContentLanguage = "en" + # theme # 主题 theme = "LoveIt" @@ -13,20 +11,27 @@ themesDir = "../.." # 网站标题 title = "LoveIt" -# language code [en, zh-CN, fr, pl, ...] -# 网站语言, 仅在这里 CN 大写 [en, zh-CN, fr, pl, ...] +# determines default content language ["en", "zh-cn", "fr", "pl", ...] +# 设置默认的语言 ["en", "zh-cn", "fr", "pl", ...] +defaultContentLanguage = "en" +# language code ["en", "zh-CN", "fr", "pl", ...] +# 网站语言, 仅在这里 CN 大写 ["en", "zh-CN", "fr", "pl", ...] languageCode = "en" -# language name [English, 简体中文, Français, Polski, ...] -# 语言名称 [English, 简体中文, Français, Polski, ...] +# language name ["English", "简体中文", "Français", "Polski", ...] +# 语言名称 ["English", "简体中文", "Français", "Polski", ...] languageName = "English" # whether to include Chinese/Japanese/Korean # 是否包括中日韩文字 hasCJKLanguage = false + # default amount of posts in each pages +# 默认每页列表显示的文章数目 paginate = 12 -# [UA-XXXXXXXX-X] google analytics code +# google analytics code [UA-XXXXXXXX-X] +# 谷歌分析代号 [UA-XXXXXXXX-X] googleAnalytics = "" # copyright description used only for seo schema +# 版权描述，仅仅用于 SEO copyright = "" # whether to use robots.txt @@ -81,14 +86,16 @@ enableEmoji = true title = "" [params] - # site default theme ("auto", "light", "dark") - # 网站默认主题 ("auto", "light", "dark") + # site default theme ["auto", "light", "dark"] + # 网站默认主题 ["auto", "light", "dark"] defaultTheme = "auto" # public git repo url only then enableGitInfo is true # 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效 gitRepo = "https://github.com/dillonzq/LoveIt" - # which hash function used for SRI, when empty, no SRI is used ("sha256", "sha384", "sha512", "md5") - # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI ("sha256", "sha384", "sha512", "md5") + # which hash function used for SRI, when empty, no SRI is used + # ["sha256", "sha384", "sha512", "md5"] + # 哪种哈希函数用来 SRI, 为空时表示不使用 SRI + # ["sha256", "sha384", "sha512", "md5"] fingerprint = "" # date format # 日期格式 @@ -106,11 +113,11 @@ enableEmoji = true # Header config # 页面头部导航栏配置 [params.header] - # desktop header mode ("fixed", "normal", "auto") - # 桌面端导航栏模式 ("fixed", "normal", "auto") + # desktop header mode ["fixed", "normal", "auto"] + # 桌面端导航栏模式 ["fixed", "normal", "auto"] desktopMode = "fixed" - # mobile header mode ("fixed", "normal", "auto") - # 移动端导航栏模式 ("fixed", "normal", "auto") + # mobile header mode ["fixed", "normal", "auto"] + # 移动端导航栏模式 ["fixed", "normal", "auto"] mobileMode = "auto" # Header title config # 页面头部导航栏标题配置 @@ -209,8 +216,8 @@ enableEmoji = true # 搜索配置 [params.search] enable = true - # type of search engine ("lunr", "algolia") - # 搜索引擎的类型 ("lunr", "algolia") + # type of search engine ["lunr", "algolia"] + # 搜索引擎的类型 ["lunr", "algolia"] type = "algolia" # max index length of the chunked content # 文章内容最长索引长度 @@ -497,12 +504,12 @@ enableEmoji = true enableQQ = false serverURLs = "https://leancloud.hugoloveit.com" # emoji data file name, default is "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # located in "themes/LoveIt/assets/data/emoji/" directory # you can store your own data files in the same path under your project: # "assets/data/emoji/" # emoji 数据文件名称, 默认是 "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # 位于 "themes/LoveIt/assets/data/emoji/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/emoji/" @@ -632,12 +639,12 @@ enableEmoji = true # 第三方库文件的 CDN 设置 [params.cdn] # CDN data file name, disabled by default - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # located in "themes/LoveIt/assets/data/cdn/" directory # you can store your own data files in the same path under your project: # "assets/data/cdn/" # CDN 数据文件名称, 默认不启用 - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # 位于 "themes/LoveIt/assets/data/cdn/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/cdn/" @@ -734,6 +741,8 @@ enableEmoji = true taxonomy = ["HTML", "RSS"] taxonomyTerm = ["HTML"] +# Multilingual +# 多语言 [languages] [languages.en] weight = 1 @@ -815,7 +824,6 @@ enableEmoji = true typeit = true social = true disclaimer = "" - # Social config in home page [languages.en.params.social] GitHub = "xxxx" Twitter = "xxxx" diff --git a/exampleSite/content/posts/theme-documentation-basics/index.en.md b/exampleSite/content/posts/theme-documentation-basics/index.en.md index a947060c..0028f8d7 100644 --- a/exampleSite/content/posts/theme-documentation-basics/index.en.md +++ b/exampleSite/content/posts/theme-documentation-basics/index.en.md @@ -77,17 +77,28 @@ The following is a basic configuration for the LoveIt theme: ```toml baseURL = "http://example.org/" -# [en, zh-cn, fr, ...] determines default content language -defaultContentLanguage = "en" -# language code -languageCode = "en" -title = "My New Hugo Site" # Change the default theme to be use when building the site with Hugo theme = "LoveIt" +# website title +title = "My New Hugo Site" + +# language code ["en", "zh-CN", "fr", "pl", ...] +languageCode = "en" +# language name ["English", "简体中文", "Français", "Polski", ...] +languageName = "English" + +# Author config +[author] + name = "xxxx" + email = "" + link = "" + +# Menu config [menu] [[menu.main]] + weight = 1 identifier = "posts" # you can add extra information before the name (HTML format is supported), such as icons pre = "" @@ -97,23 +108,22 @@ theme = "LoveIt" url = "/posts/" # title will be shown when you hover on this menu link title = "" - weight = 1 [[menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "Tags" url = "/tags/" title = "" - weight = 2 [[menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "Categories" url = "/categories/" title = "" - weight = 3 # Markup related configuration in Hugo [markup] @@ -191,12 +201,12 @@ Please open the code block below to view the complete sample configuration :(far ```toml [params] - # site default theme ("light", "dark", "auto") + # site default theme ["auto", "light", "dark"] defaultTheme = "auto" # public git repo url only then enableGitInfo is true gitRepo = "" # {{< version 0.1.1 >}} which hash function used for SRI, when empty, no SRI is used - # ("sha256", "sha384", "sha512", "md5") + # ["sha256", "sha384", "sha512", "md5"] fingerprint = "" # {{< version 0.2.0 >}} date format dateFormat = "2006-01-02" @@ -209,9 +219,9 @@ Please open the code block below to view the complete sample configuration :(far # Header config [params.header] - # desktop header mode ("fixed", "normal", "auto") + # desktop header mode ["fixed", "normal", "auto"] desktopMode = "fixed" - # mobile header mode ("fixed", "normal", "auto") + # mobile header mode ["fixed", "normal", "auto"] mobileMode = "auto" # {{< version 0.2.0 >}} Header title config [params.header.title] @@ -280,7 +290,7 @@ Please open the code block below to view the complete sample configuration :(far # {{< version 0.2.0 >}} Search config [params.search] enable = true - # type of search engine ("lunr", "algolia") + # type of search engine ["lunr", "algolia"] type = "lunr" # max index length of the chunked content contentLength = 4000 @@ -518,7 +528,7 @@ Please open the code block below to view the complete sample configuration :(far enableQQ = false serverURLs = "" # {{< version 0.2.6 >}} emoji data file name, default is "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # located in "themes/LoveIt/assets/data/emoji/" directory # you can store your own data files in the same path under your project: # "assets/data/emoji/" @@ -625,7 +635,7 @@ Please open the code block below to view the complete sample configuration :(far # {{< version 0.2.7 changed >}} CDN config for third-party library files [params.cdn] # CDN data file name, disabled by default - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # located in "themes/LoveIt/assets/data/cdn/" directory # you can store your own data files in the same path under your project: # "assets/data/cdn/" @@ -667,12 +677,6 @@ Please open the code block below to view the complete sample configuration :(far startLevel = 2 endLevel = 6 -# Author config -[author] - name = "xxxx" - email = "" - link = "" - # Sitemap config [sitemap] changefreq = "weekly" @@ -734,7 +738,7 @@ You could enable these features with `hugo serve -e production`. ```toml [params.cdn] # CDN data file name, disabled by default - # ("jsdelivr.yml") + # ["jsdelivr.yml"] data = "" ```` @@ -847,7 +851,7 @@ After learning [how Hugo handle multilingual websites](https://gohugo.io/content For example with English, Chinese and French website: ```toml -# [en, zh-cn, fr, pl, ...] determines default content language +# determines default content language ["en", "zh-cn", "fr", "pl", ...] defaultContentLanguage = "en" [languages] @@ -857,62 +861,60 @@ defaultContentLanguage = "en" languageCode = "en" languageName = "English" [[languages.en.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "Posts" url = "/posts/" title = "" - weight = 1 [[languages.en.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "Tags" url = "/tags/" title = "" - weight = 2 [[languages.en.menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "Categories" url = "/categories/" title = "" - weight = 3 [languages.zh-cn] weight = 2 title = "我的全新 Hugo 网站" - # language code, CN only here languageCode = "zh-CN" languageName = "简体中文" - # whether to include Chinese/Japanese/Korean hasCJKLanguage = true [[languages.zh-cn.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "文章" url = "/posts/" title = "" - weight = 1 [[languages.zh-cn.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "标签" url = "/tags/" title = "" - weight = 2 [[languages.zh-cn.menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "分类" url = "/categories/" title = "" - weight = 3 [languages.fr] weight = 3 @@ -920,29 +922,29 @@ defaultContentLanguage = "en" languageCode = "fr" languageName = "Français" [[languages.fr.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "Postes" url = "/posts/" title = "" - weight = 1 [[languages.fr.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "Balises" url = "/tags/" title = "" - weight = 2 [[languages.fr.menu.main]] + weight = 3 identifier = "categories" name = "Catégories" pre = "" post = "" url = "/categories/" title = "" - weight = 3 ``` Then, for each new page, append the language code to the file name. @@ -993,7 +995,7 @@ Here is the search configuration in your [site configuration](#site-configuratio ```toml [params.search] enable = true - # type of search engine ("lunr", "algolia") + # type of search engine ["lunr", "algolia"] type = "lunr" # max index length of the chunked content contentLength = 4000 diff --git a/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md b/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md index 57675719..c694a0b7 100644 --- a/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md +++ b/exampleSite/content/posts/theme-documentation-basics/index.zh-cn.md @@ -77,24 +77,30 @@ git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt ```toml baseURL = "http://example.org/" -# [en, zh-cn, fr, ...] 设置默认的语言 -defaultContentLanguage = "zh-cn" -# 网站语言, 仅在这里 CN 大写 -languageCode = "zh-CN" -# 是否包括中日韩文字 -hasCJKLanguage = true -# 网站标题 -title = "我的全新 Hugo 网站" # 更改使用 Hugo 构建网站时使用的默认主题 theme = "LoveIt" -[params] - # LoveIt 主题版本 - version = "0.2.X" +# 网站标题 +title = "我的全新 Hugo 网站" +# 网站语言, 仅在这里 CN 大写 ["en", "zh-CN", "fr", "pl", ...] +languageCode = "zh-CN" +# 语言名称 ["English", "简体中文", "Français", "Polski", ...] +languageName = "简体中文" +# 是否包括中日韩文字 +hasCJKLanguage = true + +# 作者配置 +[author] + name = "xxxx" + email = "" + link = "" + +# 菜单配置 [menu] [[menu.main]] + weight = 1 identifier = "posts" # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标 pre = "" @@ -104,23 +110,22 @@ theme = "LoveIt" url = "/posts/" # 当你将鼠标悬停在此菜单链接上时, 将显示的标题 title = "" - weight = 1 [[menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "标签" url = "/tags/" title = "" - weight = 2 [[menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "分类" url = "/categories/" title = "" - weight = 3 # Hugo 解析文档的配置 [markup] @@ -198,12 +203,12 @@ hugo ```toml [params] - # 网站默认主题样式 ("light", "dark", "auto") + # 网站默认主题样式 ["auto", "light", "dark"] defaultTheme = "auto" # 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效 gitRepo = "" # {{< version 0.1.1 >}} 哪种哈希函数用来 SRI, 为空时表示不使用 SRI - # ("sha256", "sha384", "sha512", "md5") + # ["sha256", "sha384", "sha512", "md5"] fingerprint = "" # {{< version 0.2.0 >}} 日期格式 dateFormat = "2006-01-02" @@ -216,9 +221,9 @@ hugo # 页面头部导航栏配置 [params.header] - # 桌面端导航栏模式 ("fixed", "normal", "auto") + # 桌面端导航栏模式 ["fixed", "normal", "auto"] desktopMode = "fixed" - # 移动端导航栏模式 ("fixed", "normal", "auto") + # 移动端导航栏模式 ["fixed", "normal", "auto"] mobileMode = "auto" # {{< version 0.2.0 >}} 页面头部导航栏标题配置 [params.header.title] @@ -287,7 +292,7 @@ hugo # {{< version 0.2.0 >}} 搜索配置 [params.search] enable = true - # 搜索引擎的类型 ("lunr", "algolia") + # 搜索引擎的类型 ["lunr", "algolia"] type = "lunr" # 文章内容最长索引长度 contentLength = 4000 @@ -525,7 +530,7 @@ hugo enableQQ = false serverURLs = "" # {{< version 0.2.6 >}} emoji 数据文件名称, 默认是 "google.yml" - # ("apple.yml", "google.yml", "facebook.yml", "twitter.yml") + # ["apple.yml", "google.yml", "facebook.yml", "twitter.yml"] # 位于 "themes/LoveIt/assets/data/emoji/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/emoji/" @@ -632,7 +637,7 @@ hugo # {{< version 0.2.7 changed >}} 第三方库文件的 CDN 设置 [params.cdn] # CDN 数据文件名称, 默认不启用 - # ("jsdelivr.yml") + # ["jsdelivr.yml"] # 位于 "themes/LoveIt/assets/data/cdn/" 目录 # 可以在你的项目下相同路径存放你自己的数据文件: # "assets/data/cdn/" @@ -674,12 +679,6 @@ hugo startLevel = 2 endLevel = 6 -# 作者配置 -[author] - name = "xxxx" - email = "" - link = "" - # 网站地图配置 [sitemap] changefreq = "weekly" @@ -742,7 +741,7 @@ hugo ```toml [params.cdn] # CDN 数据文件名称, 默认不启用 - # ("jsdelivr.yml") + # ["jsdelivr.yml"] data = "" ```` @@ -854,7 +853,7 @@ $code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, monospac 例如, 一个支持英语, 中文和法语的网站配置: ```toml -# [en, zh-cn, fr, pl, ...] 设置默认的语言 +# 设置默认的语言 ["en", "zh-cn", "fr", "pl", ...] defaultContentLanguage = "zh-cn" [languages] @@ -864,62 +863,60 @@ defaultContentLanguage = "zh-cn" languageCode = "en" languageName = "English" [[languages.en.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "Posts" url = "/posts/" title = "" - weight = 1 [[languages.en.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "Tags" url = "/tags/" title = "" - weight = 2 [[languages.en.menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "Categories" url = "/categories/" title = "" - weight = 3 [languages.zh-cn] weight = 2 title = "我的全新 Hugo 网站" - # 网站语言, 仅在这里 CN 大写 languageCode = "zh-CN" languageName = "简体中文" - # 是否包括中日韩文字 hasCJKLanguage = true [[languages.zh-cn.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "文章" url = "/posts/" title = "" - weight = 1 [[languages.zh-cn.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "标签" url = "/tags/" title = "" - weight = 2 [[languages.zh-cn.menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "分类" url = "/categories/" title = "" - weight = 3 [languages.fr] weight = 3 @@ -927,29 +924,29 @@ defaultContentLanguage = "zh-cn" languageCode = "fr" languageName = "Français" [[languages.fr.menu.main]] + weight = 1 identifier = "posts" pre = "" post = "" name = "Postes" url = "/posts/" title = "" - weight = 1 [[languages.fr.menu.main]] + weight = 2 identifier = "tags" pre = "" post = "" name = "Balises" url = "/tags/" title = "" - weight = 2 [[languages.fr.menu.main]] + weight = 3 identifier = "categories" pre = "" post = "" name = "Catégories" url = "/categories/" title = "" - weight = 3 ``` 然后, 对于每个新页面, 将语言代码附加到文件名中. @@ -1001,7 +998,7 @@ defaultContentLanguage = "zh-cn" ```toml [params.search] enable = true - # 搜索引擎的类型 ("lunr", "algolia") + # 搜索引擎的类型 ["lunr", "algolia"] type = "lunr" # 文章内容最长索引长度 contentLength = 4000