Hugo on Zayn's Blog

从 60 分到 95 分：Hugo Blowfish 博客的极致优化之路

yangzun@treesir.pub (Zayn) — Mon, 16 Mar 2026 12:00:00 +0800

20+ 项优化、16 个 MR、涵盖 SEO 修复、布局重构、苹果代码框、封面图自动化和 SSH 远程部署的完整博客优化复盘。

Blowfish 文章优化前后对比分析

yangzun@treesir.pub (Zayn) — Mon, 16 Mar 2026 02:30:00 +0800

通过 Front Matter、内容结构和 Shortcodes 的具体优化前后对比，直观展示文章质量提升效果。

Blowfish 主题文章优化指南

yangzun@treesir.pub (Zayn) — Mon, 16 Mar 2026 02:00:00 +0800

本文提供全面的 Blowfish 主题文章优化最佳实践，帮助你创建优雅、简洁、结构化、美观、逻辑清晰的技术文档。从 Front Matter 到 Shortcodes，一站式掌握 Blowfish 的正确用法。

Front Matter 优化
#

推荐的完整 Front Matter 模板
#

---
# 基础信息
title: "文章标题"
description: "SEO 友好的简短描述，建议 150-160 字符"
date: 2026-03-16T10:00:00+08:00
lastmod: 2026-03-16T12:00:00+08:00
draft: false

# 分类
tags: ["kubernetes", "devops", "云原生"]
categories: ["技术实践"]
series: ["Kubernetes 进阶"] # 如果属于某个系列
series_order: 1 # 系列中的顺序

# 图片
featureimage: "https://images.unsplash.com/photo-1461749280684-dccba630e2f6?w=1920&h=1080&fit=crop&q=100"
featureimagecaption: "图片说明（可选）"
showHero: true
heroStyle: "background" # basic, big, background, thumbAndBackground

# 显示控制
showDate: true
showDateUpdated: true
showReadingTime: true
showWordCount: true
showTableOfContents: true
showTaxonomies: true
showBreadcrumbs: true
showPagination: true
showZenMode: true

# SEO
robots: "index, follow"
excludeFromSearch: false
---

Front Matter 参数分类
#

必需参数
#

参数	说明	示例
`title`	文章标题	`"Kubernetes 部署指南"`
`description`	SEO 描述	`"从零开始学习 K8s 集群部署"`
`date`	发布日期	`2026-03-16T10:00:00+08:00`
`tags`	标签（数组）	`["kubernetes", "devops"]`

参数	说明	建议值
`showHero`	显示英雄图	`true`
`heroStyle`	英雄图样式	`"background"`
`showTableOfContents`	显示目录	`true`
`showReadingTime`	显示阅读时间	`true`
`showBreadcrumbs`	显示面包屑	`true`
`showZenMode`	显示 Zen 模式	`true`

可选参数
#

参数	说明	使用场景
`lastmod`	最后更新日期	更新文章后
`series`	系列名称	多篇相关文章
`series_order`	系列顺序	系列文章排序
`featureimage`	特性图片	有配图的文章
`robots`	SEO 指令	控制搜索引擎行为

不同类型文章的 Front Matter 建议
#

技术教程
#

---
title: "从零开始部署 Kubernetes 集群"
description: "详细介绍如何在生产环境部署高可用 K8s 集群"
date: 2026-03-16T10:00:00+08:00
tags: ["kubernetes", "devops", "tutorial"]
categories: ["技术教程"]
series: ["Kubernetes 生产实践"]
series_order: 1
showHero: true
heroStyle: "background"
featureimage: "k8s-cluster.jpg"
showTableOfContents: true
showReadingTime: true
---

概念解析
#

---
title: "深入理解 Kubernetes 架构"
description: "解析 K8s 核心组件和设计理念"
date: 2026-03-16T10:00:00+08:00
tags: ["kubernetes", "architecture"]
categories: ["技术概念"]
showHero: true
heroStyle: "basic"
showTableOfContents: true
showReadingTime: true
---

实战案例
#

---
title: "K8s 故障排查：Pod 一直处于 CrashLoopBackOff"
description: "记录一次完整的 K8s 故障排查过程"
date: 2026-03-16T10:00:00+08:00
lastmod: 2026-03-16T12:00:00+08:00
tags: ["kubernetes", "troubleshooting", "case-study"]
categories: ["故障排查"]
showHero: true
heroStyle: "background"
featureimage: "debugging.jpg"
showDateUpdated: true
showTableOfContents: true
---

内容结构最佳实践
#

1. 使用 Lead 引言
#

在文章开头使用 lead 突出核心内容：

