메인 컨텐츠로 이동
버전: 불안정 🚧

테마 설정

이 설정은 모든 메인 테마에 적용됩니다.

공통

컬러 모드

클래식 테마는 메뉴바에서 밝은 모드와 어두운 모드를 선택할 수 있는 기능을 기본으로 지원합니다.

colorMode 오브젝트 내에서 사용자 지정 컬러 모드를 설정할 수 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명
defaultMode'light' | 'dark''light'사용자가 사이트를 처음 방문할 때 컬러 모드입니다.
disableSwitchbooleanfalse메뉴바에서 스위치를 숨깁니다. 하나의 컬러 모드만 지원하기 원하는 경우 유용합니다.
respectPrefersColorSchemebooleanfalse직접 설정한 defaultMode 대신 사용자 시스템 기본 설정을 사용해 prefers-color-scheme 미디어 쿼리를 사용할지 여부

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
},
},
};
경고

respectPrefersColorScheme: true로 설정한 경우 defaultMode 설정값은 사용자 시스템 환경 설정에 따라 재정의됩니다.

하나의 색상 모드만 지원하려면 사용자 시스템 환경 설정에 영향을 받지 않게 해야 합니다.

메타 정보 이미지

og:imagetwitter:image처럼 메타 태그에서 사용할 기본 이미지를 설정합니다.

설정할 수 있는 필드

옵션명타입기본값설명
imagestringundefined사이트의 메타 이미지 URL입니다. 사이트 "정적" 디렉터리에 상대 경로로 설정합니다. SVG 파일은 설정할 수 없습니다. 외부 URL은 사용할 수 있습니다.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
image: 'img/docusaurus.png',
},
};

메타데이터

HTML 메타 데이터를 추가하거나 (기존 항목을 재정의할 수 있습니다).

설정할 수 있는 필드

옵션명타입기본값설명
metadataMetadata[][]모든 필드는 <meta /> 태그로 직접 전달됩니다. 사용할 수 있는 필드는 id, name, property, content, itemprop 등이 있습니다.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
metadata: [{name: 'twitter:card', content: 'summary'}],
},
};

알림표시줄

웹 사이트에서 공지할 내용이 생길 수 있습니다. 그런 경우 알림표시줄을 추가할 수 있습니다. 메뉴바 위에 고정되지 않고 선택적으로 사용자가 닫을 수 있는 패널이 표시됩니다. 모든 설정은 announcementBar 오브젝트에서 처리합니다.

설정할 수 있는 필드

옵션명타입기본값설명
idstring'announcement-bar'메시지를 식별하는 모든 값입니다.
contentstring''알리고자 하는 텍스트 콘텐츠입니다. HTML을 삽입할 수 있습니다.
backgroundColorstring'#fff'알림표시줄 영역 배경색입니다.
textColorstring'#000'알림메시지 텍스트 색상입니다.
isCloseablebooleantrue알림메시지를 'x' 버튼으로 닫을 수 있는지 여부

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
announcementBar: {
id: 'support_us',
content:
'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
backgroundColor: '#fafbfc',
textColor: '#091E42',
isCloseable: false,
},
},
};

플러그인

Our main themes offer additional theme configuration options for Docusaurus core content plugins.

문서

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
docs: {
versionPersistence: 'localStorage',
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
},
};

블로그

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
blog: {
sidebar: {
groupByYear: true,
},
},
},
};

설정할 수 있는 필드

옵션명타입기본값설명

로고는 static 디렉터리에 가져다 놓을 수 있습니다. 로고 URL은 기본적으로 여러분의 사이트 기본 URL이 설정됩니다. 로고 URL을 따로 설정할 수는 있지만 외부 링크인 경우에는 새로운 탭에서 열리게 됩니다. 또한 로고 링크의 target 속성값을 재정의할 수 있습니다. 메인 웹 사이트의 하위 디렉터리에서 문서 웹 사이트를 서비스하는 경우에 유용한 기능입니다. 이런 경우 메인 웹 사이트를 새로운 탭에서 열어주는 로고 링크가 필요하지 않을 수도 있습니다.

어두운 모드 지원을 위해 모드마다 다른 로고를 설정할 수도 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
title: 'Site Title',
logo: {
alt: 'Site Logo',
src: 'img/logo.svg',
srcDark: 'img/logo_dark.svg',
href: 'https://docusaurus.io/',
target: '_self',
width: 32,
height: 32,
className: 'custom-navbar-logo-class',
style: {border: 'solid red'},
},
},
},
};

themeConfig.navbar.items 설정에서 메뉴바에 아이템을 추가할 수 있습니다.

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
{to: 'blog', label: 'Blog', position: 'left'},
{
type: 'docsVersionDropdown',
position: 'right',
},
{
type: 'localeDropdown',
position: 'right',
},
{
href: 'https://github.com/facebook/docusaurus',
position: 'right',
className: 'header-github-link',
'aria-label': 'GitHub repository',
},
],
},
},
};

아이템은 type 필드에 따라 다르게 동작할 수 있습니다. 사용할 수 있는 모든 유형의 메뉴바 아이템을 아래에 소개합니다.

