Version: 2.0.0-beta.5 🚧

Configuration du thème

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

Commun#

Color mode#

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.

It is possible to customize the color mode support within the colorMode object.

Champs acceptés :

Name	Type	Default	Description
`defaultMode`	!!crwdBlockTags_255_sgaTkcolBdwrc!!	`'light'`	The color mode when user first visits the site.
`disableSwitch`	`boolean`	`false`	Hides the switch in the navbar. Useful if you want to support a single color mode.
`respectPrefersColorScheme`	`boolean`	`false`	Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`.
`switchConfig`	See below	See below	Dark/light switch icon options.
`switchConfig.darkIcon`	`string`	`'🌜'`	Icon for the switch while in dark mode.
`switchConfig.darkIconStyle`	JSX style object (see documentation)	`{}`	CSS to apply to dark icon.
`switchConfig.lightIcon`	`string`	`'🌞'`	Icon for the switch while in light mode.
`switchConfig.lightIconStyle`	JSX style object	`{}`	CSS to apply to light icon.

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    colorMode: {      defaultMode: 'light',      disableSwitch: false,      respectPrefersColorScheme: false,      switchConfig: {        darkIcon: '🌙',        darkIconStyle: {          marginLeft: '2px',        },        // Unicode icons such as '\u2600' will work        // Unicode with 5 chars require brackets: '\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.

Champs acceptés :

Name	Type	Default	Description
`image`	`string`	`undefined`	The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Peut également être des URL externes.

Exemple de configuration :

docusaurus.config.js

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

Name	Type	Default	Description
`metadatas`	`Metadata[]`	`[]`	Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc.

Exemple de configuration :

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. All configuration are in the announcementBar object.

Champs acceptés :

Name	Type	Default	Description
`id`	`string`	`'announcement-bar'`	Any value that will identify this message.
`content`	`string`	`''`	The text content of the announcement. HTML will be interpolated.
`backgroundColor`	`string`	`'#fff'`	Background color of the entire bar.
`textColor`	`string`	`'#000'`	Announcement text color.
`isCloseable`	`boolean`	`true`	Whether this announcement can be dismissed with a '×' button.

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    announcementBar: {      id: 'support_us',      content:        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',      backgroundColor: '#fafbfc',      textColor: '#091E42',      isCloseable: false,    },  },};

Barre de navigation#

Champs acceptés :

Name	Type	Default	Description
`title`	`string`	`undefined`	Title for the navbar.
`logo`	See below	`undefined`	Customization of the logo object.
`items`	`NavbarItem[]`	`[]`	A list of navbar items. See specification below.
`hideOnScroll`	`boolean`	`false`	Whether the navbar is hidden when the user scrolls down.
`style`	!!crwdBlockTags_299_sgaTkcolBdwrc!!	Same as theme	Sets the navbar style, ignoring the dark/light theme.

Navbar logo#

The logo can be placed in static folder. 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 :

Name	Type	Default	Description
`alt`	`string`	`undefined`	Alt tag for the logo image.
`src`	`string`	Required	URL to the logo image. Base URL is appended by default.
`srcDark`	`string`	`logo.src`	An alternative image URL to use in dark mode.
`href`	`string`	`siteConfig.baseUrl`	Link to navigate to when the logo is clicked.
`target`	`string`	Calculated based on `href` (external links will open in a new tab, all others in the current one).	The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise.

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    navbar: {      title: 'Site Title',      logo: {        alt: 'Site Logo',        src: 'img/logo.svg',        srcDark: 'img/logo_dark.svg',        href: 'https://docusaurus.io/',        target: '_self',      },    },  },};

É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 :

Name	Type	Default	Description
`label`	`string`	Required	The name to be shown for this item.
`to`	`string`	Required	Client-side routing, used for navigating within the website. La baseUrl sera automatiquement ajoutée à cette valeur.
`href`	`string`	Required	A full-page navigation, used for navigating outside of the website. Only one of `to` or `href` should be used.
`prependBaseUrlToHref`	`boolean`	`false`	Prepends the baseUrl to `href` values.
`position`	!!crwdBlockTags_342_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`activeBasePath`	`string`	`to` / `href`	To apply the active class styling on all routes starting with this path. Cela n'est généralement pas nécessaire.
`activeBaseRegex`	`string`	`undefined`	Alternative to `activeBasePath` if required.
`className`	`string`	`''`	Custom CSS class (for styling any item).

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 des docs dans 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 :

Name	Type	Default	Description
`label`	`string`	Required	The name to be shown for this item.
`items`	!!crwdBlockTags_349_sgaTkcolBdwrc!!	Required	The items to be contained in the dropdown.
`position`	!!crwdBlockTags_350_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.

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 :

Name	Type	Default	Description
`docId`	`string`	Required	The ID of the doc that this item links to.
`label`	`string`	`docId`	The name to be shown for this item.
`position`	!!crwdBlockTags_362_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`docsPluginId`	`string`	`'default'`	The ID of the docs plugin that the doc belongs to.

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 :

Name	Type	Default	Description
`position`	!!crwdBlockTags_376_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`dropdownItemsBefore`	!!crwdBlockTags_377_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the beginning of the dropdown.
`dropdownItemsAfter`	!!crwdBlockTags_378_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the end of the dropdown.
`docsPluginId`	`string`	`'default'`	The ID of the docs plugin that the doc versioning belongs to.
`dropdownActiveClassDisabled`	`boolean`	`false`	Do not add the link active class when browsing docs.

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 :

Name	Type	Default	Description
`label`	`string`	The active/latest version label.	The name to be shown for this item.
`to`	`string`	The active/latest version.	The internal link that this item points to.
`position`	!!crwdBlockTags_389_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`docsPluginId`	`string`	`'default'`	The ID of the docs plugin that the doc versioning belongs to.

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 :

Name	Type	Default	Description
`position`	!!crwdBlockTags_397_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.
`dropdownItemsBefore`	!!crwdBlockTags_398_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the beginning of the dropdown.
`dropdownItemsAfter`	!!crwdBlockTags_399_sgaTkcolBdwrc!!	`[]`	Add additional dropdown items at the end of the dropdown.

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.

Name	Type	Default	Description
`position`	!!crwdBlockTags_403_sgaTkcolBdwrc!!	`'left'`	The side of the navbar this item should appear on.

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. All configuration are in the prism object.

Champs acceptés :

Name	Type	Default	Description
`theme`	`PrismTheme`	`palenight`	The Prism theme to use for light-theme code blocks.
`darkTheme`	`PrismTheme`	`palenight`	The Prism theme to use for dark-theme code blocks.
`defaultLanguage`	`string`	`undefined`	The side of the navbar this item should appear on.

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. You may also use a different syntax highlighting theme when the site is in dark mode.

Exemple de configuration :

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 ```). Note that a valid language name must be passed.