{{< lead >}}
从零开始学习 Kubernetes 集群部署，涵盖环境准备、集群初始化、
网络配置到生产就绪的完整流程。
{{< /lead >}}

2. 结构化标题层级
#

# 主标题（H1，自动由 title 生成）

{{< lead >}}
引言内容
{{< /lead >}}

## 第一部分（H2）

### 子章节 1.1（H3）

#### 细节说明（H4）

### 子章节 1.2（H3）

## 第二部分（H2）

标题建议：H2 用于主要章节，H3 用于子章节，H4 用于细节说明，避免超过 4 级标题。

3. 使用表格对比信息
#

| 特性 | Docker | Kubernetes |
|------|--------|-----------|
| 容器编排 | 单机 | 集群级别 |
| 服务发现 | 手动配置 | 自动发现 |
| 负载均衡 | 需要额外工具 | 内置支持 |

4. 代码块语法高亮
#

支持的语言：bash, yaml, json, go, python, javascript, typescript, dockerfile, nginx 等。

5. 使用 Callout 提示重要信息
#

{{< alert icon="triangle-exclamation" >}}
**警告**：此操作不可逆，请先备份数据！
{{< /alert >}}

{{< alert icon="check-circle" cardColor="#10b981" iconColor="#fff" textColor="#fff" >}}
**最佳实践**：使用 Helm 管理应用配置。
{{< /alert >}}

Shortcodes 使用指南
#

1. Mermaid 流程图
#

替代 ASCII 字符画，使用 Mermaid 绘制流程图：

{{< mermaid >}}
graph TB
 A[开始部署] --> B{环境检查}
 B -->|通过| C[安装 Docker]
 B -->|失败| D[修复环境]
 D --> B
 C --> E[初始化集群]
 E --> F[部署网络插件]
 F --> G[验证集群]
{{< /mermaid >}}

常见图表类型：

流程图 graph TD - 决策流程、部署步骤
时序图 sequenceDiagram - API 调用、组件交互
架构图 graph TB + subgraph - 系统架构

2. Figure 增强图片
#

{{< figure
 src="architecture.png"
 alt="Kubernetes 架构图"
 caption="图 1：Kubernetes 集群架构"
 href="https://kubernetes.io"
 target="_blank"
>}}

3. Button 行动按钮
#

{{< button href="https://github.com" target="_blank" >}}
查看源码
{{< /button >}}

4. Badge 标签
#

{{< badge >}}New{{< /badge >}}
{{< badge style="warning" >}}Deprecated{{< /badge >}}

5. Timeline 时间线
#

{{< timeline >}}
{{< timelineItem icon="check" header="第一步" subheader="2026-03-01" >}}
项目启动
{{< /timelineItem >}}
{{< timelineItem icon="check" header="第二步" subheader="2026-03-10" >}}
完成开发
{{< /timelineItem >}}
{{< /timeline >}}

6. KaTeX 数学公式
#

<!-- 行内公式 -->
{{< katex >}}a^2 + b^2 = c^2{{< /katex >}}

<!-- 块级公式 -->
{{< katex display="true" >}}
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
{{< /katex >}}

实战优化示例
#

技术教程优化
#

优化前：

---
title: "Traefik 部署"
date: 2021-01-17
tags: ["traefik"]
---

# Traefik 简介

Traefik 是一个反向代理...

## 安装

kubectl apply -f traefik.yaml

优化后：

---
title: "Traefik Ingress Controller 完整部署指南"
description: "从零开始学习 Traefik：详细介绍如何在 Kubernetes 中部署和配置 Traefik Ingress Controller"
date: 2021-01-17T16:15:32+08:00
lastmod: 2026-03-16T10:00:00+08:00
tags: ["traefik", "ingress", "kubernetes"]
categories: ["网络", "Kubernetes"]
series: ["Kubernetes 网络实践"]
series_order: 2
featureimage: "traefik-architecture.png"
showHero: true
heroStyle: "background"
showTableOfContents: true
showReadingTime: true
showDateUpdated: true
---

优化后的内容结构：

{{< lead >}}
Traefik 是现代化的云原生反向代理和负载均衡器，
专为微服务架构设计。本指南将带你从零开始掌握 Traefik 的部署和配置。
{{< /lead >}}

## Traefik 核心优势

| 特性 | 传统代理 | Traefik |
|------|----------|---------|
| 配置方式 | 手动编辑 | 自动发现 |
| 配置更新 | 需要重启 | 动态实时更新 |
| 容器支持 | 需要额外配置 | 原生支持 |

## 架构概览

