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 :
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.
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).
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.
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.jsonHooks#
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.
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.
Par défaut, les éléments de la barre de navigation sont des liens ordinaires (internes ou externes).
module.exports = { // ... themeConfig: { navbar: { items: [ { // Routage côté client, utilisé pour naviguer dans le site web. // La baseUrl sera automatiquement ajoutée à cette valeur. to: 'docs/introduction', // Une navigation pleine page, utilisée pour naviguer en dehors du site Web. // Vous ne devriez utiliser que `to` ou `href`. href: 'https://www.facebook.com', // Fait précéder baseUrl aux valeurs href. prependBaseUrlToHref: true, // La chaîne à afficher. label: 'Introduction', // Le côté gauche ou droit de la barre de navigation. position: 'left', // ou 'right' // Pour appliquer le style de classe active sur toutes les routes // commençant par ce chemin. // Ce n'est généralement pas nécessaire activeBasePath: 'docs', // Alternative à activeBasePath si nécessaire. activeBaseRegex: 'docs/(next|v8)', // Classe CSS personnalisée (pour styliser n'importe quel élément). className: '', }, // ... autres éléments ], }, // ... },};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".
Menu déroulant de la barre de navigation#
Les éléments de la barre de navigation peuvent également être des éléments déroulants en spécifiant items, un tableau interne d'éléments de la barre de navigation.
module.exports = { // ... themeConfig: { navbar: { items: [ { label: 'Communauté', position: 'left', // ou 'right' items: [ { label: 'Facebook', href: '...', }, { label: 'GitHub', href: '...', }, // ... 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.
module.exports = { themeConfig: { navbar: { items: [ { type: 'doc', docId: 'introduction',
//// Facultatif position: 'left', label: 'Docs', activeSidebarClassName: 'navbar__link--active', docsPluginId: 'default', }, ], }, },};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).
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersionDropdown',
//// Facultatif position: 'left', // Ajoute des éléments supplémentaires au début/à la fin de la liste déroulante. dropdownItemsBefore: [], dropdownItemsAfter: [{to: '/versions', label: 'Toutes les versions'}], // N'ajoute pas la classe du lien actif lors de la navigation dans les docs. dropdownActiveClassDisabled: true, docsPluginId: 'default', }, ], }, },};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.
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersion',
//// Facultatif position: 'left', to: '/path', // par défaut, le lien de la version active/dernière label: 'libellé', // par défaut, affiche le libellé de la version active/dernière docsPluginId: 'default', }, ], }, },};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.
module.exports = { themeConfig: { navbar: { items: [ { type: 'localeDropdown',
//// Facultatif position: 'left', // Ajoute des éléments supplémentaires dans la liste déroulante au début/fin de la liste déroulante. dropdownItemsBefore: [], dropdownItemsAfter: [ { to: 'https://my-site.com/help-us-translate', label: 'Aidez-nous à traduire', }, ], }, ], }, },};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.
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.
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.
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.
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 :
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.
// ... 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 :
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> `, }, ], }, ], },};