Markdown 文档学习指南

简介

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后将其转换为结构化的 HTML。它的设计宗旨是"易于阅读，易于编写"。Markdown 广泛应用于文档编写、博客文章、README 文件、论坛帖子等。

基本语法

标题

Markdown 支持六级标题，通过在标题文本前添加不同数量的 # 符号来表示。# 的数量对应标题的级别。

最佳实践： 为了兼容性，# 符号后应始终添加一个空格，并且标题前后应留有空行。

段落

要创建段落，只需使用一个空行将一行或多行文本分隔开。Markdown 会将每个被空行分隔的文本块视为一个段落。

示例：

这是一个段落。

这是另一个段落。

最佳实践： 除非段落位于列表中，否则不要使用空格或制表符缩进段落。

换行

要在段落内创建换行（<br>），可以在行尾添加两个或更多空格，然后按回车键。

示例：

这是第一行。
这是第二行。

最佳实践： 考虑到不同 Markdown 应用程序的兼容性，建议使用行尾空格或 <br> HTML 标签来创建换行。

强调

可以使用星号（*）或下划线（_）来强调文本，使其变为粗体或斜体。

最佳实践： 为了在单词中间强调时获得更好的兼容性，建议使用星号（*）而不是下划线（_）。

引用块

通过在段落前添加 > 符号来创建引用块。

示例：

> 这是一个引用块。
> 引用块可以包含多行文本。

HTML 渲染：

列表

Markdown 支持有序列表和无序列表。

无序列表

使用星号（*）、加号（+）或连字符（-）作为列表项标记。

示例：

* 列表项一
* 列表项二
  * 嵌套列表项

HTML 渲染：

• 列表项一
• 列表项二
  • 嵌套列表项

有序列表

使用数字后跟一个句点（.）来创建有序列表。

示例：

1. 第一个列表项
2. 第二个列表项
   1. 嵌套有序列表项

HTML 渲染：

1. 第一个列表项
2. 第二个列表项
   1. 嵌套有序列表项

代码块

行内代码

使用反引号（`）将代码片段包裹起来，创建行内代码。

示例：

这是一个 `console.log("Hello World!");` 示例。

代码块

使用三个反引号（```）包裹多行代码，并可在第一个反引号后指定语言进行语法高亮。

示例：

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

HTML 渲染：

def hello_world():
    print("Hello, Markdown!")

分隔线

使用三个或更多的星号（***）、连字符（---）或下划线（___）来创建水平分隔线。

示例：

---

***

___

HTML 渲染：

链接

行内链接

使用 [链接文本](链接地址) 格式创建行内链接。

示例：

访问 [Markdown Guide](https://www.markdownguide.org/) 学习更多。

HTML 渲染：

访问 Markdown Guide 学习更多。

引用式链接

使用 [链接文本][引用标签]，然后在文档的任何地方定义 [引用标签]: 链接地址。

示例：

访问 [Google][1] 或 [GitHub][github_link]。

[1]: https://www.google.com
[github_link]: https://www.github.com

图片

图片语法类似于链接，但在前面多了一个感叹号（!）。

示例：

![替代文本](图片地址 "可选标题")

![Markdown Logo](https://www.markdownguide.org/assets/images/markdown-guide-logo.svg "Markdown Logo")

表格

使用连字符（-）创建表头分隔线，使用竖线（|）分隔列。可以通过在表头分隔线中添加冒号（:）来设置对齐方式。

示例：

| 表头一 | 表头二 | 表头三 |
| :----- | :----: | -----: |
| 左对齐 | 居中   | 右对齐 |
| 内容 A | 内容 B | 内容 C |

HTML 渲染：

最佳实践： 为了提高可读性，可以在表格的每一列前后都加上竖线。

扩展语法 (GitHub Flavored Markdown)

许多 Markdown 处理器支持扩展语法，其中 GitHub Flavored Markdown (GFM) 是最常用的一种。GFM 在基本语法之上增加了许多有用的功能。

删除线

使用两个波浪线（~~）包裹文本来创建删除线。

示例：

~~这是一段被删除的文本~~。

HTML 渲染：

这是一段被删除的文本。

任务列表

使用 - [ ] 或 - [x] 来创建任务列表。

示例：

- [x] 完成任务一
- [ ] 完成任务二
- [ ] 完成任务三

HTML 渲染：

• 完成任务一
• 完成任务二
• 完成任务三

自动链接

GFM 会自动将 URL 转换为链接。

示例：

访问 https://www.example.com。

HTML 渲染：

访问 https://www.example.com。

表情符号（Emoji）

GFM 支持通过 :<emoji_name>: 语法来插入表情符号。

示例：

:smile: :+1: :sparkles:

HTML 渲染：

😄 👍 ✨

Markdown 最佳实践

1. 保持一致性： 在整个文档中保持 Markdown 语法的风格一致，例如，选择使用 * 还是 _ 来表示斜体，并坚持使用。
2. 使用空行： 在块级元素（如标题、段落、列表、代码块）之间使用空行，以提高可读性。
3. 避免过度使用 HTML： 尽管 Markdown 支持嵌入 HTML，但应尽量使用 Markdown 语法，以保持文档的简洁性和可移植性。
4. 预览文档： 在发布前，务必使用 Markdown 预览工具检查渲染效果，确保符合预期。
5. 为图片添加替代文本： 为图片提供有意义的替代文本，这对于可访问性和 SEO 都很重要。
6. 使用有意义的文件名： 为 Markdown 文件选择清晰、描述性的文件名。

常用 Markdown 编辑器和工具

• Visual Studio Code: 强大的代码编辑器，内置 Markdown 预览功能，有丰富的 Markdown 扩展。
• Typora: 一款所见即所得的 Markdown 编辑器，提供流畅的写作体验。
• Obsidian / Notion / Joplin: 笔记应用，广泛支持 Markdown，并提供知识管理功能。
• Dillinger.io / StackEdit.io: 在线 Markdown 编辑器，支持实时预览和多种导出格式。

总结

Markdown 是一种简单而强大的写作工具。掌握其基本语法和最佳实践，可以大大提高文档编写的效率和质量。希望这份指南能帮助您快速入门并熟练使用 Markdown。

MD2Anki 如何帮助您学习

使用 MD2Anki，您可以轻松将 Markdown 学习笔记转换为 Anki 记忆卡片！只需：

1. 以 Markdown 格式编写您的笔记
2. 将 .md 文件上传到 MD2Anki
3. 下载生成的 .apkg 文件
4. 导入 Anki 并开始学习！

这使得从技术文档、学习指南或任何用 Markdown 编写的结构化内容创建记忆卡片变得非常简单。

参考文献

1. Markdown Guide - Basic Syntax
2. Markdown Guide - Extended Syntax