mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-01 02:12:36 +02:00
docs(v2) themes (#1645)
* More prep * rename xxx-api to api-xxx * move content around for plugins and themes * wip docs: using themes * docs(v2): tweak using plugins * docs(v2): list official themes in docs * docs(v2): advanced themes * wip notes for lifecycle apis * resolve PR review discussions * lower case "theme" * better intro for using themes * add a simple README to @docusaurus/theme-classic * remove list of components from theme classic README and replace with link to directory
This commit is contained in:
Wei Gao
Endi
parent
59b0f9cbac
commit
f4f458460c
8 changed files with 232 additions and 82 deletions
31
packages/docusaurus-theme-classic/README.md
Normal file
31
packages/docusaurus-theme-classic/README.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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 -->
|
||||
|
||||
- `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.
|
||||
|
||||
<!--
|
||||
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.
|
||||
-->
|
||||
|
||||
## How to create plugins
|
||||
|
||||
_This section is a work in progress._
|
||||
|
||||
<!-- TODO: explain creating plugins using an example -->
|
||||
<!--
|
||||
|
||||
outline:
|
||||
- jump start a plugin
|
||||
- refer to lifecycle APIs
|
||||
- describe mindset how plugins should work
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
```
|
||||
- `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.
|
||||
|
||||
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
|
||||
<!--
|
||||
For example, the in docusaurus-plugin-content-docs:
|
||||
|
||||
```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.
|
||||
|
||||
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 = {
|
||||
|
|
@ -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,7 +83,7 @@ module.exports = {
|
|||
},
|
||||
// Will be passed to @docusaurus/plugin-google-analytics.
|
||||
googleAnalytics: {
|
||||
trackingID: 'UA-000000-2',
|
||||
trackingID: 'UA-1428571428-5',
|
||||
},
|
||||
...
|
||||
},
|
||||
|
|
@ -72,3 +91,15 @@ module.exports = {
|
|||
],
|
||||
};
|
||||
```
|
||||
|
||||
## 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)
|
||||
|
|
|
|||
|
|
@ -3,20 +3,61 @@ id: using-themes
|
|||
title: Using Themes
|
||||
---
|
||||
|
||||
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
|
||||
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).
|
||||
|
||||
## 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 `<Footer />` component in `@docusaurus/theme-classic` for your site, run:
|
||||
|
||||
```shell
|
||||
$ npm swizzle @docusaurus/theme-classic Footer
|
||||
```
|
||||
|
||||
This will copy the current `<Footer />` component used by the theme to a `theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use swizzled component in place of the original one from the theme.
|
||||
|
||||
**Note**: You need to restart your dev server for Docusaurus to pick up the new component.
|
||||
|
||||
## Official themes by Docusaurus
|
||||
|
||||
- [@docusaurus/theme-classic](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic)
|
||||
- [@docusaurus/theme-search-algolia](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-search-algolia)
|
||||
- [@docusaurus/theme-live-codeblock](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-live-codeblock)
|
||||
|
||||
<!--
|
||||
|
||||
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)
|
||||
- [Lifecycle APIs](lifecycle-apis.md)
|
||||
|
||||
References
|
||||
---
|
||||
|
|
|
|||
|
|
@ -39,8 +39,7 @@ module.exports = {
|
|||
'cli',
|
||||
'docusaurus-core',
|
||||
'docusaurus.config.js',
|
||||
'plugins-api',
|
||||
'themes-api',
|
||||
'lifecycle-apis',
|
||||
],
|
||||
},
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue