跳到主要内容

配置

信息

查看 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',
    // 您网站配置的其余部分...
  };
}

docusaurus.config.js 中包含的内容​

即使您正在开发您的网站，也不必从头开始编写 docusaurus.config.js。所有模板都带有包含常见选项默认值的 docusaurus.config.js。

但是，如果您对配置的设计和实现方式有高级了解，则会很有帮助。

Docusaurus 配置的高级概述可以分为：

站点元数据​

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

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

部署配置​

当您使用 deploy 命令部署站点时，会使用部署配置，例如 projectName、organizationName 和可选的 deploymentBranch。

建议查看 部署文档 以了解更多信息。

主题、插件和预设配置​

分别在 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 上下文将其访问为 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 开发服务器。

编辑此页
最后由 HomeUbuntu 于 更新