📦 plugin-content-docs
Docusaurus 默认的文档插件，其提供文档功能。
安装#
- npm
- Yarn
npm install --save @docusaurus/plugin-content-docsyarn add @docusaurus/plugin-content-docstip
若您已安装 @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-markdowntitle: Markdown 功能特性hide_title: falsehide_table_of_contents: falsesidebar_label: Markdown :)custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.mddescription: 我没法解决问题时该怎么联系你keywords: - 文档 - Docusaurusimage: https://i.imgur.com/mErPwqL.pngslug: /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