技术作家和文档工程师的终极Markdown备忘单

孩子们渴望了解Markdown备忘单。

这是我从上周末回家度过中期休息的最小的学生那里得知的。

离开了将近两个月，他们理所当然地积累了大量问题。

在为期三个小时的课程中，我们讨论了比我记得的还要多的主题，但我从未想过我们会比其他任何事情都花更多时间来讨论Markdown。

我很享受教课的乐趣，我也想在这里为有抱负的技术作家、文档工程师或那些无法理解为什么GitHub坚持要求您在每个存储库中包含README文件的人做同样的事情。 Markdown是一种简单的标记语言，允许您编写纯文本语法并将其转换为视觉格式化的HTML。

这是一个Markdown文件的样子。左边显示语法，右边是输出。

它的创建者希望有一个易于阅读的东西，这解释了它在制作文档中的流行程度。

对于技术作家，尤其是没有工程背景的作家，这特别吸引人。使用Markdown，他们可以参与项目而无需学习使用的编程语言。

如何设置Markdown环境

Markdown易于使用，因为它是纯文本，所以大多数文本编辑器都可以使用。为了使文件读取为Markdown，您需要以.md扩展名保存它。

然而，与其使用任何旧文本编辑器，最好使用专门的Markdown编辑器。作为一种编码方法，我始终推荐使用Visual Studio Code来编辑Markdown。

无论您是否打算从事工程领域，熟悉尽可能多的开发工具都能让您更好地使用它们。

VS Code扩展Markdown All in One (opens new window)应该会为您提供创建和编辑Markdown文件所需的所有工具，从键盘快捷键到全面的导出选项。

该扩展还支持其他流行的Markdown规范和系统，包括YAML、GitHub Flavored Markdown、LaTeX和KaTeX。

如果您更喜欢轻量级的开始，我的最爱在线Markdown编辑器是Dillinger (opens new window)和StackEdit (opens new window)。在本文中，我将使用后者进行演示（代码在左侧，输出/预览在右侧）。

让我们开始吧。

如何编写Markdown #

作为初学者，您不需要了解Markdown的所有内容，所以我们只需使用Markdown的常用部分。这里将覆盖您最有可能遇到的内容，分为以下几个部分：

标题
段落
正文
列表
代码
图像
链接
引用
转义
视频

1. 标题 #

要编写标题，您需要为每个级别放置相应数量的井号 — H1在#后面，H2在##后面，H3在###后面，依此类推。

注意： 您必须在最后一个#后面加一个空格，否则将无法正常工作。

例如，标题为“第一标题”的H1将是# 第一标题，而标题为“第二标题”的H2将是## 第二标题。

从H4开始，视觉重量会显著减弱，因此您应尽量保持在H1和H3之间。

2. 段落 #

按一次Enter键会创建一个换行。要创建新段落，请按两次Enter键，这样在两个段落之间留下空白。

第二次按Enter键后，两段之间的间隔会保持不变，无论您在其中添加多少空间。 ## 3. 正文

基本正文格式的语法如下：

粗体： 用 ** 或 __ 包围文本，例如 这段文字将在 **文本中加粗**。
斜体： 用 * 或 _ 包围文本，例如 这段文字将在 *文本中倾斜*。
高亮： 用 == 包围文本，例如 这段文字将在 ==文本中高亮==。
删除线： 用 ~~ 包围文本，例如 这段文字将在 ~~文本中加删除线~~。

下划线通常用于突出显示链接，因此在Markdown中无法像上面的示例那样对文本进行下划线。

为了避免混淆，建议您永远不要在Markdown中手动对文本进行下划线。如果必须这样做，可以通过在目标文本中包围<ins> HTML 标签 (opens new window)，例如 这段文字将在 <ins>文本中加下划线</ins>。

您还可以嵌套格式化，只要按正确的顺序关闭标签即可。列表

编写列表需要在文本前面加上适当的符号，后跟一个空格，并在下一个项目之前换行：

对于有序列表，请使用从1开始顺序递增的数字。在数字后面加上一个句点，然后是一个空格，然后是项目，最后换行到列表中的下一个项目。例如：

