Version: 2.0.0-beta.4

Configuration du thème

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

Commun#

Mode clair - mode sombre#

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 avec la configuration suivante :

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // ...    colorMode: {      // "light" | "dark"      defaultMode: 'light',
      // Masque le commutateur dans la barre de navigation      // Utile si vous voulez prendre en charge un mode de couleur unique      disableSwitch: false,
      // Devrions-nous utiliser le media-query prefers-color-scheme,      // en utilisant les préférences du système de l'utilisateur, au lieu de defaultMode codé en dur.      respectPrefersColorScheme: false,
      // Options d'icône du commutateur sombre/clair      switchConfig: {        // Icône du commutateur en mode sombre        darkIcon: '🌙',
        // CSS à appliquer à l'icône sombre,        // Objet de style en ligne React        // consulter https://reactjs.org/docs/dom-elements.html#style        darkIconStyle: {          marginLeft: '2px',        },
        // Les icônes Unicode telles que '\u2600' fonctionnent.        // Les icônes Unicode à 5 caractères nécessitent des accolades : '\u{1F602}'.        lightIcon: '\u{1F602}',
        lightIconStyle: {          marginLeft: '1px',        },      },    },    // ...  },  // ...};

caution

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.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    // Relatif au répertoire "static" de votre site.    // Ne peuvent pas être des SVG. Peut également être des URL externes.    image: 'img/docusaurus.png',    // ...  },};

