# Docusaurus352 **Repository Path**: renlangman2/docusaurus352 ## Basic Information - **Project Name**: Docusaurus352 - **Description**: 原博主[愧怍](https://kuizuo.cn/) ,文章：[Docusaurus 主题魔改](https://kuizuo.cn/docs/docusaurus-guides/) 的[公开仓库](https://github.com/kuizuo/blog) 用pnpm构建失败,尝试修改为yarn4.1.1 + docusaurus3.5.2 的一些实践，docs文档与blog文件夹内容依旧 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: https://kuizuo.cn/docs/docusaurus-guides/ - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-08-18 - **Last Updated**: 2024-10-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## One-Docusaurus 关于此开源项目的说明文档，请看如下链接： 《One-Docusuaus》 ![image-20240822232336756](https://onedayxyy.cn/images/image-20240822232336756.png) ## md文件的前缀信息 --- --- # plugin-content-docs 提供 [文档](https://docusaurus.nodejs.cn/docs/docs-introduction) 功能，是 Docusaurus 的默认文档插件。 ## 安装 ```bash yarn add @docusaurus/plugin-content-docs ``` 提示 如果你使用预设 `@docusaurus/preset-classic`，则无需安装此插件作为依赖。 你可以通过 [预设选项](https://docusaurus.nodejs.cn/docs/using-plugins#docusauruspreset-classic).conf 配置该插件。 ## 配置 接受的字段： | 名称 | 类型 | 默认 | 描述 | | ------------------------------------ | ------------------------------------- | ---------------------------------------- | ------------------------------------------------------------ | | `path` | `string` | `'docs'` | 文件系统上文档内容目录的路径，相对于站点目录。 | | `editUrl` | `string | EditUrlFunction` | `undefined` | 用于编辑站点的基本 URL。最终 URL 由 `editUrl + relativeDocPath` 计算。使用函数可以对每个文件进行更细致的控制。完全省略此变量将禁用编辑链接。 | | `editLocalizedFiles` | `boolean` | `false` | 编辑 URL 将定位本地化文件，而不是原始的未本地化文件。当 `editUrl` 是函数时被忽略。 | | `editCurrentVersion` | `boolean` | `false` | 编辑 URL 将始终针对当前版本文档而不是旧版本。当 `editUrl` 是函数时被忽略。 | | `routeBasePath` | `string` | `'docs'` | 你网站的文档部分的 URL 路由。不要包含尾部斜杠。使用 `/` 发送没有基本路径的文档。 | | `tagsBasePath` | `string` | `'tags'` | 你网站的标签列表页面的 URL 路由。它位于 `routeBasePath` 之前。 | | `include` | `string[]` | `['**/*.{md,mdx}']` | 与要构建的 Markdown 文件相匹配的 glob 模式数组，相对于内容路径。 | | `exclude` | `string[]` | 查看示例配置 | 与要排除的 Markdown 文件匹配的 glob 模式数组。用作基于 `include` 选项的细化。 | | `sidebarPath` | `false | string` | `undefined` | 侧边栏配置的路径。使用 `false` 禁用侧边栏，或使用 `undefined` 创建完全自动生成的侧边栏。 | | `sidebarCollapsible` | `boolean` | `true` | 侧边栏类别默认情况下是否可折叠。另见 [可折叠类别](https://docusaurus.nodejs.cn/docs/sidebar/items#collapsible-categories) | | `sidebarCollapsed` | `boolean` | `true` | 侧边栏类别是否默认折叠。另见 [默认扩展类别](https://docusaurus.nodejs.cn/docs/sidebar/items#expanded-categories-by-default) | | `sidebarItemsGenerator` | `SidebarGenerator` | 省略 | 用于将 `'autogenerated'` 类型的侧边栏项目替换为真实侧边栏项目（文档、类别、链接...）的函数。另见 [自定义侧边栏项目生成器](https://docusaurus.nodejs.cn/docs/sidebar/autogenerated#customize-the-sidebar-items-generator) | | `numberPrefixParser` | `boolean | PrefixParser` | 省略 | 自定义解析逻辑从文件名中提取数字前缀。使用 `false` 禁用此行为并保持文档不变，使用 `true` 使用默认解析器。另见 [使用数字前缀](https://docusaurus.nodejs.cn/docs/sidebar/autogenerated#using-number-prefixes) | | `docsRootComponent` | `string` | `'@theme/DocsRoot'` | 所有文档插件页面（包括所有版本）的父组件。在文档页面和版本之间导航时保持安装状态。 | | `docVersionRootComponent` | `string` | `'@theme/DocVersionLayout'` | 单个版本的所有文档页面的父组件（带有侧边栏的文档页面、标签页面）。在该特定版本的页面之间导航时保持安装状态。 | | `docRootComponent` | `string` | `'@theme/DocRoot'` | 所有带有侧边栏的文档页面的父组件（常规文档页面、类别生成的索引页面）。在此类页面之间导航时保持安装状态。 | | `docItemComponent` | `string` | `'@theme/DocItem'` | 主文档容器，包含目录、分页等。 | | `docTagsListComponent` | `string` | `'@theme/DocTagsListPage'` | 标签列表页面的根组件 | | `docTagDocListComponent` | `string` | `'@theme/DocTagDocListPage'` | "包含标签 X 的文档" 页面的根组件。 | | `docCategoryGeneratedIndexComponent` | `string` | `'@theme/DocCategoryGeneratedIndexPage'` | 生成的类别索引页的根组件。 | | `remarkPlugins` | `any[]` | `[]` | 备注传递给 MDX 的插件。 | | `rehypePlugins` | `any[]` | `[]` | Rehype 插件传递给 MDX。 | | `rehypePlugins` | `any[]` | `[]` | 传递给 MDX 的 Recma 插件。 | | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | 自定义 Remark 插件在默认 Docusaurus Remark 插件之前传递到 MDX。 | | `beforeDefaultRehypePlugins` | `any[]` | `[]` | 自定义 Rehype 插件在默认 Docusaurus Rehype 插件之前传递到 MDX。 | | `showLastUpdateAuthor` | `boolean` | `false` | 是否显示最后更新文档的作者。 | | `showLastUpdateTime` | `boolean` | `false` | 是否显示文档的最后更新日期。这需要在构建期间访问 git 历史记录，因此无法与浅克隆（CI 系统的常见默认设置）一起正常工作。使用 GitHub `actions/checkout`，使用 `fetch-depth: 0`。 | | `breadcrumbs` | `boolean` | `true` | 启用或禁用文档页面上的面包屑。 | | `disableVersioning` | `boolean` | `false` | 即使存在多个版本，也应显式禁用版本控制。这将使该网站仅包含当前版本。如果 `includeCurrentVersion: false` 和 `disableVersioning: true` 将会出错。 | | `includeCurrentVersion` | `boolean` | `true` | 包括文档的当前版本。 | | `lastVersion` | `string` | `versions.json` 年的第一个版本 | 文档导航栏项目优先导航到并默认显示的版本。 | | `onlyIncludeVersions` | `string[]` | 所有版本均可用 | 仅包含所有可用版本的子集。 | | `versions` | `VersionsConfig` | `{}` | 独立定制每个版本的属性。 | | `tags` | `string | false | null | undefined` | `tags.yml` | 列出预定义标签的 YAML 文件的路径。相对于文档版本内容目录。 | | `onInlineTags` | `'ignore' | 'log' | 'warn' | 'throw'` | `warn` | 当文档包含内联标签（未出现在预定义标签列表中，通常为 `docs/tags.yml`）时的插件行为。 | ### 类型 #### `EditUrlFunction` ```ts type EditUrlFunction = (params: { version: string; versionDocsDirPath: string; docPath: string; permalink: string; locale: string; }) => string | undefined; ``` #### `PrefixParser` ```ts type PrefixParser = (filename: string) => { filename: string; numberPrefix?: number; }; ``` #### `SidebarGenerator` ```ts 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; 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.nodejs.cn/docs/sidebar/items }) => Promise; 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` ```ts 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 element of each doc */ className?: string; }; type VersionsConfig = {[versionName: string]: VersionConfig}; ``` ### 配置示例 你可以通过预设选项或插件选项配置此插件。 提示 大多数 Docusaurus 用户通过预设选项配置此插件。 - Preset options - Plugin options If you use a preset, configure this plugin through the [preset options](https://docusaurus.nodejs.cn/docs/using-plugins#docusauruspreset-classic): docusaurus.config.js ```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}; }, docsRootComponent: '@theme/DocsRoot', docVersionRootComponent: '@theme/DocVersionRoot', docRootComponent: '@theme/DocRoot', docItemComponent: '@theme/DocItem', remarkPlugins: [require('./my-remark-plugin')], 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'], }, }, ], ], }; ``` ```txt --- id:{id} //唯一的文档id，默认为文件夹+文件名称不带扩展名 --- ``` ## Markdown 前言 Markdown 文档可以使用以下 Markdown [头条新闻](https://docusaurus.nodejs.cn/docs/markdown-features#front-matter) 元数据字段，两侧用 `---` 行括起来。 接受的字段： | 名称 | 类型 | 默认 | 描述 | | ------------------------ | ----------------------- | ---------------------------------- | ------------------------------------------------------------ | | `id` | `string` | 文件路径（包括文件夹，不带扩展名） | 唯一的文档 ID。 | | `title` | `string` | Markdown 标题或 `id` | 文档的文本标题。用于页面元数据并作为多个位置的后备值（侧边栏、下一个/上一个按钮...）。如果文档不包含任何 Markdown 标题，则会自动添加到文档顶部。 | | `pagination_label` | `string` | `sidebar_label` 或 `title` | 本文档的下一个/上一个按钮中使用的文本。 | | `sidebar_label` | `string` | `title` | 本文档的文档侧栏中显示的文本。 | | `sidebar_position` | `number` | 默认排序 | 使用 `autogenerated` 侧边栏项目时控制文档在生成的侧边栏切片内的位置。另见 [自动生成的侧边栏元数据](https://docusaurus.nodejs.cn/docs/sidebar/autogenerated#autogenerated-sidebar-metadata)。 | | `sidebar_class_name` | `string` | `undefined` | 使用自动生成的侧边栏时，为相应的侧边栏标签指定一个特殊的类名称。 | | `sidebar_custom_props` | `object` | `undefined` | 将 [定制属性](https://docusaurus.nodejs.cn/docs/sidebar#passing-custom-props) 分配给引用此文档的侧边栏项目 | | `displayed_sidebar` | `string` | `undefined` | 浏览当前文档时强制显示给定的侧边栏。详细信息请阅读 [多个侧边栏指南](https://docusaurus.nodejs.cn/docs/sidebar/multiple-sidebars)。 | | `hide_title` | `boolean` | `false` | 是否隐藏文档顶部的标题。它仅隐藏通过前面内容声明的标题，并且对文档顶部的 Markdown 标题没有影响。 | | `hide_table_of_contents` | `boolean` | `false` | 是否隐藏右侧目录。 | | `toc_min_heading_level` | `number` | `2` | 目录中显示的最低标题级别。必须介于 2 到 6 之间且小于或等于最大值。 | | `toc_max_heading_level` | `number` | `3` | 目录中显示的最大标题级别。必须在 2 到 6 之间。 | | `pagination_next` | `string | null` | 侧边栏中的下一个文档 | 你希望 "下一个" 分页链接到的文档的 ID。使用 `null` 禁止显示该页面的 "下一个"。 | | `pagination_prev` | `string | null` | 侧边栏中的上一个文档 | 你希望 "以前的" 分页链接到的文档的 ID。使用 `null` 禁止显示该页面的 "以前的"。 | | `parse_number_prefixes` | `boolean` | `numberPrefixParser` 插件选项 | 此文档是否禁用数字前缀解析。另见 [使用数字前缀](https://docusaurus.nodejs.cn/docs/sidebar/autogenerated#using-number-prefixes)。 | | `custom_edit_url` | `string | null` | 使用 `editUrl` 插件选项计算 | 用于编辑此文档的 URL。使用 `null` 禁止显示该页面的 "编辑这个页面"。 | | `keywords` | `string[]` | `undefined` | 文档页面的关键字元标记，用于搜索引擎。 | | `description` | `string` | 第一行 Markdown 内容 | 你的文档的描述，将成为 `` 中的 `` 和 ``，供搜索引擎使用。 | | `image` | `string` | `undefined` | 将用作 `` 中的 `` 的封面或缩略图，增强社交媒体和消息平台上的链接预览。 | | `slug` | `string` | 文件路径 | 允许自定义文档 URL (`//`)。支持多种模式：`slug: my-doc`、`slug: /my/path/myDoc`、`slug: /`。 | | `tags` | `Tag[]` | `undefined` | 要标记到你的文档的两个字符串字段 `label` 和 `permalink` 的字符串或对象的列表。字符串可以是对 [标签文件](https://docusaurus.nodejs.cn/docs/api/plugins/@docusaurus/plugin-content-docs#tags-file)（通常是 `tags.yml`）的键的引用 | | `draft` | `boolean` | `false` | 草稿文件仅在开发期间可用。 | | `unlisted` | `boolean` | `false` | 未列出的文件将在开发和生产过程中提供。它们在生产中将是 "hidden"，未编入索引，从站点地图中排除，并且只能由具有直接链接的用户访问。 | | `last_update` | `FrontMatterLastUpdate` | `undefined` | 允许覆盖上次更新作者/日期。日期可以是任意 [可解析的日期字符串](https://web.nodejs.cn/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse)。 | ```ts type FrontMatterLastUpdate = {date?: string; author?: string}; type Tag = string | {label: string; permalink: string}; ``` 示例： ```md --- 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 tags: [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 ``` ## 标签文件 使用 [`tags` 插件选项](https://docusaurus.nodejs.cn/docs/api/plugins/@docusaurus/plugin-content-docs#tags) 配置 YAML 标签文件的路径。 按照惯例，插件将在你的内容文件夹的根目录中查找 `tags.yml` 文件。 此文件可以包含预定义标签列表。借助 [`tags` 前言](https://docusaurus.nodejs.cn/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter)，你可以在 Markdown 文件中通过它们的键引用这些标签。 保持标签一致 使用标签文件，你可以确保你的标签使用在整个插件内容集中保持一致。使用 [`onInlineTags: 'throw'`](https://docusaurus.nodejs.cn/docs/api/plugins/@docusaurus/plugin-content-docs#onInlineTags) 插件选项来强制这种一致性并防止使用动态声明的内联标签。 ### 类型 提供的标签文件的 YAML 内容应遵循以下形状： ```tsx type Tag = { label?: string; // Tag display label permalink?: string; // Tag URL pathname segment description?: string; // Tag description displayed in the tag page }; type TagsFileInput = Record | null>; ``` ### 示例 tags.yml ```yml releases: label: 'Product releases' permalink: '/product-releases' description: 'Content related to product releases.' # A partial tag definition is also valid announcements: label: 'Announcements' # An empty tag definition is also valid # Other attributes will be inferred from the key emptyTag: ``` content.md ```md --- tags: [releases, announcements, emptyTag] --- # Title Content ``` ## 国际化 首先阅读 [国际化介绍](https://docusaurus.nodejs.cn/docs/i18n/introduction)。 ### 翻译文件位置 - 基本路径：`website/i18n/[locale]/docusaurus-plugin-content-docs` - 多实例路径：`website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]` - JSON 文件：用 [`docusaurus write-translations`](https://docusaurus.nodejs.cn/docs/cli#docusaurus-write-translations-sitedir) 提取 - Markdown 文件：`website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]` ### 文件系统结构示例 ```bash 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 ```