Aller au contenu principal
Version: 2.0.0-beta.4

docusaurus.config.js

Vue d'ensemble#

docusaurus.config.js contient des configurations pour votre site et est placé à la racine de votre site.

Champs obligatoires#

title#

  • Type : string

Titre de votre site.

docusaurus.config.js
module.exports = {  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. Par exemple, https://facebook.github.io est l'URL de https://facebook.github.io/metro/ et https://docusaurus.io est l'URL de https://docusaurus.io. Ce champ est lié au champ baseUrl.

docusaurus.config.js
module.exports = {  url: 'https://docusaurus.io',};

baseUrl#

  • Type : string

L'URL de base de votre site. Cela peut aussi être considéré comme le chemin après l'hôte. Par exemple, /metro/ est la baseUrl de https://facebook.github.io/metro/. Pour les URL n'ayant pas de chemin, la baseUrl doit être définie à /. Ce champ est lié au champ url.

docusaurus.config.js
module.exports = {  baseUrl: '/',};

Champs optionnels#

favicon#

  • Type : string | undefined

Chemin vers le favicon de votre site

Exemple si votre favicon est dans static/img/favicon.ico :

docusaurus.config.js
module.exports = {  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 (par défaut) : garde les URLs intactes, et émet /docs/myDoc/index.html pour /docs/myDoc.md
  • true : ajoute des slashs à la fin des URL/liens, et émet /docs/myDoc/index.html pour /docs/myDoc.md
  • false : supprime les slashs à la fin des URL/liens, et émet /docs/myDoc.html pour /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).

Reportez-vous au guide de déploiement et slorber/trailing-slash-guide pour choisir le paramètre approprié.

i18n#

  • Type : Object

L'objet de configuration i18n pour localiser votre site.

Exemple :

docusaurus.config.js
module.exports = {  i18n: {    defaultLocale: 'en',    locales: ['en', 'fr'],    localeConfigs: {      en: {        label: 'English',        direction: 'ltr',      },      fr: {        label: 'Français',        direction: 'ltr',      },    },  },};
  • label : le libellé à utiliser pour cette locale
  • direction : ltr (par défaut) ou rtl (pour les langues de droite à gauche comme l'arabe, l'hébreu, etc.)

noIndex#

  • Type : boolean

Cette option ajoute <meta name="robots" content="noindex, nofollow"> dans les pages, pour dire aux moteurs de recherche de ne pas indexer votre site (plus d'informations ici).

Exemple :

docusaurus.config.js
module.exports = {  noIndex: true, // Par défaut, `false`};

onBrokenLinks#

  • Type: 'ignore' | 'log' | 'warn' | 'error' | '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

La détection de liens défectueux n'est disponible que pour une version de production (docusaurus build).

onBrokenMarkdownLinks#

  • Type: 'ignore' | 'log' | 'warn' | 'error' | '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' | 'error' | 'throw'

Le comportement de Docusaurus lorsqu'il détecte des routes dupliquées.

Par défaut, il affiche un avertissement après avoir exécuté yarn start ou yarn build.

tagline#

  • Type : string

Le slogan de votre site web.

docusaurus.config.js
module.exports = {  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. Utilisé par la commande de déploiement.

docusaurus.config.js
module.exports = {  // L'organisation de Docusaurus est facebook  organizationName: 'facebook',};

projectName#

  • Type : string

Le nom du répertoire GitHub. Utilisé par la commande de déploiement.

docusaurus.config.js
module.exports = {  projectName: 'docusaurus',};

githubHost#

  • Type : string

Le nom d'hôte de votre serveur. Utile si vous utilisez GitHub Enterprise.

docusaurus.config.js
module.exports = {  githubHost: 'github.com',};

githubPort#

  • Type : string

Le port de votre serveur. Utile si vous utilisez GitHub Enterprise.

docusaurus.config.js
module.exports = {  githubPort: '22',};

themeConfig#

  • Type : Object

L'objet de configuration du thème pour personnaliser l'interface utilisateur de votre site comme la barre de navigation, le pied de page.

Exemple :

docusaurus.config.js
module.exports = {  themeConfig: {    hideableSidebar: false,    colorMode: {      defaultMode: 'light',      disableSwitch: false,      respectPrefersColorScheme: true,      switchConfig: {        darkIcon: '🌙',        lightIcon: '\u2600',        // Objet de style en ligne de React        // consultez https://reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },        lightIconStyle: {          marginLeft: '1px',        },      },    },    navbar: {      title: 'Titre du site',      logo: {        alt: 'Logo du site',        src: 'img/logo.svg',      },      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: 'Facebook Open Source Logo',        src: 'https://docusaurus.io/img/oss_logo.png',      },      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // Vous pouvez aussi placer votre propre HTML ici    },  },};

plugins#

  • Type: any[]
docusaurus.config.js
module.exports = {  plugins: [],};

themes#

  • Type: any[]
docusaurus.config.js
module.exports = {  themes: [],};

presets#

  • Type: any[]
docusaurus.config.js
module.exports = {  presets: [],};

customFields#

Docusaurus préserve docusaurus.config.js des champs inconnus. Pour ajouter un champ personnalisé, définissez-le dans customFields.

  • Type : Object
docusaurus.config.js
module.exports = {  customFields: {    admin: 'endi',    superman: 'lol',  },};

La tentative pour ajouter un champ inconnu dans la configuration entraînera une erreur au moment de la construction :

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

scripts#

Un tableau de scripts à charger. Les valeurs peuvent être des chaînes de caractères ou des objets simples de correspondances attributs-valeurs. Les balises <script> seront insérées dans le <head> du code HTML.

Notez que les <script> ajoutés ici sont des bloqueurs de rendu donc vous pourriez vouloir ajouter async: true/defer: true aux objets.

  • Type : (string | Object)[]

Exemple :

docusaurus.config.js
module.exports = {  scripts: [    // Format d'un String.    'https://docusaurus.io/script.js',    // Format d'un Object.    {      src:        'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',      async: true,    },  ],};

clientModules#

Un tableau de modules clients à charger globalement sur votre site :

Exemple :

docusaurus.config.js
module.exports = {  clientModules: [    require.resolve('./mySiteGlobalJs.js'),    require.resolve('./mySiteGlobalCss.css'),  ],};

Voir aussi : getClientModules().

ssrTemplate#

Un template HTML écrit dans la syntaxe d'Eta qui sera utilisé pour rendre votre application. Il peut être utilisé pour définir des attributs personnalisés sur les balises body, des balises meta supplémentaires, personnaliser le 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
module.exports = {  ssrTemplate: `<!DOCTYPE html><html <%~ it.htmlAttributes %>>  <head>    <meta charset="UTF-8">    <meta name="viewport" content="width=device-width, initial-scale=0.86, maximum-scale=3.0, minimum-scale=0.86">    <meta name="generator" content="Docusaurus v<%= it.version %>">    <%~ it.headTags %>    <% it.metaAttributes.forEach((metaAttribute) => { %>      <%~ metaAttribute %>    <% }); %>    <% 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 %> itemscope="" itemtype="http://schema.org/Organization">    <%~ it.preBodyTags %>    <div id="__docusaurus">      <%~ it.appHtml %>    </div>    <div id="outside-docusaurus">      <span>Custom markup</span>    </div>    <% it.scripts.forEach((script) => { %>      <script src="<%= it.baseUrl %><%= script %>"></script>    <% }); %>    <%~ it.postBodyTags %>  </body></html>};

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. Les balises <link> seront insérées dans le <head> du code HTML.

  • Type : (string | Object)[]

Exemple :

docusaurus.config.js
module.exports = {  stylesheets: [    // Format d'un String.    'https://docusaurus.io/style.css',    // Format d'un Object.    {      href: 'http://mydomain.com/style.css',    },  ],};

titleDelimiter#

  • Type : string

Une chaîne qui sera utilisée comme délimiteur de titre dans la balise <title> générée.

Exemple :

docusaurus.config.js
module.exports = {  titleDelimiter: '🦖', // Par défaut `|`};

baseUrlIssueBanner#

  • Type : boolean

Lorsqu'il est activé, il affiche une bannière si votre site ne peut pas charger ses fichiers CSS ou JavaScript, ce qui est un problème très courant, souvent lié à un mauvais baseUrl dans la configuration du site.

Exemple :

docusaurus.config.js
module.exports = {  baseUrlIssueBanner: true, // Par défaut, `true`};

baseUrlIssueBanner

caution

Cette bannière doit être du CSS / JS en ligne.

Si vous avez une stratégie de sécurité du contenu stricte, vous devriez plutôt la désactiver.