Métadonnées#

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

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    metadatas: [{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.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    announcementBar: {      id: 'support_us', // Toute valeur qui identifiera ce message.      content:        'Nous cherchons à réorganiser nos documents, veuillez remplir <a target="_blank" rel="noopener noreferrer" href="#">cette enquête</a>',      backgroundColor: '#fafbfc', // Par défaut à `#fff`.      textColor: '#091E42', // Par défaut à `#000`.      isCloseable: false, // Par défaut à `true`.    },    // ...  },};

i18n#

Lisez l’introduction i18n en premier.

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

Hooks#

`useThemeContext`#

Hook de React pour accéder au contexte du thème. 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 useThemeContext from '@theme/hooks/useThemeContext';
const Example = () => {  const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();
  return <h1>Le mode sombre est maintenant {isDarkTheme ? 'activé' : 'désactivé'}</h1>;};

remarque

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

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

Barre de navigation#

Titre & logo de la barre de navigation#

Vous pouvez ajouter un logo et un titre à la barre de navigation via themeConfig.navbar. 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.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    navbar: {      title: 'Titre du site',      logo: {        alt: 'Logo du site',        src: 'img/logo.svg',        srcDark: 'img/logo_dark.svg', // Par défaut `logo.src`.        href: 'https://docusaurus.io/', // Par défaut `siteConfig.baseUrl`.        target : '_self', // Par défaut, cette valeur est calculée en fonction de l'attribut `href` (le lien externe s'ouvrira dans un nouvel onglet, tous les autres dans l'onglet actuel).      },    },    // ...  },};

Éléments de la barre de navigation#

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

docusaurus.config.js

module.exports = {  // ...  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.

Lien de la barre de navigation#

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`label`	`string`	Le nom à afficher pour cet élément.	Oui
`to`	`string`	Routage côté client, utilisé pour naviguer dans le site Web. La baseUrl sera automatiquement ajoutée à cette valeur.	Oui
`href`	`string`	Une navigation pleine page, utilisée pour naviguer en dehors du site web. Un seul : `to` ou `href` doit être utilisé.	Oui
`prependBaseUrlToHref`	`boolean`	Ajoute au préalable la baseUrl aux valeurs `href`.	Non	`false`
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`
`activeBasePath`	`string`	Pour appliquer le style de la classe active sur toutes les routes commençant par ce chemin. Cela n'est généralement pas nécessaire.	Non	`to` / `href`
`activeBaseRegex`	`string`	Alternative à `activeBasePath` si nécessaire.	Non	`undefined`
`className`	`string`	Classe CSS personnalisée (pour styliser n'importe quel élément).	Non	`''`

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          to: 'docs/introduction',          // Un seul : "to" ou "href" doit être utilisé          // href: 'https://www.facebook.com',          label: 'Introduction',          position: 'left',          activeBaseRegex: 'docs/(next|v8)',        },      ],    },  },};

Menu déroulant de la barre de navigation#

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 :

Lien de la barre de navigation
Lien vers un doc dans la barre de navigation
Version du doc de la barre de navigation

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`label`	`string`	Le nom à afficher pour cet élément.	Oui
`items`	`LinkLikeItem[]`	Les éléments à contenir dans le menu déroulant.	Oui
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`

Exemple de configuration :

docusaurus.config.js

module.exports = {  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          ],        },      ],    },  },};

Lien vers un doc dans la barre de navigation#

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`docId`	`string`	L'ID du document auquel cet élément est lié.	Oui
`label`	`string`	Le nom à afficher pour cet élément.	Non	`docId`
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`
`activeSidebarClassName`	`string`	Le nom de la classe CSS à appliquer lorsque la barre latérale de ce doc est active.	Non	`'navbar__link--active'`
`docsPluginId`	`string`	L'ID du plugin docs auquel appartient le doc.	Non	`'default'`

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'doc',          position: 'left',          docId: 'introduction',          label: 'Docs',        },      ],    },  },};

Liste déroulante de version dans la barre de navigation#

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Ajoute des éléments supplémentaires au début de la liste déroulante.	Non	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Ajoute des éléments supplémentaires à la fin de la liste déroulante.	Non	`[]`
`docsPluginId`	`string`	L'ID du plugin docs auquel appartient la version du doc.	Non	`'default'`
`dropdownActiveClassDisabled`	`boolean`	N'ajoute pas la classe de lien actif lors de la navigation dans la documentation.	Non	`false`

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',          position: 'left',          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],          dropdownActiveClassDisabled: true,        },      ],    },  },};

Version des docs dans la barre de navigation#

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`label`	`string`	Le nom à afficher pour cet élément.	Non	Le label actif/dernière version.
`to`	`string`	Le lien interne vers lequel pointe cet élément.	Non	La version active/dernière.
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`
`docsPluginId`	`string`	L'ID du plugin docs auquel appartient la version du doc.	Non	`'default'`

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersion',          position: 'left',          to: '/path',          label: 'label',        },      ],    },  },};

Liste déroulante des locales dans la barre de navigation#

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 :

Champ	Valeur	Explication	Obligatoire	Par défaut
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`
`dropdownItemsBefore`	`LinkLikeItem[]`	Ajoute des éléments supplémentaires au début de la liste déroulante.	Non	`[]`
`dropdownItemsAfter`	`LinkLikeItem[]`	Ajoute des éléments supplémentaires à la fin de la liste déroulante.	Non	`[]`

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',          position: 'left',          dropdownItemsAfter: [            {              to: 'https://my-site.com/help-us-translate',              label: 'Help us translate',            },          ],        },      ],    },  },};

Recherche dans la barre de navigation#

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.

Champ	Valeur	Explication	Obligatoire	Par défaut
`position`	`'left' \| 'right'`	Le côté de la barre de navigation sur lequel cet élément doit apparaître.	Non	`'left'`

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'search',          position: 'right',        },      ],    },  },};

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

module.exports = {  // ...  themeConfig: {    navbar: {      hideOnScroll: true,    },    // ...  },};

Style de barre de navigation#

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

module.exports = {  // ...  themeConfig: {    navbar: {      style: 'primary',    },    // ...  },};

Bloc de code#

Docusaurus utilise le générateur de rendu Prism React pour mettre en évidence les blocs de code.

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. Si vous voulez utiliser un thème de syntaxe différent lorsque le site est en mode sombre, vous pouvez aussi le faire.

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      theme: require('prism-react-renderer/themes/github'),      darkTheme: require('prism-react-renderer/themes/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 valide doit être passé, par exemple :

docusaurus.config.js

module.exports = {  // ...  themeConfig: {    prism: {      defaultLanguage: 'javascript',    },    // ...  },};

Footer#

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.

docusaurus.config.js

  // ...  footer: {    logo: {      alt: 'Facebook Open Source Logo',      src: 'img/oss_logo.png',      href: 'https://opensource.facebook.com',    },    copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,  }

Liens de pied de page#

Vous pouvez ajouter des éléments au pied de page via themeConfig.footer.links :

docusaurus.config.js

module.exports = {  // ...  footer: {    links: [      {        // Libellé de la section de ces liens        title: 'Docs',        items: [          {            // Libellé du lien            label: 'Guide de style',            // Routage côté client, utilisé pour naviguer dans le site web.            // La baseUrl sera automatiquement ajoutée à cette valeur.            to: 'docs/',          },          {            label: 'Second Doc',            to: 'docs/doc2/',          },        ],      },      {        title: 'Communauté',        items: [          {            label: 'Stack Overflow',            // Une navigation pleine page, utilisée pour naviguer en dehors du site web.            href: 'https://stackoverflow.com/questions/tagged/docusaurus',          },          {            label: 'Discord',            href: 'https://discordapp.com/invite/docusaurus',          },          {            label: 'Twitter',            href: 'https://twitter.com/docusaurus',          },          {            // Rend le html passé au lieu d'un simple lien            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" />                </a>              `,          },        ],      },    ],  },};

Commun#

Mode clair - mode sombre#

caution

Méta image#

Métadonnées#

Barre d'annonce#

i18n#

Emplacement des fichiers de traduction#

Exemple de structure du système de fichiers#

Hooks#

useThemeContext#

remarque

Barre de navigation#

Titre & logo de la barre de navigation#

Éléments de la barre de navigation#

Lien de la barre de navigation#

Menu déroulant de la barre de navigation#

Lien vers un doc dans la barre de navigation#

Liste déroulante de version dans la barre de navigation#

Version des docs dans la barre de navigation#

Liste déroulante des locales dans la barre de navigation#

Recherche dans la barre de navigation#

Masquage automatique de la barre de navigation flottante#

Style de barre de navigation#

Bloc de code#

Thème#

remarque

Langage par défaut#

Footer#

Liens de pied de page#

`useThemeContext`#