문서 멀티 인스턴스
The @docusaurus/plugin-content-docs
plugin can support multi-instance.
This feature is only useful for versioned documentation. 이 페이지를 읽기 전에 문서 버전에 대한 내용을 먼저 확인하기를 권장합니다. If you just want multiple sidebars, you can do so within one plugin.
Use-cases
도큐사우루스 사이트에서 2개 이상의 다른 문서 세트를 처리하기 원하는 상황을 가정합니다.
각 문서 세트는 서로 다른 버전/릴리스 생명주기를 가지고 있을 겁니다.
Mobile SDKs documentation
여러 운영체제를 지원하는 모바일 SDK에 대한 2개의 문서를 가지고 있다고 가정합니다.
- Android SDK documentation (
v1.0
,v1.1
) - iOS SDK documentation (
v1.0
,v2.0
)
이런 경우 모바일 SDK 문서에 따라 각각의 문서 플러그인 인스턴스를 사용할 수 있습니다.
각각의 문서 인스턴스가 너무 크다면 도큐사우루스 사이트를 2개로 나누는 것이 더 좋습니다.
누군가 iOS 문서를 편집했을 때 변경되지 않는 안드로이드 문서까지 포함해 다시 빌드하는 것이 유용한지를 검토해야 합니다.
Versioned and unversioned doc
일부 문서는 버전을 지정하지만 다른 문서는 버전과 상관없이 "모든 버전에서" 사용하길 원할 수 있습니다.
도큐사우루스 웹사이트에서는 아래와 같은 패턴을 사용하고 있습니다.
- The /docs/* section is versioned
- The /community/* section is unversioned
Setup
여러분이 아래와 같은 2가지 형태의 문서를 작성한다고 가정해보죠.
- Product: 제품에 대한 문서로 몇 가지 버전을 가집니다.
- Community: 제품 관련 커뮤니티에 대한 문서로 버전을 지정하지 않습니다.
이런 경우 사이트 설정 시 같은 플러그인을 두 번 사용해야 합니다.
@docusaurus/preset-classic
already includes a docs plugin instance for you!
프리셋을 사용하는 경우에는
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
],
};
프리셋을 사용하지 않는 경우에는
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
// id: 'product', // omitted => default instance
path: 'product',
routeBasePath: 'product',
sidebarPath: './sidebarsProduct.js',
// ... other options
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'community',
path: 'community',
routeBasePath: 'community',
sidebarPath: './sidebarsCommunity.js',
// ... other options
},
],
],
};
Don't forget to assign a unique id
attribute to plugin instances.
We consider that the product
instance is the most important one, and make it the "default" instance by not assigning any ID.
Versioned paths
각 플러그인 인스턴스는 다른 폴더에 버전이 지정된 문서를 저장합니다.
플러그인 기본 인스턴스는 아래 경로에 저장됩니다.
website/versions.json
website/versioned_docs
website/versioned_sidebars
The other plugin instances (with an id
attribute) will use these paths:
website/[pluginId]_versions.json
website/[pluginId]_versioned_docs
website/[pluginId]_versioned_sidebars
You can omit the id
attribute (defaults to default
) for one of the docs plugin instances.
이렇게 하면 인스턴스 경로는 간단해지고 단일 인스턴스 설정에 대한 하위 호환성도 유지됩니다.
Tagging new versions
각 플러그인 인스턴스에 새로운 버전 태그를 추가하기 위한 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
Docs navbar items
Each docs-related theme navbar items take an optional docsPluginId
attribute.
예를 들어 각 모바일 SDK(iOS와 안드로이드)에 대한 하나의 버전을 선택하는 드롭다운 목록을 표시하고 싶다면 아래와 같이 설정합니다.
export default {
themeConfig: {
navbar: {
items: [
{
type: 'docsVersionDropdown',
docsPluginId: 'ios',
},
{
type: 'docsVersionDropdown',
docsPluginId: 'android',
},
],
},
},
};