More writeup

website/docs/api/plugin-apis/_category_.yml

@@ -1,2 +1,2 @@
-label: Lifecycle APIs
+label: Plugin APIs
 position: 1

website/docs/api/plugin-apis/extend-infrastructure.md

@@ -4,6 +4,8 @@ sidebar_position: 2
 
 # Extending infrastructure
 
+Docusaurus has some infrastructure like hot reloading, CLI, and swizzling that can be extended by external plugins.
+
 ## `getPathsToWatch()` {#getPathsToWatch}
 
 Specifies the paths to watch for plugins and themes. The paths are watched by the dev server so that the plugin lifecycles are reloaded when contents in the watched paths change. Note that the plugins and themes modules are initially called with `context` and `options` from Node, which you may use to find the necessary directory information about the site.
@@ -92,7 +94,9 @@ module.exports = function (context, options) {
 
 ## `getSwizzleComponentList()` {#getSwizzleComponentList}
 
-Return a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned then all components are considered unstable, if `undefined` is returned then all component are considered stable.
+**This is a static method not attached to any plugin instance.**
+
+Returns a list of stable component that are considered as safe for swizzling. These components will be listed in swizzle component without `--danger`. All the components are considers unstable by default. If an empty array is returned then all components are considered unstable, if `undefined` is returned then all component are considered stable.
 
 ```js {0-12} title="my-theme/src/index.js"
 const swizzleAllowedComponents = [

website/docs/api/plugin-apis/i18n-lifecycles.md

@@ -2,7 +2,9 @@
 sidebar_position: 3
 ---
 
-# i18n lifecycles
+# I18n lifecycles
+
+Plugins use these lifecycles to load i18n-related data.
 
 ## `getTranslationFiles({content})` {#getTranslationFiles}
 
@@ -11,9 +13,9 @@ Plugins declare the JSON translation files they want to use.
 Returns translation files `{path: string, content: ChromeI18nJSON}`:
 
 - Path: relative to the plugin localized folder `i18n/<locale>/pluginName`. Extension `.json` is not necessary.
-- Content: using the Chrome i18n JSON format
+- Content: using the Chrome i18n JSON format.
 
-These files will be written by the [`write-translations` CLI](./cli.md#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translate-content) and [`translateThemeConfig()`](#translate-theme-config)
+These files will be written by the [`write-translations` CLI](../../cli.md#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translateContent) and [`translateThemeConfig()`](#translateThemeConfig)
 
 Example:
 
@@ -41,7 +43,7 @@ module.exports = function (context, options) {
 };
 ```
 
-## `translateContent({content,translationFiles})` {#translate-content}
+## `translateContent({content,translationFiles})` {#translateContent}
 
 Translate the plugin content, using the localized translation files.
 
@@ -101,7 +103,7 @@ module.exports = function (context, options) {
 
 Themes using the `<Translate>` API can provide default code translation messages.
 
-It should return messages in `Record<string,string`>, where keys are translation ids and values are messages (without the description) localized using the site current locale.
+It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site current locale.
 
 Example:
 

website/docs/api/plugin-apis/introduction.md

@@ -16,7 +16,7 @@ Plugin APIs are shared by Themes and Plugins—themes are loaded just like plugi
 
 Every plugin is imported as a module. The module is expected to have the following components:
 
-- A **default export**: the constructor for the plugin.
+- A **default export**: the constructor function for the plugin.
 - **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized.
 
 ## Example {#example}

website/docs/api/plugin-apis/lifecycle-apis.md

@@ -5,9 +5,11 @@ toc_max_heading_level: 4
 
 # Lifecycle APIs
 
+During build, plugins are loaded in parallel to fetch their own contents and render them to pages. Plugins may also configure webpack or post-process the generated files.
+
 ## `async loadContent()` {#loadContent}
 
-Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.
+Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc.) or do some server processing. The return value is the content it needs.
 
 For example, this plugin below return a random integer between 1 to 10 as content;
 
@@ -29,7 +31,7 @@ Plugins should use the data loaded in `loadContent` and construct the pages/rout
 
 ### `content` {#content}
 
-`contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
+`contentLoaded` will be called _after_ `loadContent` is done. The return value of `loadContent()` will be passed to `contentLoaded` as `content`.
 
 ### `actions` {#actions}
 
@@ -39,7 +41,7 @@ Plugins should use the data loaded in `loadContent` and construct the pages/rout
 
 Create a route to add to the website.
 
-```typescript
+```ts
 interface RouteConfig {
   path: string;
   component: string;
@@ -62,7 +64,7 @@ type Module =
 
 #### `createData(name: string, data: any): Promise<string>`
 
-A function to help you create static data (generally json or string), that you can provide to your routes as props.
+A declarative callback to create static data (generally json or string) which can later be provided to your routes as props. Takes the file name and data to be stored, and returns the actual data file's path.
 
 For example, this plugin below create a `/friends` page which display `Your friends are: Yangshun, Sebastien`:
 
@@ -104,17 +106,13 @@ export default function friendsPlugin(context, options) {
 
 #### `setGlobalData(data: any): void`
 
-This function permits to create some global plugin data, that can be read from any page, including the pages created by other plugins, and your theme layout.
+This function permits to create some global plugin data that can be read from any page, including the pages created by other plugins, and your theme layout.
 
-This data become accessible to your client-side/theme code, through the [`useGlobalData`](./docusaurus-core.md#useglobaldata) and [`usePluginData`](./docusaurus-core.md#useplugindatapluginname-string-pluginid-string).
-
-One this data is created, you can access it with the global data hooks APIs.
+This data becomes accessible to your client-side/theme code through the [`useGlobalData`](../../docusaurus-core.md#useGlobalData) and [`usePluginData`](../../docusaurus-core.md#usePluginData) hooks.
 
 :::caution
 
-Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small.
-
-Prefer `createData` and page-specific data whenever possible.
+Global data is... global: its size affects the loading time of all pages of your site, so try to keep it small. Prefer `createData` and page-specific data whenever possible.
 
 :::
 
@@ -152,7 +150,7 @@ export default function friendsPlugin(context, options) {
 
 ## `configureWebpack(config, isServer, utils, content)` {#configureWebpack}
 
-Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument.
+Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the second argument.
 
 :::caution
 
@@ -164,7 +162,7 @@ The API of `configureWebpack` will be modified in the future to accept an object
 
 `configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with.
 
-### `isServer` {#isserver}
+### `isServer` {#isServer}
 
 `configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`.
 

website/docs/api/plugin-apis/static-methods.md

@@ -4,7 +4,7 @@ sidebar_position: 4
 
 # Static methods
 
-Static methods are not part of the plugin instance—they are attached to the constructor function. These methods are used to validate and normalize the plugin options and theme config, which are then used to initialize the plugin as constructor parameters.
+Static methods are not part of the plugin instance—they are attached to the constructor function. These methods are used to validate and normalize the plugin options and theme config, which are then used as constructor parameters to initialize the plugin instance.
 
 ## `validateOptions({options, validate})` {#validateOptions}
 
@@ -64,7 +64,7 @@ export function validateOptions({options, validate}) {
 
 Return validated and normalized configuration for the theme.
 
-### `themeConfig` {#themeconfig}
+### `themeConfig` {#themeConfig}
 
 `validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
 
@@ -83,17 +83,19 @@ To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-vali
 If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options.
 
 ```js {8-11} title="my-theme/src/index.js"
-module.exports = function (context, options) {
+function myPlugin(context, options) {
   return {
     name: 'docusaurus-plugin',
     // rest of methods
   };
-};
+}
 
-module.exports.validateThemeConfig = ({themeConfig, validate}) => {
+myPlugin.validateThemeConfig = ({themeConfig, validate}) => {
   const validatedThemeConfig = validate(myValidationSchema, options);
   return validatedThemeConfig;
 };
+
+module.exports = validateThemeConfig;
 ```
 
 You can also use ES modules style exports.

website/docs/docusaurus-core.md

@@ -314,7 +314,7 @@ You can even omit a children prop and specify a translation string in your `code
 
 ## Hooks {#hooks}
 
-### `useDocusaurusContext` {#usedocusauruscontext}
+### `useDocusaurusContext` {#useDocusaurusContext}
 
 React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata.
 
@@ -398,7 +398,7 @@ const MyComponent = () => {
 };
 ```
 
-### `useBaseUrl` {#usebaseurl}
+### `useBaseUrl` {#useBaseUrl}
 
 React hook to prepend your site `baseUrl` to a string.
 
@@ -448,7 +448,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
 
 :::
 
-### `useBaseUrlUtils` {#usebaseurlutils}
+### `useBaseUrlUtils` {#useBaseUrlUtils}
 
 Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
 
@@ -468,7 +468,7 @@ const Component = () => {
 };
 ```
 
-### `useGlobalData` {#useglobaldata}
+### `useGlobalData` {#useGlobalData}
 
 React hook to access Docusaurus global data created by all the plugins.
 
@@ -509,7 +509,7 @@ Inspect your site's global data at `./docusaurus/globalData.json`
 
 :::
 
-### `usePluginData` {#useplugindata}
+### `usePluginData` {#usePluginData}
 
 Access global data created by a specific plugin instance.
 
@@ -533,7 +533,7 @@ const MyComponent = () => {
 };
 ```
 
-### `useAllPluginInstancesData` {#useallplugininstancesdata}
+### `useAllPluginInstancesData` {#useAllPluginInstancesData}
 
 Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.