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

테마 설정

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

공통

컬러 모드

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

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

설정할 수 있는 필드

필드명타입기본값설명
defaultMode!!crwdBlockTags_263_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',
},
};

메타 데이터

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

설정할 수 있는 필드

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

설정 예시:

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

설정할 수 있는 필드

필드명타입기본값설명
titlestringundefined메뉴바 제목입니다.
logo아래 내용 참고undefined사용자 지정 로고 오브젝트를 설정합니다.
itemsNavbarItem[][]메뉴바 아이템 목록입니다. 상세한 내용은 아래 내용을 참고하세요.
hideOnScrollbooleanfalse사용자가 아래로 스크롤 시 메뉴바를 숨길지 여부를 설정합니다.
style!!crwdBlockTags_307_sgaTkcolBdwrc!!테마와 같음어두운/밝은 테마 설정을 무시하고 메뉴바 스타일을 설정합니다.

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

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

설정할 수 있는 필드

필드명타입기본값설명
altstringundefined로고 이미지 Alt 태그입니다.
srcstring필수로고 이미지 URL를 설정합니다. 기본적으로 기본 URL이 추가됩니다.
srcDarkstringlogo.src어두운 모드에서 사용할 대체 이미지 URL을 설정합니다.
hrefstringsiteConfig.baseUrl로고 클릭 시 이동할 링크를 설정합니다.
targetstringhref 값에 따라 처리합니다(외부 링크는 새 탭으로 열리고 다른 모든 링크는 현재 탭에서 열립니다).링크의 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',
},
},
},
};

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" 코드가 적용됩니다.

설정할 수 있는 필드

필드명타입기본값설명
labelstring필수아이템을 표시하는 이름입니다.
tostring필수웹사이트 내에서 탐색 시 사용할 클라이언트 라우팅입니다. 해당 값 앞에 baseUrl이 자동으로 추가됩니다.
hrefstring필수웹사이트 외부 탐색 시 사용할 URL입니다. to 또는 href 중 하나만 사용해야 합니다.
prependBaseUrlToHrefbooleanfalsebaseUrl 값을 href 값 앞에 추가합니다.
position!!crwdBlockTags_350_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
activeBasePathstringto / href해당 경로로 시작하는 모든 경로에 활성 클래스 스타일을 적용합니다. 일반적인 경우는 필요하지 않습니다.
activeBaseRegexstringundefined필요한 경우 activeBasePath 값을 대체합니다.
classNamestring''사용자 지정 CSS 클래스(특정 아이템 스타일 설정 시).
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 필드를 내부 배열 형태로 가질 수 있습니다.

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

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

설정할 수 있는 필드

필드명타입기본값설명
labelstring필수아이템을 표시하는 이름입니다.
items!!crwdBlockTags_357_sgaTkcolBdwrc!!필수드롭다운에 포함될 아이템입니다.
position!!crwdBlockTags_358_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.

설정 예시:

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 클래스를 얻게 됩니다.

설정할 수 있는 필드

필드명타입기본값설명
docIdstring필수아이템이 링크되는 문서 ID입니다.
labelstringdocId아이템을 표시하는 이름입니다.
position!!crwdBlockTags_370_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
docsPluginIdstring'default'문서가 속한 문서 플러그인 ID입니다.

설정 예시:

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

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

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

설정할 수 있는 필드

필드명타입기본값설명
position!!crwdBlockTags_384_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
dropdownItemsBefore!!crwdBlockTags_385_sgaTkcolBdwrc!![]드롭다운 시작 부분에 드롭다운 아이템을 추가합니다.
dropdownItemsAfter!!crwdBlockTags_386_sgaTkcolBdwrc!![]드롭다운 끝 부분에 드롭다운 아이템을 추가합니다.
docsPluginIdstring'default'문서 버전 기능이 속한 문서 플러그인 ID입니다.
dropdownActiveClassDisabledbooleanfalse문서 탐색 시 링크 활성 클래스를 추가하지 마세요.

설정 예시:

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

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

설정할 수 있는 필드

필드명타입기본값설명
labelstring활성화/최신 버전을 표시하는 라벨입니다.아이템을 표시하는 이름입니다.
tostring활성화/최신 버전입니다.아이템이 가리키는 내부 링크입니다.
position!!crwdBlockTags_397_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
docsPluginIdstring'default'문서 버전 기능이 속한 문서 플러그인 ID입니다.

설정 예시:

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

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

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

설정할 수 있는 필드

필드명타입기본값설명
position!!crwdBlockTags_405_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
dropdownItemsBefore!!crwdBlockTags_406_sgaTkcolBdwrc!![]드롭다운 시작 부분에 드롭다운 아이템을 추가합니다.
dropdownItemsAfter!!crwdBlockTags_407_sgaTkcolBdwrc!![]드롭다운 끝 부분에 드롭다운 아이템을 추가합니다.

설정 예시:

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',
},
],
},
],
},
},
};

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

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

필드명타입기본값설명
position!!crwdBlockTags_411_sgaTkcolBdwrc!!'left'메뉴바에서 아이템이 표시되는 위치를 설정합니다.
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 오브젝트에서 처리합니다.

설정할 수 있는 필드

prism | --- | --- | --- | --- | | theme | PrismTheme | palenight | 밝은 테마 코드 블록에 사용할 프리즘 테마입니다. | | darkTheme | PrismTheme | palenight | 어두운 테마 코드 블록에 사용할 프리즘 테마입니다. | | defaultLanguage | string | undefined | 해당 아이템이 메뉴바에서 표시될 위치를 설정합니다. |

테마

기본적으로 구문 강조 테마로 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은 메뉴바 로고와 같은 방식으로 처리됩니다.

설정할 수 있는 필드

필드명타입기본값설명
logoLogoundefined사용자 지정 로고 오브젝트입니다. 자세한 내용은 메뉴바 로고 항목을 참고하세요.
copyrightstringundefined바닥글에 표시되는 저작권 정보 문구입니다.
style!!crwdBlockTags_434_sgaTkcolBdwrc!!'light'바닥글 컴포넌트의 색상 테마입니다.
itemsFooterItem[][]표시할 링크 그룹입니다.

설정 예시:

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

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

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

필드명타입기본값설명
titlestringundefined링크 영역을 표시하는 이름입니다.
itemsFooterLink[][]링크 처리할 아이템입니다.

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

필드명타입기본값설명
labelstring필수링크를 나타내는 텍스트입니다.
tostring필수웹사이트 내에서 탐색 시 사용할 클라이언트 라우팅입니다. 해당 값 앞에 baseUrl이 자동으로 추가됩니다.
hrefstring필수웹사이트 외부 탐색 시 사용할 URL입니다. to 또는 href 중 하나만 사용할 수 있습니다.
htmlstringundefined단순 링크 대신 HTML 형식으로 설정합니다. html 필드를 설정한 경우에는 다른 옵션은 설정하지 않아야 합니다.

설정 예시:

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