跳过正文
  1. 文档/

配置

14 分钟· ·
配置 文档
目录
部署教程 - 这篇文章属于一个选集。
§ 4: 本文

Blowfish 适宜个高度定制化的主题,使用到了一些 Hugo 中最新的特性来简化配置方式。

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

我们刚刚推出了 CLI 工具,来帮助你快速上手 Blowfish。它将帮助你进行安装和配置。使用以下命令可以全局范围安装 CLI 工具:

npx blowfish-tools

配置文件是基于 TOML 格式的,这也是 Hugo 默认支持的语法。当然如果你愿意,也可以将配置转换成 YAML 或 JSON 格式。

默认情况下,在每个文件中都定义了主题中的可用参数,因此你可以自由调整设置来满足你的需求。

正如安装说明中的内容,如果你想调整主题配置,可以修改 Hugo 项目中 config/_default/ 文件夹下的文件,并删除项目根目录中的 config.toml 文件。

网站配置
#

Blowfish 主题支持了 Hugo 框架中定义的所有标准配置变量。但如果希望有更好的体验,需要设置一些特定的配置。

网站配置是通过 config/_default/config.toml 文件管理的。下面的表格展示了 Blowfish 中的所有设置.

值得注意的是,表格中提供的变量名可以使用点表示法来简化 TOML 数据结构,例如 outputs.home 指的是 [outputs] home

名称默认值描述
theme"blowfish"当你使用 Hugo 模块安装时,应该移除这个配置项。但对 Git 子模块或本地文件复制的安装方式,必须将其设置为 blowfish 才能正常工作。
baseURL网站 URL 根地址。
defaultContentLanguage"en"这个值决定了主题中组件和内容所使用的默认语言。 参考 语言和 i18n 部分来了解 blowfish 支持的所有语言代码。
enableRobotsTXTtrue当开启这个值,robots.txt 文件将会被创建在站点根目录, 这将允许搜索引擎抓取整个网站。如果你想要自己提供 robots.txt,那么设置这个值为 false 并把你的文件放置到 static 目录下。 为了实现完全控制,你可以需要提供一个 自定义布局 来生成此文件。
pagination.pagerSize10定义文章列表中,每页展示的文章数量。
summaryLength0扉页参数 中没有提供文章摘要时,此参数定义了自动生成文章摘要的单词数量。如果值为0,则默认使用第一句话作为摘要。当摘要被隐藏,这个值没有任何效果。
outputs.home["HTML", "RSS", "JSON"]为站点自动生成输出格式。Blowfish 要求 HTML、RSS 和 JSON 都需要有,以保证主题组件可以正常运作。
permalinks参考 Hugo 文档 中的自定义文章的固定链接配置。
taxonomies参考 整理内容 中的分类器配置。

缩略图
#

Blowfish 的创立开端旨在便于为文章添加视觉效果。如果你熟悉 Hugo 的文章结构,只需要在你文章所在的文件夹中,放置一个以feature*开头的图像文件(Blowfish支持所有格式的文件,但更推荐使用 .png.jpg)。就这样,Blowfish 就能够将图像文件作为文章的缩略图,而且能够在社交平台的 <a target="_blank" href="https://oembed.com/">oEmbed</a> 卡片中使用。

这里 可以看到更多内容,同时我们提供了一个示例,以便你具体看看如何操作。

语言和i18n
#

Blowfish 针对多语言网站进行了优化,主题的资源素材目前已经翻译成了多个语言版本。语言配置允许你生成多个版本的内容介绍,为网站的访问者提供他们母语的定制化体验。

Blowfish 主题目前默认支持了以下语言:

语言代码
Arabicar
Bulgarianbg
Bengalibn
Catalanca
Czechcs
Germande
Englishen
Esperantoeo
Spanish (Spain)es
Finnishfi
Frenchfr
Hebrewhe
Croatianhr
Hungarianhu
Indonesianid
Italianit
Japaneseja
Koreanko
Polishpl
Portuguese (Brazil)pt-br
Portuguese (Portugal)pt-pt
Romanianro
Russianru
Turkishtr
Vietnamesevi
Simplified Chinese (China)zh-cn
Traditional Chinese (Taiwan)zh-tw

组件和静态资源的默认翻译在 i18n/[code].yaml 文件中,当然如果你想自定义,覆盖对应的文件即可。你也可以使用这种方法添加新的语言。如果你想与社区分享心得翻译,请提交PR

