Docusaurus 是 Facebook 开源的一个静态网站生成器，主要用来给开源项目生成帮助文档或博客。我开源的博客主题 MWordStar 的使用文档就是用 Docusaurus 生成的。

Docusaurus 的功能和 HEXO 或 Jekyll 差不多，可以根据 Markdown 文件生成静态页面，可以直接部署到 Github Pages 之类的纯静态环境。

Docusaurus 会使用 React 构建，生成的页面可以实现无刷新跳转，同时 Docusaurus 也会生成独立的 HTML 页面，可以让搜索引擎获取页面内容。

这里就简单写一下 Docusaurus 的配置和使用。

Github https://github.com/facebook/docusaurus

安装

Docusaurus 是使用 Node.js 开发的，安装 Docusaurus 之前需要确保电脑上已经安装了 Node.js。

使用 npm 安装：

npx @docusaurus/init@next init my-website classic

其中的 my-website 就是你的项目或文档名称，classic 是 Docusaurus 的默认模板名称。

安装完成后会生成一个 my-website 的目录，这个 my-website 目录相当于就是一个前端项目，其中就包含了 node_modules、.gitignore、package.json、package-lock.json、README.md。

运行和编译

进入项目目录后可以输入：

npm run start

运行项目。

Docusaurus 编译后会启动一个本地服务器，在浏览器中输入 localhost:3000 即可访问页面。

如下：

Docusaurus页面截图

如果更改了内容，页面也会自动刷新。

编译为静态页面：

npm run build

编译完成后会在项目根目录生成一个 build 目录，页面文件就在 build 目录中，你可以把 build 目录中的内容上传到服务器或 Github Pages。

Docusaurus 还能自动生成 sitemap 文件，不过在不配置的情况下生成的 Docusaurus 文件是无法使用的。

撰写文档

在项目目录下有一个 docs 目录，文档的 Markdown 文件就放在 docs 目录中。

Markdown 文件的开头格式如下：

---
id: doc1
title: Style Guide
---

id 是用来配置侧边栏的。title 就是文章标题，会显示在侧边栏。

侧边栏配置

编写玩文档后是不会出现在页面中的，需要先配置侧边栏。

在项目根目录有一个 sidebars.js，这就是侧边栏的配置文件。

配置文件的格式如下：

module.exports = {
  someSidebar: ['doc1', 'doc2', 'doc3'],
};

其中 someSidebar 数组中的内容就是 Markdown 文件开头的 ID。

下面是 3 个 Markdown 文件的 ID 和标题：

---
id: doc1
title: Style Guide
---
---
id: doc2
title: Document Number 2
---
---
id: doc3
title: This is Document Number 3
---

使用上面的侧边栏配置，页面侧边栏如下：

Docusaurus侧边栏

侧边栏的标题就是 Markdown 文件开头 title 后面的内容。

你也可以配置多级侧边栏，如下：

module.exports = {
  someSidebar: [
    'install',
    {
      组件: ['button', 'table'],
    },
  ],
};

其中的 install、button、table 都是文件 ID。

下面是 3 个文件的 ID 和标题：

install.md：

---
id: install
title: 安装
---

button.md：

---
id: button
title: 按钮
---

table.md：

---
id: table
title: 表格
---

多级侧边栏的效果如下：

Docusaurus多级侧边栏

配置站点信息

在项目根目录有一个 docusaurus.config.js，这就是站点配置文件，可以配置站点信息、页头、页脚。

站点信息

站点信息的部分：

module.exports = {
  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook',
  projectName: 'docusaurus',
};

下面是配置项说明：

  • title：站点标题，显示在浏览器标签页。
  • tagline：网站简介，显示在 meta 标签，可以给搜索结果提供摘要。
  • url：网站域名，用于生成 sitemap 文件。
  • baseUrl：资源文件的路劲。
  • favicon：站点图标的位置，站点图标会显示在标签页标题的前面。
  • organizationName：公司或组织名称。
  • projectName：项目名称。

