Skip to content

Commit 00a950c

Browse files
slorberslorber
committed
docs
1 parent ce634ff commit 00a950c

File tree

103 files changed

+21394
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

103 files changed

+21394
-0
lines changed

‎website/versioned_docs/version-3.7.0/advanced/architecture.mdx

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: How Docusaurus works to build your app
3+
---
4+
5+
# Architecture
6+
7+
```mdx-code-block
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
import Zoom from 'react-medium-image-zoom';
11+
```
12+
13+
<Zoom>
14+
15+
![Architecture overview](/img/architecture.png)
16+
17+
</Zoom>
18+
19+
This diagram shows how Docusaurus works to build your app. Plugins each collect their content and emit JSON data; themes provide layout components which receive the JSON data as route modules. The bundler bundles all the components and emits a server bundle and a client bundle.
20+
21+
Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments:
22+
23+
- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as ES modules that can be imported, or CommonJS that can be `require`'d.
24+
- The theme code is built with Webpack. They can be provided as ESM—following React conventions.
25+
26+
Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options).
27+
28+
During bundling, the config file itself is serialized and bundled, allowing the theme to access config options like `themeConfig` or `baseUrl` through [`useDocusaurusContext()`](../docusaurus-core.mdx#useDocusaurusContext). However, the `siteConfig` object only contains **serializable values** (values that are preserved after `JSON.stringify()`). Functions, regexes, etc. would be lost on the client side. The `themeConfig` is designed to be entirely serializable.

‎website/versioned_docs/version-3.7.0/advanced/client.mdx

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
description: How the Docusaurus client is structured
3+
---
4+
5+
# Client architecture
6+
7+
## Theme aliases {#theme-aliases}
8+
9+
A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias:
10+
11+
```js
12+
import Navbar from '@theme/Navbar';
13+
```
14+
15+
The alias `@theme` can refer to a few directories, in the following priority:
16+
17+
1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
18+
2. A Docusaurus theme package's `theme` directory.
19+
3. Fallback components provided by Docusaurus core (usually not needed).
20+
21+
This is called a _layered architecture_: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. Given the following structure:
22+
23+
```
24+
website
25+
├── node_modules
26+
│ └── @docusaurus/theme-classic
27+
│ └── theme
28+
│ └── Navbar.js
29+
└── src
30+
└── theme
31+
└── Navbar.js
32+
```
33+
34+
`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. If you are familiar with Objective C where a function's implementation can be swapped during runtime, it's the exact same concept here with changing the target `@theme/Navbar` is pointing to!
35+
36+
We already talked about how the "userland theme" in `src/theme` can re-use a theme component through the [`@theme-original`](../swizzling.mdx#wrapping) alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
37+
38+
Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
39+
40+
```js
41+
import InitialCodeBlock from '@theme-init/CodeBlock';
42+
import React from 'react';
43+
44+
export default function CodeBlock(props) {
45+
return props.live ? (
46+
<ReactLivePlayground {...props} />
47+
) : (
48+
<InitialCodeBlock {...props} />
49+
);
50+
}
51+
```
52+
53+
Check the code of `@docusaurus/theme-live-codeblock` for details.
54+
55+
:::warning
56+
57+
Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`.
58+
59+
:::
60+
61+
It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack".
62+
63+
```text
64+
+-------------------------------------------------+
65+
| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top
66+
+-------------------------------------------------+
67+
| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component
68+
+-------------------------------------------------+
69+
| `plugin-awesome-codeblock/theme/CodeBlock.js` |
70+
+-------------------------------------------------+
71+
| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom
72+
+-------------------------------------------------+
73+
```
74+
75+
The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
76+
77+
`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
78+
79+
`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
80+
81+
`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
82+
83+
## Client modules {#client-modules}
84+
85+
Client modules are part of your site's bundle, just like theme components. However, they are usually side-effect-ful. Client modules are anything that can be `import`ed by Webpack—CSS, JS, etc. JS scripts usually work on the global context, like registering event listeners, creating global variables...
86+
87+
These modules are imported globally before React even renders the initial UI.
88+
89+
```js title="@docusaurus/core/App.tsx"
90+
// How it works under the hood
91+
import '@generated/client-modules';
92+
```
93+
94+
Plugins and sites can both declare client modules, through [`getClientModules`](../api/plugin-methods/lifecycle-apis.mdx#getClientModules) and [`siteConfig.clientModules`](../api/docusaurus.config.js.mdx#clientModules), respectively.
95+
96+
Client modules are called during server-side rendering as well, so remember to check the [execution environment](./ssg.mdx#escape-hatches) before accessing client-side globals.
97+
98+
```js title="mySiteGlobalJs.js"
99+
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
100+
101+
if (ExecutionEnvironment.canUseDOM) {
102+
// As soon as the site loads in the browser, register a global event listener
103+
window.addEventListener('keydown', (e) => {
104+
if (e.code === 'Period') {
105+
location.assign(location.href.replace('.com', '.dev'));
106+
}
107+
});
108+
}
109+
```
110+
111+
CSS stylesheets imported as client modules are [global](../styling-layout.mdx#global-styles).
112+
113+
```css title="mySiteGlobalCss.css"
114+
/* This stylesheet is global. */
115+
.globalSelector {
116+
color: red;
117+
}
118+
```
119+
120+
### Client module lifecycles {#client-module-lifecycles}
121+
122+
Besides introducing side-effects, client modules can optionally export two lifecycle functions: `onRouteUpdate` and `onRouteDidUpdate`.
123+
124+
Because Docusaurus builds a single-page application, `script` tags will only be executed the first time the page loads, but will not re-execute on page transitions. These lifecycles are useful if you have some imperative JS logic that should execute every time a new page has loaded, e.g., to manipulate DOM elements, to send analytics data, etc.
125+
126+
For every route transition, there will be several important timings:
127+
128+
1. The user clicks a link, which causes the router to change its current location.
129+
2. Docusaurus preloads the next route's assets, while keeping displaying the current page's content.
130+
3. The next route's assets have loaded.
131+
4. The new location's route component gets rendered to DOM.
132+
133+
`onRouteUpdate` will be called at event (2), and `onRouteDidUpdate` will be called at (4). They both receive the current location and the previous location (which can be `null`, if this is the first screen).
134+
135+
`onRouteUpdate` can optionally return a "cleanup" callback, which will be called at (3). For example, if you want to display a progress bar, you can start a timeout in `onRouteUpdate`, and clear the timeout in the callback. (The classic theme already provides an `nprogress` integration this way.)
136+
137+
Note that the new page's DOM is only available during event (4). If you need to manipulate the new page's DOM, you'll likely want to use `onRouteDidUpdate`, which will be fired as soon as the DOM on the new page has mounted.
138+
139+
```js title="myClientModule.js"
140+
export function onRouteDidUpdate({location, previousLocation}) {
141+
// Don't execute if we are still on the same page; the lifecycle may be fired
142+
// because the hash changes (e.g. when navigating between headings)
143+
if (location.pathname !== previousLocation?.pathname) {
144+
const title = document.getElementsByTagName('h1')[0];
145+
if (title) {
146+
title.innerText += '❤️';
147+
}
148+
}
149+
}
150+
151+
export function onRouteUpdate({location, previousLocation}) {
152+
if (location.pathname !== previousLocation?.pathname) {
153+
const progressBarTimeout = window.setTimeout(() => {
154+
nprogress.start();
155+
}, delay);
156+
return () => window.clearTimeout(progressBarTimeout);
157+
}
158+
return undefined;
159+
}
160+
```
161+
162+
Or, if you are using TypeScript and you want to leverage contextual typing:
163+
164+
```ts title="myClientModule.ts"
165+
import type {ClientModule} from '@docusaurus/types';
166+
167+
const module: ClientModule = {
168+
onRouteUpdate({location, previousLocation}) {
169+
// ...
170+
},
171+
onRouteDidUpdate({location, previousLocation}) {
172+
// ...
173+
},
174+
};
175+
export default module;
176+
```
177+
178+
Both lifecycles will fire on first render, but they will not fire on server-side, so you can safely access browser globals in them.
179+
180+
:::tip Prefer using React
181+
182+
Client module lifecycles are purely imperative, and you can't use React hooks or access React contexts within them. If your operations are state-driven or involve complicated DOM manipulations, you should consider [swizzling components](../swizzling.mdx) instead.
183+
184+
:::

‎website/versioned_docs/version-3.7.0/advanced/index.mdx

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Advanced Tutorials
2+
3+
This section is not going to be very structured, but we will cover the following topics:
4+
5+
```mdx-code-block
6+
import DocCardList from '@theme/DocCardList';
7+
8+
<DocCardList />
9+
```
10+
11+
We will assume that you have finished the guides, and know the basics like how to configure plugins, how to write React components, etc. These sections will have plugin authors and code contributors in mind, so we may occasionally refer to [plugin APIs](../api/plugin-methods/README.mdx) or other architecture details. Don't panic if you don't understand everything😉

‎website/versioned_docs/version-3.7.0/advanced/plugins.mdx

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Plugins
2+
3+
Plugins are the building blocks of features in a Docusaurus site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets.
4+
5+
## Creating plugins {#creating-plugins}
6+
7+
A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.mdx).
8+
9+
### Function definition {#function-definition}
10+
11+
You can use a plugin as a function directly included in the Docusaurus config file:
12+
13+
```js title="docusaurus.config.js"
14+
export default {
15+
// ...
16+
plugins: [
17+
// highlight-start
18+
async function myPlugin(context, options) {
19+
// ...
20+
return {
21+
name: 'my-plugin',
22+
async loadContent() {
23+
// ...
24+
},
25+
async contentLoaded({content, actions}) {
26+
// ...
27+
},
28+
/* other lifecycle API */
29+
};
30+
},
31+
// highlight-end
32+
],
33+
};
34+
```
35+
36+
### Module definition {#module-definition}
37+
38+
You can use a plugin as a module path referencing a separate file or npm package:
39+
40+
```js title="docusaurus.config.js"
41+
export default {
42+
// ...
43+
plugins: [
44+
// without options:
45+
'./my-plugin',
46+
// or with options:
47+
['./my-plugin', options],
48+
],
49+
};
50+
```
51+
52+
Then in the folder `my-plugin`, you can create an `index.js` such as this:
53+
54+
```js title="my-plugin/index.js"
55+
export default async function myPlugin(context, options) {
56+
// ...
57+
return {
58+
name: 'my-plugin',
59+
async loadContent() {
60+
/* ... */
61+
},
62+
async contentLoaded({content, actions}) {
63+
/* ... */
64+
},
65+
/* other lifecycle API */
66+
};
67+
}
68+
```
69+
70+
---
71+
72+
You can view all plugins installed in your site using the [debug plugin's metadata panel](/__docusaurus/debug/metadata).
73+
74+
Plugins come as several types:
75+
76+
- `package`: an external package you installed
77+
- `project`: a plugin you created in your project, given to Docusaurus as a local file path
78+
- `local`: a plugin created using the function definition
79+
- `synthetic`: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. You won't see this in the metadata because it's an implementation detail.
80+
81+
You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`.
82+
83+
## Plugin design {#plugin-design}
84+
85+
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 is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.
86+
87+
### Theme design {#theme-design}
88+
89+
When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.mdx#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.mdx#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.mdx). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`...
90+
91+
**Themes provide the set of UI components to render 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, which makes swapping designs easy.
92+
93+
For example, a Docusaurus blog may consist of a blog plugin and a blog theme.
94+
95+
:::note
96+
97+
This is a contrived example: in practice, `@docusaurus/theme-classic` provides the theme for docs, blog, and layouts.
98+
99+
:::
100+
101+
```js title="docusaurus.config.js"
102+
export default {
103+
// highlight-next-line
104+
themes: ['theme-blog'],
105+
plugins: ['plugin-content-blog'],
106+
};
107+
```
108+
109+
And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme):
110+
111+
```js title="docusaurus.config.js"
112+
export default {
113+
// highlight-next-line
114+
themes: ['theme-blog-bootstrap'],
115+
plugins: ['plugin-content-blog'],
116+
};
117+
```
118+
119+
Now, although the theme receives the same data from the plugin, how the theme chooses to _render_ the data as UI can be drastically different.
120+
121+
While themes share the exact same lifecycle methods with plugins, themes' implementations can look very different from those of plugins based on themes' designed objectives.
122+
123+
Themes are designed to complete the build of your Docusaurus site and supply the components used by your site, plugins, and the themes themselves. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use [`loadContent`](../api/plugin-methods/lifecycle-apis.mdx#loadContent), since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an `src/theme` directory full of components, which are made known to the core through the [`getThemePath`](../api/plugin-methods/extend-infrastructure.mdx#getThemePath) lifecycle.
124+
125+
To summarize:
126+
127+
- Themes share the same lifecycle methods with Plugins
128+
- Themes are run after all existing Plugins
129+
- Themes add component aliases by providing `getThemePath`.

0 commit comments

Comments
 (0)