跳至主要内容
版本：3.5.2

📦 plugin-content-docs

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

安装​

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

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

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

配置​

接受的字段

名称类型默认值描述
pathstring'docs'指向文档内容目录的路径，相对于站点目录。
editUrlstring | EditUrlFunctionundefined用于编辑站点的基本 URL。最终 URL 由 editUrl + relativeDocPath 计算得出。使用函数可以对每个文件进行更细致的控制。完全省略此变量将禁用编辑链接。
editLocalizedFilesbooleanfalse编辑 URL 将指向本地化文件，而不是原始的非本地化文件。当 editUrl 是一个函数时将被忽略。
editCurrentVersionbooleanfalse编辑 URL 将始终指向当前版本的文档，而不是旧版本。当 editUrl 是一个函数时将被忽略。
routeBasePathstring'docs'站点文档部分的 URL 路径。不要包含尾部斜杠。使用 / 来发布没有基本路径的文档。
tagsBasePathstring'tags'站点标签列表页面的 URL 路径。它将被追加到 routeBasePath 前面。
includestring[]['**/*.{md,mdx}']匹配要构建的 Markdown 文件的 glob 模式数组，相对于内容路径。
excludestring[]参见示例配置匹配要排除的 Markdown 文件的 glob 模式数组。基于 include 选项进行细化。
sidebarPathfalse | stringundefined侧边栏配置的路径。使用 false 来禁用侧边栏，或使用 undefined 来创建一个完全自动生成的侧边栏。
sidebarCollapsiblebooleantrue侧边栏类别是否默认可折叠。另请参阅 可折叠类别
sidebarCollapsedbooleantrue侧边栏类别是否默认折叠。另请参阅 默认展开的类别
sidebarItemsGeneratorSidebarGenerator省略用于将类型为 'autogenerated' 的侧边栏项目替换为实际的侧边栏项目（文档、类别、链接...）。另请参阅 自定义侧边栏项目生成器
numberPrefixParserboolean | PrefixParser省略自定义解析逻辑，用于从文件名中提取数字前缀。使用 false 禁用此行为并保持文档不变，使用 true 使用默认解析器。另请参阅 使用数字前缀
docsRootComponentstring'@theme/DocsRoot'所有文档插件页面（包括所有版本）的父组件。在文档页面和版本之间导航时保持挂载状态。
docVersionRootComponentstring'@theme/DocVersionLayout'单个版本的所有文档页面的父组件（带有侧边栏的文档页面、标签页面）。在该特定版本页面之间导航时保持挂载状态。
docRootComponentstring'@theme/DocRoot'所有带有侧边栏的文档页面的父组件（常规文档页面、类别生成的索引页面）。在这些页面之间导航时保持挂载状态。
docItemComponentstring'@theme/DocItem'主要的文档容器，带有目录、分页等。
docTagsListComponentstring'@theme/DocTagsListPage'标签列表页面的根组件
docTagDocListComponentstring'@theme/DocTagDocListPage'"包含标签 X 的文档"页面的根组件。
docCategoryGeneratedIndexComponentstring'@theme/DocCategoryGeneratedIndexPage'生成的类别索引页面的根组件。
remarkPluginsany[][]传递给 MDX 的 Remark 插件。
rehypePluginsany[][]传递给 MDX 的 Rehype 插件。
rehypePluginsany[][]传递给 MDX 的 Recma 插件。
beforeDefaultRemarkPluginsany[][]传递给 MDX 的自定义 Remark 插件，在默认的 Docusaurus Remark 插件之前。
beforeDefaultRehypePluginsany[][]传递给 MDX 的自定义 Rehype 插件，在默认的 Docusaurus Rehype 插件之前。
showLastUpdateAuthorbooleanfalse是否显示最后更新文档的作者。
showLastUpdateTimebooleanfalse是否显示文档最后更新的日期。这需要在构建期间访问 Git 历史记录，因此在使用浅克隆（CI 系统的常见默认值）时将无法正常工作。在使用 GitHub actions/checkout 时，请使用 fetch-depth: 0。
disableVersioningbooleanfalse即使存在多个版本，也要显式禁用版本控制。这将使站点只包含当前版本。如果 includeCurrentVersion: false 和 disableVersioning: true，则会报错。
includeCurrentVersionbooleantrue包含文档的当前版本。
lastVersionstringversions.json 中的第一个版本文档导航栏项目中默认优先导航到的版本并显示的版本。
onlyIncludeVersionsstring[]所有可用版本仅包含所有可用版本的一个子集。
versionsVersionsConfig{}独立自定义每个版本的属性。
tagsstring | false | null | undefinedtags.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: {
  /** The sidebar item with type "autogenerated" to be transformed. */
  item: {type: 'autogenerated'; dirName: string};
  /** Useful metadata for the version this sidebar belongs to. */
  version: {contentPath: string; versionName: string};
  /** All the docs of that version (unfiltered). */
  docs: {
    id: string;
    title: string;
    frontMatter: DocFrontMatter & Record<string, unknown>;
    source: string;
    sourceDirName: string;
    sidebarPosition?: number | undefined;
  }[];
  /** Number prefix parser configured for this plugin. */
  numberPrefixParser: PrefixParser;
  /** The default category index matcher which you can override. */
  isCategoryIndex: CategoryIndexMatcher;
  /**
   * key is the path relative to the doc content directory, value is the
   * category metadata file's content.
   */
  categoriesMetadata: {[filePath: string]: CategoryMetadata};
  /**
   * Useful to re-use/enhance the default sidebar generation logic from
   * Docusaurus.
   */
  defaultSidebarItemsGenerator: SidebarGenerator;
  // Returns an array of sidebar items — same as what you can declare in
  // sidebars.js, except for shorthands. See https://docusaurus.org.cn/docs/sidebar/items
}) => Promise<SidebarItem[]>;

