238 lines
12 KiB
Markdown
238 lines
12 KiB
Markdown
---
|
||
title: 进阶自定义
|
||
date: 2020-08-08
|
||
draft: false
|
||
description: "了解如何手动构建 Blowfish。"
|
||
slug: "advanced-customisation"
|
||
tags: ["高级", "CSS", "文档"]
|
||
series: ["部署教程"]
|
||
series_order: 13
|
||
---
|
||
|
||
您可以通过多种方式对 Blowfish 进行高级自定义。请阅读下文，了解更多可自定义的内容以及实现想要效果的最佳方法。
|
||
|
||
如果您需要更多指导，请在 [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions) 上提问。
|
||
|
||
## Hugo 项目结构
|
||
|
||
在开始讨论之前，首先简要介绍一下 [Hugo 项目结构](https://gohugo.io/getting-started/directory-struct/) 以及管理内容和主题自定义的最佳方式。
|
||
|
||
{{< alert >}}
|
||
**总结：** 切勿直接编辑主题文件。一定要仅在 Hugo 项目的子目录中进行自定义，而不是在主题目录中进行自定义。
|
||
{{< /alert >}}
|
||
|
||
Blowfish 旨在利用所有标准的 Hugo 参数操作。它旨在允许在不更改任何核心主题文件的情况下自定义和覆盖主题的所有方面。这也给您提供了一种无缝升级的体验，同时让您完全控制网站的外观和感觉。
|
||
|
||
为了实现这一点，您永远不应该直接手动更改任何主题核心文件。无论你是使用 Hugo 模块安装，还是作为 git 子模块安装，还是手动将主题安装在 `themes/` 目录中，你都应该始终保持这些主题文件不变。
|
||
|
||
调整主题行为的正确方法是通过使用 Hugo 强大的[文件查找顺序](https://gohugo.io/templates/lookup-order/)覆盖文件。总之，查找顺序确保了包含在你的项目目录中的文件都会优先于主题文件。
|
||
|
||
例如，如果您想覆盖 Blowfish 中的主要文章模板， 您可以创建自己的 `layouts/_default/single.html` 文件并将其放在项目的根目录中。然后，此文件将覆盖主题文件中的 `single.html` 同时也不会对主题文件本身进行更改。 这适用于任何主题文件：HTML 模板、partials、shortcodes、config 文件、data、assets 等等。
|
||
|
||
只要您遵循这个方法，您将始终能够无缝更新主题（或测试不同的主题版本），而不必担心会丢失任何自定义更改。
|
||
|
||
## 修改图片优化设置
|
||
|
||
Hugo 有各种内置的方法来调整大小，裁剪和优化图像。
|
||
|
||
举个例子，如果在 `layouts/partials/article-link/card.html` 中，您有以下代码：
|
||
|
||
```go
|
||
{{ with .Resize "600x" }}
|
||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||
{{ end }}
|
||
```
|
||
|
||
Hugo 将默认把图像大小调整为 600px 同时保持比例不变。
|
||
|
||
值得注意的是，默认的图像设置比如[锚点](https://gohugo.io/content-management/image-processing/#anchor) 也可以在你的 [站点配置](https://gohugo.io/content-management/image-processing/#processing-options) 中修改，就和修改模板一样。
|
||
|
||
想要了解更多信息，请再参考 [有关图像处理的 Hugo 文档](https://gohugo.io/content-management/image-processing/#image-processing-methods)。
|
||
|
||
## 配色方案
|
||
|
||
Blowfish 附带了多种开箱即用的配色方案。想要更改基本配色方案，您可以设置 `colorScheme` 主题参数。请参阅[快速上手#配色方案]({{< ref "getting-started#colour-schemes" >}}) 以了解更多内置方案。
|
||
|
||
除了默认方案之外，您还可以创建自己的方案并根据自己的喜好重新设计整个网站的样式。 通过在 `assets/css/schemes/` 中创建 `<scheme-name>.css` 文件可以创建新的配色方案。创建文件后，只需在主题配置中按名称引用它即可。
|
||
|
||
{{< alert "github">}}
|
||
**注意：** 手动生成这些文件可能会比较困难，我编写了一个 `nodejs` 工具 [Fugu](https://github.com/nunocoracao/fugu) 来帮助解决这个问题。简而言之，您只需要提供调色板的三个主要 `hex` 值，程序将生成一个可以直接导入到 Blowfish 中的 css 文件。
|
||
{{< /alert >}}
|
||
|
||
Blowfish 使用一种定义了整个主题中使用的三色调色板。这三种颜色被定义为 `neutral` 、 `primary` 和 `secondary` 颜色，每种颜色包含十种色调。
|
||
|
||
由于 Tailwind CSS 3.0 计算不透明度颜色值的方式，方案中指定的颜色需要通过提供红色、绿色和蓝色值来[符合特定格式](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) 。
|
||
|
||
```css
|
||
:root {
|
||
--color-primary-500: 139, 92, 246;
|
||
}
|
||
```
|
||
|
||
此示例为一个 `primary-500` 的 CSS 颜色变量，红色值为 `139`，绿色值为 `92`，蓝色值为 `246`。
|
||
|
||
您可以使用现有主题样式表之一作为模板并自由配置自己的颜色。如果想要寻求一些灵感，请查看官方 [Tailwind 调色板参考](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) 。
|
||
|
||
## 覆盖样式
|
||
|
||
有时您需要添加自定义样式来设置您自己的 HTML 元素的样式。 Blowfish 允许您覆盖自己的 CSS 样式表中的默认样式来进行自定义。只需在项目的 `assets/css/` 文件夹中创建一个 `custom.css` 文件即可。
|
||
|
||
`custom.css` 文件将被 Hugo 优化并在所有其他主题样式之后自动加载，这意味着自定义文件中的任何内容都将优先于默认值。
|
||
|
||
### 使用附加字体
|
||
|
||
Blowfish 可以让您轻松更改网站的字体。在项目的 `assets/css/` 文件夹中创建 `custom.css` 文件后，将字体文件放入 `static/fonts` 文件夹中。
|
||
|
||
```shell
|
||
.
|
||
├── assets
|
||
│ └── css
|
||
│ └── custom.css
|
||
...
|
||
└─── static
|
||
└── fonts
|
||
└─── font.ttf
|
||
|
||
```
|
||
|
||
这样，该字体便可供网站使用。现在，可以将字体导入到您的 `custom.css` 中，并在您认为合适的地方进行替换。下面的示例展示了替换整个 `html` 字体的方法。
|
||
|
||
```css
|
||
@font-face {
|
||
font-family: font;
|
||
src: url('/fonts/font.ttf');
|
||
}
|
||
|
||
html {
|
||
font-family: font;
|
||
}
|
||
```
|
||
|
||
### 调整字体大小
|
||
|
||
我们也提供更改网站的字体大小的示例。 Blowfish 使这一切变得简单，因为它在整个主题中使用源自基本 HTML 语言的缩放字体大小方法。默认情况下，Tailwind 将默认大小设置为 `12pt` ，但您可以将其更改为喜欢的大小。
|
||
|
||
参考[上面的说明]({{< ref "#overriding-the-stylesheet" >}}) 创建一个 `custom.css` 文件并添加以下 CSS 声明：
|
||
|
||
```css
|
||
/* Increase the default font size */
|
||
html {
|
||
font-size: 13pt;
|
||
}
|
||
```
|
||
|
||
只需更改此值，您网站上的所有字体大小都将调整为此新大小。因此，要增加使用的整体字体大小，请将该值设置为大于 `12pt` 。同样，要减小字体大小，请将值设置为小于 `12pt` 。
|
||
|
||
## 从源代码构建主题 CSS
|
||
|
||
如果您想进行大量更改，您可以利用 Tailwind CSS 的 JIT 编译器并从头开始重建整个主题 CSS。尤其是您想要调整 Tailwind 配置或向主样式表添加额外的 Tailwind 类的时候，这种方法将非常有用。
|
||
|
||
{{< alert >}}
|
||
**注意：** 手动构建主题仅适用于高级用户。
|
||
{{< /alert >}}
|
||
|
||
让我们逐步了解构建 Tailwind CSS 的工作原理。
|
||
|
||
### Tailwind 配置
|
||
|
||
为了生成仅包含用于实际使用的 Tailwind 类的 CSS 文件，JIT 编译器需要扫描所有 HTML 模板和 Markdown 文档，以检查 markup 中存在哪些样式。编译器将根据主题目录根目录中的 `tailwind.config.js` 文件来完成此操作：
|
||
|
||
```js
|
||
// themes/blowfish/tailwind.config.js
|
||
|
||
module.exports = {
|
||
content: [
|
||
"./layouts/**/*.html",
|
||
"./content/**/*.{html,md}",
|
||
"./themes/blowfish/layouts/**/*.html",
|
||
"./themes/blowfish/content/**/*.{html,md}",
|
||
],
|
||
|
||
// 更多...
|
||
};
|
||
```
|
||
|
||
此默认配置包含了这些路径，以便您可以十分方便地生成自己的 CSS 文件，而无需修改它，前提是您遵循我们的主题项目结构。也就是说，**您必须将 Blowfish 主题文件夹 `themes/blowfish/` 作为子目录包含在项目中**。这意味着您无法使用 Hugo Modules 方式来安装主题，而必须使用 git 子模块（推荐）或手动安装。 [安装文档]({{< ref "installation" >}}) 介绍了如何使用以上方法安装主题。
|
||
|
||
### 项目结构
|
||
|
||
为了充分利用默认配置，您的项目结构应该如下所示：
|
||
|
||
```shell
|
||
.
|
||
├── assets
|
||
│ └── css
|
||
│ └── compiled
|
||
│ └── main.css # 这是我们生成的文件
|
||
├── config # 站点配置
|
||
│ └── _default
|
||
├── content # site content
|
||
│ ├── _index.md
|
||
│ ├── projects
|
||
│ │ └── _index.md
|
||
│ └── blog
|
||
│ └── _index.md
|
||
├── layouts # 站点的自定义布局
|
||
│ ├── partials
|
||
│ │ └── extend-article-link/simple.html
|
||
│ ├── projects
|
||
│ │ └── list.html
|
||
│ └── shortcodes
|
||
│ └── disclaimer.html
|
||
└── themes
|
||
└── blowfish # Git 子模块或本地复制安装
|
||
```
|
||
|
||
此示例结构添加了一个新自定义的 `projects` 内容类型，具有自定义的 layout 以及自定义的 shortcodes 和扩展的 partials 。如果项目遵循类似结构，所需要做的就是仅仅是重新编译 `main.css` 文件。
|
||
|
||
### 安装依赖项
|
||
|
||
为了使 Tailwind 正常工作，您需要更改终端工作目录为 `themes/blowfish/` 并安装项目依赖项。您需要安装 [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install)。
|
||
|
||
```shell
|
||
cd themes/blowfish
|
||
npm install
|
||
```
|
||
|
||
### 运行 Tailwind 编译器
|
||
|
||
安装依赖项后，接下来可以使用 [Tailwind CLI](https://v2.tailwindcss.com/docs/installation#using-tailwind-cli) 来调用 JIT 编译器。返回 Hugo 项目的根目录并在终端输入以下命令：
|
||
|
||
```shell
|
||
cd ../..
|
||
./themes/blowfish/node_modules/tailwindcss/lib/cli.js -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||
```
|
||
|
||
这个命令稍微有点复杂，因为涉及到几个路径。但本质上你是在调用 Tailwind CLI 并提供下面三个参数：
|
||
- Tailwind 配置文件 `tailwind.config.js`
|
||
- 主题的 `main.css` 文件
|
||
- 编译产出后的 CSS 文件的位置 `assets/css/compiled/`
|
||
|
||
配置文件将自动检查项目中以及主题中的所有内容和布局，并构建一个新的 CSS 文件，其中包含网站所需的所有 CSS。由于 Hugo 处理文件层次结构的方式，此文件现在将自动覆盖主题附带的文件。
|
||
|
||
每次更改布局并需要新的 Tailwind CSS 样式时，您只需重新运行命令并生成新的 CSS 文件即可。您还可以在命令末尾添加 `-w` 以在监视模式下运行 JIT 编译器。
|
||
|
||
### 制作构建脚本
|
||
|
||
要完成此解决方案，您可以通过为这些命令添加别名来简化整个过程，或者参照我的操作，将该 `package.json` 添加到包含必要脚本的项目的根目录：
|
||
|
||
```js
|
||
// package.json
|
||
|
||
{
|
||
"name": "my-website",
|
||
"version": "1.0.0",
|
||
"description": "",
|
||
"scripts": {
|
||
"server": "hugo server -b http://localhost -p 8000",
|
||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/tailwindcss/lib/cli.js -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/tailwindcss/lib/cli.js -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||
},
|
||
// and more...
|
||
}
|
||
```
|
||
|
||
现在，当您想要设计站点时，可以调用 `npm run dev` ，编译器将以监视模式运行。当您准备好部署时，运行 `npm run build` ，您将生成一个编译好的 Tailwind CSS。
|
||
|
||
🙋♀️ 如果您需要帮助，请随时在 [GitHub Discusions](https://github.com/nunocoracao/blowfish/discussions) 上提问。
|