如何编写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）。

 

在“[]”之间输入你想转换成链接的字符串，然后在“()”之间输入链接目标的URL。
这很容易理解，因为它的用法类似于HTML的a标签。

 

我想编写源代码

Markdown 中有一个类似于 HTML 中的代码标签的功能
，叫做围栏式代码块。

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）要求至少有三个连字符。
在 VSCode 中，即使只有一个连字符，查看器也能正常显示。

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

 

定义文本强调

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

在 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

 

标记

事实上，入门可能相当困难，但它就像一个 Markdown 培训课程。
它对 Markdown 语法要求非常严格，如果出错，你会立即收到警告。

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

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

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

markdownlint - Visual Studio Marketplace

 

概括

Markdown 本身就是一种可以转换为 HTML 的语言，因此本文的解释仅限于说明它转换为 HTML 后的样子。您觉得如何？
实际上，Markdown 的表达方式远不止这些，但这次我们只关注了它的基本表示法。

虽然我只介绍了 VSCode，但我很高兴能够介绍一些让 Markdown 编写更轻松的实用工具。
希望您能谨慎使用 markdownlint。

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

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

就是这样。