Configuration

Docusaurus a une approche unique sur les configurations. Nous vous encourageons à rassembler les informations de votre site en un seul endroit. Nous gardons les champs de ce fichier et facilitons l'accès à cet objet de données à travers votre site.

Keeping a well-maintained docusaurus.config.js helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site.

What goes into a docusaurus.config.js?

You should not have to write your docusaurus.config.js from scratch even if you are developing your site. All templates come with a docusaurus.config.js that includes defaults for the common options.

Toutefois, il peut être utile d'avoir une compréhension de haut niveau de la façon dont les configurations sont conçues et mises en œuvre.

La configuration de haut niveau de Docusaurus peut être classée en plusieurs catégories :

• Site metadata
• Deployment configurations
• Theme, plugin, and preset configurations
• Custom configurations

For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.

Site metadata

Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon.

Ils sont utilisés à de nombreux endroits, comme le titre et les entêtes de votre site, l'icône de l'onglet du navigateur, les informations relatives au partage social (Facebook, Twitter) ou même pour générer le chemin d'accès correct pour servir vos fichiers statiques.

Deployment configurations

Deployment configurations such as projectName, organizationName, and optionally deploymentBranch are used when you deploy your site with the deploy command.

It is recommended to check the deployment docs for more information.

Theme, plugin, and preset configurations

List the themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. Il s'agit généralement de paquets npm :

docusaurus.config.js

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

astuce

Docusaurus supports module shorthands, allowing you to simplify the above configuration as:

docusaurus.config.js

module.exports = {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

Ils peuvent également être chargés à partir de répertoires locaux :

docusaurus.config.js

const path = require('path');

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

Pour spécifier des options pour un plugin ou un thème, remplacer le nom du plugin ou du thème dans le fichier de configuration par un tableau contenant le nom et un objet d'options :

docusaurus.config.js

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

To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets field. In this example, docs refers to @docusaurus/plugin-content-docs and theme refers to @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')],
        },
      },
    ],
  ],
};

astuce

The presets: [['classic', {...}]] shorthand works as well.

For further help configuring themes, plugins, and presets, see Using Plugins.

Custom configurations

Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.

Exemple :

docusaurus.config.js

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

Accessing configuration from components

Votre objet de configuration sera rendu disponible pour tous les composants de votre site. And you may access them via React context as siteConfig.

Exemple basique :

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

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

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

astuce

If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js.

Customizing Babel Configuration

For new Docusaurus projects, we automatically generated a babel.config.js in the project root.

babel.config.js

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

La plupart du temps, cette configuration fonctionnera correctement. Si vous voulez personnaliser votre configuration Babel (par exemple pour ajouter le support de Flow), vous pouvez directement modifier ce fichier. Pour que vos changements prennent effet, vous devez redémarrer le serveur de dev de Docusaurus.