메인 컨텐츠로 이동
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.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

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

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