📦 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.        /**         * 마크다운 페이지 목록을 보여주는 사이드바 경로를 설정합니다.         */        sidebarPath: 'sidebars.js',        /**         * "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,        /**         * 기본적으로 문서 버전을 관리하는 사이트는 버전 관리 기능이 활성화됩니다.         * 아래 옵션은 명시적으로 버전 관리 기능을 비활성화할 수 있습니다.         */        disableVersioning: false,        /**         * 버전 관리 기능을 활성화한 경우에는 next 릴리스 문서 처리를 건너뜁니다.         * 문서의 제품 빌드 시 `/docs/next` 디렉터리에는 HTML 파일을 만들지 않고         * 버전이 지정된 문서만 만듭니다.         */        excludeNextVersionDocs: false,        /**         * 마지막 버전은 버전 관리를 사용하는 사이트에서 우선적으로 탐색하는 버전입니다.         * navbar 아이템에서 기본적으로 표시되는 버전입니다.         * 기본적으로 마지막 버전은 versions.json 파일에서 가장 먼저 표시되는 버전입니다.         * 기본적으로 마지막 버전은 문서 경로의 "루트"에 위치합니다(문서의 경로=/docs/myDoc)         * 참고: 마지막 버전의 경로와 표시 문자열을 설정할 수 있습니다.         * 팁: lastVersion 옵션값을 'current'로 설정하면 대부분 문제 없이 동작합니다.         */        lastVersion: undefined,        /**         * 도큐사우루스의 버전 관리 기본값은 모든 프로젝트에 적합하지 않을 수 있습니다.         * 기본 버전 설정이 맘에 들지 않는다면         * 각 버전의 표시 문자열이나 경로를 수정해서 설정할 수 있습니다.         */        versions: {          /*          설정 예:           current: {            label: 'Android SDK v2.0.0 (WIP)',            path: 'android-2.0.0',          },          '1.0.0': {            label: 'Android SDK v1.0.0',            path: 'android-1.0.0',          },          */        },        /**         * 사용할 수 있는 버전만 공개하도록 설정할 수 있습니다.         * 팁: 개발 및 배포 미리 보기 상태에서는 시작 및 빌드 성능을 향상시키기 위해 2~3개 정도 버전만 사용하는 것이 좋습니다.         */        onlyIncludeVersions: undefined, // 예: ["current", "1.0.0", "2.0.0"]      },    ],  ],};

마크다운 프런트 매터

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

• id: 유일한 문서 id입니다. 값을 설정하지 않으면 문서 id는 파일명(확장자를 제외한)으로 기본 설정됩니다.
• title: 문서 제목입니다. 값을 설정하지 않으면 문서 title은 id 값으로 기본 설정됩니다.
• hide_title: 문서 상단에서 제목을 숨길지 여부를 설정합니다. 기본값은 false입니다
• hide_table_of_contents: 오른쪽에 표시되는 목차 숨김 여부를 설정합니다. 기본값은 false입니다
• sidebar_label: 사이드바와 다음/이전 버튼에 표시할 텍스트를 설정합니다. 값을 설정하지 않으면 문서 sidebar_label은 title 값으로 기본 설정됩니다.
• sidebar_position: autogenerated 사이드바 아이템을 사용하는 경우 만들어진 사이드바 슬라이스 내에서 문서 위치를 조정할 수 있습니다. Int 또는 Float 값을 설정할 수 있습니다.
• parse_number_prefixes: 문서에 번호 접두사(001 - My Doc.md, 2. MyDoc.md...)가 있는 경우 numberPrefixParser 플러그인에서 자동으로 구문을 분석하고 추출해 sidebar_position으로 번호 접두사를 사용합니다. parse_number_prefixes: false로 설정하면 문서에서 번호 접두사 구문 분석을 사용하지 않습니다.
• custom_edit_url: 문서를 편집할 수 있는 URL을 설정합니다. 값을 설정하지 않으면 문서의 편집 URL은 docusaurus-plugin-content-docs에 전달된 옵션 필드에서 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: Markdown Featureshide_title: falsehide_table_of_contents: falsesidebar_label: Markdown :)custom_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---My Document Markdown content

i18n

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

번역 파일 위치

• 기본 경로: website/i18n/<locale>/docusaurus-plugin-content-docs
• 멀티 인스턴스 경로: website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>
• JSON 파일: extracted with 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