테마 설정

이 설정은 모든 주요 테마에 적용됩니다.

공통

컬러 모드

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

colorMode 객체에서 색상 모드 지원을 설정할 수 있습니다.

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};

경고

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

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

메타 정보 이미지

메타 태그, 특히 og:image와 twitter:image에 사용할 기본 이미지를 설정할 수 있습니다.

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js

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

메타데이터

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js

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

알림표시줄

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

설정할 수 있는 필드

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

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        '문서를 개편하려고 합니다. <a target="_blank" rel="noopener noreferrer" href="#">설문조사</a>에 참여해 주세요',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

플러그인

도큐사우루스의 주요 테마는 도큐사우루스 핵심 콘텐츠 플러그인을 위한 추가 테마 설정 옵션을 제공합니다.

문서

옵션명	타입	기본값	설명
versionPersistence	'localStorage' | 'none'	undefined	선호하는 문서 버전을 브라우저에 유지하는 방식을 정의합니다.
sidebar.hideable	boolean	false	사이드바 아래쪽에 숨기기 버튼을 표시합니다.
sidebar.autoCollapseCategories	boolean	false	이동한 카테고리와 같은 수준에 있는 다른 카테고리를 모두 자동으로 접습니다.

설정 예시:

docusaurus.config.js

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

블로그

옵션명	타입	기본값	설명
sidebar.groupByYear	boolean	true	사이드바의 블로그 게시물을 연도별로 묶습니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

메뉴바

설정할 수 있는 필드

옵션명	타입	기본값	설명
title	string	undefined	메뉴바 제목
logo	아래 내용 참고	undefined	로고 오브젝트 사용자 지정
items	NavbarItem[]	[]	메뉴바 아이템 목록입니다. 상세한 내용은 아래 내용을 참고하세요.
hideOnScroll	boolean	false	사용자가 아래로 스크롤할 때 메뉴바를 숨길지 여부입니다.
style	'primary' | 'dark'	theme와 같음	어두운/밝은 테마 설정을 무시하고 메뉴바 스타일을 설정합니다.

메뉴바 로고

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

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

설정할 수 있는 필드

옵션명	타입	기본값	설명
alt	string	undefined	로고 이미지의 Alt 태그입니다.
src	string	필수	로고 이미지의 URL입니다. 기본적으로 기본 URL이 추가됩니다.
srcDark	string	logo.src	어두운 모드에서 사용할 대체 이미지 URL입니다.
href	string	siteConfig.baseUrl	로고 클릭 시 이동할 링크입니다.
width	string | number	undefined	width 속성을 지정합니다.
height	string | number	undefined	height 속성을 지정합니다.
target	string	href를 기준으로 계산됩니다(외부 링크는 새 탭에서, 나머지는 현재 탭에서 열립니다).	링크의 target 속성입니다. 링크를 새 탭이나 현재 탭 등 어디에서 열지 제어합니다.
className	string	undefined	이미지에 적용된 CSS 클래스
style	object	undefined	CSS 인라인 스타일 오브젝트. 리액트/JSX에서는 카멜표기법을 선호합니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      title: '사이트 제목',
      logo: {
        alt: '사이트 로고',
        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: '문서',
        },
        {to: 'blog', label: '블로그', 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 저장소',
        },
      ],
    },
  },
};

항목은 type 필드에 따라 다르게 동작할 수 있습니다. 사용할 수 있는 모든 유형의 메뉴바 아이템을 아래에 소개합니다.

메뉴바 링크

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

리액트 라우터는 링크에 활성 링크 스타일을 자동으로 적용하지만, 예외적인 경우에는 activeBasePath를 사용할 수 있습니다. 같은 사이드바 아래에 문서 폴더가 여러 개 있는 경우처럼 여러 경로에서 링크가 활성 상태여야 한다면 activeBaseRegex를 사용할 수 있습니다. activeBaseRegex는 activeBasePath보다 유연한 대안이며 우선 적용됩니다. 도큐사우루스는 이를 정규식으로 파싱하여 현재 URL과 일치하는지 검사합니다.

외부로 연결되는 링크에는 target="_blank" rel="noopener noreferrer" 속성이 자동으로 추가됩니다.

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'default'	선택사항	항목 유형을 링크로 설정합니다.
label	string	필수	아이템을 표시하는 이름입니다.
html	string	선택사항	label과 같지만 텍스트 콘텐츠 대신 순수 HTML을 렌더링합니다.
to	string	필수	웹 사이트 내에서 탐색을 위해 사용하는 클라이언트 라우팅입니다. 해당 값 앞에 baseUrl이 자동으로 추가됩니다.
href	string	필수	웹 사이트 외부 탐색을 위해 사용하는 전체 페이지 탐색입니다. to와 href 중 하나만 사용해야 합니다.
prependBaseUrlToHref	boolean	false	href 값 앞에 baseUrl을 추가합니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
activeBasePath	string	to / href	해당 경로로 시작하는 모든 경로에 활성화된 클래스 스타일을 적용합니다. 일반적인 경우는 필요하지 않습니다.
activeBaseRegex	string	undefined	필요한 경우 activeBasePath 대신 사용할 수 있습니다.
className	string	''	사용자 지정 CSS 클래스(특정 아이템 스타일 처리)

