跳转至主内容
Version: 2.0.0-beta.3

配置

Docusaurus 对配置文件有着独特见解。 我们鼓励您将站点信息聚合至一处。 我们将维护此文件的每个字段，并让其可被您站点的每个角落所使用。

悉心维护的 docusaurus.config.js 将让您在自定义站点的同时，帮助您、您的协作者及开源项目贡献者能更专心于文档网站本身。

docusaurus.config.js 里会写什么？#

即便您正在开发网站，您也不应该从零开始撰写 docusaurus.config.js。 所有模板均自带包含常见选项的 docusaurus.config.js。

但是，深知配置是如何设计及实现的也很有帮助。

Docusaurus 配置的高阶概览可分为：

要参考每个可配置字段，您可参见 docusaurus.config.js API 文档。

站点元数据#

站点元数据包含 title、url、baseUrl 和 favicon 在内的重要全局元数据。

您站点的诸多位置，如标题、页眉、浏览器图标、社交网站分享（Facebook、Twitter）或甚至在生成正确位置的静态文件时，都将使用这些信息。

部署配置#

使用 deploy 命令时将使用如 projectName 和 organizationName 在内的部署选项。

我们推荐您参考部署文档以了解详情。

主题、插件和预设配置#

分别列出位于 themes、plugins 和 presets 字段的主题、插件及预设。 这些通常为 npm 软件包：

docusaurus.config.js
module.exports = {  // ...  plugins: [    '@docusaurus/plugin-content-blog',    '@docusaurus/plugin-content-pages',  ],  themes: ['@docusaurus/theme-classic'],};

同时也可以从本地目录加载：

docusaurus.config.js
const path = require('path');
module.exports = {  // ...  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],};

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

docusaurus.config.js
module.exports = {  // ...  plugins: [    [      '@docusaurus/plugin-content-blog',      {        path: 'blog',        routeBasePath: 'blog',        include: ['*.md', '*.mdx'],        // ...      },    ],    '@docusaurus/plugin-content-pages',  ],};

要指定内置于预设中的插件或主题之选项，请经由 presets 字段传递。 本例中，docs 指向 @docusaurus/plugin-content-docs 而 theme 则指向 @docusaurus/theme-classic。

docusaurus.config.js
module.exports = {  // ...  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          sidebarPath: require.resolve('./sidebars.js'),        },        theme: {          customCss: [require.resolve('./src/css/custom.css')],        },      },    ],  ],};

欲获取主题、插件及预设的进一步帮助，请参见使用主题、使用插件及使用预设。

自定义配置#

Docusaurus 不允许 docusaurus.config.js 存在未知字段。 要添加自定义字段，请在 customFields 中定义。

示例：

docusaurus.config.js
module.exports = {  // ...  customFields: {    image: '',    keywords: [],  },  // ...};

在组件中获取配置#

您站点的所有组件均可访问配置对象。 您可通过名为 siteConfig 的 React 上下文获取：

简单示例：

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.config.js。

babel.config.js
module.exports = {  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],};

大多情况下，这份配置就已足够。 若您想自定义，您可以直接编辑此文件来修改 Babel 配置。 要使您的更改生效，您需要重新启动 Docusaurus 开发服务器。