기본적으로 메뉴바 아이템은 일반 링크(내부 또는 외부)입니다.

리액트 라우터는 자동으로 링크에 대해서 활성 링크 스타일을 적용합니다. 하지만 필요에 따라 activeBasePath를 사용할 수 있습니다. 여러 다른 경로의 링크를 활성화해야 하는 경우(예를 들면 같은 사이드바 아래 여러 문서 디렉터리가 포함된 경우) activeBaseRegex를 사용할 수 있습니다. activeBaseRegexactiveBasePath보다 유연한 대안이며 우선적으로 적용됩니다. 도큐사우루스에서는 현재 URL에 정규식으로 적용해 구문 분석을 처리합니다.

외부 링크는 자동으로 target="_blank" rel="noopener noreferrer" 코드가 적용됩니다.

설정할 수 있는 필드

옵션명타입기본값설명
참고

위에 설명한 필드 외에 HTML 링크에 적용할 수 있는 다른 속성을 사용할 수 있습니다.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
to: 'docs/introduction',
// Only one of "to" or "href" should be used
// href: 'https://www.facebook.com',
label: 'Introduction',
// Only one of "label" or "html" should be used
// html: '<b>Introduction</b>'
position: 'left',
activeBaseRegex: 'docs/(next|v8)',
target: '_blank',
},
],
},
},
};

dropdown 유형의 메뉴바 아이템은 추가적으로 items 필드를 내부 배열 형태로 가질 수 있습니다.

메뉴바 드롭다운 아이템은 아래와 같이 "링크 기능을 지원하는" 아이템 유형만 허용합니다.

드롭다운 기본 아이템도 클릭할 수 있는 링크이므로 해당 아이템은 일반적인 메뉴바 링크의 모든 속성을 가질 수 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'dropdown',
label: 'Community',
position: 'left',
items: [
{
label: 'Facebook',
href: 'https://www.facebook.com',
},
{
type: 'doc',
label: 'Social',
docId: 'social',
},
// ... more items
],
},
],
},
},
};

특정 문서에 대한 링크를 만들고 싶은 경우 특정 메뉴바 아이템 타입을 설정하면 docId를 기준으로 문서 링크를 만듭니다. 같은 사이드바 문서를 탐색하고 있다면 navbar__link--active 클래스를 얻게 됩니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
],
},
},
};

문서 ID를 하드코딩하지 않고 주어진 사이드바의 첫 번째 문서 링크(문서 링크 또는 생성된 카테고리 인덱스)에 메뉴바 항목을 연결할 수 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명

사이드바가 자주 업데이트되고 순서가 안정적이지 않은 경우에 이 메뉴바 항목 타입을 사용하세요.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docSidebar',
position: 'left',
sidebarId: 'api',
label: 'API',
},
],
},
},
};
sidebars.js
export default {
tutorial: [
{
type: 'autogenerated',
dirName: 'guides',
},
],
api: [
'cli', // The navbar item will be linking to this doc
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};

문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 여러분의 사이트에서 사용할 수 있는 버전 목록을 드롭다운 목록으로 표시할 수 있습니다.

사용자는 같은 문서를 유지하면서 다른 버전으로 전환할 수 있습니다(버전 별 문서 ID가 같은 경우).

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
position: 'left',
dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
dropdownActiveClassDisabled: true,
},
],
},
},
};

문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 (현재 URL에 따라) 활성화되고 탐색하고 있는 문서 버전 링크로 연결할 수 있습니다. 설정이 없으면 최신 버전 링크로 연결합니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersion',
position: 'left',
to: '/path',
label: 'label',
},
],
},
},
};

i18n 기능을 사용하고 있다면 특정 메뉴바 아이템을 설정해 사이트에서 사용할 수 있는 로케일을 드롭다운 목록에 표시할 수 있습니다.

사용자는 같은 문서를 유지하면서 다른 언어로 전환할 수 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'localeDropdown',
position: 'left',
dropdownItemsAfter: [
{
to: 'https://my-site.com/help-us-translate',
label: 'Help us translate',
},
],
},
],
},
},
};

검색 기능을 사용하고 있다면 메뉴바 오른쪽 끝에 검색바가 표시됩니다.

하지만 특정 메뉴바 아이템을 설정해 기본 위치를 변경할 수 있습니다.

옵션명타입기본값설명
docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};

해당 메뉴바 아이템 타입을 사용해 메뉴바 아이템 내부에 여러분만의 HTML 마크업을 렌더링할 수 있습니다.

옵션명타입기본값설명
docusaurus.config.js
export default {
themeConfig: {
navbar: {
items: [
{
type: 'html',
position: 'right',
value: '<button>Give feedback</button>',
},
],
},
},
};

메뉴바 자동 숨김

사용자가 페이지 스크롤 다운을 시작하면 자동으로 메뉴바가 숨겨지고 스크롤을 올리면 다시 보여지는 UI 기능을 활성화할 수 있습니다.

docusaurus.config.js
export default {
themeConfig: {
navbar: {
hideOnScroll: true,
},
},
};

