PZY | Markdown 基本语法

03Jul 2022

Markdown 基本语法

2478 words - 13 mins

本文提供了可用于 Zola 内容文件的基本 Markdown 语法示例。

让我们面对现实吧：为 Web 编写内容令人厌烦。 WYSIWYG 编辑器有助于减轻这项任务，但它们通常会导致糟糕的代码，或者更糟糕的是，丑陋的网页。

Markdown 是编写 HTML 的更好方式，没有通常伴随的所有复杂性和丑陋性。

一些主要好处是：

Markdown 简单易学，额外字符很少，因此编写内容也更快。
使用 Markdown 编写时出错的可能性较小。
产生有效的 XHTML 输出。
将内容和视觉显示分开，这样您就不会弄乱网站的外观。
在任何你喜欢的文本编辑器或 Markdown 应用程序中编写。
Markdown 使用起来很愉快！

事不宜迟，让我们回顾一下 Markdown 的主要元素以及生成的 HTML 是什么样子的！

标题

从 h1 到 h6 的标题由每个级别的 # 构成：

# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading

HTML 如下所示：

<h1>h1 Heading</h1>
<h2>h2 Heading</h2>
<h3>h3 Heading</h3>
<h4>h4 Heading</h4>
<h5>h5 Heading</h5>
<h6>h6 Heading</h6>

注释

注释应该与 HTML 兼容。

<!--
这是一条注释
-->

下面的注释应该不被看到：

水平规则

HTML <hr> 元素用于在段落级元素之间创建“主题分隔”。在 Markdown 中，您可以使用以下任何内容创建一个 <hr>：

___: three consecutive underscores
---: three consecutive dashes
***: three consecutive asterisks

呈现的输出如下所示：

正文

正常书写的正文，纯文本将在呈现的 HTML 中以 <p></p> 标记包装。

如以下正文：

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri,
animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex,
soluta officiis concludaturque ei qui, vide sensibus vim ad.

HTML 如下所示：

<p>Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.</p>

换行可以用一个空行来完成。

内联 HTML

如果您需要某个特定的 HTML 标签（带有类），您可以简单地使用 HTML：

Markdown 中的段落。

<div class="class">
    This is <b>HTML</b>
</div>

Markdown 中的段落。

强调

粗体（Bold）

用于强调字体粗细较重的文本片段。

以下文本片段呈现为粗体文本。

**rendered as bold text**
__rendered as bold text__

HTML 如下所示：

<strong>rendered as bold text</strong>

斜体（Italics）

用于用斜体强调文本片段，以下文本片段呈现为斜体文本：

*rendered as italicized text*
_rendered as italicized text_

HTML 如下所示：

<em>rendered as italicized text</em>

删除线（Strikethrough）

在 [GFM]^(GitHub 风格的 Markdown) 中，您可以使用删除线。

~~ Strike through this text. ~~

HTML 如下所示：

<del>Strike through this text.</del>

块引用（Blockquotes）

用于引用文档中其他来源的内容块。在要引用的任何文本之前添加>：

> **Fusion Drive** combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.

渲染的输出如下所示：

Fusion Drive combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.

HTML 如下所示：

<blockquote>
  <p>
    <strong>Fusion Drive</strong> combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.
  </p>
</blockquote>

块引用也可以嵌套：

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue.
Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>> Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor
odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

渲染的输出如下所示：

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

列表（List）

无序列表

项目列表，其中项目的顺序没有明确的重要性。您可以使用以下任何符号来表示每个列表项的项目符号：

* valid bullet
- valid bullet
+ valid bullet

例如：

* Lorem ipsum dolor sit amet
* Consectetur adipiscing elit
* Integer molestie lorem at massa
* Facilisis in pretium nisl aliquet
* Nulla volutpat aliquam velit
  * Phasellus iaculis neque
  * Purus sodales ultricies
  * Vestibulum laoreet porttitor sem
  * Ac tristique libero volutpat at
* Faucibus porta lacus fringilla vel
* Aenean sit amet erat nunc
* Eget porttitor lorem

渲染的输出如下所示：

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Integer molestie lorem at massa
Facilisis in pretium nisl aliquet
Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
Faucibus porta lacus fringilla vel
Aenean sit amet erat nunc
Eget porttitor lorem

HTML 如下所示：

<ul>
  <li>Lorem ipsum dolor sit amet</li>
  <li>Consectetur adipiscing elit</li>
  <li>Integer molestie lorem at massa</li>
  <li>Facilisis in pretium nisl aliquet</li>
  <li>Nulla volutpat aliquam velit
    <ul>
      <li>Phasellus iaculis neque</li>
      <li>Purus sodales ultricies</li>
      <li>Vestibulum laoreet porttitor sem</li>
      <li>Ac tristique libero volutpat at</li>
    </ul>
  </li>
  <li>Faucibus porta lacus fringilla vel</li>
  <li>Aenean sit amet erat nunc</li>
  <li>Eget porttitor lorem</li>
</ul>

有序列表

项目列表，其中项目的顺序明确重要。

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
4. Facilisis in pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Aenean sit amet erat nunc
8. Eget porttitor lorem

