From a234f3355093b795d533da0f2b93de87abee0ccb Mon Sep 17 00:00:00 2001 From: Wei Gao Date: Wed, 10 Jul 2019 00:20:19 +0800 Subject: [PATCH 01/13] More prep --- website/docs/advanced-themes.md | 7 ++++++- website/docs/themes-api.md | 5 +++++ website/docs/using-themes.md | 10 ++++++---- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/website/docs/advanced-themes.md b/website/docs/advanced-themes.md index be1a9ed7cdba..28fd1ef49383 100644 --- a/website/docs/advanced-themes.md +++ b/website/docs/advanced-themes.md @@ -9,9 +9,14 @@ _This section is a work in progress._ 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) diff --git a/website/docs/themes-api.md b/website/docs/themes-api.md index ce7f724a40a3..e683f9af882a 100644 --- a/website/docs/themes-api.md +++ b/website/docs/themes-api.md @@ -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) diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 24154fd55fd0..5b64fc1157e5 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -10,13 +10,15 @@ _This section is a work in progress. [Welcoming PRs](https://github.com/facebook Outline --- High-level overview about themes: -- how they are used -- how to shadow components and the power of it +- how to use a theme +- how to pass theme configurations +- how to swizzle components and the power of it Related pieces --- -- [Advanced Guide – Themes](advanced-themes.md) -- [API - Themes](themes-api.md) + +- [Advanced Guides – Themes](advanced-themes.md) +- [API - Themes](api-themes.md) References --- From 1a14380d77872668fedc2455bb4f3d1b46188f2d Mon Sep 17 00:00:00 2001 From: Wei Gao Date: Tue, 23 Jul 2019 08:38:51 +0800 Subject: [PATCH 02/13] rename xxx-api to api-xxx --- website/docs/{plugins-api.md => api-plugins.md} | 2 +- website/docs/{themes-api.md => api-themes.md} | 2 +- website/docs/using-plugins.md | 2 +- website/sidebars.js | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) rename website/docs/{plugins-api.md => api-plugins.md} (99%) rename website/docs/{themes-api.md => api-themes.md} (96%) diff --git a/website/docs/plugins-api.md b/website/docs/api-plugins.md similarity index 99% rename from website/docs/plugins-api.md rename to website/docs/api-plugins.md index 0fc9e1d147f9..582f7c48c6a9 100644 --- a/website/docs/plugins-api.md +++ b/website/docs/api-plugins.md @@ -1,5 +1,5 @@ --- -id: plugins-api +id: api-plugins title: Plugins --- diff --git a/website/docs/themes-api.md b/website/docs/api-themes.md similarity index 96% rename from website/docs/themes-api.md rename to website/docs/api-themes.md index e683f9af882a..3c2859efb1fc 100644 --- a/website/docs/themes-api.md +++ b/website/docs/api-themes.md @@ -1,5 +1,5 @@ --- -id: themes-api +id: api-themes title: Themes --- diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index d0d9a7d50c20..242f4a3a5761 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -8,7 +8,7 @@ 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). For API reference, check out [API Reference: Plugins](api-plugins.md). ## Using plugins diff --git a/website/sidebars.js b/website/sidebars.js index 0d1676d5fae2..c67f860b8e05 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -38,8 +38,8 @@ module.exports = { 'cli', 'docusaurus-core', 'docusaurus.config.js', - 'plugins-api', - 'themes-api', + 'api-plugins', + 'api-themes', ], }, }; From d486e06a685ea1d5ba4148ae35c559357d980b60 Mon Sep 17 00:00:00 2001 From: Wei Gao Date: Tue, 23 Jul 2019 09:03:20 +0800 Subject: [PATCH 03/13] move content around for plugins and themes --- website/docs/advanced-plugins.md | 28 +++++----- website/docs/advanced-themes.md | 2 +- .../{api-plugins.md => lifecycle-apis.md} | 55 ++++--------------- website/docs/using-plugins.md | 42 +++++++++++++- website/docs/using-themes.md | 2 +- website/sidebars.js | 3 +- 6 files changed, 68 insertions(+), 64 deletions(-) rename website/docs/{api-plugins.md => lifecycle-apis.md} (64%) diff --git a/website/docs/advanced-plugins.md b/website/docs/advanced-plugins.md index 7c5345e1eea8..de1c8be51511 100644 --- a/website/docs/advanced-plugins.md +++ b/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/). 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 - - +## 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._ +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. - +--> ## 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. diff --git a/website/docs/advanced-themes.md b/website/docs/advanced-themes.md index 28fd1ef49383..5d6016ceacff 100644 --- a/website/docs/advanced-themes.md +++ b/website/docs/advanced-themes.md @@ -3,7 +3,7 @@ id: advanced-themes title: Themes --- -_This section is a work in progress._ +Under the hood, Themes are plugins with exactly the same lifecycle methods, but most likely they would not use `loadContent`. They exist to add component aliases by extending the webpack config. And they are run after all existing plugins. -A plugin is an npm package, so you install them like other npm packages using npm. +- `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. -```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 - -Plugins are modules which export a function that takes in the context, options and returns a plain JavaScript object that has some properties defined. + ```jsx const DEFAULT_OPTIONS = { diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 242f4a3a5761..5f764d6ddc18 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -8,9 +8,47 @@ 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](api-plugins.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 +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')], +}; +``` + +## Configuring plugins To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`. diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md index 5b64fc1157e5..ffa1b5b60ccd 100644 --- a/website/docs/using-themes.md +++ b/website/docs/using-themes.md @@ -3,7 +3,7 @@ id: using-themes title: Using Themes --- -_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ +Themes provide the consistent components for your doc sites. + +## Using themes + +To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes: + +```js +// docusaurus.config.js +module.exports = { + themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'], +}; +``` + +## Swizzling theme components + +Themes are all about components. Docusaurus Themes' components are designed to be easily replaceable. We created a command for you to replace the components called `swizzle`. + +To swizzle a component for a theme, run the following command in your doc site: + +```shell +$ docusaurus swizzle [theme name] [component name] +``` + +As an example, to swizzle the `