Utilisation de Plugins
The Docusaurus core doesn't provide any feature of its own. All features are delegated to individual plugins: the docs feature provided by the docs plugin; the blog feature provided by the blog plugin; or individual pages provided by the pages plugin. S'il n'y a pas de plugins installés, le site ne contiendra pas de routes.
You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. Pour la plupart des utilisateurs, les plugins sont configurés via la configuration du preset.
We maintain a list of official plugins, but the community has also created some unofficial plugins. If you want to add any feature: autogenerating doc pages, executing custom scripts, integrating other services... be sure to check out the list: someone may have implemented it for you!
If you are feeling energetic, you can also read the plugin guide or plugin method references for how to make a plugin yourself.
Installing a 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
Then you add it in your site's docusaurus.config.js
's plugins
option:
module.exports = {
// ...
plugins: ['@docusaurus/plugin-content-pages'],
};
Docusaurus peut également charger des plugins depuis votre répertoire local, avec quelque chose comme ceci :
module.exports = {
// ...
plugins: ['./src/plugins/docusaurus-local-plugin'],
};
Les chemins doivent être absolus ou relatifs par rapport au fichier de configuration.
Configuring 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 ».
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-xxx',
{
/* options */
},
],
],
};
Exemple :
module.exports = {
plugins: [
// Basic usage.
'@docusaurus/plugin-debug',
// With options object (babel style)
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};
Multi-instance plugins and plugin IDs
Tous les plugins de contenu Docusaurus peuvent supporter plusieurs instances de plugins. For example, it may be useful to have multiple docs plugin instances or multiple blogs. It is required to assign a unique ID to each plugin instance, and by default, the plugin ID is default
.
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-1',
// autres options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'docs-2',
// autres options
},
],
],
};
At most one plugin instance can be the "default plugin instance", by omitting the id
attribute, or using id: 'default'
.
Using themes
Les thèmes sont chargés exactement de la même manière que les plugins. From the consumer perspective, the themes
and plugins
entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for a theme to override a plugin's default theme components.
The themes
and plugins
options lead to different shorthand resolutions, so if you want to take advantage of shorthands, be sure to use the right entry!
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};
Using presets
Les presets sont des paquets de plugins et de thèmes. For example, instead of letting you register and configure @docusaurus/plugin-content-docs
, @docusaurus/plugin-content-blog
, etc. one after the other in the config file, we have @docusaurus/preset-classic
preset allows you to configure them in one centralized place.
@docusaurus/preset-classic
The classic preset is shipped by default to new Docusaurus websites created with 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
(deprecated)@docusaurus/plugin-sitemap
Le preset classic transmettra chaque entrée d'option au plugin/thème respectif.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// Debug defaults to true in dev, false in prod
debug: undefined,
// Will be passed to @docusaurus/theme-classic.
theme: {
customCss: [require.resolve('./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-content-sitemap (false to disable)
sitemap: {},
// 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: {},
},
],
],
};
Installing 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
Then, add it in your site's docusaurus.config.js
's presets
option:
module.exports = {
// ...
presets: ['@docusaurus/preset-classic'],
};
Les chemins du preset peuvent être relatifs à celui du fichier de configuration :
module.exports = {
// ...
presets: ['./src/presets/docusaurus-local-preset'],
};
Creating presets
A preset is a function with the same shape as the plugin constructor. It should return an object of { plugins: PluginConfig[], themes: PluginConfig[] }
, in the same as how they are accepted in the site config. Par exemple, vous pouvez spécifier un prest qui inclut les thèmes et plugins suivants:
module.exports = function preset(context, opts = {}) {
return {
themes: [['docusaurus-theme-awesome', opts.theme]],
plugins: [
// Using three docs plugins at the same time!
// Assigning a unique ID for each without asking the user to do it
['@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 :
module.exports = {
presets: [
[
'./src/presets/docusaurus-preset-multi-docs.js',
{
theme: {hello: 'world'},
docs1: {path: '/docs'},
docs2: {path: '/community'},
docs3: {path: '/api'},
},
],
],
};
Cela équivaut à :
module.exports = {
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.
Module shorthands
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]
(likecontent-docs
)@docusaurus/[moduleType]-[name]
(like@docusaurus/plugin-content-docs
)docusaurus-[moduleType]-[name]
(likedocusaurus-plugin-content-docs
)
where moduleType
is one of 'preset'
, 'theme'
, 'plugin'
, depending on which field the module name is declared in. Le premier nom de module trouvé est chargé.
If the name is scoped (beginning with @
), the name is first split into scope and package name by the first slash:
@scope
^----^
scope (no name!)
@scope/awesome
^----^ ^-----^
scope name
@scope/awesome/main
^----^ ^----------^
scope name
If there is no name (like @jquery
), [scope]/docusaurus-[moduleType]
(i.e. @jquery/docusaurus-plugin
) is loaded. Sinon, les tentatives suivantes sont effectuées :
[scope]/[name]
(like@jquery/content-docs
)[scope]/docusaurus-[moduleType]-[name]
(like@jquery/docusaurus-plugin-content-docs
)
Below are some examples, for a plugin registered in the plugins
field. Note that unlike ESLint or Babel where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.
Déclaration | Peut être résolu comme suit |
---|---|
awesome | docusaurus-plugin-awesome |
sitemap | @docusaurus/plugin-sitemap |
@my-company | @my-company/docusaurus-plugin (the only possible resolution!) |
@my-company/awesome | @my-company/docusaurus-plugin-awesome |
@my-company/awesome/web | @my-company/docusaurus-plugin-awesome/web |