📦 plugin-content-docs

Docusaurus 默认的文档插件，其提供文档功能。

安装

npm

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

Yarn

yarn add @docusaurus/plugin-content-docs

tip

若您已安装 @docusaurus/preset-classic，则无需安装此依赖。 您也可以通过经典预设选项来配置，从而无需进行下列操作。

配置

docusaurus.config.js

module.exports = {  plugins: [    [      '@docusaurus/plugin-content-docs',      {        /**         * 相对于站点目录的文件系统数据目录。         */        path: 'docs',        /**         * 编辑您的站点的基本网址。         * Docusaurus will compute the final editUrl with "editUrl + relativeDocPath"         * Omitting this variable entirely will disable edit links.         */        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',        /**         * For advanced cases, compute the edit url for each Markdown file yourself.         */        editUrl: function ({          locale,          version,          versionDocsDirPath,          docPath,          permalink,        }) {          return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;        },        /**         * 若您提交本地化文件到 Git，此选项将十分有用。         * When Markdown files are localized, the edit url will target the localized file,         * instead of the original unlocalized file.         * 注：当 editUrl 为函数时，此选项将被自动忽略。         */        editLocalizedFiles: false,        /**         * 若您不希望用户向旧版本提交文档合并请求，此选项将十分有用。         * 当文档存在不同版本时，编辑链接将指向         * 当前版本，而非其他版本。         * 注：当 editUrl 为函数时，此选项将被自动忽略         */        editCurrentVersion: false,        /**         * 您站点文档部分的 URL 路由。         * *请务必不要*添加斜杠。         * 注：您可以设置为 `/` 以在根目录提供文档。         */        routeBasePath: 'docs',        include: ['**/*.md', '**/*.mdx'], // 要包括的文件扩展名。        /**         * No route will be created for matching files         */        exclude: [          '**/_*.{js,jsx,ts,tsx,md,mdx}',          '**/_*/**',          '**/*.test.{js,jsx,ts,tsx}',          '**/__tests__/**',        ],        /**         * Path to sidebar configuration for showing a list of markdown pages.         */        sidebarPath: 'sidebars.js',        /**         * By default, all sidebar categories will be collapsible.         * This can be overriden per-category.         */        sidebarCollapsible: true,        /**         * By default, all sidebar categories will be initialized in a collapsed state.         * This can be overriden per-category.         */        sidebarCollapsed: false,        /**         * Function used to replace the sidebar items of type "autogenerated"         * by real sidebar items (docs, categories, links...)         */        sidebarItemsGenerator: async function ({          defaultSidebarItemsGenerator, // 用于重复利用/改良 Docusaurus 默认的侧边栏生成逻辑          numberPrefixParser, // 本插件配置使用的 numberPrefixParser          item, // “自动生成的”侧边栏内容          version, // 当前文档版本          docs, // 当前版本的所有文档（未经过滤）        }) {          // 使用给定数据生成自定义边栏片段          return [            {type: 'doc', id: 'intro'},            {              type: 'category',              label: 'Tutorials',              items: [                {type: 'doc', id: 'tutorial1'},                {type: 'doc', id: 'tutorial2'},              ],            },          ];        },        /**         * Docs 插件支持 "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: [],        /**         * 在默认 Docusaurus Remark 和 Rehype 插件之前         * 传递给 MDX 的 Remark 和 Rehype 插件。         */        beforeDefaultRemarkPlugins: [],        beforeDefaultRehypePlugins: [],        /**         * 是否显示最近更新文档的作者。         */        showLastUpdateAuthor: false,        /**         * 是否显示文档的最新更新日期。         */        showLastUpdateTime: false,        /**         * 默认情况下，分版站点将自动启用文档分版功能。         * 这是用于关闭分版功能的选项。         * This will only include the "current" version (the `/docs` directory)         */        disableVersioning: false,        /**         * Include the "current" version of your docs (the `/docs` directory)         * Tip: turn it off if the current version is a work-in-progress, not ready to be published         */        includeCurrentVersion: true,        /**         * The last version is the one we navigate to in priority on versioned sites         * It is the one displayed by default in docs navbar items         * By default, the last version is the first one to appear in versions.json         * By default, the last version is at the "root" (docs have path=/docs/myDoc)         * Note: it is possible to configure the path and label of the last version         * Tip: using lastVersion: 'current' make sense in many cases         */        lastVersion: undefined,        /**         * The docusaurus versioning defaults don't make sense for all projects         * This gives the ability customize the properties of each version independantly         * - label: the label of the version         * - path: the route path of the version         * - banner: the banner to show at the top of a doc of that version: "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',          },          */        },        /**         * Sometimes you only want to include a subset of all available versions.         * 提示：将其限制在 2 个或 3 个版本以缩短开发环境及部署预览时的启动及构建时间。         */        onlyIncludeVersions: undefined, // 例：["current", "1.0.0", "2.0.0"]      },    ],  ],};

Markdown 前言

Markdown 文档可使用以下的前言（Frontmatter）元数据字段，由上下方的 --- 所包裹：

• id：文档的唯一 ID。 默认值：文件路径（包括文件夹，不包括扩展名）
• title：文档标题。 用于页面元数据和多个地方的备用值（Fallback Value，用于侧边栏、下篇/上篇按钮...）。 若没有 Markdown 标题，此字段将自动添加到您的文档顶部。 默认值：Markdown 标题或文档 id
• hide_title：是否隐藏文档顶部的标题。 此选项仅隐藏前言中定义的标题，而对您 Markdown 文档顶部的标题无任何影响。 默认值︰false
• hide_table_of_contents - 是否隐藏右侧的目录。 默认值︰false
• sidebar_label: The text shown in the document sidebar for this document. Default value: title
• sidebar_position：当使用 autogenerated 侧边栏项目时，允许控制文档在生成的侧边栏片段内的位置。 可以是整数或浮点数。
• pagination_label: The text used in the document next/previous buttons for this document. Default value: sidebar_label, or title
• parse_number_prefixes：当文档包含数字前缀（001 - My Doc.md, 2. MyDoc.md...）时，它会自动被 numberPrefixParser 解析提取，而数字前缀会被用作 sidebar_position。 Use parse_number_prefixes: false to disable number prefix parsing on this doc. Default value: parse_number_prefixes plugin option
• custom_edit_url：编辑此文档的网址。 Default value: computed using the editUrl plugin options
• keywords：用于搜索引擎优化的文档页关键词元标签。
• description：文档描述，即位于 <head> 中的 <meta name="description" content="..."/> 及 <meta property="og:description" content="..."/>，用于搜索引擎优化。 Default value: the first line of Markdown content
• image - 显示博文链接时所用的缩略图或封面。
• slug：允许自定义文档链接 (<routeBasePath><slug>) Support multiple patterns: 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 files: extracted with docusaurus write-translations
• Markdown 文件：website/i18n/<locale>/docusaurus-plugin-content-docs/<version>

文件系统结构示例

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