跳到主要内容

配置

信息

查看 docusaurus.config.js API 参考 获取详尽的选项列表。

道格龙（Docusaurus） 对配置有独特的处理方式。我们鼓励您将网站的相关信息集中到一个地方。我们会保护此文件中的字段，并方便您在整个网站中访问这些数据对象。

维护一个良好的 docusaurus.config.js 文件可以帮助您、您的协作者以及开源贡献者在专注于文档整理的同时，仍然能够自定义网站。

docusaurus.config.js 的声明语法​

docusaurus.config.js 文件在 Node.js 中运行，并且应该导出一个：

  • 配置对象
  • 创建配置对象的 函数
信息

docusaurus.config.js 文件支持：

约束条件：

  • 必需： 使用 export default /* your config*/ (或 module.exports) 来导出您的 道格龙（Docusaurus） 配置
  • 可选： 使用 import Lib from 'lib' (或 require('lib')) 来导入 Node.js 包

道格龙（Docusaurus） 允许我们以多种 等效的方式 声明其配置，以下所有配置示例都会产生完全相同的结果：

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.js
module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
} satisfies Config;
docusaurus.config.js
const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

export default config;
docusaurus.config.js
export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
使用仅支持 ESM 的包

使用异步配置创建器对于导入仅支持 ESM 的模块（特别是大多数 Remark 插件）非常有用。通过动态导入可以导入这些模块：

docusaurus.config.js
export default async function createConfigAsync() {
  // 使用动态导入，而不是 require('esm-lib')
  const lib = await import('lib');

  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // rest of your site config...
  };
}

docusaurus.config.js 中包含哪些内容？​

即使您正在开发自己的网站，也不应该从头开始编写 docusaurus.config.js。所有模板都附带一个 docusaurus.config.js 文件，其中包含了常用选项的默认值。

但是，如果您对配置的设计和实现方式有一个宏观的了解，将会很有帮助。

道格龙（Docusaurus） 配置的宏观概述可以分为以下几类：

网站元数据​

网站元数据包含一些必要的全局元数据，如 title、url、baseUrl 和 favicon。

它们用于多个地方，例如您网站的标题、浏览器标签页图标、社交分享（Facebook、X）信息，甚至包括为图片等静态文件生成正确的访问路径。

部署配置​

部署配置（如 projectName、organizationName 和可选的 deploymentBranch）在您使用 deploy 命令部署网站时使用。

建议查看 部署文档 以获取更多信息。

主题、插件和预设配置​

分别在 themes、plugins 和 presets 字段中列出您网站的 主题、插件 和 预设。这些通常是 npm 包：

docusaurus.config.js
export default {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};
提示

道格龙（Docusaurus）支持 模块简写，允许您将上述配置简化为：

docusaurus.config.js
export default {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

它们也可以从本地目录加载：

docusaurus.config.js
import path from 'path';

export default {
  // ...
  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

要为插件或主题指定选项，请在配置文件中将插件或主题的名称替换为一个包含名称和选项对象的数组：

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

要为预设中捆绑的插件或主题指定选项，请通过 presets 字段传递选项。在此示例中，docs 指的是 @docusaurus/plugin-content-docs，theme 指的是 @docusaurus/theme-classic。

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};
提示

presets: [['classic', {...}]] 的简写方法同样有效。

有关配置主题、插件和预设的更多帮助，请参阅使用插件。

自定义配置​

道格龙（Docusaurus） 会保护 docusaurus.config.js 免受未知字段的影响。要添加自定义字段，请在 customFields 中定义它们。

示例：

docusaurus.config.js
export default {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

从组件访问配置​

您的配置对象将对网站的所有组件可用。您可以通过 React context 将其作为 siteConfig 进行访问。

基本示例：

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};
提示

如果您只想在客户端使用这些字段，可以创建自己的 JS 文件并将其作为 ES6 模块导入，无需将它们放在 docusaurus.config.js 中。

自定义 Babel 配置​

道格龙（Docusaurus） 默认使用 Babel 来转译您网站的源代码。如果您想自定义 Babel 配置，可以通过在项目根目录中创建一个 babel.config.js 文件来实现。

要使用内置的预设作为基础配置，请安装以下包并使用它

npm install --save @docusaurus/babel

然后在您的 babel.config.js 文件中使用该预设：

babel.config.js
export default {
  presets: ['@docusaurus/babel/preset'],
};

大多数情况下，默认的预设配置就可以正常工作。如果您想自定义您的 Babel 配置（例如，添加对 Flow 的支持），您可以直接编辑此文件。为了使您的更改生效，您需要重新启动 道格龙（Docusaurus） 的开发服务器。