Docs Multi-Instance
Le plugin @docusaurus/plugin-content-docs
peut prendre en charge la multi-instance.
Cette fonctionnalité n'est utile que pour la documentation versionnée. Il est recommandé de se familiariser avec les versions de docs avant de lire cette page. Si vous voulez juste plusieurs barres latérales, vous pouvez le faire dans un seul plugin.
Cas d'utilisation
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.
Documentation des SDK mobiles
Si vous construisez un SDK mobile multi-plateforme, vous pouvez avoir 2 documentations :
- Documentation d'Android SDK (
v1.0
,v1.1
) - Documentation iOS SDK (
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é ?
Documentation versionnée et non versionnée
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 :
- La section /docs/* est versionnée
- La section /community/* n'est pas versionnée
Configuration
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
inclut déjà une instance de plugin de docs pour vous !
Lors de l'utilisation du preset :
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// id: 'product', // omis => instance par défaut
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... d'autres options
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... d'autres options
},
],
],
};
Si vous n'utilisez pas le preset :
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// id: 'product', // omis => instance par défaut
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... d'autres options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... d'autres options
},
],
],
};
N'oubliez pas d'affecter un attribut id
unique aux instances de plugin.
Nous considérons que l'instance product
est la plus importante, et donc en ne lui attribuant aucun ID, nous faisons d'elle l'instance « par défaut ».
Chemins versionnés
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
Les autres instances de plugin (avec un attribut id
) utiliseront ces chemins :
website/[pluginId]_versions.json
website/[pluginId]_versioned_docs
website/[pluginId]_versioned_sidebars
Vous pouvez omettre l'attribut id
(par défaut à default
) pour l'une des instances du plugin de docs.
Les chemins de l'instance seront plus simples et rétro-compatibles avec la configuration d'une instance unique.
Étiquetage des nouvelles 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
Éléments de la barre de navigation des docs
Chaque élément du thème de la barre de navigation lié à la documentation prend un attribut facultatif docsPluginId
.
Par exemple, si vous voulez avoir une liste déroulante pour chaque SDK mobile (iOS et Android), vous pouvez faire :
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};