Doucsaurus配置

July 15, 2024 · 10 min read

Front-end Engineer

create-docusaurus是一个创建 Docusaurus 应用的脚手架工具。

初始化项目：

npx create-docusaurus@latest my-website classic --typescript --package-manager pnpm

项目名：my-website
模板：classic
使用 typescript
使用 pnpm

如果查看 tsconfig.json 或者执行pnpm typecheck报错，安装以下依赖：

pnpm add -D @docusaurus/theme-classic @types/node

blog 配置

Docusaurus 博客功能由 blog plugin 提供支持。

只需将 Markdown 文件（或文件夹）添加到 blog 目录即可。文件夹便于将相关图片放在一起。

如果不想要博客就删除 blog 目录，在 docusaurus.config.ts 中配置 blog: false 即可。

文件命名

日期 + 标题，可以从文件名中提取文章日期，例如：2024-06-08-welcome.md
标题，例如：welcome.md，然后在文件中编写元数据 date ：

---
title: welcome
date: 2024-06-08
---

如果没有设置日期，则默认显示当天的日期。

以日期开头的文件，排序更清晰，但是会在路径中显示日期，如：/blog/2024/07/15/docusaurus

配置作者信息

可以将常规博客作者添加到 authors.yml 文件

authors.yml
zgh:
  name: zgh
  title: Front-end Engineer
  url: https://github.com/Ivanzgh
  image_url: https://avatars.githubusercontent.com/u/26456994?v=4

也可以直接在文件中配置，但是建议集中在一个地方，方便管理，使用 authors: zgh 即可。

---
title: First Blog Post
authors:
  name: zgh
  title: Front-end Engineer
  url: https://github.com/Ivanzgh
  image_url: https://avatars.githubusercontent.com/u/26456994?v=4
---

配置标签

tags.yml文件是集中管理标签的地方。配置 tags.yml 文件：

tags.yml
react:
  label: React
  permalink: /react
  description: React tag description
vue:
  label: Vue
  permalink: /vue
  description: Vue tag description
docusaurus:
  label: Docusaurus
  permalink: /docusaurus
  description: Docusaurus tag description

在文件开头写入以下内容，在页面的底部会显示标签。

---
tags:
  - react
  - docusaurus
---

tip

访问 /docs/tags，可以看到所有 tag
访问 /docs/archive，可以看到所有博客，归档

配置元数据

元数据配置文档

---
title: Doucsaurus配置
authors: zgh
tags: [docusaurus]
---

<!--truncate-->

slug: file-url自定义文件路径

隐藏更多内容

使用  限制博客列表内容的长度，点击「阅读更多」查看更多内容。

编写 MDX 文件

博客文章支持 Docusaurus Markdown 功能，例如 MDX。

可以创建一个.mdx 后缀的文件，例如 2024-01-01-docusaurus.mdx。也可以直接在 .md 后缀的文件中编写。

然后写入如下内容，点击按钮，实现交互效果。

<button onClick={() => alert('button clicked!')}>Click me!</button>

语言设置

编辑 docusaurus.config.js 文件：

{
  "i18n": {
    "defaultLocale": "zh", // 设置默认语言为中文
    "locales": ["en", "zh"] // 支持的语言列表
  }
}

右侧目录

默认显示 h2 和 h3 标题，范围是 h2 到 h6，可以设置单个文档或者全局设置

---
# 显示 h2 到 h5 标题
toc_min_heading_level: 2
toc_max_heading_level: 5
---

左侧边栏

如果未指定 sidebarPath ，Docusaurus 将使用 docs 文件夹的文件系统结构自动生成侧边栏：

// sidebars.js
export default {
  mySidebar: [{ type: 'autogenerated', dirName: '.' }]
};

如果在 sidebars.js 中指定了 link 配置，如下，会生成类似 TOC 的总览目录，在点击父级目录时会出现

{
  type: 'category',
  label: 'JavaScript',
  link: {
    type: 'generated-index'
  },
  items: []
}

目录实现手风琴效果，hideable 是控制左下角展开折叠按钮的属性

themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
        autoCollapseCategories: true
      }
    },
}

静态资源

静态资源都在 static 目录下，文档

在 markdown 中引用：

![img](/img/1.png)

markdown

链接

不能使用尖括号包裹到链接，要使用规范化的写法：[]()

点击展开收起内容

<details>
  <summary>点击展开</summary>
  内容
</details>

选项卡

1、嵌套简单内容：

import BrowserWindow from '@site/src/components/BrowserWindow';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<BrowserWindow>
  <Tabs>
    <TabItem value="apple" label="Apple">
      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>
</BrowserWindow>;

note

在 .md 中，像引入代码块一样先写三个反引号，然后挨着写 mdx-code-block 表示这块的类型，将下面示例中挨着三个反引号后的斜杠去掉。

```/mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```

2、嵌套代码：

先导入组件
用组件包裹代码，注意上下空格

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

<Tabs>
<TabItem value="js" label="JavaScript">

```js
function helloWorld() {
  console.log('Hello, world!');
}
```

</TabItem>
<TabItem value="py" label="Python">

```js
console.log(1);
```

</TabItem>
<TabItem value="css" label="CSS">

```css
width: 100%;
```

</TabItem>
</Tabs>

嵌套网页

import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow';

<IframeWindow url="https://www.processon.com/embed/64623e6407a1a76bf6d4a33a" height="600" />

