Version: 3.0.0-rc.1

`docusaurus.config.js`

info

Refer to the Getting Started Configuration for examples.

Vue d'ensemble

docusaurus.config.js contains configurations for your site and is placed in the root directory of your site.

Ce fichier est exécuté dans Node.js et doit exporter un objet de config de site, ou une fonction qui le crée.

The docusaurus.config.js file supports:

hey

Exemples :

docusaurus.config.js
export default {
  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 ...
  };
}

astuce

Refer to Syntax to declare docusaurus.config.js for a more exhaustive list of examples and explanations.

Required fields

`title`

Type: string

Titre de votre site. Sera utilisé dans les métadonnées et comme titre dans l'onglet du navigateur.

docusaurus.config.js
export default {
  title: 'Docusaurus',
};

`url`

Type: string

URL de votre site web. Cela peut également être considéré comme le nom d'hôte de premier niveau. For example, https://facebook.github.io is the URL of https://facebook.github.io/metro/, and https://docusaurus.io is the URL for https://docusaurus.io. This field is related to the baseUrl field.

docusaurus.config.js
export default {
  url: 'https://docusaurus.io',
};

`baseUrl`

Type: string

L'URL de base de votre site. Cela peut être considéré comme le chemin après l'hôte. For example, /metro/ is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to /. This field is related to the url field. Il y a toujours un slash avant et un slash après.

docusaurus.config.js
export default {
  baseUrl: '/',
};

Optional fields

`favicon`

Type: string | undefined

Le chemin d'accès au favicon de votre site, il doit s'agir d'une URL qui peut être utilisée dans le href du lien. For example, if your favicon is in static/img/favicon.ico:

docusaurus.config.js
export default {
  favicon: '/img/favicon.ico',
};

`trailingSlash`

Type: boolean | undefined

Permet de personnaliser la présence ou l'absence du slash à la fin des URL/liens, et la façon dont les fichiers HTML statiques sont générés :

undefined (default): keeps URLs untouched, and emit /docs/myDoc/index.html for /docs/myDoc.md
true: add trailing slashes to URLs/links, and emit /docs/myDoc/index.html for /docs/myDoc.md
false: remove trailing slashes from URLs/links, and emit /docs/myDoc.html for /docs/myDoc.md

astuce

Chaque fournisseur d'hébergement statique sert les fichiers statiques différemment (ce comportement peut même changer avec le temps).

Refer to the deployment guide and slorber/trailing-slash-guide to choose the appropriate setting.

`i18n`

Type: Object

The i18n configuration object to localize your site.

Exemple :

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fa'],
    path: 'i18n',
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
        calendar: 'gregory',
        path: 'en',
      },
      fa: {
        label: 'فارسی',
        direction: 'rtl',
        htmlLang: 'fa-IR',
        calendar: 'persian',
        path: 'fa',
      },
    },
  },
};

defaultLocale: The locale that (1) does not have its name in the base URL (2) gets started with docusaurus start without --locale option (3) will be used for the <link hrefLang="x-default"> tag
locales: List of locales deployed on your site. Must contain defaultLocale.
path: Root folder which all locale folders are relative to. Doit être absolus ou relatifs par rapport au fichier de configuration. Defaults to i18n.
localeConfigs: Individual options for each locale.
- label: The label displayed for this locale in the locales dropdown.
- direction: ltr (default) or rtl (for right-to-left languages like Farsi, Arabic, Hebrew, etc.). Utilisé pour sélectionner le méta attribut CSS et HTML de la locale.
- htmlLang: BCP 47 language tag to use in <html lang="..."> (or any other DOM tag name) and in <link ... hreflang="...">
- calendar: the calendar used to calculate the date era. Note that it doesn't control the actual string displayed: MM/DD/YYYY and DD/MM/YYYY are both gregory. To choose the format (DD/MM/YYYY or MM/DD/YYYY), set your locale name to en-GB or en-US (en means en-US).
- path: Root folder that all plugin localization folders of this locale are relative to. Will be resolved against i18n.path. Par défaut, le nom de la locale. Note: this has no effect on the locale's baseUrl—customization of base URL is a work-in-progress.

`noIndex`

Type: boolean

This option adds <meta name="robots" content="noindex, nofollow"> to every page to tell search engines to avoid indexing your site (more information here).

Exemple :

docusaurus.config.js
export default {
  noIndex: true, // Par défaut, `false`
};

`onBrokenLinks`

Type: 'ignore' | 'log' | 'warn' | 'throw'

Le comportement de Docusaurus lorsqu'il détecte un lien défectueux.

