Markdown 特性
Docusaurus使用 Markdown 作为其主要内容格式。
你可以10分钟速通 Markdown。
Docusaurus 使用现代化工具来帮助你轻松撰写交互式文档。
MDX 编译器将 Markdown 文件转换成 React 组件,并允许您在 Markdown 内容中使用 JSX。 这使得您能够轻松地将 React 组件在您的内容中进行交互,并创造愉快的学习体验。
MDX 游乐场 是您最好的朋友!
这是一个非常有用的调试工具,显示 MDX 编译器如何将 Markdown 转换为 React。
选项: 选择正确的格式 (MDX 或 CommonMark) 和以下插件: remark-gfm
, remark-directive
, rehype-raw
MDX 与 CommonMark 的对比
Docusaurus 会通过 MDX 编译器把 .md
和 .mdx
文件都编译成 React 组件。 but the syntax can be interpreted differently depending on your settings.
MDX 编译器支持 2 种格式:
- MDX 格式: 一个允许使用 JSX 的强大解析器
- CommonMark format: 一个符合标准的Markdown 解析器,不允许使用 JSX
出于一些历史原因,默认情况下, Docusaurus v3 对所有文件使用 MDX 格式(包括 .md
文件)。
It is possible to opt-in for CommonMark using the siteConfig.markdown.format
setting or the mdx.format: md
front matter.
If you plan to use CommonMark, we recommend the siteConfig.markdown.format: 'detect'
setting. The appropriate format will be selected automatically, based on file extensions:
.md
文件将使用 CommonMark 格式.mdx
文件将使用 MDX 格式
此功能是实验性的 ,目前有几个限制。
标准功能
Markdown 是一种能让你撰写易读的格式化内容的语法。
### 我的文档章节
一些文本,包括**粗体**、_斜体_,和[链接](/)

Markdown 是声明式的
Some may assume a 1-1 correlation between Markdown and HTML, e.g., 
will always become <img src="/img/docusaurus.png" alt="Preview" />
, as-is. However, that is not the case.
The Markdown syntax 
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) 来给你的 Markdown 文件添加元数据。 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.
前言是在文件的最顶端给出的,两端由三个横线 ---
包围。 内容被解析为 YAML
---
title: 我的文档标题
其他内容:
- 可以以
- 对象: 或者
数组: 的形式给出
---
Use the Markdown config parseFrontMatter
function to provide your own front matter parser, or to enhance the default parser.
It is possible to reuse the default parser to wrap it with your own custom proprietary logic. This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.
export default {
markdown: {
parseFrontMatter: async (params) => {
// Reuse the default parser
const result = await params.defaultParseFrontMatter(params);
// Process front matter description placeholders
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Create your own front matter shortcut
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Rename an unsupported front matter coming from another system
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
引文
Markdown 引文有着漂亮的样式:
> 易于维护开源文档网站。
>
> — Docusaurus
易于维护开源文档网站。
— Docusaurus
细节
Markdown 可以嵌入 HTML 元素,and details
HTML elements are beautifully styled:
### Details element example
<details>
<summary>Toggle me!</summary>
This is the detailed content
```js
console.log("Markdown features including the code block are available");
```
You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.io)
<details>
<summary>Nested toggle! Some surprise inside...</summary>
😲😲😲😲😲
</details>
</details>
Details element example
Toggle me!
This is the detailed content
console.log("Markdown features including the code block are available");
You can use Markdown here including bold and italic text, and inline link 😲😲😲😲😲Nested toggle! Some surprise inside...
您可能想要将您的 <summary>
保留在单行上。 Keep in mind that MDX creates extra HTML <p>
paragraphs for line breaks.. 如有疑问,请使用 MDX 播放场 来排除 <details>
呈现问题。