테마 설정
이 설정은 모든 메인 테마에 적용됩니다.
공통#
색상 모드 - 어두운 모드#
클래식 테마는 메뉴바에서 밝은 모드와 어두운 모드를 선택할 수 있는 기능을 기본으로 지원합니다.
아래와 같은 설정으로 색상 모드를 원하는 형태로 수정할 수 있습니다.
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: [ { // 웹 사이트 내부 탐색에 사용하는 클라이언트 사이드 라우팅을 설정합니다. // 해당 값 앞에 baseUrl은 자동으로 추가됩니다. to: 'docs/introduction', // 웹 사이트 외부 탐색에 사용하는 전체 페이지 경로를 설정합니다. // `to` 또는 `href`만 사용할 수 있습니다. href: 'https://www.facebook.com', // href 값 앞에 baseUrl을 추가할지 여부를 설정합니다. prependBaseUrlToHref: true, // 메뉴바 아이템에 표시할 문자열을 설정합니다. label: 'Introduction', // 메뉴바 아이템의 위치를 left 또는 right로 설정합니다. position: 'left', // 또는 'right' // 설정값으로 시작하는 모든 경로에 대해 // 활성 클래스 스타일을 적용합니다. // 거의 사용되지 않는 설정입니다. activeBasePath: 'docs', // 필요한 경우 activeBasePath 설정값에 추가로 정규식을 적용합니다. activeBaseRegex: 'docs/(next|v8)', // 사용자 지정 CSS 클래스(아이템 스타일 처리를 위해) className: '', }, // ... 다른 아이템 설정 ], }, // ... },};리액트 라우터는 자동으로 링크에 대해서 활성 링크 스타일을 적용합니다. 하지만 필요에 따라 activeBasePath를 사용할 수 있습니다. 여러 다른 경로의 링크를 활성화해야 하는 경우(예를 들면 같은 사이드바 아래 여러 문서 디렉터리가 포함된 경우) activeBaseRegex를 사용할 수 있습니다. activeBaseRegex는 activeBasePath보다 유연한 대안이며 우선적으로 적용됩니다. 도큐사우루스에서는 현재 URL에 정규식으로 적용해 구문 분석을 처리합니다.
외부 링크는 자동으로 target="_blank" rel="noopener noreferrer" 코드가 적용됩니다.
메뉴바 드롭다운#
메뉴바 아이템은 items 설정 시 드롭다운 아이템으로 적용할 수 있습니다.
module.exports = { // ... themeConfig: { navbar: { items: [ { label: 'Community', position: 'left', // 또는 'right' items: [ { label: 'Facebook', href: '...', }, { label: 'GitHub', href: '...', }, // ... 드롭다운 목록에 적용할 다른 아이템 설정 ], }, ], }, // ... },};메뉴바 문서 링크#
특정 문서에 대한 링크를 만들고 싶은 경우 특정 메뉴바 아이템 타입을 설정하면 docId를 기준으로 문서 링크를 만듭니다. 같은 사이드바 문서를 탐색하고 있다면 navbar__link--active 클래스를 얻게 됩니다.
module.exports = { themeConfig: { navbar: { items: [ { type: 'doc', docId: 'introduction',
//// 옵션 position: 'left', label: 'Docs', activeSidebarClassName: 'navbar__link--active', docsPluginId: 'default', }, ], }, },};메뉴바 문서 버전 드롭다운#
문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 여러분의 사이트에서 사용할 수 있는 버전 목록을 드롭다운 목록으로 표시할 수 있습니다.
사용자는 같은 문서를 유지하면서 다른 버전으로 전환할 수 있습니다(버전 별 문서 id가 같은 경우).
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersionDropdown',
//// 옵션 position: 'left', // 드롭다운 아이템 목록 시작 또는 끝에 추가할 아이템을 설정합니다. dropdownItemsBefore: [], dropdownItemsAfter: [{to: '/versions', label: 'All versions'}], // 문서 탐색 시에는 링크 활성화 클래스를 추가하지 못하도록 설정합니다. dropdownActiveClassDisabled: true, docsPluginId: 'default', }, ], }, },};메뉴바 문서 버전#
문서 버전 기능을 사용하고 있다면 특정 메뉴바 아이템 타입을 설정해 (현재 URL에 따라) 활성화되고 탐색하고 있는 문서 버전 링크로 연결할 수 있습니다. 설정이 없으면 최신 버전 링크로 연결합니다.
module.exports = { themeConfig: { navbar: { items: [ { type: 'docsVersion',
//// 옵션 position: 'left', to: '/path', // 기본값은 활성화된 최신 버전 링크 label: 'label', // 기본값은 활성화된 최신 버전 라벨 docsPluginId: 'default', }, ], }, },};메뉴바 로케일 드롭다운#
i18n 기능을 사용하고 있다면 특정 메뉴바 아이템을 설정해 사이트에서 사용할 수 있는 로케일을 드롭다운 목록에 표시할 수 있습니다.
사용자는 같은 문서를 유지하면서 다른 언어로 전환할 수 있습니다.
module.exports = { themeConfig: { navbar: { items: [ { type: 'localeDropdown',
//// 옵션 position: 'left', // 드롭다운 아이템 목록 시작 또는 끝에 추가할 아이템을 설정합니다. dropdownItemsBefore: [], dropdownItemsAfter: [ { to: 'https://my-site.com/help-us-translate', label: 'Help us translate', }, ], }, ], }, },};메뉴바 검색#
검색 기능을 사용하고 있다면 메뉴바 오른쪽 끝에 검색바가 표시됩니다.
하지만 특정 메뉴바 아이템을 설정해 기본 위치를 변경할 수 있습니다.
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> `, }, ], }, ], },};