From 504fcb1b4a6fe4e3679412de9b9daec8430db0a0 Mon Sep 17 00:00:00 2001 From: Wei Gao Date: Wed, 3 Jul 2019 14:12:22 +0800 Subject: [PATCH] docs(v2): plugins (#1629) --- website/docs/plugins.md | 193 ++++++++++++++++++++++++++++++++-- website/docs/using-plugins.md | 60 ++++++++++- 2 files changed, 239 insertions(+), 14 deletions(-) diff --git a/website/docs/plugins.md b/website/docs/plugins.md index a8f5d1a570..7736586d11 100644 --- a/website/docs/plugins.md +++ b/website/docs/plugins.md @@ -3,21 +3,194 @@ id: plugins title: Plugins --- -TODO: Explain what plugins are. +A plugin is a package that exports a class which can be instantiated with configurable options (provided by the user) and its various lifecycle methods will be invoked by the Docusaurus runtime. -## What are Plugins for? +In this doc, we talk about the design intention of plugins, the lifecycle methods, how you may write your own plugins, etc. -TODO +Docusaurus Plugins are very similar to [Gatsby Plugins](https://www.gatsbyjs.org/plugins/) and [VuePress Plugins](https://v1.vuepress.vuejs.org/plugin/). The main difference here is that Docusaurus plugins don't allow using other plugins. Docusaurus provides [presets](./presets.md) for the use scenarios for plugins that are meant to work together. -## How to Create Plugins +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. -TODO +## Lifecycle methods -## Official Plugins + -TODO +- `loadContent` - Plugins should fetch from data sources (filesystem, remote API, etc) +- `contentLoaded` - Plugins should use the data loaded in loadContent and construct the pages/routes that consume the data +- `configureWebpack` - To extend the webpack config via webpack-merge. -#### References + + +## How to create plugins + + + +## Official plugins + +### `@docusaurus/plugin-content-blog` + +The default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations. + +```js +// 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. + +```js +// docusaurus.config.js +module.exports = { + plugins: [ + [ + '@docuaurus/plugin-content-docs', + { + /** + * Path to data on filesystem + * relative to site dir + */ + path: '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: [], + }, + ], + ], +}; +``` + +### `@docusaurus/plugin-content-pages` + +The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. + +```js +// 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-content-analytics` + +The classic template ships with this plugin for Google Analytics. To use this analytics, specify the plugin in the `plugins` field, and provide your Google Analytics configuration in [theme config](./using-themes.md). + +```js +// docusaurus.config.js +module.exports = { + plugins: ['@docusaurus/plugin-content-analytics'], +}; +``` + +### `@docusaurus/plugin-content-gtag` + + + +### `@docusaurus/plugin-content-sitemap` + +The classic template ships with this plugin. + +```js +// docusaurus.config.js +module.exports = { + plugins: [ + '@docusaurus/plugin-content-sitemap', + { + cacheTime: 600 * 1000, // 600 sec - cache purge period + changefreq: 'weekly', + priority: 0.5, + }, + ], +}; +``` diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index fe2f72271e..12a627e6e1 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -3,9 +3,61 @@ id: using-plugins title: Using Plugins --- -TODO: Give a high-level overview about plugins and what they can be used for. + -#### References +Plugins are the building blocks for Docusaurus 2 sites' features. Each plugin handles its own individual feature. Plugins may work together as [presets](./presets.md). -- https://v1.vuepress.vuejs.org/plugin/ -- https://www.gatsbyjs.org/docs/plugins/ +Docusaurus 2 provides a few essential plugins such as [sitemap](#docusaurus-plugin-content-sitemap), [analytics](#docusaurus-plugin-content-analytics). And you may write your own plugins for customized features. + +In this doc, we talk about how to use plugins with Docusaurus' official plugins. To learn about the design implementation and how to write your own plugins, check out [Advanced Guides: Plugins](./plugins.md). For API reference, check out [API Reference: Plugins]('./plugins-api.md). + +## Using plugins + +To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`. + +For some plugins, providing just the plugin name is sufficient. For plugins that require options, specify the plugin in a `['plugin-name', options]` array. + +```js +// docusaurus.config.js +module.exports = { + plugins: [ + '@docusaurus/plugin-google-analytics', + ['@docusaurus/plugin-sitemap', opts.sitemap], + ], +}; +``` + +## Passing options to Docusaurus plugins + +Docusaurus' classic template is scaffolded with the classic preset, which in turn includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](./plugins.md). + +- `@docusaurus/plugin-content-blog` +- `@docusaurus/plugin-content-docs` +- `@docusaurus/plugin-content-pages` +- `@docusaurus/plugin-content-analytics` +- `@docusaurus/plugin-content-gtag` +- `@docusaurus/plugin-content-sitemap` + +If you initialized your site using the classic template, you do not have to specify them individually in your `docusaurus.config.js`. To provide the neccesary fields to certain plugins, i.e. `trackingID` of `@docusaurus/plugin-content-analytics`, pass them in the preset field. + +```js +// docusaurus.config.js +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + sidebarPath: require.resolve('./sidebars.js'), + }, + theme: { + customCss: require.resolve('./src/css/custom.css'), + }, + googleAnalytics: { + trackingID: 'UA-000000-2', + }, + }, + ], + ], +}; +```