Exemple de configuration :

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.

Champs acceptés :

Name	Type	Default	Description
`logo`	`Logo`	`undefined`	Customization of the logo object. See Navbar logo for details.
`copyright`	`string`	`undefined`	The copyright message to be displayed at the bottom.
`style`	!!crwdBlockTags_426_sgaTkcolBdwrc!!	`'light'`	The color theme of the footer component.
`items`	`FooterItem[]`	`[]`	The link groups to be present.

Exemple de configuration :

docusaurus.config.js

module.exports = {  themeConfig: {    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#

You can add links to the footer via themeConfig.footer.links.

Accepted fields of each link section:

Name	Type	Default	Description
`title`	`string`	`undefined`	Label of the section of these links.
`items`	`FooterLink[]`	`[]`	Links in this section.

Accepted fields of each item in items:

Name	Type	Default	Description
`label`	`string`	Required	Text to be displayed for this link.
`to`	`string`	Required	Client-side routing, used for navigating within the website. La baseUrl sera automatiquement ajoutée à cette valeur.
`href`	`string`	Required	A full-page navigation, used for navigating outside of the website. Only one of `to` or `href` should be used.
`html`	`string`	`undefined`	Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided.

Exemple de configuration :

docusaurus.config.js

module.exports = {  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: 'Twitter',            href: 'https://twitter.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" />                </a>              `,          },        ],      },    ],  },};

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>  );}

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

Commun#

Color mode#

caution

Méta image#

Métadonnées#

Barre d'annonce#

Barre de navigation#

Navbar logo#

É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#

Hooks#

useThemeContext#

remarque

i18n#

Emplacement des fichiers de traduction#

Exemple de structure du système de fichiers#

`useThemeContext`#