配置
#

为了让 Blowfish 尽可能的灵活,每个网站都至少语言创建一个语言配置文件。默认情况下,Blowfish 提供了 config/_default/languages.en.toml 文件以默认支持英语。

默认的文件可以用来作为创建其他语言的一个模板,如果你希望用英语以外的语言撰写网站,也可以对其重命名。只需要格式遵循 languages.[language-code].toml 的命名即可。

注意: 保证 网站设置 中的 defaultContentLanguage参数和你提供的语言配置文件相匹配。

全局
#

名称默认值描述
languageCode"en"Hugo 中的默认语言代码。他可以是一个高层级语言(例如 en),也可以是一个变体子语言(例如 en-au),但一定需要和语言配置文件中的语言代码相匹配。为了符合 HTML 的规范并设置设置大小写敏感的 isoCode,Hugo希望这个值最好是小写。
languageName"English"语言名称。
weight1权重决定了在构建多语言时的语言顺序。
title"Blowfish"网站的标题。它将在网站头部和底部进行展示。

参数
#

名称默认值描述
params.displayName"EN"语言在网站中的展示名。
params.isoCode"en"用于 HTML 元数据的 ISO 语言代码。他可以是一个高层级语言(例如 en),也可以是一个变体子语言(例如 en-au)。
params.rtlfalse用于指定是否是 RTL 语言。设置为 true 则网站会从右向左重拍内容。Blowfish 完全支持同时使用 RTL 和 LTR 语言,并将动态调整。
params.dateFormat"2 January 2006"用于指定如何日期格式化。参考 Hugo 文档 了解可以支持的格式。
params.logoassets/ 文件夹中站点 logo 的相对路径。该 logo 文件需要提供 2x 分辨率并支持任何图像尺寸。
params.secondaryLogoassets/ 文件夹中站点次要 logo 的相对路径。该 logo 文件需要提供 2x 分辨率并支持任何图像尺寸。这个 logo 的颜色方案应该是和上面的是相反或对比的。如果设置了这个值,当用户从 defaultAppearance 模式切换时,将会显示这个 logo。
params.description网站表述。此参数将会被用作站点元数据。
params.copyright此参数是一个 Markdown,用于网站页脚的版权声明。此参数可以包含占位符 { year } ,以此动态插入当前年份。 如果没有提供,Blowfish 将会使用网站 title 自动生成版权信息。

作者
#

名称默认值描述
author.name作者名。此参数将展示在文章页脚。并且如果主页使用了个人资料布局,也会展示此值。
author.image作者头像的文件路径。图像应该是 1:1 的宽高比。可以放在网站的 assets/ 文件夹中,也可以是外部 URL。
author.headline包含作者头衔的 Markdown。它将展示在主页中作者姓名打分下方。
author.bio包含作者简介的 Markdown。它将展示在文章页脚。
author.links与作者详细信息一起显示的链接。配置文件中包含示例链接,取消注释即可启用。链接展示的顺序由他们在数组中定义的顺序决定。如果你想自定义链接,可以在 assets/icons/ 中提供相应的SVG图片。

菜单
#

Blowfish 还支持针对特定语言的菜单配置。菜单配置文件的命名规则和语言配置文件的格式类似。只需要在文件名中提供语言代码,Hugo 就可以知道这是针对哪种语言的菜单。

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

入门指南部分更详细地介绍了这个文件的结构。你还可以参考 Hugo 菜单文档,以获取更多配置示例。

主题参数
#

Blowfish 提供了大量控制主题功能的配置参数,下面的表格中列举了 config/_default/params.toml 文件中所有的可用参数。

下面列举的文章参数是全局默认值,都可以在每个文章中的前置元数据内容中进行覆盖。详细可以参考 扉页参数

全局
#

