Aller au contenu principal
Version: 2.0.0-beta.1 🚧

Thèmes

Tout comme les plugins, les thèmes sont conçus pour ajouter des fonctionnalités à votre site Docusaurus. En règle générale, les thèmes sont principalement axés sur les fonctionnalités côté client, tandis que les plugins sont davantage axés sur les fonctionnalités côté serveur. Les thèmes sont également conçus pour être remplaçables par d'autres thèmes.

Thèmes disponibles#

Nous maintenons une liste de thèmes officiels.

Utilisation des thèmes#

Pour utiliser des thèmes, spécifiez les thèmes dans votre docusaurus.config.js. Vous pouvez utiliser plusieurs thèmes :

docusaurus.config.js
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

Composants du thème#

La plupart du temps, le thème est utilisé pour fournir un ensemble de composants React, par exemple Navbar, Layout, Footer.

Les utilisateurs peuvent utiliser ces composants dans leur code en les important en utilisant l'alias de webpack @theme :

import Navbar from '@theme/Navbar';

L'alias @theme peut faire référence à quelques répertoires, selon la priorité suivante :

  1. Un répertoire website/src/theme d'un utilisateur, qui est un répertoire spécial qui a la priorité supérieure.
  2. Un répertoire theme du paquet du thème de Docusaurus.
  3. Des composants de secours fournis par le noyau de Docusaurus (généralement pas nécessaire).

Considérons la structure suivante

website
├── node_modules
│ └── docusaurus-theme
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js

