跳转至主内容
Version: 2.0.0-alpha.73

配置

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

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

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

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

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

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

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

站点元数据#

站点元数据包含 titleurlbaseUrlfavicon 在内的重要全局元数据。

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

部署配置#

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

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

主题、插件和预设配置#

分别列出位于 themespluginspresets 字段的主题插件预设。 这些通常为 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-docstheme 则指向 @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 中定义。

Example:

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 开发服务器。