MDX and React

docStaticはMDXの組み込みサポートを提供しており、MarkdownファイルにJSXを記述してReactコンポーネントとしてレンダリングできます。ただし、JSXをトピックに直接追加した場合、CMSはリッチテキストエディターでそれらを表示できません。

MDXコンポーネントのスコープ

docStaticでMDXのコンポーネントを使用する方法として推奨されるのは、グローバルスコープに登録することです。これにより、インポート文なしですべてのMDXファイルで自動的に利用可能になります。また、CMSがコンポーネントを認識できるように、テンプレート定義をコンポーネントに追加してインポートする必要があります。この方法の例については、CodeSnippet などのdocStatic独自のコンポーネントを参照してください。グローバルコンポーネントは静的にレンダリングされることを確認することが重要です。そうしないと、ページのレンダリングに遅延が発生する可能性があります。

たとえば、src/themes/MDXComponents.jsx の内容は次のとおりです。

import CodeBlock from "@theme-original/CodeBlock";
import DocCardList from "@theme-original/DocCardList";
import MDXComponents from "@theme-original/MDXComponents";
import TabItem from "@theme-original/TabItem";
import Tabs from "@theme-original/Tabs";
import Details from "@theme/Details";
import React from "react";

import CodeSnippet from "@site/src/components/CodeSnippet";
import ConditionalText from "@site/src/components/ConditionalText";
import Figure from "@site/src/components/Figure";
import Footnote from "@site/src/components/Footnote";
import GlossaryTerm from "@site/src/components/GlossaryTerm";
import Passthrough from "@site/src/components/Passthrough";
import Snippet from "@site/src/components/Snippet";
import VariableSet from "@site/src/components/VariableSet";

export default {
  ...MDXComponents,
  Admonition: MDXComponents.admonition,
  CodeBlock: CodeBlock,
  CodeSnippet: CodeSnippet,
  ConditionalText: ConditionalText,
  Details: Details,
  DocCardList: DocCardList,
  Figure: Figure,
  Footnote: Footnote,
  GlossaryTerm: GlossaryTerm,
  Passthrough: Passthrough,
  Snippet: Snippet,
  TabItem: TabItem,
  Tabs: Tabs,
  VariableSet: VariableSet,
};

@site/src/components/ で始まるインポートは、トピックでレンダリングできるカスタムコンポーネントです。StatusFieldなど、CMSが使用するカスタムコンポーネントもありますが、それらはインポートする必要はありません。

src/themes/tempate.jsx ファイルの冒頭は次のとおりです。

import React from "react";
import codeFiles from "../../reuse/code-files.json";
import { slugify } from "../../util";
import { CodeSnippetBlockTemplate } from "../components/CodeSnippet/template";
import { ConditionalTextBlockTemplate } from "../components/ConditionalText/template";
import { FigureBlockTemplate } from "../components/Figure/template";
import { FootnoteBlockTemplate } from "../components/Footnote/template";
import { GlossaryTermBlockTemplate } from "../components/GlossaryTerm/template";
import { PassthroughBlockTemplate } from "../components/Passthrough/template";
import { SnippetBlockTemplate } from "../components/Snippet/template";
import { VariableSetBlockTemplate } from "../components/VariableSet/template";

Details などのネイティブコンポーネントのテンプレートは、ファイル内に直接定義する必要があります。例えば：

const DetailsTemplate = {
  name: "Details",
  fields: [
    {
      name: "summary",
      label: "Summary",
      type: "string",
      isTitle: true,
      required: true,
    },
    {
      name: "children",
      label: "Details",
      type: "rich-text",
    },
  ],
};

ファイルの末尾では、すべてのテンプレートをエクスポートします。

export const MDXTemplates = [
  AdmonitionTemplate,
  CodeSnippetBlockTemplate,
  CommentBlockTemplate,
  ConditionalTextBlockTemplate,
  ContextHelpTemplate,
  DetailsTemplate,
  DocCardListTemplate,
  FigureBlockTemplate,
  FootnoteBlockTemplate,
  GlossaryTermBlockTemplate,
  SnippetBlockTemplate,
  PassthroughBlockTemplate,
  TabsTemplate,
  TruncateTemplate,
  VariableSetBlockTemplate,
];

これで、これらのコンポーネントをあらゆるMDXファイルで使用できるようになります。

注意

タグ名は大文字で始めてください。

MDX v3以降、小文字のタグ名は常にネイティブHTML要素としてレンダリングされ、指定したコンポーネントのマッピングは使用されません。

詳細については、DocusaurusドキュメントのMDX and Reactを参照してください。

Passthroughコンポーネント

CMSのリッチテキストエディターで表示できないHTML、JSX、またはMarkdownをトピックに含める必要がある場合があります。他のコンテンツに対してエディターを引き続き使用できるよう、Passthrough コンポーネントが提供されています。これにより、リッチテキストエディターが実質的に無視するようにコンテンツをラップできます。

埋め込み リストから Passthrough を選択します。
概要（Summary） を設定します。
コンテンツ をプレーンテキストで入力します。
コンテンツタイプ（Markdown、HTML、または JSX）を選択します。

コンテンツは、サイトのビルド時にラッパーなしでページに直接追加されます。

例については、サンプルページと数式を参照してください。

MDXコンポーネントのスコープ​

Passthroughコンポーネント​

MDXコンポーネントのスコープ

Passthroughコンポーネント