跳到主要内容
版本：3.5.2

📦 plugin-content-docs

提供 文档 功能，是 Docusaurus 预设的文档插件。

安装​

npm install --save @docusaurus/plugin-content-docs
提示

如果您使用预设 @docusaurus/preset-classic，则不需要将此插件安装为相依项。

您可以透过 预设选项 来配置此插件。

組態​

可接受的欄位

名稱類型預設值說明
路徑字串'docs'相對於站台目錄的檔案系統上文件內容目錄的路徑。
編輯網址字串 | EditUrlFunction未定義用以編輯您的站台的基本網址。最終網址會透過 編輯網址 +相對文件路徑 計算得出。使用函式時，可以針對個別檔案進行更細緻的控制。完全省略這個變數則會停用編輯連結。
編輯在地化檔案布林值false編輯網址將針對在地化檔案，而非原始未在地化的檔案。在 編輯網址 是函式時會忽略。
編輯目前版本布林值false編輯網址將總是指向目前版本的文件，而非舊版本。在 編輯網址 是函式時會忽略。
路線基本路徑字串'docs'站台文件部分的網址路線。不要包含尾部斜線。對於沒有基本路徑的運送文件，請使用 /。
標籤基本路徑字串'tags'站台標籤清單頁面的網址路線。會加在 路線基本路徑 前面。
包含字串陣列['**/*.{md,mdx}']與內容路徑相對，與符合所建立 Markdown 檔案的 glob 模式陣列。
排除字串陣列參閱範例組態與應排除的 Markdown 檔案相對的 glob 模式陣列。根據 包含 選項進一步微調。
側邊欄路徑false | 字串未定義側邊欄組態的路徑。使用 false 停用側邊欄，或使用 undefined 建立一個完全自動產生的側邊欄。
側邊欄可摺疊布林值true預設是否將側邊欄類別進行摺疊。另見 可摺疊類別
側邊欄已摺疊布林值true預設是否將側邊欄類別摺疊。另見 預設展開類別
側邊欄項目產生器SidebarGenerator省略用於將類型為 'autogenerated' 的按鈕項目替換為真正的按鈕項目（文件、類別、連結...）的函式。另見 自訂側邊欄項目產生器
數字字首剖析器布林值 | PrefixParser省略從檔案名稱摘取數字字首的自訂剖析邏輯。使用 false 停用這個行為並保留文件不變，使用 true 套用預設的剖析器。另見 使用數字字首
文件根元件字串'@theme/DocsRoot'所有文件外掛頁面（包含所有版本）的父元件。在文件頁面和版本間導覽時會保持掛載。
文件版本根元件字串'@theme/DocVersionLayout'所有文件中個別版本的文件頁面父層元件（帶有側邊欄的文件頁面、標籤頁面）。當在特定版本頁面之間導覽時，維持掛載狀態。
docRootComponent字串'@theme/DocRoot'所有帶有側邊欄的文件頁面父層元件（一般文件頁面、類別產生的索引頁面）。當在這些頁面之間導覽時，維持掛載狀態。
docItemComponent字串'@theme/DocItem'主文件容器，包含目錄、分頁等。
docTagsListComponent字串'@theme/DocTagsListPage'標籤清單頁面根層元件
docTagDocListComponent字串'@theme/DocTagDocListPage'"包含標籤 X 的文件" 頁面根層元件。
docCategoryGeneratedIndexComponent字串'@theme/DocCategoryGeneratedIndexPage'產生的類別索引頁面根層元件。
remarkPluginsany[][]傳遞給 MDX 的備註外掛程式。
rehypePluginsany[][]傳遞給 MDX 的 Rehype 外掛程式。
rehypePluginsany[][]傳遞給 MDX 的 Recma 外掛程式。
beforeDefaultRemarkPluginsany[][]在預設 Docusaurus 備註外掛程式之前傳遞給 MDX 的自訂備註外掛程式。
beforeDefaultRehypePluginsany[][]在預設 Docusaurus Rehyp 外掛程式之前傳遞給 MDX 的自訂 Rehype 外掛程式。
showLastUpdateAuthor布林值false是否顯示最後更新文件的作者。
showLastUpdateTime布林值false是否顯示文件的最後更新日期。這需要在建置過程中存取 git 歷程記錄，因此無法正確使用淺層類節（CI 系統的常見預設）。使用 GitHub actions/checkout 時，請使用 fetch-depth: 0。
disableVersioning布林值false即使存在多個版本，仍明確停用版本控制。這將使網站僅包含最新版本。如果 includeCurrentVersion: false 且 disableVersioning: true，則會傳回錯誤訊息。
includeCurrentVersion布林值true包含目前版本的文件。
lastVersion字串versions.json 中的第一個版本。導覽時優先顯示且在文件導覽列項目中預設顯示的版本。
onlyIncludeVersions字串陣列所有可用版本。僅包含所有可用版本中的一部分。
versionsVersionsConfig{}獨立自訂每種版本的屬性。
tags字串 | false | null | 未定義tags.yml列出預先定義標籤的 YAML 檔案路徑。相對於文件版本內容目錄。
onInlineTags'忽略' | '紀錄' | '警告' | '擲回'警告文件包含內嵌標籤（未出現在預先定義標籤清單中，通常是 docs/tags.yml）時的附加元件行為。

