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 |