3、配置

配置

原文

https://docusaurus.nodejs.cn/docs/configuration

正文

信息

检查 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.nodejs.cn',
  // your site config ...
};

docusaurus.config.js

module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};

docusaurus.config.ts

import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
} satisfies Config;

docusaurus.config.js

const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.nodejs.cn',
  // your site config ...
};

export default config;

docusaurus.config.js

export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // your site config ...
  };
}

docusaurus.config.js

export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.nodejs.cn',
    // your site config ...
  };
}

提示

使用仅限 ESM 的软件包:（待研究？？？）

使用异步配置创建器对于导入仅限 ESM 的模块（尤其是大多数 Remark 插件）非常有用。由于动态导入，可以导入此类模块：

docusaurus.config.js

export default async function createConfigAsync() {
  // Use a dynamic import instead of require('esm-lib')
  const lib = await import('lib');

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

docusaurus.config.js 包含什么？

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

但是，如果你对配置的设计和实现方式有深入的了解，这会很有帮助。

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

站点元数据

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

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

部署配置

当你使用 deploy 命令部署站点时，将使用 projectName、organizationName 和可选的 deploymentBranch 等部署配置。

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

主题、插件和预设配置

在 themes、plugins 和 presets 字段中分别列出你站点的 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.js 中。

自定义 Babel 配置

对于新的 Docusaurus 项目，我们在项目根目录中自动生成了 babel.config.js。

babel.config.js

export default {
  presets: ['@docusaurus/core/lib/babel/preset'],
};

大多数时候，这个配置就可以正常工作。如果你想自定义 Babel 配置（例如添加对 Flow 的支持），可以直接编辑此文件。为了使更改生效，你需要重新启动 Docusaurus 开发服务器。

在线运行

Playgrounds 允许你在浏览器中运行 Docusaurus，无需安装任何东西！

它们主要用于：

测试 Docusaurus
报告错误

使用 docusaurus.new 作为易于记住的快捷方式。

选择下面的可用选项之一。

📦 CodeSandbox

CodeSandbox is an online code editor and development environment that allows developers to create, share and collaborate on web development projects in a browser-based environment

CodeSandbox是一个在线代码编辑器和开发环境，允许开发人员在基于浏览器的环境中创建、共享和协作web开发项目

Try it now!

JavaScript TypeScript

⚡ StackBlitz 🆕

StackBlitz uses a novel WebContainers technology to run Docusaurus directly in your browser.

StackBlitz使用了一种新颖的WebContainers在浏览器中直接运行Docusaurus的技术。

Try it now!

JavaScript TypeScript

提示

为了方便起见，我们会在你下次访问 docusaurus.new 时记住你的选择。

TypeScript 支持

提示

Docusaurus 用 TypeScript 编写，并提供一流的 TypeScript 支持。

所需的最低版本是 TypeScript 5.1。

初始化

Docusaurus 支持编写和使用 TypeScript 主题组件。如果 init 模板提供 TypeScript 变体，你可以使用 --typescript 标志直接初始化具有完整 TypeScript 支持的站点。

npx create-docusaurus@latest my-website classic --typescript

以下是有关如何将现有项目迁移到 TypeScript 的一些指南。

设置

将以下包添加到你的项目中：

提示

npm
Yarn
pnpm

npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types

yarn add --dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types

pnpm add --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types

然后将 tsconfig.json 添加到项目根目录，内容如下：

tsconfig.json

{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "baseUrl": "."
  }
}

信息

Docusaurus 不使用此 tsconfig.json 来编译你的项目。添加它只是为了获得更好的编辑器体验，尽管你可以选择运行 tsc 来为自己或在 CI 上类型检查你的代码。

现在你可以开始编写 TypeScript 主题组件。

键入配置文件

可以在 Docusaurus 中使用 TypeScript 配置文件。

docusaurus.config.ts

import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',

  /* Your site config here */

  presets: [
    [
      'classic',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;

It is also possible to use JSDoc type annotations within a .js file:

默认情况下，Docusaurus TypeScript 配置不会对 JavaScript 文件进行类型检查。

// @ts-check 注释确保在运行 npx tsc 时对配置文件进行正确的类型检查。

docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Config} */
const config = {
  tagline: 'Dinosaurs are cool',
  favicon: 'img/favicon.ico',

  /* Your site config here */

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      (
        {
          /* Your preset config here */
        }
      ),
    ],
  ],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    (
      {
        /* Your theme config here */
      }
    ),
};

export default config;

提示

类型注释非常有用，可以帮助你的 IDE 了解配置对象的类型！

最好的 IDE（VS Code、WebStorm、IntelliJ...）将提供良好的自动补齐体验。

Swizzling TypeScript 主题组件

对于支持 TypeScript 主题组件的主题，你可以在 swizzle 命令末尾添加 --typescript 标志来获取 TypeScript 源代码。例如，以下命令将把 index.tsx 和 styles.module.css 生成为 src/theme/Footer。

提示

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic Footer -- --typescript

yarn swizzle @docusaurus/theme-classic Footer --typescript

pnpm run swizzle @docusaurus/theme-classic Footer --typescript

所有官方 Docusaurus 主题都支持 TypeScript 主题组件，包括 theme-classic、theme-live-codeblock 和 theme-search-algolia。如果你是 Docusaurus 主题包作者，想要添加 TypeScript 支持，请参阅生命周期 API 文档。

配置​

目录​

原文​

正文​

声明 docusaurus.config.js 的语法​

docusaurus.config.js 包含什么？​

站点元数据​

部署配置​

主题、插件和预设配置​

定制配置​

从组件访问配置​

自定义 Babel 配置​

在线运行​

📦 CodeSandbox​

⚡ StackBlitz 🆕​

TypeScript 支持​

初始化​

设置​

键入配置文件​

Swizzling TypeScript 主题组件​

配置

目录

原文

正文

声明 docusaurus.config.js 的语法

docusaurus.config.js 包含什么？

站点元数据

部署配置

主题、插件和预设配置

定制配置

从组件访问配置

自定义 Babel 配置

在线运行

📦 CodeSandbox

⚡ StackBlitz 🆕

TypeScript 支持

初始化

设置

键入配置文件

Swizzling TypeScript 主题组件