📦 plugin-content-docs

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

安装

npm
Yarn
pnpm

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

yarn add @docusaurus/plugin-content-docs

pnpm add @docusaurus/plugin-content-docs

提示

如果您使用预设 @docusaurus/preset-classic，则无需将其作为依赖项安装此插件。

您可以通过预设选项配置此插件。

配置

可接受的字段：

名称	类型	默认值	描述
`path`	`string`	`'docs'`	文档内容目录在文件系统中的路径，相对于站点目录。
`editUrl`	`string \| EditUrlFunction`	`undefined`	编辑站点的基本 URL。最终 URL 由 `editUrl + relativeDocPath` 计算得出。使用函数允许对每个文件进行更细致的控制。完全省略此变量将禁用编辑链接。
`editLocalizedFiles`	`boolean`	`false`	编辑 URL 将指向本地化文件，而不是原始的非本地化文件。当 `editUrl` 为函数时忽略。
`editCurrentVersion`	`boolean`	`false`	编辑 URL 将始终指向当前版本文档，而不是旧版本。当 `editUrl` 为函数时忽略。
`routeBasePath`	`string`	`'docs'`	站点文档部分的 URL 路径。不要包含尾部斜杠。对于不带基路径的文档，请使用 `/`。
`tagsBasePath`	`string`	`'tags'`	站点标签列表页面的 URL 路径。它会添加到 `routeBasePath` 前面。
`include`	`string[]`	`['*/.{md,mdx}']`	匹配要构建的 Markdown 文件的 glob 模式数组，相对于内容路径。
`exclude`	`string[]`	参见示例配置	匹配要排除的 Markdown 文件的 glob 模式数组。根据 `include` 选项进行细化。
`sidebarPath`	`false \| string`	`undefined`	侧边栏配置文件的路径，在 Node.js 上下文中加载。使用 `false` 禁用侧边栏，或使用 `undefined` 创建完全自动生成的侧边栏。
`sidebarCollapsible`	`boolean`	`true`	侧边栏类别是否默认可折叠。另请参见可折叠类别
`sidebarCollapsed`	`boolean`	`true`	侧边栏类别是否默认折叠。另请参见默认展开类别
`sidebarItemsGenerator`	`SidebarGenerator`	省略	用于将类型为 `'autogenerated'` 的侧边栏项替换为实际侧边栏项（文档、类别、链接……）的函数。另请参见自定义侧边栏项生成器
`numberPrefixParser`	`boolean \| PrefixParser`	省略	用于从文件名中提取数字前缀的自定义解析逻辑。使用 `false` 禁用此行为并保持文档不变，使用 `true` 使用默认解析器。另请参见使用数字前缀
`docsRootComponent`	`string`	`'@theme/DocsRoot'`	所有文档插件页面（包括所有版本）的父组件。在文档页面和版本之间导航时保持挂载状态。
`docVersionRootComponent`	`string`	`'@theme/DocVersionLayout'`	单个版本的文档页面的父组件（带有侧边栏的文档页面、标签页面）。在该特定版本的页面之间导航时保持挂载状态。
`docRootComponent`	`string`	`'@theme/DocRoot'`	所有带有侧边栏的文档页面的父组件（常规文档页面、类别生成的索引页面）。在这些页面之间导航时保持挂载状态。
`docItemComponent`	`string`	`'@theme/DocItem'`	带有 TOC、分页等的主要文档容器。
`docTagsListComponent`	`string`	`'@theme/DocTagsListPage'`	标签列表页面的根组件
`docTagDocListComponent`	`string`	`'@theme/DocTagDocListPage'`	“包含标签 X 的文档”页面的根组件。
`docCategoryGeneratedIndexComponent`	`string`	`'@theme/DocCategoryGeneratedIndexPage'`	生成的类别索引页面的根组件。
`remarkPlugins`	`any[]`	`[]`	传递给 MDX 的 Remark 插件。
`rehypePlugins`	`any[]`	`[]`	传递给 MDX 的 Rehype 插件。
`rehypePlugins`	`any[]`	`[]`	传递给 MDX 的 Recma 插件。
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	在默认 Docusaurus Remark 插件之前传递给 MDX 的自定义 Remark 插件。
`beforeDefaultRehypePlugins`	`any[]`	`[]`	在默认 Docusaurus Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。
`showLastUpdateAuthor`	`boolean`	`false`	是否显示最后更新文档的作者。
`showLastUpdateTime`	`boolean`	`false`	是否显示文档最后更新日期。这需要在构建期间访问 git 历史记录，因此浅克隆（CI 系统的常见默认值）将无法正常工作。对于 GitHub `actions/checkout`，请使用 `fetch-depth: 0`。
`breadcrumbs`	`boolean`	`true`	启用或禁用文档页面上的面包屑。
`disableVersioning`	`boolean`	`false`	即使存在多个版本，也明确禁用版本控制。这将使站点仅包含当前版本。如果 `includeCurrentVersion: false` 和 `disableVersioning: true`，则会出错。
`includeCurrentVersion`	`boolean`	`true`	包含文档的当前版本。
`lastVersion`	`string`	`versions.json` 中的第一个版本	优先导航到的版本以及文档导航栏项目默认显示的版本。
`onlyIncludeVersions`	`string[]`	所有可用版本	只包含所有可用版本的一个子集。
`versions`	`VersionsConfig`	`{}`	每个版本的属性的独立自定义。
`tags`	`string \| false \| null \| undefined`	`tags.yml`	列出预定义标签的 YAML 文件路径。相对于文档版本内容目录。
`onInlineTags`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`warn`	当文档包含内联标签（通常不在预定义标签列表中，通常为 `docs/tags.yml`）时的插件行为。

