入门指南

npx blowfish-tools

Blowfish 中的配置文件中包含了主题需要的所有可能的设置选项。但默认情况下大多数设置都是被注释的，你只需要取消注释就可以激活或者修改设定选项。

基础设置

#

在刚刚安装完成，创建内容之前，有几个设置需要关注。从 hugo.toml 开始，设置 baseURL 和 languageCode 参数。languageCode参数是用来指定你创作内容的主要语言。

# config/_default/hugo.toml

baseURL = "https://your_domain.com/"
languageCode = "en"

下一步是设置语言。尽管 Blowfish 支持多语言，但是 hugo.toml 只能配置一个主语言。

在 config/_default 文件夹中找到 languages.en.toml。如果你的主语言是英语，你可以直接使用此文件。否则需要重命名为主语言对应的文件名。例如，如果主语言是法语，那么需要将文件命名为 languages.fr.toml。

# config/_default/languages.en.toml

title = "My awesome website"

[author]
name = "My name"
image = "img/author.jpg"
headline = "A generally awesome human"
bio = "A little bit about me"
links = [
  { twitter = "https://twitter.com/username" }
]

[author] 属性决定了作者信息的展示方式。 作者的图片信息应该放在 assets/ 文件夹中。作者相关的链接将会按照排列顺序依次展示。

如果你还需要额外属性，在配置部分会有详细说明。

颜色方案

#

Blowfish 主题中包含了数个颜色方案，这些方案可以快速使用。如果需要修改方案，只需要简单的设置 colorScheme 参数即可。colorScheme 可选的值有blowfish （默认）、avocado、fire、ocean、forest、princess、neon、bloody、terminal、marvel、noir、autumn、congo和slate。

# config/_default/params.toml

colorScheme = "blowfish"

Blowfish 定义了一种由三种主色调构成的配色方案，每种主色调包含了10种子色调，10个色调是借鉴 Tailwind 中的定义。Blowfish 中定义了多个预置的三色主题，以便在整个主题中使用。

Blowfish（默认）

#

Avocado

#

Fire

#

Ocean

#

Forest

#

Princess

#

Neon

#

Bloody

#

Terminal

#

Marvel

#

Noir

#

Autumn

#

Congo

#

Slate

#

整理内容

#

默认情况下， Blowfish 不强制你使用特定类型的内容。这样你可以随意自定义你想要的内容。你可能喜欢用作静态网站页面、博客帖子，或作为作品集中的某个项目。

这是基本 Blowfish 项目的快速概览。所有内容都放在 content 文件夹中：

.
├── assets
│   └── img
│       └── author.jpg
├── config
│   └── _default
├── content
│   ├── _index.md
│   ├── about.md
│   └── posts
│       ├── _index.md
│       ├── first-post.md
│       └── another-post
│           ├── aardvark.jpg
│           └── index.md
└── themes
    └── blowfish

一定要熟练掌握在 Hugo 中组织你想要的内容，此主题也旨在充分利用 Hugo 中页面页面捆绑的逻辑。请阅读 Hugo 官方文档 以获取更多内容。

Blowfish 在分类方法上面也非常灵活。有的人喜欢使用标签（tags）和类别（categories）来分组内容，而有的人喜欢用话题（topics）。

Hugo 默认是使用帖子、标签和类别，这三种可以开箱即用的。但如果你希望自定义，那么可以创建 taxonomies.toml 配置文件来实现：

# config/_default/taxonomies.toml

topic = "topics"

这将把默认的标签和分类替换成话题。有关 Hugo 中命名分类法的更多内容，可以参考 Hugo 分类方法。

当你创建了一个新的分类法时，需要调整网站上的导航链接，以确保新分类可以指向正确的内容，下面会详细介绍。

菜单

#

Blowfish 有两个可以定制的菜单，以此来适配网站中的内容和布局。main菜单出现在网站头部，footer菜单出现在页面底部和版权声明上方。

这两个菜单都是配置在 menus.en.toml 文件中。与语言配置文件类似，如果你希望使用另一种语言，请重命名这个文件并将 en 替换为你所希望的语言代码。

# config/_default/menus.toml

[[main]]
  name = "Blog"
  pageRef = "posts"
  weight = 10

[[main]]
  name = "Topics"
  pageRef = "topics"
  weight = 20

[[main]]
  pre = "github"
  name = "GitHub"
  url = "https://github.com/nunocoracao/blowfish"
  weight = 30

[[main]]
  identifier = "github2"
  pre = "github"
  url = "https://github.com/nunocoracao/blowfish"
  weight = 40

[[footer]]
  name = "Privacy"
  url = "https://external-link"

name 参数用于指定菜单中的文本。你还可以选择性的提供一个 title 标题，它将会被填充到链接的 HTML 代码的 title 属性中。

pageRef 参数用于引用 Hugo 的分类。这是配置菜单最简单的方法，你无需引用任何 Hugo 内容项，它会自动构建正确的链接。如果你需要链接到外部 URL，那么可以使用 url 参数。

菜单中的多个链接将会根据 weight 权重参数进行从低到高排序，如果权重值一样那么会按照 name 字母顺序排序。

这两个菜单都是完全可选的，如果不需要也可以注释掉。你可以使用文件中提供的模板作为示例。

嵌套菜单

#

Blowfish 还支持嵌套菜单。你需要在menu.toml 中定义一个父级菜单项及其子菜单，使用 parent 可以指定子菜单项的父级。在上面菜单部分提到的所有参数一样适用于子菜单项，同样地，pageRef 和 url 也可以在父菜单项中使用。还需要注意一点，嵌套菜单只能在 main 菜单中可用，即网站头部的菜单。

# config/_default/menus.toml

[[main]]
  name = "Parent"
  weight = 20

[[main]]
  name = "sub-menu 1"
  parent = "Parent"
  pageRef = "samples"
  weight = 20

[[main]]
  name = "sub-menu 2"
  parent = "Parent"
  pageRef = "samples"
  weight = 20

[[main]]
  name = "sub-menu 3"
  parent = "Parent"
  pre = "github"
  pageRef = "samples"
  weight = 20

子导航菜单

#

此外，你可以设置一个子导航菜单。只需要在 menus.toml 中将新的菜单项定义为 subnavigation 即可。 这将在主菜单下面展示第二行，其中包含子类别项。

# config/_default/menus.toml

[[subnavigation]]
  name = "An interesting topic"
  pageRef = "tags/interesting-topic"
  weight = 10

[[subnavigation]]
  name = "My Awesome Category"
  pageRef = "categories/awesome"
  weight = 20

默认的 name 是 pageRef 的首字母大写。

缩略图 & 背景

#

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

Blowfish 还支持在文章和列表中使用背景图。为了使与缩略图不同，可以添加一个名为 background* 开头的图像文件。当然如果你没有设置背景图片，Blowfish 会默认使用缩略图作为背景图。