{{< mermaid >}}
graph TB
 Client[客户端] --> Traefik
 Traefik --> Service1[服务 A]
 Traefik --> Service2[服务 B]
 Traefik --> Service3[服务 C]
 subgraph Kubernetes
 Service1
 Service2
 Service3
 end
{{< /mermaid >}}

## 部署方式

### 使用 Helm 部署

```bash
helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik \
 --namespace traefik \
 --create-namespace
```

### 使用 kubectl 部署

```bash
kubectl apply -f https://raw.githubusercontent.com/.../kubernetes-crd-rbac.yml
```

{{< alert icon="triangle-exclamation" >}}
**注意**：生产环境建议配置持久化存储和 RBAC 权限。
{{< /alert >}}

架构文档优化
#

优化前：

---
title: "OpenClaw 架构"
date: 2026-03-15
---

优化后：

---
title: "OpenClaw AI Agent 架构解析：多引擎联动与记忆系统"
description: "深入解析 OpenClaw AI Agent 的核心架构设计，包括多 AI 引擎联动、Skills 系统和 MCP 集成"
date: 2026-03-15T22:30:00+08:00
tags: ["AI", "Agent", "OpenClaw", "Architecture"]
categories: ["系统架构"]
series: ["OpenClaw 技术解析"]
series_order: 1
showHero: true
heroStyle: "background"
showTableOfContents: true
showReadingTime: true
showZenMode: true
---

优化后的内容结构：

{{< lead >}}
OpenClaw 是一个现代化的 AI Agent 框架，支持多引擎联动、技能系统和记忆管理。
本文将深入解析其核心架构设计。
{{< /lead >}}

## 核心架构

{{< mermaid >}}
graph TB
 subgraph Agent["OpenClaw Agent"]
 Claude["Claude Sonnet 4.6"]
 GPT["GPT-5.2/5.3"]
 end
 subgraph Router["Model Router"]
 Route["路由层"]
 end
 Claude --> Route
 GPT --> Route
 Route --> Skills["Skills Layer"]
 Skills --> MCP["MCP Layer"]
{{< /mermaid >}}

### 核心组件说明

| 组件 | 职责 | 技术栈 |
|------|------|--------|
| **Agent 层** | AI 模型集成 | Claude, GPT, GLM, Gemini |
| **Router 层** | 智能路由分发 | 自定义路由规则 |
| **Skills 层** | 技能系统 | 90+ 预置技能 |
| **MCP 层** | 外部集成 | Teambition, Nowledge Mem |

{{< alert icon="triangle-exclamation" >}}
**重要**：Working Memory 每日自动清理，
重要信息需要手动归档到 Long-term Memory。
{{< /alert >}}

常见问题
#

如何选择 heroStyle？
#

heroStyle	适用场景	特点
`basic`	简单文章	小图片，简洁
`big`	重要文章	大图片，突出
`background`	推荐	全屏背景，现代感
`thumbAndBackground`	双图需求	缩略图+背景

大多数文章推荐使用 background。

何时使用 Mermaid？
#

适用场景：流程图、时序图、架构图、状态转换图、甘特图。

不适用场景：简单的 2-3 步流程（用列表即可）、需要精细控制的图形（用图片）。

如何优化图片？
#

使用 WebP 格式（Hugo 自动转换）
提供不同尺寸（响应式）
添加 alt 文本（SEO）
使用 caption 说明

如何组织系列文章？
#

规划系列名称和顺序
每篇文章添加 series 和 series_order
第一篇设置 seriesOpened: true

---
series: ["Kubernetes 进阶"]
series_order: 1
seriesOpened: true
---

性能优化建议
#

构建优化：启用图片优化（默认开启）、使用 CDN 加速、减少不必要的 shortcodes。

