跳到主要内容
版本:Canary 🚧

Markdown 特性

文档是你的产品向用户展示的门面之一。 文从字顺、层次清晰的文章有助于用户快速了解您的产品。 我们的一致目标是帮助用户尽快找到所需要的信息。

Docusaurus 2 使用现代化工具来帮助你轻松撰写交互式文档。 你可以嵌入 React 组件,亦或是搭建用户可交互的实时代码编辑块。 就用代码呈现你的灵光一现,捕获你的受众的心吧! 这可能是吸引潜在用户的最有效的方式。

important

本章节假定你使用 Docusaurus 官方的内容插件。

标准功能

Markdown 是一种能让你撰写易读的格式化内容的语法。

我们用 MDX 作为模板引擎,它能做的事情要比解析标准 Markdown 语法多得多,比如可以在文档中渲染 React 组件。

### 我的文档章节

一些文本,包括**粗体**_斜体_,和[链接](/)

![图片 alt 文本](/img/docusaurus.png)
http://localhost:3000

我的文档章节

一些文本,包括粗体斜体,和链接

图片 alt 文本

Markdown 是声明式的

有些人可能会假定 Markdown 和 HTML 之间存在一对一的对应,例如 ![Preview](/img/docusaurus.png) 始终会变成 <img src="/img/docusaurus.png" alt="Preview" />。 然而,事实并非如此

![message](url) 这种 Markdown 语法只会声明式地告诉 Docusaurus 需要在此处插入一个图像。但我们可能会做其他事情,比如把文件路径转换为 URL 路径,所以我们生成的标记可能不同于其他 Markdown 渲染器的输出,也可能不同于简单转写出的等效 JSX/HTML 代码。

一般来说,你只应该假定输出的语义(比如``` 会变成代码块> 会变成引文等),但不能假定真正的编译输出。

前言

你可以用前言 (front matter) 来给你的 Markdown 文件添加元数据。 所有内容插件都有自己可接受的前言规范,并使用前言来丰富元数据,因为后者不能从内容或其他配置中完美地推断。

前言是在文件的最顶端给出的,两端由三个横线 --- 包围。 内容会按 YAML 解析。

---
title: 我的文档标题
其他内容:
- 可以以
- 对象: 或者
数组: 的形式给出
---

引文

Markdown 引文有着漂亮的样式:

> 易于维护开源文档网站。
>
> — Docusaurus
http://localhost:3000

易于维护开源文档网站。

— Docusaurus

详情内容

Markdown 可以嵌入 HTML 元素。HTML 的 details 元素会拥有漂亮的样式:

### Details 元素示例

<details>
<summary>点我!</summary>
<div>
<div>这是详情内容</div>
<br/>
<details>
<summary>
嵌套的下拉栏! 内含惊喜……
</summary>
<div>
😲😲😲😲😲
</div>
</details>
</div>
</details>
http://localhost:3000

Details 元素示例

点我!
这是详情内容

嵌套的下拉栏! 内含惊喜……
😲😲😲😲😲
备注

实际上,这些并不是真正的 HTML 元素,而是 React JSX 元素。我们接下来就会具体介绍它们!