メインコンテンツへスキップ
バージョン: 3.5.2

📦 plugin-content-docs

ドキュメント機能を提供し、Docusaurusのデフォルトのドキュメントプラグインです。

インストール​

npm install --save @docusaurus/plugin-content-docs
ヒント

プリセット @docusaurus/preset-classic を使用している場合、このプラグインを依存関係としてインストールする必要はありません。

プリセットオプションを使用して、このプラグインを設定できます。

設定​

受け入れられるフィールド

名前タイプデフォルト説明
pathstring'docs'サイトディレクトリを基準とした、ファイルシステム上のドキュメントコンテンツディレクトリへのパス。
editUrlstring | EditUrlFunctionundefinedサイトを編集するためのベースURL。最終的なURLは editUrl + relativeDocPath によって計算されます。関数を使用すると、各ファイルに対してよりきめ細かい制御が可能になります。この変数を完全に省略すると、編集リンクが無効になります。
editLocalizedFilesbooleanfalse編集URLは、元のローカライズされていないファイルではなく、ローカライズされたファイルをターゲットにします。 editUrl が関数の場合は無視されます。
editCurrentVersionbooleanfalse編集URLは、常に古いバージョンではなく、現在のバージョンのドキュメントをターゲットにします。 editUrl が関数の場合は無視されます。
routeBasePathstring'docs'サイトのドキュメントセクションのURLルート。末尾にスラッシュを含めないでください。ベースパスなしでドキュメントを出荷するには、/ を使用します。
tagsBasePathstringサイトのタグリストページのURLルート。 routeBasePath の前に付加されます。'tags'
includestring[]['**/*.{md,mdx}']コンテンツパスを基準とした、ビルド対象のMarkdownファイルと一致するglobパターンの配列。
excludestring[]string[]除外するMarkdownファイルと一致するglobパターンの配列。 include オプションに基づく絞り込みとして機能します。
sidebarPathfalse | stringundefinedサイドバー設定へのパス。サイドバーを無効にするには false を使用し、完全に自動生成されたサイドバーを作成するには undefined を使用します。
sidebarCollapsiblebooleanbooleanサイドバーカテゴリがデフォルトで折りたたみ可能かどうか。 折りたたみ可能なカテゴリも参照してください。
sidebarCollapsedbooleanbooleanサイドバーカテゴリがデフォルトで折りたたまれているかどうか。 デフォルトで展開されているカテゴリも参照してください
sidebarItemsGeneratorSidebarGenerator省略タイプ 'autogenerated' のサイドバーアイテムを実際のサイドバーアイテム（ドキュメント、カテゴリ、リンクなど）に置き換えるために使用される関数。 サイドバーアイテムジェネレーターのカスタマイズも参照してください
numberPrefixParserファイル名から数値プレフィックスを抽出するためのカスタム解析ロジック。この動作を無効にしてドキュメントをそのままにするには false を使用し、デフォルトのパーサーを使用するには true を使用します。 数値プレフィックスの使用も参照してください省略docsRootComponent
stringstring'@theme/DocsRoot'すべてのドキュメントプラグインページ（すべてのバージョンを含む）の親コンポーネント。ドキュメントページとバージョン間を移動してもマウントされたままになります。
docVersionRootComponentstringstring'@theme/DocVersionLayout'
個々のバージョンのすべてのドキュメントページ（サイドバー付きのドキュメントページ、タグページ）の親コンポーネント。特定のバージョンのページ間を移動してもマウントされたままになります。stringdocPageLayoutComponentサイドバー付きのすべてのドキュメントページ（通常のドキュメントページ、カテゴリ生成されたインデックスページ）の親コンポーネント。そのようなページ間を移動してもマウントされたままになります。
docItemComponentstringstring'@theme/DocItem'
docTagsListComponentstringstring'@theme/DocTagsListPage'
docTagDocListComponentstringstring'@theme/DocTagDocListPage'
docCategoryGeneratedIndexComponentstringstring'@theme/DocCategoryGeneratedIndexPage'
remarkPluginsany[][][]
rehypePluginsany[][]any[]
rehypePluginsany[][]MDXに渡されるRehypeプラグイン。Recma プラグインは MDX に渡されます。
beforeDefaultRemarkPluginsany[][]any[]
beforeDefaultRehypePluginsany[][]デフォルトのDocusaurus Rehypeプラグインの前にMDXに渡されるカスタムRehypeプラグイン。
showLastUpdateAuthorbooleanfalseドキュメントを最後に更新した作成者を表示するかどうか。
showLastUpdateTimebooleanfalseドキュメントが最後に更新された日付を表示するかどうか。これには、ビルド中にgit履歴にアクセスする必要があるため、浅いクローン（CIシステムの一般的なデフォルト）では正しく機能しません。GitHub actions/checkout を使用する場合は、fetch-depth: 0 を使用してください。
disableVersioningbooleanfalse複数のバージョンが存在する場合でも、バージョン管理を明示的に無効にします。これにより、サイトには現在のバージョンのみが含まれるようになります。 includeCurrentVersion: false と disableVersioning: true の場合はエラーになります。
includeCurrentVersionbooleanbooleanドキュメントの現在のバージョンを含めます。
lastVersionstringstring | nullversions.json の最初のバージョン
onlyIncludeVersionsstring[]string[] | null利用可能なすべてのバージョン
versionsVersionsConfig{}{}
tagsstring | false | null | undefined'tags.yml'事前定義されたタグをリストしたYAMLファイルへのパス。ドキュメントバージョンのコンテンツディレクトリを基準とします。
onInlineTags'ignore' | 'log' | 'warn' | 'throw''warn'ドキュメントにインラインタグ（事前定義されたタグのリストに表示されない、通常は docs/tags.yml）が含まれている場合のプラグインの動作。

