Aller au contenu principal
Version: 2.0.0-beta.7

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!!crwdBlockTags_263_sgaTkcolBdwrc!!'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.
switchConfigVoir ci-dessousVoir ci-dessousOptions d'icônes sombres/claires.
switchConfig.darkIconstring'🌜'Icône de l'interrupteur en mode sombre.
switchConfig.darkIconStyleObjet de style JSX (voir documentation){}CSS à appliquer à l'icône sombre.
switchConfig.lightIconstring'🌞'Icône de l'interrupteur en mode clair.
switchConfig.lightIconStyleObjet de style JSX{}CSS à appliquer à l'icône claire.

Exemple de configuration :

docusaurus.config.js
module.exports = {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
switchConfig: {
darkIcon: '🌙',
darkIconStyle: {
marginLeft: '2px',
},
// Les icônes Unicode telles que '\u2600' fonctionnent.
// Les icônes Unicode à 5 caractères nécessitent des parenthèses : '\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 :

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

NomTypePar défautDescription
metadatasMetadata[][]Tout champ sera directement transmis à la balise <meta />. Les champs possibles sont notamment 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. 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 d'arrière-plan de la barre entière.
textColorstring'#000'Couleur du texte de l'annonce.
isCloseablebooleantrueSi cette annonce peut être ignorée avec un bouton '×'.

Exemple de configuration :

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

Champs acceptés :

NomTypePar défautDescription
titlestringundefinedTitre de la barre de navigation.
logoVoir ci-dessousundefinedPersonnalisation de l'objet logo.
itemsNavbarItem[][]Une liste des éléments de la barre de navigation. Voir les spécifications ci-dessous.
hideOnScrollbooleanfalseIndique si la barre de navigation est masquée lorsque l'utilisateur fait défiler la page vers le bas.
style!!crwdBlockTags_307_sgaTkcolBdwrc!!Identique au thèmeDéfinit le style de la barre de navigation, ignorant le thème sombre/clair.

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
altstringundefinedBalise Alt pour l'image du logo.
srcstringObligatoireURL de l'image du logo. L'URL de base est ajoutée par défaut.
srcDarkstringlogo.srcUne URL d'image alternative à utiliser en mode sombre.
hrefstringsiteConfig.baseUrlLien vers lequel naviguer lorsque le logo est cliqué.
targetstringCalculé à partir de href (les liens externes s'ouvriront dans un nouvel onglet, tous les autres dans le même onglet).L'attribut target du lien; contrôle si le lien est ouvert dans un nouvel onglet, l'actuel ou autre.

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',
},
},
},
};

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.

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
labelstringObligatoireLe nom à afficher pour cet élément.
tostringObligatoireRoutage côté client, utilisé pour naviguer dans le site web. La baseUrl sera automatiquement ajoutée à cette valeur.
hrefstringObligatoireUne navigation pleine page, utilisée pour naviguer en dehors du site Web. Un seul de to ou href doit être utilisé.
prependBaseUrlToHrefbooleanfalseAjoute la baseUrl aux valeurs href.
position!!crwdBlockTags_350_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
activeBasePathstringto / hrefPour appliquer le style de classe active sur toutes les routes commençant par ce chemin. Cela n'est généralement pas nécessaire.
activeBaseRegexstringundefinedAlternative à activeBasePath si nécessaire.
classNamestring''Classe CSS personnalisée (pour styliser n'importe quel élément).
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
module.exports = {
themeConfig: {
navbar: {
items: [
{
to: 'docs/introduction',
// Un seul de "to" ou "href" doit être utilisé
// href: 'https://www.facebook.com',
label: 'Introduction',
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
labelstringObligatoireLe nom à afficher pour cet élément.
items!!crwdBlockTags_357_sgaTkcolBdwrc!!ObligatoireLes éléments à contenir dans le menu déroulant.
position!!crwdBlockTags_358_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.

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
],
},
],
},
},
};

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
docIdstringObligatoireL'ID du doc auquel cet élément renvoie.
labelstringdocIdLe nom à afficher pour cet élément.
position!!crwdBlockTags_370_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
docsPluginIdstring'default'L'ID du plugin docs auquel appartient le doc.

Exemple de configuration :

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

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
position!!crwdBlockTags_384_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
dropdownItemsBefore!!crwdBlockTags_385_sgaTkcolBdwrc!![]Ajouter des éléments supplémentaires au début du menu déroulant.
dropdownItemsAfter!!crwdBlockTags_386_sgaTkcolBdwrc!![]Ajouter des éléments supplémentaires à la fin du menu déroulant.
docsPluginIdstring'default'L'ID du plugin docs auquel appartient le versionnage du doc.
dropdownActiveClassDisabledbooleanfalseNe pas ajouter la classe active de lien lors de la navigation dans la documentation.

Exemple de configuration :

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
position: 'left',
dropdownItemsAfter: [{to: '/versions', label: 'All 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
labelstringLe libellé active/dernière version.Le nom à afficher pour cet élément.
tostringLa version active/dernière version.Le lien interne vers lequel pointe cet élément.
position!!crwdBlockTags_397_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
docsPluginIdstring'default'L'ID du plugin docs auquel appartient le versionnage du doc.

Exemple de configuration :

docusaurus.config.js
module.exports = {
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
position!!crwdBlockTags_405_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
dropdownItemsBefore!!crwdBlockTags_406_sgaTkcolBdwrc!![]Ajouter des éléments supplémentaires au début du menu déroulant.
dropdownItemsAfter!!crwdBlockTags_407_sgaTkcolBdwrc!![]Ajouter des éléments supplémentaires à la fin du menu déroulant.

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',
},
],
},
],
},
},
};

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
position!!crwdBlockTags_411_sgaTkcolBdwrc!!'left'Le côté de la barre de navigation sur lequel cet élément doit apparaître.
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,
},
},
};

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. 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 du thème sombre.
defaultLanguagestringundefinedLe côté de la barre de navigation sur laquelle cet élément devrait apparaître.

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
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é.

Exemple de configuration :

docusaurus.config.js
module.exports = {
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
logoLogoundefinedPersonnalisation de l'objet logo. Consultez le logo de barre de navigation pour plus de détails.
copyrightstringundefinedLe message de copyright à afficher en bas.
style!!crwdBlockTags_434_sgaTkcolBdwrc!!'light'Le thème de couleur du composant de pied de page.
itemsFooterItem[][]Les groupes de liens devant être présents.

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.`,
},
},
};

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

Champs acceptés de chaque section de lien :

NomTypePar défautDescription
titlestringundefinedLibellé de la section de ces liens.
itemsFooterLink[][]Liens dans cette section.

Champs acceptés de chaque élément dans items :

NomTypePar défautDescription
labelstringObligatoireTexte à afficher pour ce lien.
tostringObligatoireRoutage côté client, utilisé pour naviguer dans le site web. La baseUrl sera automatiquement ajoutée à cette valeur.
hrefstringObligatoireUne navigation pleine page, utilisée pour naviguer en dehors du site Web. *Un seul de to ou href doit être utilisé.
htmlstringundefinedRend le passage html au lieu d'un simple lien. Dans le cas où html est utilisé, aucune autre option ne devrait être fournie.

Exemple de configuration :

docusaurus.config.js
module.exports = {
footer: {
links: [
{
title: 'Docs',
items: [
{
label: 'Guide de style',
to: 'docs/',
},
{
label: 'Second doc',
to: 'docs/doc2/',
},
],
},
{
title: 'Communauté',
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>
`,
},
],
},
],
},
};

Table des matières

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

NomTypeTypePar défaut
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
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};

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