Version: 2.0.0-beta.9

`docusaurus.config.js`

개요

docusaurus.config.js 파일에는 사이트에 필요한 설정을 담고 있습니다. 설정 파일은 사이트 루트 디렉터리에 있습니다.

필수 입력 항목

`title`

Type: string

웹 사이트 타이틀을 설정합니다.

docusaurus.config.js

module.exports = {
  title: 'Docusaurus',
};

`url`

Type: string

웹 사이트의 URL을 설정합니다. 이 설정은 최상위 호스트 이름으로 처리되기도 합니다. 예를 들어 https://facebook.github.io는 https://facebook.github.io/metro/의 URL이 되고 https://docusaurus.io는 https://docusaurus.io의 URL이 됩니다. baseUrl와 같이 사용되는 항목입니다.

docusaurus.config.js

module.exports = {
  url: 'https://docusaurus.io',
};

`baseUrl`

Type: string

사이트의 Base URL을 설정합니다. 이 설정은 호스트 이름 뒤의 경로로 처리되기도 합니다. 예를 들어 /metro/는 https://facebook.github.io/metro/의 baseUrl이 됩니다. 경로가 없는 URL이라면 baseUrl은 /을 설정해주어야 합니다. url과 같이 사용되는 항목입니다.

docusaurus.config.js

module.exports = {
  baseUrl: '/',
};

선택 입력 항목

`favicon`

Type: string | undefined

파비콘 경로를 설정합니다.

예를 들어 여러분의 파비콘 파일이 static/img/favicon.ico 경로에 있다면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  favicon: '/img/favicon.ico',
};

`trailingSlash`

Type: boolean | undefined

URL/링크 끝 부분에 트레일링 슬래시 사용 여부와 정적 HTML 파일 생성 방식을 정의합니다.

undefined (default): URL을 그대로 유지하고 합니다. /docs/myDoc.md 파일은 /docs/myDoc/index.html파일로 생성됩니다.
true: URL/링크에 트레일링 슬래시를 추가합니다. /docs/myDoc.md 파일은 /docs/myDoc/index.html파일로 생성됩니다.
false: URL/링크에서 트레일링 슬래시를 제거합니다. /docs/myDoc.md 파일은 /docs/myDoc.html파일로 생성됩니다.

tip

정적 호스팅 제공 업체에 따라 정적 파일은 다른 방식으로 제공합니다(이 동작 또한 변경될 수 있습니다).

적절한 설정 방법을 선택하기 위해 배포 가이드와 slorber/trailing-slash-guide를 참고하세요.

`i18n`

Type: Object

i18n 설정 오브젝트는 사이트 지역화를 위한 설정입니다.

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
      },
      fr: {
        label: 'Français',
        direction: 'ltr',
      },
    },
  },
};

label: 해당 로케일을 표시하는 문자열
direction: ltr (default) 또는 rtl (아랍어나 히브리어 같은 right-to-left 언어 사용 시)

`noIndex`

Type: boolean

이 옵션은 페이지에 <meta name="robots" content="noindex, nofollow"> 값을 추가해서 검색 엔진이 여러분의 사이트를 수집하지 않도록 합니다(moz.com 설명을 참고하세요).

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  noIndex: true, // Defaults to `false`
};

`onBrokenLinks`

Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

깨진 링크를 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.

기본적으로 깨진 링크가 배포되지 않도록 에러로 처리하지만 필요에 따라 수준을 조정할 수 있습니다.

note

링크의 깨짐 여부는 제품 빌드 시에만 확인할 수 있습니다 (docusaurus build).

`onBrokenMarkdownLinks`

Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

깨진 마크다운 링크를 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.

기본적으로 깨진 마크다운 링크가 확인할 수 있도록 경고를 출력하지만 필요에 따라 수준을 조정할 수 있습니다.

`onDuplicateRoutes`

Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

경로 중복을 발견했을 때 도큐사우루스에서 어떻게 처리할지 설정합니다.

기본적으로 yarn start 또는 yarn build 명령 실행 후에 경고를 출력합니다.

`tagline`

Type: string

웹 사이트를 설명하는 짧은 문구를 설정합니다.

docusaurus.config.js

module.exports = {
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

`organizationName`

Type: string

코드 저장소를 소유하고 있는 깃허브 사용자 또는 그룹 계정을 설정합니다. 배포 명령 실행 시 사용합니다.

docusaurus.config.js

module.exports = {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
};

`projectName`

Type: string

깃허브 저장소 이름을 설정합니다. 배포 명령 실행 시 사용합니다.

docusaurus.config.js

module.exports = {
  projectName: 'docusaurus',
};

`deploymentBranch`

Type: string

정적 파일을 배포할 브랜치 이름입니다. 배포 명령 실행 시 사용합니다.

docusaurus.config.js

module.exports = {
  deploymentBranch: 'gh-pages',
};

`githubHost`

Type: string

여러분의 서버 호스트 이름을 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다.

docusaurus.config.js

module.exports = {
  githubHost: 'github.com',
};

`githubPort`

Type: string

여러분의 서버에서 사용하는 포트를 설정합니다. 깃허브 엔터프라이즈를 사용하는 경우 필요한 항목입니다.

docusaurus.config.js

module.exports = {
  githubPort: '22',
};

`themeConfig`

Type: Object

사이트 메뉴바나 푸터 등에 사용자 지정 UI를 적용하기 위한 테마 설정 오브젝트를 설정합니다.

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  themeConfig: {
    hideableSidebar: false,
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
      switchConfig: {
        darkIcon: '🌙',
        lightIcon: '\u2600',
        // 리액트 인라인 스타일 오브젝트
        // https://reactjs.org/docs/dom-elements.html#style 를 참고하세요.
        darkIconStyle: {
          marginLeft: '2px',
        },
        lightIconStyle: {
          marginLeft: '1px',
        },
      },
    },
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        width: 32,
        height: 32,
      },
      items: [
        {
          to: 'docs/docusaurus.config.js',
          activeBasePath: 'docs',
          label: 'docusaurus.config.js',
          position: 'left',
        },
        // ... other links
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: 'docs/doc1',
            },
          ],
        },
        // ... other links
      ],
      logo: {
        alt: 'Facebook Open Source Logo',
        src: 'https://docusaurus.io/img/oss_logo.png',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
    },
  },
};

