본문으로 건너뛰기
버전: 2.1.0

테마 설정

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

공통​

컬러 모드​

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

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

설정할 수 있는 필드

옵션명타입기본값설명
defaultMode'light' | 'dark''light'사용자가 사이트를 처음 방문할 때 컬러 모드입니다.
disableSwitchbooleanfalse메뉴바에서 스위치를 숨깁니다. 하나의 컬러 모드만 지원하기 원하는 경우 유용합니다.
respectPrefersColorSchemebooleanfalse직접 설정한 defaultMode 대신 사용자 시스템 기본 설정을 사용해 prefers-color-scheme 미디어 쿼리를 사용할지 여부

설정 예시:

docusaurus.config.js
module.exports = {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
warning

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

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

메타 정보 이미지​

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

설정할 수 있는 필드

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

설정 예시:

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

메타데이터​

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

설정할 수 있는 필드

옵션명타입기본값설명
metadataMetadata[][]모든 필드는 <meta /> 태그로 직접 전달됩니다. 사용할 수 있는 필드는 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알림메시지를 'x' 버튼으로 닫을 수 있는지 여부

설정 예시:

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,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

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

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

설정할 수 있는 필드

옵션명타입기본값설명
노트

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

설정 예시:

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // "to" 또는 "href" 중 하나만 사용해야 합니다.
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // "label" 또는 "html" 중 하나만 사용해야 합니다.
          // html: '<b>Introduction</b>'
          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: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
module.exports = {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // 메뉴바 항목이 이 문서에 연결됩니다.
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

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

사용자는 같은 문서를 유지하면서 다른 버전으로 전환할 수 있습니다(버전 별 문서 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',
        },
      ],
    },
  },
};

해당 메뉴바 아이템 타입을 사용해 메뉴바 아이템 내부에 여러분만의 HTML 마크업을 렌더링할 수 있습니다.

옵션명타입기본값설명
docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
      ],
    },
  },
};

메뉴바 자동 숨김​

사용자가 페이지 스크롤 다운을 시작하면 자동으로 메뉴바가 숨겨지고 스크롤을 올리면 다시 보여지는 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 오브젝트에서 처리합니다.

설정할 수 있는 필드

옵션명타입기본값설명
themePrismThemepalenightlight-theme 코드 블록에서 사용할 Prism 테마입니다.
darkThemePrismThemepalenightdark-theme 코드 블록에서 사용할 Prism 테마입니다.
defaultLanguagestringundefined메뉴바에서 아이템이 표시되는 위치를 설정합니다.
magicCommentsMagicCommentConfig[]아래를 참조하세요.매직 주석 목록입니다.
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];

테마​

By default, we use Palenight as syntax highlighting theme. 사용할 수 있는 테마 목록에서 다른 테마를 선택할 수 있습니다. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

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

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

기본 언어​

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

설정 예시:

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

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

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

themeConfig.footer.links 설정에서 바닥글에 링크를 추가할 수 있습니다. 바닥글 구성에는 multi-column footers와simple footers 두 가지 유형이 있습니다.

다중 컬럼 바닥글 링크는 각 컬럼에 대한 title과 FooterItem 목록이 있습니다.

옵션명타입기본값설명

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

옵션명타입기본값설명

다중 컬럼 구성 예제입니다.

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" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

간단한 바닥글에는 행에 표시되는 FooterItem 목록이 있습니다.

간단한 구성 예제입니다.

docusaurus.config.js
module.exports = {
  footer: {
    links: [
      {
        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" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

목차​

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

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

설정 예시:

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

후크​

useColorMode​

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

사용 예:

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
노트

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

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

i18n​

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

번역 파일 위치​

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

파일 시스템 구조 예​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json