Posts

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 基于空格分词，对中文不适用。使用 `

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 主题根据文章开头格式自动生成摘要： 开头格式 摘要来源 示例 正文 + `