📦 plugin-content-docs

提供文档功能，是道格龙（Docusaurus）默认的文档插件。

安装

npm
Yarn
pnpm
Bun

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

yarn add @docusaurus/plugin-content-docs

pnpm add @docusaurus/plugin-content-docs

bun 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'`	主要文档容器，包含目录、分页等。
`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[]`	`[]`	在默认道格龙 Remark 插件之前传递给 MDX 的自定义 Remark 插件。
`beforeDefaultRehypePlugins`	`any[]`	`[]`	在默认道格龙 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: {
  /** type 为 "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;
  /**
   * key 为文档内容目录的相对路径，value 为分类元数据文件内容。
   */
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  /**
   * 可复用/增强道格龙默认的侧边栏生成逻辑。
   */
  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};

示例配置

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

提示

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

// 预设选项：docs
// 插件选项：@docusaurus/plugin-content-docs

const config = {
  path: 'docs',
  breadcrumbs: true,
  // 简单用法：字符串 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: 'Tutorials',
        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 front matter

Markdown 文档可以使用如下 Markdown front matter 元数据字段，需用 --- 包裹。

可用字段：

名称	类型	默认值	说明
`id`	`string`	文件路径（含文件夹，不含扩展名）	文档唯一 ID。
`title`	`string`	Markdown 标题或 `id`	文档标题文本。用于页面元数据，并作为多个位置（侧边栏、上下页按钮等）的备用值。如果文档顶部没有 Markdown 标题，则会自动添加。
`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`	是否隐藏文档顶部标题。仅隐藏通过 front matter 声明的标题，不影响 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`	文档页面的关键词 meta 标签，供搜索引擎使用。
`description`	`string`	Markdown 内容第一行	文档描述，将作为 `<meta name="description" content="..."/>` 和 `<meta property="og:description" content="..."/>` 出现在 `<head>`，供搜索引擎使用。
`image`	`string`	`undefined`	封面或缩略图，将作为 `<meta property="og:image" content="..."/>` 出现在 `<head>`，用于增强社交媒体和消息平台的链接预览效果。
`slug`	`string`	文件路径	自定义文档 URL（`/<routeBasePath>/<slug>`）。支持多种模式：`slug: my-doc`、`slug: /my/path/myDoc`、`slug: /`。
`tags`	`Tag[]`	`undefined`	文档标签字符串或对象数组。字符串可引用标签文件（通常为 `tags.yml`）中的 key。
`draft`	`boolean`	`false`	草稿文档仅在开发环境可见。
`unlisted`	`boolean`	`false`	未列出的文档在开发和生产环境均可访问，但在生产环境下会被"隐藏"，不被索引、不会出现在 sitemap，只能通过直链访问。
`last_update`	`FrontMatterLastUpdate`	`undefined`	可覆盖最后更新作者/日期。日期可为任意可解析的日期字符串。

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

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

示例：

---
id: doc-markdown
title: Docs Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown features
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 front matter 引用这些标签的 key。

保持标签一致性

通过标签文件，你可以确保在插件内容中标签的使用保持一致。使用 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: '公告'

# 空标签定义同样有效
# 其他属性会根据 key 自动推断
emptyTag:

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

# 标题

内容

i18n

请先阅读i18n 介绍。

翻译文件位置

基础路径：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
│
│ # 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

安装​

配置​

类型定义​

EditUrlFunction​

PrefixParser​

SidebarGenerator​

VersionsConfig​

示例配置​

Markdown front matter​

标签文件​

类型​

示例​

i18n​

翻译文件位置​

文件系统结构示例​

安装

配置