type CategoryIndexMatcher = (param: {
  /** The file name, without extension */
  fileName: string;
  /**
   * The list of directories, from lowest level to highest.
   * If there's no dir name, directories is ['.']
   */
  directories: string[];
  /** The extension, with a leading dot */
  extension: string;
}) => boolean;

VersionsConfig​

type VersionConfig = {
  /**
   * The base path of the version, will be appended to `baseUrl` +
   * `routeBasePath`.
   */
  path?: string;
  /** The label of the version to be used in badges, dropdowns, etc. */
  label?: string;
  /** The banner to show at the top of a doc of that version. */
  banner?: 'none' | 'unreleased' | 'unmaintained';
  /** Show a badge with the version label at the top of each doc. */
  badge?: boolean;
  /** Prevents search engines from indexing this version */
  noIndex?: boolean;
  /** Add a custom class name to the <html> element of each doc */
  className?: string;
};

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

示例配置​

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

提示

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

如果你使用预设，请通过 预设选项 配置此插件

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs',
          breadcrumbs: true,
          // Simple use-case: string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Advanced use-case: functional 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,
          }) {
            // Use the provided data to generate a custom sidebar slice
            return [
              {type: 'doc', id: 'intro'},
              {
                type: 'category',
                label: 'Tutorials',
                items: [
                  {type: 'doc', id: 'tutorial1'},
                  {type: 'doc', id: 'tutorial2'},
                ],
              },
            ];
          },
          numberPrefixParser(filename) {
            // Implement your own logic to extract a potential number prefix
            const numberPrefix = findNumberPrefix(filename);
            // Prefix found: return it with the cleaned filename
            if (numberPrefix) {
              return {
                numberPrefix,
                filename: filename.replace(prefix, ''),
              };
            }
            // No number prefix found
            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 前置信息 元数据字段，两侧用 --- 行包围。

接受的字段

名称类型默认值描述
idstring文件路径（包括文件夹，不包括扩展名）唯一的文档 ID。
titlestringMarkdown 标题或 id文档的文本标题。用于页面元数据，并在多个地方用作后备值（侧边栏、下一个/上一个按钮...）。如果文档不包含任何 Markdown 标题，则会自动添加到文档顶部。
pagination_labelstringsidebar_label 或 title文档下一个/上一个按钮中用于此文档的文本。
displayed_sidebarstringundefined在浏览当前文档时强制显示给定的侧边栏。阅读 多个侧边栏指南 获取详细信息。
hide_titlebooleanfalse是否隐藏文档顶部的标题。它只隐藏通过前置信息声明的标题，对文档顶部的 Markdown 标题没有影响。
hide_table_of_contentsbooleanfalse是否隐藏右侧的目录。
toc_min_heading_levelnumber2目录中显示的最小标题级别。必须介于 2 到 6 之间，且小于或等于最大值。
toc_max_heading_levelnumber3目录中显示的最大标题级别。必须介于 2 到 6 之间。
pagination_nextstring | null侧边栏中的下一份文档要链接到“下一个”分页的文档 ID。使用 null 来禁用为此页面显示“下一个”。
pagination_prevstring | null侧边栏中的上一份文档要链接到“上一个”分页的文档 ID。使用 null 来禁用为此页面显示“上一个”。
parse_number_prefixesbooleannumberPrefixParser 插件选项是否在该文档上禁用数字前缀解析。另请参阅 使用数字前缀。
custom_edit_urlstring | null使用 editUrl 插件选项计算得出用于编辑此文档的 URL。使用 null 来禁用为此页面显示“编辑此页面”。
keywordsstring[]undefined文档页面的关键词元标签，用于搜索引擎。
描述string第一行 Markdown 内容文档描述，将在 <head> 中变成 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/>，用于搜索引擎。
图像stringundefined封面或缩略图，将在 <head> 中用作 <meta property="og:image" content="..."/>，增强社交媒体和消息平台上的链接预览。
别名string文件路径允许自定义文档 URL (/<routeBasePath>/<slug>)。支持多种模式：slug: my-doc，slug: /my/path/myDoc，slug: /。
tagsTag[]undefined字符串或包含两个字符串字段 label 和 permalink 的对象的列表，用于标记您的文档。字符串可以是 标签文件（通常为 tags.yml）的键的引用。
草稿booleanfalse草稿文档仅在开发过程中可用。
未列出booleanfalse未列出的文档在开发和生产中都可用。它们在生产中将被“隐藏”，不会被索引，不会包含在站点地图中，并且只能通过拥有直接链接的用户访问。
最后更新FrontMatterLastUpdateundefined允许覆盖最后更新的作者/日期。日期可以是任何 可解析的日期字符串。
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: How do I find you when I cannot solve this problem
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 Features

My Document Markdown content

标签文件​

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

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

此文件可以包含预定义标签的列表。您可以通过 tags 前置内容 在 Markdown 文件中通过其键引用这些标签。

保持标签一致

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

类型​

提供的标签文件的 YAML 内容应符合以下形状

type Tag = {
  label?: string; // Tag display label
  permalink?: string; // Tag URL pathname segment
  description?: string; // Tag description displayed in the tag page
};

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

示例​

tags.yml
releases:
  label: 'Product releases'
  permalink: '/product-releases'
  description: 'Content related to product releases.'

# A partial tag definition is also valid
announcements:
  label: 'Announcements'

# An empty tag definition is also valid
# Other attributes will be inferred from the key
emptyTag:
content.md
---
tags: [releases, announcements, emptyTag]
---

# Title

Content

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
编辑此页面
最后更新于 由 Sébastien Lorber 更新