버전: 2.3.1

문서 멀티 인스턴스

@docusaurus/plugin-content-docs 플러그인은 multi-instance을 지원할 수 있습니다.

노트

이 기능은 버전이 지정된 문서 사용 시에만 활용할 수 있습니다. 이 페이지를 읽기 전에 문서 버전에 대한 내용을 먼저 확인하기를 권장합니다. 여러 개의 사이트바가 필요하다면 하나의 플러그인 내에서 처리할 수 있습니다.

이렇게 사용합니다

도큐사우루스 사이트에서 2개 이상의 다른 문서 세트를 처리하기 원하는 상황을 가정합니다.

각 문서 세트는 서로 다른 버전/릴리스 생명주기를 가지고 있을 겁니다.

모바일 SDK 문서

여러 운영체제를 지원하는 모바일 SDK에 대한 2개의 문서를 가지고 있다고 가정합니다.

안드로이드 SDK 문서 (v1.0, v1.1)
iOS SDK 문서 (v1.0, v2.0)

이런 경우 모바일 SDK 문서에 따라 각각의 문서 플러그인 인스턴스를 사용할 수 있습니다.

warning

각각의 문서 인스턴스가 너무 크다면 도큐사우루스 사이트를 2개로 나누는 것이 더 좋습니다.

누군가 iOS 문서를 편집했을 때 변경되지 않는 안드로이드 문서까지 포함해 다시 빌드하는 것이 유용한지를 검토해야 합니다.

버전 지정이 된 문서와 그렇지 않은 문서

일부 문서는 버전을 지정하지만 다른 문서는 버전과 상관없이 "모든 버전에서" 사용하길 원할 수 있습니다.

도큐사우루스 웹사이트에서는 아래와 같은 패턴을 사용하고 있습니다.

/docs/* 아래 문서는 버전 지정이 된 문서입니다.
/community/* 아래 문서는 버전 지정을 하지 않았습니다.

설치하기

여러분이 아래와 같은 2가지 형태의 문서를 작성한다고 가정해보죠.

Product: 제품에 대한 문서로 몇 가지 버전을 가집니다.
Community: 제품 관련 커뮤니티에 대한 문서로 버전을 지정하지 않습니다.

이런 경우 사이트 설정 시 같은 플러그인을 두 번 사용해야 합니다.

warning

@docusaurus/preset-classic에는 문서 플러그인 인스턴스를 이미 포함하고 있습니다!

프리셋을 사용하는 경우에는

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // id: 'product', // omitted => default instance
          path: 'product',
          routeBasePath: 'product',
          sidebarPath: require.resolve('./sidebarsProduct.js'),
          // ... other options
        },
      },
    ],
  ],
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: require.resolve('./sidebarsCommunity.js'),
        // ... other options
      },
    ],
  ],
};

프리셋을 사용하지 않는 경우에는

docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // id: 'product', // omitted => default instance
        path: 'product',
        routeBasePath: 'product',
        sidebarPath: require.resolve('./sidebarsProduct.js'),
        // ... other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'community',
        path: 'community',
        routeBasePath: 'community',
        sidebarPath: require.resolve('./sidebarsCommunity.js'),
        // ... other options
      },
    ],
  ],
};

플러그인 인스턴스에 유일한 id 속성을 설정하는 것을 잊지 마세요.

노트

여기에서는 product 인스턴스를 가장 중요하다고 가정하고 "default" 인스턴스로 설정하기 위해 ID 속성값을 지정하지 않았습니다.

버전 지정된 문서의 경로

각 플러그인 인스턴스는 다른 폴더에 버전이 지정된 문서를 저장합니다.

플러그인 기본 인스턴스는 아래 경로에 저장됩니다.

website/versions.json
website/versioned_docs
website/versioned_sidebars

다른 플러그인 인스턴스(id 속성을 지정한)는 아래 경로에 저장됩니다.

website/[pluginId]_versions.json
website/[pluginId]_versioned_docs
website/[pluginId]_versioned_sidebars

팁

문서 플러그인 기본 인스턴스의 id 속성값(default)은 생략할 수 있습니다.

이렇게 하면 인스턴스 경로는 간단해지고 단일 인스턴스 설정에 대한 하위 호환성도 유지됩니다.

새로운 버전 태그 추가하기

각 플러그인 인스턴스에 새로운 버전 태그를 추가하기 위한 CLI 명령을 사용할 수 있습니다. CLI 옵션은 아래 명령으로 확인할 수 있습니다.

npm
Yarn
pnpm

npm run docusaurus -- --help

yarn docusaurus --help

pnpm run docusaurus -- --help

product/default 문서 플러그인 인스턴스에 버전을 지정하려면 아래와 같이 실행합니다.

npm
Yarn
pnpm

npm run docusaurus docs:version 1.0.0

yarn docusaurus docs:version 1.0.0

pnpm run docusaurus docs:version 1.0.0

community 문서 플러그인 인스턴스에 버전을 지정하려면 아래와 같이 실행합니다.

npm
Yarn
pnpm

npm run docusaurus docs:version:community 1.0.0

yarn docusaurus docs:version:community 1.0.0

pnpm run docusaurus docs:version:community 1.0.0

각 문서와 연결되는 테마 내비게이션 바 아이템을 docsPluginId 속성에서 설정할 수 있습니다.

예를 들어 각 모바일 SDK(iOS와 안드로이드)에 대한 하나의 버전을 선택하는 드롭다운 목록을 표시하고 싶다면 아래와 같이 설정합니다.

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'ios',
        },
        {
          type: 'docsVersionDropdown',
          docsPluginId: 'android',
        },
      ],
    },
  },
};

문서 멀티 인스턴스

이렇게 사용합니다​

모바일 SDK 문서​

버전 지정이 된 문서와 그렇지 않은 문서​

설치하기​

버전 지정된 문서의 경로​

새로운 버전 태그 추가하기​

문서 내비게이션 바 아이템​