页头配置

还是在 docusaurus.config.js 中的 module.exports 对象中配置：

module.exports = {
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      links: [
        {
          to: 'docs/install/',
          activeBasePath: 'docs/',
          label: 'Docs',
          position: 'left',
        },
        { to: 'blog', label: 'Blog', position: 'left' },
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
  },
};

navbar 中的内容就是页头配置，下面是一些配置项说明：

  • title：页头的标题。
  • logo.alt：页头 Logo 的描述，相当于 img 的 alt。
  • logo.src：页头 Logo 的图片地址。

links中的内容是页头导航链接配置，下面是配置项说明：

  • to：路由链接的跳转地址，地址就是 docs 目录中的文件名，不需要加 md。
  • activeBasePath：设置要处于选中状态的路劲，如果设置为 docs，只要访问 docs 目录中的页面，设置了 docs 的链接样式就是选中状态。
  • label：链接标签中的文字内容。
  • position：链接定位，left 居左，right 居右。
  • href：链接跳转地址，相当于 a 的 href，一般用于外部链接跳转。

href 设置的地址是不能无刷新跳转的，只有 to 才能无刷新跳转，但是 to 只能设置内容链接，而且需要使用相对路劲。

页脚配置

页脚配置也是在 docusaurus.config.js 的 module.exports对象中。

下面是页脚配置：

module.exports = {
  themeConfig: {
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Style Guide',
              to: 'docs/',
            },
            {
              label: 'Second Doc',
              to: 'docs/install/',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

footer 和 上面的 navbar 一样都是写在 themeConfig 中。

links 中的数组是链接组，一个链接组中可以包含多个链接。链接的属性还是和页头的链接属性是一样的，只是没有 position。

copyright 是页脚的版权信息。

首页配置

在项目目录中有一个 src 目录，src 目录中又有一个 pages 目录，pages 目录中的 index.js 就是首页文件。

在 index.js中有一个 features 数组，数组中的内容就是首页的项目描述。

features数组内容：

const features = [
  {
    title: <>Easy to Use</>,
    imageUrl: 'img/undraw_docusaurus_mountain.svg',
    description: (
      <>
        Docusaurus was designed from the ground up to be easily installed and
        used to get your website up and running quickly.
      </>
    ),
  },
  {
    title: <>Focus on What Matters</>,
    imageUrl: 'img/undraw_docusaurus_tree.svg',
    description: (
      <>
        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
        ahead and move your docs into the <code>docs</code> directory.
      </>
    ),
  },
  {
    title: <>Powered by React</>,
    imageUrl: 'img/undraw_docusaurus_react.svg',
    description: (
      <>
        Extend or customize your website layout by reusing React. Docusaurus can
        be extended while reusing the same header and footer.
      </>
    ),
  },
];

首页项目描述如下：

Docusaurus首页描述

可以根据上图中的内容修改 图片 URL、标题、描述文本，也可以增加或删除一组描述内容。

要更改元素结构或属性可以在 index.js 中的 Feature 函数中更改。

撰写博客

博客页面如下：

Docusaurus博客

博客的 Markdown 文件存放在项目目录下的 blog 目录中。

博客的 Markdown 文件开头也需要填写文章信息，如下：

---
id: vscode
title: VSCode 远程开发配置
author: Mr. Ma
author_title: 程序员
author_url: https://github.com/wgao19
author_image_url: https://www.misterma.com/img/avatar.jpg
tags: [VScode, 远程开发]
---

下面是文章信息说明：

  • id：文章 ID，用于自定义 URL 地址。
  • title：文章标题。
  • author：作者。
  • author_title：作者描述。
  • author_url：作者个人主页的 URL。
  • author_image_url：作者的头像图片 URL。
  • tags：文章标签，格式类似于数组。

以上就是 Docusaurus 的简单使用和配置，我这里只是写了一部分 Docusaurus 的配置，如果需要查看更详细的配置和说明可以访问 https://v2.docusaurus.io/。