如何编写Markdown & 环境准备（用VSCode）

你好。
我是Mandai，负责Wild 开发团队。

我想很多人都熟悉 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 你好。 我是Mandai，负责Wild 开发团队。我想很多人都熟悉 Markdown 这种文档格式，并且很多人经常使用它。

 

在标题后面插入换行符并开始编写。

你是否理解流程？
之后，您所要做的就是随心所欲地写！

 

我想写一个在行首有一个中心黑色字符的列表。

理解为列表就是HTML标签中的ul标签就可以了。

定义无序列表非常容易。

在行首放置“-”、“+”或“*”，并输入一个半角空格。就是这样。

- 在 Markdown 中编写列表很容易 - 例如，只需在行首输入“-”和半角空格，如下所示 - 您还可以通过在行首插入空格或制表符来嵌套列表- 这很容易，不是吗？

 

有两件事需要注意。

• 不要在列表之间插入换行符
• 关于嵌套时空格（或制表符）的数量有多种方言。

就这样。

根据编辑器的不同，嵌套时空格的识别方式也不同。
我稍后会讨论这种方言，但现在，只要说这种方言存在就足够了。
编辑器应该能够调整它以适应您可能将 Markdown 发布到的任何 Web 服务，例如 github 或 backlog。

 

我想写一个编号列表

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

使用有序列表也很容易，这在
使用 Markdown 的好处部分这部分的Markdown版本如下。

1. 简单的句子结构，可以轻松转换为其他格式 1. 可以使用简单的符号和规则来简化文档，让您专注于文档细化 1. 源代码可以存储在 Markdown 文档中 可以嵌入（但不能执行） 。特别是在技术领域，很容易创建由文本和补充它的代码部分组成的结构。1.由于它是简单的文档格式，因此您可以编写文本而不依赖于特定的编辑器。

 

当字符串“1.”出现时，它表示编号列表的开始。
即使有连续的数字，字符串的开头也应该是“1.”。
即使累加1，规格也没有问题，但如果累加时改变顺序，就需要重写数字，需要维护。

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

HTML列表显示需要用li标签包裹起来，这样Markdown更容易写。

 

我想写一个标题

当文字量增加到一定程度时，就需要分章来写文字了。

为每个项目添加标题非常容易，如下所示。

# 主要项目（标题） 在这里写开头 ## 中项目 在这里写关于中项目的内容 ### 小项目 在这里写关于小项目的内容

 

通过增加“#”字符的数量，您可以定义更小的项目，从而更容易编写具有良好可视性的句子。

 

我想定义一个链接

当然，有时您希望在文本中包含指向 Internet 上的文章的链接。

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

