博客写作规范指南

为了保证博客内容的排版整洁、风格统一以及良好的阅读体验，特制定本写作规范。

一、结构与标题

1. 标题层级

不要使用一级标题 (#)：Hugo 会自动将 Frontmatter 中的 title 渲染为页面一级标题，正文从 二级标题 (##) 开始。
层级递进：遵循 ## -> ### -> ####，不要跳级（例如从 ## 直接跳到 ####）。

正确示例：

## 一、背景介绍
### 1.1 问题描述
#### 1.1.1 详细说明

错误示例：

# 背景介绍 (不要在正文中用一级标题)
### 1.1 问题描述 (跳过了二级标题)

2. 标题编号风格

技术类统一阿拉伯数字：tech 和 blog 目录使用 1.、2. 风格。
- ✅ ## 1. 背景 / ### 2. 方案对比
- ❌ ## 一、背景 / ### 二、方案对比
非技术类保持一致：可用中文序号，但同一篇文章内保持一致。

3. 标题样式

标题不加粗：标题自带粗体，不要额外使用 ** 或 __。
- ✅ ## 核心概念
- ❌ ## **核心概念**
简洁明了：标题应简练概括本节内容，避免长句。

4. 禁止伪标题

不要用加粗当标题：正文中 **关键概念** 不会进入目录。
- ✅ ### 关键概念
- ❌ **关键概念**

二、段落与间距

1. 段落空行

段落间距：段落之间保留一行空行。

2. 段落首行缩进（空两格）

使用全角空格：首行缩进用两个全角空格（U+3000）。
- ✅ 　　这是首行缩进示例。
不要用半角空格：半角空格可能被 Markdown 解析为代码块或被压缩。
替代写法：必要时可以使用 HTML 实体 　 表示全角空格。

3. 块级元素间距

标题、代码块、分割线前后留空行：避免渲染错乱。
引用块与列表：引用和列表前后留空行更清晰。

三、全角与半角

中文标点用全角：逗号、句号、冒号、引号、括号等统一使用全角。
- ✅ 这是中文，使用全角标点。
- ❌ 这是中文, 使用半角标点.
英文与数字用半角：英文单词、数字、技术名词使用半角字符。
- ✅ Go 1.22 / HTTP/2 / Redis
- ❌ Ｇｏ１．２２
中英文混排空格：中文与英文、中文与数字之间保留半角空格。
- ✅ 使用 Go 编写服务 / 版本 1.2
- ❌ 使用Go编写服务 / 版本1.2

四、强调与行内语法

粗体 (**text**)：用于强调关键概念或重点结论，不要滥用。
行内代码 (`text`)：用于标记代码片段、文件名、路径、配置项或专有名词。
- ✅ 请修改 config.yml 文件。
- ❌ 请修改 config.yml 文件。

五、引用与列表

引用块：使用 > 引用外部资料、名言或提示内容。

✅

> 这是一个引用示例。
>
> 引用块也可以包含分段。

列表使用：有序列表用于步骤说明，无序列表用于并列观点。
不要用列表冒充标题：禁止 1. #### 标题 这类写法。

六、代码块规范

指定语言：所有代码块必须指定语言标识符，便于语法高亮。

正确示例：

console.log("Hello");

错误示例：

console.log("Hello");

七、脚注语法

Hugo 支持 Markdown 脚注语法，可用于为正文添加注释、引用来源或补充说明。

1. 基本用法

在正文中用 [^n] 标记脚注，在文末用 [^n]: 注释内容 定义脚注内容：

这是一段正文[^1]，其中包含脚注标记。

[^1]: 这是脚注的具体内容。

2. 渲染行为

Hugo 会自动将 [^n] 渲染为上标链接，点击可跳转到脚注内容
Hugo 会在页面底部自动生成脚注区域，并在脚注列表上方添加一条分割线
脚注区域的标题（如"Footnotes"或"注释"）由主题控制，不要手动添加 **注释** 或 **脚注** 标题

3. 禁止事项

不要在脚注定义前手动加标题：Hugo 会自动生成脚注区域和分割线，手动加 **注释** 标题会导致分割线出现在标题下方，造成视觉重复
- ✅ 直接写 [^1]: 内容
- ❌ 先写 **注释** 再写 [^1]: 内容
脚注编号建议连续：虽然 Markdown 不要求连续编号，但连续编号便于阅读和维护

八、Frontmatter 规范

每篇文章的开头必须包含以下元信息：

---
title: "文章标题"
date: YYYY-MM-DDTHH:MM:SS+08:00
lastmod: YYYY-MM-DDTHH:MM:SS+08:00
author: ["GopherDing"]
keywords: 
-
categories: 
-
tags: 
- 标签1
- 标签2
description: "一句话描述文章内容"
weight:
slug: ""
draft: false
comments: true
reward: false
mermaid: false
showToc: true
TocOpen: true
hidemeta: false
disableShare: true
showbreadcrumbs: true
cover:
    image: ""
    caption: ""
    alt: ""
    relative: false
---

字段说明：

字段	默认值	说明
`draft`	`false`	是否为草稿，发布时设为 `false`
`comments`	`true`	是否开启评论
`reward`	`false`	是否开启打赏
`mermaid`	`false`	仅在文章包含 mermaid 代码块时设为 `true`
`showToc`	`true`	是否显示目录
`TocOpen`	`true`	是否自动展开目录
`hidemeta`	`false`	是否隐藏文章元信息（发布日期、作者等）
`disableShare`	`true`	底部是否隐藏分享栏
`showbreadcrumbs`	`true`	顶部是否显示路径导航
`cover`	空	封面图片，用于文章列表展示

九、古文与摘录类文章格式

content/posts/read/ 目录下的文章用于收录古文、演讲稿、歌词等摘录内容，格式遵循以下约定。

1. Frontmatter 特殊字段

author：填写原作者（如 ["文天祥"]），而非博客作者
tags：使用对应分类标签，如 古文、演讲、歌词
description：选用原文中最具代表性的一句话

2. 正文结构

古文类文章的正文通常包含以下三部分：

朝代·作者

　　原文第一段……

　　原文第二段……

**翻译**

　　翻译第一段……

　　翻译第二段……

[^1]: 注释内容。
[^2]: 注释内容。

要点：

朝代·作者：独占一行，置于正文开头，不加粗
原文：首行用两个全角空格缩进（　　），段落间空一行
翻译：用 **翻译** 标记，与原文之间空一行
注释：使用脚注语法 [^n]，定义放在文末。不要手动添加 **注释** 标题（Hugo 会自动生成脚注区域）

3. 演讲稿类文章

演讲者

　　演讲正文……

**注释**

1. 注释内容。
2. 注释内容。

演讲稿类文章如果注释较少，可以使用有序列表而非脚注，此时允许手动添加 **注释** 标题。

十、图片与资源

图片存放：建议文章相关的图片存放在 static/img 目录下，按分类或文章名归档。
图片引用：使用 Markdown 语法，并填写 alt 文本以便 SEO。
- ![图片描述](/img/path/to/image.png)

十一、常见错误清单（快速排查）

标题加粗重复：### 1. **核心概念** -> ### 1. 核心概念
列表套标题：1. #### 步骤一 -> #### 1. 步骤一
标题层级跳跃：## 下面直接出现 ####
伪标题：**关键概念** -> ### 关键概念
块级元素无空行：标题、代码块、分割线紧贴正文
脚注前手动加标题：删除 **注释** / **脚注** 标题，Hugo 会自动生成

一、结构与标题#

1. 标题层级#

2. 标题编号风格#

3. 标题样式#

4. 禁止伪标题#

二、段落与间距#

1. 段落空行#

2. 段落首行缩进（空两格）#

3. 块级元素间距#

三、全角与半角#

四、强调与行内语法#

五、引用与列表#

六、代码块规范#

七、脚注语法#

1. 基本用法#

2. 渲染行为#

3. 禁止事项#

八、Frontmatter 规范#

九、古文与摘录类文章格式#

1. Frontmatter 特殊字段#

2. 正文结构#

3. 演讲稿类文章#

十、图片与资源#

十一、常见错误清单（快速排查）#