跳转至主内容
Version: 2.0.0-alpha.73

📦 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: function ({item, version, docs}) {          // Use the provided data to create a custom "sidebar slice"          return [{type: 'doc', id: 'doc1'}];        },        /**         * Theme components used by the docs pages         */        docLayoutComponent: '@theme/DocPage',        docItemComponent: '@theme/DocItem',        /**         * Remark and Rehype plugins passed to MDX         */        remarkPlugins: [          /* require('remark-math') */        ],        rehypePlugins: [],        /**         * Custom Remark and Rehype plugins passed to MDX before         * the default Docusaurus Remark and Rehype plugins.         */        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 侧边栏项目时,允许控制文档在生成的侧边栏片段内的位置。 可以是整数或浮点数。
  • strip_number_prefixes: When a document has a number prefix (001 - My Doc.md, 2. MyDoc.md...), it is automatically removed, and the prefix is used as sidebar_position. Use strip_number_prefixes: false if you want to disable this behavior
  • 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