MDX と React

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

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

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

例えば、src/theme/MDXComponents.jsx では現在、以下のように登録されています：

import CalsTable from "@site/src/components/CalsTable";
import CodeSnippet from "@site/src/components/CodeSnippet";
import Comment from "@site/src/components/Comment";
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 RelatedTopics from "@site/src/components/RelatedTopics";
import Snippet from "@site/src/components/Snippet";
import VariableSet from "@site/src/components/VariableSet";
import Details from "@theme/Details";
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 React from "react";

// {/* truncate */} is converted to {/* truncate */} by the Markdown preprocessor at build time.
const Truncate = () => null;

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

@site/src/components/ で始まるインポートは、トピック内でレンダリング可能なカスタムコンポーネントです。また、StatusField のように CMS によって使用されるカスタムコンポーネントもあり、これらはインポートする必要はありません。

src/theme/template.jsx ファイルは次のように始まります：

import React from "react";
import codeFiles from "../../reuse/code-files.json";
import { slugify } from "../../util";
import { CalsTableBlockTemplate } from "../components/CalsTable/template";
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,
  CalsTableBlockTemplate,
  CodeSnippetBlockTemplate,
  CommentBlockTemplate,
  ConditionalTextBlockTemplate,
  ContextHelpTemplate,
  DetailsTemplate,
  DocCardListTemplate,
  FigureBlockTemplate,
  FootnoteBlockTemplate,
  GlossaryTermBlockTemplate,
  PassthroughBlockTemplate,
  RelatedTopicsBlockTemplate,
  SnippetBlockTemplate,
  TabsTemplate,
  TruncateTemplate,
  VariableSetBlockTemplate,
];

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

注意

タグ名は大文字で指定してください。

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

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

Passthrough コンポーネント

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

Embed リストから Passthrough を選択します。
Summaryを入力します。
Contentにプレーンテキストを入力します。
Content Type（Markdown、HTML、またはJSX）を選択します。

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

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

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

Passthrough コンポーネント​

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

Passthrough コンポーネント