本文提供全面的 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(避免过多)、图片压缩后再上传、使用 `
` 控制摘要。
快速参考#
Front Matter 必选模板#
---
title: "文章标题"
description: "SEO 描述(150-160 字符)"
date: 2026-03-16T10:00:00+08:00
tags: ["tag1", "tag2"]
categories: ["分类"]
showTableOfContents: true
showReadingTime: true
showBreadcrumbs: true
showZenMode: true
---
常用 Shortcodes 速查#
| Shortcode | 用途 | 使用频率 |
|---|---|---|
lead | 文章引言 | 每篇必用 |
alert | 重要提示/警告 | 高 |
mermaid | 流程图/架构图 | 高 |
figure | 增强图片 | 中 |
button | 行动按钮 | 中 |
badge | 状态标签 | 低 |
timeline | 时间线 | 低 |
accordion | 折叠面板 | 低 |
推荐配置组合#
技术教程:
showHero: true
heroStyle: "background"
showTableOfContents: true
showReadingTime: true
showBreadcrumbs: true
showZenMode: true
概念解析:
showHero: true
heroStyle: "basic"
showTableOfContents: true
showReadingTime: true
实战案例:
showHero: true
heroStyle: "background"
showDateUpdated: true
showTableOfContents: true
showReadingTime: true
发布检查清单#
Front Matter#
- title 和 description 完整
- date 格式正确(ISO 8601)
- tags 和 categories 合理
- featureimage 已设置(如有)
- 显示控制参数已配置
内容结构#
- 使用
lead引言 - 标题层级合理(H2-H4)
- 使用表格对比信息
- 代码块指定语言
- 重要信息使用 alert
Shortcodes#
- Mermaid 替代 ASCII 图
- 图片使用 figure
- 必要时使用 button 引导
SEO#
- description 包含关键词
- robots 设置正确
- 图片有 alt 文本
- URL slug 友好
