跳到主要内容
  1. 文档/

基本配置

3 分钟·

Congo 是一个高度可定制的主题,利用一些最新的 Hugo 特性来简化配置过程。

该主题附带了一个默认配置,让你可以快速启动一个基本的博客或静态网站。

主题附带的配置文件采用 TOML 格式,因为这是 Hugo 的默认语法。如果你愿意,可以将配置转换为 YAML 或 JSON。

每个文件中都有默认主题配置的文档,因此你可以自由调整设置以满足你的需求。

正如在安装说明中所述,你应该通过修改 Hugo 项目的 config/_default/ 文件夹中的文件来调整主题配置,并删除项目根目录中的 config.toml 文件。

网站配置 #

Congo主题全面遵循标准 Hugo 配置变量,但是有一些特定的配置项需要进行设置以获得最佳体验。

网站配置通过 config/_default/config.toml 文件管理。下表概述了 Congo 主题所使用的所有设置。

请注意,此表中提供的变量名使用点表示法来简化 TOML 数据结构(即 outputs.home 指的是 [outputs] home)。

名称默认值描述
theme"congo"使用 Hugo 模块方法安装时,应删除此配置值。对于所有其他安装类型,必须将其设置为 congo,以使主题正常运行。
baseURL未设置网站根目录的 URL。
defaultContentLanguage"en"此值确定主题组件和内容的默认语言。有关受支持的语言代码,请参阅下面的语言和国际化部分。
enableRobotsTXTtrue启用时,在站点根目录将创建一个 robots.txt 文件,允许搜索引擎爬取整个站点。如果你更喜欢提供自己制作的 robots.txt,请设置为 false 并将文件放置在 static 目录中。为了完全控制,你可以提供一个自定义布局来生成此文件。
paginate10在文章列表中每页列出的文章数。
summaryLength0front matter中未提供摘要时,用于生成文章摘要的字数。值为 0 将使用第一句。当摘要被隐藏时,此值无效。
outputs.home["HTML", "RSS", "JSON"]生成站点的输出格式。Congo 需要 HTML、RSS 和 JSON 才能使所有主题组件正常工作。
permalinks未设置有关固定链接配置,请参阅Hugo文档
taxonomies未设置有关分类法配置,请参阅组织内容部分。

语言和国际化 #

Congo 针对完整的多语言网站进行了优化,并且主题assets中已经默认翻译成多种语言。语言配置允许您生成多个版本的内容,以为访问者提供在其母语中的定制体验。

该主题目前支持以下语言:

语言代码
🇬🇧 英语(默认)en
🇪🇬 阿拉伯语ar
🇧🇩 孟加拉语bn
🇧🇬 保加利亚语bg
🇨🇳 中文 - 简体(中国)zh-cn
🇹🇼 中文 - 繁体(台湾)zh-tw
🇨🇿 捷克语cs
🇳🇱 荷兰语nl
🇫🇮 芬兰语fi
🇫🇷 法语fr
🇩🇪 德语de
🇮🇱 希伯来语he
🇭🇺 匈牙利语hu
🇮🇩 印尼语id
🇮🇹 意大利语it
🇯🇵 日语ja
🇵🇱 波兰语pl
🇧🇷 葡萄牙语(巴西)pt-br
🇵🇹 葡萄牙语(葡萄牙)pt-pt
🇷🇴 罗马尼亚语ro
🇷🇺 俄语ru
🇸🇰 斯洛伐克语sk
🇪🇸 西班牙语(西班牙)es
🇹🇷 土耳其语tr
🇺🇦 乌克兰语uk

默认翻译可以通过在 i18n/[code].yaml 中创建自定义文件来覆盖,其中包含翻译字符串。您还可以使用此方法添加新语言。如果您希望与社区分享新的翻译,请Pull Request

配置 #

为了尽可能灵活,需要为网站上的每种语言创建一个语言配置文件。默认情况下,Congo 在 config/_default/languages.en.toml 中包含英语语言配置。

默认文件可以用作创建其他语言的模板,或者如果希望使用英语以外的语言编写网站,则可以重命名。只需使用格式 languages.[language-code].toml 命名文件。

