Aller au contenu principal
Version : 3.6.0

Configuration du thème

Cette configuration s'applique à tous les thèmes principaux.

Commun​

Mode de couleur​

Le thème classic fournit par défaut la prise en charge du mode clair et sombre, avec un commutateur dans la barre de navigation pour l'utilisateur.

Il est possible de personnaliser le support du mode de couleur dans l'objet colorMode.

Champs acceptés :

NomTypePar défautDescription
defaultMode'light' | 'dark''light'Le mode de couleur lorsque l'utilisateur visite le site pour la première fois.
disableSwitchbooleanfalseMasque l'interrupteur dans la barre de navigation. Utile si vous voulez prendre en charge un mode de couleur unique.
respectPrefersColorSchemebooleanfalseSi vous voulez utiliser la requête media-query prefers-color-scheme, en utilisant les préférences du système utilisateur, au lieu du defaultMode codé en dur.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
attention

Avec respectPrefersColorScheme: true, le defaultMode est remplacé par les préférences du système utilisateur.

Si vous ne voulez prendre en charge qu'un seul mode couleur, vous devriez ignorer les préférences du système utilisateur.

Méta image​

Vous pouvez configurer une image par défaut qui sera utilisée pour votre balise méta, notamment og:image et twitter:image.

Champs acceptés :

NomTypePar défautDescription
imagestringundefinedL'URL de la méta image pour le site. Par rapport au répertoire "static" de votre site. Ne peuvent pas être des SVG. Peut également être des URL externes.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

Métadonnées​

Vous pouvez configurer des métadonnées HTML supplémentaires (et remplacer celles existantes).

Champs acceptés :

NomTypePar défautDescription
metadataMetadata[][]N'importe quel champ sera directement passé à la balise <meta />. Les champs possibles sont notamment id, name, property, content, itemprop, etc.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

Barre d'annonce​

Parfois, vous voulez annoncer quelque chose dans votre site Web. Juste pour ce cas, vous pouvez ajouter une barre d'annonce. Il s'agit d'un panneau non fixe et éventuellement dissimulable au-dessus de la barre de navigation. Toutes les configurations sont dans l'objet announcementBar.

Champs acceptés :

NomTypePar défautDescription
idstring'announcement-bar'Toute valeur qui identifiera ce message.
contentstring''Le contenu de l'annonce. Le HTML sera interpolé.
backgroundColorstring'#fff'Couleur en arrière plan de toute la barre.
textColorstring'#000'Couleur du texte de l'annonce.
isCloseablebooleantrueSi cette annonce peut être ignorée avec un bouton '×'.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        'Nous cherchons à améliorer nos documents, veuillez répondre à <a target="_blank" rel="noopener noreferrer" href="#">cette enquête</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

Plugins​

Our main themes offer additional theme configuration options for Docusaurus core content plugins.

Docs​

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      versionPersistence: 'localStorage',
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
  },
};

Blog​

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

Champs acceptés :

NomTypePar défautDescription

Le logo peut être placé dans le dossier static. L'URL du logo est défini par défaut sur l'URL de base de votre site. Bien que vous puissiez spécifier votre propre URL pour le logo, s'il s'agit d'un lien externe, il s'ouvrira dans un nouvel onglet. De plus, vous pouvez remplacer une valeur pour l'attribut cible du lien du logo, ce qui peut s'avérer pratique si vous hébergez les docs du site Web dans un sous-répertoire de votre site Web principal, et dans ce cas, vous n'avez probablement pas besoin d'un lien dans le logo vers le site Web principal qui s'ouvrira dans un nouvel onglet.

Pour améliorer la prise en charge du mode sombre, vous pouvez également définir un logo différent pour ce mode.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo_dark.svg',
        href: 'https://docusaurus.io/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

Vous pouvez ajouter des éléments à la barre de navigation via themeConfig.navbar.items.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          type: 'docsVersionDropdown',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/facebook/docusaurus',
          position: 'right',
          className: 'header-github-link',
          'aria-label': 'GitHub repository',
        },
      ],
    },
  },
};

Les éléments peuvent avoir des comportements différents en fonction du champ type. Les sections ci-dessous vous présenteront tous les types d'éléments de la barre de navigation disponibles.

