3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-21 04:57:05 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): add doc for wrapping theme components with @theme-original and @theme-init (#3502)

Browse source 
* add doc for wrapping theme components

* fix tests

* Minor improvements

Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
This commit is contained in:
Sébastien Lorber 2020-09-30 18:15:47 +02:00 • committed by GitHub
parent 9cbca49ecf
commit dc31dad1de
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 58 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

52
website/docs/using-themes.md
View file

@ -101,6 +101,58 @@ npm run swizzle @docusaurus/theme-classic
**Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component.
## Wrapping theme components
Sometimes, you just want to wrap an existing theme component with additional logic, and it can be a pain to have to maintain an almost duplicate copy of the original theme component.
In such case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it.
### For site owners
The `@theme-original` alias allows you to import the original theme component.
Here is an example to display some text just above the footer, with minimal code duplication.
```js title="src/theme/Footer.js"
// Note: importing from "@theme/Footer" would fail due to the file importing itself
import OriginalFooter from '@theme-original/Footer';
export default function Footer(props) {
return (
<>
<div>Before footer</div>
<OriginalFooter {...props} />
</>
);
}
```
### For plugin authors
One theme can wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
```js
import InitialCodeBlock from '@theme-init/CodeBlock';
export default function CodeBlock(props) {
return props.live ? (
<ReactLivePlayground {...props} />
) : (
<InitialCodeBlock {...props} />
);
}
```
Check the code of `docusaurus-theme-live-codeblock` for details.
:::caution
Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-codeblock`), you likely don't need `@theme-init`.
:::
## Official themes by Docusaurus
### `@docusaurus/theme-classic`