Par défaut, il lance une erreur, pour vous assurer que vous ne livrez jamais de lien défectueux, mais vous pouvez réduire cette sécurité si nécessaire.

remarque

The broken links detection is only available for a production build (docusaurus build).

`onBrokenMarkdownLinks`

Type: 'ignore' | 'log' | 'warn' | 'throw'

Le comportement de Docusaurus lorsqu'il détecte un lien défectueux du Markdown.

Par défaut, il affiche un avertissement, pour vous informer que votre lien Markdown est défectueux, mais vous pouvez modifier cette sécurité si nécessaire.

`onDuplicateRoutes`

Type: 'ignore' | 'log' | 'warn' | 'throw'

The behavior of Docusaurus when it detects any duplicate routes.

By default, it displays a warning after you run yarn start or yarn build.

`tagline`

Type: string

Le slogan de votre site web.

docusaurus.config.js
export default {
  tagline:
    'Docusaurus facilite la maintenance des sites de documentation Open Source',
};

`organizationName`

Type: string

L'utilisateur ou l'organisation GitHub qui possède le dépôt. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  // L'organisation de Docusaurus est facebook
  organizationName: 'facebook',
};

`projectName`

Type: string

Le nom du répertoire GitHub. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  projectName: 'docusaurus',
};

`deploymentBranch`

Type: string

Le nom de la branche vers laquelle déployer les fichiers statiques. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  deploymentBranch: 'gh-pages',
};

`githubHost`

Type: string

Le nom d'hôte de votre serveur. Utile si vous utilisez GitHub Enterprise. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  githubHost: 'github.com',
};

`githubPort`

Type: string

Le port de votre serveur. Utile si vous utilisez GitHub Enterprise. You don't need this if you are not using the docusaurus deploy command.

docusaurus.config.js
export default {
  githubPort: '22',
};

`themeConfig`

Type: Object

The theme configuration object to customize your site UI like navbar and footer.

Exemple :

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: 'Titre du site',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        width: 32,
        height: 32,
      },
      items: [
        {
          to: 'docs/docusaurus.config.js',
          activeBasePath: 'docs',
          label: 'docusaurus.config.js',
          position: 'left',
        },
        // ... autres liens
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: 'docs/doc1',
            },
          ],
        },
        // ... autres liens
      ],
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // Vous pouvez aussi mettre votre propre HTML ici
    },
  },
};

`plugins`

Type: PluginConfig[]

type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

See plugin method references for the shape of a PluginModule.

docusaurus.config.js
export default {
  plugins: [
    'docusaurus-plugin-awesome',
    ['docusuarus-plugin-confetti', {fancy: false}],
    () => ({
      postBuild() {
        console.log('Build finished');
      },
    }),
  ],
};

`themes`

Type: PluginConfig[]

docusaurus.config.js
export default {
  themes: ['@docusaurus/theme-classic'],
};

`presets`

Type: PresetConfig[]

type PresetConfig = string | [string, any];

docusaurus.config.js
export default {
  presets: [],
};

`markdown`

La configuration globale du Markdown de Docusaurus.

Type: MarkdownConfig

type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

type MDX1CompatOptions =
  | boolean
  | {
      comments: boolean;
      admonitions: boolean;
      headingIds: boolean;
    };

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  mdx1Compat: MDX1CompatOptions;
};

Exemple :

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Nom	Type	Par défaut	Description
`format`	`'mdx' \| 'md' \| 'detect'`	`'mdx'`	Le format d'analyseur par défaut à utiliser pour le contenu Markdown. L'utilisation de l'option 'detect' permet de sélectionner automatiquement le format approprié en fonction des extensions de fichiers : `.md` vs `.mdx`.
`mermaid`	`boolean`	`false`	Si `true`, permet à Docusaurus de rendre les blocs de code Markdown avec le langage `mermaid` comme des diagrammes Mermaid.
`preprocessor`	`MarkdownPreprocessor`	`undefined`	Permet de modifier la chaîne de contenu Markdown avant l'analyse. Utilisez-le comme solution de dernier recours : il est presque toujours préférable de mettre en œuvre un plugin Remark/Rehype.
`mdx1Compat`	`MDX1CompatOptions`	`{comments: true, admonitions: true, headingIds: true}`	Compatibility options to make it easier to upgrade to Docusaurus v3+.

`customFields`

Docusaurus préserve docusaurus.config.js des champs inconnus. To add a custom field, define it on customFields.

Type: Object