注意: 确保网站配置中的 defaultContentLanguage 参数与语言配置文件名中的语言代码匹配。
名称默认值描述
languageCode"en"此文件的 Hugo 语言代码。它可以是顶级语言(即 en)或子变体(即 en-AU),并应与文件名中的语言代码匹配。
languageName"English"语言的名称。
languageDirection"ltr"这是否是 RTL 语言。设置为 "rtl" 以从右到左重新排列内容。Congo 完全支持同时使用 RTL 和 LTR 语言,并会动态调整到两者。
weight1构建多语言站点时语言的顺序的权重。
title"Congo"网站的标题。这将显示在站点标题和页脚中。
copyright未设置包含要显示在站点页脚中的版权消息的 Markdown 字符串。如果未提供,则 Congo 将使用站点 title 自动生成版权字符串。
params.dateFormat"2 January 2006"此语言中日期的格式。有关可接受格式,请参阅Hugo文档
params.mainSections未设置显示在最新文章列表中的部分。如果未提供,则使用文章数最多的部分。
params.description未设置网站描述。这将用于站点元数据。
author.name未设置作者的姓名。这将显示在文章页脚和使用配置文件布局时在主页上。
author.image未设置作者的图像文件路径。图像应为1:1的宽高比,并放置在站点的 assets/ 文件夹中。
author.headline未设置包含作者头衔的 Markdown 字符串。它将显示在主页上作者姓名下方。
author.bio未设置包含作者简介的 Markdown 字符串。它将显示在文章页脚中。
author.links未设置要显示在作者详细信息旁边的链接。配置文件包含可以取消注释以启用的示例链接。显示链接的顺序由它们在数组中出现的顺序确定。可以通过在 assets/icons/ 中提供相应的 SVG 图标资产来添加自定义链接。

菜单 #

Congo 还支持语言特定的菜单配置。菜单配置文件遵循与语言文件相同的命名格式。只需在文件名中提供语言代码,以告诉 Hugo 该文件与哪种语言相关。

菜单配置文件的命名格式为 menus.[language-code].toml。始终确保菜单配置中使用的语言代码与语言配置相匹配。

快速开始部分更详细地解释了此文件的结构。您还可以参考Hugo 菜单文档以获取更多配置示例。

主题参数 #

Congo 提供了大量的配置参数,用于控制主题的功能。下表概述了 config/_default/params.toml 文件中的每个可用参数。

这里的许多文章默认值可以通过在 front matter 中指定来覆盖每篇文章的默认值。有关详细信息,请参阅Front Matter部分。