1. 第一 2. 第二 3. 第三

对于无序列表，只需使用-后跟一个空格，然后是项目，并在下一个项目之前换行，例如：

- 第一项 - 第二项 - 第三项

您还可以添加待办事项您可以在Markdown中包含代码的两种方式：内联或作为代码块。

要添加内联代码，请将片段括起来`, 例如The command `print (“Giraffe”)` will print the word “Giraffe” to the console.

要添加一个独立的代码块，您可以：

高亮代码片段并按Tab键。
将代码片段括起来```或~~~。在这种方法中，您可以使用超过三个反引号或波浪线，只要开始和结束标签的数量相同即可。
在行首添加四个空格。使用反引号或波浪号时，您可以通过指定用于编写代码的语言来添加语法高亮显示。

只需在第一组反引号或波浪号后面写出语言的名称，例如 ```python。

您可以在Markdown中指定的一些流行语言的代码包括：

Python: python
Javascript: js
HTML, XHTML: html
CSS: css
C: c
C++: cpp
C#: csharp
Go: go
SQL: sql
YAML: yaml
JSON: json
SASS: sass
SCSS: scss
Java: java
Ruby: ruby
PHP: php
R: r

6. 链接 #

在Markdown中编写链接，首先用方括号括起锚文本，然后用括号括起目标URL，即 [锚文本](example.com)。

对于要重复使用的目标URL，您可以使用任何您喜欢的标签，只要在代码中指定其值即可，例如：

`这个 [链接][x] 和这个 [链接][x] 指向相同的目的地。 [x]: [h 请注意，此处的语法使用方括号来表示目标URL和锚文本。

如果您希望网址或电子邮件地址显示为可点击的文本，同时保持可点击性，请将其放在尖括号内，即<[email protected]>或<https://example.com>。

**注意：**在处理外部URL时，包括HTTPS部分以指定地址在互联网上。

7. 图片 #

与处理代码时一样，添加图片需要直接链接到它们。

在Markdown中添加图片时，您需要以!开头，然后是方括号内的alt文本，然后是路径和鼠标悬停文本，即：

![alt text](/location/image.jpg “Mouse hover text”)

要使图像作为链接可点击，请将原始代码放在方括号内，并将目标地址附加到结构的末尾内的括号内，即：

[![alt text](/location/image.jpg “Mouse hover text”)](https://example.com) ## 8. 参考资料

Markdown允许您在文档中使用脚注和块引用来制作引用。

脚注遵循与上述重复链接相似的格式，创建一个标签用于引用（推荐数字），并在代码中指定标签所指的内容，即：

示例语句。[^1] [^1]: 相应的脚注。

要创建一个块引用，在段落开头添加一个>。

9. 转义 #

在任何激活格式的符号前面放置一个反斜杠（\）以防止其激活格式。

例如，\*斜体*将以未格式化形式显示，但反斜杠不会出现在输出中。

反斜杠会立即取消其后的符号，因此您需要根据需要为每个符号提供一个反斜杠。

例如，\**示例**将使文本变为斜体，因为第二个星号仍然有效。在这种情况下，您需要使用\*\*示例**。

10. 视频 #

如何向Markdown文件添加视频取决于视频的位置。

如果视频存储在您的设备上或者您知道视频文件的路径，您可以直接链接到它。

为此，您可以使用HTML的<video>标签 (opens new window)，例如 <video src="path/to/video.mp4" width="1280" height="720" controls></video>。

这种方法不适用于像YouTube这样的网站，因为您无法直接访问文件。

在这些情况下，您需要获取嵌入链接并将其添加到您的Markdown文件中。

例如，在YouTube上，这是获取链接的方法：

打开您想在Markdown中包含的视频
点击“分享”
点击“嵌入”
复制嵌入链接。它应该以<iframe开头。

当您获得链接后，将其复制到您的Markdown文档中，它将显示为输出中的视频。

结论 #

恭喜！您刚刚迈出了Markdown世界的第一步。

通过练习，无论是做笔记、撰写博客文章还是为专业领域做出贡献，来提高您的Markdown技能。项目文档。

祝写作顺利！