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

docusaurus.config.js

개요

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

필수 입력 항목

title

  • Type: string

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

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

url

  • Type: string

웹 사이트의 URL을 설정합니다. 이 설정은 최상위 호스트 이름으로 처리되기도 합니다. 예를 들어 https://facebook.github.iohttps://facebook.github.io/metro/의 URL이 되고 https://docusaurus.iohttps://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`
};
  • Type: 'ignore' | 'log' | 'warn' | 'error' | 'throw'

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

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

note

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

  • 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

staticDirectories

An array of paths, relative to the site's directory or absolute. Files under these paths will be copied to the build output as-is.

  • Type: string[]

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

docusaurus.config.js
module.exports = {
staticDirectories: ['static'],
};

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 코드가 필요합니다.

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