docs(v2) themes

packages/docusaurus-theme-classic/README.md

@@ -0,0 +1,31 @@
+# Docusaurus Theme Classic
+
+The classic theme for Docusaurus.
+
+## Installation
+
+Add `docusaurus/theme-classic` to your package:
+
+```bash
+npm i @docusaurus/theme-classic
+# or
+yarn add @docusaurus/theme-classic
+```
+
+Modify your `docusaurus.config.js`:
+
+```diff
+module.exports = {
+  ...
++ themes: ['@docusaurus/theme-classic'],
+  ...
+}
+```
+
+## Swizzling components
+
+```shell
+$ npm swizzle @docusaurus/theme-classic [component name]
+```
+
+All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/src/theme)

website/docs/advanced-plugins.md

@@ -3,37 +3,35 @@ id: advanced-plugins
 title: Plugins
 ---
 
+In this doc, we talk about the design intention of plugins, the lifecycle methods, how you may write your own plugins, etc.
+
 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.
 
-In this doc, we talk about the design intention of plugins, the lifecycle methods, how you may write your own plugins, etc.
+Plugins are one of the best ways to add functionality to our Docusaurus. Plugins allow third-party developers to extend or modify the default functionality that Docusaurus provides.
 
 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.
 
 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.
 
-## Lifecycle methods
-
-<!-- TODO: explain lifecycle methods -->
+## How to create plugins
 
-- `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.
+_This section is a work in progress._
 
 <!--
-For example, the in docusaurus-plugin-content-docs:
 
-    In loadContent, it loads the doc Markdown files based on the specified directory in options (defaulting to docs).
-    In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
- -->
+outline:
+- jump start a plugin
+- refer to lifecycle APIs
+- describe mindset how plugins should work
 
-## How to create plugins
-
-_This section is a work in progress._
+Plugins are modules which export a function that takes in the context, options and returns a plain JavaScript object that has some properties defined.
 
-<!-- TODO: explain creating plugins using an example -->
+-->
 
 ## Official plugins
 
+List of [official plugins](https://github.com/facebook/docusaurus/tree/master/packages) created by Docusaurus.
+
 ### `@docusaurus/plugin-content-blog`
 
 The default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations.

website/docs/advanced-themes.md

@@ -3,15 +3,89 @@ id: advanced-themes
 title: Themes
 ---
 
-_This section is a work in progress._
+In this doc, we discuss how themes are designed and how you can write your own themes.
+
+## Theme design
+
+While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives.
+
+Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. So a typical theme implementation would look like a `src/index.js` file that hooks it up to the lifecycle methods. Most likely they would not use `loadContent`, which plugins would use. And it is typically accompanied by a `src/theme` directory full of components.
+
+To summarize:
+
+- Themes share the same lifecycle methods with Plugins
+- Themes are run after all existing Plugins
+- Themes exist to add component aliases by extending the webpack config
+
+## Writing customized Docusaurus themes
+
+A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus theme folder looks like this:
+
+```shell
+.
+├── package.json
+└── src
+    ├── index.js
+    └── theme
+        ├── MyThemeComponent
+        └── AnotherThemeComponent.js
+```
+
+There are two lifecycle methods that are essential to theme implementation:
+
+**`getThemePath`**
+
+Returns the path to the directory where the theme components can be found. When your users calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
+
+If you use the folder directory above, your `getThemePath` can be:
+
+```js
+// my-theme/src/index.js
+
+const path = require('path');
+module.exports = function(context, options) {
+  return {
+    name: 'name-of-my-theme',
+    getThemePath() {
+      return path.resolve(__dirname, './theme');
+    },
+  };
+};
+```
+
+**`getClientModules`**
+
+Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.
+
+As an example, to make your theme load a `customCss` object from `options` passed in by the user:
+
+```js
+// my-theme/src/index.js
+
+const path = require('path');
+module.exports = function(context, options) {
+  const {customCss} = options || {};
+  return {
+    name: 'name-of-my-theme',
+    getClientModules() {
+      return [customCss];
+    },
+  };
+};
+```
 
 <!--
 
 Advanced guide on:
 - customizing themes
-- implementing themes
+- creating your own themes
 - swizzling components
 
+Related pieces
+---
+- [Guides – Themes](using-themes.md)
+- [API - Themes](api-themes.md)
+
 References
 ---
 - [classic themes](packages/docusaurus-theme-classic/src/index.js)

website/docs/themes-api.md → website/docs/api-themes.md

@@ -1,5 +1,5 @@
 ---
-id: themes-api
+id: api-themes
 title: Themes
 ---
 
@@ -9,6 +9,11 @@ _This section is a work in progress. [Welcoming PRs](https://github.com/facebook
 
 API for themes
 
+Related pieces
+---
+- [Guides – Themes](using-themes.md)
+- [Advanced Guides - Themes](advanced-themes.md)
+
 References
 ---
 - [source code on loading themes](/packages/docusaurus/src/server/themes/index.ts)

website/docs/plugins-api.md → website/docs/lifecycle-apis.md

@@ -1,53 +1,24 @@
 ---
-id: plugins-api
-title: Plugins
+id: lifecycle-apis
+title: Lifecycle APIs
 ---
 
-Plugins are one of the best ways to add functionality to our Docusaurus. Plugins allow third-party developers to extend or modify the default functionality that Docusaurus provides.
+_This section is a work in progress._
 
-## Installing a plugin
+Lifecycle APIs are shared by Themes and Plugins.
 
-A plugin is an npm package, so you install them like other npm packages using npm.
+<!-- TODO: explain lifecycle methods -->
 
-```bash
-yarn add docusaurus-plugin-name
-```
-
-Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
-
-```jsx
-// docusaurus.config.js
-module.exports = {
-  plugins: [
-    '@docusaurus/plugin-content-pages',
-    [
-      // Plugin with options
-      '@docusaurus/plugin-content-blog',
-      {
-        include: ['*.md', '*.mdx'],
-        path: 'blog',
-      },
-    ],
-  ],
-};
-```
-
-Docusaurus can also load plugins from your local directory, you can do something like the following:
-
-```jsx
-// docusaurus.config.js
-const path = require('path');
-
-module.exports = {
-  plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
-};
-```
-
-## Basic Plugin Definition
+- `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.
 
