第3章：Markdown 文档基础

3.1 Markdown 文档命名与后缀

文档命名规范

Markdown文档的命名应该遵循以下规范：

• 简洁明了：文件名应该能够清晰地反映文档的内容
• 使用小写字母：避免使用大写字母，保持一致性
• 使用连字符或下划线：单词之间使用连字符（-）或下划线（_）分隔，避免使用空格
• 避免特殊字符：不要使用特殊字符，如 !、@、# 等

示例：

• 好的命名：markdown-basics.md、learning-notes.md、project-plan.md
• 不好的命名：Markdown Basics.md、学习笔记.md、project plan.md

文件后缀

Markdown文档的标准文件后缀是 .md，也可以使用 .markdown。在大多数情况下，.md 是更常用的后缀。

示例：

• document.md
• readme.md
• guide.markdown

3.2 文档结构概述

Markdown文档的基本结构通常包括以下几个部分：

1. 标题

标题是文档的骨架，用于组织文档结构。Markdown支持六级标题，使用 # 符号表示，# 的数量代表标题级别。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

2. 正文

正文是文档的主要内容，包括普通文本、段落、换行等。

3. 列表

列表用于组织项目，包括无序列表和有序列表。

• 无序列表：使用 -、* 或 + 符号
• 有序列表：使用数字加 . 符号

4. 引用

引用用于突出显示引用的内容，使用 > 符号。

> 这是一段引用文本

5. 链接

链接用于跳转到其他页面或资源，使用 [链接文本](链接地址) 语法。

[Markdown官网](https://daringfireball.net/projects/markdown/)

6. 图片

图片用于在文档中插入图像，使用 ![图片alt文本](图片地址) 语法。

![测试图片](https://via.placeholder.com/150)

7. 代码

代码用于显示代码片段，包括行内代码和代码块。

• 行内代码：使用反引号 ` 包裹
• 代码块：使用三个反引号 ``` 包裹

8. 表格

表格用于展示结构化数据，使用 | 分隔列，使用 --- 分隔表头和表体。

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |

9. 分割线

分割线用于分隔不同的内容部分，使用 ---、*** 或 ___。

---

3.3 换行与分段

换行

在Markdown中，要实现换行，你需要在一行的末尾添加两个或更多的空格，然后按回车键。

示例：

这是第一行  
这是第二行

渲染效果： 这是第一行
这是第二行

分段

在Markdown中，要创建一个新段落，你需要在两段之间添加一个空行。

示例：

这是第一个段落。

这是第二个段落。

渲染效果： 这是第一个段落。

这是第二个段落。

新手易错点

• 错误：在一行末尾不添加空格就直接换行，结果文本会显示在同一行。
• 错误：在段落之间不添加空行，结果文本会显示为一个段落。

3.4 空格与缩进

空格

在Markdown中，空格的使用主要有以下几种情况：

• 行尾空格：用于实现换行
• 标题空格：# 符号与标题文本之间需要添加一个空格
• 列表空格：列表符号与列表内容之间需要添加一个空格
• 引用空格：> 符号与引用内容之间需要添加一个空格

示例：

# 标题（正确，#后有空格）

- 列表项（正确，-后有空格）

> 引用文本（正确，>后有空格）

缩进

在Markdown中，缩进主要用于以下情况：

• 列表嵌套：嵌套列表需要缩进4个空格或1个制表符
• 代码块：代码块中的代码通常需要缩进
• 引用嵌套：嵌套引用需要添加额外的 > 符号

示例：

- 一级列表项
    - 二级列表项（缩进4个空格）
        - 三级列表项（缩进8个空格）

> 一级引用
>> 二级引用（添加额外的>）

优化排版整洁度

• 保持一致的缩进：使用空格或制表符，但不要混合使用
• 适当使用空行：在不同的内容块之间添加空行，提高可读性
• 避免多余的空格：不要在行首或行尾添加不必要的空格
• 使用合理的标题层级：不要跳过标题层级，保持文档结构清晰

3.5 实操案例：创建第一个完整Markdown文档

目标

创建一个包含标题、正文、换行、分段、列表、引用、链接和图片的完整Markdown文档。

步骤

1. 打开编辑器：打开你的Markdown编辑器

2. 创建文档：新建一个文件，保存为 complete-document.md

3. 输入内容：在文档中输入以下内容：

# 我的完整Markdown文档

## 文档介绍

这是我的第一个完整Markdown文档，包含了各种Markdown元素。

## 基本元素

### 文本样式

**这是加粗文本**
*这是斜体文本*
~~这是删除线文本~~

### 列表

#### 无序列表
- 项目1
- 项目2
    - 子项目2.1
    - 子项目2.2
- 项目3

#### 有序列表
1. 步骤1
2. 步骤2
3. 步骤3
    1. 子步骤3.1
    2. 子步骤3.2

### 引用

> 这是一段引用文本
> 
> 引用可以有多行

### 链接与图片

[Markdown官网](https://daringfireball.net/projects/markdown/)

![测试图片](https://via.placeholder.com/200)

### 分割线

---

## 总结

通过本案例，我学习了如何创建一个完整的Markdown文档，包括：
- 标题的使用
- 文本样式的应用
- 列表的创建和嵌套
- 引用的使用
- 链接和图片的添加
- 分割线的使用
- 换行和分段的技巧

这是文档的结尾部分。

4. 查看预览：在编辑器中查看预览效果，确保所有元素都能正确渲染

5. 保存文档：将文档保存为 complete-document.md

效果预览

通过上面的操作，你应该可以看到一个格式良好的Markdown文档，包含了各种Markdown元素，结构清晰，排版整洁。

练习建议

• 尝试修改文档内容，添加更多的Markdown元素
• 练习使用不同的标题层级
• 尝试创建更复杂的列表嵌套
• 练习添加更多的链接和图片
• 尝试使用代码块和表格

通过这个实操案例，你应该已经掌握了Markdown文档的基本结构和元素的使用方法。