Swizzle
在本节中,我们将介绍如何在 Docusaurus 中完成自定义布局。
听起来有点耳熟……?
This section is similar to Styling and Layout, but this time, we will write actual React code instead of playing with stylesheets. We will talk about a central concept in Docusaurus: swizzling, which allows deeper site customizations.
In practice, swizzling permits to swap a theme component with your own implementation, and it comes in 2 patterns:
- Ejecting: creates a copy of the original theme component, which you can fully customize
- Wrapping: creates a wrapper around the original theme component, which you can enhance
Why is it called swizzling?
The name comes from Objective-C and Swift-UI: method swizzling is the process of changing the implementation of an existing selector (method).
For Docusaurus, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.
You can think of it as Monkey Patching for React components, enabling you to override the default implementation. Gatsby has a similar concept called theme shadowing.
To gain a deeper understanding of this, you have to understand how theme components are resolved.
Swizzle 的过程
概览
Docusaurus provides an convenient interactive CLI to swizzle components. 你一般只需要记住以下指令:
- npm
- Yarn
- pnpm
npm run swizzle
yarn swizzle
pnpm run swizzle
It will generate a new component in your src/theme
directory, which should look like this example:
- Ejecting
- Wrapping
import React from 'react';
export default function SomeComponent(props) {
// You can fully customize this implementation
// including changing the JSX, CSS and React hooks
return (
<div className="some-class">
<h1>Some Component</h1>
<p>Some component implementation details</p>
</div>
);
}
import React from 'react';
import SomeComponent from '@theme-original/SomeComponent';
export default function SomeComponentWrapper(props) {
// You can enhance the original component,
// including adding extra props or JSX elements around it
return (
<>
<SomeComponent {...props} />
</>
);
}
要总览所有可用的主题和组件,请运行:
- npm
- Yarn
- pnpm
npm run swizzle -- --list
yarn swizzle --list
pnpm run swizzle --list
Use --help
to see all available CLI options, or refer to the reference swizzle CLI documentation.
After swizzling a component, restart your dev server in order for Docusaurus to know about the new component.
Be sure to understand which components are safe to swizzle. Some components are internal implementation details of a theme.
docusaurus swizzle
is only an automated way to help you swizzle the component. You can also create the src/theme/SomeComponent.js
file manually, and Docusaurus will resolve it. 这个命令背后没有什么内部的魔法!
Ejecting
Ejecting a theme component is the process of creating a copy of the original theme component, which you can fully customize and override.
To eject a theme component, use the swizzle CLI interactively, or with the --eject
option:
- npm
- Yarn
- pnpm
npm run swizzle [主题名] [组件名] -- --eject
yarn swizzle [主题名] [组件名] --eject
pnpm run swizzle [主题名] [组件名] --eject
举个例子:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle @docusaurus/theme-classic Footer --eject
This will copy the current <Footer />
component's implementation to your site's src/theme
directory. Docusaurus will now use this <Footer>
component copy instead of the original one. You are now free to completely re-implement the <Footer>
component.
import React from 'react';
export default function Footer(props) {
return (
<footer>
<h1>This is my custom site footer</h1>
<p>And it is very different from the original</p>
</footer>
);
}
To keep ejected components up-to-date after a Docusaurus upgrade, re-run the eject command and compare the changes with git diff
. 也建议你在文件顶部写一个简短的注释,说明你做了哪些修改。这样你可以在重弹出后更容易地重新做更改。
Wrapping
Wrapping a theme component is the process of creating a wrapper around the original theme component, which you can enhance.
To wrap a theme component, use the swizzle CLI interactively, or with the --wrap
option:
- npm
- Yarn
- pnpm
npm run swizzle [主题名] [组件名] -- --wrap
yarn swizzle [主题名] [组件名] --wrap
pnpm run swizzle [主题名] [组件名] --wrap