如何编写 Markdown 并准备你的环境（使用 VSCode）

大家好，
我是Mandai，Wild团队负责开发工作的成员。

相信很多人都熟悉 Markdown 文档格式，并且经常使用它。
这次，为了进一步推广 Markdown 在公司内部的应用，我想总结一下 Markdown 的基本写作风格，以及编写更严谨、更优雅的 Markdown 文档的一些要点。

使用 Markdown 的好处

首先，我们来探讨一下使用 Markdown 的好处。

使用 Markdown 的优势，尤其是在技术领域，是无法估量的。
由于 Markdown 具有定义明确的格式，因此它具有以下优点：

1. 句子结构简单，易于转换成其他格式。
2. 使用简单的符号和规则可以简化文档，使您能够专注于文档的完善。
3. 您可以在 Markdown 文档中嵌入源代码（但无法执行）。这使得创建由句子和一段与之互补的代码组成的结构变得容易，尤其是在技术领域。
4. 由于它只是一种文档格式，因此您可以直接编写文本而无需依赖特定的编辑器。

我的 Beyond Blog 文档都是用 Markdown 编写的（这篇文章也不例外）。
写完之后，我会进行修改和校对，然后转换成 HTML 格式，添加图片，并做一些简单的布局调整。

转换过程由 Gulp 处理，只需点击一下即可使用 Node.js 模块进行转换。
由于 CSS 的限制，模块输出的 HTML 无法直接使用，因此我先使用自己的转换器进行转换，然后再用模块进行转换。
这样，我充分利用了文档结构简洁的优势，便于处理，也让我能够专注于修改。

此外，由于 Beyond Blog 上的文章通常比较技术性，因此能够在文章中编写源代码是非常有帮助的。

 

我们开始吧！

我们先从使用 Markdown 格式开始。
写文章的时候，标题通常写在最右边，对吧？

那么，我们来学习如何写标题吧。

虽然有点晚了，但我们还是来总结一下 Markdown 吧。

 

就是这样。
我正在写的这篇文章和用 Markdown 写的一模一样。
在 Word 里给文档添加标题时，你每次都要操心标题是否居中、页边距多少字符等等问题，但用 Markdown 就完全不用操心这些了。

标题写好之后，下一步就是写正文了。
我们像这样写吧！

虽然有点晚了，但我们还是来总结一下 Markdown 吧。大家好，我是开发团队 Wild Team 的成员 Mandai。我相信你们中的许多人都熟悉 Markdown 这种文档格式，而且很多人经常使用它。

 

在标题之后插入一个换行符，然后开始撰写正文。

你开始明白大概意思了吗？
现在你只需要把你的想法和感受写下来就行了！

 

我想写一个列表，每行开头用项目符号标明项目符号。

你可以把列表想象成 HTML 中的 ul 标签。

定义无序列表非常简单：

只需在行首输入“-”、“+”或“*”，然后输入一个半角空格。

- 在 Markdown 中编写列表非常简单。- 例如，只需在行首输入“-”和一个空格，像这样。- 你也可以通过在行首输入空格或制表符来嵌套列表。- 非常简单。

 

有两件事需要注意：

• 列表之间不要换行。
• 嵌套时使用的空格（或制表符）数量有多种不同的规定。

就这样。

嵌套空格的处理方式因编辑器而异。
我们稍后会讨论这些差异，但现在您只需知道它们的存在即可。
编辑器通常允许进行调整，因此您可以自定义设置，使其与您发布 Markdown 内容的 Web 服务（例如 GitHub 或 Backlog）相匹配。

 

我想写一个编号列表

本节描述的功能对应于 HTML 中的 ol 标签。

“使用 Markdown 的优势”一节中提到的，使用编号列表
本节的 Markdown 版本如下：

1. 句子结构简单，因此易于转换为其他格式。2. 文档可以使用简单的符号和规则进行简化，因此您可以专注于文档的润色。3. 源代码可以嵌入到 Markdown 文档中（尽管无法执行）。尤其是在技术领域，创建由句子和补充代码段组成的结构非常容易。4. 由于它只是一种文档格式，因此您可以编写句子而无需依赖特定的编辑器。

 

字符串“1.”的出现表示编号列表的开始。
即使后面是连续的数字，该字符串也始终以“1.”开头。虽然
理论上“1.”可以递增计数，但如果条目顺序发生变化，则需要重写这些数字，从而增加维护工作量。

这里也只有两件事需要注意：列表之间不要换行，以及嵌套时空格的数量。

在 HTML 中显示列表需要将其包裹在 li 标签中，因此 Markdown 更容易编写。

 

我想写一个标题

当文本量很大时，你需要分章节撰写。

给每个项目添加标题也很容易，只需像这样写：

# 这是主要内容（标题）。请在此处撰写开头。## 这是中间内容。请在此处撰写关于中间内容的内容。### 这是次要内容。请在此处撰写关于次要内容的内容。

 

通过增加“#”符号的数量，您可以定义更小的项目，从而更容易编写清晰的句子。

 

我想定义一个链接

当然，有时候你可能需要在文章中添加指向互联网上文​​章的链接。

在这种情况下，您可以轻松地使用 Markdown 进行写作。

这是 Beyond 公司官网的链接（https://beyondjapan.com）。

 

在方括号“[]”内输入要转换成链接的文本，然后在圆括号“)”内输入链接目标网址。这
类似于使用HTML的“<a>”标签，所以应该很容易理解。

 

我想编写源代码

Markdown 中也有类似于 HTML 中 `<code>` 标签的东西。
在 Markdown 中，它被称为代码块。