名称默认值描述
colorScheme"blowfish"主题使用的颜色方案。合法的值有: blowfish (默认)、avocadofireoceanforestprincessneonbloodyterminalmarvelnoirautumncongoslate。 具体参考颜色方案以获取更多信息。
defaultAppearance"light"默认的主题外观,可以是 light 或者 dark
autoSwitchAppearancetrue主题外观是否根据访问者操作系统的偏好自动切换。设置为 false 会强制网站始终使用 defaultAppearance
enableSearchfalse是否开启网站的搜索功能,设为 true 即为启用。注意,搜索功能依赖于站点设置中的 outputs.home 设置,请确保此值配置正确。
enableCodeCopyfalse是否可以将<code>代码块复制到剪贴板。想要使用代码复制功能,需要将 highlight.noClasses 参数设置为 false。 阅读 其他配置文件 以获取更多信息。
mainSections指定最近文章中应该展示的模块。 如果没有指定,则使用文章数量最多的板块。
showViews是否显示文章和列表页面的阅读量。这需要集成 firebase ,具体可以看下面。
showLikes是否显示文章和列表页面的点赞量。这需要集成 firebase ,具体可以看下面。
robots用于支持搜索引擎爬虫如何处理你的网站。如果设置了该值,它将被输出在页面头部。具体的参数值请参考 Google 文档
disableImageZoomfalse禁用网站上所有图片缩放功能。
disableImageOptimizationfalse禁用图片上所有图片的调整大小和优化功能。
disableTextInHeaderfalse禁用文本类型的标题,对基于 logo 的标题很有用。
defaultBackgroundImage设置默认背景图,用于 backgroundhero 布局下的主页。
defaultFeaturedImage设置默认背景图片,用于所有文章的featured图片,可以通过文章目录中的 featured 图片替换。
highlightCurrentMenuArea当菜单被选择时,标记主菜单中的菜单项。
smartTOC开启智能目录,视图中的项目将会被高亮显示。
smartTOCHideUnfocusedChildren当开启智能目录,如果目录级别不再被聚焦时,将会隐藏更深层次的目录。

页头
#

名称默认值描述
header.layout"basic"定义整个站点的页头的布局,支持的参数有 basicfixedfixed-fill、and fixed-fill-blur.

页脚
#

名称默认值描述
footer.showMenutrue显示/隐藏页面底部菜单,该菜单可以在 config/_default/menus.en.toml 文件中的 [[footer]] 部分进行配置。
footer.showCopyrighttrue是否在底部显示 copyright 版权信息。请注意,如果你想定制,可以在语言配置中使用 copyright 参数。
footer.showThemeAttributiontrue是否在网站底部中显示"powered by" 的主题归属信息。如果禁用此参数,请考虑在你网站的其他位置设置主题归属信息,例如在关于页面。
footer.showAppearanceSwitcherfalse是否在也页面底部显示外观切换器。浏览器的本地存储会缓存访问者的偏好设置。
footer.showScrollToToptrue当设置为 true 时,显示返回顶部的箭头按钮。

主页
#

名称默认值描述
homepage.layout"profile"首页布局参数。合法的参数值有: pageprofileherocardbackgroundcustom。当你设置为 custom 时,你必须创建 /layouts/partials/home/custom.html 文件以定制自己的布局。参考主页布局来获取更多信息。
homepage.homepageImageherocard 布局中使用的图像。图片可以来自于本地的资源目录,也可以是外部图像 URL。参考 主页布局 来获取更多信息。
homepage.showRecentfalse是否在主页展示最新文章列表。
homepage.showRecentItems5如果将 showRecent 设置为 true,此参数用于显示多少篇文章。如果没有设置或者为0,则默认显示5篇文章。
homepage.showMoreLinkfalse是否在主页底部添加“显示更多”,该链接会降会用带到一个预定义位置。
homepage.showMoreLinkDest/posts更多按钮所指向的位置。
homepage.cardViewfalse将列表展示为卡片容器。
homepage.cardViewScreenWidthfalse增强列表中卡片的宽度,使其可以占据可用的全部宽度。
homepage.layoutBackgroundBlurfalse向下滚动主页时,是否模糊背景图。

文章页
#