-Plugins are modules which export a function that takes in the context, options and returns a plain JavaScript object that has some properties defined.
+<!--
+For example, the in docusaurus-plugin-content-docs:
 
-For examples, please refer to several [official plugins](https://github.com/facebook/docusaurus/tree/master/packages) created.
+    In loadContent, it loads the doc Markdown files based on the specified directory in options (defaulting to docs).
+    In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
+ -->
 
 ```jsx
 const DEFAULT_OPTIONS = {

website/docs/using-plugins.md

@@ -8,9 +8,37 @@ Plugins are the building blocks which add features to a Docusaurus 2 site. Each
 
 Docusaurus 2 provides a few essential plugins such as [Google Analytics](advanced-plugins.md#docusaurusplugin-google-analytics) and [Sitemap](advanced-plugins.md#docusaurusplugin-sitemap). You may also 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](advanced-plugins.md). For API reference, check out [API Reference: Plugins](plugins-api.md).
+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](advanced-plugins.md).
 
-## Using plugins
+## Installing a plugin
+
+A plugin is an npm package, so you install them like other npm packages using npm.
+
+```bash
+npm install --save docusaurus-plugin-name
+```
+
+Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
+
+```jsx
+// docusaurus.config.js
+module.exports = {
+  plugins: ['@docusaurus/plugin-content-pages'],
+};
+```
+
+Docusaurus can also load plugins from your local directory, you can do something like the following:
+
+```jsx
+// docusaurus.config.js
+const path = require('path');
+
+module.exports = {
+  plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
+};
+```
+
+## Configuring plugins
 
 To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`.
 
@@ -36,16 +64,7 @@ module.exports = {
 
 ## Passing options to Docusaurus plugins via preset
 
-Docusaurus' classic template is scaffolded with the classic preset, which includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](advanced-plugins.md).
-
-- `@docusaurus/plugin-content-blog`
-- `@docusaurus/plugin-content-docs`
-- `@docusaurus/plugin-content-pages`
-- `@docusaurus/plugin-google-analytics`
-- `@docusaurus/plugin-google-gtag`
-- `@docusaurus/plugin-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.
+If you initialized your site using the classic template, you do not have to specify plugin options individually in your `docusaurus.config.js`. To provide the neccesary fields to certain plugins, i.e. `trackingID` for `@docusaurus/plugin-google-analytics`, pass them in the preset field, like this:
 
 ```js
 // docusaurus.config.js
@@ -64,11 +83,23 @@ module.exports = {
         },
         // Will be passed to @docusaurus/plugin-google-analytics.
         googleAnalytics: {
-          trackingID: 'UA-000000-2',
+          trackingID: 'UA-1428571428-5',
         },
         ...
       },
     ],
   ],
 };
 ```
+
+## Official plugins by Docusaurus
+
+Docusaurus' classic template is scaffolded with the classic preset, which includes the following official plugins. You may read more about the configurations of these plugins in our [Advanced Guides: Plugins](advanced-plugins.md).
+
+- [@docusaurus/plugin-content-blog](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-blog)
+- [@docusaurus/plugin-content-docs](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-docs-legacy)
+- [@docusaurus/plugin-content-pages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-content-pages)
+- [@docusaurus/plugin-google-analytics](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-google-analytics)
+- [@docusaurus/plugin-google-gtag](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-google-gtag)
+- [@docusaurus/plugin-sitemap](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-sitemap)
+- [@docusaurus/plugin-ideal-image](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-plugin-ideal-image)