为世界所有美好而战

渺万里层云，千山暮雪，只影向谁去？#

Markdown#

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。由约翰·格鲁伯在2004 （英语：John Gruber）创建。其设计理念是”易读易写”，让人们能够使用简单的纯文本格式来编写结构化文档。其编写的文档可以导出 HTML 、Word、图像、PDF、Epub 等多种格式的文档。文档格式为 .md, .markdown。

1. 特点

• 简洁性：使用直观的符号来表示格式，比如用 # 表示标题，用 * 表示列表项。这些符号在视觉上就能传达其含义，即使不进行渲染也具有良好的可读性。

• 可读性：即使是纯文本形式的 Markdown 文档，也能清晰地展现文档的结构和层次。读者无需专门的软件就能理解内容的组织方式。

• 便携性：Markdown 文件是纯文本格式，可以在任何文本编辑器中打开和编辑，不依赖特定的软件或操作系统。

• 转换性：可以轻松转换为 HTML、PDF、Word 文档等多种格式，满足不同的发布需求。

2. Markdown 的应用场景

• 技术文档编写

  • 在软件开发领域，Markdown 已成为技术文档的标准格式。它特别适合：

  • API 文档：清晰的标题层次和代码块展示，让 API 说明既专业又易读。许多 API 文档生成工具（如 Swagger）都支持 Markdown 格式的描述。

  • 项目说明：从安装指南到使用手册，Markdown 能够有效组织技术信息。代码示例、配置文件、命令行操作都能得到恰当的展示。

  • 开发规范：团队的编码规范、设计准则、工作流程等都可以用 Markdown 编写，方便团队成员查阅和更新。

• 博客文章创作

  • 现代的博客平台和静态网站生成器大多支持 Markdown：
  • 内容管理：博主可以专注于内容创作，而不必担心复杂的 HTML 编码。文章的格式化通过简单的标记即可完成。
  • 平台迁移：使用 Markdown 编写的文章可以轻松在不同平台间迁移，不会因为平台特有的格式而被锁定。
  • 离线编写：可以在任何文本编辑器中离线编写文章，然后批量发布，提高了写作的灵活性。

• GitHub README 文件

  • GitHub 平台广泛使用 Markdown，特别是项目的 README 文件：
  • 项目介绍：清晰展示项目的目的、特性、使用方法等关键信息。
  • 安装指南：通过代码块和列表，提供详细的安装和配置步骤。
  • 贡献指南：说明如何参与项目开发，包括代码规范、提交流程等。
  • 问题跟踪：在 Issues 和 Pull Requests 中，开发者使用 Markdown 来描述问题、提供解决方案。

标题（Heading）#

用 1-6 个 # 表示 1~6 级标题，# 与文字之间要有空格。

1
# 一级标题
2
## 二级标题
3
### 三级标题
4
#### 四级标题
5
##### 五级标题
6
###### 六级标题

TIP

实际写作中，一般不会用到太多层级，常用到 H3 就已经足够细分结构。

强调：粗体、斜体、删除线#

• 粗体：**粗体** 或 __粗体__
• 斜体：*斜体* 或 _斜体_
• 粗体 + 斜体：***粗体斜体***
• 删除线：~~删除线~~（GFM 扩展，并非所有平台都支持） 示例：

1
这是一段普通文本。
2
这是 **粗体**，这是 *斜体*，这是 ~~删除线~~。
3
这是 ***粗体斜体***。

分割线#

用三个或以上的 - 或 *（建议在单独一行）可以生成分割线：

1
---

链接与图片#

• 链接：[显示文本](URL)
• 图片：在链接前面加 !：![替代文字](图片URL) 示例：

1
[访问示例站点](https://example.com)
2
![风景图](https://example.com/path/to/image.png)

TIP

替代文字 在图片无法显示时会展示，对无障碍访问也很重要。

引用（Blockquote）#

• 用 > 加空格开头表示引用，可以嵌套使用多个 >：

1
> 这是一段引用。
2
> > 可以嵌套引用。
3
> > > 嵌套再嵌套。

• 用

1
``

包裹，可以指定引用的来源：
eg:
你好

列表#

• 无序列表：- 或 *，后接空格：
• 有序列表：数字加点，后接空格：
• 嵌套列表：在下一行缩进即可（通常 2~4 个空格）。 示例：

1
- 苹果
2
- 橙子
3
- 香蕉
4
1. 打开文件
5
2. 编辑内容
6
3. 保存

嵌套示例：

1
- 项目 A
2
  - 子项 1
3
  - 子项 2
4
    - 子子项

代码：行内与代码块#

• 行内代码：用反引号 ` 包裹：
• 代码块：用三个反引号 ``` 包裹，可指定语言（如 javascript）进行语法高亮（GFM 扩展）。 示例：

1
这是一段普通文字，其中 `console.log("Hello")` 是行内代码。

1
function hello() {
2
  console.log("Hello, Markdown!");
3
}

CAUTION

上面示例为了展示，把 前后用缩进隔开；实际写作时，` ` 前后不要缩进，并且顶格写。

表格（扩展，部分平台支持）#

• 表头行用 | 分隔列。
• 第二行用 |---|---| 形式，冒号可控制对齐方式（左、中、右）。 示例：

1
| 姓名   | 年龄 | 城市   |
2
| ------ | ---- | ------ |
3
| 张三   | 22   | 北京   |
4
| 李四   | 25   | 上海   |

对齐方式：

1
| 左对齐   | 居中对齐 | 右对齐 |
2
| :------- | :------: | -----: |
3
| 文本     | 文本     | 文本  |

键盘输入#

使用 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> 重启电脑

eg:
使用 Ctrl+Alt+Del 重启电脑

任务列表（待办，GFM 扩展）#

用 - [ ] 表示未完成，- [x] 表示已完成（[] 前后要有空格）。

1
- [x] 学习标题语法
2
- [x] 学习链接与图片
3
- [ ] 学习表格与任务列表

脚注（扩展，部分平台支持）#

在正文中用 [^n] 标注脚注编号，然后在文末给出解释：

1
这里有一句需要说明[^1]。
2
[^1]: 这是脚注的内容。

HTML 标签：在 Markdown 中使用（安全范围内的）#

在大多数 Markdown 实现中，可以直接使用 HTML 标签（如 <span>、<u> 等），用于实现 Markdown 原生语法不支持的效果，比如颜色和下划线：

1
这是 <span style="color:red">红色文字</span>。
2
这是 <u>下划线文字</u>。

WARNING

只用简单标签（如 <span>、<u>、<i>、<br>）。 不要使用复杂脚本/样式，避免安全风险。

文章插入锚点#

// 插确定id锚点 <a id="one">one</a>
//id锚点 [one](#one)

隐藏文字写法#

:spoiler[**这里看不见**]

eg: 这里看不见

额外内容#

• 文字下划线跟随

1
.one {
2
        color: #000;
3
        font-weight: bold;
4
        background-image: linear-gradient(to right,green,yellow) ;
5
        background-size: 0px 2px;
6
        background-repeat: no-repeat;
7
        background-position: left bottom;
8
    }
9
.one:hover {
10
        background-size: 100% 2px;
11
        transition:2s;
12
    }

• Github导航块 ::github{repo="qitinyu/yuqi"}

eg:

高亮提示#

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

了解更多？#