Markdown 特性
Docusaurus使用 Markdown 作为其主要内容格式。
你可以10分钟速通 Markdown。
Docusaurus 使用现代化工具来帮助你轻松撰写交互式文档。
The MDX compiler transforms Markdown files to React components, and allows you to use JSX in your Markdown content. This enables you to easily interleave React components within your content, and create delightful learning experiences.
The MDX playground is your new best friend!
It is a very helpful debugging tool that shows how the MDX compiler transforms Markdown to React.
Options: select the right format (MDX or CommonMark) and the following plugins Docusaurus uses: 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 种格式：
- The MDX format: a powerful parser allowing the usage of JSX
- The CommonMark format: a standard-compliant Markdown parser that does not allow the usage of JSX
By default, Docusaurus v3 uses the MDX format for all files (including .md files) for historical reasons.
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:
.mdfiles will use the CommonMark format.mdxfiles will use the MDX format
The CommonMark support is experimental and currently has a few limitations.
标准功能
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
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: 我的文档标题
其他内容:
- 可以以
- 对象: 或者
数组: 的形式给出
---
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;
},
},
};
Quotes
Markdown quotes are beautifully styled:
> 易于维护开源文档网站。
>
> — 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...
You may want to keep your <summary> on a single line. Keep in mind that MDX creates extra HTML <p> paragraphs for line breaks.. When in doubt, use the MDX playground to troubleshoot <details> rendering problems.