名称默认值描述
article.showDatetrue是否显示日期。
article.showViewsfalse是否显示文章阅读量。这需要集成 firebase ,具体可以看下面。
article.showLikesfalse是否显示文章点赞量。这需要集成 firebase ,具体可以看下面。
article.showDateOnlyInArticlefalse是否在文章内显示日期,不影响文章列表或卡片页面的日期显示。
article.showDateUpdatedfalse是否展示文章的更新日期。
article.showAuthortrue是否在文章底部显示作者框。
article.showAuthorBottomfalse作者框显示在每页的底部而不是顶部。
article.showHerofalse缩略图是否会在每个页面中作为 hero 图像显示。
article.heroStylehero 图像的展示样式,可选的参数值有:basicbigbackgroundthumbAndBackground
article.layoutBackgroundBlurtrue向下滚动文章页时,是否模糊背景图。
article.layoutBackgroundHeaderSpacetrue在标题和正文之间添加空白区域间隔。
article.showBreadcrumbsfalse是否在标题栏显示面包屑导航。
article.showDraftLabeltrue当使用 --buildDrafts 构建网站时,是否在文章旁边显示草稿。
article.showEditfalse是否展示编辑文章的链接。
article.editURL当激活 article.showEdit 参数,此参数用于设置文章的编辑链接。
article.editAppendPathtrue当激活 article.showEdit 参数,是否将文章的路径附加到 article.editURL 参数所设置的 URL 后面。
article.seriesOpenedfalse是否默认显示打开系列模块、
article.showHeadingAnchorstrue是否在文章标题旁添加锚点。
article.showPaginationtrue是否在文章末尾展示上一篇/下一篇的文章链接。
article.invertPaginationfalse是否翻转下一篇/上一篇文章链接的方向。
article.showReadingTimetrue是否展示文章的阅读时间。如果你的语言包含 CJK 语言,需要在 config.toml 中开启 hasCJKLanguage 参数。
article.showTableOfContentsfalse是否展示文章的目录。
article.showRelatedContentfalse为文章显示相关内容。如果你想要启用此功能,请检查 config.toml 文件并复制所有 related 相关的参数,如果你想自定义,也可以对 config.toml 添加额外配置。更多内容请参考 Hugo 文档 中关于 related 的内容。
article.relatedContentLimit3如果启用showRelatedContent,则限制显示相关文章的数量。
article.showTaxonomiesfalse是否显示文章的分类或标签信息。
article.showAuthorsBadgesfalse是否在文章或列表中显示 authors 分类。这需要开启多个作者 multiple authorsauthors 分类法。 请阅读 这个网页 来获取更多内容。
article.showWordCountfalse是否显示文章的字数。 如果你的语言属于 CJK 语言,需要在 config.toml 中开启 hasCJKLanguage 参数。
article.showCommentsfalse是否在文章末尾添加 评论部分
article.sharingLinks在文章末尾显示的分享链接。如果没有提供或设置为 false,则不会显示任何分享链接。可用的值包括:“linkedin”、“twitter”、“reddit”、“pinterest”、“facebook”、“email”、“whatsapp” 和 “telegram”
article.showZenModefalse指定是否激活文章阅读的禅模式,即隐藏常规的界面元素。

列表页
#

名称默认值描述
list.showHerofalse缩略图是否会在每个页面中作为 hero 图像显示。
list.heroStylehero 图像的展示样式,可选的参数值有:basicbigbackgroundthumbAndBackground
list.showBreadcrumbsfalse是否在标题栏显示面包屑导航。
list.layoutBackgroundBlurtrue向下滚动列表页时,是否模糊背景图。
list.layoutBackgroundHeaderSpacetrue在标题和正文之间添加空白区域间隔。
list.showTableOfContentsfalse是否展示目录。
list.showSummaryfalse是否在列表页显示文章摘要。如果在扉页参数中没有提供摘要,那么将会使用站点配置 中的 summaryLength 参数自动生成一个。
list.showViewsfalse是否显示文章阅读量。这需要集成 firebase ,具体可以看下面。
list.showLikesfalse是否显示文章点赞量。这需要集成 firebase ,具体可以看下面。
list.showCardsfalse是否将每个文章显示为卡片或简单的内联文本。
list.groupByYeartrue是否根据年做聚合。
list.cardViewfalse将列表展示为卡片容器。
list.cardViewScreenWidthfalse增强列表中卡片的宽度,使其可以占据可用的全部宽度。
list.constrainItemsWidthfalse将项目宽度限制为 prose 以提高可读性。在没有 featurn 图片的时候非常有用。

网站地图
#

名称默认值描述
sitemap.excludedKinds["taxonomy", "term"]从生成的 /sitemap.xml 文件中排除的内容。 具体的配置请参考Hugo 文档

分类法
#

名称默认值描述
taxonomy.showTermCounttrue是否在分类列表总显示对应的数量。
taxonomy.showHerofalse缩略图是否会在每个页面中作为 hero 图像显示。
taxonomy.heroStylehero 图像的展示样式,可选的参数值有:basicbigbackgroundthumbAndBackground
taxonomy.showBreadcrumbsfalse是否在标题栏显示面包屑导航。
taxonomy.showViewsfalse是否显示文章阅读量。这需要集成 firebase ,具体可以看下面。
taxonomy.showLikesfalse是否显示文章点赞量。这需要集成 firebase ,具体可以看下面。
taxonomy.showTableOfContentsfalse是否显示目录。
taxonomy.cardViewfalse将列表展示为卡片容器。

