企业官网建设流程全解析

• 文档
• 教程

本指南以 learnxinyminutes-docs 仓库中的 葡萄牙语版 Markdown 教程 及其英文原版为骨架，系统讲解 Markdown 从基础语法到工程化使用的完整知识：标题、列表、代码块、链接、图片等通用语法，以及 GitHub Flavored Markdown（GFM）扩展特性，并结合本仓库的 CONTRIBUTING.md 与 lint 工具 说明如何用 frontmatter 元数据和 Markdownlint 写出规范、可被工具链自动校验的文档。读完本文，你将掌握 Markdown 的完整语法体系，并能在本仓库或任何以 Markdown 为载体的项目中写出专业级文档。

Markdown 的起源与解析器差异

Markdown 由 John Gruber 于 2004 年发布，设计目标是提供一种易于阅读和书写的语法，并能方便地转换为 HTML（如今也支持许多其他输出格式）。

需要特别注意的是：Markdown 的实现在不同解析器之间是有差异的。某些语法是几乎所有解析器都支持的"通用特性"，另一些则属于某个特定解析器（如 GitHub Flavored Markdown）的扩展。本指南在讲解每个语法点时，都会明确区分哪些是通用特性、哪些是特定解析器的扩展，避免你在迁移文档时踩坑。

HTML 元素：Markdown 是 HTML 的超集

Markdown 是 HTML 的超集，因此任何 HTML 文件本身就是合法的 Markdown 文件。这意味着我们可以直接在 Markdown 中使用 HTML 元素（如注释元素），它们不会被 Markdown 解析器处理：

<!--这意味着我们可以在 Markdown 中使用 HTML 元素，例如注释元素， 它们不会被 Markdown 解析器影响。但是，如果你在 Markdown 文件中创建了 一个 HTML 元素，你就不能在该元素的内容内部使用 Markdown 语法。-->

一个关键限制是：一旦进入 HTML 元素内部，Markdown 语法在该元素的内容范围内不再生效。这是编写混合文档时必须牢记的边界。

标题：六级标题与两种写法

在文本前面加上若干#号，即可轻松创建 HTML 的<h1>到<h6>元素：

# 这是一个 h1 标题 ## 这是一个 h2 标题 ### 这是一个 h3 标题 #### 这是一个 h4 标题 ##### 这是一个 h5 标题 ###### 这是一个 h6 标题

Markdown 还提供了两种指示 h1 和 h2 的替代写法（Setext 风格），在标题行下方用=或-划线：

这是一个 h1 标题 ====================== 这是一个 h2 标题 ----------------------

注意：=对应 h1，-对应 h2，划线的长度没有严格要求，但至少要能覆盖标题文字。

简单文本样式：斜体与粗体

用 Markdown 可以轻松地把文本设置为斜体或粗体：

*这段文字是斜体* _这段也是斜体_ **这段文字是粗体** __这段也是粗体__ ***这段文字既是粗体又是斜体*** **_这段也是_** *__这一段同样是__*

可以看到，斜体可用*或_包裹，粗体可用双*或双_包裹，两者可以自由组合嵌套。

在 GitHub Flavored Markdown（用于渲染 GitHub 上 Markdown 文件的规范）中，还有删除线：

~~这段文字会被渲染为带删除线的效果。~~

段落与换行

段落由一行或多行相邻文本组成，段落之间用一个或多个空行分隔：

这是一个段落。我在段落里打字，是不是很有趣？ 现在我在第二段。 我依然在第二段！ 我在第三段！

如果你需要插入 HTML 的<br />标签，可以在段落末尾加上两个或更多空格，然后另起一行：

我以两个空格结尾（选中这行可以看到它们）。 我上面有一个 <br />！

这种"行尾两空格 + 换行"的写法是 Markdown 中显式强制换行的经典方式。

引用块

引用块用>字符即可轻松创建：

> 这是一个引用块。你可以 > 手动换行并在每一行前面放一个 `>`，或者让行变得很长、 > 让它自己换行。 > 只要每行都以 `>` 开头，效果没有区别。 > 你还可以使用多于一级的引用 >> 的缩进？ > 是不是很酷？

多级嵌套引用通过连续叠加>>实现，且各层引用可以交替出现。

列表：无序、有序、子列表与任务列表

无序列表可以用星号、加号或连字符三种符号创建：

* 项目 * 项目 * 另一个项目 或 + 项目 + 项目 + 另一个项目 或 - 项目 - 项目 - 最后一个项目

有序列表用数字加句点构成：

1. 项目一 2. 项目二 3. 项目三

你甚至不需要正确编号，Markdown 仍会按顺序渲染序号。例如下面这个列表的渲染结果与上面完全相同：

1. 项目一 1. 项目二 1. 项目三

（渲染结果与上面的示例相同。）

尽管解析器会自动修正序号，但为了可读性与可维护性，还是建议手动编号。

