跳转至主内容
Version: 2.0.0-beta.0

📦 plugin-content-docs

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

安装#

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

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

配置#

docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
/**
* 相对于站点目录的文件系统数据目录。
*/
path: 'docs',
/**
* 编辑您的站点的基本网址。
* Docusaurus 将使用 "editUrl + relativeDocPath" 来自动计算最终的 editUrl
*/
editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
/**
* 您也可以自己根据每个 Markdown 文件进行编辑 Url。
*/
editUrl: function ({
locale,
version,
versionDocsDirPath,
docPath,
permalink,
}) {
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
},
/**
* 若您提交本地化文件到 Git,此选项将十分有用。
* 本地化 Markdown 文件后,编辑 URl 将指定为本地化后的文件,
* 而非未本地化的原始文件。
* 注:当 editUrl 为函数时,此选项将被自动忽略。
*/
editLocalizedFiles: false,
/**
* 若您不希望用户向旧版本提交文档合并请求,此选项将十分有用。
* 当文档存在不同版本时,编辑链接将指向
* 当前版本,而非其他版本。
* 注:当 editUrl 为函数时,此选项将被自动忽略
*/
editCurrentVersion: false,
/**
* 您站点文档部分的 URL 路由。
* *请务必不要*添加斜杠。
* 注:您可以设置为 `/` 以在根目录提供文档。
*/
routeBasePath: 'docs',
include: ['**/*.md', '**/*.mdx'], // 要包括的文件扩展名。
/**
* 用于显示 Markdown 页面列表的侧边栏配置路径。
*/
sidebarPath: 'sidebars.js',
/**
* 用于将“自动生成”的侧边栏项目替换成真正的内容
* (文档、类别、链接……)
*/
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,
/**
* 默认情况下,分版站点将自动启用文档分版功能。
* 这是用于关闭分版功能的选项。
*/
disableVersioning: false,
/**
* 当分版功能启用时,跳过下一个发行版的文档。
* Docusaurus 将不再为生产环境生成位于 `/docs/next` 中的
* HTML 文件,而仅仅生成分版文档。
*/
excludeNextVersionDocs: false,
/**
* 分版站点中,我们优先浏览最新版本。
* 文档导航栏中也默认显示最新版本。
* 默认情况下,versions.json 中最新版本最先出现。
* 默认情况下,最新版本位于根目录(文档则位于 path=/docs/myDoc)
* 注:您可配置最新版本的路径及标签。
* 提示:大多情况下,您可使用 lastVersion: 'current'。
*/
lastVersion: undefined,
/**
* Docusaurus 的分版不适合大多项目。
* 因此,此选项可让您自定义每个版本的标签及路径。
*/
versions: {
/*
示例配置:
current: {
label: 'Android SDK v2.0.0(未完成)',
path: 'android-2.0.0',
},
'1.0.0': {
label: 'Android SDK v1.0.0',
path: 'android-1.0.0',
},
*/
},
/**
* 有时候,您只想包括一部分版本。
* 提示:将其限制在 2 个或 3 个版本以缩短开发环境及部署预览时的启动及构建时间。
*/
onlyIncludeVersions: undefined, // 例:["current", "1.0.0", "2.0.0"]
},
],
],
};

Markdown 前言#

Markdown 文档可使用以下元数据字段,由上下方的 --- 所包裹:

  • id:文档的唯一 ID。 若此字段不存在,则该文档的 id 将默认为它的文件名(不带扩展名)。
  • title:文档标题。 若此字段不存在,文档的 title 将默认为 id。
  • hide_title:是否隐藏文档顶部的标题。 默认情况下为 false。
  • hide_table_of_contents - 是否隐藏右侧的目录。 默认情况下为 false。
  • sidebar_label:在文档侧边栏及此文档的下篇/上篇文档按钮中所显示的标签文本。 若此字段不存在,文档的 sidebar_label 将默认为 title。
  • sidebar_position:当使用 autogenerated 侧边栏项目时,允许控制文档在生成的侧边栏片段内的位置。 可以是整数或浮点数。
  • parse_number_prefixes:当文档包含数字前缀(001 - My Doc.md, 2. MyDoc.md...)时,它会自动被 numberPrefixParser 解析提取,而数字前缀会被用作 sidebar_position。 使用 parse_number_prefix: false 来禁用此文档中的数字前缀解析。
  • custom_edit_url:编辑此文档的网址。 若此字段不存在,文档的编辑网址将默认为传递至 docusaurus-plugin-content-docs 的设置字段 editUrl。
  • keywords:用于搜索引擎优化的文档页关键词元标签。
  • description:文档描述,即位于 <head> 中的 <meta name="description" content="..."/> 及 <meta property="og:description" content="..."/>,用于搜索引擎优化。 若此字段不存在,则将默认为正文内容的第一行。
  • image:显示文档链接时所用的缩略图或封面。
  • slug:允许自定义文档链接 (<routeBasePath><slug>) 支持多种方式: slug: my-doc, slug: /my/path/myDoc, slug: /

Example:

---
id: doc-markdown
title: Markdown 功能特性
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown :)
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
description: 我没法解决问题时该怎么联系你
keywords:
- 文档
- Docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
---
我的 Markdown 文档内容

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/<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