설정

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

Keeping a well-maintained docusaurus.config.js helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site.

What goes into a docusaurus.config.js?

You should not have to write your docusaurus.config.js from scratch even if you are developing your site. All templates come with a docusaurus.config.js that includes defaults for the common options.

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

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

• Site metadata
• Deployment configurations
• Theme, plugin, and preset configurations
• Custom configurations

For exact reference to each of the configurable fields, you may refer to docusaurus.config.js API reference.

Site metadata

Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon.

They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, X) information or even to generate the correct path to serve your static files.

Deployment configurations

Deployment configurations such as projectName, organizationName, and optionally deploymentBranch are used when you deploy your site with the deploy command.

It is recommended to check the deployment docs for more information.

Theme, plugin, and preset configurations

List the themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. 대부분은 npm 패키지로 제공되는 것들입니다.

docusaurus.config.js

module.exports = {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};

팁

Docusaurus supports module shorthands, allowing you to simplify the above configuration as:

docusaurus.config.js

module.exports = {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

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

docusaurus.config.js

const path = require('path');

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

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

docusaurus.config.js

module.exports = {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

To specify options for a plugin or theme that is bundled in a preset, pass the options through the presets field. In this example, docs refers to @docusaurus/plugin-content-docs and theme refers to @docusaurus/theme-classic.

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

팁

The presets: [['classic', {...}]] shorthand works as well.

For further help configuring themes, plugins, and presets, see Using Plugins.

Custom configurations

Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields.

예:

docusaurus.config.js

module.exports = {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

Accessing configuration from components

사이트의 모든 컴포넌트에서는 설정 객체를 사용할 수 있습니다. And you may access them via React context as siteConfig.

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

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

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

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

팁

If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in docusaurus.config.js.

Customizing Babel Configuration

For new Docusaurus projects, we automatically generated a babel.config.js in the project root.

babel.config.js

module.exports = {
  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

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