子列表通过缩进实现——有序列表项下方缩进的无序列表项会成为其子项：

1. 项目一 2. 项目二 3. 项目三 * 子项目 * 子项目 4. 项目四

此外还有任务列表，它会生成 HTML 的复选框（checkbox）：

下面不带 'x' 的方框是未勾选的 HTML 复选框。 - [ ] 第一项待完成的任务。 - [ ] 第二项待完成的任务。 下面这个复选框会被渲染为已勾选的 HTML 复选框。 - [x] 这项任务已经完成

任务列表是 GFM 风格的常用特性，非常适合书写 TODO 清单与验收清单。

代码块：缩进式、行内式与围栏式

通过缩进四个空格或一个 Tab可以指示一个代码块（内部使用<code>元素）：

这是代码 就是这样，懂了吗？

在代码块内部需要继续缩进时，可以再次 Tab（或再缩进四个空格）：

my_array.each do |item| puts item end

行内代码使用反引号`创建：

John 甚至不知道 `go_to()` 函数是干什么的！

在 GitHub Flavored Markdown 中，还可以使用围栏式代码块（fenced code block）特殊语法：

```ruby def foobar puts "你好，世界！" end ```

上面的写法不需要任何缩进，而且 GitHub 会根据开头的```之后指定的语言进行语法高亮。围栏式代码块是本仓库所有教程文档的主要代码载体——比如本仓库的 python.md 等文件，正文几乎全部由带语言标注的围栏代码块构成，这正是"用代码写文档"理念的体现。

水平线

用三个或更多星号或连字符（可带空格、可不带空格）即可轻松添加水平线（<hr/>）：

*** --- - - - ****************

链接：行内式、带标题与引用式

Markdown 最出色的特性之一就是创建链接非常容易：把要显示的文本放在方括号[]中，紧接着把 URL 放在圆括号()中：

[点这里！](http://test.com/)

还可以在圆括号内使用引号添加链接标题：

[点这里！](http://test.com/ "链接到 Test.com")

相对路径同样适用：

去音乐区。

在仓库文档中，相对链接是文档互引的基础——例如 README.md 中就以[CONTRIBUTING][2]的引用式写法指向 CONTRIBUTING.md。

Markdown 还支持引用式链接（reference style links），把链接定义集中放在文档任意位置：

[点击这个链接][link1] 获取更多信息！ [也可以看看这个链接][foobar] 如果你想的话。 [link1]: http://test.com/ "酷！" [foobar]: http://foobar.biz/ "行！"

链接标题既可以用双引号，也可以用单引号或圆括号，甚至可以完全省略。引用定义可以放在文档的任何位置，引用 ID 可以是任意内容，只要保证唯一即可。

还有一种"隐式命名"（implicit naming），直接用链接文本作为 ID：

[这个][] 是一个链接。 [这个]: http://thisisalink.com/

不过这种写法并不太常用。

表格目录（Table of Contents）

某些 Markdown 方言还支持用"列表 + 链接 + 标题"的组合生成目录：此时标题文本会转为小写、前面加上#作为链接锚点 ID；如果标题由多个单词组成，单词之间用连字符-连接，同时部分特殊字符会被替换（另一些特殊字符则会被省略）：

- [标题](#标题) - [另一个标题](#另一个标题) - [章节](#章节) - [子章节 <h3 />](#子章节-h3-)

需要说明的是，这个特性不一定在所有 Markdown 实现中都以相同方式工作，生成目录时建议以目标平台的实际渲染结果为准。

图片

图片的写法和链接一样，只是在前面多了一个感叹号：

![这是我图片的 alt 文本（替代文本）](http://imgur.com/myimage.jpg "一个可选的标题")

引用式写法同样适用：

![这是 alt 属性。][myimage] [myimage]: relative/urls/cool/image.jpg "如果需要标题，就在这里"

alt文本是图片的替代说明，对无障碍访问与搜索引擎理解图片内容都至关重要。

杂项：自动链接、转义、键盘键与表格

自动链接

<http://testwebsite.com/> 等价于 [http://testwebsite.com/](http://testwebsite.com/)

用尖括号包裹 URL，Markdown 会自动将其转换为链接。

邮件自动链接

<foo@bar.com>

同样的尖括号写法也适用于邮箱地址，解析器会生成可点击的mailto:链接。

转义字符

如果想输入带星号的文本，又不想让它被渲染为斜体，可以用反斜杠转义：

我想输入 *这段带星号的文字*，但我不想让它变成斜体， 所以我这样做：\*这段带星号的文字\*。

反斜杠转义同样适用于其他 Markdown 特殊字符（如#、>、[等）。

键盘键

在 GitHub Flavored Markdown 中，可以使用<kbd>标签来表示键盘按键：

你的电脑死机了？试试按 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>

表格

表格仅在 GitHub Flavored Markdown 中可用，语法稍显繁琐，但如果你想用的话：

| 列1 | 列2 | 列3 | | :----------- | :------: | ------------: | | 左对齐 | 居中 | 右对齐 | | blah | blah | blah |

或者，为了同样的效果：

列 1 | 列 2 | 列 3 :-- | :-: | --: 这个太丑了 | 这样做 | 停

第二行中的冒号位置决定了每列的对齐方式：:--左对齐、:-:居中、--:右对齐。

从语法到工程化：Markdownlint 与仓库规范

为了让 Markdown 的使用更规范、风格更统一，社区创建了Markdownlint工具。它既可以作为某些 IDE 的插件使用，也可以作为独立命令行工具运行，用来确保 Markdown 的有效性与可读性。

本仓库正是 Markdown 工程化实践的典型样本：全部文档均为 Markdown 文件，并配有专门的 lint 工具链来保证质量。仓库根目录下的 CONTRIBUTING.md 明确了以下风格规范：

• 代码行保持在 80 字符以内：代码块中的行长度尽量不超过 80 字符，否则文本会溢出、看起来很奇怪。这类潜在问题正是由 Markdownlint 识别的；
• 示例优先于叙述：尽量少用文字，任何情况下代码示例都优于文字说明；
• 避免赘述：面向有经验的程序员，避免解释基础概念；
• 使用 UTF-8 编码。

配套的 lint/encoding.sh 脚本会在仓库中查找所有*.md文件，逐文件检查其 MIME 编码，若编码既不是utf-8也不是us-ascii，或文件携带 UTF-8 BOM（文件头三个字节为\xEF\xBB\xBF），则报错退出。这从工具层面落实了"使用 UTF-8"的规范，也解释了为何所有多语言文档都能在 zh-cn/ 等目录中正确显示中文等内容。

frontmatter：Markdown 文件的元数据头

仓库的实际站点会由这些 Markdown 文件生成 HTML 页面。除了正文，Markdown 文件还可以在开头携带额外的元数据，称为frontmatter（以---分隔的 YAML 块）。以本教程文件 pt-br/markdown.md 开头为例：

--- contributors: - ["Dan Turkel", "http://danturkel.com/"] translators: - ["Miguel Araújo", "https://github.com/miguelarauj1o"] - ["Gabriele Luz", "https://github.com/gabrieleluz"] - ["Monique Baptista", "https://github.com/bfmonique"] - ["Marcel Ribeiro-Dantas", "https://github.com/mribeirodantas"] filename: learnmarkdown.md ---

根据 CONTRIBUTING.md 的说明，英文语言类文章必需的字段包括：

• name：编程语言的人类可读名称；
• contributors：[作者, URL]形式的列表，用于署名，URL 可选。

其他可选字段包括：

• category：文章分类，目前可以是language、tool或Algorithms & Data Structures，省略时默认为language；
• filename：该文章代码的文件名，站点会抓取、拼接并使其可下载。

翻译文章还应包含translators（[译者, URL]列表）。非英文文章默认继承英文文章的 frontmatter 值，但可以覆盖。

这些约定并不是口头规范，而是有自动化校验支撑的。lint/frontmatter.py 会解析每个 Markdown 文件开头的 YAML frontmatter，先使用 yamllint 做语法检查，再验证键的合法性：只允许name、where_x_eq_name、category、filename、contributors、translators六个键，且contributors/translators必须是[字符串, 可选字符串]形式的二元列表。一旦发现非法键、类型错误或 YAML 解析错误，脚本就会打印出对应的文件路径与具体问题并以非零状态退出。这就是 Markdown 语法之外、"元数据语法"层面的质量保障。

延伸阅读与仓库内实践

关于 Markdown 的更多信息，可以参阅 John Gruber 在 Daring Fireball 发布的官方语法说明，以及 Adam Pritchard 编写的著名速查表（cheatsheet）。若想深入了解各大方言的特性，可分别查阅 GitHub Flavored Markdown 与 GitLab Flavored Markdown 的官方文档。

在本仓库内，你可以继续对照阅读：

• 英文原版 Markdown 教程：了解本指南对应内容在英文版中的表述与补充细节；
• CONTRIBUTING.md：完整的贡献规范、frontmatter 字段说明与本地构建流程（克隆站点仓库、安装依赖后执行python build.py，再用python -m http.server在本地预览）；
• lint/frontmatter.py 与 lint/encoding.sh：frontmatter 校验与 UTF-8 编码检查的完整实现；
• README.md：项目总览，说明本仓库"以带注释的代码呈现教程"的核心理念。

掌握了从基础语法、GFM 扩展到 frontmatter 元数据与 lint 工具链的完整链路，你就能在 learnxinyminutes-docs 这样的多语言文档仓库中写出结构清晰、风格统一、可被自动校验的 Markdown 文档。

• 文档
• 教程