mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 18:27:56 +02:00
docs(v2): update plugins, presets and themes docs (#1889)
* docs(v2): update plugins, presets and themes docs * ideal image plugin * proof reading * Merge master
This commit is contained in:
Endi
GitHub
parent
242c9e0c29
commit
2bbfbf88d6
12 changed files with 360 additions and 227 deletions
2
packages/docusaurus-types/src/index.d.ts
vendored
2
packages/docusaurus-types/src/index.d.ts
vendored
|
|
@ -94,7 +94,7 @@ export interface Plugin<T> {
|
|||
getThemePath?(): string;
|
||||
getPathsToWatch?(): string[];
|
||||
getClientModules?(): string[];
|
||||
extendCli?(cli: CommanderStatic): any;
|
||||
extendCli?(cli: CommanderStatic): void;
|
||||
}
|
||||
|
||||
export type PluginConfig = [string, Object] | [string] | string;
|
||||
|
|
|
|||
|
|
@ -1,23 +1,16 @@
|
|||
---
|
||||
id: advanced-plugins
|
||||
title: Plugins
|
||||
title: Writing Plugins
|
||||
---
|
||||
|
||||
<!-- TODO
|
||||
- move the list of plugins (maybe to links to each plugin's READMEs)
|
||||
- add guides on how to create plugins
|
||||
-->
|
||||
|
||||
In this doc, we talk about the design intention of plugins and how you may write your own plugins.
|
||||
|
||||
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](./advanced-presets.md) to bundle plugins that are meant to work together.
|
||||
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 plugins to include another plugin. Docusaurus provides [presets](presets.md) to bundle plugins that are meant to work together.
|
||||
|
||||
## Plugins design
|
||||
|
||||
Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
|
||||
|
||||
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. A plugin can also provide React components to be used together with the non-UI functionality. You can also specify a resolution rule for the plugin to find its components to call, which you then supply with a [theme](./advanced-themes.md).
|
||||
|
||||
## Creating plugins
|
||||
|
||||
A plugin is a module which exports a function that takes two parameters and returns an object when executed.
|
||||
|
|
@ -34,7 +27,7 @@ module.exports = function(context, options) {
|
|||
name: 'my-docusaurus-plugin',
|
||||
async loadContent() { ... },
|
||||
async contentLoaded({content, actions}) { ... },
|
||||
...
|
||||
/* other lifecycle api */
|
||||
};
|
||||
};
|
||||
```
|
||||
|
|
@ -55,7 +48,7 @@ interface LoadContext {
|
|||
|
||||
#### `options`
|
||||
|
||||
`options` are the [second optional parameter when the plugins are used](./using-plugins.md#configuring-plugins). `options` is plugin-specific and are specified by the user when they use it in `docusaurus.config.js` or if preset contains the plugin. The preset will then be in-charge of passing the correct options into the plugin. It is up to individual plugins to define what options it takes.
|
||||
`options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
|
||||
|
||||
#### Return value
|
||||
|
||||
|
|
@ -67,7 +60,7 @@ Find the list of official Docusaurus plugins [here](https://github.com/facebook/
|
|||
|
||||
### `@docusaurus/plugin-content-blog`
|
||||
|
||||
The default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations.
|
||||
Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. The classic template ships with this plugin with default configurations.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -106,26 +99,9 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
<!--
|
||||
#### 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.
|
||||
Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus. The classic template ships with this plugin with default configurations.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -180,7 +156,7 @@ module.exports = {
|
|||
|
||||
### `@docusaurus/plugin-content-pages`
|
||||
|
||||
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations.
|
||||
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](creating-pages.md) functionality.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -214,7 +190,7 @@ The default [Google Analytics](https://developers.google.com/analytics/devguides
|
|||
**Installation**
|
||||
|
||||
```shell
|
||||
$ yarn add @docusaurus/plugin-google-analytics
|
||||
$ npm install --save @docusaurus/plugin-google-analytics
|
||||
```
|
||||
|
||||
**Configuration**
|
||||
|
|
@ -238,7 +214,7 @@ The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/
|
|||
**Installation**
|
||||
|
||||
```shell
|
||||
$ yarn add @docusaurus/plugin-google-gtag
|
||||
$ npm install --save @docusaurus/plugin-google-gtag
|
||||
```
|
||||
|
||||
**Configuration**
|
||||
|
|
@ -257,7 +233,7 @@ module.exports = {
|
|||
|
||||
### `@docusaurus/plugin-sitemap`
|
||||
|
||||
The classic template ships with this plugin.
|
||||
The classic template ships with this plugin. This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -272,3 +248,48 @@ module.exports = {
|
|||
],
|
||||
};
|
||||
```
|
||||
|
||||
### `@docusaurus/plugin-ideal-image`
|
||||
|
||||
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder)
|
||||
|
||||
```sh
|
||||
npm install --save @docusaurus/plugin-ideal-image
|
||||
```
|
||||
|
||||
Modify your `docusaurus.config.js`
|
||||
|
||||
```diff
|
||||
module.exports = {
|
||||
...
|
||||
+ plugins: ['@docusaurus/plugin-ideal-image'],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
This plugin supports png, gif and jpg only
|
||||
|
||||
```jsx
|
||||
import Image from '@theme/IdealImage';
|
||||
import thumbnail from './path/to/img.png';
|
||||
|
||||
// your react code
|
||||
<Image img={thumbnail} />
|
||||
|
||||
// or
|
||||
<Image img={require('./path/to/img.png')} />
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. |
|
||||
| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). You may also declare a default `sizes` array in the loader options in your `webpack.config.js`. |
|
||||
| `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) |
|
||||
| `min` | `integer` | | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
|
||||
| `max` | `integer` | | See `min` above |
|
||||
| `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
|
||||
| `quality` | `integer` | `85` | JPEG compression quality |
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
---
|
||||
id: advanced-presets
|
||||
title: Presets
|
||||
---
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!--
|
||||
|
||||
Advanced guide on using and configuring presets
|
||||
|
||||
References
|
||||
---
|
||||
- [classic themes](/packages/docusaurus-preset-classic/src/index.js)
|
||||
- [babel docs on presets](https://babeljs.io/docs/en/presets)
|
||||
|
||||
-->
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
id: advanced-themes
|
||||
title: Themes
|
||||
title: Writing Themes
|
||||
---
|
||||
|
||||
In this doc, we discuss how themes are designed and how you can write your own themes.
|
||||
|
|
@ -32,47 +32,8 @@ A Docusaurus theme normally includes an `index.js` file where you hook up to the
|
|||
```
|
||||
|
||||
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];
|
||||
},
|
||||
};
|
||||
};
|
||||
```
|
||||
- [getThemePath](lifecycle-apis.md#getthemepath)
|
||||
- [getClientModules](lifecycle-apis.md#getclientmodules)
|
||||
|
||||
<!--
|
||||
|
||||
|
|
|
|||
|
|
@ -1,23 +0,0 @@
|
|||
---
|
||||
id: api-themes
|
||||
title: Themes
|
||||
---
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
|
||||
<!--
|
||||
|
||||
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)
|
||||
- [using plugins doc](using-plugins.md)
|
||||
- [vuepress docs on themes](https://v1.vuepress.vuejs.org/theme/)
|
||||
|
||||
-->
|
||||
|
|
@ -7,7 +7,7 @@ _This section is a work in progress._
|
|||
|
||||
Lifecycle APIs are shared by Themes and Plugins.
|
||||
|
||||
## `getPathsToWatch(): string[]`
|
||||
## 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.
|
||||
|
||||
|
|
@ -21,11 +21,11 @@ getPathsToWatch() {
|
|||
}
|
||||
```
|
||||
|
||||
## `async loadContent()`
|
||||
## async loadContent()
|
||||
|
||||
Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc).
|
||||
|
||||
## `async contentLoaded({content, actions})`
|
||||
## async contentLoaded({content, actions})
|
||||
|
||||
Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data.
|
||||
|
||||
|
|
@ -60,21 +60,15 @@ Example `addRoute` call:
|
|||
|
||||
```js
|
||||
addRoute({
|
||||
path: permalink,
|
||||
component: blogPostComponent,
|
||||
path: '/help',
|
||||
component: '@site/src/pages/help',
|
||||
exact: true,
|
||||
modules: {
|
||||
content: source,
|
||||
metadata: metadataPath,
|
||||
prevItem: prevItem && prevItem.metadataPath,
|
||||
nextItem: nextItem && nextItem.metadataPath,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
And `createData` takes a file name relative to to your plugin's directory, a string for the `JSON.stringify` result of your data, and will return a path to the module which you may then use as the path to items in your `RouteModule`. The modules will be loaded when the related pages are loaded following our optimizations according to the [PRPL pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/).
|
||||
|
||||
## `configureWebpack(config, isServer, utils)`
|
||||
## configureWebpack(config, isServer, utils)
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -99,34 +93,42 @@ You may use them to return your webpack configures conditionally.
|
|||
Example:
|
||||
|
||||
```js
|
||||
configureWebpack(config, isServer, {getBabelLoader, getCacheLoader}) {
|
||||
const {rehypePlugins, remarkPlugins, truncateMarker} = options;
|
||||
return {
|
||||
module: {
|
||||
rules: [
|
||||
{
|
||||
test: /(\.mdx?)$/,
|
||||
use: [
|
||||
getCacheLoader(isServer),
|
||||
getBabelLoader(isServer),
|
||||
{
|
||||
loader: '@docusaurus/mdx-loader',
|
||||
options: {
|
||||
remarkPlugins,
|
||||
rehypePlugins,
|
||||
configureWebpack(config, isServer) {
|
||||
if (!isServer) {
|
||||
// mutate the webpack config for client
|
||||
|
||||
}
|
||||
return config;
|
||||
},
|
||||
},
|
||||
{
|
||||
loader: path.resolve(__dirname, './markdownLoader.js'),
|
||||
options: {
|
||||
truncateMarker,
|
||||
},
|
||||
},
|
||||
].filter(Boolean),
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## postBuild(props)
|
||||
|
||||
Called when a (production) build finishes.
|
||||
|
||||
```ts
|
||||
interface LoadContext {
|
||||
siteDir: string;
|
||||
generatedFilesDir: string;
|
||||
siteConfig: DocusaurusConfig;
|
||||
outDir: string;
|
||||
baseUrl: string;
|
||||
}
|
||||
|
||||
interface Props extends LoadContext {
|
||||
routesPaths: string[];
|
||||
plugins: Plugin<any>[];
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
|
||||
// Print out to console all the rendered routes
|
||||
routesPaths.map(route => {
|
||||
console.log(route);
|
||||
})
|
||||
},
|
||||
```
|
||||
|
||||
|
|
@ -147,6 +149,47 @@ extendCli(cli) {
|
|||
},
|
||||
```
|
||||
|
||||
## 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];
|
||||
},
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
<!--
|
||||
For example, the in docusaurus-plugin-content-docs:
|
||||
|
||||
|
|
|
|||
|
|
@ -403,7 +403,7 @@ In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com
|
|||
|
||||
### Language-specific Code Tabs
|
||||
|
||||
Refer to the [multi-language support code blocks](markdown-features.md#multi-language-support-code-blocks) section.
|
||||
Refer to the [multi-language support code blocks](markdown-features.mdx#multi-language-support-code-blocks) section.
|
||||
|
||||
## Update `.gitignore`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
id: motivation
|
||||
title: Motivation
|
||||
description: Motivation of Docusaurus
|
||||
---
|
||||
|
||||
#### References
|
||||
|
||||
- https://redux.js.org/introduction/motivation
|
||||
121
website/docs/presets.md
Normal file
121
website/docs/presets.md
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
---
|
||||
id: presets
|
||||
title: Presets
|
||||
---
|
||||
|
||||
Presets are collections of plugins and themes.
|
||||
|
||||
## Using Presets
|
||||
|
||||
A preset is usually a npm package, so you install them like other npm packages using npm.
|
||||
|
||||
```bash
|
||||
npm install --save docusaurus-preset-name
|
||||
```
|
||||
|
||||
Then, add it in your site's `docusaurus.config.js`'s `presets` option:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
presets: ['@docusaurus/preset-xxxx'],
|
||||
};
|
||||
```
|
||||
|
||||
To load presets from your local directory, specify how to resolve them:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
presets: [path.resolve(__dirname, '/path/to/docusaurus-local-presets')],
|
||||
};
|
||||
```
|
||||
|
||||
## Presets -> Themes and Plugins
|
||||
|
||||
Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,
|
||||
|
||||
```js
|
||||
module.exports = function preset(context, opts = {}) {
|
||||
return {
|
||||
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
|
||||
plugins: ['@docusaurus/plugin-blog'],
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
then in your Docusaurus config, you may configure the preset instead:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
presets: ['@docusaurus/preset-a'],
|
||||
};
|
||||
```
|
||||
|
||||
This is equivalent of doing:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
|
||||
plugins: ['@docusaurus/plugin-blog'],
|
||||
};
|
||||
```
|
||||
|
||||
This is especially useful when some plugins and themes are intended to be used together.
|
||||
|
||||
## Official Presets
|
||||
|
||||
### `@docusaurus/preset-classic`
|
||||
|
||||
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
|
||||
|
||||
| Themes | Plugins |
|
||||
| -------------------------------- | ----------------------------------- |
|
||||
| @docusaurus/theme-classic | @docusaurus/plugin-content-docs |
|
||||
| @docusaurus/theme-search-algolia | @docusaurus/plugin-content-blog |
|
||||
| | @docusaurus/plugin-content-pages |
|
||||
| | @docusaurus/plugin-google-analytics |
|
||||
| | @docusaurus/plugin-google-gtag |
|
||||
| | @docusaurus/plugin-sitemap |
|
||||
|
||||
To specify plugin options individually, you can provide the neccesary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// Will be passed to @docusaurus/theme-classic.
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
// Will be passed to @docusaurus/plugin-content-docs
|
||||
docs: {},
|
||||
// Will be passed to @docusaurus/plugin-content-blog
|
||||
blog: {},
|
||||
// Will be passed to @docusaurus/plugin-content-pages
|
||||
pages: {},
|
||||
// Will be passed to @docusaurus/plugin-content-sitemap
|
||||
sitemap: {},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
<!--
|
||||
|
||||
Advanced guide on using and configuring presets
|
||||
|
||||
References
|
||||
---
|
||||
- [classic themes](/packages/docusaurus-preset-classic/src/index.js)
|
||||
- [babel docs on presets](https://babeljs.io/docs/en/presets)
|
||||
|
||||
-->
|
||||
|
|
@ -1,18 +1,16 @@
|
|||
---
|
||||
id: using-plugins
|
||||
title: Using Plugins
|
||||
description: 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.
|
||||
title: Plugins
|
||||
sidebar_label: Introduction
|
||||
---
|
||||
|
||||
Plugins are the building blocks which add features to a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work be bundled together and distributed via [presets](advanced-presets.md).
|
||||
|
||||
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.
|
||||
Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of bundle via [presets](presets.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).
|
||||
|
||||
## Installing a plugin
|
||||
|
||||
A plugin is an npm package, so you install them like other npm packages using npm.
|
||||
A plugin is usually a npm package, so you install them like other npm packages using npm.
|
||||
|
||||
```bash
|
||||
npm install --save docusaurus-plugin-name
|
||||
|
|
@ -40,9 +38,25 @@ module.exports = {
|
|||
|
||||
## Configuring plugins
|
||||
|
||||
To use a plugin, add the plugin to the `plugins` field of your `docusaurus.config.js`.
|
||||
For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.
|
||||
|
||||
For the most basic usage of plugins, you can providing just the plugin name or the absolute path to the plugin. For plugins that require options, specify the plugin as an array where the first value is the plugin name/path and second value is an options object, e.g. `['plugin-name', { path: 'foo/bar' }]` array.
|
||||
However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-xxx',
|
||||
{
|
||||
/* options */
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
|
|
@ -51,7 +65,7 @@ module.exports = {
|
|||
// Basic usage.
|
||||
'@docusaurus/plugin-google-analytics',
|
||||
|
||||
// With options object.
|
||||
// With options object (babel style)
|
||||
[
|
||||
'@docusaurus/plugin-sitemap',
|
||||
{
|
||||
|
|
@ -61,37 +75,3 @@ module.exports = {
|
|||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Passing options to Docusaurus plugins via preset
|
||||
|
||||
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. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
// Will be passed to @docusaurus/theme-classic.
|
||||
theme: {
|
||||
customCss: require.resolve('./src/css/custom.css'),
|
||||
},
|
||||
...
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## 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)
|
||||
|
|
|
|||
|
|
@ -1,11 +1,10 @@
|
|||
---
|
||||
id: using-themes
|
||||
title: Using Themes
|
||||
title: Themes
|
||||
sidebar_label: Introduction
|
||||
---
|
||||
|
||||
In Docusaurus 2, themes are there to finish the build step of your site by supplying the components used by your site, your plugins, and the themes themselves. Furthermore, you may easily swap out components from themes by _swizzling_ them with your own components.
|
||||
|
||||
In this document, we discuss the basic usages of themes. You will learn how to use a theme and how to swizzle a component. To grasp a deeper understanding of themes, and / or to learn how you may implement your own themes, check out our [advanced guide on themes](advanced-themes.md).
|
||||
Like plugins, themes are designed to add functionality to your Docusaurus site. As a good rule of thumb, themes are mostly focused on client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be easily replace-able with other themes.
|
||||
|
||||
## Using themes
|
||||
|
||||
|
|
@ -18,9 +17,64 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
## Theme components
|
||||
|
||||
Most of the time, theme is used to provide a set of React components, e.g. `Navbar`, `Layout`, `Footer`.
|
||||
|
||||
Users can use these components in their code by importing them using the `@theme` webpack alias:
|
||||
|
||||
```js
|
||||
import Navbar from '@theme/Navbar';
|
||||
```
|
||||
|
||||
The alias `@theme` can refer to a few directories, in the following priority:
|
||||
|
||||
1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
|
||||
1. A Docusaurus theme packages's `theme` directory.
|
||||
1. Fallback components provided by Docusaurus core (usually not needed).
|
||||
|
||||
Given the following structure
|
||||
|
||||
```
|
||||
website
|
||||
├── node_modules
|
||||
│ └── docusaurus-theme
|
||||
│ └── theme
|
||||
│ └── Navbar.js
|
||||
└── src
|
||||
└── theme
|
||||
└── Navbar.js
|
||||
```
|
||||
|
||||
`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. In iOS, method swizzling is the process of changing the implementation of an existing selector (method). In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.
|
||||
|
||||
**Themes are for providing UI components to present the content.** Most content plugins need to be paired with a theme in order to be actually useful. The UI is a separate layer from the data schema, so it makes it easy to swap out the themes for other designs (i.e., Bootstrap).
|
||||
|
||||
For example, a Docusaurus blog consists of a blog plugin and a blog theme.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
{
|
||||
theme: ['theme-blog'],
|
||||
plugins: ['plugin-content-blog'],
|
||||
}
|
||||
```
|
||||
|
||||
and if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap`:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
{
|
||||
theme: ['theme-blog-bootstrap'],
|
||||
plugins: ['plugin-content-blog'],
|
||||
}
|
||||
```
|
||||
|
||||
The content plugin remains the same and the only thing you need to change is the theme.
|
||||
|
||||
## 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`.
|
||||
Docusaurus Themes' components are designed to be easily replaceable. To make it easier for you, we created a command for you to replace theme components called `swizzle`.
|
||||
|
||||
To swizzle a component for a theme, run the following command in your doc site:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,11 +7,7 @@
|
|||
|
||||
module.exports = {
|
||||
docs: {
|
||||
Docusaurus: [
|
||||
'introduction',
|
||||
/*'motivation', */ 'design-principles',
|
||||
'contributing',
|
||||
],
|
||||
Docusaurus: ['introduction', 'design-principles', 'contributing'],
|
||||
'Getting Started': ['installation', 'configuration'],
|
||||
Guides: [
|
||||
'creating-pages',
|
||||
|
|
@ -26,15 +22,21 @@ module.exports = {
|
|||
'analytics',
|
||||
'seo',
|
||||
'search',
|
||||
'using-plugins',
|
||||
'using-themes',
|
||||
'deployment',
|
||||
'migrating-from-v1-to-v2',
|
||||
],
|
||||
'Advanced Guides': [
|
||||
'advanced-plugins',
|
||||
'advanced-themes',
|
||||
'advanced-presets',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Plugins',
|
||||
items: ['using-plugins', 'advanced-plugins'],
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Themes',
|
||||
items: ['using-themes', 'advanced-themes'],
|
||||
},
|
||||
'presets',
|
||||
],
|
||||
'API Reference': [
|
||||
'cli',
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue