메인 컨텐츠로 이동
버전: 3.6.0

설정

정보

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

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

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.

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...
  };
}

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​

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
export default {
  // ...
  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
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',
  ],
};

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
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
        theme: {
          customCss: ['./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
export default {
  // ...
  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​

Docusaurus transpiles your site's source code using Babel by default. If you want to customize the Babel configuration, you can do so by creating a babel.config.js file in your project root.

To use the built-in preset as a base configuration, install the following package and use it

npm install --save @docusaurus/theme-live-codeblock

Then use the preset in your babel.config.js file:

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

Most of the time, the default preset configuration will work just fine. 바벨 구성을 사용자 지정하려는 경우(예: Flow 지원 추가) 파일을 직접 편집할 수 있습니다. 변경된 사항을 적용하려면 도큐사우루스 개발 서버를 다시 시작해야 합니다.