<IframeWindow url="/docs/fe/js/ajax?docusaurus-theme=dark" />
<IframeWindow url="/docs/fe/js/ajax?docusaurus-theme=light" />

默认高度是 300，可以传入自定义 height

代码高亮支持更多语言

docusaurus 使用 prism 来对不同的语言进行语法高亮，这里是默认支持的语言列表，如果需要启用更多语言的支持，可以在 docusaurus.config.js 中配置下 additionalLanguages（点这里查看 prism 支持的所有语言的列表）:

themeConfig: {
  prism: {
    additionalLanguages: ['json', 'scss', 'less', 'bash', 'nginx'];
  }
}

按需开启

自定义组件

可以自定义组件，然后将其注册为全局组件

MDX and React

创建自定义组件：src/components/Highlight.js

import React from 'react';

export default function Highlight({ children, color }) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '2px',
        color: '#fff',
        padding: '0.2rem'
      }}
    >
      {children}
    </span>
  );
}

全局注册：src/theme/MDXComponents.js

import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';

export default {
  ...MDXComponents,
  Highlight
};

在 md 文件中使用

<Highlight color="#25c2a0">Docusaurus green</Highlight>

giscus 评论系统

1. 配置 giscus

给博客接入文章系统，采用 giscus，原理就是 Github 的 Discussion 评论系统。

先去创建一个公开的仓库，可以是单独的仓库，也可以是你博客的源代码仓库
将 giscus app安装到你的仓库中
启用 Discussion 功能，在仓库的 Settings -> Features -> Discussions，勾选上即可
回到 giscus 官网，填上仓库名，如 Ivanzgh/blog-comments
Discussion 分类选择 General
勾选上「将评论框放在评论上方」
最后得到一个 script 标签，等会填入下面的组件中，去掉data-、连字符变为小驼峰写法

然后安装 giscus 依赖：

pnpm add @giscus/react

2. 创建评论组件

在 src/components/GiscusComment.tsx 创建评论组件：

import Giscus from '@giscus/react';
import { useColorMode } from '@docusaurus/theme-common';

export default function GiscusComment() {
  const { colorMode } = useColorMode();
  const giscusTheme = colorMode === 'dark' ? 'dark' : 'light';
  return (
    <Giscus
      id="comments"
      repo="填入你的仓库名"
      repoId="填入你的repoId"
      category="填入你的category"
      categoryId="填入你的categoryId"
      mapping="pathname"
      term="Welcome to @giscus/react component!"
      strict="0"
      reactionsEnabled="1"
      emitMetadata="0"
      inputPosition="top"
      theme={giscusTheme}
      lang="zh-CN"
      loading="lazy"
    />
  );
}

如果在使用 useColorMode 时报错，可以安装依赖：pnpm add @docusaurus/theme-common

3. 配置主题

执行以下命令，会出现 src/theme/BlogPostItem 目录：

pnpm run swizzle @docusaurus/theme-classic BlogPostItem --wrap --typescript

如果项目不是使用 TS，可以省略 --typescript参数。

修改 src/theme/BlogPostItem/index.tsx：

import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import type BlogPostItemType from '@theme/BlogPostItem';
import type { WrapperProps } from '@docusaurus/types';
import GiscusComment from '@site/src/components/GiscusComment';
import { useLocation } from '@docusaurus/router';

type Props = WrapperProps<typeof BlogPostItemType>;

export default function BlogPostItemWrapper(props: Props): JSX.Element {
  const location = useLocation();
  const isBlogPostPage =
    location.pathname.startsWith('/blog/') &&
    !location.pathname.startsWith('/blog/tags') &&
    location.pathname !== '/blog';

  return (
    <>
      <BlogPostItem {...props} />
      {isBlogPostPage && <GiscusComment />}
    </>
  );
}

通过判断页面路由，只在博客详情页显示评论。过滤以下路径，否则也会显示评论：

博客列表页: /blog
某类标签的列表页: /blog/tags/xxx

踩坑记录

1. 打包报错

打包时一直报错 Error: Unable to build website for locale en. 可能的原因：

markdown 文档里有不规范的写法，如 iframe 的 style 要用 JSX 写、检查页面内部跳转链接是否正确
showLastUpdateTime 配置错误，它需要在构建期间访问 git 历史记录，仅适用于 Markdown 页面。如果在 markdown 里没有配置元数据 metadata，或者不是部署到 GitHub 上，就会报这种错误。

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          // showLastUpdateTime: true
          // showLastUpdateAuthor: true,
        }
      } satisfies Preset.Options
    ]
  ],

2. 使用 iframe 标签

如果使用了 iframe 链接，不能直接写 style="display:block;width:100%;height:500px;"，要写成 JSX

style={{display:'block',width:'100%',height:'500px'}}

相关属性要写成小驼峰格式，如：

allowfullscreen 写为 allowFullScreen
frameborder 写为 frameBorder

blog 配置​

文件命名​

配置作者信息​

配置标签​

配置元数据​

隐藏更多内容​

编写 MDX 文件​

语言设置​

右侧目录​

左侧边栏​

静态资源​

markdown​

链接​

点击展开收起内容​

选项卡​

嵌套网页​

代码高亮支持更多语言​

自定义组件​

giscus 评论系统​

1. 配置 giscus​

2. 创建评论组件​

3. 配置主题​

踩坑记录​

1. 打包报错​

2. 使用 iframe 标签​