1. 文件规范
1.1 文件扩展名
Markdown 文件必须使用 .md 扩展名。
正确：
docker-installation.md
docker-compose.md
mysql-index.md
错误：
docker-installation.markdown
docker-installation.txt
1.2 文件名
文件名统一使用小写字母。
多个单词之间使用 - 分隔，不使用空格、下划线或驼峰命名。
推荐：
docker-installation.md
docker-image-optimization.md
mysql-deep-pagination.md
不推荐：
DockerInstallation.md
docker_installation.md
docker installation.md
1.3 文件编码
Markdown 文件必须使用 UTF-8 编码。
2. 标题规范
2.1 文档标题
按照 FEX 规范，文档标题可以使用 Setext 风格：
Markdown 编写规范
================
如果项目使用 Hugo 等现代 Markdown 工具链，也可以使用：
# Markdown 编写规范
但是，如果严格遵循 FEX Team 原规范，则推荐使用 Setext 风格作为文档标题。
对于 Hugo 技术文章，如果 Front Matter 已经提供 title，正文通常不再重复一级标题。
例如：
---
title: "Docker 镜像优化与安全"
---
正文直接从：
## 为什么要优化 Docker 镜像
开始。
2.2 章节标题
章节标题必须从 ## 开始。
正确：
## Docker 是什么
错误：
# Docker 是什么
标题标记 ## 与标题文字之间必须有一个空格。
正确：
## Docker 是什么
错误：
##Docker 是什么
标题末尾不要再次添加 #。
正确：
## Docker 是什么
错误：
## Docker 是什么 ##
2.3 标题与正文
标题和正文之间必须保留一个空行。
正确：
## Docker 是什么
Docker 是一种容器化技术。
错误：
## Docker 是什么
Docker 是一种容器化技术。
2.4 标题层级
标题应该保持合理的层级关系。
推荐：
## Docker 镜像
### 镜像是什么
### 镜像如何构建
## Docker 容器
### 容器是什么
### 容器如何运行
不推荐跳级：
## Docker 镜像
#### 镜像是什么
通常建议：
## 主要章节
### 子章节
#### 必要的细分内容
技术博客不应该为了增加目录层级而大量使用 ####。
3. 段落规范
一个段落只表达一个主要主题。
推荐：
Docker 镜像由多个只读 Layer 组成。每一层对应 Dockerfile 中的一条
或多条构建指令。
镜像构建完成后，可以通过 Registry 进行存储和分发。
不推荐把多个主题全部堆在一个段落中：
Docker 镜像由多个 Layer 组成，可以通过 Dockerfile 构建，也可以推送到
Registry，还可以通过 Harbor 管理，生产环境还需要考虑安全问题……
一个好的段落通常遵循：
提出主题
↓
解释主题
↓
给出必要细节
↓
回扣主题
FEX 规范也强调一个段落只表达一个主题，并建议段落开头点题、结尾扣题。
4. 代码规范
4.1 使用 Fenced Code Block
代码段必须使用 fenced code block。
正确：
```bash
docker ps
错误：
```markdown
docker ps
对于技术文章，推荐始终标注代码语言：
```php
<?php
echo "Hello World";
```markdown
```yaml
services:
app:
image: nginx
```markdown
```bash
docker compose up -d
常用语言标识包括：
```text
bash
shell
php
javascript
typescript
html
css
sql
yaml
json
xml
nginx
dockerfile
text
4.2 命令与输出分离
如果同时展示命令和执行结果，建议明确区分。
docker ps
输出：
CONTAINER ID IMAGE STATUS
a123456789 nginx:latest Up 10 seconds
不要把大量命令和输出混在一个代码块中而不做说明。
4.3 代码前后保留空行
代码块与正文之间保持空行。
正确：
执行以下命令：
```bash
docker ps
查看当前运行中的容器。
---
## 5. 行内代码规范
技术文章中的命令、文件名、类名、方法名、配置项、变量名等，推荐使用行内代码。
例如：
```markdown
执行 `docker ps` 查看正在运行的容器。
Dockerfile 中可以使用 `COPY` 指令复制文件。
配置文件位于 `compose.yaml`。
不要使用普通文本描述容易产生歧义的技术标识：
执行 docker ps 查看容器。
推荐：
执行 `docker ps` 查看容器。
6. 列表规范
6.1 无序列表
使用 - 作为无序列表标记。
推荐：
- Docker
- Docker Compose
- Harbor
- GitHub Actions
不要混用：
- Docker
* Docker Compose
+ Harbor
6.2 有序列表
需要表达明确步骤时使用有序列表：
1. 编写 Dockerfile。
2. 构建 Docker 镜像。
3. 给镜像添加 Tag。
4. 推送到 Harbor。
5. 部署应用。
6.3 列表保持结构一致
并列项目应该尽量保持相同的语法结构。
推荐：
- 构建镜像。
- 运行容器。
- 查看日志。
- 停止容器。
不推荐：
- 构建镜像。
- 容器运行。
- 查看日志。
- 可以停止容器。
7. 表格规范
表格建议遵循 GitHub Flavored Markdown（GFM）格式。
基本格式：
| 项目 | 说明 |
| --- | --- |
| Docker | 容器运行时 |
| Harbor | 私有镜像仓库 |
| Compose | 多容器编排 |
对于技术文章，表格应该用于表达结构化信息，而不是代替普通段落。
例如比较不同工具时适合使用表格：
| 工具 | 定位 | 主要用途 |
| --- | --- | --- |
| Docker Registry | 基础 Registry | 镜像存储与分发 |
| Harbor | 企业级 Registry | 镜像管理与安全 |
| Docker Hub | 公共 Registry | 公共镜像分发 |
FEX 原规范推荐使用 GFM 表格格式。
8. 中英文混排
中英文混排时，需要特别注意空格。
8.1 英文和数字使用半角字符
推荐：
Docker 运行在 Linux 环境中。
PHP 8.3 支持 JIT。
MySQL 8.0 使用 InnoDB。
不推荐：
Docker运行在Linux环境中。
PHP８.３支持JIT。
8.2 中文与英文、数字之间增加空格
推荐：
Docker 是一种容器化技术。
PHP 8.3 是目前常用的 PHP 版本。
MySQL 8.0 提供了更多数据库能力。
不推荐：
Docker是一种容器化技术。
PHP8.3是目前常用的PHP版本。
MySQL8.0提供了更多数据库能力。
8.3 中文与英文标点之间
按照 FEX 规范，中文与英文、数字及半角符号之间适当增加空格，但中文标点与前后文字之间不增加空格。
推荐：
Docker 是一种容器化技术，常用于 Web 应用部署。
而不是：
Docker 是一种容器化技术 ，常用于 Web 应用部署 。
8.4 / 表示「或者」
当 / 表示「或者」时，两侧不加空格。
推荐：
开发/测试环境
而不是：
开发 / 测试环境
如果 / 本身是路径的一部分，也不需要添加空格：
/etc/nginx/nginx.conf
9. 中文标点规范
9.1 使用中文标点
中文正文使用中文标点：
Docker 镜像是什么？
Docker 镜像由多个 Layer 组成。
不要在中文正文中大量混用英文标点：
Docker 镜像是什么?
Docker 镜像由多个 Layer 组成.
9.2 引号
FEX 规范推荐使用直角引号：
「Docker 镜像」
而不是：
“Docker 镜像”
不过代码、配置文件、JSON 等技术语法必须遵循对应语言的语法要求。
例如：
{
"name": "docker"
}
这里不能将 JSON 的双引号替换成中文引号。
9.3 省略号
使用：
……
不要使用：
。。。
FEX 规范明确推荐中文省略号使用 ……。
10. 链接规范
Markdown 链接使用标准语法：
[Docker 官方文档](https://docs.docker.com/)
链接文字应该具有明确含义。
推荐：
参考 [Docker 官方文档](https://docs.docker.com/)。
不推荐：
点击[这里](https://docs.docker.com/)。
如果链接本身就是文章中的重要实体，可以直接使用实体名称作为链接文字。
11. 图片规范
图片使用标准 Markdown：
图片必须提供有意义的 alt 文本。
推荐：
不推荐：
如果图片用于说明架构、流程或配置，应在图片前后配合文字说明，而不是只放图片。
12. 强调规范
12.1 粗体
粗体用于强调重要概念：
Docker Image 和 Docker Container 是两个不同的概念。
也可以：
Docker 镜像必须经过安全扫描后才能进入生产环境。
不要大量使用粗体。
12.2 斜体
技术文档中不建议大量使用斜体。
如果没有明确语义需求，可以不用。
12.3 行内代码优先
对于技术名词，应优先使用代码格式，而不是粗体。
推荐：
执行 `docker build` 构建镜像。
不推荐：
执行 **docker build** 构建镜像。
13. 引用规范
引用内容使用 Markdown Blockquote：
> Docker 镜像是运行容器的基础。
多段引用：
> Docker 镜像由多个只读 Layer 组成。
>
> 容器启动后，会在镜像之上创建可写层。
引用应该用于：
官方定义。
原文引用。
特别需要强调的结论。
文档中的重要说明。
不要把普通正文全部写成引用。
14. 表达规范
Markdown 不只是格式规范，文章本身也需要保持良好的表达方式。
14.1 一个段落表达一个主题
不要在一个段落中同时解释多个概念。
例如：
Docker 镜像用于保存应用运行所需的文件和依赖，
Container 则是镜像运行后的实例，同时 Docker 还提供
Network、Volume 等能力，这些能力共同构成容器化体系。
可以拆成：
Docker 镜像用于保存应用运行所需的文件和依赖。
Container 是 Docker 镜像运行后的实例。
Docker Network 和 Volume 则分别负责网络通信和持久化数据。
这样更容易阅读。
14.2 开头点题
每个章节开头应该直接说明本章节解决什么问题。
推荐：
## Docker 镜像缓存
Docker 镜像缓存可以避免重复执行耗时的构建步骤，从而缩短镜像构建时间。
然后再解释实现方式。
14.3 删除不必要的词
推荐：
Docker 使用 Layer 保存镜像内容。
不推荐：
在实际的 Docker 使用过程中，我们可以发现 Docker 是通过 Layer
这种方式来保存镜像内容的。
技术文档应该直接表达结论。
14.4 使用主动语态
推荐：
Docker 使用 BuildKit 构建镜像。
不推荐：
镜像是由 BuildKit 被 Docker 用来进行构建的。
14.5 使用肯定表达
推荐：
生产环境应该使用 HTTPS。
不推荐：
生产环境最好不要不使用 HTTPS。
14.6 并列内容保持相同结构
推荐：
Docker Image 负责存储镜像。
Docker Container 负责运行镜像。
Docker Network 负责容器网络通信。
Docker Volume 负责数据持久化。
这种结构比每一项使用不同的表达方式更容易阅读。
15. 技术文章结构规范
对于技术博客，推荐使用以下结构：
## 问题背景
说明为什么需要这个技术。
## 基本概念
解释核心概念和工作原理。
## 核心功能
介绍主要能力。
## 实际使用
通过代码或命令说明具体使用方式。
## 常见问题
说明容易遇到的问题。
## 最佳实践
总结生产环境中的实践。
## 总结
回顾全文核心内容。
并不是每篇文章都必须完整包含这些章节。
应该根据文章主题调整。
例如 Docker 文章：
## Docker 镜像是什么
## Dockerfile 基本结构
## 镜像构建
## 构建缓存
## 多阶段构建
## 镜像安全
## CI/CD 集成
## 总结
重点是保持内容递进，而不是为了增加章节数量而拆分内容。
16. 技术博客的推荐结构
对于实际技术博客，建议遵循：
标题
↓
问题背景
↓
概念解释
↓
原理
↓
实践
↓
问题与解决方案
↓
最佳实践
↓
总结
例如：
## 为什么需要 Docker Registry
## Docker Registry 是什么
## 搭建 Docker Registry
## 镜像 Push 与 Pull
## Harbor
## Harbor 项目与权限
## CI/CD 集成
## 生产环境实践
## 总结
不要出现大量只有几句话的章节。
例如不推荐：
## 什么是 Docker
……
## 什么是镜像
……
## 什么是容器
……
## 什么是 Registry
……
如果这些内容属于同一个知识体系，可以适当合并。
17. Hugo 文章规范
如果 Markdown 用于 Hugo 技术博客，可以使用 Front Matter：
---
title: "Docker 镜像优化与安全"
slug: "docker-image-optimization-security"
date: 2026-09-15
description: "介绍 Docker 镜像优化与安全实践。"
featured: ""
categories: ["DevOps"]
tags: ["Docker", "容器安全", "镜像优化"]
keywords: ["Docker 镜像优化", "Docker 镜像安全"]
author: "Leanku"
draft: false
---
正文从 ## 开始：
## 为什么要优化 Docker 镜像
Docker 镜像不仅影响部署速度，也会影响运行环境的安全性。
这样可以避免 Front Matter 中已经存在标题，正文再次出现：
# Docker 镜像优化与安全
18. Markdown 文件检查清单
提交 Markdown 文档之前，可以按照下面的 Checklist 检查。
文件
[ ] 文件扩展名为 .md
[ ] 文件名使用小写
[ ] 多个单词使用 - 分隔
[ ] 文件使用 UTF-8 编码
标题
[ ] 章节标题从 ## 开始
[ ] ## 后存在空格
[ ] 标题末尾没有 ##
[ ] 标题与正文之间有空行
[ ] 标题层级没有明显跳跃
代码
[ ] 使用 Fenced Code Block
[ ] 代码块标注语言
[ ] 命令使用行内代码或代码块
[ ] 配置示例使用正确的语言标识
表格
[ ] 使用 GFM 表格
[ ] 表头和分隔线正确
[ ] 表格内容保持简洁
[ ] 不使用表格替代普通正文
中英文混排
[ ] 英文使用半角字符
[ ] 数字使用半角字符
[ ] 中文与英文之间适当增加空格
[ ] 中文与数字之间适当增加空格
[ ] / 表示「或者」时不加空格
[ ] 中文标点使用中文形式
[ ] 省略号使用……
内容
[ ] 一个段落只表达一个主题
[ ] 段落开头能够点题
[ ] 删除冗余表达
[ ] 尽量使用主动语态
[ ] 使用肯定表达
[ ] 并列内容保持相同结构
[ ] 避免过度拆分章节
19. 推荐的统一规范
综合 FEX Team Markdown 规范和实际技术博客写作需求，后续技术文章统一采用以下标准：
文件
├── .md
├── 小写文件名
├── - 分隔单词
└── UTF-8
标题
├── 正文章节从 ## 开始
├── ## 后有空格
├── 标题末尾不加 #
└── 标题与正文之间空一行
正文
├── 一个段落一个主题
├── 开头点题
├── 结尾扣题
├── 使用主动语态
├── 删除冗余表达
└── 并列结构保持一致
代码
├── 使用 Fenced Code Block
├── 标注语言
└── 命令、类名、文件名使用行内代码
表格
└── 使用 GFM
中英文
├── 英文使用半角字符
├── 数字使用半角字符
├── 中文与英文之间加空格
├── 中文与数字之间加空格
└── / 表示「或者」时不加空格
中文标点
├── 使用中文标点
├── 推荐使用「」作为引号
└── 省略号使用……
文章结构
├── 问题背景
├── 基本概念
├── 原理
├── 实践
├── 常见问题
├── 最佳实践
└── 总结
总结
FEX Team 的 Markdown 规范核心并不在于规定大量 Markdown 语法，而在于建立一套稳定、可读、易维护的文档格式和表达方式。其核心要求可以浓缩为：
格式统一、层级清晰、代码规范、排版整洁、表达直接。
后续技术文章按照这套规范编写时，尤其需要坚持三点：
章节从
##开始，避免无意义的标题层级。代码、表格、中英文混排统一格式。
优先保证内容结构和表达质量，而不是堆砌 Markdown 格式。
以上规则以 FEX Team 的 markdown.md 为主要参考，并结合 Hugo 技术博客场景进行了整理。FEX 原规范本身也明确说明，其目标是提高文档可读性，并建议参考 GFM 等 Markdown 规范。
参考 https://github.com/fex-team/styleguide/blob/master/markdown.md