8.1 KiB
| id | title |
|---|---|
| advanced-plugins | Plugins |
In this doc, we talk about the design intention of plugins and how you may write your own plugins.
Docusaurus Plugins are very similar to Gatsby Plugins and VuePress Plugins. The main difference here is that Docusaurus plugins don't allow using other plugins. Docusaurus provides presets to bundle plugins that are meant to work together.
Plugins design
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
In most cases, plugins are there to fetch data and create routes. A plugin could take in components as part of its options and to act as the wrapper for the page. A plugin can also provide React components to be used together with the non-UI functionality. You can also specify a resolution rule for the plugin to find its components to call, which you then supply with a theme.
Creating plugins
A plugin is a module which exports a function that takes two parameters and returns an object when executed.
Module definition
The exported modules for plugins are called with two parameters: context and options and returns a JavaScript object with defining the lifecycle APIs.
// Example contents of a Docusaurus plugin.
module.exports = function(context, options) {
// ...
return {
name: 'my-docusaurus-plugin',
async loadContent() { ... },
async contentLoaded({content, actions}) { ... },
...
};
};
context
context is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The context object contains the following fields:
interface LoadContext {
siteDir: string;
generatedFilesDir: string;
siteConfig: DocusaurusConfig;
outDir: string;
baseUrl: string;
}
options
options are the second optional parameter when the plugins are used. options is plugin-specific and are specified by the user when they use it in docusaurus.config.js or if preset contains the plugin. The preset will then be in-charge of passing the correct options into the plugin. It is up to individual plugins to define what options it takes.
Return value
The returned object value should implement the lifecycle APIs.
Official plugins
Find the list of official Docusaurus plugins here.
@docusaurus/plugin-content-blog
The default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations.
// docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* Path to data on filesystem
* relative to site dir
*/
path: 'blog',
/**
* URL route for the blog section of your site
* do not include trailing slash
*/
routeBasePath: 'blog',
include: ['*.md', '*.mdx'],
postsPerPage: 10,
/**
* Theme components used by the blog pages
*/
blogListComponent: '@theme/BlogListPage',
blogPostComponent: '@theme/BlogPostPage',
blogTagsListComponent: '@theme/BlogTagsListPage',
blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
rehypePlugins: [],
},
],
],
};
@docusaurus/plugin-content-docs
The default docs plugin for Docusaurus. The classic template ships with this plugin with default configurations.
// docusaurus.config.js
module.exports = {
plugins: [
[
'@docuaurus/plugin-content-docs',
{
/**
* Path to data on filesystem
* relative to site dir
*/
path: 'docs',
/**
* URL for editing docs, example: 'https://github.com/facebook/docusaurus/edit/master/website/docs/'
*/
editUrl: 'https://github.com/repo/project/website/docs/',
/**
* URL route for the blog section of your site
* do not include trailing slash
*/
routeBasePath: 'docs',
include: ['**/*.md', '**/*.mdx'], // Extensions to include.
/**
* Path to sidebar configuration for showing a list of markdown pages.
* Warning: will change
*/
sidebarPath: '',
/**
* Theme components used by the docs pages
*/
docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/DocItem',
/**
* Remark and Rehype plugins passed to MDX
*/
remarkPlugins: [],
rehypePlugins: [],
/**
* Whether to display the author who last updated the doc.
* /
showLastUpdateAuthor: false,
/**
* Whether to display the last date the doc was updated.
* /
showLastUpdateTime: false,
},
],
],
};
@docusaurus/plugin-content-pages
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations.
// docusaurus.config.js
module.exports = {
plugins: [
[
'@docuaurus/plugin-content-pages',
{
/**
* Path to data on filesystem
* relative to site dir
* components in this directory will be automatically converted to pages
*/
path: 'src/pages',
/**
* URL route for the blog section of your site
* do not include trailing slash
*/
routeBasePath: '',
include: ['**/*.{js,jsx}'],
},
],
],
};
@docusaurus/plugin-google-analytics
The default Google Analytics plugin.
Installation
$ yarn add @docusaurus/plugin-google-analytics
Configuration
// docusaurus.config.js
module.exports = {
plugins: ['@docusaurus/plugin-google-analytics'],
themeConfig: {
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
},
};
@docusaurus/plugin-google-gtag
The default Global Site Tag (gtag.js) plugin.
Installation
$ yarn add @docusaurus/plugin-google-gtag
Configuration
// docusaurus.config.js
module.exports = {
plugins: ['@docusaurus/plugin-google-gtag'],
themeConfig: {
gtag: {
trackingID: 'UA-141789564-1',
},
},
};
@docusaurus/plugin-sitemap
The classic template ships with this plugin.
// docusaurus.config.js
module.exports = {
plugins: [
'@docusaurus/plugin-sitemap',
{
cacheTime: 600 * 1000, // 600 sec - cache purge period
changefreq: 'weekly',
priority: 0.5,
},
],
};