메인 컨텐츠로 이동
버전: 불안정 🚧

테마 설정

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

공통​

컬러 모드​

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

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
경고

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

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

메타 정보 이미지​

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

메타데이터​

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

알림표시줄​

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

설정할 수 있는 필드

옵션명타입기본값설명
idstring'announcement-bar'메시지를 식별하는 모든 값입니다.
contentstring''알리고자 하는 텍스트 콘텐츠입니다. HTML을 삽입할 수 있습니다.
backgroundColorstring'#fff'알림표시줄 영역 배경색입니다.
textColorstring'#000'알림메시지 텍스트 색상입니다.
isCloseablebooleantrue알림메시지를 'x' 버튼으로 닫을 수 있는지 여부

설정 예시:

docusaurus.config.js
export default {
  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,
    },
  },
};

플러그인​

Our main themes offer additional theme configuration options for Docusaurus core content plugins.

문서​

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      versionPersistence: 'localStorage',
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
  },
};

블로그​

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

설정할 수 있는 필드

옵션명타입기본값설명

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

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  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
export default {
  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
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

dropdown 유형의 메뉴바 아이템은 추가적으로 items 필드를 내부 배열 형태로 가질 수 있습니다.

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

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  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
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

문서 ID를 하드코딩하지 않고 주어진 사이드바의 첫 번째 문서 링크(문서 링크 또는 생성된 카테고리 인덱스)에 메뉴바 항목을 연결할 수 있습니다.

설정할 수 있는 필드

옵션명타입기본값설명
팁

사이드바가 자주 업데이트되고 순서가 안정적이지 않은 경우에 이 메뉴바 항목 타입을 사용하세요.

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

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

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

설정할 수 있는 필드

옵션명타입기본값설명

Types:

type DropdownVersion = {
  /** Allows you to provide a custom display label for each version. */
  label?: string;
};

type DropdownVersions = string[] | {[versionName: string]: DropdownVersion};

설정 예시:

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

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

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

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

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Help us translate',
            },
          ],
        },
      ],
    },
  },
};

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

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

옵션명타입기본값설명
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

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

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

메뉴바 자동 숨김​

사용자가 페이지 스크롤 다운을 시작하면 자동으로 메뉴바가 숨겨지고 스크롤을 올리면 다시 보여지는 UI 기능을 활성화할 수 있습니다.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

테마 전환 기능을 비활성화하지 않고도 메뉴바의 스타일을 따로 설정할 수 있습니다. 선택한 스타일은 선택한 테마와 상관없이 항상 적용됩니다.

현재 설정할 수 있는 스타일 옵션은 2가지입니다. dark, primary(--ifm-color-primary 색상에 따라) 인피마 문서에서 적용될 스타일을 확인해볼 수 있습니다.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

코드 블록​

도큐사우루스에서는 Prism React Renderer를 사용해 코드 블록 구문 강조를 처리합니다. 모든 설정은 prism 오브젝트에서 처리합니다.

설정할 수 있는 필드

옵션명타입기본값설명
themePrismThemepalenightlight-theme 코드 블록에서 사용할 Prism 테마입니다.
darkThemePrismThemepalenightdark-theme 코드 블록에서 사용할 Prism 테마입니다.
defaultLanguagestringundefinedThe default language to use for code blocks not declaring any explicit language.
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. You can specify a custom theme from the list of available themes. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};
참고

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

기본 언어​

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

설정 예시:

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

docusaurus.config.js
export default {
  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
export default {
  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: 'X',
            href: 'https://x.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
export default {
  footer: {
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'X',
        href: 'https://x.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
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

후크​

useColorMode​

색상 컨텍스트에 접근하기 위한 리액트 후크입니다. This context contains functions for selecting light/dark/system mode and exposes the current color mode and the choice from the user. The color mode values should not be used for dynamic content rendering (see below).

사용 예:

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

const MyColorModeButton = () => {
  const {
    colorMode, // the "effective" color mode, never null
    colorModeChoice, // the color mode chosen by the user, can be null
    setColorMode, // set the color mode chosen by the user
  } = useColorMode();

  return (
    <button
      onClick={() => {
        const nextColorMode = colorModeChoice === 'dark' ? 'light' : 'dark';
        setColorMode(nextColorMode);
      }}>
      Toggle color mode
    </button>
  );
};

Attributes:

  • colorMode: 'light' | 'dark': The effective color mode currently applied to the UI. It cannot be null.
  • colorModeChoice: 'light' | 'dark' | null: The color mode explicitly chosen by the user. It can be null if user has not made any choice yet, or if they reset their choice to the system/default value.
  • setColorMode(colorModeChoice: 'light' | 'dark' | null, options: {persist: boolean}): void: A function to call when the user explicitly chose a color mode. null permits to reset the choice to the system/default value. By default, the choice is persisted in localStorage and restored on page reload, but you can opt out with {persist: false}.
경고

Don't use colorMode and colorModeChoice while rendering React components. Doing so is likely to produce FOUC, layout shifts and React hydration mismatches if you use them to render JSX content dynamically.

However, these values are safe to use after React hydration, in useEffect and event listeners, like in the MyColorModeButton example above.

If you need to render content dynamically depending on the current theme, the only way to avoid FOUC, layout shifts and hydration mismatch is to rely on CSS selectors to render content dynamically, based on the html data attributes that we set before the page displays anything:

<html data-theme="<light | dark>" data-theme-choice="<light | dark | system>">
  <!-- content -->
</html>
[data-theme='light']
[data-theme='dark']

[data-theme-choice='light']
[data-theme-choice='dark']
[data-theme-choice='system']
Why are colorMode and colorModeChoice unsafe when rendering?

To understand the problem, you need to understand how React hydration works.

During the static site generation phase, Docusaurus doesn't know what the user color mode choice is, and useColorMode() returns the following static values:

  • colorMode = themeConfig.colorMode.defaultMode
  • colorModeChoice = null

During the very first React client-side render (the hydration), React must produce the exact same HTML markup, and will also use these static values.

The correct colorMode and colorModeChoice values will only be provided in the second React render.

Typically, the following component will lead to React hydration mismatches. The label may switch from light to dark while React hydrates, leading to a confusing user experience.

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

const DisplayCurrentColorMode = () => {
  const {colorMode} = useColorMode();
  return <span>{colorMode}</span>;
};
참고

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