跳到主要内容

Markdown Features

文档是产品与用户之间的接口之一。一组精心编写和组织良好的文档可帮助您的用户快速了解您的产品。我们一致的目标是帮助您的用户尽快找到并了解他们所需的信息。

Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.

important

本章节假定您使用的是由 Docusaurus 官方提供的内容插件(即 docusaurus-plugin-content-{blog, docs, pages})。

标准特性

Markdown 是一种语法,使您能够以一种便于阅读的语法来编写格式化的内容。

We use MDX as the parsing engine, which can do much more than just parsing standard Markdown syntax, like rendering React components inside your documents as well.

### My Doc Section

Hello world message with some **bold** text, some _italic_ text, and a [link](/)

![img alt](/img/docusaurus.png)
http://localhost:3000

My Doc Section

Hello world message with some bold text, some italic text and a link

img alt

Markdown is declarative

Some may assume a 1-1 correlation between Markdown and HTML, e.g., ![Preview](/img/docusaurus.png) will always become <img src="/img/docusaurus.png" alt="Preview" />, as-is. However, that is not the case.

The Markdown syntax ![message](url) only declaratively tells Docusaurus that an image needs to be inserted here, but we may do other things like transforming a file path to URL path, so the generated markup may differ from the output of other Markdown renderers, or a naïve hand-transcription to the equivalent JSX/HTML code.

In general, you should only assume the semantics of the markup (``` fences become code blocks; > becomes quotes, etc.), but not the actual compiled output.

Front matter

Front matter is used to add metadata to your Markdown file. All content plugins have their own front matter schema, and use the front matter to enrich the default metadata inferred from the content or other configuration.

Front matter is provided at the very top of the file, enclosed by three dashes ---. The content is parsed as YAML.

---
title: My Doc Title
more_data:
- Can be provided
- as: objects
or: arrays
---

引言(Quotes)

我们为 Markdown 中的引言(quotes)标记设置了漂亮的样式:

> Easy to maintain open source documentation websites.
>
> — Docusaurus
http://localhost:3000

Easy to maintain open source documentation websites.

— Docusaurus

<details> 元素

Markdown 中可以嵌入 HTML 元素。我们为 HTML 中的 details 元素设置了漂亮的样式:

### Details element example

<details>
<summary>Toggle me!</summary>
<div>
<div>This is the detailed content</div>
<br/>
<details>
<summary>
Nested toggle! Some surprise inside...
</summary>
<div>
😲😲😲😲😲
</div>
</details>
</div>
</details>
http://localhost:3000

Details element example

Toggle me!
This is the detailed content

Nested toggle! Some surprise inside...
😲😲😲😲😲
备注

其实,上面这些并不是真正的 HTML 元素,而实 React 的 JSX 元素。我们将在接下来的章节中详细说明!