名称默认值描述
colorScheme"congo"要使用的主题颜色方案。有效值为 congo(默认)、avocadocherryfireoceansapphireslate。有关详细信息,请参阅颜色方案部分。
defaultThemeColor"#FFFFFFtheme-color meta 标签的原值(在脚本修改它之前)。meta 标签会根据所选主题而变化(lightdark),但是一些软件(例如 Discord)会使用该标签的原值来显示主题色。
defaultAppearance"light"默认的主题外观,可以是 lightdark
autoSwitchAppearancetrue主题外观是否根据访问者的操作系统首选项自动切换。设置为 false 以始终使用 defaultAppearance
enableSearchfalse是否启用站内搜索。设置为 true 以启用搜索功能。请注意,搜索功能取决于 站点配置 中的 outputs.home 设置正确。
enableCodeCopyfalse是否启用 <code> 块的复制到剪贴板按钮。highlight.noClasses 参数必须设置为 false,以使代码复制正常工作。有关其他配置文件的详细信息,请阅读下文。
enableImageLazyLoadingtrue是否将图像标记为浏览器的延迟加载。
robots未设置指示机器人如何处理您的站点的字符串。如果设置,将在页面头部输出。有关有效值,请参阅Google 文档
fingerprintAlgorithm"sha256"指示在对assets进行指纹识别时使用的哈希算法。有效选项包括 md5sha256sha384sha512
header.layout"basic"页面头部和菜单的布局。有效值为 basichamburgerhybridcustom。当设置为 custom 时,您必须通过创建 /layouts/partials/header/custom.html 文件提供自己的布局。
header.logo未设置站点徽标文件在 assets/ 文件夹内的相对路径。徽标文件应以 2x 分辨率提供,并支持任何图像尺寸。
header.logoDark未设置header.logo 参数相同,但此图像在启用深色模式时使用。
header.showTitletrue是否在页眉中显示站点标题。
footer.showCopyrighttrue是否在站点页脚显示版权字符串。请注意,可以使用语言配置中的 copyright 参数自定义字符串。
footer.showThemeAttributiontrue是否在站点页脚显示 “由…强力驱动” 的主题归属。如果选择禁用此消息,请考虑在站点的其他地方(例如关于页面)写上主题归属。
footer.showAppearanceSwitcherfalse是否在站点页脚显示外观切换器。使用浏览器的本地存储来保留访问者的首选项。
footer.showScrollToToptrue设置为 true 时,将显示返回顶部箭头。
homepage.layout"page"主页的布局。有效值为 pageprofilecustom。当设置为 custom 时,您必须通过创建 /layouts/partials/home/custom.html 文件提供自己的布局。有关详细信息,请参阅主页布局部分。
homepage.showRecentfalse是否在主页上显示最近的文章列表。
homepage.recentLimit5homepage.showRecenttrue 时,显示的最大最近文章数。
article.showDatetrue是否显示文章日期。
article.showDateUpdatedfalse是否显示文章更新日期。
article.showAuthortrue是否在文章页脚显示作者框。
article.showBreadcrumbsfalse是否在文章头部显示面包屑。
article.showDraftLabeltrue在使用 --buildDrafts 构建站点时,是否显示文章旁边的草稿标签。
article.showEditfalse是否显示编辑文章内容的链接。
article.editURL未设置article.showEdit 激活时,编辑链接的 URL。
article.editAppendPathtruearticle.showEdit 激活时,是否将当前文章的路径附加到设置为 article.editURL 的 URL。
article.showHeadingAnchorstrue是否在文章内的标题旁边显示锚链接。
article.showPaginationtrue是否在文章页脚显示下一篇/上一篇文章的链接。
article.invertPaginationfalse是否翻转下一篇/上一篇文章链接的方向。
article.showReadingTimetrue是否显示文章阅读时间。
article.showTableOfContentsfalse是否在文章上显示目录。
article.showTaxonomiesfalse是否在与文章相关的分类法上显示。
article.showWordCountfalse是否显示文章字数。
article.showCommentsfalse是否在文章页脚之后包含comments partial
article.sharingLinks未设置要在每篇文章末尾显示的分享链接。如果未提供或设置为 false,则不会显示任何链接。
list.showBreadcrumbsfalse是否在列表页面的页眉中显示面包屑。
list.showTableOfContentsfalse是否在列表页面上显示目录。
list.showTaxonomiesfalse是否在列表页面上显示与此文章相关的分类法。
list.showSummaryfalse是否在列表页面上显示文章摘要。如果在Front Matter中未提供摘要,则将使用站点配置中的 summaryLength 参数自动生成一个摘要。
list.groupByYeartrue是否在列表页面上按年份对文章进行分组。
list.paginationWidth1在需要截断页面列表时,输出当前页面两侧的分页链接数。宽度为 1 将在需要截断列表时输出当前页面两侧的一个链接。当前、第一个和最后一个页面的链接始终会显示,并且是在此值之外的链接。
sitemap.excludedKinds["taxonomy", "term"]应从生成的 /sitemap.xml 文件中排除的内容类型。有关可接受的值,请参阅Hugo 文档
taxonomy.showTermCounttrue是否在分类法列表上显示分类术语内文章的数量。
fathomAnalytics.site未设置由 Fathom Analytics 为网站生成的站点代码。有关详细信息,请参阅分析文档
fathomAnalytics.domain未设置如果在 Fathom Analytics 中使用自定义域,请在此提供以从自定义域提供 script.js
plausibleAnalytics.domain未设置输入要跟踪的网站的域。有关详细信息,请参阅分析文档
plausibleAnalytics.event未设置可寻址 Plausible api 事件的 URL。有关详细信息,请参阅分析文档
plausibleAnalytics.script未设置可寻址 Plausible 分析脚本的 URL。有关详细信息,请参阅分析文档
verification.google未设置由 Google 提供的要包含在站点元数据中的站点验证字符串。
verification.bing未设置由 Bing 提供的要包含在站点元数据中的站点验证字符串。
verification.pinterest未设置由 Pinterest 提供的要包含在站点元数据中的站点验证字符串。
verification.yandex未设置由 Yandex 提供的要包含在站点元数据中的站点验证字符串。

其他配置文件 #

主题还包括一个 markup.toml 配置文件。该文件包含一些重要的参数,确保 Hugo 正确配置以生成使用 Congo 构建的站点。

始终确保此文件存在于配置目录中,并设置所需的值。否则,可能导致某些功能不正确地运行,并可能导致意外的行为。