编程马·菜鸟教程

Appearance

第16章：Markdown 进阶提升与规范 ​

16.1 Markdown 代码规范（命名规范、排版规范、语法规范） ​

命名规范 ​

文件名命名规范 ​

  1. 使用小写字母：文件名应使用小写字母，避免使用大写字母
  2. 使用连字符：单词之间使用连字符 - 分隔，避免使用下划线或空格
  3. 使用描述性名称：文件名应能清晰描述文件内容
  4. 使用 .md 后缀：Markdown 文件应使用 .md 后缀

示例：

  • 正确：getting-started.md、advanced-techniques.md
  • 错误：GettingStarted.md、advanced_techniques.md、advanced techniques.md

标题命名规范 ​

  1. 使用简洁明了的标题：标题应能准确反映章节内容
  2. 保持一致的风格：标题应使用一致的大小写风格（如首字母大写）
  3. 避免使用特殊字符：标题中应避免使用特殊字符
  4. 保持适当长度：标题不宜过长，一般不超过 50 个字符

示例：

  • 正确：Markdown 基础语法、高级排版技巧
  • 错误：Markdown 基础语法！、这是一个非常长的标题，描述了 Markdown 的基础语法

排版规范 ​

空白字符规范 ​

  1. 行尾空格：行尾不应有多余的空格
  2. 空行使用：
    • 标题前后应各有一个空行
    • 段落之间应有一个空行
    • 列表、引用、代码块前后应各有一个空行
  3. 缩进规范：
    • 列表嵌套应使用 2 或 4 个空格缩进
    • 引用嵌套应使用 > 缩进
    • 代码块应保持原始缩进

示例：

markdown
# 标题

段落内容。

- 列表项1
  - 子列表项

> 引用内容
> > 嵌套引用

```python
def hello():
    print("Hello, Markdown!")

#### 标点符号规范
1. **使用中文标点**：中文内容应使用中文标点符号
2. **使用英文标点**：英文内容应使用英文标点符号
3. **避免混用**：不要在同一段落中混用中英文标点
4. **空格使用**：
   - 中文与英文之间应添加空格
   - 中文与数字之间应添加空格
   - 英文标点后应添加空格

**示例**：
- 正确：`Markdown 是一种轻量级标记语言。`
- 错误：`Markdown是一种轻量级标记语言。`
- 正确：`我有 3 个 Markdown 文件。`
- 错误：`我有3个Markdown文件。`

### 语法规范

#### 标题语法规范
1. **使用 # 符号**：标题应使用 `#` 符号，而不是下划线或其他符号
2. **空格要求**：`#` 符号与标题文本之间应有一个空格
3. **层级使用**：标题层级应从一级开始，逐渐递增，不要跳跃
4. **数量限制**：一级标题通常只使用一次，作为文档标题

**示例**：
- 正确：`# 一级标题`、`## 二级标题`
- 错误：`#一级标题`、`### 三级标题`（直接使用三级标题）

#### 列表语法规范
1. **符号选择**：无序列表应使用 `-`、`*` 或 `+`，选择一种并保持一致
2. **空格要求**：列表符号与文本之间应有一个空格
3. **嵌套规范**：嵌套列表应正确缩进
4. **空行使用**：列表项之间可以添加空行以提高可读性

**示例**：
- 正确：
  ```markdown
  - 列表项1
  - 列表项2
    - 子列表项
  • 错误：
    markdown
    -列表项1
* 列表项2
+ 列表项3

代码块语法规范 ​

  1. 使用反引号：代码块应使用三个反引号 ` 包裹
  2. 指定语言：代码块应指定编程语言以获得语法高亮
  3. 保持格式：代码块应保持原始代码格式和缩进
  4. 空行使用：代码块前后应各有一个空行