Par défaut, les éléments de la barre de navigation sont des liens ordinaires (internes ou externes).

React Router devrait automatiquement appliquer un style de lien actif aux liens, mais vous pouvez utiliser activeBasePath dans les cas particuliers. Pour les cas où un lien devrait être actif sur plusieurs chemins différents (comme lorsque vous avez plusieurs dossiers doc sous la même barre latérale), vous pouvez utiliser activeBaseRegex. activeBaseRegex est une alternative plus flexible à activeBasePath et a la priorité sur celle-ci -- Docusaurus l'analyse en une expression régulière qui est testée par rapport à l'URL actuelle.

Les liens sortants (externes) reçoivent automatiquement des attributs target="_blank" rel="noopener noreferrer".

Champs acceptés :

NomTypePar défautDescription
remarque

En plus des champs ci-dessus, vous pouvez spécifier d'autres attributs arbitraires qui peuvent être appliqués à un lien HTML.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Un seul de "to" ou "href" doit être utilisé
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Un seul de "label" ou "html" doit être utilisé
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

Les éléments de la barre de navigation du type dropdown possède le champ supplémentaire items, un tableau interne d'éléments de la barre de navigation.

Les éléments de la liste déroulante de la barre de navigation n'acceptent que les types d'éléments "de type lien" suivants :

Notez que l'élément de base de la liste déroulante est également un lien cliquable, de sorte que cet élément peut recevoir tous les props d'un lien de barre de navigation ordinaire.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: 'Social',
              docId: 'social',
            },
            // ... plus d'éléments
          ],
        },
      ],
    },
  },
};

Si vous souhaitez lier à un doc spécifique, ce type spécial d'élément de la barre de navigation affichera le lien vers le doc du docId fourni. Il obtiendra la classe navbar__link--active tant que vous parcourrez un doc de la même barre latérale.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

Vous pouvez lier un élément de la barre de navigation au premier lien du document (qui peut être un lien de doc ou un index de catégorie généré) d'une barre latérale donnée sans avoir à coder en dur un ID de documentation.

Champs acceptés :

NomTypePar défautDescription
astuce

Utilisez ce type d'élément de la barre de navigation si votre barre latérale est mise à jour souvent et que l'ordre n'est pas stable.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // L'élément de la barre de navigation renvoie à ce doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

Si vous utilisez des docs avec la gestion des versions, ce type spécial d'élément de la barre de navigation affichera un menu déroulant avec toutes les versions disponibles de votre site.

L'utilisateur sera en mesure de passer d'une version à une autre, tout en restant sur le même doc (tant que l'ID du doc est constant entre les versions).

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'Toutes les versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

Si vous utilisez des docs avec la gestion de version, ce type spécial d'élément de la barre de navigation sera lié à la version active/consultée de votre doc (dépend de l'URL actuelle), et sinon se placera sur la dernière version.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
      ],
    },
  },
};

Si vous utilisez la fonctionnalité i18n, ce type spécial d'élément de la barre de navigation affichera un menu déroulant avec toutes les locales disponibles de votre site.

L'utilisateur pourra basculer d'une locale à une autre, tout en restant sur la même page.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Aidez-nous à traduire',
            },
          ],
        },
      ],
    },
  },
};

Si vous utilisez la recherche, la barre de recherche sera l'élément le plus à droite de la barre de navigation.

Cependant, avec ce type spécial d'élément de la barre de navigation, vous pouvez changer l'emplacement par défaut.

NomTypePar défautDescription
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

Vous pouvez également rendre votre propre balisage HTML à l'intérieur d'un élément de barre de navigation en utilisant ce type d'élément de barre de navigation.

NomTypePar défautDescription
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Donnez votre avis</button>',
        },
      ],
    },
  },
};

Masquage automatique de la barre de navigation flottante​

Vous pouvez activer cette fonctionnalité d'interface utilisateur qui masque automatiquement la barre de navigation lorsqu'un utilisateur commence à faire défiler la page vers le bas, et la réaffiche lorsqu'il la fait défiler vers le haut.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

