📦 plugin-content-docs
Docusaurus 默认的文档插件,其提供文档功能。
#
安装- npm
- Yarn
npm install --save @docusaurus/plugin-content-docs
yarn add @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-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