Markdown 特性
文档是你的产品向用户展示的门面之一。 文从字顺、层次清晰的文章有助于用户快速了解您的产品。 我们的一致目标是帮助用户尽快找到所需要的信息。
Docusaurus 2 使用现代化工具来帮助你轻松撰写交互式文档。 你可以嵌入 React 组件,亦或是搭建用户可交互的实时代码编辑块。 就用代码呈现你的灵光一现,捕获你的受众的心吧! 这可能是吸引潜在用户的最有效的方式。
本章节假定你使用 Docusaurus 官方的内容插件。
Standard features
Markdown is a syntax that enables you to write formatted content in a readable syntax.
我们用 MDX 作为模板引擎,它能做的事情要比解析标准 Markdown 语法多得多,比如可以在文档中渲染 React 组件。
### 我的文档章节
一些文本,包括**粗体**、_斜体_,和[链接](/)
![图片 alt 文本](/img/docusaurus.png)
我的文档章节
一些文本,包括粗体、斜体,和链接
Markdown 是声明式的
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: 我的文档标题
其他内容:
- 可以以
- 对象: 或者
数组: 的形式给出
---
Quotes
Markdown quotes are beautifully styled:
> 易于维护开源文档网站。
>
> — Docusaurus
易于维护开源文档网站。
— Docusaurus
Details
Markdown can embed HTML elements, and details
HTML elements are beautifully styled:
### Details 元素示例
<details>
<summary>点我!</summary>
<div>
<div>这是详情内容</div>
<br/>
<details>
<summary>
嵌套的下拉栏! 内含惊喜……
</summary>
<div>😲😲😲😲😲</div>
</details>
</div>
</details>
Details 元素示例
点我!
嵌套的下拉栏! 内含惊喜……
In practice, those are not really HTML elements, but React JSX elements, which we'll cover next!