Vous pouvez définir le style statique de la barre de navigation sans désactiver la possibilité de changer de thème. Le style sélectionné s'appliquera toujours quel que soit le thème sélectionné par l'utilisateur.

Actuellement, il y a deux options de style possibles : dark et primary (basé sur la couleur --ifm-color-primary). Vous pouvez voir l'aperçu des styles dans la documentation Infima.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

Bloc de code​

Docusaurus utilise Prism React Renderer pour mettre en évidence les blocs de code. Toutes les configurations sont dans l'objet prism.

Champs acceptés :

NomTypePar défautDescription
themePrismThemepalenightLe thème Prism à utiliser pour les blocs de code de thème clair.
darkThemePrismThemepalenightLe thème Prism à utiliser pour les blocs de code de thème sombre.
defaultLanguagestringundefinedLe langage par défaut à utiliser pour les blocs de code ne déclarant pas de langage explicite.
magicCommentsMagicCommentConfig[]voir ci-dessousLa liste des commentaires magiques.
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];

Thème​

Par défaut, nous utilisons Palenight comme thème de coloration de syntaxe. Vous pouvez spécifier un thème personnalisé à partir de la liste des thèmes disponibles. Vous pouvez également utiliser un thème de coloration syntaxique différent lorsque le site est en mode sombre.

Exemple de configuration :

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};
remarque

Si vous utilisez la coloration de ligne de la syntaxe Markdown, vous devrez peut-être spécifier une couleur d'arrière-plan différente pour le thème de coloration syntaxique en mode sombre. Reportez-vous aux docs pour obtenir des conseils.

Langage par défaut​

Vous pouvez définir un langage par défaut pour les blocs de code si aucun langage n'est ajouté après le triple backticks (c'est-à-dire ```). Notez qu'un [nom de langage](https://prismjs.com/#langues supportées) valide doit être passé.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

Vous pouvez ajouter un logo et un copyright au pied de page via themeConfig.footer. Le logo peut être placé dans le dossier static. L'URL du logo fonctionne de la même manière que le logo de la barre de navigation.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      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()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

Vous pouvez ajouter des éléments au pied de page via themeConfig.footer.links. Il existe deux types de configurations de pied de page : pieds de page à colonnes multiples et pieds de page simples.

Les liens de pied de page multi-colonnes ont un title et une liste de FooterItem pour chaque colonne.

NomTypePar défautDescription

Champs acceptés de chaque FooterItem :

NomTypePar défautDescription

Exemple de configuration multi-colonnes :

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Style Guide',
            to: 'docs/',
          },
          {
            label: 'Second Doc',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus',
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus',
          },
          {
            label: 'X',
            href: 'https://x.com/docusaurus',
          },
          {
            html: `
                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

Un pied de page simple a juste une liste de FooterItem affichés dans une ligne.

Exemple de configuration simple :

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'X',
        href: 'https://x.com/docusaurus',
      },
      {
        html: `
            <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

Table des matières​

Vous pouvez ajuster la table des matières par défaut via themeConfig.tableOfContents.

NomTypePar défautDescription
minHeadingLevelnumber2Le niveau de titre minimum affiché dans la table des matières. Doit être compris entre 2 et 6 et inférieur ou égal à la valeur maximale.
maxHeadingLevelnumber3Niveau maximum affiché dans la table des matières. Doit être un entier entre 2 et 6.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

Hooks​

useColorMode​

Un hook React pour accéder au contexte de couleur. Ce contexte contient des fonctions permettant de définir le mode clair et le mode sombre et expose une variable booléenne, indiquant le mode actuellement utilisé.

Exemple d'utilisation :

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
remarque

Le composant appelant useColorMode doit être un enfant du composant Layout.

function ExamplePage() {
  return (
    <Layout>
      <Example />
    </Layout>
  );
}

i18n​

Lisez d'abord l'introduction i18n .

Emplacement des fichiers de traduction​

  • Chemin de base : website/i18n/[locale]/docusaurus-theme-[themeName]
  • Chemin multi-instance : Non applicable
  • Fichiers JSON : extrait avec docusaurus write-translations
  • Fichiers Markdown : Non applicable

Exemple de structure du système de fichiers​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # traductions pour le thème
├── navbar.json
└── footer.json