📦 plugin-content-docs

문서 만들기 기능을 제공하는 도큐사우루스의 기본 문서 플러그인입니다.

설치

npm

npm install --save @docusaurus/plugin-content-docs

Yarn

yarn add @docusaurus/plugin-content-docs

tip

@docusaurus/preset-classic을 설치한 경우에는 테마를 따로 설치할 필요는 없습니다. 아래와 같이 설정하는 대신 classic preset options에서 설정할 수 있습니다.

설정

docusaurus.config.js

module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        /**         * 사이트 디렉터리의 상대 경로로 파일 시스템의 데이터 경로를 설정합니다.         */        path: 'docs',        /**         * 여러분의 사이트를 편집하기 위한 Base url을 설정합니다.         * 도큐사우루스에서 "editUrl + relativeDocPath" 조합으로 최종 editUrl을 계산합니다.         * 값을 설정하지 않으면 편집 링크를 비활성화합니다.         */        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',        /**         * 필요에 따라 각 마크다운 파일의 editUrl을 직접 설정해줄 수 있습니다.         */        editUrl: function ({          locale,          version,          versionDocsDirPath,          docPath,          permalink,        }) {          return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;        },        /**         * 번역된 파일을 깃에 커밋하는 경우 유용한 설정입니다.         * 마크다운 파일을 현지화하게 되면 편집 URL은 현지화되지 않은 원본 파일 대신         * 현지화된 파일을 가리키게 됩니다.         * 참고: editUrl이 함수인 경우에 해당 옵션은 무시됩니다.         */        editLocalizedFiles: false,        /**         * 이전 버전에 대한 사용자의 풀 리퀘스트 요청을 막을 경우 유용합니다.         * 문서 버전이 올라간 경우 편집할 수 있는 url은 이전 버전 문서 대신         * 현재 버전 문서로 연결되도록 합니다.         * 참고: editUrl이 함수인 경우에 해당 옵션은 무시됩니다.         */        editCurrentVersion: false,        /**         * 여러분의 사이트 문서 디렉터리에 대한 URL 경로를 설정합니다.         * *절대* URL 끝에 슬래시를 붙이지 마세요.         * 참고: base 경로 없이 배포되는 문서는 `/`을 설정할 수도 있습니다.         */        routeBasePath: 'docs',        include: ['**/*.md', '**/*.mdx'], // Extensions to include.        /**         * 아래 설정한 파일은 라우트 처리를 하지 않습니다.         */        exclude: [          '**/_*.{js,jsx,ts,tsx,md,mdx}',          '**/_*/**',          '**/*.test.{js,jsx,ts,tsx}',          '**/__tests__/**',        ],        /**         * 마크다운 페이지 목록을 보여주기 위한 사이드바 구성 경로입니다.         */        sidebarPath: 'sidebars.js',        /**         * 모든 사이드바 카테고리는 접을 수 있는 상태가 기본값입니다.         * 카테고리 별로 옵션을 설정할 수 있습니다.         */        sidebarCollapsible: true,        /**         * 모든 사이드바 카테고리는 접혀져 있는 상태가 기본값입니다.         * 카테고리 별로 옵션을 설정할 수 있습니다.         */        sidebarCollapsed: false,        /**         * "autogenerated" 타입의 사이드바 아이템을 실제 사이드바 아이템(문서, 카테고리, 링크 등)으로         * 바꾸기 위해 사용하는 함수입니다.         */        sidebarItemsGenerator: async function ({          defaultSidebarItemsGenerator, // 도큐사우루스에서 사이드바를 만드는 기본 로직을 재사용하거나 향상시킬 때 유용합니다.          numberPrefixParser, // 플러그인을 위한 numberPrefixParser를 설정합니다.          item, // "autogenerated" 타입의 사이드바 아이템입니다.          version, // 현재 버전을 설정합니다.          docs, // 해당 버전의 모든 문서(필터링하지 않은)를 설정합니다.        }) {          // 사용자 지정 사이드바 슬라이스를 만들기 위해 주어진 데이터를 사용합니다.          return [            {type: 'doc', id: 'intro'},            {              type: 'category',              label: 'Tutorials',              items: [                {type: 'doc', id: 'tutorial1'},                {type: 'doc', id: 'tutorial2'},              ],            },          ];        },        /**         * 문서 플러그인은 "01-My Folder/02.My Doc.md"같은 숫자 형식의 접두사를 지원합니다.         * 번호 접두사는 자동으로 추출되어 자동 생성된 사이드바 아이템의 정렬 순서로 사용됩니다.         * 사용성을 위해 기본 문서의 id, 이름, 제목에서 숫자 접두사는 자동으로 제거됩니다.         * 구문 분석을 위한 로직에서 모든 사용 방식과 파일명 패턴을 허용하도록 설정할 수 있습니다.         * "false"를 설정하면 아무 동작 없이 문서를 건드리지 않은 상태로 유지합니다.         */        numberPrefixParser: function (filename) {          // 잠재적인 번호 접두사를 추출하기 위한 사용자 지정 로직을 구현합니다.          const numberPrefix = findNumberPrefix(filename);          // 접두사를 발견하면 수정된 파일명과 함께 반환합니다.          if (numberPrefix) {            return {              numberPrefix,              filename: filename.replace(prefix, ''),            };          }          // 접두사가 별견되지 않으면          return {numberPrefix: undefined, filename};        },        /**         * 문서 페이지에서 사용할 테마 컴포넌트를 설정합니다.         */        docLayoutComponent: '@theme/DocPage',        docItemComponent: '@theme/DocItem',        /**         * MDX에 전달할 Remark, Rehype 플러그인을 설정합니다.         */        remarkPlugins: [          /* require('remark-math') */        ],        rehypePlugins: [],        /**         * 기본 Remark, Rehype 플러그인이 적용되기 전에         * MDX에 사용자 지정 Remark, Rehype 플러그인을 전달하도록 설정합니다.         */        beforeDefaultRemarkPlugins: [],        beforeDefaultRehypePlugins: [],        /**         * 마지막으로 문서를 수정한 사용자를 표시할지 여부를 설정합니다.         */        showLastUpdateAuthor: false,        /**         * 마지막으로 문서를 수정한 일자를 표시할지 여부를 설정합니다.         */        showLastUpdateTime: false,        /**         * 기본적으로 문서 버전을 관리하는 사이트는 버전 관리 기능이 활성화됩니다.         * 아래 옵션은 명시적으로 버전 관리 기능을 비활성화할 수 있습니다.         * "current" 버전 (`/docs` 디렉터리)에만 적용됩니다.         */        disableVersioning: false,        /**         * 문서의 "current" 버전(`/docs` 디렉터리) 포함 여부를 설정합니다.         * 팁: current 버전이 작업중이고 아직 배포할 준비가 되지 않았을 때 꺼놓습니다.         */        includeCurrentVersion: true,        /**         * 마지막 버전은 버전 관리를 적용한 사이트에서 우선적으로 탐색하는 대상입니다.         * 문서 탐색바에서 기본값으로 표시되는 값입니다.         * 기본적으로 마지막 버전은 versions.json 파일 내 첫 항목에 위치한 값입니다.         * 기본적으로 마지막 버전은 "root" (문서 경로=/docs/myDoc)에 위치합니다.         * 참고: 마지막 버전의 경로와 표시되는 값을 설정할 수 있습니다.         * 팁: 'current'로 값을 설정하면 대부분 문제가 없습니다.         */        lastVersion: undefined,        /**         * 도큐사우루스에 기본 예로 설정한 versions 설정값은 대부분 프로젝트에 적합하지는 않습니다.         * 각 버전의 속성을 독립적으로 사용자가 정의하고자 할때 사용할 수 있습니다.         * - label: 버전 표시값         * - path: 버전의 라우트 경로         * - banner: 해당 버전 문서 상단에 표시할 배너: "none" | "unreleased" | "unmaintained"         */        versions: {          /*          Example configuration:           current: {            label: 'Android SDK v2.0.0 (WIP)',            path: 'android-2.0.0',            banner: 'none',          },          '1.0.0': {            label: 'Android SDK v1.0.0',            path: 'android-1.0.0',            banner: 'unmaintained',          },          */        },        /**         * 사용할 수 있는 버전 중 일부만 포함하려는 경우 사용하는 옵션입니다.         * 팁: 개발 및 배포 미리 보기 상태에서는 시작 및 빌드 성능을 향상시키기 위해 2~3개 정도 버전만 사용하는 것이 좋습니다.         */        onlyIncludeVersions: undefined, // 예: ["current", "1.0.0", "2.0.0"]      },    ],  ],};

마크다운 프런트 매터

마크다운 문서에서는 ---로 감싼 마크다운 프런트 매터 영역에서 아래와 같은 메타데이터 필드를 사용할 수 있습니다.

• id: 유일한 문서 id입니다. 기본값: 파일 경로(확장자는 제외하고 디렉터리는 포함)
• title: 문서 제목입니다. 페이지 메타데이터로 사용하며 여러 위치(사이드바, 다음/이전 버튼 등)에서 대체값으로 사용됩니다. 마크다운 제목이 없는 경우 문서 상단에 자동으로 추가됩니다. 기본값: 마크다운 제목 또는 문서 id
• hide_title: 문서 상단에서 제목을 숨길지 여부를 설정합니다. 프런트 매터 영역에서 설정한 제목만 감춥니다. 마크다운 문서 내에 지정된 타이틀에는 영향을 주지 않습니다. 기본값: false
• hide_table_of_contents: 오른쪽에 표시되는 목차 숨김 여부를 설정합니다. 기본값: false
• sidebar_label: 문서 내에서 문서의 사이드바에 표시할 텍스트를 설정합니다. 기본값: title
• sidebar_position: autogenerated 사이드바 아이템을 사용하는 경우 만들어진 사이드바 슬라이스 내에서 문서 위치를 조정할 수 있습니다. Int 또는 Float 값을 설정할 수 있습니다.
• pagination_label: 문서 내에서 문서의 다음/이전 버튼에 표시할 텍스트를 설정합니다. 기본값: sidebar_label 또는 title
• parse_number_prefixes: 문서에 번호 접두사(001 - My Doc.md, 2. MyDoc.md...)가 있는 경우 numberPrefixParser 플러그인에서 자동으로 구문을 분석하고 추출해 sidebar_position으로 번호 접두사를 사용합니다. parse_number_prefixes: false로 설정하면 문서에서 번호 접두사 구문 분석을 사용하지 않습니다. 기본값: parse_number_prefixes 플러그인 옵션
• custom_edit_url: 문서를 편집할 수 있는 URL을 설정합니다. 기본값: editUrl 플러그인 옵션을 사용해 계산된 값
• keywords: 검색 엔진에서 필요한 문서 페이지의 키워드 메타 태그를 설정합니다.
• description: 문서의 설명은 검색엔진에서 사용할 수 있게 <head> 태그 안에 <meta name="description" content="..."/>와 <meta property="og:description" content="..."/>로 처리됩니다. 기본값: 마크다운 콘텐츠 첫 번째 줄
• image: 게시글에 대한 링크를 표시할 때 보여지는 커버 또는 섬네일 이미지를 설정합니다.
• slug: 문서 url을 변경할 수 있도록 허용합니다(/<routeBasePath>/<slug>). 여러 패턴을 설정할 수도 있습니다: slug: my-doc, slug: /my/path/myDoc, slug: /.

예를 들면 아래와 같이 설정합니다.

---id: doc-markdowntitle: Docs Markdown Featureshide_title: falsehide_table_of_contents: falsesidebar_label: Markdownsidebar_position: 3pagination_label: Markdown featurescustom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.mddescription: How do I find you when I cannot solve this problemkeywords:  - docs  - docusaurusimage: https://i.imgur.com/mErPwqL.pngslug: /myDoc---# Markdown Features
My Document Markdown content

i18n

i18n 소개 문서를 먼저 확인해주세요.

번역 파일 위치

• 기본 경로: website/i18n/<locale>/docusaurus-plugin-content-docs
• 멀티 인스턴스 경로: website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>
• JSON 파일: docusaurus write-translations 명령 실행 후 만들어진 파일
• 마크다운 파일: website/i18n/<locale>/docusaurus-plugin-content-docs/<version>

파일 시스템 구조 예

website/i18n/<locale>/docusaurus-plugin-content-docs││ # translations for website/docs├── current│   ├── api│   │   └── config.md│   └── getting-started.md├── current.json││ # translations for website/versioned_docs/version-1.0.0├── version-1.0.0│   ├── api│   │   └── config.md│   └── getting-started.md└── version-1.0.0.json