참고

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

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // "to"와 "href" 중 하나만 사용해야 합니다
          // href: 'https://www.facebook.com',
          label: '소개',
          // "label"과 "html" 중 하나만 사용해야 합니다
          // html: '<b>소개</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

메뉴바 드롭다운

dropdown 유형의 내비게이션 바 항목에는 내비게이션 바 항목의 내부 배열인 items 필드가 추가로 있습니다.

내비게이션 바 드롭다운 항목에는 다음과 같은 "링크형" 항목 유형만 사용할 수 있습니다:

• 내비게이션 바 링크
• 내비게이션 바 문서 링크
• 내비게이션 바 문서 버전
• 내비게이션 바 문서 사이드바
• 사용자 정의 HTML 내비게이션 바

드롭다운의 기본 항목도 클릭 가능한 링크이므로 일반 내비게이션 바 링크의 모든 props를 받을 수 있습니다.

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'dropdown'	선택사항	항목 유형을 드롭다운으로 설정합니다.
label	string	필수	아이템을 표시하는 이름입니다.
items	LinkLikeItem[]	필수	드롭다운에 포함될 아이템입니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: '커뮤니티',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: '소셜',
              docId: 'social',
            },
            // ... 추가 항목
          ],
        },
      ],
    },
  },
};

메뉴바 문서 링크

특정 문서에 연결하려면 이 특별한 내비게이션 바 항목 유형을 사용하세요. 지정한 docId의 문서로 연결되는 링크를 렌더링합니다. 같은 사이드바에 속한 문서를 탐색하는 동안에는 navbar__link--active 클래스가 적용됩니다.

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'doc'	필수	항목 유형을 문서 링크로 설정합니다.
docId	string	필수	아이템에서 링크로 연결되는 문서의 ID입니다.
label	string	docId	아이템을 표시하는 이름입니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
docsPluginId	string	'default'	문서가 속한 문서 플러그인 ID입니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: '문서',
        },
      ],
    },
  },
};

사이드바에 연결된 메뉴바

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

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'docSidebar'	필수	메뉴바 아이템의 유형을 사이드바 첫 번째 문서로 설정합니다.
sidebarId	string	필수	아이템에서 링크로 연결되는 사이드바 ID입니다.
label	string	첫 번째 문서 링크의 사이드바 라벨	아이템을 표시하는 이름입니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
docsPluginId	string	'default'	사이드바가 속한 문서 플러그인 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', // 내비게이션 바 항목이 이 문서에 연결됩니다
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

메뉴바 문서 버전 드롭다운

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

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

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'docsVersionDropdown'	필수	항목 유형을 문서 버전 드롭다운으로 설정합니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
dropdownItemsBefore	LinkLikeItem[]	[]	드롭다운 시작 부분에 드롭다운 아이템을 추가합니다.
dropdownItemsAfter	LinkLikeItem[]	[]	드롭다운 끝 부분에 드롭다운 아이템을 추가합니다.
docsPluginId	string	'default'	문서 버전이 속한 문서 플러그인 ID입니다.
dropdownActiveClassDisabled	boolean	false	문서를 탐색할 때 링크 활성 클래스를 추가하지 않습니다.
versions	DropdownVersions	undefined	드롭다운에 포함할 버전 목록을 직접 지정합니다. 자세한 내용은 버전 관리 가이드를 참고하세요.

유형:

type DropdownVersion = {
  /** 각 버전의 표시 레이블을 직접 지정할 수 있습니다. */
  label?: string;
};

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

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: '모든 버전'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

메뉴바 문서 버전

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

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'docsVersion'	필수	항목 유형을 문서 버전 링크로 설정합니다.
label	string	활성화/최신 버전 라벨	아이템을 표시하는 이름입니다.
to	string	활성화/최신 버전	아이템이 가리키는 내부 링크입니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
docsPluginId	string	'default'	문서 버전이 속한 문서 플러그인 ID입니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: '레이블',
        },
      ],
    },
  },
};

메뉴바 로케일 드롭다운

i18n 기능을 사용하면 이 특별한 내비게이션 바 항목 유형이 사이트에서 사용 가능한 모든 로케일을 포함하는 드롭다운을 렌더링합니다.

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

설정할 수 있는 필드

