스위즐링
이번 섹션에서는 도큐사우루스에서 사용자 정의 레이아웃을 처리하는 방법을 소개합니다.
Déjà vu...?
This section is similar to Styling and Layout, but this time, we will customize React components themselves, rather than what they look like. 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.
스위즐링 프로세스
개요
Docusaurus provides a 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 [theme name] [component name] -- --eject
yarn swizzle [theme name] [component name] --eject
pnpm run swizzle [theme name] [component name] --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 [theme name] [component name] -- --wrap
yarn swizzle [theme name] [component name] --wrap
pnpm run swizzle [theme name] [component name] --wrap
예:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer -- --wrap
yarn swizzle @docusaurus/theme-classic Footer --wrap
pnpm run swizzle @docusaurus/theme-classic Footer --wrap
This will create a wrapper in your site's src/theme
directory. Docusaurus will now use the <FooterWrapper>
component instead of the original one. 이제 원본 컴포넌트를 감싼 위에 사용자 지정 항목을 추가할 수 있습니다.
import React from 'react';
import Footer from '@theme-original/Footer';
export default function FooterWrapper(props) {
return (
<>
<section>
<h2>Extra section</h2>
<p>This is an extra section that appears above the original footer</p>
</section>
<Footer {...props} />
</>
);
}
What is this @theme-original
thing?
Docusaurus uses theme aliases to resolve the theme components to use. The newly created wrapper takes the @theme/SomeComponent
alias. @theme-original/SomeComponent
permits to import original component that the wrapper shadows without creating an infinite import loop where the wrapper imports itself.
Wrapping a theme is a great way to add extra components around existing one without ejecting it. 예를 들어 각 블로그 게시물 아래에 사용자 지정 댓글 시스템을 손쉽게 추가할 수 있습니다.
import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import MyCustomCommentSystem from '@site/src/MyCustomCommentSystem';
export default function BlogPostItemWrapper(props) {
return (
<>
<BlogPostItem {...props} />
<MyCustomCommentSystem />
</>
);
}
스위즐하기 안전하다는 것은 무엇인가요?
권한이 크면 책임감도 커집니다.
Some theme components are internal implementation details of a theme. Docusaurus allows you to swizzle them, but it might be risky.
Why is it risky?
테마 작성자(저희도 마찬가지로)는 시간이 지나면서 테마를 업데이트할 수 있습니다. 컴포넌트 속성, 이름, 파일 시스템 위치, 타입 등이 바뀔 수 있습니다. For example, consider a component that receives two props name
and age
, but after a refactor, it now receives a person
prop with the above two properties. Your component, which still expects these two props, will render undefined
instead.
또한 내부 컴포넌트가 삭제될 수도 있습니다. If a component is called Sidebar
and it's later renamed to DocSidebar
, your swizzled component will be completely ignored.
Theme components marked as unsafe may change in a backward-incompatible way between theme minor versions. When upgrading a theme (or Docusaurus), your customizations might behave unexpectedly, and can even break your site.
For each theme component, the swizzle CLI will indicate 3 different levels of safety declared by theme authors:
- Safe: this component is safe to be swizzled, its public API is considered stable, and no breaking changes should happen within a theme major version
- Unsafe: this component is a theme implementation detail, not safe to be swizzled, and breaking changes might happen within a theme minor version
- Forbidden: the swizzle CLI will prevent you from swizzling this component, because it is not designed to be swizzled at all
일부 컴포넌트는 감싸기는 안전하지만 추출하기는 안전하지 않을 수 있습니다.
Don't be too afraid to swizzle unsafe components: just keep in mind that breaking changes might happen, and you might need to upgrade your customizations manually on minor version upgrades.
If you have a strong use-case for swizzling an unsafe component, please report it here and we will work together to find a solution to make it safe.
어떤 컴포넌트를 스위즐해야 하나요?
원하는 결과를 얻기 위해 정확하게 어떤 컴포넌트를 스위즐해야 하는지 항상 명확한 것은 아닙니다. @docusaurus/theme-classic
, which provides most of the theme components, has about 100 components!
To print an overview of all the @docusaurus/theme-classic
components:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic -- --list
yarn swizzle @docusaurus/theme-classic --list
pnpm run swizzle @docusaurus/theme-classic --list
다음 단계에 따라 스위즐하기 적절한 컴포넌트를 찾을 수 있습니다.
- Component description. Some components provide a short description, which is a good way to find the right one.
- Component name. Official theme components are semantically named, so you should be able to infer its function from the name. swizzle CLI를 사용하면 컴포넌트 이름 일부를 입력해 사용할 수 있는 선택 범위를 좁힐 수 있습니다. For example, if you run
yarn swizzle @docusaurus/theme-classic
, and enterDoc
, only the docs-related components will be listed. - Start with a higher-level component. Components form a tree with some components importing others. Every route will be associated with one top-level component that the route will render (most of them listed in Routing in content plugins). For example, all blog post pages have
@theme/BlogPostPage
as the topmost component. 컴포넌트를 스위즐링한 다음 컴포넌트 트리를 해당 컴포넌트까지 타고 내려가서 여러분이 목표로 하는 것을 렌더링합니다. 너무 많은 컴포넌트를 관리하지 않으려면 올바른 파일을 찾은 후 파일을 삭제해서 나머지를 언스위즐하는 것을 잊지 마세요. - Read the theme source code and use search wisely.
If you still have no idea which component to swizzle to achieve the desired effect, you can reach out for help in one of our support channels.
We also want to understand better your fanciest customization use-cases, so please report them.
스위즐이 꼭 필요한가요?
스위즐링은 궁극적으로 도큐사우루스 내부 API와 상호 작용하는 몇 가지 추가 리액트 코드를 유지하고 관리해야 함을 의미합니다. 사이트를 사용자 정의할 때는 다음과 같은 대안을 고려하세요.
- Use CSS. CSS rules and selectors can often help you achieve a decent degree of customization. Refer to styling and layout for more details.
- Use translations. It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is
en
, you can still runyarn write-translations -l en
and edit thecode.json
emitted. Refer to the i18n tutorial for more details.
Wrapping your site with <Root>
The <Root>
component is rendered at the very top of the React tree, above the theme <Layout>
, and never unmounts. It is the perfect place to add stateful logic that should not be re-initialized across navigations (user authentication status, shopping cart state...).
Swizzle it manually by creating a file at src/theme/Root.js
:
import React from 'react';
// Default implementation, that you can customize
export default function Root({children}) {
return <>{children}</>;
}
해당 컴포넌트를 사용해 리액트 컨텍스트 제공자를 렌더링합니다.