一份面向 Hexo + Solitude 主题的博文书写指南，侧重 Markdown 语法使用和写作规范。

博文书写指南

1. 文件与 Front-matter 规范

1.1 文件位置与命名

  • 博文统一放在 source/_posts/ 目录下。
  • 文件名建议使用 YYYY-MM-DD-文章标题.md 或 文章标题.md。
  • 标题使用英文或拼音，避免中文文件名在部分系统下出现编码问题。
  • 示例：2026-07-14-hexo-writing-guide.md

1.2 Front-matter 必填字段

1
2
3
4
5
6
7
8
9
10
---
title: 文章标题
date: 2026-07-14 14:30:00
tags:
  - Hexo
  - Markdown
categories:
  - 技术
cover: /img/default.avif
---
字段 说明
title 文章标题，简洁明确
date 发布日期，格式 YYYY-MM-DD HH:MM:SS
tags 标签，1-5 个为宜
categories 分类，建议只设一个主分类
cover 封面图，未设置时使用主题默认图
updated 更新日期，可选
description 文章摘要，可选

1.3 Front-matter 书写注意

  • 字段名后必须加冒号和空格，如 title: 文章标题。
  • 列表项使用 - 开头，保持缩进一致。
  • 字符串中包含特殊字符时建议用引号包裹，如 title: "Hexo #1 指南"。

2. Markdown 语法规范

2.1 标题

  • 一篇文章只能有一个 # 一级标题，通常就是 title 字段对应的内容。
  • 正文从 ## 二级标题 开始。
  • 标题层级必须连续，不要跳级，如 ## 后直接接 ####。
  • 标题前后保留空行。
1
2
3
4
5
## 2. 正文结构

### 2.1 小节标题

这里是正文内容。

2.2 段落与换行

  • 段落之间用空行分隔。
  • 不要使用多个 <br> 强制换行。
  • 中文段落首行不需要缩进。

2.3 列表

有序列表：

1
2
3
1. 第一步
2. 第二步
3. 第三步

无序列表：

1
2
3
4
- 项目一
- 项目二
  - 子项目
  - 子项目

注意：

  • 同级列表符号保持一致。
  • 嵌套列表缩进两个空格。

2.4 强调

1
2
3
4
**粗体**
*斜体*
`行内代码`
~~删除线~~

中文排版建议：

  • 中文与英文、数字之间保留一个空格，如 Hexo 3.0。
  • 标点符号使用中文全角，如 ，。：；！？。
  • 行内代码两侧不加空格，如 使用 hexo clean 清理。

2.5 链接

1
2
[链接文字](https://example.com)
[站内文章](/2026/05/01/发发发/)

规范：

  • 链接文字要有意义，避免使用 “点击这里”。
  • 外部链接建议在新标签页打开，可在主题配置中统一设置。

2.6 图片

1
![图片描述](/img/example.png)

规范：

  • 必须添加 alt 描述。
  • 图片路径使用站内相对路径 /img/xxx。
  • 截图建议压缩后再上传。
  • 重要图片可考虑使用图床加速，但需保证稳定性。

3. 代码块规范

3.1 代码块格式

1
2
3
4
```javascript
function hello() {
  console.log('Hello, World!');
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

- 必须标注语言，以便高亮。
- 代码块前后保留空行。
- 行内代码仅用于短变量、命令或函数名。

### 3.2 常用语言标识

| 语言 | 标识 |
|------|------|
| JavaScript | `javascript` |
| Python | `python` |
| HTML | `html` |
| CSS | `css` |
| Bash/Shell | `bash` |
| YAML | `yaml` |
| JSON | `json` |

### 3.3 代码块注释

- 代码块内使用目标语言的标准注释。
- 关键步骤建议添加简短注释。

## 4. 引用与表格

### 4.1 引用

```markdown
> 这是一段引用文字。
> 多行引用需要在每行开头加 `>`。

4.2 表格

1
2
3
4
| 字段 | 类型 | 说明 |
|------|------|------|
| title | string | 文章标题 |
| date | datetime | 发布时间 |
  • 表头下必须使用 |---| 分隔线。
  • 列对齐方式默认左对齐即可。

5. 标签与分类规范

5.1 标签（tags）

  • 标签应具体、可检索。
  • 避免创建过多近义词标签，如同时有 Hexo 和 hexo。
  • 单个标签不要超过 10 个字符。

5.2 分类（categories）

  • 分类用于文章归档，层级不要过深。
  • 建议预先规划好分类体系，如：
    • 技术
    • 生活
    • 随笔
    • 工具

6. 写作风格规范

6.1 标题与摘要

  • 标题控制在 30 字以内，避免标题党。
  • 首段应概括文章核心内容，方便生成摘要。

6.2 正文结构

建议采用 “总—分—总” 结构：

  1. 引言：说明写作背景和目的。
  2. 正文：分点阐述，配合代码和图示。
  3. 总结：回顾要点，给出建议或展望。

6.3 语言风格

  • 使用简体中文，避免中英混杂。
  • 专业术语首次出现可标注英文，如 “持续集成（Continuous Integration, CI）”。
  • 避免口语化表达，如 “我觉得”、“那个”。

6.4 数字与单位

  • 数字与单位之间保留空格，如 10 MB、2 小时。
  • 年份、日期统一使用阿拉伯数字，如 2026年7月14日。

7. Hexo 特有语法

7.1 文章摘要

在正文中插入 <!-- more -->，首页只显示摘要部分。

1
2
3
4
5
这是摘要内容。

<!-- more -->

这是正文内容。

7.2 资源引用

如果启用 post_asset_folder，可将图片放在文章同名文件夹中：

1
![截图](image.png)

7.3 数学公式

如果主题启用 MathJax，可使用：

1
2
3
$$
E = mc^2
$$

8. 发布前检查清单

  • [ ] Front-matter 字段完整且格式正确
  • [ ] 标题层级连续，只有一个 #
  • [ ] 代码块标注了语言
  • [ ] 图片有 alt 描述且路径正确
  • [ ] 链接可正常访问
  • [ ] 中文与英文、数字之间空格正确
  • [ ] 无明显错别字和语法错误
  • [ ] 已执行 hexo clean && hexo generate 预览
  • [ ] 本地预览无报错

9. 常用命令

1
2
3
4
5
6
7
8
# 清理并生成
hexo clean && hexo generate

# 本地预览
hexo server

# 新建文章
hexo new post "文章标题"