옵션명	타입	기본값	설명
type	'localeDropdown'	필수	항목 유형을 로케일 드롭다운으로 설정합니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
dropdownItemsBefore	LinkLikeItem[]	[]	드롭다운 시작 부분에 드롭다운 아이템을 추가합니다.
dropdownItemsAfter	LinkLikeItem[]	[]	드롭다운 끝 부분에 드롭다운 아이템을 추가합니다.
queryString	string	undefined	URL에 추가할 쿼리 문자열입니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: '번역에 참여해 주세요',
            },
          ],
        },
      ],
    },
  },
};

메뉴바 검색

검색을 사용하면 검색 창은 내비게이션 바의 맨 오른쪽에 표시됩니다.

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

옵션명	타입	기본값	설명
type	'search'	필수	항목 유형을 검색바로 설정합니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
className	string	/	메뉴바 아이템을 위한 사용자 지정 CSS 클래스

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

메뉴바 사용자 지정 HTML

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

옵션명	타입	기본값	설명
type	'html'	필수	항목 유형을 HTML 요소로 설정합니다.
position	'left' | 'right'	'left'	메뉴바에서 아이템이 표시되는 위치를 설정합니다.
className	string	''	메뉴바 아이템을 위한 사용자 지정 CSS 클래스
value	string	''	메뉴바 아이템 내에서 렌더링할 사용자 지정 HTML입니다.

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>의견 보내기</button>',
        },
      ],
    },
  },
};

메뉴바 자동 숨김

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

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

메뉴바 스타일

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

현재 사용할 수 있는 스타일 옵션은 dark와 primary(--ifm-color-primary 색상 기반) 두 가지입니다. Infima 문서에서 스타일 미리보기를 확인할 수 있습니다.

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

코드 블록

도큐사우루스는 Prism React Renderer를 사용해 코드 블록을 강조 표시합니다. 모든 설정은 prism 객체 안에 있습니다.

설정할 수 있는 필드

옵션명	타입	기본값	설명
theme	PrismTheme	palenight	light-theme 코드 블록에서 사용할 Prism 테마입니다.
darkTheme	PrismTheme	palenight	dark-theme 코드 블록에서 사용할 Prism 테마입니다.
defaultLanguage	string	undefined	언어를 명시적으로 선언하지 않은 코드 블록에 사용할 기본 언어입니다.
magicComments	MagicCommentConfig[]	아래 내용 참고	매직 주석 목록입니다.

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

테마

기본적으로 구문 강조 테마는 Palenight를 사용합니다. 사용 가능한 테마 목록에서 원하는 테마를 지정할 수 있습니다. 어두운 모드를 사이트에서 사용할 때는 다른 구문 강조 테마를 사용하도록 설정할 수도 있습니다.

설정 예시:

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를 통해 푸터에 로고와 저작권 문구를 추가할 수 있습니다. 로고는 정적 파일 폴더에 넣을 수 있습니다. 로고 URL은 메뉴바 로고와 같은 방식으로 처리됩니다.

설정할 수 있는 필드

옵션명	타입	기본값	설명
logo	Logo	undefined	로고 오브젝트 사용자 지정 자세한 내용은 내비게이션 바 로고를 참고하세요.
copyright	string	undefined	하단에 표시되는 저작권 문구 작성 시 사용자 지정 HTML도 사용할 수 있습니다.
style	'dark' | 'light'	'light'	바닥글 컴포넌트의 색상 테마입니다.
links	(Column | FooterLink)[]	[]	표시할 링크 그룹입니다.

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta 오픈 소스 로고',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. 도큐사우루스로 제작되었습니다.`,
    },
  },
};

바닥글 링크

themeConfig.footer.links를 통해 푸터에 링크를 추가할 수 있습니다. 푸터 설정에는 여러 열 푸터와 간단한 푸터 두 가지 유형이 있습니다.

여러 열 푸터의 링크에는 각 열마다 title과 FooterItem 목록이 있습니다.

옵션명	타입	기본값	설명
title	string	undefined	링크 섹션 라벨입니다.
items	FooterItem[]	[]	섹션 링크입니다.

각 FooterItem에서 사용할 수 있는 필드:

옵션명	타입	기본값	설명
label	string	필수	링크에 대해 표시할 텍스트입니다.
to	string	필수	웹 사이트 내에서 탐색을 위해 사용하는 클라이언트 라우팅입니다. 해당 값 앞에 baseUrl이 자동으로 추가됩니다.
href	string	필수	웹 사이트 외부 탐색을 위해 사용하는 전체 페이지 탐색입니다. to와 href 중 하나만 사용해야 합니다.
html	string	undefined	단순 링크 대신 HTML 패스스루(pass-through)를 렌더링합니다. html을 사용하는 경우 다른 옵션을 제공하면 안 됩니다.

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