术语
#

名称默认值描述
term.showHerofalse缩略图是否会在每个页面中作为 hero 图像显示。
term.heroStylehero 图像的展示样式,可选的参数值有: basicbigbackgroundthumbAndBackground
term.showBreadcrumbsfalse是否在标题栏显示面包屑导航。
term.showViewsfalse是否显示文章阅读量。这需要集成 firebase ,具体可以看下面。
term.showLikesfalse是否显示文章点赞量。这需要集成 firebase ,具体可以看下面。
term.showTableOfContentsfalse是否显示目录。
term.groupByYearfalse是否根据年做聚合。
term.cardViewfalse将列表展示为卡片容器。
term.cardViewScreenWidthfalse增强列表中卡片的宽度,使其可以占据可用的全部宽度。

Firebase(Firebase 平台)
#

名称默认值描述
firebase.apiKeyFirebase apiKey, 与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.authDomainFirebase authDomain,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.projectIdFirebase projectId,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.storageBucketFirebase storageBucket,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.messagingSenderIdFirebase messagingSenderId,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.appIdFirebase appId,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面
firebase.measurementIdFirebase measurementId,与 Firebase 集成的必填参数。了解如何将 Firebase 集成进 Blowfish 请参考 这个页面

Fathom Analytics(一种网站分析工具)
#

名称默认值描述
fathomAnalytics.site支持 Fathom 站点分析平台。更多详细内容请参考 分析文档
fathomAnalytics.domain如果使用自定义域名的 Fathom Analytics,请在此提供,以便从自定义域名获取 script.js

Umami Analytics(一种网站分析工具)
#

NameDefaultDescription
umamiAnalytics.websiteid支持 Umami 站点分析平台。更多详细内容请参考 分析文档
umamiAnalytics.domain如果使用自定义域名的 Umami Analytics,请在此提供,以便从自定义域名获取 script.js
umamiAnalytics.dataDomains如果你只想在特别的数个域名中使用 tracker 功能,那么你需要设置它。这个参数的值是逗号分隔的域名列表,如:yoursite.com,yoursite2.com。
umamiAnalytics.enableTrackEventtrue默认会自动添加 Umami Track Event。如果你不想添加 Event,那学需要设置为 false

Seline Analytics
#

NameDefaultDescription
selineAnalytics.tokenSeline 站点分析平台的 token。更多详细内容请参考 分析文档
selineAnalytics.enableTrackEventtrue默认会自动添加 Umami Track Event。如果你不想添加 Event,那学需要设置为 false

BuyMeACoffee(赞助平台)
#

名称默认值描述
buymeacoffee.identifierbuymeacoffee 账号的用户名。
buymeacoffee.globalWidget激活位于全局的 buymeacoffee 组件。
buymeacoffee.globalWidgetMessage新用户首次访问网站时显示的消息。
buymeacoffee.globalWidgetColor组件颜色,使用 HEX 格式。
buymeacoffee.globalWidgetPosition组件位置,例如 “Left” 或 “Right”。

验证
#

名称默认值描述
verification.googleGoogle 提供的网站验证字符串,用于在网站元数据中包含。
verification.bingBing 提供的网站验证字符串,用于在网站元数据中包含。
verification.pinterestPinterest 提供的网站验证字符串,用于在网站元数据中包含。
verification.yandexYandex 提供的网站验证字符串,用于在网站元数据中包含。

别的配置文件
#

Blowfish 主题还包括 markup.toml 配置文件。这个文件包含了一些重要参数,来确保 Hugo 正确配置以生成使用 Blowfish 创建的网站。

需要确保次文件在 config 目录中,并设置所需要的值。否则某些功能可能无法正确启用,并可能导致意外行为。

部署教程 - 这篇文章属于一个选集。
§ 4: 本文

相关文章

缩略图
1 分钟
缩略图 配置 文档
Front Matter(文件头信息)
3 分钟
front matter 配置 文档
多创作者模式
3 分钟
作者 配置 文档
主页布局
3 分钟
主页 布局 文档
入门指南
5 分钟
安装 文档
安装和配置
4 分钟
安装 文档