跳到主要内容

Markdown 功能

Markdown 功能​

Docusaurus 使用 Markdown 作为其主要内容创作格式。

提示

学习 MARKDOWN

你可以 10 分钟学会 Markdown。

Docusaurus 使用现代工具来帮助你创建交互式文档。

MDX 编译器将 Markdown 文件转换为 React 组件，并允许你在 Markdown 内容中使用 JSX。这使你能够轻松地在内容中交错 React 组件，并创造令人愉快的学习体验。

信息

使用 MDX PLAYGROUND

MDX 在线运行 是你最好的新朋友！

它是一个非常有用的调试工具，展示了 MDX 编译器如何将 Markdown 转换为 React。

选项：选择正确的格式（MDX 或 CommonMark）以及 Docusaurus 使用的以下插件：remark-gfm、remark-directive、rehype-raw。

MDX 对比 CommonMark​

Docusaurus 使用 MDX 编译器将 .md 和 .mdx 文件编译为 React 组件，但根据你的设置，语法可能会有不同的解释。

MDX 编译器支持 2 种格式：

  • MDX 格式：一个强大的解析器，允许使用 JSX
  • 通用标记格式：一个符合标准的 Markdown 解析器，不允许使用 JSX

默认情况下，由于历史原因，Docusaurus v3 对所有文件（包括 .md 文件）使用 MDX 格式。

可以使用 siteConfig.markdown.format 设置或 format: md 前面的内容选择加入 CommonMark。

提示

如何使用 COMMONMARK

如果你计划使用 CommonMark，我们建议使用 siteConfig.markdown.format: 'detect' 设置。将根据文件扩展名自动选择适当的格式：

  • .md 文件将使用 CommonMark 格式
  • .mdx 文件将使用 MDX 格式
危险

实验性 COMMONMARK 支持

CommonMark 支持是实验性的，目前有一些 limitations。

标准功能​

Markdown 是一种语法，使你能够以可读的语法编写格式化内容。

### My Doc Section

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

![img alt](/img/docusaurus.png)

http://localhost:3000

image-20240908213948152

Markdown is declarative

信息

有些人可能会假设 Markdown 和 HTML 之间存在 1-1 的相关性，例如 ![Preview](/img/docusaurus.png) 总是会变成 <img src="/img/docusaurus.png" alt="Preview" />。然而，事实并非如此。

Markdown 语法 ![message](url) 只是声明性地告诉 Docusaurus 需要在此处插入图片，但我们可能会做其他事情，例如转换 文件路径到 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出不同，或者是对 等效的 JSX/HTML 代码。

一般来说，你应该只假设标记的语义（````` 栅栏变成 代码块；> 变成 quotes，等等），而不是实际的编译输出。

前言​

Front Matter 用于将元数据添加到 Markdown 文件中。所有内容插件都有自己的前题模式，并使用前题来丰富从内容或其他配置推断出的默认元数据。

前言位于文件的最顶部，由三个破折号 --- 括起来。内容被解析为 YAML。

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

每个官方插件的 API 文档列出了支持的属性：

增强你的头条新闻

使用 Markdown 配置 parseFrontMatter 功能 提供你自己的前端解析器，或增强默认解析器。

可以重用默认解析器，用你自己的自定义专有逻辑封装它。这使得实现方便的 Front Matter 转换、快捷方式或使用 Docusaurus 插件不支持的 Front Matter 与外部系统集成成为可能。

docusaurus.config.js

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 引号的样式很漂亮：

> Easy to maintain open source documentation websites.
>
> — Docusaurus

http://localhost:3000

image-20240912074218674

细节​

Markdown 可以嵌入 HTML 元素，details 个 HTML 元素的样式很漂亮：

### 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.nodejs.cn)
  <details>
    <summary>Nested toggle! Some surprise inside...</summary>

    😲😲😲😲😲
  </details>
</details>
<BrowserWindow>

<h3>Details element example</h3>

<details>
  <summary>Toggle me!</summary>

  This is the detailed content

  ```

js console.log("包括代码块在内的 Markdown 功能可用");

¥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.nodejs.cn)
<details>
  <summary>Nested toggle! Some surprise inside...</summary>

  😲😲😲😲😲
</details>
</details>

</BrowserWindow>
```
信息

你可能希望将 <summary> 放在一行上。请记住 MDX 创建额外的 HTML <p> 段落用于换行。。如有疑问，请使用 MDX 在线运行 解决 <details> 渲染问题。

¥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.

最后由 One 于 更新
0%