Blowfish on Zhenda's Blog

Blowfish 图表使用

Mon, 07 Apr 2025 00:00:00 +0800

KaTeX 数学公式

Mon, 07 Apr 2025 00:00:00 +0800

KaTeX 数学公式
#

Blowfish 主题使用 KaTeX 渲染数学公式。KaTeX 是一个快速的数学排版库。

启用方法
#

在文章中添加 shortcode（放在任意位置）：

+++
title = "文章标题"
+++

文章内容...

支持的公式格式
#

行内公式
#

使用 $...$ 包裹：

行内公式: \(E = mc^2\)

效果：行内公式: $E = mc^2$

块级公式
#

使用 $$...$$ 或 \[...\] 包裹：

$$
\varphi = \frac{1 + \sqrt{5}}{2} = 1.6180339887…
$$

效果：

$$ \varphi = \frac{1 + \sqrt{5}}{2} = 1.6180339887… $$

配置原理
#

两层配置
#

层级	文件	作用
Hugo Goldmark	`config/_default/markup.toml`	保留 LaTeX 语法，不转换为 HTML 实体
KaTeX auto-render	`themes/blowfish/assets/lib/katex/auto-render.min.js`	渲染数学公式

Hugo Goldmark 配置
#

config/_default/markup.toml：

[goldmark.extensions.passthrough.delimiters]
 block = [['\[', '\]'], ['$$', '$$']]
 inline = [['\(', '\)']]

这告诉 Hugo：不要转义这些分隔符之间的内容。

KaTeX delimiters 定义
#

KaTeX auto-render 的默认分隔符（在 auto-render.min.js 中）：

分隔符	类型	说明
`$$...$$`	块级	标准块级公式
`$...$`	行内	标准行内公式
`\[...\]`	块级	LaTeX 标准块级
`\begin{equation}...\end{equation}`	块级	equation 环境
`\begin{align}...\end{align}`	块级	align 环境

注意：默认配置不支持 $...$ 作为行内公式分隔符。

常见问题
#

Q: 为什么 $E = mc^2$ 不渲染？
#

A: KaTeX 默认不支持 $...$ 分隔符。使用 $...$ 代替：

❌ $E = mc^2$
✅ \(E = mc^2\)

Q: 如何添加 $...$ 支持？
#

A: 需要自定义 KaTeX 配置。创建 layouts/partials/extend-head.html：

<script>
 document.addEventListener("DOMContentLoaded", function() {
 renderMathInElement(document.body, {
 delimiters: [
 {left: "$$", right: "$$", display: true},
 {left: "$", right: "$", display: false},
 {left: "\\(", right: "\\)", display: false},
 {left: "\\[", right: "\\]", display: true}
 ]
 });
 });
</script>

Q: 中文文章自动摘要不工作？
#

A: Hugo 的 .Summary 基于空格分词，对中文不适用。使用 `

Umami 统计部署指南

Mon, 07 Apr 2025 00:00:00 +0800

Blowfish 布局说明

Sun, 06 Apr 2025 00:00:00 +0800

Blowfish 搜索功能

Sun, 06 Apr 2025 00:00:00 +0800

Blowfish 迁移记录

Sun, 06 Apr 2025 00:00:00 +0800

Blowfish 配置指南

Sun, 06 Apr 2025 00:00:00 +0800

Blowfish 配置选项
#

配置项	当前值	可选值	说明
外观
`colorScheme`	blowfish	blowfish, avocado, fire, ocean, forest, neon, etc.	主题配色
`defaultAppearance`	light	light, dark	默认外观
`autoSwitchAppearance`	true	true, false	自动切换深浅色
导航栏
`header.layout`	fixed	basic, fixed, fixed-fill, fixed-fill-blur	导航栏样式
首页
`homepage.layout`	profile	profile, page, hero, card, background, custom	首页布局
`homepage.showRecentItems`	999	数字	显示文章数
`homepage.cardView`	true	true, false	卡片视图
文章
`article.showHero`	false	true, false	显示 Hero 图片
`article.heroStyle`	-	basic, big, background, thumbAndBackground	Hero 样式
`article.showBreadcrumbs`	false	true, false	面包屑导航
`article.sharingLinks`	-	bluesky, email, facebook, linkedin, mastodon, etc.	分享按钮
列表页
`list.showHero`	false	true, false	列表 Hero 图片
`list.showSummary`	false	true, false	显示摘要
其他
`footer.showAppearanceSwitcher`	false	true, false	底部外观切换
`smartTOC`	-	true, false	智能 TOC 高亮

当前已启用的功能
#

✅ 搜索 (enableSearch = true)
✅ 代码复制 (enableCodeCopy = true)
✅ 固定导航栏 (header.layout = "fixed")
✅ 文章目录 (article.showTableOfContents = true)
✅ 阅读时间 (article.showReadingTime = true)
✅ 字数统计 (article.showWordCount = true)
✅ 标题锚点 (article.showHeadingAnchors = true)
✅ 分类标签 (article.showTaxonomies = true)
❌ 按年份分组 (list.groupByYear = false)
✅ 卡片视图 (list.cardView = true)
⏸️ Giscus 评论（需要自定义 partial）
⏸️ 文章缩略图（可选）
⏸️ 面包屑导航

待配置功能
#

⏸️ 作者头像（需要添加图片）
⏸️ 分享按钮
⏸️ Hero 图片

文章创建配置
#

修改 archetypes/default.md 可设置新文章的默认 front matter：

+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
subtitle = ""
date = {{ .Date }}
draft = false # 默认发布状态
toc = true
series = []
+++

创建新文章时使用：

hugo new posts/my-new-article.md

文章摘要配置
#

Blowfish 主题根据文章开头格式自动生成摘要：

开头格式	摘要来源	示例
正文 + `

Firebase 集成指南

Sun, 06 Apr 2025 00:00:00 +0800

Mermaid 图表支持

Sun, 06 Apr 2025 00:00:00 +0800

如何自定义文章标题

Sun, 06 Apr 2025 00:00:00 +0800

Blowfish on Zhenda's Blog

Blowfish 图表使用

KaTeX 数学公式

KaTeX 数学公式 #

启用方法 #

支持的公式格式 #

行内公式 #

块级公式 #

配置原理 #

两层配置 #

Hugo Goldmark 配置 #

KaTeX delimiters 定义 #

常见问题 #

Q: 为什么 $E = mc^2$ 不渲染？ #

Q: 如何添加 $...$ 支持？ #

Q: 中文文章自动摘要不工作？ #

Umami 统计部署指南

Blowfish 布局说明

Blowfish 搜索功能

Blowfish 迁移记录

Blowfish 配置指南

Blowfish 配置选项 #

当前已启用的功能 #

待配置功能 #

文章创建配置 #

文章摘要配置 #

Firebase 集成指南

Mermaid 图表支持

如何自定义文章标题

KaTeX 数学公式
#

启用方法
#

支持的公式格式
#

行内公式
#

块级公式
#

配置原理
#

两层配置
#

Hugo Goldmark 配置
#

KaTeX delimiters 定义
#

常见问题
#

Q: 为什么 $E = mc^2$ 不渲染？
#

Q: 如何添加 $...$ 支持？
#

Q: 中文文章自动摘要不工作？
#

Blowfish 配置选项
#

当前已启用的功能
#

待配置功能
#

文章创建配置
#

文章摘要配置
#