MDX und React

docStatic bietet integrierte Unterstützung für MDX, wodurch Sie JSX in Ihren Markdown-Dateien schreiben und als React-Komponenten rendern können. Wenn Sie JSX jedoch direkt in Ihre Themen einfügen, kann das CMS diese nicht im Rich-Text-Editor anzeigen.

MDX-Komponentenbereich

Die empfohlene Vorgehensweise zur Verwendung von MDX-Komponenten in docStatic besteht darin, diese im globalen Bereich zu registrieren, wodurch sie automatisch in jeder MDX-Datei verfügbar sind, ohne dass Import-Anweisungen erforderlich sind. Außerdem musst du der Komponente eine Vorlagendefinition hinzufügen und sie importieren, damit das CMS sie erkennt. Beispiele dafür findest du in den eigenen Komponenten von docStatic, wie beispielsweise CodeSnippet. Es ist wichtig, sicherzustellen, dass globale Komponenten statisch gerendert werden, da sie sonst zu Verzögerungen beim Rendern der Seite führen können.

Beispielsweise registriert src/theme/MDXComponents.jsx derzeit Folgendes:

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,
};

Die Importe, die mit @site/src/components/ beginnen, sind die benutzerdefinierten Komponenten, die in Themen gerendert werden können. Es gibt auch benutzerdefinierte Komponenten, die vom CMS verwendet werden, wie z. B. StatusField, die nicht importiert werden müssen.

Die Datei src/theme/template.jsx beginnt wie folgt:

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";

Vorlagen für native Komponenten, wie z. B. Details, müssen direkt in der Datei definiert werden. Zum Beispiel:

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

Die Datei endet mit dem Export aller Vorlagen:

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

Nun können diese Komponenten in jeder MDX-Datei verwendet werden.

Achtung

Verwenden Sie Tag-Namen in Großbuchstaben.

Ab MDX v3+ werden Tag-Namen in Kleinbuchstaben stets als native HTML-Elemente dargestellt und es wird keine von Ihnen angegebene Komponentenzuordnung verwendet.

Weitere Informationen finden Sie unter MDX und React in der Docusaurus-Dokumentation.

Passthrough-Komponente

Manchmal ist es notwendig, HTML-, JSX- oder Markdown-Inhalte in ein Thema einzubinden, die das CMS im Rich-Text-Editor nicht anzeigen kann. Um sicherzustellen, dass der Editor weiterhin für andere Inhalte genutzt werden kann, steht die Passthrough-Komponente zur Verfügung. Damit können Sie Inhalte so umschließen, dass der Rich-Text-Editor sie effektiv ignoriert.

1. Wählen Sie Passthrough aus der Liste Einbetten aus.
2. Geben Sie eine Zusammenfassung ein.
3. Geben Sie den Inhalt als einfachen Text ein.
4. Wählen Sie den Inhaltstyp aus (Markdown, HTML oder JSX).

Der Inhalt wird beim Erstellen der Website direkt und ohne den Wrapper zur Seite hinzugefügt.

Beispiele finden Sie auf der Beispielseite und unter mathematische Gleichungen.