类型

`EditUrlFunction`

type EditUrlFunction = (params: {
  version: string;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

`PrefixParser`

type PrefixParser = (filename: string) => {
  filename: string;
  numberPrefix?: number;
};

`SidebarGenerator`

type SidebarGenerator = (generatorArgs: {
  /** 要转换的类型为“autogenerated”的侧边栏项。 */
  item: {type: 'autogenerated'; dirName: string};
  /** 此侧边栏所属版本的实用元数据。 */
  version: {contentPath: string; versionName: string};
  /** 该版本的所有文档（未过滤）。 */
  docs: {
    id: string;
    title: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }[];
  /** 为此插件配置的数字前缀解析器。 */
  numberPrefixParser: PrefixParser;
  /** 可以覆盖的默认类别索引匹配器。 */
  isCategoryIndex: CategoryIndexMatcher;
  /**
   * 键是相对于文档内容目录的路径，值是类别元数据文件的內容。
   */
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  /**
   * 用于重用/增强 Docusaurus 的默认侧边栏生成逻辑。
   */
  defaultSidebarItemsGenerator: SidebarGenerator;
  // 返回侧边栏项数组——与您可以在 sidebars.js 中声明的内容相同，但快捷方式除外。请参见 https://docusaurus.io/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
  /** 文件名，不含扩展名 */
  fileName: string;
  /**
   * 目录列表，从最低级别到最高级别。
   * 如果没有目录名称，则目录为 ['.']
   */
  directories: string[];
  /** 扩展名，带前导点 */
  extension: string;
}) => boolean;

`VersionsConfig`

type VersionConfig = {
  /**
   * 版本的基路径，将附加到 `baseUrl` +
   * `routeBasePath`。
   */
  path?: string;
  /** 要在徽章、下拉菜单等中使用的版本的标签。 */
  label?: string;
  /** 要在该版本文档顶部显示的横幅。 */
  banner?: 'none' | 'unreleased' | 'unmaintained';
  /** 在每个文档顶部显示带有版本标签的徽章。 */
  badge?: boolean;
  /** 防止搜索引擎索引此版本 */
  noIndex?: boolean;
  /** 为每个文档的 <html> 元素添加自定义类名 */
  className?: string;
};

type VersionsConfig = {[versionName: string]: VersionConfig};

示例配置

您可以通过预设选项或插件选项配置此插件。

提示

大多数 Docusaurus 用户通过预设选项配置此插件。

Preset options
Plugin options

If you use a preset, configure this plugin through the preset options:

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        [translation failure]: {
          path: 'docs',
          breadcrumbs: true,
          // 简单用例：string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // 高级用例：函数式 editUrl
          editUrl: ({versionDocsDirPath, docPath}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`,
          editLocalizedFiles: false,
          editCurrentVersion: false,
          routeBasePath: 'docs',
          include: ['**/*.md', '**/*.mdx'],
          exclude: [
            '**/_*.{js,jsx,ts,tsx,md,mdx}',
            '**/_*/**',
            '**/*.test.{js,jsx,ts,tsx}',
            ' **/__tests__/** ',
          ],
          sidebarPath: 'sidebars.js',
          async sidebarItemsGenerator({
            defaultSidebarItemsGenerator,
            numberPrefixParser,
            item,
            version,
            docs,
            isCategoryIndex,
          }) {
            // 使用提供的数据生成自定义侧边栏切片
            return [
              {type: 'doc', id: 'intro'},
              {
                type: 'category',
                label: '教程',
                items: [
                  {type: 'doc', id: 'tutorial1'},
                  {type: 'doc', id: 'tutorial2'},
                ],
              },
            ];
          },
          numberPrefixParser(filename) {
            // 实现您自己的逻辑来提取潜在的数字前缀
            const numberPrefix = findNumberPrefix(filename);
            // 找到前缀：使用清理后的文件名返回它
            if (numberPrefix) {
              return {
                numberPrefix,
                filename: filename.replace(prefix, ''),
              };
            }
            // 未找到数字前缀
            return {numberPrefix: undefined, filename};
          },
          docsRootComponent: '@theme/DocsRoot',
          docVersionRootComponent: '@theme/DocVersionRoot',
          docRootComponent: '@theme/DocRoot',
          docItemComponent: '@theme/DocItem',
          remarkPlugins: [require('./my-remark-plugin')],
          rehypePlugins: [],
          beforeDefaultRemarkPlugins: [],
          beforeDefaultRehypePlugins: [],
          showLastUpdateAuthor: false,
          showLastUpdateTime: false,
          disableVersioning: false,
          includeCurrentVersion: true,
          lastVersion: undefined,
          versions: {
            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',
            },
          },
          onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
        },
      },
    ],
  ],
};

If you are using a standalone plugin, provide options directly to the plugin:

docusaurus.config.js
module.exports = {
  plugins: [
    [
      '[translation failure]',
      {
        path: 'docs',
        breadcrumbs: true,
        // 简单用例：string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // 高级用例：函数式 editUrl
        editUrl: ({versionDocsDirPath, docPath}) =>
          `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`,
        editLocalizedFiles: false,
        editCurrentVersion: false,
        routeBasePath: 'docs',
        include: ['**/*.md', '**/*.mdx'],
        exclude: [
          '**/_*.{js,jsx,ts,tsx,md,mdx}',
          '**/_*/**',
          '**/*.test.{js,jsx,ts,tsx}',
          ' **/__tests__/** ',
        ],
        sidebarPath: 'sidebars.js',
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          isCategoryIndex,
        }) {
          // 使用提供的数据生成自定义侧边栏切片
          return [
            {type: 'doc', id: 'intro'},
            {
              type: 'category',
              label: '教程',
              items: [
                {type: 'doc', id: 'tutorial1'},
                {type: 'doc', id: 'tutorial2'},
              ],
            },
          ];
        },
        numberPrefixParser(filename) {
          // 实现您自己的逻辑来提取潜在的数字前缀
          const numberPrefix = findNumberPrefix(filename);
          // 找到前缀：使用清理后的文件名返回它
          if (numberPrefix) {
            return {
              numberPrefix,
              filename: filename.replace(prefix, ''),
            };
          }
          // 未找到数字前缀
          return {numberPrefix: undefined, filename};
        },
        docsRootComponent: '@theme/DocsRoot',
        docVersionRootComponent: '@theme/DocVersionRoot',
        docRootComponent: '@theme/DocRoot',
        docItemComponent: '@theme/DocItem',
        remarkPlugins: [require('./my-remark-plugin')],
        rehypePlugins: [],
        beforeDefaultRemarkPlugins: [],
        beforeDefaultRehypePlugins: [],
        showLastUpdateAuthor: false,
        showLastUpdateTime: false,
        disableVersioning: false,
        includeCurrentVersion: true,
        lastVersion: undefined,
        versions: {
          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',
          },
        },
        onlyIncludeVersions: ['current', '1.0.0', '2.0.0'],
      },
    ],
  ],
};

Markdown 前端内容

Markdown 文档可以使用以下 Markdown 前端内容元数据字段，两侧都用 --- 行括起来。

可接受的字段：

名称	类型	默认值	描述
`id`	`string`	文件路径（包括文件夹，不包含扩展名）	唯一的文档 ID。
`title`	`string`	Markdown 标题或 `id`	文档的文本标题。用于页面元数据以及多个位置的备用值（侧边栏、前后按钮……）。如果文档不包含任何 Markdown 标题，则会自动添加到文档顶部。
`title_meta`	`string`	`frontMatter.title`	文档的 SEO 元数据标题，用于 `<head>` 中的 `<title>` 和 `og:title`。允许在显示标题和 SEO 标题应不同时覆盖 `frontMatter.title`。
`pagination_label`	`string`	`sidebar_label` 或 `title`	文档前后按钮中用于此文档的文本。
`sidebar_label`	`string`	`title`	在文档侧边栏中显示的此文档文本。
`sidebar_position`	`number`	默认排序	使用 `autogenerated` 侧边栏项时，控制文档在生成的侧边栏切片中的位置。另请参见自动生成的侧边栏元数据。
`sidebar_class_name`	`string`	`undefined`	使用自动生成的侧边栏时，为相应的侧边栏标签提供一个特殊的类名。
`sidebar_custom_props`	`object`	`undefined`	为引用此文档的侧边栏项分配自定义属性
`displayed_sidebar`	`string`	`undefined`	浏览当前文档时强制显示给定的侧边栏。阅读多个侧边栏指南以了解详细信息。
`hide_title`	`boolean`	`false`	是否隐藏文档顶部的标题。它只隐藏通过前端内容声明的标题，对文档顶部的 Markdown 标题没有影响。
`hide_table_of_contents`	`boolean`	`false`	是否隐藏右侧的目录。
`toc_min_heading_level`	`number`	`2`	目录中显示的最小标题级别。必须在 2 到 6 之间，并且小于或等于最大值。
`toc_max_heading_level`	`number`	`3`	目录中显示的最大标题级别。必须在 2 到 6 之间。
`pagination_next`	`string \| null`	侧边栏中的下一个文档	您希望“下一个”分页链接到的文档的 ID。使用 `null` 来禁用为此页面显示“下一个”。
`pagination_prev`	`string \| null`	侧边栏中的上一个文档	您希望“上一个”分页链接到的文档的 ID。使用 `null` 来禁用为此页面显示“上一个”。
`parse_number_prefixes`	`boolean`	`numberPrefixParser` 插件选项	是否在此文档上禁用数字前缀解析。另请参见使用数字前缀。
`custom_edit_url`	`string \| null`	使用 `editUrl` 插件选项计算	编辑此文档的 URL。使用 `null` 来禁用为此页面显示“编辑此页面”。
`keywords`	`string[]`	`undefined`	文档页面的关键词元标签，用于搜索引擎。
`description`	`string`	Markdown 内容的第一行	文档的描述，它将成为 `<head>` 中的 `<meta name="description" content="..."/>` 和 `<meta property="og:description" content="..."/>`，搜索引擎使用。
`image`	`string`	`undefined`	将用作 `<head>` 中 `<meta property="og:image" content="..."/>` 的封面或缩略图图像，增强社交媒体和消息平台上的链接预览。
`slug`	`string`	文件路径	允许自定义文档 URL (`/<routeBasePath>/<slug>`)。支持多种模式：`slug: my-doc`，`slug: /my/path/myDoc`，`slug: /`。
`tags`	`Tag[]`	`undefined`	字符串或两个字符串字段 `label` 和 `permalink` 的对象列表，用于标记您的文档。字符串可以是标签文件 (通常是 `tags.yml`) 的键的引用
`draft`	`boolean`	`false`	草稿文档仅在开发期间可用。
`unlisted`	`boolean`	`false`	未列出的文档在开发和生产环境中都可用。它们将在生产环境中“隐藏”，不会被索引，不包含在站点地图中，并且只能由拥有直接链接的用户访问。
`last_update`	`FrontMatterLastUpdate`	`undefined`	允许覆盖最后更新的作者/日期。日期可以是任何可解析的日期字符串。

type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

示例：

---
id: doc-markdown
title: Docs Markdown 功能
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown 功能
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: 当我无法解决这个问题时，我该如何找到你
keywords:
  - docs
  - docusaurus
tags: [docusaurus]
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
last_update:
  date: 1/1/2000
  author: custom author name
---

# Markdown 功能

我的文档 Markdown 内容

标签文件

使用 tags 插件选项配置 YAML 标签文件的路径。

按照惯例，插件会在您的内容文件夹的根目录下查找 tags.yml 文件。

此文件可以包含预定义标签的列表。您可以通过 Markdown 文件中的键来引用这些标签，这要感谢 tags 前置 matter 。

保持标签一致

使用标签文件，您可以确保在整个插件内容集中一致地使用标签。使用 onInlineTags: 'throw' 插件选项来强制执行此一致性，并防止使用动态声明的内联标签。

类型

提供的标签文件的 YAML 内容应遵循以下结构：

type Tag = {
  label?: string; // 标签显示标签
  permalink?: string; // 标签 URL 路径段
  description?: string; // 在标签页中显示的标签描述
};

type TagsFileInput = Record<string, Partial<Tag> | null>;

示例

tags.yml
releases:
  label: '产品发布'
  permalink: '/product-releases'
  description: '与产品发布相关的內容。'

# 部分标签定义也是有效的
announcements:
  label: '公告'

# 空标签定义也是有效的
# 其他属性将从键中推断
emptyTag:

content.md
---
tags: [releases, announcements, emptyTag]
---

# 标题

内容

国际化

请先阅读国际化介绍。

翻译文件位置

基本路径 : website/i18n/[locale]/docusaurus-plugin-content-docs
多实例路径 : website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]
JSON 文件 : 使用 docusaurus write-translations 提取
Markdown 文件 : website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]

示例文件系统结构

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

安装​

配置​

类型​

EditUrlFunction​

PrefixParser​

SidebarGenerator​

VersionsConfig​

示例配置​

Markdown 前端内容​

标签文件​

类型​

示例​

国际化​

翻译文件位置​

示例文件系统结构​

安装

配置

类型