php<?php class hogehoge { function echo($message) { echo $message; } } $a = new hogehoge(); $a->回声（）;

 

这段代码没有实际用途，但当你想用 Markdown 编写源代码时，从三个反引号 (`) 到接下来的三个反引号 (`) 之间的行会被识别为源代码。
第一个反引号后面的 `php` 是源代码的编程语言，并非必需。

您还可以通过调整部件数量来嵌套它们。

你可以使用 ~（波浪号）代替 `，但不能混用。

在 Markdown 中，代码块的边界最初是用四个空格定义的，而不是反引号或波浪号。然而，这一点并不为人所熟知，乍一看可能并不起眼，有些读者甚至不会注意到。因此，如果你记住了这个小知识，或许以后有机会可以炫耀一下。

 

我想定义一个表

从视觉上看，我认为最引人注目的是那张桌子。

正确的写法如下：

A列 | B列 | C列 ---------|----------|--------- A1 | B1 | C1 A2 | B2 | C2 A3 | B3 | C3

 

它看起来有点像表格，但查看器会根据“|”符号的数量自动调整格式，非常方便。
元素排列在一行水平线上，使得逐行重新排列变得极其容易，这是一个很大的优点。

“---------|----------|---------”这部分分隔了头部和数据部分，但GitHub和类似平台要求至少三个连字符。VS
Code的查看器即使只有一个连字符也能正常工作。

一般来说，编辑会灵活解读信息，但最好输入三项左右的信息作为指导原则。

 

定义文本强调

如果要突出显示文本，请用“__”将其括起来，它就会被突出显示。

在 Markdown 中，这就是你如何__强调__。

 

注意空格的位置。
开头是一个空格和两个下划线。
结尾是两个下划线和一个空格。

此外，还可以使用替代字符“**”。
在 Markdown 定义中，两者并无区别。

 

关于方言

文中有多处表达暗示（或直接说明）Markdown 有方言。

例如，Markdown 最著名的扩展可能是 GitHub Flavored Markdown，但还有许多其他扩展方言，如 R Markdown、Maruku 和 PHP Markdown Extra。

GitHub Flavored Markdown 会禁用下划线高亮显示，并且会将文本中的 URL 转换为链接。此外，Markdown 规范中也不包含表情符号的使用。

R Markdown 的一个关键特性是允许你将 R 语法编写为源代码，并让解析器将其作为 R 执行。

PHP Markdown Extra 似乎更注重转换为 HTML，允许您分配 ID 和类等内容，并且解析器采用类似 HTML 的方法工作，例如在 HTML 和 Markdown 混合的情况下，以及在块元素和行内元素的情况下。

此外，作为源文件的原始 Markdown 文档名为 CommonMark，但我认为这不在本次测试的范围内。
关于 CommonMark，有很多用 HTML 编写的非常详细的测试用例，所以即使页面是英文的，阅读这些用例也能获得很多启发。

CommonMark 规范 （本文以 0.28 版本为参考）

 

在 Visual Studio Code 中编写 Markdown

最后，我想介绍一个在 Visual Studio Code (VSCode) 中编写 Markdown 的实用扩展。
顺便一提，VSCode 内置了一个功能，虽然可能不太实用，但它可以在编写 Markdown 时，为代码块内的编程语言提供正确的高亮显示。

 

Markdown All in One

顾名思义，此扩展程序在一个软件包中提供了所有必要的 Markdown 功能。
安装后，您通常可以轻松地编写 Markdown 文档。

就我而言，我经常用要点列出我的想法，然后进行相应的格式化，因此能够消除不必要的键盘操作的功能非常棒，例如用 Enter 键完成列表，或者在列表中按 Tab 键创建子列表时在行首添加制表符。

Markdown All in One - Visual Studio Marketplace

 

Markdown 预览 美人鱼支持

这是一个扩展程序，可在 Markdown 预览中渲染 Mermaid 库。Mermaid
是一个用于显示流程图、序列图和甘特图的库。虽然您需要单独学习 Mermaid 的语法，但此扩展程序绝对能让您仅使用 Markdown 创建图表，从而加快文档创建速度。

Markdown Preview Mermaid 支持 - Visual Studio Marketplace

 

markdownlint

虽然刚开始使用时可能会有些困难，但它就像一个 Markdown 训练用的括号。
它对 Markdown 语法要求相当严格，如果出错，会立即显示警告。

我记得刚开始使用它的时候，感觉非常痛苦，但现在它已经很好地纠正了我的病情，以至于我几乎忘记了它曾经存在过。

毫不夸张地说，自从我发现了这个扩展程序后，我的MD技能有了显著提高。

至少我的写作水平已经提高到可以写出这样的文章了。

markdownlint - Visual Studio Marketplace

 

概括

由于 Markdown 本身基于可以转换为 HTML 的表达式，所以最终的解释类似于“这就是它转换为 HTML 后的样子”。你觉得怎么样？
实际上，Markdown 中还有很多其他的表达方式，但这次我们只关注了基本符号。

虽然我只介绍了 VSCode，但我对这篇文章很满意，因为我成功介绍了一些让 Markdown 编写更轻松的实用工具。
请负责任地、合理地使用 markdownlint。

如果 Markdown 太难用，以至于我最终讨厌它，那就适得其反了。

一旦你提高 Markdown 技能，我认为它在需要速度的情况下会很有用，例如会议记录，而且编写良好的 Markdown 甚至可以非常美观（这是本末倒置……！！）。

就这样。