Aller au contenu principal
Version : 2.4.0

Docs Multi-Instance

The @docusaurus/plugin-content-docs plugin can support multi-instance.

remarque

This feature is only useful for versioned documentation. Il est recommandé de se familiariser avec les versions de docs avant de lire cette page. If you just want multiple sidebars, you can do so within one plugin.

Use-cases​

Parfois, vous voulez qu'un site Docusaurus héberge 2 ensembles distincts de documentation (ou plus).

Ces documentations peuvent même avoir des versions/cycles de vie différents.

Mobile SDKs documentation​

Si vous construisez un SDK mobile multi-plateforme, vous pouvez avoir 2 documentations :

  • Android SDK documentation (v1.0, v1.1)
  • iOS SDK documentation (v1.0, v2.0)

Dans ce cas, vous pouvez utiliser une instance distincte de docs pour chaque documentation SDK mobile.

attention

Si chaque instance de documentation est très grande, vous devriez plutôt créer 2 sites Docusaurus distincts.

Si quelqu'un modifie la documentation iOS, est-il vraiment utile de tout reconstruire, y compris toute la documentation Android qui n'a pas changé ?

Versioned and unversioned doc​

Parfois, vous souhaitez que certains documents soient versionnés, tandis que d'autres documents sont plus « globaux », et il vous semble inutile de les versionner.

Nous utilisons ce modèle sur le site web de Docusaurus :

Setup​

Supposons que vous ayez 2 documentations :

  • Produit : un document versionné à propos de votre produit
  • Communauté : quelques documents non versionnés sur la communauté autour de votre produit

Dans ce cas, vous devez utiliser le même plugin deux fois dans la configuration de votre site.

attention

@docusaurus/preset-classic already includes a docs plugin instance for you!

Lors de l'utilisation du preset :

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // id: 'product', // omitted => default instance
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: require.resolve('./sidebarsProduct.js'),
          // ... other options
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: require.resolve('./sidebarsCommunity.js'),
        // ... other options
      },
    ],
  ],
};

Si vous n'utilisez pas le preset :

docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // omitted => default instance
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: require.resolve('./sidebarsProduct.js'),
        // ... other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: require.resolve('./sidebarsCommunity.js'),
        // ... other options
      },
    ],
  ],
};

Don't forget to assign a unique id attribute to plugin instances.

remarque

We consider that the product instance is the most important one, and make it the "default" instance by not assigning any ID.

Versioned paths​

Chaque instance de plugin stockera les documentations versionnées dans un dossier distinct.

L'instance de plugin par défaut utilisera ces chemins :

  • website/versions.json
  • website/versioned_docs
  • website/versioned_sidebars

The other plugin instances (with an id attribute) will use these paths:

  • website/[pluginId]_versions.json
  • website/[pluginId]_versioned_docs
  • website/[pluginId]_versioned_sidebars
astuce

You can omit the id attribute (defaults to default) for one of the docs plugin instances.

Les chemins de l'instance seront plus simples et rétro-compatibles avec la configuration d'une instance unique.

Tagging new versions​

Chaque instance de plugin aura sa propre commande CLI pour taguer une nouvelle version. Ils sont alors affichés si vous vous exécutez :

npm run docusaurus -- --help

Pour la version de l'instance de product/par défaut :

npm run docusaurus docs:version 1.0.0

Pour la version de l'instance de community :

npm run docusaurus docs:version:community 1.0.0

Docs navbar items​

Each docs-related theme navbar items take an optional docsPluginId attribute.

Par exemple, si vous voulez avoir une liste déroulante pour chaque SDK mobile (iOS et Android), vous pouvez faire :

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};