内容优化：合理使用 Mermaid（避免过多）、图片压缩后再上传、使用 `

欢迎来到我的博客！

yangzun@treesir.pub (Zayn) — Thu, 02 Jan 2025 10:00:00 +0800

我很兴奋地推出这个使用 Hugo 和令人惊叹的 Blowfish 主题构建的新博客！

为什么选择 Hugo 和 Blowfish？
#

在研究了各种博客平台和静态网站生成器后，我选择 Hugo 有以下几个原因：

Hugo 的优势
#

闪电般快速: Hugo 是最快的静态网站生成器之一
灵活性: 支持各种内容类型和自定义选项
SEO 友好: 内置 SEO 优化功能
Markdown 支持: 使用简单易读的 Markdown 编写内容

Blowfish 主题特色
#

精美设计: 简洁、现代、专业的外观
响应式: 在桌面、平板和移动设备上都表现出色
多种布局: 可选择各种首页和内容布局
配色方案: 多种内置配色方案
丰富功能: 支持评论、分析、社交分享等功能

接下来会写什么？
#

我计划写关于以下主题的内容：

Hugo 入门：初学者指南

yangzun@treesir.pub (Zayn) — Wed, 01 Jan 2025 15:30:00 +0800

Hugo 是最受欢迎的静态网站生成器之一，以其速度和灵活性而闻名。在本指南中，我们将介绍开始使用 Hugo 所需了解的一切。

什么是 Hugo？
#

Hugo 是一个用 Go 语言编写的快速现代静态网站生成器。它将你用 Markdown 编写的内容转换为包含 HTML、CSS 和 JavaScript 的完整网站。

每日技术实践简报 - 2026-03-29：从 MCP 到一键发包的博客深度写作与 Skill 链优化

yangzun@treesir.pub (Zayn) — Sun, 29 Mar 2026 23:00:00 +0800

今日技术实践
#

解决的问题
#

深度博客文章撰写：完成"从 MCP 到一键发包"的 300+ 行技术博客，完整记录了从 Teambition MCP 对接到 APK 自动上传 Nexus 的全链路踩坑过程。
Blowfish 主题 shortcode 踩坑：发现主题没有 notice shortcode，只有 alert。经过多次 sed/edit 替换尝试，最终确认正确语法为 {{< alert "icon-name" >}}内容{{< /alert >}}。
Mermaid 流程图修复：从 text 代码块改为 {{< mermaid >}} shortcode 格式，Hugo 才能正确渲染可视化流程图。
Git 分支治理：发现旧分支 feat/extract-markdown-rental-risk-20260324 堆积了大量无关提交（_index.md 修改、租房信息文章等），从 main 重新创建干净分支，只包含必要文件。

学到的新东西
#

Blowfish 可用 shortcode 清单：alert、mermaid、chart、timeline、figure、gist、katex 等。写文章前先确认 shortcode 存在，不要凭记忆用。
blog-post-generator Skill 规范：frontmatter 需要 featureimage、keywords、tags_weight/categories_weight；推荐阅读用相对路径内链；代码块必须是实际可用代码，不要伪代码。
Git 分支清理策略：保护分支的仓库应"从 main 创建新分支 → cherry-pick 或 checkout 需要的文件 → 关闭旧 MR → 创建新 MR"，比 rebase 更可控。
租房等非技术内容不应推到技术博客：分支提交前必须 review 文件列表，排除无关内容。

实际产出
#

深度博客文章 1 篇（302 行，9892 字节）
3月28日日报 1 篇
Git MR !53 创建（干净版本，排除租房信息）

踩坑记录
#

notice shortcode 不存在：Blowfish 主题没有 notice，只有 alert。Skill 文档记录有误，需以实际 shortcode 目录为准。
多次 sed 替换导致文件状态混乱：部分 notice 被替换为 alert，但残留不完整标签。应一次性 read 全文确认再精确 edit。
Hugo 版本兼容性警告：Module “blowfish” is not compatible with Hugo 0.137.0/0.148.0，但实际构建可通过，属于警告而非阻断。

其他思考
#

博客写作风格确立：口语化、有实操感、不要 AI 味；像一个资深工程师在写给同行看；段落简短，多用小标题。
博客 Skill 链（blowfish-hugo + blog-post-generator + structured-guide-writer）已形成完整工作流，后续写作效率会持续提升。

Hugo on Zayn's Blog

从 60 分到 95 分：Hugo Blowfish 博客的极致优化之路

Blowfish 文章优化前后对比分析

Blowfish 主题文章优化指南

Front Matter 优化 #

推荐的完整 Front Matter 模板 #

Front Matter 参数分类 #

必需参数 #

推荐参数 #

可选参数 #

不同类型文章的 Front Matter 建议 #

技术教程 #

概念解析 #

实战案例 #

内容结构最佳实践 #

1. 使用 Lead 引言 #

2. 结构化标题层级 #

3. 使用表格对比信息 #

4. 代码块语法高亮 #

5. 使用 Callout 提示重要信息 #

Shortcodes 使用指南 #

1. Mermaid 流程图 #

2. Figure 增强图片 #

3. Button 行动按钮 #

4. Badge 标签 #

5. Timeline 时间线 #

6. KaTeX 数学公式 #

实战优化示例 #

技术教程优化 #

架构文档优化 #

常见问题 #

如何选择 heroStyle？ #

何时使用 Mermaid？ #

如何优化图片？ #

如何组织系列文章？ #

性能优化建议 #