docs(v2): Docs refactoring and reorganization (#3831)

* stable refactor of plugins api documentation * plugins sidebar not collapsed by default as small? * theme docs reorg * Refactor migration guide doc * fix broken link
facebook · Nov 30, 2020 · 8f47bab · 8f47bab
1 parent f43781f
commit 8f47bab
Show file tree

Hide file tree

Showing 31 changed files with 1,529 additions and 1,418 deletions.
diff --git a/website/community/resources.md b/website/community/resources.md
@@ -18,16 +18,6 @@ A curated list of interesting Docusaurus community projects.
 
 See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase</a>.
 
-## Official plugins
-
-- [@docusaurus/plugin-content-blog](/docs/using-plugins#docusaurusplugin-content-blog)
-- [@docusaurus/plugin-content-docs](/docs/using-plugins#docusaurusplugin-content-docs)
-- [@docusaurus/plugin-content-pages](/docs/using-plugins#docusaurusplugin-content-pages)
-- [@docusaurus/plugin-google-analytics](/docs/using-plugins#docusaurusplugin-google-analytics)
-- [@docusaurus/plugin-google-gtag](/docs/using-plugins#docusaurusplugin-google-gtag)
-- [@docusaurus/plugin-sitemap](/docs/using-plugins#docusaurusplugin-sitemap)
-- [@docusaurus/plugin-ideal-image](/docs/using-plugins#docusaurusplugin-ideal-image)
-
 ## Community plugins
 
 - [docusaurus-plugin-lunr](https://github.com/daldridge/docusaurus-plugin-lunr) - Docusaurus v2 plugin to create a local search index for use with Lunr.js

diff --git a/website/docs/api/plugins/overview.md b/website/docs/api/plugins/overview.md
@@ -0,0 +1,28 @@
+---
+id: plugins-overview
+title: 'Docusaurus plugins'
+sidebar_label: Plugins overview
+slug: '/api/plugins'
+---
+
+We provide official Docusaurus plugins.
+
+## Content plugins
+
+These plugins are responsible to load your site's content, and create pages for your theme to render.
+
+- [@docusaurus/plugin-content-docs](./plugin-content-docs.md)
+- [@docusaurus/plugin-content-blog](./plugin-content-blog.md)
+- [@docusaurus/plugin-content-pages](./plugin-content-pages.md)
+
+## Behavior plugins
+
+These plugins will add a useful behavior to your Docusaurus site.
+
+- [@docusaurus/plugin-debug](./plugin-debug.md)
+- [@docusaurus/plugin-sitemap](./plugin-sitemap.md)
+- [@docusaurus/plugin-pwa](./plugin-pwa.md)
+- [@docusaurus/plugin-client-redirects](./plugin-client-redirects.md)
+- [@docusaurus/plugin-ideal-image](./plugin-ideal-image.md)
+- [@docusaurus/plugin-google-analytics](./plugin-google-analytics.md)
+- [@docusaurus/plugin-google-gtag](./plugin-google-gtag.md)
diff --git a/website/docs/api/plugins/plugin-client-redirects.md b/website/docs/api/plugins/plugin-client-redirects.md
@@ -0,0 +1,129 @@
+---
+id: plugin-client-redirects
+title: '📦 plugin-client-redirects'
+slug: '/api/plugins/@docusaurus/plugin-client-redirects'
+---
+
+Docusaurus Plugin to generate **client-side redirects**.
+
+This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript.
+
+:::note
+
+This plugin only create redirects for the production build.
+
+:::
+
+:::caution
+
+It is better to use server-side redirects whenever possible.
+
+Before using this plugin, you should look if your hosting provider doesn't offer this feature.
+
+:::
+
+## Installation
+
+```bash npm2yarn
+npm install --save @docusaurus/plugin-client-redirects
+```
+
+## Configuration
+
+Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        fromExtensions: ['html'],
+      },
+    ],
+  ],
+};
+```
+
+Second usecase: you have `/myDocusaurusPage.html`, and you want to redirect to this page from `/myDocusaurusPage`.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        toExtensions: ['html'],
+      },
+    ],
+  ],
+};
+```
+
+For custom redirect logic, provide your own `createRedirects` function.
+
+Let's imagine you change the url of an existing page, you might want to make sure the old url still works:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        redirects: [
+          {
+            to: '/docs/newDocPath', // string
+            from: ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016'], // string | string[]
+          },
+        ],
+      },
+    ],
+  ],
+};
+```
+
+It's possible to use a function to create the redirects for each existing path:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        createRedirects: function (existingPath) {
+          if (existingPath === '/docs/newDocPath') {
+            return ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016']; // string | string[]
+          }
+        },
+      },
+    ],
+  ],
+};
+```
+
+Finally, it's possible to use all options at the same time:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        fromExtensions: ['html', 'htm'],
+        toExtensions: ['exe', 'zip'],
+        redirects: [
+          {
+            to: '/docs/newDocPath',
+            from: '/docs/oldDocPath',
+          },
+        ],
+        createRedirects: function (existingPath) {
+          if (existingPath === '/docs/newDocPath2') {
+            return ['/docs/oldDocPath2'];
+          }
+        },
+      },
+    ],
+  ],
+};
+```
diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md
@@ -0,0 +1,107 @@
+---
+id: plugin-content-blog
+title: '📦 plugin-content-blog'
+slug: '/api/plugins/@docusaurus/plugin-content-blog'
+---
+
+Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus.
+
+## Installation
+
+```bash npm2yarn
+npm install --save @docusaurus/plugin-content-blog
+```
+
+:::tip
+
+If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency. You can also configure it through the [classic preset options](presets.md#docusauruspreset-classic) instead of doing it like below.
+
+:::
+
+## Configuration
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-blog',
+      {
+        /**
+         * Path to data on filesystem relative to site dir.
+         */
+        path: 'blog',
+        /**
+         * URL for editing a blog post.
+         * Example: 'https://github.com/facebook/docusaurus/edit/master/website/blog/'
+         */
+        editUrl:
+          'https://github.com/facebook/docusaurus/edit/master/website/blog/',
+        /**
+         * Blog page title for better SEO
+         */
+        blogTitle: 'Blog title',
+        /**
+         * Blog page meta description for better SEO
+         */
+        blogDescription: 'Blog',
+        /**
+         * Number of blog post elements to show in the blog sidebar
+         * 'ALL' to show all blog posts
+         * 0 to disable
+         */
+        blogSidebarCount: 5,
+        /**
+         * Title of the blog sidebar
+         */
+        blogSidebarTitle: 'All our posts',
+        /**
+         * URL route for the blog section of your site.
+         * *DO NOT* include a 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: [
+          /* require('remark-math') */
+        ],
+        rehypePlugins: [],
+        /**
+         * Custom Remark and Rehype plugins passed to MDX before
+         * the default Docusaurus Remark and Rehype plugins.
+         */
+        beforeDefaultRemarkPlugins: [],
+        beforeDefaultRehypePlugins: [],
+        /**
+         * Truncate marker, can be a regex or string.
+         */
+        truncateMarker: /<!--\s*(truncate)\s*-->/,
+        /**
+         * Show estimated reading time for the blog post.
+         */
+        showReadingTime: true,
+        /**
+         * Blog feed.
+         * If feedOptions is undefined, no rss feed will be generated.
+         */
+        feedOptions: {
+          type: '', // required. 'rss' | 'feed' | 'all'
+          title: '', // default to siteConfig.title
+          description: '', // default to  `${siteConfig.title} Blog`
+          copyright: '',
+          language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
+        },
+      },
+    ],
+  ],
+};
+```