Utilisation de Plugins
Le noyau de Docusaurus ne fournit aucune fonctionnalité propre. Toutes les fonctionnalités sont déléguées à des plugins individuels : la fonctionnalité docs fournie par le plugin docs ; la fonctionnalité blog fournie par le plugin blog ; ou les pages individuelles fournies par le plugin pages. S'il n'y a pas de plugins installés, le site ne contiendra pas de routes.
Vous n'aurez peut-être pas besoin d'installer les plugins les plus courants un par un : ils peuvent être distribués sous forme de paquet dans un preset. Pour la plupart des utilisateurs, les plugins sont configurés via la configuration du preset.
Nous maintenons une liste de plugins officiels, mais la communauté a également créé des s plugins non officiels. Si vous souhaitez ajouter une fonctionnalité quelconque : génération automatique de pages de documentation, exécution de scripts personnalisés, intégration d'autres services... n'oubliez pas de consulter la liste : quelqu'un l'a peut-être implémentée pour vous !
Si vous vous sentez énergique, vous pouvez également lire le guide du plugin ou les références de la méthode du plugin pour savoir comment faire un plugin vous-même.
Installation d'un plugin
Un plugin est généralement un paquet npm, donc vous les installez comme les autres paquets npm en utilisant npm.
- npm
- Yarn
- pnpm
npm install --save docusaurus-plugin-name
yarn add docusaurus-plugin-name
pnpm add docusaurus-plugin-name
Puis vous l'ajoutez dans l'option plugins
dans docusaurus.config.js
de votre site :
export default {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};
Docusaurus peut également charger des plugins depuis votre répertoire local, avec quelque chose comme ceci :
export default {
// ...
plugins: ['./src/plugins/docusaurus-local-plugin'],
};
Les chemins doivent être absolus ou relatifs par rapport au fichier de configuration.
Configuration des plugins
Pour l'utilisation la plus basique des plugins, vous pouvez fournir juste le nom du plugin ou le chemin vers le plugin.
Cependant, les plugins peuvent avoir des options spécifiées en encapsulant le nom et un objet d'options dans un tuple à deux membres dans votre configuration. Ce style est généralement appelé « Style Babel ».
export default {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};
Exemple :
export default {
plugins: [
// Utilisation de base.
'@docusaurus/plugin-debug',
// Avec l'objet options (style babel)
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};
ID de plugins et de plugins multi-instance
Tous les plugins de contenu Docusaurus peuvent supporter plusieurs instances de plugins. Par exemple, il peut être utile d'avoir plusieurs instances de plugin docs ou plusieurs blogs. Il est nécessaire d'affecter un ID unique à chaque instance de plugin, et par défaut, l'ID du plugin est default
.
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-1',
// d'autres options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-2',
// d'autres options
},
],
],
};
Au maximum une instance de plugin peut être « l'instance de plugin default », en omettant l'attribut id
, ou en utilisant id : 'default'
.
Utilisation des thèmes
Les thèmes sont chargés exactement de la même manière que les plugins. Du point de vue du consommateur, les entrées themes
et plugins
sont interchangeables lors de l'installation et de la configuration d'un plugin. La seule nuance est que les thèmes sont chargés après les plugins, et il est possible pour un thème de remplacer les composants du thème par défaut d'un plugin.
Les options themes
et plugins
conduisent à des résolutions de raccourcis différentes, donc si vous voulez profiter des raccourcis, assurez-vous d'utiliser la bonne saisie !
export default {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};
Utiliser les presets
Les presets sont des paquets de plugins et de thèmes. Par exemple, au lieu de vous laisser enregistrer et configurer @docusaurus/plugin-content-docs
, @docusaurus/plugin-content-blog
, etc. les uns après les autres dans le fichier de configuration, nous avons le preset @docusaurus/preset-classic
qui vous permet de les configurer en un seul et même endroit centralisé.
@docusaurus/preset-classic
Le preset classic est expédié par défaut aux nouveaux sites web Docusaurus créés avec create-docusaurus
. Il contient les thèmes et plugins suivants :
@docusaurus/theme-classic
@docusaurus/theme-search-algolia
@docusaurus/plugin-content-docs
@docusaurus/plugin-content-blog
@docusaurus/plugin-content-pages
@docusaurus/plugin-debug
@docusaurus/plugin-google-gtag
@docusaurus/plugin-google-tag-manager
@docusaurus/plugin-google-analytics
(déprécié)@docusaurus/plugin-sitemap
@docusaurus/plugin-svgr
Le preset classic transmettra chaque entrée d'option au plugin/thème respectif.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
// Débogage par défaut à true dans dev, false dans prod
debug: undefined,
// Sera passé à @docusaurus/theme-classic.
theme: {
customCss: ['./src/css/custom.css'],
},
// Will be passed to @docusaurus/plugin-content-docs (false to disable)
docs: {},
// Will be passed to @docusaurus/plugin-content-blog (false to disable)
blog: {},
// Will be passed to @docusaurus/plugin-content-pages (false to disable)
pages: {},
// Will be passed to @docusaurus/plugin-sitemap (false to disable)
sitemap: {},
// Will be passed to @docusaurus/plugin-svgr (false to disable)
svgr: {},
// Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
gtag: {},
// Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
googleTagManager: {},
// DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
googleAnalytics: {},
},
],
],
};
Installation des presets
Un preset est généralement un paquet npm, donc vous les installez comme les autres paquets npm en utilisant npm.
- npm
- Yarn
- pnpm
npm install --save @docusaurus/preset-classic
yarn add @docusaurus/preset-classic
pnpm add @docusaurus/preset-classic
Puis, ajoutez-le dans l'option presets
de docusaurus.config.js
de votre site :
export default {
// ...
presets: ['@docusaurus/preset-classic'],
};
Les chemins du preset peuvent être relatifs à celui du fichier de configuration :
export default {
// ...
presets: ['./src/presets/docusaurus-local-preset'],
};
Création de presets
Un preset est une fonction ayant la même forme que le constructeur de plugin. Il devrait retourner un objet de { plugins: PluginConfig[], themes: PluginConfig[] }
, de la même manière qu'ils sont acceptés dans la configuration du site. Par exemple, vous pouvez spécifier un prest qui inclut les thèmes et plugins suivants:
export default function preset(context, opts = {}) {
return {
themes: [['docusaurus-theme-awesome', opts.theme]],
plugins: [
// Utilisation de trois plugins docs en même temps !
// Assigne un ID unique pour chacun sans demander à l'utilisateur de le faire
['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
],
};
}
Puis dans votre configuration de Docusaurus, vous pouvez configurer le preset :
export default {
presets: [
[
'./src/presets/docusaurus-preset-multi-docs.js',
{
theme: {hello: 'world'},
docs1: {path: '/docs'},
docs2: {path: '/community'},
docs3: {path: '/api'},
},
],
],
};
Cela équivaut à :
export default {
themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
plugins: [
['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
],
};
Ceci est particulièrement utile lorsque certains plugins et thèmes sont destinés à être utilisés ensemble. Vous pouvez même lier leurs options entre eux, par exemple en transmettant une option à plusieurs plugins.
Raccourcis de module
Docusaurus prend en charge les raccourcis pour les plugins, les thèmes et les presets. Lorsqu'il voit un nom de plugin/ thème/preset, il essaie de charger l'un des éléments suivants, dans cet ordre :
[name]
(commecontent-docs
)@docusaurus/[moduleType]-[name]
(comme@docusaurus/plugin-content-docs
)docusaurus-[moduleType]-[name]
(commedocusaurus-plugin-content-docs
)
où moduleType
est soit 'preset'
, 'theme'
ou 'plugin'
, selon le champ dans lequel le nom du module est déclaré. Le premier nom de module trouvé est chargé.
Si le nom est scopé (commençant par @
), le nom est d'abord divisé en scope et nom de paquet par le premier slash :
@scope
^----^
scope (aucun nom !)
@scope/awesome
^----^ ^-----^
scope nom
@scope/awesome/main
^----^ ^----------^
scope nom
S'il n'y a pas de nom (comme @jquery
), [scope]/docusaurus-[moduleType]
(par exemple @jquery/docusaurus-plugin
) est chargé. Sinon, les tentatives suivantes sont effectuées :
[scope]/[name]
(comme@jquery/content-docs
)[scope]/docusaurus-[moduleType]-[name]
(comme@jquery/docusaurus-plugin-content-docs
)
Voici quelques exemples, pour un plugin enregistré dans le champ plugins
. Notez que contrairement à ESLint ou Babel où une convention de nommage cohérente pour les plugins est imposée, Docusaurus permet une plus grande liberté de nommage, les résolutions ne sont donc pas certaines, mais suivent la priorité définie ci-dessus.
Déclaration | Peut être résolu comme suit |
---|---|
awesome | docusaurus-plugin-awesome |
sitemap | @docusaurus/plugin-sitemap |
@my-company | @my-company/docusaurus-plugin (la seule résolution possible !) |
@my-company/awesome | @my-company/docusaurus-plugin-awesome |
@my-company/awesome/web | @my-company/docusaurus-plugin-awesome/web |