본문으로 건너뛰기
버전: Canary 🚧

설정

정보

Check the docusaurus.config.js API reference for an exhaustive list of options.

도큐사우루스는 자체적인 설정 환경을 가지고 있습니다. 여러분의 각 사이트에서 사용할 정보는 한 곳에 모아 놓는 것을 권장합니다. 그렇게 하면 우리는 설정 파일의 필드를 보호하고 각 사이트에서 데이터 객체에 접근할 수 있도록 허용해줄 수 있습니다.

적절하게 구성된 docusaurus.config.js 파일은 여러분 뿐 아니라 협업자, 오픈소스 기여자들이 문서 작성에 집중할 수 있도록 도와줍니다. 물론 필요한 경우 개별 설정을 변경할 수 있습니다.

Syntax to declare docusaurus.config.js​

The docusaurus.config.js file is run in Node.js and should export either:

  • a config object
  • a function that creates the config object
정보

The docusaurus.config.js file supports:

Constraints:

  • Required: use export default /* your config*/ (or module.exports to export your Docusaurus config
  • Optional: use import Lib from 'lib' (or require('lib')) to import Node.js packages

Docusaurus gives us the ability to declare its configuration in various equivalent ways, and all the following config examples lead to the exact same result:

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.js
module.exports = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};
docusaurus.config.ts
import type {Config} from '@docusaurus/types';

export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
} satisfies Config;
docusaurus.config.js
const config = {
  title: 'Docusaurus',
  url: 'https://docusaurus.io',
  // your site config ...
};

export default config;
docusaurus.config.js
export default function configCreator() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // your site config ...
  };
}
Using ESM-only packages

Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:

docusaurus.config.js
export default async function createConfigAsync() {
  // Use a dynamic import instead of require('esm-lib')
  const lib = await import('lib');

  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.io',
    // rest of your site config...
  };
}

docusaurus.config.js 파일에서 무엇을 설정하나요?​

사이트의 내용은 직접 작성해야 하지만 docusaurus.config.js 파일을 처음부터 새로 작성할 필요는 없습니다. 모든 템플릿은 공통으로 사용하는 옵션에 대한 기본값을 포함하는 docusaurus.config.js 파일을 함께 제공합니다.

하지만 설정 항목이 어떤 식으로 설계됐고 반영되고 있는지 알아야 하는 경우 필요한 유용한 정보를 정리했습니다.

도큐사우루스에서 사용하는 각 설정은 아래와 같이 구분할 수 있습니다.

사이트 메타데이터​

사이트 메타데이터는 title, url, baseUrl, favicon 같이 사이트 전체에서 필수로 사용하는 메타데이터를 포함합니다.

메타데이터는 사이트 제목, 브라우저 탭 아이콘, 소셜 공유(페이스북, 트위터)를 위한 정보로 사용하거나 사이트에서 사용할 파일에 대한 정확한 경로를 생성하기 위해 사용합니다.

배포 설정​

projectName이나 organizationName 배포 설정 그리고 deploymentBranch과 같은 추가적인 배포 설정은 deploy 명령으로 사이트를 배포할 때 사용됩니다.

배포 설정 시에는 배포 가이드를 먼저 참고하기를 권장합니다.

테마, 플러그인, 프리셋 설정​

여러분의 사이트에서 themes, plugins, presets 필드 항목에 설정한 themes, plugins, presets 목록은 모두 다를 수 있습니다. 대부분은 npm 패키지로 제공되는 것들입니다.

docusaurus.config.js
export default {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};
팁

도큐사우루스는 모듈 약식 표기를 지원하므로 위의 구성을 다음과 같이 단순하게 처리할 수 있습니다.

docusaurus.config.js
export default {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

로컬 디렉터리에서 항목을 가져오게 할 수도 있습니다.

docusaurus.config.js
import path from 'path';

export default {
  // ...
  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

플러그인이나 테마 옵션을 설정할 때 이름을 바로 지정하지 않고 이름과 옵션 객체를 포함한 배열로 지정할 수도 있습니다.

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

플러그인이나 테마 옵션을 기본 제공되는 프리셋으로 지정하려면 presets 항목에 해당 옵션을 지정합니다. 예를 들어 아래 설정에서 docs에서는 @docusaurus/plugin-content-docs를 그리고 theme는 @docusaurus/theme-classic을 프리셋으로 사용합니다.

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};
팁

presets: [['classic', {...}]] 약식 표기는 잘 동작합니다.

테마, 플러그인, 프리셋에 대한 추가적인 내용은 플러그인 사용하기를 참조하세요.

사용자 지정 설정​

도큐사우루스는 docusaurus.config.js 파일 내에 알 수 없는 필드가 추가되지 않도록 보호합니다. 사용자 지정 필드는 customFields 안에 정의할 수 있습니다.

예:

docusaurus.config.js
export default {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

컴포넌트에서 설정 객체에 접근하기​

사이트의 모든 컴포넌트에서는 설정 객체를 사용할 수 있습니다. 여러분은 siteConfig라는 리액트 컨텍스트를 통해 설정 객체에 접근할 수 있습니다.

간단한 예를 살펴보면 아래와 같습니다.

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};
팁

클라이언트 쪽에서 해당 필드를 사용할 때 자신만의 JS 파일을 만들어서 ES6 모듈로 가져온다면 docusaurus.config.js 안에 추가할 필요는 없습니다.

사용자 지정 바벨 설정​

새로운 도큐사우루스 프로젝트를 만들면 자동으로 프로젝트 루트 경로에 babel.config.js 파일이 만들어집니다.

babel.config.js
export default {
  presets: ['@docusaurus/core/lib/babel/preset'],
};

대부분의 경우 기본 설정만으로 충분합니다. 바벨 구성을 사용자 지정하려는 경우(예: Flow 지원 추가) 파일을 직접 편집할 수 있습니다. 변경된 사항을 적용하려면 도큐사우루스 개발 서버를 다시 시작해야 합니다.