示例：

  • 正确：
    markdown
    ```python
def hello():
    print("Hello, Markdown!")
  • 错误：
    markdown
    def hello(): print("Hello, Markdown!")

16.2 排版技巧（提升文档可读性，新手必备） ​

合理使用标题、分割线，梳理文档结构 ​

标题使用技巧 ​

  1. 层次分明：使用不同层级的标题来组织文档结构
  2. 标题间距：标题前后应各有一个空行，增强视觉分隔
  3. 标题长度：标题应简洁明了，避免过长
  4. 标题一致性：保持标题风格一致，如使用相同的大小写规则

示例：

markdown
# 文档标题

## 第一章 简介

### 1.1 什么是 Markdown？

### 1.2 为什么使用 Markdown？

## 第二章 基础语法

### 2.1 标题

### 2.2 文本样式

分割线使用技巧 ​

  1. 使用场景：分割线用于分隔不同主题的内容
  2. 使用规范：
    • 分割线应使用 ---、*** 或 ___，选择一种并保持一致
    • 分割线前后应各有一个空行
    • 避免过度使用分割线，一般用于 major 主题的分隔
  3. 视觉效果：分割线应与文档风格一致

示例：

markdown
## 第一部分 基础

内容...

---

## 第二部分 进阶

内容...

避免过度使用样式，保持排版简洁 ​

文本样式使用技巧 ​

  1. 加粗使用：仅用于重点内容，如关键术语、重要概念
  2. 斜体使用：用于强调、补充说明或外国词汇
  3. 删除线使用：用于表示废弃内容或修改痕迹
  4. 下划线使用：谨慎使用，一般用于链接或特殊强调

示例：

  • 正确：**重要**：请仔细阅读本指南。
  • 错误：**这是**一个**非常**重要的**内容**。

代码样式使用技巧 ​

  1. 行内代码：用于短代码片段、变量名或命令
  2. 代码块：用于长代码片段、完整函数或类
  3. 语法高亮：始终为代码块指定编程语言以获得语法高亮
  4. 代码注释：在代码块中添加必要的注释以提高可读性

示例：

  • 行内代码：使用 npm install 安装依赖
  • 代码块：
    javascript
    // 计算圆的面积
function calculateArea(radius) {
    return Math.PI * radius * radius;
}

图文结合，重点内容突出 ​

图片使用技巧 ​

  1. 图片选择：选择与内容相关、清晰的图片
  2. 图片大小：调整图片大小以适应文档布局
  3. 图片说明：为图片添加 alt 文本，描述图片内容
  4. 图片位置：将图片放在相关文本附近
  5. 图片版权：确保使用的图片有适当的版权许可

示例：

markdown
## Markdown 编辑器推荐

以下是几款流行的 Markdown 编辑器：

![Typora 界面](https://typora.io/img/screenshot/mac-1.png)

*Typora：一款支持实时预览的 Markdown 编辑器*

![Obsidian 界面](https://obsidian.md/images/screenshot.png)

*Obsidian：一款支持双向链接的 Markdown 笔记工具*

重点内容突出技巧 ​

  1. 使用引用：将重要内容放在引用块中
  2. 使用列表：使用列表突出多项内容
  3. 使用表格：使用表格展示结构化数据
  4. 使用强调：使用加粗、斜体等样式强调重点
  5. 使用分割线：使用分割线分隔重要内容

示例：

markdown
> **注意**：在使用 Markdown 时，应遵循以下最佳实践：
>
> - 保持语法简洁
> - 避免过度使用样式
> - 确保文档结构清晰
> - 使用一致的格式

---

## 最佳实践总结

| 类别 | 建议 |
|-----|-----|
| 标题 | 使用层次分明的标题结构 |
| 列表 | 使用一致的列表符号和缩进 |
| 代码 | 指定编程语言以获得语法高亮 |
| 图片 | 添加 alt 文本并确保版权合规 |

16.3 小众语法与高级技巧（可选，进阶学习） ​

脚注 ​

脚注用于添加补充说明，不影响正文排版。

语法：

markdown
这是一个脚注示例[^1]。

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

使用场景：

  • 文档注释
  • 引用说明
  • 补充知识点

目录生成 ​

部分 Markdown 编辑器支持自动生成目录。

语法：

markdown
[TOC]

使用场景：

  • 长文档导航
  • 快速跳转到指定章节

表情符号 ​

表情符号可以丰富文档氛围。

语法：

markdown
:smile: :warning: :heavy_check_mark:

常用表情：

  • :smile: 😊
  • :warning: ⚠️
  • :heavy_check_mark: ✅
  • :x: ❌
  • :information_source: ℹ️

数学公式 ​

数学公式用于学术、技术文档。

行内公式：

markdown
$E = mc^2$

块级公式：

markdown
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

常用公式：

  • 加减乘除：$a + b = c$
  • 平方：$x^2$
  • 分数：$\frac{a}{b}$
  • 积分：$\int f(x) dx$

任务列表 ​

任务列表用于待办事项、实操步骤核对。

语法：

markdown
- [x] 已完成任务
- [ ] 未完成任务

使用场景：

  • 待办清单
  • 项目计划
  • 学习进度跟踪

定义列表 ​

定义列表用于术语解释。

语法：

markdown
术语
: 解释

Markdown
: 一种轻量级标记语言

使用场景：

  • 术语表
  • 词汇解释
  • 概念说明

表格高级技巧 ​

表格对齐 ​

语法：

markdown
| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| 内容 | 内容 | 内容 |

表格合并 ​

语法：

markdown
| 姓名 | 科目 | 成绩 |
|-----|-----|-----|
| 张三 | 数学 | 90 |
|     | 语文 | 85 |
| 李四 | 数学 | 88 |
|     | 语文 | 92 |

16.4 Markdown 与网站结合（适配网站搭建，如Hexo、VuePress） ​

Hexo ​

Hexo 是一款基于 Node.js 的静态博客框架，支持 Markdown 写作。

安装与配置 ​

  1. 安装 Hexo：

    bash
    npm install -g hexo-cli

  2. 初始化项目：

    bash
    hexo init blog
cd blog
npm install

  3. 创建文章：

    bash
    hexo new "文章标题"

  4. 编写 Markdown：在 source/_posts 目录中编辑 Markdown 文件

  5. 生成静态文件：

    bash
    hexo generate

  6. 部署网站：

    bash
    hexo deploy

配置技巧 ​

  1. 主题配置：修改 _config.yml 文件中的主题设置
  2. 插件安装：安装 Markdown 相关插件，如 hexo-renderer-markdown-it
  3. 自定义样式：在主题目录中添加自定义 CSS

VuePress ​

VuePress 是一款基于 Vue 的静态网站生成器，专为技术文档设计。

安装与配置 ​

  1. 安装 VuePress：

    bash
    npm install -g vuepress

  2. 初始化项目：

    bash
    mkdir docs
cd docs
npm init -y

  3. 创建文档：在 docs 目录中创建 Markdown 文件

  4. 配置导航：在 docs/.vuepress/config.js 中配置导航和侧边栏

  5. 构建网站：

    bash
    vuepress build

  6. 部署网站：将 docs/.vuepress/dist 目录部署到服务器

配置技巧 ​

  1. 侧边栏配置：在 config.js 中配置侧边栏导航
  2. 主题配置：修改 config.js 中的主题设置
  3. 插件使用：安装并配置 Markdown 相关插件
  4. 自定义组件：创建自定义 Vue 组件增强 Markdown 功能

GitHub Pages ​

GitHub Pages 是 GitHub 提供的静态网站托管服务，支持 Markdown。

部署步骤 ​

  1. 创建仓库：在 GitHub 上创建一个新仓库
  2. 启用 GitHub Pages：在仓库设置中启用 GitHub Pages
  3. 创建 README.md：在仓库根目录创建 README.md 文件
  4. 推送更改：将 Markdown 文件推送到 GitHub
  5. 访问网站：通过 username.github.io/repository 访问网站

配置技巧 ​

  1. 使用 Jekyll：GitHub Pages 默认使用 Jekyll 构建，可以配置 _config.yml
  2. 使用主题：选择合适的 Jekyll 主题
  3. 自定义域名：配置自定义域名

通过以上进阶提升与规范，你可以编写更加专业、美观的 Markdown 文档，并将其与网站结合，实现更广泛的应用。

© 2026 编程马·菜鸟教程 版权所有

基于 VitePress 构建