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

테마 설정

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

공통#

색상 모드 - 어두운 모드#

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

아래와 같은 설정으로 색상 모드를 원하는 형태로 수정할 수 있습니다.

docusaurus.config.js
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:imagetwitter:image처럼 메타 태그에서 사용할 기본 이미지를 설정합니다.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // 사이트 "static" 디렉터리의 상대 경로를 설정합니다.    // SVG 파일은 설정할 수 없습니다. 외부 URL은 사용할 수 있습니다.    image: 'img/docusaurus.png',    // ...  },};

메타 데이터#

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

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

알림표시줄#

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

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', // 기본값 `#fff`.      textColor: '#091E42', // 기본값 `#000`.      isCloseable: false, //기본값 `true`.    },    // ...  },};

i18n#

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

번역 파일 위치#

  • 기본 경로: website/i18n/<locale>/docusaurus-theme-<themeName>
  • 멀티 인스턴스 경로: 해당없음
  • JSON 파일: extracted with 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 속성값을 재정의할 수 있습니다. 메인 웹 사이트의 하위 디렉터리에서 문서 웹 사이트를 서비스하는 경우에 유용한 기능입니다. 이런 경우 메인 웹 사이트를 새로운 탭에서 열어주는 로고 링크가 필요하지 않을 수도 있습니다.

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

docusaurus.config.js
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 설정에서 메뉴바에 아이템을 추가할 수 있습니다.

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

docusaurus.config.js
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를 사용할 수 있습니다. activeBaseRegexactiveBasePath보다 유연한 대안이며 우선적으로 적용됩니다. 도큐사우루스에서는 현재 URL에 정규식으로 적용해 구문 분석을 처리합니다.

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

메뉴바 드롭다운#

메뉴바 아이템은 items 설정 시 드롭다운 아이템으로 적용할 수 있습니다.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    navbar: {      items: [        {          label: 'Community',          position: 'left', // 또는 'right'          items: [            {              label: 'Facebook',              href: '...',            },            {              label: 'GitHub',              href: '...',            },            // ... 드롭다운 목록에 적용할 다른 아이템 설정          ],        },      ],    },    // ...  },};

메뉴바 문서 링크#

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'doc',          docId: 'introduction',
          //// 옵션          position: 'left',          label: 'Docs',          activeSidebarClassName: 'navbar__link--active',          docsPluginId: 'default',        },      ],    },  },};

메뉴바 문서 버전 드롭다운#

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

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersionDropdown',
          //// 옵션          position: 'left',          // 드롭다운 아이템 목록 시작 또는 끝에 추가할 아이템을 설정합니다.          dropdownItemsBefore: [],          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],          // 문서 탐색 시에는 링크 활성화 클래스를 추가하지 못하도록 설정합니다.          dropdownActiveClassDisabled: true,          docsPluginId: 'default',        },      ],    },  },};

메뉴바 문서 버전#

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'docsVersion',
          //// 옵션          position: 'left',          to: '/path', // 기본값은 활성화된 최신 버전 링크          label: 'label', // 기본값은 활성화된 최신 버전 라벨          docsPluginId: 'default',        },      ],    },  },};

메뉴바 로케일 드롭다운#

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

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

docusaurus.config.js
module.exports = {  themeConfig: {    navbar: {      items: [        {          type: 'localeDropdown',
          //// 옵션          position: 'left',          // 드롭다운 아이템 목록 시작 또는 끝에 추가할 아이템을 설정합니다.          dropdownItemsBefore: [],          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를 사용해 코드 블록 구문 강조를 처리합니다.

테마#

기본적으로 구문 강조 테마로 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
  // ...  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 설정에서 바닥글에 링크를 추가할 수 있습니다.

docusaurus.config.js
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>              `,          },        ],      },    ],  },};