MDX y React

docStatic incluye soporte integrado para MDX, lo que te permite escribir JSX dentro de tus archivos Markdown y renderizarlos como componentes de React. Sin embargo, si añades JSX directamente en tus temas, el CMS no podrá mostrarlos en el editor de texto enriquecido.

Ámbito de los componentes MDX

La forma recomendada de utilizar componentes MDX en docStatic es registrándolos en el ámbito global, lo que hace que estén disponibles automáticamente en todos los archivos MDX, sin necesidad de declaraciones de importación. También es necesario añadir una definición de plantilla al componente e importarlo para que el CMS lo reconozca. Para ver ejemplos de cómo se hace esto, puedes explorar los propios componentes de docStatic, como CodeSnippet. Es importante asegurarse de que los componentes globales se rendericen de forma estática, ya que, de lo contrario, podrían provocar retrasos en el renderizado de la página.

Por ejemplo, src/theme/MDXComponents.jsx registra actualmente lo siguiente:

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

Las importaciones que comienzan por @site/src/components/ son los componentes personalizados que se pueden renderizar en los temas. También hay componentes personalizados que utiliza el CMS, como StatusField, que no es necesario importar.

El archivo src/theme/template.jsx comienza así:

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

Las plantillas para componentes nativos, como Details, deben definirse directamente en el archivo. Por ejemplo:

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

El archivo termina exportando todas las plantillas:

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

Ahora estos componentes pueden utilizarse en cualquier archivo MDX.

Precaución

Utiliza nombres de etiquetas en mayúsculas.

A partir de MDX v3+, los nombres de etiquetas en minúsculas siempre se representan como elementos HTML nativos y no utilizarán ninguna asignación de componentes que proporciones.

Para obtener más información, consulta MDX y React en la documentación de Docusaurus.

Componente «Passthrough»

A veces será necesario incluir código HTML, JSX o Markdown en un tema que el CMS no pueda mostrar en el editor de texto enriquecido. Para garantizar que el editor pueda seguir utilizándose para otros contenidos, se proporciona el componente Passthrough. Esto te permite envolver el contenido de forma que el editor de texto enriquecido lo ignore efectivamente.

1. Selecciona Passthrough en la lista Incrustar.
2. Asigna un Resumen.
3. Introduce el Contenido como texto sin formato.
4. Selecciona el Tipo de contenido (Markdown, HTML o JSX).

El contenido se añade directamente a la página cuando se genera el sitio, sin el contenedor.

Para ver ejemplos, consulta la página de ejemplo y las ecuaciones matemáticas.