`plugins`

Type: any[]

docusaurus.config.js

module.exports = {
  plugins: [],
};

`themes`

Type: any[]

docusaurus.config.js

module.exports = {
  themes: [],
};

`presets`

Type: any[]

docusaurus.config.js

module.exports = {
  presets: [],
};

`customFields`

도큐사우루스는 docusaurus.config.js 파일 내에 알 수 없는 필드가 추가되지 않도록 보호합니다. 사용자 지정 필드를 추가하고 싶다면 customFields에 설정해주어야 합니다.

Type: Object

docusaurus.config.js

module.exports = {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

알 수 없는 필드 항목을 설정 파일에 추가한 경우 빌드 시 아래와 같은 에러가 발생합니다.

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

`scripts`

로드할 스크립트 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. <script> 태그는 HTML <head> 태그 안에 추가됩니다.

추가한 <script>는 렌더링 차단 리소스로 처리되며 필요한 경우 오브젝트에 async: true/defer: true 설정을 추가할 수 있습니다.

Type: (string | Object)[]

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  scripts: [
    // String format.
    'https://docusaurus.io/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

`clientModules`

사이트에 전역 오브젝트로 로드할 클라이언트 모듈 배열을 설정합니다.

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  clientModules: [
    require.resolve('./mySiteGlobalJs.js'),
    require.resolve('./mySiteGlobalCss.css'),
  ],
};

getClientModules()를 참고하세요.

`ssrTemplate`

애플리케이션 렌더링 시 사용할 수 있는 Eta 구문으로 작성된 HTML 템플릿입니다. body 태그나 추가적인 meta 태그를 설정하거나 viewport를 설정하기 위해 사용할 수 있습니다. 도큐사우루스는 올바르게 동작하기 위해 템플릿이 제대로 작성되었는지 확인합니다. 사용자 지정 템플릿을 작성한 경우에는 upstream 요구사항을 제대로 반영했는지 확인해주세요.

Type: string

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% if (it.noIndex) { %>
      <meta name="robots" content="noindex, nofollow" />
    <% } %>
    <%~ it.headTags %>
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus">
      <%~ it.appHtml %>
    </div>
    <% it.scripts.forEach((script) => { %>
      <script src="<%= it.baseUrl %><%= script %>"></script>
    <% }); %>
    <%~ it.postBodyTags %>
  </body>
</html>`,
};

`stylesheets`

로드할 CSS 소스의 배열을 설정합니다. 값은 문자열이거나 속성, 값 조합으로 구성된 오브젝트일 수 있습니다. <link> 태그는 HTML <head> 태그 안에 추가됩니다.

Type: (string | Object)[]

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  stylesheets: [
    // String format.
    'https://docusaurus.io/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};

`titleDelimiter`

Type: string

생성된 <title> 태그에서 구분자로 사용할 문자열을 설정합니다.

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  titleDelimiter: '🦖', // Defaults to `|`
};

`baseUrlIssueBanner`

Type: boolean

활성화 시 사이트에서 CSS 또는 자바스크립트 파일을 로드하지 못하면 배너를 표시합니다. 이런 문제는 사이트 설정 시 잘못된 baseUrl로 인해 자주 발생할 수 있습니다.

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js

module.exports = {
  baseUrlIssueBanner: true, // Defaults to `true`
};

baseUrlIssueBanner

caution

배너를 표시하기 위해 인라인 CSS/JS 코드가 필요합니다.

엄격한 콘텐츠 보안 정책을 가지고 있다면 해당 기능을 활성화하지 마세요.

개요​

필수 입력 항목​

title​

url​

baseUrl​

선택 입력 항목​

favicon​

trailingSlash​

tip

i18n​

noIndex​

onBrokenLinks​

note

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

customFields​

scripts​

clientModules​

ssrTemplate​

stylesheets​

titleDelimiter​

baseUrlIssueBanner​

caution

개요

필수 입력 항목

`title`

`url`

`baseUrl`

선택 입력 항목

`favicon`

`trailingSlash`

`i18n`

`noIndex`

`onBrokenLinks`

`onBrokenMarkdownLinks`

`onDuplicateRoutes`

`tagline`

`organizationName`

`projectName`

`deploymentBranch`

`githubHost`

`githubPort`

`themeConfig`

`plugins`

`themes`

`presets`

`customFields`

`scripts`

`clientModules`

`ssrTemplate`

`stylesheets`

`titleDelimiter`

`baseUrlIssueBanner`