메인 컨텐츠로 이동
버전: 2.x

테마 설정

This configuration applies to all main themes.

Common​

Color mode​

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

It is possible to customize the color mode support within the colorMode object.

설정할 수 있는 필드

옵션명타입기본값설명
defaultMode'light' | 'dark''light'사용자가 사이트를 처음 방문할 때 컬러 모드입니다.
disableSwitchbooleanfalse메뉴바에서 스위치를 숨깁니다. 하나의 컬러 모드만 지원하기 원하는 경우 유용합니다.
respectPrefersColorSchemebooleanfalseWhether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode.

설정 예시:

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

With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

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

Meta image​

You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

설정할 수 있는 필드

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

설정 예시:

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

Metadata​

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

설정할 수 있는 필드

옵션명타입기본값설명
metadataMetadata[][]Any field will be directly passed to the <meta /> tag. Possible fields include id, name, property, content, itemprop, etc.

설정 예시:

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

Announcement bar​

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

설정할 수 있는 필드

옵션명타입기본값설명
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,
    },
  },
};

설정할 수 있는 필드

옵션명타입기본값설명

The logo can be placed in static folder. 로고 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'},
      },
    },
  },
};

You can add items to the navbar via 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',
        },
      ],
    },
  },
};

The items can have different behaviors based on the type field. 사용할 수 있는 모든 유형의 메뉴바 아이템을 아래에 소개합니다.

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

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

설정할 수 있는 필드

옵션명타입기본값설명
참고

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

설정 예시:

docusaurus.config.js
module.exports = {
  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',
        },
      ],
    },
  },
};

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

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
          ],
        },
      ],
    },
  },
};

If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

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',
        },
      ],
    },
  },
};

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

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

설정할 수 있는 필드

옵션명타입기본값설명

설정 예시:

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',
            },
          ],
        },
      ],
    },
  },
};

If you use the search, the search bar will be the rightmost element in the navbar.

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

옵션명타입기본값설명
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>',
        },
      ],
    },
  },
};

Auto-hide sticky navbar​

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

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

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

Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock​

Docusaurus uses Prism React Renderer to highlight code blocks. All configuration are in the prism object.

설정할 수 있는 필드

옵션명타입기본값설명
themePrismThemepalenightlight-theme 코드 블록에서 사용할 Prism 테마입니다.
darkThemePrismThemepalenightdark-theme 코드 블록에서 사용할 Prism 테마입니다.
defaultLanguagestringundefined메뉴바에서 아이템이 표시되는 위치를 설정합니다.
magicCommentsMagicCommentConfig[]see belowThe list of magic comments.
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'},
  },
];

Theme​

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

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

마크다운 구문을 강조해야 하는 경우 어두운 모드 구문 강조 테마 사용 시 다른 배경색을 설정해야 할 수도 있습니다. Refer to the docs for guidance.

Default language​

3개의 억음부호(```) 뒤에 언어를 설정하지 않았을 때 코드 블록에서 기본으로 적용할 언어를 설정할 수 있습니다. Note that a valid language name must be passed.

설정 예시:

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

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. 로고 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.`,
    },
  },
};

You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

Multi-column footer links have a title and a list of FooterItems for each column.

옵션명타입기본값설명

Accepted fields of each 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>
              `,
          },
        ],
      },
    ],
  },
};

A simple footer just has a list of FooterItems displayed in a row.

간단한 구성 예제입니다.

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>
          `,
      },
    ],
  },
};

Table of Contents​

You can adjust the default table of contents via themeConfig.tableOfContents.

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

설정 예시:

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

Hooks​

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>;
};
참고

The component calling useColorMode must be a child of the Layout component.

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

i18n​

Read the i18n introduction first.

Translation files location​

  • Base path: website/i18n/[locale]/docusaurus-theme-[themeName]
  • Multi-instance path: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: N/A

Example file-system structure​

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