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

테마 설정

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

공통

컬러 모드

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

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

설정할 수 있는 필드

필드명타입기본값설명
defaultMode!!crwdBlockTags_283_sgaTkcolBdwrc!!'light'사용자가 사이트를 처음 방문할 때 컬러 모드입니다.
disableSwitchbooleanfalse메뉴바에서 컬러모드 변환 스위치를 숨깁니다. 하나의 컬러 모드만 지원하기 원하는 경우 유용합니다.
respectPrefersColorSchemebooleanfalsedefaultMode 설정값 대신 사용자 시스템 설정을 사용해 prefers-color-scheme 미디어 쿼리를 사용할지 여부를 설정합니다.
switchConfig아래 내용 참고아래 내용 참고어두운/밝은 변환 스위치 아이콘 옵션을 설정합니다.
switchConfig.darkIconstring'🌜'어두운 모드 변환 시 사용하는 아이콘을 설정합니다.
switchConfig.darkIconStyleJSX 스타일 오브젝트(documentation를 참고하세요){}어두운 모드 아이콘에 적용할 CSS를 설정합니다.
switchConfig.lightIconstring'🌞'밝은 모드 변환 시 사용하는 아이콘을 설정합니다.
switchConfig.lightIconStyleJSX 스타일 오브젝트{}밝은 모드 아이콘에 적용할 CSS를 설정합니다.

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
switchConfig: {
darkIcon: '🌙',
darkIconStyle: {
marginLeft: '2px',
},
// '\u2600' 형식의 유니코드 아이콘을 설정할 수 있습니다.
// 5자리 유니코드 사용 시에는 중괄호를 사용해야 합니다: '\u{1F602}'
lightIcon: '\u{1F602}',
lightIconStyle: {
marginLeft: '1px',
},
},
},
},
};
caution

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

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

메타 정보 이미지

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
image: 'img/docusaurus.png',
},
};

Metadata

You can configure additional html metadata (and override existing ones).

설정할 수 있는 필드

NameTypeDefaultDescription
metadataMetadata[][]Any field will be directly passed to the <meta /> tag. id, name, property, content, itemprop 등의 필드를 사용할 수 있습니다.

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
metadata: [{name: 'twitter:card', content: 'summary'}],
},
};

알림표시줄

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

설정할 수 있는 필드

필드명타입기본값설명
idstring'announcement-bar'메시지를 식별하기 위한 값입니다.
contentstring''알림에 사용할 텍스트 콘텐츠입니다. HTML을 삽입할 수 있습니다.
backgroundColorstring'#fff'전체 바 영역에 적용할 배경 색상을 설정합니다.
textColorstring'#000'알림 메시지 텍스트 색상을 설정합니다.
isCloseablebooleantrue알림표시줄을 '×' 버튼으로 해제할 수 있을지 여부를 설정합니다.

설정 예시:

docusaurus.config.js
module.exports = {
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,
},
},
};

설정할 수 있는 필드

필드명타입기본값설명

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

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

docusaurus.config.js
module.exports = {
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,
},
},
},
};

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

docusaurus.config.js
module.exports = {
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" 코드가 적용됩니다.

설정할 수 있는 필드

필드명타입기본값설명
note

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

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
to: 'docs/introduction',
// "to" 또는 "href" 중 하나만 설정할 수 있습니다.
// href: 'https://www.facebook.com',
label: 'Introduction',
position: 'left',
activeBaseRegex: 'docs/(next|v8)',
target: '_blank',
},
],
},
},
};

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

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

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

docusaurus.config.js
module.exports = {
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
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'doc',
position: 'left',
docId: 'introduction',
label: 'Docs',
},
],
},
},
};

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

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

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

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

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

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

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

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

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

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

필드명타입기본값설명
docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
items: [
{
type: 'search',
position: 'right',
},
],
},
},
};

메뉴바 자동 숨김

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

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
hideOnScroll: true,
},
},
};

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

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

docusaurus.config.js
module.exports = {
themeConfig: {
navbar: {
style: 'primary',
},
},
};

코드 블록

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

설정할 수 있는 필드

NameTypeDefaultDescription
themePrismThemepalenightThe Prism theme to use for light-theme code blocks.
darkThemePrismThemepalenight어두운 테마 코드 블록에 사용할 프리즘 테마입니다.
defaultLanguagestringundefined해당 아이템이 메뉴바에서 표시될 위치를 설정합니다.

테마

기본적으로 구문 강조 테마로 Palenight를 사용합니다. 사용할 수 있는 테마 목록에서 다른 테마를 선택할 수 있습니다. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
prism: {
theme: require('prism-react-renderer/themes/github'),
darkTheme: require('prism-react-renderer/themes/dracula'),
},
},
};
note

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

기본 언어

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

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
prism: {
defaultLanguage: 'javascript',
},
},
};

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

설정할 수 있는 필드

필드명타입기본값설명

설정 예시:

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

themeConfig.footer.links 설정에서 바닥글에 링크를 추가할 수 있습니다.

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

필드명타입기본값설명

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

필드명타입기본값설명

설정 예시:

docusaurus.config.js
module.exports = {
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: 'Twitter',
href: 'https://twitter.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" />
</a>
`,
},
],
},
],
},
};

목차

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

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

설정 예시:

docusaurus.config.js
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};

후크

useThemeContext

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

사용 예:

import React from 'react';
import useThemeContext from '@theme/hooks/useThemeContext';

const Example = () => {
const {isDarkTheme, setLightTheme, setDarkTheme} = useThemeContext();

return <h1>Dark mode is now {isDarkTheme ? 'on' : 'off'}</h1>;
};
note

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

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

i18n

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

번역 파일 위치

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

파일 시스템 구조 예

website/i18n/<locale>/docusaurus-theme-classic

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