테마 설정
이 설정은 모든 메인 테마에 적용됩니다.
공통#
색상 모드 - 어두운 모드#
클래식 테마는 메뉴바에서 밝은 모드와 어두운 모드를 선택할 수 있는 기능을 기본으로 지원합니다.
아래와 같은 설정으로 색상 모드를 원하는 형태로 수정할 수 있습니다.
module.exports = { // ... themeConfig: { // ... colorMode: { // "light" | "dark" defaultMode: 'light',
// 메뉴바에서 모드 전환 버튼을 숨깁니다. // 하나의 색상 모드만 지원하는 경우에 사용할 수 있습니다. disableSwitch: false,
// defaultMode 설정값 대신 사용자 시스템 환경 설정에 따라 // prefers-color-scheme 미디어쿼리 속성을 적용할지 여부를 설정합니다. respectPrefersColorScheme: false,
// 어두운/밝은 모드 전환 아이콘 옵션을 설정합니다. switchConfig: { // 어두운 모드일 때 전환 버튼 아이콘을 설정합니다. darkIcon: '🌙',
// 리액트 인라인 스타일 오브젝트로 // 어두운 모드 아이콘에 적용할 CSS를 설정합니다. // https://reactjs.org/docs/dom-elements.html#style를 참고하세요. darkIconStyle: { marginLeft: '2px', },
// '\u2600'같은 유니코드 아이콘을 설정할 수 있습니다. // 5자리 유니코드를 사용하려면 대괄호로 감싸주어야 합니다: '\u{1F602}' lightIcon: '\u{1F602}',
lightIconStyle: { marginLeft: '1px', }, }, }, // ... }, // ...};caution
respectPrefersColorScheme: true로 설정한 경우 defaultMode 설정값은 사용자 시스템 환경 설정에 따라 재정의됩니다.
하나의 색상 모드만 지원하려면 사용자 시스템 환경 설정에 영향을 받지 않게 해야 합니다.
메타 정보 이미지#
og:image나 twitter:image처럼 메타 태그에서 사용할 기본 이미지를 설정합니다.
module.exports = { // ... themeConfig: { // 사이트 "static" 디렉터리의 상대 경로를 설정합니다. // SVG 파일은 설정할 수 없습니다. 외부 URL은 사용할 수 있습니다. image: 'img/docusaurus.png', // ... },};메타 데이터#
HTML 메타 데이터를 추가하거나 (기존 항목을 재정의할 수 있습니다).
module.exports = { // ... themeConfig: { metadatas: [{name: 'twitter:card', content: 'summary'}], // ... },};알림표시줄#
웹 사이트에서 공지할 내용이 생길 수 있습니다. 그런 경우 알림표시줄을 추가할 수 있습니다. 메뉴바 위에 고정되지 않고 선택적으로 사용자가 닫을 수 있는 패널이 표시됩니다.
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', // 기본값 `#fff`. textColor: '#091E42', // 기본값 `#000`. isCloseable: false, //기본값 `true`. }, // ... },};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후크#
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> );}메뉴바#
메뉴바 제목과 로고#
themeConfig.navbar 설정에서 메뉴바에 로고와 제목을 추가할 수 있습니다. 로고는 static 디렉터리에 가져다 놓을 수 있습니다. 로고 URL은 기본적으로 여러분의 사이트 기본 URL이 설정됩니다. 로고 URL을 따로 설정할 수는 있지만 외부 링크인 경우에는 새로운 탭에서 열리게 됩니다. 또한 로고 링크의 target 속성값을 재정의할 수 있습니다. 메인 웹 사이트의 하위 디렉터리에서 문서 웹 사이트를 서비스하는 경우에 유용한 기능입니다. 이런 경우 메인 웹 사이트를 새로운 탭에서 열어주는 로고 링크가 필요하지 않을 수도 있습니다.
어두운 모드 지원을 위해 모드마다 다른 로고를 설정할 수도 있습니다.
module.exports = { // ... themeConfig: { navbar: { title: 'Site Title', logo: { alt: 'Site Logo', src: 'img/logo.svg', srcDark: 'img/logo_dark.svg', // 기본값 `logo.src`. href: 'https://docusaurus.io/', // 기본값 `siteConfig.baseUrl`. target: '_self', // 기본적으로 이 값은 `href` 속성에 따라 처리됩니다(외부 링크는 새로운 탭으로 열리고 그 외에는 현재 탭에서 열립니다). }, }, // ... },};메뉴바 아이템#
themeConfig.navbar.items 설정에서 메뉴바에 아이템을 추가할 수 있습니다.
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를 사용할 수 있습니다. activeBaseRegex는 activeBasePath보다 유연한 대안이며 우선적으로 적용됩니다. 도큐사우루스에서는 현재 URL에 정규식으로 적용해 구문 분석을 처리합니다.
외부 링크는 자동으로 target="_blank" rel="noopener noreferrer" 코드가 적용됩니다.
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
label | string | 아이템을 표시하는 이름입니다. | Yes | |
to | string | 웹 사이트 내에서 탐색을 위해 사용하는 클라이언트 경로입니다. 해당 값 앞에 baseUrl이 자동으로 추가됩니다. | Yes | |
href | string | 웹 사이트 외부 탐색을 위해 사용하는 전체 페이지 탐색입니다. to 또는 href 중 하나만 사용해야 합니다. | Yes | |
prependBaseUrlToHref | boolean | baseUrl을 href 값 앞에 추가합니다. | No | false |
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
activeBasePath | string | 해당 경로로 시작하는 모든 경로에 활성화된 클래스 스타일을 적용합니다. 일반적인 경우는 필요하지 않습니다. | No | to / href |
activeBaseRegex | string | 필요한 경우 activeBasePath를 대체해 사용할 수 있습니다. | No | undefined |
className | string | 커스텀 CSS 클래스(특정 아이템 스타일 처리) | No | '' |
설정 예시:
module.exports = { themeConfig: { navbar: { items: [ { to: 'docs/introduction', // "to" 또는 "href" 중 하나만 사용해야 합니다. // href: 'https://www.facebook.com', label: 'Introduction', position: 'left', activeBaseRegex: 'docs/(next|v8)', }, ], }, },};메뉴바 드롭다운#
dropdown 유형의 메뉴바 아이템은 추가적으로 items 필드를 내부 배열 형태로 가질 수 있습니다.
메뉴바 드롭다운 아이템은 아래와 같이 "링크 기능을 지원하는" 아이템 유형만 허용합니다.
드롭다운 기본 아이템도 클릭할 수 있는 링크이므로 해당 아이템은 일반적인 메뉴바 링크의 모든 속성을 가질 수 있습니다.
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
label | string | 아이템을 표시하는 이름입니다. | Yes | |
items | LinkLikeItem[] | 드롭다운에 포함될 아이템입니다. | Yes | |
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
설정 예시:
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 클래스를 얻게 됩니다.
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
docId | string | 아이템에서 링크로 연결되는 문서의 ID입니다. | Yes | |
label | string | 아이템을 표시하는 이름입니다. | No | docId |
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
activeSidebarClassName | string | 문서 사이드바가 활성화될 때 적용할 CSS 클래스 이름입니다. | No | 'navbar__link--active' |
docsPluginId | string | 문서가 속한 문서 플러그인 ID입니다. | No | 'default' |
설정 예시:
module.exports = { themeConfig: { navbar: { items: [ { type: 'doc', position: 'left', docId: 'introduction', label: 'Docs', }, ], }, },};메뉴바 문서 버전 드롭다운#
문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 여러분의 사이트에서 사용할 수 있는 버전 목록을 드롭다운 목록으로 표시할 수 있습니다.
사용자는 같은 문서를 유지하면서 다른 버전으로 전환할 수 있습니다(버전 별 문서 id가 같은 경우).
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
dropdownItemsBefore | LinkLikeItem[] | 드롭다운 시작 부분에 드롭다운 아이템을 추가합니다. | No | [] |
dropdownItemsAfter | LinkLikeItem[] | 드롭다운 끝 부분에 드롭다운 아이템을 추가합니다. | No | [] |
docsPluginId | string | 문서 버전이 속한 문서 플러그인 ID입니다. | No | 'default' |
dropdownActiveClassDisabled | boolean | 문서를 탐색할 때 링크 활성 클래스를 추가하지 않습니다. | No | false |
설정 예시:
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersionDropdown', position: 'left', dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], dropdownActiveClassDisabled: true, }, ], }, },};메뉴바 문서 버전#
문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 (현재 URL에 따라) 활성화되고 탐색하고 있는 문서 버전 링크로 연결할 수 있습니다. 설정이 없으면 최신 버전 링크로 연결합니다.
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
label | string | 아이템을 표시하는 이름입니다. | No | 활성화/최신 버전 라벨 |
to | string | 아이템이 가리키는 내부 링크입니다. | No | 활성화/최신 버전 |
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
docsPluginId | string | 문서 버전이 속한 문서 플러그인 ID입니다. | No | 'default' |
설정 예시:
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersion', position: 'left', to: '/path', label: 'label', }, ], }, },};메뉴바 로케일 드롭다운#
i18n 기능을 사용하고 있다면 특정 메뉴바 아이템을 설정해 사이트에서 사용할 수 있는 로케일을 드롭다운 목록에 표시할 수 있습니다.
사용자는 같은 문서를 유지하면서 다른 언어로 전환할 수 있습니다.
설정할 수 있는 필드
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
dropdownItemsBefore | LinkLikeItem[] | 드롭다운 시작 부분에 드롭다운 아이템을 추가합니다. | No | [] |
dropdownItemsAfter | LinkLikeItem[] | 드롭다운 끝 부분에 드롭다운 아이템을 추가합니다. | No | [] |
설정 예시:
module.exports = { themeConfig: { navbar: { items: [ { type: 'localeDropdown', position: 'left', dropdownItemsAfter: [ { to: 'https://my-site.com/help-us-translate', label: 'Help us translate', }, ], }, ], }, },};메뉴바 검색#
검색 기능을 사용하고 있다면 메뉴바 오른쪽 끝에 검색바가 표시됩니다.
하지만 특정 메뉴바 아이템을 설정해 기본 위치를 변경할 수 있습니다.
| Field | 값 | 설명 | 필수사항 | 기본값 |
|---|---|---|---|---|
position | 'left' | 'right' | 메뉴바에서 아이템이 표시되는 위치를 설정합니다. | No | 'left' |
module.exports = { themeConfig: { navbar: { items: [ { type: 'search', position: 'right', }, ], }, },};메뉴바 자동 숨김#
사용자가 페이지 스크롤 다운을 시작하면 자동으로 메뉴바가 숨겨지고 스크롤을 올리면 다시 보여지는 UI 기능을 활성화할 수 있습니다.
module.exports = { // ... themeConfig: { navbar: { hideOnScroll: true, }, // ... },};메뉴바 스타일#
테마 전환 기능을 비활성화하지 않고도 메뉴바의 스타일을 따로 설정할 수 있습니다. 선택한 스타일은 선택한 테마와 상관없이 항상 적용됩니다.
현재 설정할 수 있는 스타일 옵션은 2가지입니다. dark, primary(--ifm-color-primary 색상에 따라) 인피마 문서에서 적용될 스타일을 확인해볼 수 있습니다.
module.exports = { // ... themeConfig: { navbar: { style: 'primary', }, // ... },};코드 블록#
도큐사우루스에서는 Prism React Renderer를 사용해 코드 블록 구문 강조를 처리합니다.
테마#
기본적으로 구문 강조 테마로 Palenight를 사용합니다. 사용할 수 있는 테마 목록에서 다른 테마를 선택할 수 있습니다. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.
module.exports = { // ... themeConfig: { prism: { theme: require('prism-react-renderer/themes/github'), darkTheme: require('prism-react-renderer/themes/dracula'), }, // ... },};note
마크다운 구문을 강조해야 하는 경우 어두운 모드 구문 강조 테마 사용 시 다른 배경색을 설정해야 할 수도 있습니다. 적용 가이드를 참고하세요.
기본 언어#
3개의 억음부호(```) 뒤에 언어를 설정하지 않았을 때 코드 블록에서 기본으로 적용할 언어를 설정할 수 있습니다. 유효한 언어명을 설정해주어야 하는 것은 주의해주세요.
module.exports = { // ... themeConfig: { prism: { defaultLanguage: 'javascript', }, // ... },};바닥글#
themeConfig.footer 설정에서 바닥글에 로고나 저작권 정보를 추가할 수 있습니다. 로고는 static 디렉터리에 가져다 놓을 수 있습니다. 로고 URL은 메뉴바 로고와 같은 방식으로 처리됩니다.
// ... 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 설정에서 바닥글에 링크를 추가할 수 있습니다.
module.exports = { // ... footer: { links: [ { // 링크 그룹 제목을 설정합니다. title: 'Docs', items: [ { // 링크 제목을 설정합니다. label: 'Style Guide', // 웹 사이트 내에서 탐색할 때 사용할 클라이언트 라우팅을 설정합니다. // 해당 값 앞에 baseUrl은 자동으로 추가됩니다. to: 'docs/', }, { label: 'Second Doc', to: 'docs/doc2/', }, ], }, { title: 'Community', items: [ { label: 'Stack Overflow', // 웹 사이트 바깥에 있는 링크는 전체 URL을 설정합니다. href: 'https://stackoverflow.com/questions/tagged/docusaurus', }, { label: 'Discord', href: 'https://discordapp.com/invite/docusaurus', }, { label: 'Twitter', href: 'https://twitter.com/docusaurus', }, { //단순 링크 대신 HTML 구문을 설정할 수도 있습니다. 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> `, }, ], }, ], },};