메인 컨텐츠로 이동
Version: 2.0.0-beta.4

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

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',        // React inline style object        // see 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',      },      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',      },      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=0.86, maximum-scale=3.0, minimum-scale=0.86">    <meta name="generator" content="Docusaurus v<%= it.version %>">    <%~ 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 %> itemscope="" itemtype="http://schema.org/Organization">    <%~ it.preBodyTags %>    <div id="__docusaurus">      <%~ it.appHtml %>    </div>    <div id="outside-docusaurus">      <span>Custom markup</span>    </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 코드가 필요합니다.

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