docusaurus.config.js
export default {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

La tentative pour ajouter des champs inconnus dans la configuration entraînera des erreurs au moment de la construction :

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

`staticDirectories`

Un tableau de chemins, relatif ou absolu au répertoire du site. Les fichiers sous ces chemins seront copiés dans la sortie de compilation telle quelle.

Type: string[]

Exemple :

docusaurus.config.js
export default {
  staticDirectories: ['static'],
};

`headTags`

An array of tags that will be inserted in the HTML <head>. The values must be objects that contain two properties; tagName and attributes. tagName must be a string that determines the tag being created; eg "link". attributes must be an attribute-value map.

Type: { tagName: string; attributes: Object; }[]

Exemple :

docusaurus.config.js
export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'icon',
        href: '/img/docusaurus.png',
      },
    },
  ],
};

This would become <link rel="icon" href="img/docusaurus.png" /> in the generated HTML.

`scripts`

Un tableau de scripts à charger. Les valeurs peuvent être des chaînes de caractères ou des objets simples de correspondances attributs-valeurs. The <script> tags will be inserted in the HTML <head>. If you use a plain object, the only required attribute is src, and any other attributes are permitted (each one should have boolean/string values).

Note that <script> added here are render-blocking, so you might want to add async: true/defer: true to the objects.

Type: (string | Object)[]

Exemple :

docusaurus.config.js
export default {
  scripts: [
    // String format.
    'https://docusaurus.io/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

`stylesheets`

Un tableau de sources CSS à charger. Les valeurs peuvent être des chaînes de caractères ou des objets simples de correspondances attributs-valeurs. The <link> tags will be inserted in the HTML <head>. If you use an object, the only required attribute is href, and any other attributes are permitted (each one should have boolean/string values).

Type: (string | Object)[]

Exemple :

docusaurus.config.js
export default {
  stylesheets: [
    // String format.
    'https://docusaurus.io/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};

info

By default, the <link> tags will have rel="stylesheet", but you can explicitly add a custom rel value to inject any kind of <link> tag, not necessarily stylesheets.

`clientModules`

An array of client modules to load globally on your site.

Exemple :

docusaurus.config.js
export default {
  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};

`ssrTemplate`

An HTML template written in Eta's syntax that will be used to render your application. This can be used to set custom attributes on the body tags, additional meta tags, customize the viewport, etc. Veuillez noter que Docusaurus s'appuiera sur la structure correcte du template pour fonctionner correctement. Une fois que vous l'aurez personnalisé, vous devrez vous assurer que votre template est conforme aux exigences de upstream.

Type: string

Exemple :

docusaurus.config.js
export default {
  ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <%~ it.headTags %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus">
      <%~ it.appHtml %>
    </div>
    <% it.scripts.forEach((script) => { %>
      <script src="<%= it.baseUrl %><%= script %>"></script>
    <% }); %>
    <%~ it.postBodyTags %>
  </body>
</html>`,
};

`titleDelimiter`

Type: string

Will be used as title delimiter in the generated <title> tag.

Exemple :

docusaurus.config.js
export default {
  titleDelimiter: '🦖', // Par défaut `|`
};

`baseUrlIssueBanner`

Type: boolean

When enabled, will show a banner in case your site can't load its CSS or JavaScript files, which is a very common issue, often related to a wrong baseUrl in site config.

Exemple :

docusaurus.config.js
export default {
  baseUrlIssueBanner: true, // Par défaut, `true`
};

A sample base URL issue banner. Le style est très brut car les feuilles de style n'ont pas pu être chargées. The text says "Your Docusaurus site did not load properly... Current configured baseUrl = / (default value); We suggest trying baseUrl = /build/

attention

Cette bannière doit être en ligne CSS / JS au cas où le chargement de l'actif échouerait en raison d'une mauvaise URL de base.

If you have a strict Content Security Policy, you should rather disable it.

docusaurus.config.js

Vue d'ensemble​

Required fields​

title​

url​

baseUrl​

Optional fields​

favicon​

trailingSlash​

i18n​

noIndex​

onBrokenLinks​

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

markdown​

customFields​

staticDirectories​

headTags​

scripts​

stylesheets​

clientModules​

ssrTemplate​

titleDelimiter​

baseUrlIssueBanner​

`docusaurus.config.js`

Vue d'ensemble

Required fields

`title`

`url`

`baseUrl`

Optional fields

`favicon`

`trailingSlash`

`i18n`

`noIndex`

`onBrokenLinks`

`onBrokenMarkdownLinks`

`onDuplicateRoutes`

`tagline`

`organizationName`

`projectName`

`deploymentBranch`

`githubHost`

`githubPort`

`themeConfig`

`plugins`

`themes`

`presets`

`markdown`

`customFields`

`staticDirectories`

`headTags`

`scripts`

`stylesheets`

`clientModules`

`ssrTemplate`

`titleDelimiter`

`baseUrlIssueBanner`