📦 plugin-client-redirects

Plugin Docusaurus pour générer les redirections côté client.

Ce plugin écrirera des pages HTML supplémentaires sur votre site statique qui redirige l'utilisateur vers vos pages Docusaurus existantes avec JavaScript.

seulement en production

Ce plugin est toujours inactif en développement et uniquement actif en production car il fonctionne sur la sortie de la construction.

attention

Il est préférable d'utiliser les redirections côté serveur chaque fois que cela est possible.

Avant d'utiliser ce plugin, vous devez vérifier si votre fournisseur d'hébergement n'offre pas cette fonctionnalité.

Installation

npm

npm install --save @docusaurus/plugin-client-redirects

Yarn

yarn add @docusaurus/plugin-client-redirects

pnpm

pnpm add @docusaurus/plugin-client-redirects

Configuration

Champs acceptés :

Option	Type	Par défaut	Description
fromExtensions	string[]	[]	Les extensions à retirer de la route après redirection.
toExtensions	string[]	[]	Les extensions à ajouter à la route après redirection.
redirects	RedirectRule[]	[]	La liste des règles de redirection.
createRedirects	CreateRedirectsFn	undefined	Un callback pour créer une règle de redirection. Docusaurus interroge ce callback pour chaque chemin qu'il a créé, et utilise sa valeur de retour pour produire d'autres chemins.

remarque

Ce plugin lira également la configuration siteConfig.onDuplicateRoutes pour configurer son niveau de journalisation lorsque plusieurs fichiers seront émis au même endroit.

Types

RedirectRule

type RedirectRule = {
  to: string;
  from: string | string[];
};

remarque

L'idée de "from" et "to" est primordiale dans ce plugin. "From" signifie un chemin que vous voulez créer, c'est-à-dire un fichier HTML supplémentaire qui sera créé, "To" signifie un chemin vers lequel vous voulez rediriger, généralement une route que Docusaurus connaît déjà.

C'est pourquoi vous pouvez avoir plusieurs "from" pour le même "to" : nous allons créer plusieurs fichiers HTML qui redirigent tous vers la même destination. A l'inverse, un "from" ne peut jamais avoir plus d'un "to" : le fichier HTML écrit doit avoir une destination déterminée.

CreateRedirectsFn

// Le paramètre `path` est une route que Docusaurus a déjà créée. Il peut être vu
// comme le "to", et votre valeur de retour est le "from". Retourner une valeur falsy
// ne créera aucune page de redirection pour ce chemin particulier.
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

Exemple de configuration

Voici un exemple de configuration :

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
        toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists)
        redirects: [
          // /docs/oldDoc -> /docs/newDoc
          {
            to: '/docs/newDoc',
            from: '/docs/oldDoc',
          },
          // Redirection depuis plusieurs anciens chemins vers le nouveau chemin
          {
            to: '/docs/newDoc2',
            from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
          },
        ],
        createRedirects(existingPath) {
          if (existingPath.includes('/community')) {
            // Redirection de /docs/team/X vers /community/X et /docs/support/X vers /community/X
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // Renvoie une valeur fausse : pas de redirection créée
        },
      },
    ],
  ],
};