docs(v2): plugins (#1629)

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/)<!-- TODO: is this the correct link? -->. 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: explain lifecycle methods -->
 
-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
+<!--
+For example, the in docusaurus-plugin-content-docs:
 
-- https://v1.vuepress.vuejs.org/plugin/
+    In loadContent, it loads the doc Markdown files based on the specified directory in options (defaulting to docs).
-- https://www.gatsbyjs.org/docs/plugins/
+    In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
+ -->
+
+## How to create plugins
+
+<!-- TODO: explain creating plugins using an example -->
+
+## 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: [],
+      },
+    ],
+  ],
+};
+```
+
+<!--
+#### Options
+| Option | Default | Notes |
+| :-- | :-- | :-- |
+| `path` | `'blog'` | Path to data on filesystem, relative to site dir |
+| `routeBasePath` | `'blog'` | URL Route |
+| `include` | `['*.md', '*.mdx']` | Extensions to include |
+| `postsPerPage` | `10` | How many posts per page |
+| `blogListComponent` | `'@theme/BlogListPage'` | Theme component used for the blog listing page |
+| `blogPostComponent` | `'@theme/BlogPostPage'` | Theme component used for the blog post page |
+| `blogTagsListComponent` | `'@theme/BlogTagsListPage'` | Theme component used for the blog tags list page |
+| `blogTagsPostsComponent` | `'@theme/BlogTagsPostsPage'` | Theme component used for the blog tags post page |
+| `remarkPlugins` | `[]` | Plugins for remark |
+| `rehypePlugins` | `[]` | Plugins for rehype |
+commenting out because charts look less direct than code example
+-->
+
+### `@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`
+
+<!-- TODO -->
+
+### `@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,
+    },
+  ],
+};
+```

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.
+<!-- 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. -->
 
-#### 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/
+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.
-- https://www.gatsbyjs.org/docs/plugins/
+
+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',
+        },
+      },
+    ],
+  ],
+};
+```