Skip to main content

Docusaurus

tip
  • 默认第一个段落内容作为 description
caution
  • Support ESM config file #5379
    • 无法使用 remark-defin, remark-image
  • Migration to ES Modules #6520
  • React 18 #7264
  • MDX 2.0 #4029
  • OOTB Mermaid code block #1258
    • v2.2

目录结构​

  • /
    • blog
    • docs
    • src
      • theme
      • css
        • custom.css
      • pages
        • styles.module.css
        • index.js
    • static/
      • img/
    • docusaurus.config.js
    • package.json
    • sidebars.js
tip
  • 支持 \```` - 方便包含 markdown codeblock
# [name] [template]
# @docusaurus/preset-classic
# @docusaurus/preset-bootstrap
npx @docusaurus/init@next init my-website classic
tip
  • link href 可指向 md, Docusaurus 会去掉 md 后缀
    • ./link - 无后缀也可以
    • ./link.md -> ./link - github 上也能识别
    • 绝对路径 - Github 上不可用
      • 基于内容目录 - /a/b.md -> /docs/a/b.md
      • 也可以直接写 /docs/a/b.md

自定义​

添加在文档开头

---
title: My Doc
---

<head>
  <html className="some-extra-html-class" />
  <body className="other-extra-body-class" />
  <title>Head Metadata customized title!</title>
  <meta charset="utf-8" />
  <meta name="twitter:card" content="summary" />
  <link rel="canonical" href="https://docusaurus.io/docs/markdown-features/head-metadata" />
</head>

# My Doc

Docs​

# 默认为文件名
id: doc-markdown
# 也支持 slug 控制 - 但一般不用
# slug: part1.html
# 默认为 id
title: Markdown Features
# hide_title 是否隐藏顶部标题 - 如果 markdown 本身包含了 title 可以考虑隐藏
hide_title: false
# 隐藏目录
hide_table_of_contents: false
# 默认为 title - 显示在左侧 sidebar 和上下文章位置
sidebar_label: Markdown :)
# 编辑地址 - 默认 editUrl 传递给 docusaurus-plugin-content-docs 插件
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
# 描述信息 - <meta name="description" content="..."/> <meta property="og:description" content="..."/>
# 默认为内容第一行
description: How do I find you when I cannot solve this problem
keywords:
  - docs
  - docusaurus
# thumbnail
image: https://i.imgur.com/mErPwqL.png

支持提示信息​

note

The content and title can include markdown.

自定义标题

Heads up! Here's a pro-tip.

info

Useful information.

caution

Warning! You better pay attention!

danger

Danger danger, mayday!

代码块支持标题​

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
  // Hello there
  return <h1>Hello, {props.name}</h1>;
}

Mermaid​

npm add @docusaurus/theme-mermaid
docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};

mermaid 支持 theme

%%{init: { "theme": "forest" } }%%

JSX Mermaid​

yarn add mermaid
src/theme/Mermaid.js
import React, { useEffect } from 'react';
import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
});

const Mermaid = ({ chart }) => {
  useEffect(() => {
    mermaid.contentLoaded();
  }, []);
  return <div className='mermaid'>{chart}</div>;
};

export default Mermaid;
doc.md
import Mermaid from '@theme/Mermaid';

<Mermaid
  chart={`
  graph LR;
    A-->B;
    B-->C;
    B-->D[plop lanflz eknlzeknfz];
`}
/>
graph LR; A-->B; B-->C; B-->D[plop lanflz eknlzeknfz];

docusaurus.config.js​

Docs​

  • sidebar

  • autogenerated

    • 支持 index.md, README.md, {__dirname}.md 作为 index
    • 使用 _category_.{json,yml,yaml} 作为类目元数据

  • export 多个 sidebar 则显示匹配的那一

    组

caution
  • 默认移除 数字 前缀 - 01-Intro.md -> intro
type SidebarItemDoc =
  | {
      type: 'doc';
      id: string;
      label: string;
      className?: string;
      customProps?: object; // 自定义属性 for swizzled sidebar item
    }
  | string;

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
};

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // Source folder to generate the sidebar slice from (relative to docs)
};

type SidebarItemRef = {
  type: 'ref';
  id: string;
};
frontmatter
id:
title:
description:
image:
slug:
tags: []

pagination_next: getting-started
pagination_prev: null
pagination_label: Label in pagination

sidebar_label: Easy
sidebar_position: 2
sidebar_class_name: green

hide_title: false
hide_table_of_contents: false
toc_min_heading_level: 2
toc_max_heading_level: 3

parse_number_prefixes: true
custom_edit_url:
keywords: []

Generator​

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // 自定义
        async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        },
      },
    ],
  ],
};
_category_.yml
position: 2.5
label: 'Tutorial'
collapsible: true
collapsed: true
className: red
# 作为 index 的 doc 信息
link:
  type: generated-index
  title: Tutorial overview

Blog​

frontmatter
title: Welcome to my blog
description: First blog
slug: welcome
authors:
  - name: wener
    title: Writer
    url: https://github.com/wenerme
    image_url: https://github.com/wenerme.png
tags: [hello, story]
image: https://github.com/wenerme.png
hide_table_of_contents: false
hide_reading_time: false

# 旧的方式
author:
author_title:
author_url:
author_image_url:

# 预定义 author
# website/blog/authors.yml
# website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
authors: wener
authors: [wener]

magicComments​

type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: { start: string; end: string };
};
module.exports = {
  themeConfig: {
    prism: {
      magicComments: [
        // Remember to extend the default highlight class name as well!
        {
          className: 'theme-code-block-highlighted-line',
          line: 'highlight-next-line',
          block: { start: 'highlight-start', end: 'highlight-end' },
        },
        {
          className: 'code-block-error-line',
          line: 'This will error',
        },
      ],
    },
  },
};

参考​

Version

Docusaurus v3​

Table span​

| Head 1 | Head 2 | Head 3 | Head 4 | Head 4 |
| :----: | :----: | :----: | :----: | :----: |
| (2x1)  |   <    |  Cell  |  Cell  |  Cell  |
| (1x3)  | (2x2)  |   <    | (2x2)  |   <    |
|   ^    |   ^    |   <    |  Cell  |  Cell  |
|   ^    | (3x1)  |   <    |   <    |  Cell  |