渲染的输出如下所示：

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Integer molestie lorem at massa
Facilisis in pretium nisl aliquet
Nulla volutpat aliquam velit
Faucibus porta lacus fringilla vel
Aenean sit amet erat nunc
Eget porttitor lorem

HTML 如下所示：

<ol>
  <li>Lorem ipsum dolor sit amet</li>
  <li>Consectetur adipiscing elit</li>
  <li>Integer molestie lorem at massa</li>
  <li>Facilisis in pretium nisl aliquet</li>
  <li>Nulla volutpat aliquam velit</li>
  <li>Faucibus porta lacus fringilla vel</li>
  <li>Aenean sit amet erat nunc</li>
  <li>Eget porttitor lorem</li>
</ol>

任务列表

任务列表允许您创建带有复选框的项目列表。若要创建任务列表，请在任务列表项之前添加短划线 (-) 和带空格的方括号 ([ ])。要选择一个复选框，请在方括号 ([x]) 之间添加一个 x。

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

渲染的输出如下所示：

Write the press release
Update the website
Contact the media

代码（Code）

内联代码

用 ` 包装内联代码片段。

In this example, `<section></section>` should be wrapped as **code**.

渲染的输出如下所示：

In this example, <section></section> should be wrapped as code.

HTML 如下所示：

<p>
  In this example, <code>&lt;section&gt;&lt;/section&gt;</code> should be wrapped with <strong>code</strong>.
</p>

缩进代码

或者将几行代码缩进至少四个空格，如下所示：

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code

渲染的输出如下所示：

// Some comments

line 1 of code

line 2 of code

line 3 of code

HTML 如下所示：

<pre>
  <code>
    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code
  </code>
</pre>

表格（Tables）

通过在每个单元格之间添加管道作为分隔线，并在标题下方添加一行短划线（也由条形分隔）来创建表格。请注意，管道不需要垂直对齐。

| Option | Description |
| ------ | ----------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

渲染的输出如下所示：

Option	Description
data	path to data files to supply the data that will be passed into templates.
engine	engine to be used for processing templates. Handlebars is the default.
ext	extension to be used for dest files.

HTML 如下所示：

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>data</td>
      <td>path to data files to supply the data that will be passed into templates.</td>
    </tr>
    <tr>
      <td>engine</td>
      <td>engine to be used for processing templates. Handlebars is the default.</td>
    </tr>
    <tr>
      <td>ext</td>
      <td>extension to be used for dest files.</td>
    </tr>
  </tbody>
</table>

链接（Links）

基本链接

<https://assemble.io>
[email protected]>
[Assemble](https://assemble.io)

呈现的输出如下所示（将鼠标悬停在链接上，没有工具提示）：

https://assemble.io

[email protected]

Assemble

HTML 如下所示：

<a href="https://assemble.io">https://assemble.io</a>
<a href="mailto:[email protected]">[email protected]</a>
<a href="https://assemble.io">Assemble</a>

添加标题

[Upstage](https://github.com/upstage/ "Visit Upstage!")

呈现的输出如下所示（将鼠标悬停在链接上，将有一个工具提示）：

Upstage

HTML 如下所示：

<a href="https://github.com/upstage/" title="Visit Upstage!">Upstage</a>

命名锚点

命名锚点使您能够跳转到同一页面上的指定锚点。例如，这些章节中的每一章：

## Table of Contents
  * [Chapter 1](#chapter-1)
  * [Chapter 2](#chapter-2)
  * [Chapter 3](#chapter-3)

将跳转到这些部分：

## Chapter 1 <a id="chapter-1"></a>
Content for chapter one.

## Chapter 2 <a id="chapter-2"></a>
Content for chapter one.

## Chapter 3 <a id="chapter-3"></a>
Content for chapter one.

脚注（Footnotes）

脚注允许您添加注释和参考，而不会使文档正文混乱。当您创建脚注时，添加脚注引用的位置会出现一个带有链接的上标数字。读者可以点击链接跳转到页面底部脚注的内容。

要创建脚注引用，请在方括号内添加插入符号和标识符([^1])。标识符可以是数字或单词，但不能包含空格或制表符。标识符仅将脚注引用与脚注本身相关联——在输出中，脚注按顺序编号。

使用另一个插入符号和括号内的数字添加脚注，带有冒号和文本（[^1]：我的脚注。）。您不必在文档末尾添加脚注。您可以将它们放在除了其他元素（如列表，块引号和表格等）之外的任何位置。

This is a digital footnote[^1].
This is a footnote with "label"[^label]

[^1]: This is a digital footnote
[^label]: This is a footnote with "label"

This is a digital footnote¹.

This is a footnote with "label"²

This is a digital footnote

This is a footnote with "label"

图片（Images）

图像具有与链接类似的语法，但包含前面的感叹号。

![Minion](https://octodex.github.com/images/minion.png)

Minion

或者：

![Alt text](https://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")

Alt text

像链接一样，图像也有脚注样式语法：

![Alt text][id]

Alt text

在文档后面定义 URL 位置的引用：

[id]: https://octodex.github.com/images/dojocat.jpg  "The Dojocat"

Markdown