型​

EditUrlFunction​

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

PrefixParser​

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.dokyumento.jp/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 フロントマターメタデータフィールドを使用できます。

受け入れられるフィールド

名前タイプデフォルト説明
idstringstringファイルパス（フォルダを含む、拡張子を除く）
titlestringstringMarkdownタイトルまたは id
pagination_labelstringstringsidebar_label または title
displayed_sidebarstringundefined現在のドキュメントを参照するときに、指定されたサイドバーを強制的に表示します。詳細は、複数サイドバーガイドをご覧ください。
hide_titlebooleanfalseドキュメントの上部にあるタイトルを非表示にするかどうか。フロントマターで宣言されたタイトルのみを非表示にし、ドキュメントの上部にあるMarkdownタイトルには影響しません。
hide_table_of_contentsbooleanfalse右側の目次を非表示にするかどうか。
toc_min_heading_levelnumber2目次で表示される最小の見出しレベル。2から6の間で、最大値以下である必要があります。
toc_max_heading_levelnumber3目次で表示される最大の見出しレベル。2から6の間である必要があります。
pagination_next文字列 | nullサイドバーの次のドキュメント「次へ」ページネーションのリンク先となるドキュメントのID。このページの「次へ」の表示を無効にするには、nullを使用します。
pagination_prev文字列 | nullサイドバーの前のドキュメント「前へ」ページネーションのリンク先となるドキュメントのID。このページの「前へ」の表示を無効にするには、nullを使用します。
parse_number_prefixesbooleannumberPrefixParser プラグインオプションこのドキュメントで番号プレフィックスの解析が無効になっているかどうか。番号プレフィックスの使用も参照してください。
custom_edit_url文字列 | nulleditUrl プラグインオプションを使用して計算されますこのドキュメントを編集するためのURL。このページの「このページを編集」の表示を無効にするには、nullを使用します。
keywordsstring[]undefined検索エンジン用のドキュメントページのキーワードメタタグ。
descriptionstringMarkdownコンテンツの最初の行ドキュメントの説明。これは、検索エンジンで使用される<head>内の<meta name="description" content="..."/>および<meta property="og:description" content="..."/>になります。
imagestringundefined<head>内の<meta property="og:image" content="..."/>として使用されるカバー画像またはサムネイル画像。ソーシャルメディアやメッセージングプラットフォームでのリンクプレビューを強化します。
slugstringファイルパスドキュメントのURL（/<routeBasePath>/<slug>）をカスタマイズできます。複数の パターンをサポートします：slug: my-doc、slug: /my/path/myDoc、slug: /。
tagsタグ[]undefinedドキュメントにタグ付けするための、文字列のリスト、または2つの文字列フィールドlabelとpermalinkを持つオブジェクトのリスト。文字列はタグファイル（通常はtags.yml）のキーへの参照にすることができます。
draftbooleanfalseドラフトドキュメントは、開発中にのみ利用可能です。
unlistedbooleanfalseリストされていないドキュメントは、開発環境と本番環境の両方で利用できます。本番環境では「非表示」になり、インデックス化されず、サイトマップから除外され、直接リンクを持つユーザーのみがアクセスできます。
last_updateFrontMatterLastUpdateundefined最終更新の作成者/日付を上書きできます。日付は、解析可能な日付文字列であれば何でも構いません。
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

タグファイル​

YAMLタグファイルのパスを設定するには、tags プラグインオプションを使用します。

慣例により、プラグインはコンテンツフォルダのルートにあるtags.ymlファイルを検索します。

このファイルには、事前定義されたタグのリストを含めることができます。tags フロントマターのおかげで、Markdownファイルでこれらのタグをキーで参照できます。

タグの整合性を保つ

タグファイルを使用することで、プラグインコンテンツセット全体でタグの使用に一貫性を持たせることができます。この一貫性を強制し、その場で宣言されたインラインタグの使用を防ぐには、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