類型​

編輯網址函式​

type EditUrlFunction = (params: {
  version: string;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

字首解析器​

type PrefixParser = (filename: string) => {
  filename: string;
  numberPrefix?: number;
};

SidebarGenerator​

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<string, unknown>;
    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.dev.org.tw/docs/sidebar/items
}) => Promise<SidebarItem[]>;

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​

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 <html> element of each doc */
  className?: string;
};

type VersionsConfig = {[versionName: string]: VersionConfig};

範例組態​

您可以透過預設選項或外掛程式選項來組態這個外掛程式。

提示

大多數 Docusaurus 使用者會透過預設選項來組態這個外掛程式。

如果您使用預設值，請透過 預設選項 來組態這個外掛程式

docusaurus.config.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'],
        },
      },
    ],
  ],
};

Markdown 前置資訊​

Markdown 文件可以使用下列的 Markdown 前置資訊 欄位，並在兩側以 --- 行包住。

可接受的欄位

名稱類型預設值說明
id字串檔案路徑（包括資料夾，不含副檔名）文件識別碼。
title字串Markdown 標題或 id文件文字標題。用於頁面資料，並在許多地方中作為後備值（側欄、上一個/下一個按鈕...）。若您的文件中沒有包含 Markdown 標題，將自動加入在文件開頭。
pagination_label字串sidebar_label 或 title在此文件的上一個/下一個按鈕上使用的文字。
displayed_sidebar字串未定義瀏覽當前文件時強制顯示特定的側欄。閱讀 多個側欄指南 取得詳細資訊。
hide_title布林值false是否要隱藏文件頂端的標題。它只會隱藏透過前置資訊宣告的標題，對文件開頭的 Markdown 標題不具有效果。
hide_table_of_contents布林值false是否要隱藏右側的目錄。
toc_min_heading_level數字2目錄中所顯示的最小標題層級。必須介於 2 至 6 之間，且小於或等於最大值。
toc_max_heading_level數字3顯示於目錄中的最大標題層級。必須介於 2 至 6 之間。
pagination_next字串 | 無側邊欄中的下一個文件此文件所連結的「下一頁」分頁之文件 ID。若要停用顯示此頁面的「下一頁」，請使用 `null`。
pagination_prev字串 | 無側邊欄中的前一個文件此文件所連結的「前一頁」分頁之文件 ID。若要停用顯示此頁面的「前一頁」，請使用 `null`。
parse_number_prefixes布林值numberPrefixParser 外掛程式選項是否停用這份文件中的數字前綴分析。另請參閱 使用數字前綴。
custom_edit_url字串 | 無使用 editUrl 外掛程式選項計算編輯此文件的 URL。若要停用顯示此頁面的「編輯此頁面」，請使用 `null`。
keywords字串陣列未定義文件的頁面供搜尋引擎使用的「關鍵字」meta 標籤。
description字串Markdown 內容的第一行文件說明，內容會轉為 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/>，放在 <head> 中，供搜尋引擎使用。
image字串未定義封面或縮圖圖片，會作為 <meta property="og:image" content="..."/> 中 <head> 的圖片，加強連結在社群媒體和訊息平台上的預覽效果。
slug字串檔案路徑允許自訂文件 URL (/<routeBasePath>/<slug>)。支援多個模式：slug: my-doc、slug: /my/path/myDoc、slug: /。
tagsTag[]未定義字串或兩個字串欄位物件的清單（標籤及固定連結），可加註到您的文件。字串可做為 標籤檔案 （通常為 tags.yml）金鑰的參考。
draft布林值false草稿文件僅會在開發期間提供。
unlisted布林值false未列出的文件在開發及製作過程中皆可使用。它們會在製作過程中「隱藏」，不建立索引，排除在網站地圖之外，且僅允許擁有直接連結的使用者存取。
last_updateFrontMatterLastUpdate未定義允許覆寫最後更新的作者/日期。日期可以是任何 可解析的日期字串。
type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

範例

---
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 外掛程式選項 設定 YAML 標籤檔案的路徑。

依慣例，外掛程式會在您的內容資料夾根目錄尋找 tags.yml 檔案。

此檔案包含預定義標籤清單。在 Markdown 檔案中，您可以透過 tags front matter 透過金鑰參照這些標籤。

維持標籤一致

使用標籤檔案，您可以確保您的標籤使用在您的外掛程式內容集上是一致的。使用 onInlineTags: 'throw' 外掛程式選項來強制執行這種一致性，並防止使用即時宣告的內嵌標籤。

類型​

提供的標籤檔案的 YAML 內容應符合以下形式

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<string, Partial<Tag> | null>;

範例​

tags.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
---
tags: [releases, announcements, emptyTag]
---

# Title

Content

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/[versionName]

範例檔案系統結構​

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
編輯此頁面
最近更新在 由 Sébastien Lorber 更新。