docusaurus.config.js

export default {
  footer: {
    links: [
      {
        title: '문서',
        items: [
          {
            label: '스타일 가이드',
            to: 'docs/',
          },
          {
            label: '두 번째 문서',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: '커뮤니티',
        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="Netlify로 배포">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="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="Netlify로 배포">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Netlify로 배포" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

목차

themeConfig.tableOfContents를 통해 기본 목차를 조정할 수 있습니다.

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

설정 예시:

docusaurus.config.js

export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

후크

useColorMode

색상 컨텍스트에 접근하기 위한 리액트 후크입니다. 이 컨텍스트에는 라이트/다크/시스템 모드를 선택하는 함수가 포함되며, 현재 색상 모드와 사용자가 선택한 값을 제공합니다. 색상 모드 값은 동적 콘텐츠 렌더링에 사용하면 안 됩니다(아래 내용 참고).

사용 예:

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

const MyColorModeButton = () => {
  const {
    colorMode, // 실제 적용된 색상 모드이며 null이 될 수 없습니다
    colorModeChoice, // 사용자가 선택한 색상 모드이며 null일 수 있습니다
    setColorMode, // 사용자가 선택한 색상 모드 설정
  } = useColorMode();

  return (
    <button
      onClick={() => {
        const nextColorMode = colorModeChoice === 'dark' ? 'light' : 'dark';
        setColorMode(nextColorMode);
      }}>
      색상 모드 전환
    </button>
  );
};

속성:

• colorMode: 'light' | 'dark': 현재 UI에 적용된 유효 색상 모드입니다. null일 수 없습니다.
• colorModeChoice: 'light' | 'dark' | null: 사용자가 명시적으로 선택한 색상 모드입니다. 사용자가 아직 선택하지 않았거나 선택을 시스템/기본값으로 초기화했다면 null일 수 있습니다.
• setColorMode(colorModeChoice: 'light' | 'dark' | null, options: {persist: boolean}): void: 사용자가 색상 모드를 명시적으로 선택했을 때 호출하는 함수입니다. null을 사용하면 선택을 시스템/기본값으로 초기화할 수 있습니다. 기본적으로 선택은 localStorage에 저장되어 페이지를 다시 로드할 때 복원되지만, {persist: false}로 이 동작을 해제할 수 있습니다.

경고

리액트 컴포넌트를 렌더링하는 동안 colorMode와 colorModeChoice를 사용하지 마세요. 이 값을 사용해 JSX 콘텐츠를 동적으로 렌더링하면 FOUC, 레이아웃 이동, 리액트 하이드레이션 불일치가 발생할 가능성이 높습니다.

하지만 위의 MyColorModeButton 예제처럼 리액트 하이드레이션 이후에는 useEffect와 이벤트 리스너에서 이 값을 안전하게 사용할 수 있습니다.

현재 테마에 따라 콘텐츠를 동적으로 렌더링하면서 FOUC, 레이아웃 이동, 하이드레이션 불일치를 방지하려면 CSS 선택자를 사용해야 합니다. 페이지에 아무것도 표시되기 전에 설정하는 다음 html 데이터 속성을 기준으로 콘텐츠를 렌더링하세요:

<html data-theme="<light | dark>" data-theme-choice="<light | dark | system>">
  <!-- 콘텐츠 -->
</html>

[data-theme='light']
[data-theme='dark']

[data-theme-choice='light']
[data-theme-choice='dark']
[data-theme-choice='system']

렌더링 시 colorMode와 colorModeChoice가 안전하지 않은 이유는 무엇인가요?

이 문제를 이해하려면 리액트 하이드레이션의 동작 방식을 이해해야 합니다.

정적 사이트 생성 단계에서는 도큐사우루스가 사용자의 색상 모드 선택을 알 수 없으므로 useColorMode()는 다음 정적 값을 반환합니다:

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

리액트의 첫 클라이언트 측 렌더링(하이드레이션)에서는 정확히 같은 HTML 마크업을 생성해야 하므로 이 정적 값을 그대로 사용합니다.

올바른 colorMode와 colorModeChoice 값은 리액트의 두 번째 렌더링에서야 제공됩니다.

예를 들어 다음 컴포넌트는 리액트 하이드레이션 불일치를 일으킵니다. 리액트가 하이드레이션하는 동안 레이블이 light에서 dark로 바뀌어 사용자에게 혼란을 줄 수 있습니다.

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 소개를 읽으세요.

번역 파일 위치

• 기본 경로: website/i18n/[locale]/docusaurus-theme-[themeName]
• 다중 인스턴스 경로: 해당 없음
• JSON 파일: docusaurus write-translations로 추출합니다
• 마크다운 파일: 해당 없음

파일 시스템 구조 예

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