跳到主要内容

Docusaurus 快速教程

0. 准备工作​

0. 安装nodejs​

Ubuntu 24.04 LTS apt 源只提供nodejs V18.x，此版本可能存在内存泄露问题，官方提供的 nodejs V20.x 需要手动下载配置环境变量。

1. 创建项目​

npx create-docusaurus@latest my-website classic

2.项目结构​

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

3. 启动项目​

cd my-website
npm run start

默认地址 http://localhost:3000

4. 编译部署项目​

npm run build
cp -r build/*  path/to/your/deploy/path

1. 自定义配置​

1.1 数学公式支持​

1.1.1 安装插件​

npm install --save remark-math@6 rehype-katex@7

1.1.2 配置​

vi docusaurus.config.js

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          remarkPlugins: [remarkMath],
          rehypePlugins: [rehypeKatex],
        },
      },
    ],
  ],

  stylesheets: [
    {
      # 下载css 文件 和 css用到的字体文件
      href: '/katex/katex.css',
      type: 'text/css',
      ## 使用CDN
      <!-- href: 'https://cdn.jsdelivr.net.cn/npm/[email protected]/dist/katex.min.css',
      type: 'text/css',
      integrity:
        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
      crossorigin: 'anonymous', -->
    },
  ],
};

1.1.3 规范化markdown书写​

提示
  • html 标签需要全部闭合，例如<br>标签需写成<br/>，有些标准不需要闭合，但是docusaurus 要求标签必须闭合
  • 块 数学公式，需注意$$...$$前和后需要有换行，不能和文字在一行内，尤其中文的情况

2. 常用组件​

2.1 告示​

:::note
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::tip
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::info
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::warning
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::

:::danger
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
备注

Some content with Markdown syntax. Check this api.

提示

Some content with Markdown syntax. Check this api.

信息

Some content with Markdown syntax. Check this api.

注意

Some content with Markdown syntax. Check this api.

危险

Some content with Markdown syntax. Check this api.

提示

docusaurus和 sphinx myst 格式略有差异

sphinx myst tip
:::```

2.2 选项卡和sphinx完全不同​

注意

后面必须有空行

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

This is an apple 🍎

2.2 高亮代码​

`// highlight-next-line`
高亮行


`// highlight-start`
高亮内容
...
`// highlight-end`