테마 전환 기능을 비활성화하지 않고도 메뉴바의 스타일을 따로 설정할 수 있습니다. 선택한 스타일은 선택한 테마와 상관없이 항상 적용됩니다.

현재 설정할 수 있는 스타일 옵션은 2가지입니다. dark, primary(--ifm-color-primary 색상에 따라) 인피마 문서에서 적용될 스타일을 확인해볼 수 있습니다.

docusaurus.config.js
export default {
themeConfig: {
navbar: {
style: 'primary',
},
},
};

코드 블록

도큐사우루스에서는 Prism React Renderer를 사용해 코드 블록 구문 강조를 처리합니다. 모든 설정은 prism 오브젝트에서 처리합니다.

설정할 수 있는 필드

옵션명타입기본값설명
themePrismThemepalenightlight-theme 코드 블록에서 사용할 Prism 테마입니다.
darkThemePrismThemepalenightdark-theme 코드 블록에서 사용할 Prism 테마입니다.
defaultLanguagestringundefinedThe default language to use for code blocks not declaring any explicit language.
magicCommentsMagicCommentConfig[]아래를 참조하세요.매직 주석 목록입니다.
type MagicCommentConfig = {
className: string;
line?: string;
block?: {start: string; end: string};
};
const defaultMagicComments = [
{
className: 'theme-code-block-highlighted-line',
line: 'highlight-next-line',
block: {start: 'highlight-start', end: 'highlight-end'},
},
];

테마

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
themeConfig: {
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
},
},
};
참고

마크다운 구문을 강조해야 하는 경우 어두운 모드 구문 강조 테마 사용 시 다른 배경색을 설정해야 할 수도 있습니다. 적용 가이드를 참고하세요.

기본 언어

3개의 억음부호(```) 뒤에 언어를 설정하지 않았을 때 코드 블록에서 기본으로 적용할 언어를 설정할 수 있습니다. 유효한 언어명을 설정해주어야 하는 것은 주의해주세요.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
},
};

themeConfig.footer 설정에서 바닥글에 로고나 저작권 정보를 추가할 수 있습니다. 로고는 static 디렉터리에 가져다 놓을 수 있습니다. 로고 URL은 메뉴바 로고와 같은 방식으로 처리됩니다.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: 'img/meta_oss_logo.png',
href: 'https://opensource.fb.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},
},
};

themeConfig.footer.links 설정에서 바닥글에 링크를 추가할 수 있습니다. 바닥글 구성에는 multi-column footerssimple footers 두 가지 유형이 있습니다.

다중 컬럼 바닥글 링크는 각 컬럼에 대한 titleFooterItem 목록이 있습니다.

옵션명타입기본값설명

FooterItem에서 사용할 수 있는 필드는 아래와 같습니다.

옵션명타입기본값설명

다중 컬럼 구성 예제입니다.

docusaurus.config.js
export default {
footer: {
links: [
{
title: 'Docs',
items: [
{
label: 'Style Guide',
to: 'docs/',
},
{
label: 'Second Doc',
to: 'docs/doc2/',
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'X',
href: 'https://x.com/docusaurus',
},
{
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
</a>
`,
},
],
},
],
},
};

간단한 바닥글에는 행에 표시되는 FooterItem 목록이 있습니다.

간단한 구성 예제입니다.

docusaurus.config.js
export default {
footer: {
links: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
{
label: 'X',
href: 'https://x.com/docusaurus',
},
{
html: `
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
</a>
`,
},
],
},
};

목차

themeConfig.tableOfContents에서 기본 목차를 설정할 수 있습니다.

옵션명타입기본값설명
minHeadingLevelnumber2목차에 표시되는 최소 제목 수준입니다. 2에서 6 사이의 값으로 설정할 수 있고 최댓값보다 작거나 같아야 합니다.
maxHeadingLevelnumber3목차에 표시되는 최대 제목 수준입니다. 2에서 6 사이의 값으로 설정할 수 있습니다.

설정 예시:

docusaurus.config.js
export default {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};

후크

useColorMode

색상 컨텍스트에 접근하기 위한 리액트 후크입니다. 컨텍스트는 어두운, 밝은 모드를 설정하기 위한 함수와 현재 사용하고 있는 모드를 알려주는 부울 변수를 포함하고 있습니다.

사용 예:

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
const {colorMode, setColorMode} = useColorMode();

return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
참고

useColorMode를 호출하는 컴포넌트는 Layout 컴포넌트의 자식 요소이어야 합니다.

function ExamplePage() {
return (
<Layout>
<Example />
</Layout>
);
}

i18n

i18n 소개 문서를 먼저 확인해주세요.

번역 파일 위치

  • Base 경로: website/i18n/[locale]/docusaurus-theme-[themeName]
  • 멀티 인스턴스 경로: 해당없음
  • JSON 파일: docusaurus write-translations 명령 실행 후 만들어진 파일
  • 마크다운 파일: 해당없음

파일 시스템 구조 예

website/i18n/[locale]/docusaurus-theme-classic

# translations for the theme
├── navbar.json
└── footer.json