메인 컨텐츠로 이동
Version: 2.0.0-beta.5 🚧

테마

플러그인처럼 테마는 여러분의 도큐사우루스 사이트에 기능을 추가하도록 설계됐습니다. 일반적으로 테마는 사용자 중심이고 플러그인은 서버 측 기능에 초점을 맞추고 있습니다. 테마는 다른 테마로 교체될 수 있도록 설계합니다.

사용할 수 있는 테마#

공식적으로 지원하는 테마 목록은 링크를 참고하세요.

테마 사용하기#

특정 테마를 사용하려면 docusaurus.config.js 파일 내에서 테마를 설정해주어야 합니다. 아래와 같이 여러 개의 테마를 사용할 수도 있습니다.

docusaurus.config.js
module.exports = {  // ...  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],};

테마 컴포넌트#

대부분 테마는 리액트 컴포넌트 형식을 사용합니다. Navbar, Layout, Footer 구조를 가지고 있습니다.

사용자는 @theme이라는 웹팩 별칭을 사용해 컴포넌트를 가져와 코드 내에서 사용할 수 있습니다.

import Navbar from '@theme/Navbar';

@theme 별칭은 아래와 같은 우선순위에 따라 몇 개의 디렉터리를 참조할 수 있습니다.

  1. 사용자의 website/src/theme 디렉터리가 가장 높은 우선순위를 가집니다.
  2. 도큐사우루스 테마 패키지의 theme 디렉터리
  3. 도큐사우루스 코어에서 제공하는 대체 컴포넌트(거의 사용할 일은 없습니다)

디렉터리 구조가 아래와 같은 경우

website├── node_modules│   └── docusaurus-theme│       └── theme│           └── Navbar.js└── src    └── theme        └── Navbar.js

@theme/Navbar 가져오기를 하게 되면 website/src/theme/Navbar.js 파일이 언제나 우선순위를 가집니다. 이런 동작을 컴포넌트 바꾸기(swizzling)이라고 합니다. iOS에서 swizzling 메소드는 기존 selector(메소드)의 구현 기능을 대체하는 과정을 의미합니다. 웹 사이트의 관점에서 컴포넌트 swizzling은 테마에서 기본 컴포넌트보다 우선하는 대체 컴포넌트를 제공하는 것을 의미합니다.

테마는 컨텐츠를 화면에 표시하기 위해 제공되는 UI 컴포넌트입니다. 대부분의 컨텐츠 플러그인을 실제 사용하기 위해서는 테마가 같이 제공되어야 합니다. UI는 데이터 스키마와 별도의 계층입니다. 때문에 다른 디자인(부트스트랩 테마 같은)의 테마로 쉽게 바꾸어줄 수 있습니다.

예를 들어 도큐사우루스 블로그는 블로그 플러그인과 블로그 테마로 구성이 되어 있습니다.

docusaurus.config.js
{  theme: ['theme-blog'],  plugins: ['plugin-content-blog'],}

부트스트랩 테마를 사용하고 싶다면 theme-blog-bootstrap(실제 있는 테마는 아닙니다)로 설정값을 변경하기만 하면 됩니다.

docusaurus.config.js
{  theme: ['theme-blog-bootstrap'],  plugins: ['plugin-content-blog'],}

사이트를 <Root>로 감싸기#

<Root> 테마 컴포넌트는 도큐사우루스 사이트에서 가장 먼저 처리되는 항목입니다.

src/theme/Root.js 파일 내에 설정해주면 여러분의 사이트를 추가적인 로직으로 감쌀 수 있습니다.

website/src/theme/Root.js
import React from 'react';
// 수정할 수 있는 기본 구현 예시입니다.function Root({children}) {  return <>{children}</>;}
export default Root;

이 컴포넌트는 라우터나 테마 <Layout>보다 상위에 적용되며 제외시킬 수 없습니다.

tip

이 컴포넌트를 사용해 리액트 컨텍스트 공급자나 전역으로 처리할 로직을 적용할 수 있습니다.

테마 컴포넌트 바꾸기#

caution

도큐사우루스 2 베타 기간 동안에 컴포넌트 바꾸기 기능을 사용하는 건 권장하지 않습니다. 테마 컴포넌트 API는 기능 향상을 위해 변경될 수 있습니다. 가능한 현재 기본 상태를 유지해주세요.

도큐사우루스의 테마 컴포넌트는 대체할 수 있도록 설계했습니다. 이런 바꾸기 작업을 쉽게 할 수 있도록 컴포넌트를 바꾸는 명령인 swizzle을 만들었습니다.

테마 컴포넌트를 바꾸기 위해서는 여러분의 문서 사이트에서 아래 명령을 실행합니다.

npm run swizzle <theme name> [component name]

여러분의 사이트의 @docusaurus/theme-classic에서 <Footer /> 컴포넌트를 바꾸고 싶다면 아래와 같이 명령을 실행합니다.

npm run swizzle @docusaurus/theme-classic Footer

이렇게 하면 <Footer /> 컴포넌트가 테마에서 사용하는 src/theme/Footer 디렉터리 아래에 복사됩니다. 이렇게 하면 도큐사우루스에서는 바뀐 컴포넌트를 찾게 됩니다. 그리고 도큐사우루스는 원래 테마 대신 바뀐 컴포넌트를 사용합니다.

모든 컴포넌트를 바꾸는 것은 권장하지 않지만 혹 필요한 경우 아래와 같이 실행합니다.

npm run swizzle @docusaurus/theme-classic

참고: 도큐사우루스에서 새로운 컴포넌트를 처리하게 하려면 여러분의 웹팩 개발 서버를 다시 시작해주어야 합니다.

테마 컴포넌트 감싸기#

기존의 테마 컴포넌트에 추가적인 로직만 감싸는 것이 필요한 경우가 있습니다. 이렇게 하려면 원래 테마 컴포넌트와 거의 같은 복사본을 별도 관리해야 하는 곤란함이 있습니다.

이런 경우 필요한 컴포넌트를 바꾸어주어야 하지만 원래의 테마 컴포넌트를 수정한 버전에서 가져와 감싸는 방식을 사용할 수 있습니다.

사이트 관리자#

원래 테마 컴포넌트를 가져오기 위해 @theme-original 별칭을 사용할 수 있습니다.

아래 예제는 코드 중복을 최소화하면서 푸터 위에 텍스트를 표시하는 기능을 추가한 예제입니다.

src/theme/Footer.js
// 참고: "@theme/Footer" 가져오기를 시도하면 파일 자체를 가져오기 때문에 문제가 될 수 있습니다.import OriginalFooter from '@theme-original/Footer';import React from 'react';
export default function Footer(props) {  return (    <>      <div>Before footer</div>      <OriginalFooter {...props} />    </>  );}

플러그인 개발자#

테마는 다른 테마의 컴포넌트를 감쌀 수 있습니다. @theme-init 별칭을 사용해 원래 테마에서 컴포넌트를 가져올 수 있습니다.

아래 예제는 기본 테마의 CodeBlock 컴포넌트를 react-live 코드 연습 페이지 기능으로 확장하는 방법을 보여줍니다.

import InitialCodeBlock from '@theme-init/CodeBlock';import React from 'react';
export default function CodeBlock(props) {  return props.live ? (    <ReactLivePlayground {...props} />  ) : (    <InitialCodeBlock {...props} />  );}

좀 더 상세한 내용은 docusaurus-theme-live-codeblock 코드를 참고하세요.

caution

npm에 "확장된 테마"(docusaurus-theme-live-codeblock 같은)을 배포하지 않을 계획이라면 @theme-init 별칭을 사용하지 않아도 됩니다.

테마 설계#

테마는 플러그인과 같은 lifecyelc 메소드를 공유합니다. 하지만 테마의 설계 목적에 따라 플러그인과 구현 방식은 달라질 수 있습니다.

테마는 여러분이 도큐사우루스 사이트를 빌드하고 사이트, 플러그인, 테마 자신이 사용할 수 있는 컴포넌트를 공급하도록 설계됩니다. 때문에 일반적인 테마는 src/index.js 파일과 비슷한 형태로 lifecycle 메소드를 구현합니다. 하지만 플러그인에서 사용하는 loadContent 기능은 사용하지 않습니다. 그리고 보통은 src/theme 디렉터리 아래에 작성합니다.

다시 정리하면

  • 테마는 플러그인과 같은 lifecycle 메소드를 공유합니다.
  • 테마는 모든 플러그인이 설정된 이후 동작합니다.
  • 테마는 기존 웹팩 설정을 확장할 수 있게 컴포넌트 별칭을 추가할 수 있습니다.

사용자 지정 도큐사우루스 테마 만들기#

도큐사우루스 테마는 lifecyelc 메소드를 포함한 index.js 파일을 컴포넌트의 theme/ 디렉터리에 포함합니다. 일반적인 도큐사우루스 theme 디렉터리는 아래와 같습니다.

website├── package.json└── src    ├── index.js    └── theme        ├── MyThemeComponent        └── AnotherThemeComponent.js

아래 두 개의 lifecycle 메소드는 테마 구현 시 필수적인 항목입니다.

아래 lifecyelc 메소드는 꼭 구현해야 하는 건 아니지만 권장하는 항목입니다.