跳到主要内容
版本:2.x

📦 plugin-content-docs

Provides the Docs functionality and is the default docs plugin for Docusaurus.

Installation

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

If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

You can configure this plugin through the preset options.

Configuration

接受的字段:

参数类型默认值描述
pathstring'docs'文档内容目录的文件系统路径,相对于站点目录。
editUrlstring | EditUrlFunctionundefined编辑文档的基础 URL。 The final URL is computed by editUrl + relativeDocPath. 使用函数可以允许你更精细地控制每一个文件。 完全忽略这个变量就会禁用编辑链接。
editLocalizedFilesbooleanfalse编辑 URL 会指向本地化的文件,而不是原始的未翻译文件。 Ignored when editUrl is a function.
editCurrentVersionbooleanfalse编辑 URL 会永远指向当前版本文档而不是历史版本。 Ignored when editUrl is a function.
routeBasePathstring'docs'站点文档部分的 URL 前缀。 DO NOT include a trailing slash. Use / for shipping docs without base path.
tagsBasePathstring'tags'站点标签列表部分的 URL 前缀。 It is prepended to the routeBasePath.
includestring[]['**/*.{md,mdx}']相对于内容路径的 glob 模式列表,匹配到的 Markdown 文件会被构建。
excludestring[]See example configurationGlob 模式列表,匹配到的 Markdown 文件会被排除。 Serves as refinement based on the include option.
sidebarPathfalse | stringundefined侧边栏配置的路径。 Use false to disable sidebars, or undefined to create a fully autogenerated sidebar.
sidebarCollapsiblebooleantrue侧边栏类别是否默认可折叠。 See also Collapsible categories
sidebarCollapsedbooleantrue侧边栏类别是否默认被折叠。 See also Expanded categories by default
sidebarItemsGeneratorSidebarGeneratorOmittedFunction used to replace the sidebar items of type 'autogenerated' with real sidebar items (docs, categories, links...). See also Customize the sidebar items generator
numberPrefixParserboolean | PrefixParserOmitted自定义从文件名中提取数字前缀的逻辑。 Use false to disable this behavior and leave the docs untouched, and true to use the default parser. See also Using number prefixes
docLayoutComponentstring'@theme/DocPage'每个文档页面的根布局组件。 提供了版本的数据 context,不会在切换文档时卸载。
docItemComponentstring'@theme/DocItem'文档主容器,包括了目录、页面导航等。
docTagsListComponentstring'@theme/DocTagsListPage'标签列表页的根组件
docTagDocListComponentstring'@theme/DocTagDocListPage'「包含某标签的所有文档」页面的根组件。
docCategoryGeneratedIndexComponentstring'@theme/DocCategoryGeneratedIndexPage'自动生成类别索引页的根组件。
remarkPluginsany[][]传递给 MDX 的 Remark 插件。
rehypePluginsany[][]传递给 MDX 的 Rehype 插件。
beforeDefaultRemarkPluginsany[][]在 Docusaurus 默认 Remark 插件之前传递给 MDX 的自定义 Remark 插件。
beforeDefaultRehypePluginsany[][]在 Docusaurus 默认 Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。
showLastUpdateAuthorbooleanfalse是否显示最后更新文档的作者。
showLastUpdateTimebooleanfalseWhether to display the last date the doc was updated.
disableVersioningbooleanfalse即使存在多个版本,也明确禁用分版功能。 这会让网站只包含当前版本。 Will error if includeCurrentVersion: false and disableVersioning: true.
includeCurrentVersionbooleantrue包含文档的当前版本。
lastVersionstringFirst version in versions.json文档类的导航栏项会默认显示并跳转到的文档版本。
onlyIncludeVersionsstring[]所有版本只包含所有可用版本中的一个子集。
versionsVersionsConfig{}独立自定义每个版本的属性。

Types

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.io/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};

Example configuration

你可以通过预设选项或插件选项来配置这个插件。

提示

大多数 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};
},
docLayoutComponent: '@theme/DocPage',
docItemComponent: '@theme/DocItem',
remarkPlugins: [require('remark-math')],
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 documents can use the following Markdown front matter metadata fields, enclosed by a line --- on either side.

接受的字段:

参数类型默认值描述
idstring文件路径(包括文件夹,不含扩展名)文档的唯一 ID。
titlestringMarkdown title or id你的文档使用的文本标题。 用于页面元数据和多个地方的备用值(侧边栏、下篇/上篇按钮……)。 如果 Markdown 内容没有标题,它会被自动添加到你的文档顶部。
pagination_labelstringsidebar_label or title这篇文档在上一篇/下一篇按钮中显示的文本
displayed_sidebarstringundefinedForce the display of a given sidebar when browsing the current document. Read the multiple sidebars guide for details.
hide_titlebooleanfalse是否隐藏文档顶部显示的标题。 此选项只会隐藏前言中定义的标题,对于 Markdown 文档顶部的标题没有任何影响。
hide_table_of_contentsbooleanfalse是否隐藏右侧的文档目录。
toc_min_heading_levelnumber2目录中显示的最小标题层级。 必须介于 2 到 6 之间,并且小于等于最大值。
toc_max_heading_levelnumber3目录中显示的最大标题层级。 必须介于 2 和 6。
pagination_nextstring | null侧边栏的下一个文档「下篇文档」按钮链接到的文档 ID。 Use null to disable showing "Next" for this page.
pagination_prevstring | null侧边栏的上一个文档「上篇文档」按钮链接到的文档 ID。 Use null to disable showing "Previous" for this page.
parse_number_prefixesbooleannumberPrefixParser plugin option是否禁用本文档的数字前缀解析。 See also Using number prefixes.
custom_edit_urlstringComputed using the editUrl plugin option编辑此文档时要跳转到的 URL。
keywordsstring[]undefined用于搜索引擎优化的文档关键词元标签。
descriptionstringMarkdown 正文的第一行The description of your document, which will become the <meta name="description" content="..."/> and <meta property="og:description" content="..."/> in <head>, used by search engines.
imagestringundefined显示文档链接时所用的缩略图或封面。
slugstring文件路径Allows to customize the document URL (/<routeBasePath>/<slug>). Support multiple patterns: slug: my-doc, slug: /my/path/myDoc, slug: /.
tagsTag[]undefinedA list of strings or objects of two string fields label and permalink to tag to your docs.
draftbooleanfalse一个布尔值,表明文档处于未完成状态。 文档草稿只会在开发模式下显示。
last_updateFileChangeundefined允许覆盖最后更新的作者、日期。 Date can be any parsable date string.
type Tag = string | {label: string; permalink: string};
type FileChange = {date: string; author: 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
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

i18n

Read the i18n introduction first.

Translation files location

  • Base path: website/i18n/[locale]/docusaurus-plugin-content-docs
  • Multi-instance path: website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]

Example file-system structure

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