Docs Multi-Instance
The @docusaurus/plugin-content-docs
plugin can support multi-instance.
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.
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 :
- The /docs/* section is versioned
- The /community/* section is unversioned
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.
@docusaurus/preset-classic
already includes a docs plugin instance for you!
Lors de l'utilisation du preset :
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 :
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.
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
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
- Yarn
- pnpm
npm run docusaurus -- --help
yarn docusaurus --help
pnpm run docusaurus -- --help
Pour la version de l'instance de product/par défaut :
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.0.0
yarn docusaurus docs:version 1.0.0
pnpm run docusaurus docs:version 1.0.0
Pour la version de l'instance de community :
- npm
- Yarn
- pnpm
npm run docusaurus docs:version:community 1.0.0
yarn docusaurus docs:version:community 1.0.0
pnpm 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 :
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};