website/src/theme/Navbar.js est prioritaire lorsque @theme/Navbar est importé. Ce comportement est appelé « swizzling de composant ». Dans iOS, le « swizzling » (modification) de méthode consiste à changer l'implémentation d'un sélecteur (d'une méthode) existant. Dans le contexte d'un site Web, le « swizzling de composant » signifie fournir un composant alternatif qui a la priorité sur le composant fourni par le thème.

Les thèmes servent à fournir des composants de l'interface utilisateur pour présenter le contenu. La plupart des plugins de contenu doivent être associés à un thème pour être réellement utiles. L'interface utilisateur est une couche séparée du schéma de données, donc il est facile d'échanger les thèmes pour d'autres designs (c'est-à-dire Bootstrap).

Par exemple, un blog Docusaurus se compose d'un plugin de blog et d'un thème de blog.

docusaurus.config.js
{
theme: ['theme-blog'],
plugins: ['plugin-content-blog'],
}

Et si vous voulez utiliser le style Bootstrap, vous pouvez échanger le thème avec theme-blog-bootstrap (thème fictif qui n'existe pas) :

docusaurus.config.js
{
theme: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
}

Enveloppez votre site avec <Root>#

Un composant de thème <Root> est affiché en haut de votre site Docusaurus.

Il vous permet d'envelopper votre site d'une logique supplémentaire, en créant un fichier src/theme/Root.js :

website/src/theme/Root.js
import React from 'react';
// Implémentation par défaut, que vous pouvez personnaliser
function Root({children}) {
return <>{children}</>;
}
export default Root;

Ce composant est appliqué au-dessus du routeur et du thème <Layout>, et ne sera jamais démonté.

astuce

Utilisez ce composant pour rendre les providers de contexte React et la logique globale de l'état.

Swizzler les composants du thème#

attention

Nous décourageons de « swizzler » des composants pendant la phase bêta du Docusaurus 2. Les API des composants de thèmes sont susceptibles d'évoluer et de subir des modifications. Si possible, restez avec l'apparence par défaut pour le moment.

Les composants des Thèmes Docusaurus sont conçus pour être remplacés. Pour vous faciliter la tâche, nous avons créé une commande pour vous permettre de remplacer les composants du thème appelée swizzle.

Pour swizzler un composant pour un thème, exécutez la commande suivante dans votre site de doc :

npm run swizzle <theme name> [component name]

Par exemple, pour swizzler le composant <Footer /> dans @docusaurus/theme-classic pour votre site, exécutez :

npm run swizzle @docusaurus/theme-classic Footer

Cela copiera le composant <Footer /> actuel utilisé par le thème dans un répertoire src/theme/Footer sous la racine de votre site, qui est l'endroit où Docusaurus cherchera les composants swizzlés. Docusaurus utilisera alors le composant swizzlé à la place du composant original du thème.

Bien que nous décourageons fortement de swizzler tous les composants, si vous le souhaitez, exécutez :

npm run swizzle @docusaurus/theme-classic

Remarque : vous devez redémarrer votre serveur de développement webpack pour que Docusaurus connaisse le nouveau composant.

Envelopper les composants du thème#

Parfois, vous souhaitez simplement envelopper un composant de thème existant avec une logique supplémentaire, et il peut être pénible de devoir maintenir une copie presque identique du composant de thème original.

Dans ce cas, vous devez swizzler le composant que vous souhaitez envelopper, mais importer le composant du thème original dans votre version personnalisée pour l'envelopper.

Pour les propriétaires du site#

L'alias @theme-original vous permet d'importer le composant du thème original.

Voici un exemple pour afficher du texte juste au-dessus du pied de page, avec une duplication minimale du code.

src/theme/Footer.js
// Remarque : l'importation à partir de "@theme/Footer" échouerait en raison de l'importation du fichier lui-même.
import OriginalFooter from '@theme-original/Footer';
import React from 'react';
export default function Footer(props) {
return (
<>
<div>Before footer</div>
<OriginalFooter {...props} />
</>
);
}

Pour les auteurs de plugins#

Un thème peut envelopper un composant d'un autre thème, en important le composant du thème initial, à l'aide de l'import @theme-init.

Voici un exemple d'utilisation de cette fonctionnalité pour améliorer le composant CodeBlock du thème par défaut avec une fonctionnalité de terrain de jeu react-live.

import InitialCodeBlock from '@theme-init/CodeBlock';
import React from 'react';
export default function CodeBlock(props) {
return props.live ? (
<ReactLivePlayground {...props} />
) : (
<InitialCodeBlock {...props} />
);
}

Vérifiez le code de docusaurus-theme-live-codeblock pour plus de détails.

attention

À moins que vous ne vouliez publier sur npm un « rehausseur de thème » (comme docusaurus-theme-live-codeblock), vous n'avez probablement pas besoin de @theme-init.

Conception de thèmes#

Alors que les thèmes partagent exactement les mêmes méthodes de cycle de vie avec les plugins, leurs implémentations peuvent être très différentes de celles des plugins en fonction des objectifs définis par les thèmes.

Les thèmes sont conçus pour compléter la construction de votre site Docusaurus et fournir les composants utilisés par votre site, les plugins et les thèmes eux-mêmes. Ainsi, une implémentation typique de thème ressemblerait à un fichier src/index.js qui le relie aux méthodes du cycle de vie. Il est fort probable qu'ils n'utilisent pas le loadContent, que les plugins utilisent. Et il est généralement accompagné d'un répertoire src/theme plein de composants.

Pour résumer :

  • Les thèmes partagent les mêmes méthodes de cycle de vie avec les plugins
  • Les thèmes sont exécutés après tous les plugins existants
  • Des thèmes existent pour ajouter des alias de composants en étendant la configuration de webpack

Écriture de thèmes Docusaurus personnalisés#

Un thème Docusaurus comprend normalement un fichier index.js dans lequel vous vous connectez aux méthodes du cycle de vie, ainsi qu'un répertoire theme/ de composants. Un dossier typique du theme de Docusaurus ressemble à ceci :

website
├── package.json
└── src
├── index.js
└── theme
├── MyThemeComponent
└── AnotherThemeComponent.js

Il y a deux méthodes de cycle de vie qui sont essentielles à l'implémentation du thème :

Ces méthodes de cycle de vie ne sont pas essentielles, mais recommandées :