Doucsaurus配置

2024年7月15日 · 阅读需 12 分钟

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

CLI 命令解析

https://docusaurus.io/docs/cli

在 package.json 中，可以找到以下命令：

{
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "typecheck": "tsc"
  }
}

docusaurus：运行 Docusaurus 命令
start：启动开发服务器，访问 http://localhost:3000
build：构建项目，生成静态文件
swizzle：用于自定义主题，修改默认主题
deploy：将构建好的静态文件部署到 GitHub Pages
clear：清除缓存
serve：启动本地服务器托管构建后的项目
write-translations：生成翻译文件，用于翻译
write-heading-ids：为标题添加 id，方便跳转
typecheck：类型检查

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

提示

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

配置元数据

元数据配置文档

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

<!--truncate-->

slug: file-url 自定义文件路径
draft: true 草稿

隐藏更多内容

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

编写 MDX 文件

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

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

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

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

swizzle

swizzle 支持自定义布局，可以在默认主题的基础上，修改某些组件。

例如修改博客详情组件，执行以下命令，会出现 src/theme/BlogPostItem 目录：

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

参数说明：

--wrap：包裹组件，不涉及内部实现
--eject：直接修改组件源代码
--typescript：使用 TypeScript 编写组件

语言设置

设置默认语言

编辑 docusaurus.config.js 文件：

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

修改默认文字

比如在博客页面的底部有「较新一篇」和「较旧一篇」，想将其修改为「上一篇」和「下一篇」。可以使用 i18n 自定义翻译：

1、执行以下命令会在根目录下生成 i18n 文件夹：

pnpm run write-translations

2、在 i18n/zh-Hans/code.json 中修改：

{
  "theme.blog.post.paginator.newerPost": {
    "message": "上一篇",
    "description": "The blog post button label to navigate to the newer/previous post"
  }
}

如果没有生效，可以尝试重启服务。

右侧目录

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

例如设置某篇 blog 显示 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 是控制左下角展开折叠按钮的属性：

const config = {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
        autoCollapseCategories: true
      }
    }
  }
};

自定义 URL 路径

默认情况下可以访问如：xxx.com/docs/1 和 xxx.com/blog/1，即 URL 路径中会包含 docs 和 blog。如果想定义 docs 和 blog 以外的路径，如 xxx.com/code/1，可以在根目录新建一个 code 文件夹，里面放一些 md 文件，然后配置 docusaurus.config.js。

自定义 docs 类型

const config = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'code', // 自定义插件 ID
        path: 'code', // 对应文件夹
        routeBasePath: 'code', // 路由前缀
        sidebarPath: {} // 自定义侧边栏文件
      }
    ]
  ]
};

自定义 blog 类型

const config = {
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        id: 'code', // 自定义插件 ID
        path: 'code', // 对应文件夹
        routeBasePath: 'code', // 路由前缀
        showReadingTime: true, // 是否显示阅读时间
        blogTitle: 'Code Snippets', // 博客标题，配置网站的 <title>
        blogDescription: 'A collection of code snippets.', // 博客描述，配置 <meta description>
        postsPerPage: 10, // 每页显示的文章数
        blogSidebarTitle: 'All Snippets', // 侧边栏标题
        blogSidebarCount: 'ALL' // 左侧边栏显示的文章数。设置为 0，则不显示侧边栏。设置为'ALL'，则显示全部
      }
    ]
  ]
};

静态资源

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

在 markdown 中引用：

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

如果要引用本地中的其他文件，以根路径开始 /，例如：

[React 概览](/docs/react/index.md)

路径别名：@site 表示根路径。例如：

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

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>;

备注

在 .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'];
  }
}

按需开启要支持的语言

配置主题样式

1、可以在src/css/custom.css中配置主题样式，然后在docusaurus.config.js中引入：

const config = {
  presets: [
    [
      'classic',
      {
        theme: {
          customCss: './src/css/custom.css'
        }
      }
    ]
  ]
};

2、自定义代码块的样式可以使用 prism-react-renderer。可以直接使用或者修改其自带的样式。在docusaurus.config.js中配置：

import { themes as prismThemes } from 'prism-react-renderer';

const config = {
  themeConfig: {
    prism: {
      theme: prismThemes.oneLight,
      darkTheme: prismThemes.vsDark
    }
  }
};

自定义组件

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

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>

踩坑记录

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

CLI 命令解析​

blog 配置​

文件命名​

配置作者信息​

配置标签​

配置元数据​

隐藏更多内容​

编写 MDX 文件​

swizzle​

语言设置​

设置默认语言​

修改默认文字​

右侧目录​

左侧边栏​

自定义 URL 路径​

自定义 docs 类型​

自定义 blog 类型​

静态资源​

markdown​

链接​

点击展开收起内容​

选项卡​

嵌套网页​

代码高亮支持更多语言​

配置主题样式​

自定义组件​

踩坑记录​

1. 打包报错​

2. 使用 iframe 标签​