Skip to main content
Version: 3.7.0

配置

info

查看docusaurus.config.js API参考以获取完整的选项列表。

Docusaurus 在配置方面有独特的见解。我们鼓励您将有关您网站的信息集中到一个地方。我们保护此文件的字段，并促进使这个数据对象在您的网站上可访问。

保持一个良好维护的docusaurus.config.js有助于你、你的合作者以及你的开源贡献者能够专注于文档，同时仍然能够自定义网站。

声明 docusaurus.config.js 的语法​

docusaurus.config.js 文件在 Node.js 中运行，并且应该导出以下内容之一：

  • 一个 配置对象
  • 一个函数，用于创建配置对象
info

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 ...
  };
}
Using ESM-only packages

使用异步配置创建器可以有助于导入仅支持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',
    // 其余的站点配置...
  };
}

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'],
};
tip

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'],
        },
      },
    ],
  ],
};
tip

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

如需进一步帮助配置主题、插件和预设，请参阅使用插件。

自定义配置​

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

示例：

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

从组件访问配置​

您的配置对象将对您网站的所有组件可用。您可以通过React上下文以siteConfig的形式访问它们。

基本示例：

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

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

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

如果您只想在客户端使用这些字段，您可以创建自己的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开发服务器。