MDX et React

docStatic intègre la prise en charge de MDX, ce qui vous permet d'écrire du JSX dans vos fichiers Markdown et de les afficher sous forme de composants React. Cependant, si vous ajoutez du JSX directement dans vos rubriques, le CMS ne pourra pas les afficher dans l'éditeur de texte enrichi.

Portée des composants MDX

La meilleure façon d’utiliser les composants MDX dans docStatic consiste à les enregistrer dans la portée globale, ce qui les rend automatiquement disponibles dans tous les fichiers MDX, sans aucune instruction d’importation. Vous devez également ajouter une définition de modèle au composant et l’importer afin que le CMS le reconnaisse. Pour voir des exemples de cette procédure, vous pouvez consulter les composants propres à docStatic, tels que CodeSnippet. Il est important de s’assurer que les composants globaux sont rendus de manière statique, sinon ils risquent d’entraîner des retards dans le rendu des pages.

Par exemple, le fichier src/theme/MDXComponents.jsx enregistre actuellement les éléments suivants :

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

Les importations commençant par @site/src/components/ correspondent aux composants personnalisés pouvant être rendus dans les rubriques. Il existe également des composants personnalisés utilisés par le CMS, tels que StatusField, qui n’ont pas besoin d’être importés.

Le fichier src/theme/template.jsx commence ainsi :

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

Les modèles pour les composants natifs, tels que Details, doivent être définis directement dans le fichier. Par exemple :

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

Le fichier se termine par l’exportation de tous les modèles :

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

Ces composants peuvent désormais être utilisés dans n’importe quel fichier MDX.

Caution

Use upper-case tag names.

From MDX v3+ onward, lower-case tag names are always rendered as native HTML elements and will not use any component mapping you provide.

Pour plus d’informations, consultez la section MDX et React dans la documentation de Docusaurus.

Composant Passthrough

Il est parfois nécessaire d’inclure du code HTML, JSX ou Markdown dans un sujet que le CMS ne peut pas afficher dans l’éditeur de texte enrichi. Afin de garantir que l’éditeur puisse toujours être utilisé pour d’autres contenus, le composant Passthrough est fourni. Il vous permet d’encapsuler du contenu de manière à ce que l’éditeur de texte enrichi l’ignore complètement.

1. Sélectionnez Passthrough dans la liste Embed.
2. Remplissez le champ Résumé.
3. Saisissez le Contenu sous forme de texte brut.
4. Sélectionnez le Type de contenu (Markdown, HTML ou JSX).

Le contenu est ajouté directement à la page lors de la génération du site, sans le conteneur.

Pour des exemples, consultez la page d'exemple et les équations mathématiques.