这是[Beyond 公司网站](https://beyondjapan.com) 的链接。

 

在“[]”中输入要建立链接的字符串，然后在“()”中输入链接目标的URL。
它的用法和HTML的a标签类似，所以应该很容易理解。

 

我想写源码

Markdown 也有类似 HTML 中的代码标签的东西。
在 Markdown 中，这称为隔离代码块。

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

 

虽然是没有价值的代码，但是当你想用 Markdown 写源代码时，从下一行三个“``”字符到又一行三个“``”字符的行都会被识别为源代码代码。 。
第一个“`”后面的“php”是源代码的编程语言，不是必需的。

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

您还可以使用 ~（波形符）作为 ` 的替代字符，但不能混合使用它们。

请注意，Markdown 最初将围栏代码块的边框定义为四个空格，而不是反引号或波形符，但乍一看似乎没有边框，有些查看者可能没有意识到这一点，所以，如果你记住它的话。至少，在某些情况下你可以脱颖而出。

 

我想定义一个表

我认为这幅画中最引人注目的部分是桌子。

其写法如下。

A 栏 | B 栏 |---------|--------- A1 | C1 A2 | B3 | C3

 

虽然它看起来像一个表格，但它非常方便，因为查看者可以根据“|”字符的数量调整外观。
关键是，由于元素是水平排列的，所以交换行非常方便。

“---------|---------|---------”部分分隔了标头部分和数据部分，但在 github 等中必须有三个或更多连字符。
在 VSCode 中，即使只有一个查看器也会做出响应。

基本上，编辑器会更灵活地解释它，但我认为最好输入3左右作为指导。

 

我想定义角色重点

如果你想强调一个字符，用“__”包围它，它就会突出显示。

在 Markdown 中，我们像这样执行 __emphasis__ ：

 

注意空间的位置。
以空格和两个下划线开头。
完成后，以两个下划线和一个空格结束。

还有“**”作为替代字符。
两者之间的 Markdown 定义没有区别。

 

关于方言

文本中多次出现表明（甚至明确表明）Markdown 有方言的表达方式。

我认为最著名的 Markdown 扩展GitHub Flavored Markdown

GitHub Flavored Markdown 具有禁用下划线突出显示以及让查看者将文本中的 URL 转换为链接等功能。表情符号的使用实际上并不包含在 Markdown 规范中。

R Markdown 的特点是，当 R 语法被编写为源代码时，解析器将其作为 R 执行。

PHP Markdown Extra 似乎强调转换为 HTML，允许添加诸如 ID 和类之类的东西，HTML 和 Markdown 混合的情况，以及面向 HTML 的想法（例如块元素和内联元素）解析器现在正在工作。

另外，成为起源的原始 Markdown 特别称为 CommonMark，但我觉得这不是测试的范围。
至于CommonMark，测试用例非常详细，并且被转换为HTML，所以即使页面是英文的，我只是阅读它就注意到了很多东西。

CommonMark Spec （本文引用0.28）

 

使用 Visual Studio Code 编写 Markdown 时

有一些扩展在 Visual Studio Code（以下简称 VSCode）中编写 Markdown 时很有用，所以我会在最后介绍它们。
顺便说一句，当你使用 VSCode 编写 Markdown 时，它默认带有一个不错的功能，可以让你在受隔离的代码块中清楚地突出显示编程语言。

 

Markdown 多合一

顾名思义，它是一个具有 Markdown 所需所有功能的扩展。
一旦你做到了这一点，你通常就可以轻松地编写 Markdown 了。

尤其是在我的情况下，我经常将我的想法格式化为列表中的项目符号点后，这样我就可以使用回车键来完成列表，或者在列表上按 Tab 键来创建子列表，从而节省不必要的功能。通过在行首添加 `` 进行键盘操作是令人惊奇的。

Markdown 多合一 - Visual Studio Marketplace

 

Markdown 预览 Mermaid 支持

这是一个使用 Markdown 预览渲染名为 mermaid 的库的扩展。
mermaid 是一个用于显示流程图、序列图和甘特图的库，虽然您需要单独记住 mermaid 符号，但它是一个绝对可以帮助您创建材料的扩展，因为您将能够仅使用 Markdown 来绘制图表。

Markdown 预览 Mermaid 支持 - Visual Studio Marketplace

 

标记

相反，它就像 Markdown 培训演员，尽管一开始通常很难介绍它。
需要相当严格的 Markdown 符号，如果你的描述不正确，你会立即收到警告。

我记得它刚推出时只是一种痛苦，但现在它已经得到了很好的纠正，以至于我什至忘记了它的存在。

我认为，自从我发现这个扩展以来，我的 MD 技能有了很大的提高，这一点并不夸张。

至少我已经进步到可以写这样的文章了。

markdownlint - Visual Studio Marketplace

 

概括

由于 Markdown 本身是一个可以转换为 HTML 的表达式，因此最终的解释是这样的：“这就是转换为 HTML 时会发生的情况。”您觉得怎么样？
实际上，Markdown 中的表达方式还有很多，但这次我们主要关注基本符号。

虽然我只使用了 VSCode，但我也能够介绍一些有用的工具，使编写 Markdown 变得更容易，所以我对这篇文章很满意。
请按照使用说明使用markdownlint。

如果你最终因为 Markdown 太难而讨厌它，那么你就没有抓住重点。

一旦你提高了 MD 技能，我认为你将能够在需要速度的情况下展示你的力量，比如会议纪要，而且我觉得精心完成的 Markdown 是纯粹的美（这是将本末倒置...).!!)。

就是这样。