MDX: Componentes Interactivos y Portales de Documentación

El Markdown convencional es un formato estático: produce texto enriquecido, pero no permite que el usuario interactúe con la página. En el desarrollo web contemporáneo con React, Next.js, Astro y Docusaurus, la documentación ha evolucionado gracias a MDX.

MDX es un superconjunto de Markdown que permite intercalar de forma nativa componentes JSX interactivos dentro de archivos de documentación .mdx.

1┌──────────────────────────────────────────────────────────────────────────────────┐
2│                         EL ECOSISTEMA Y FLUJO DE MDX                             │
3├──────────────────────────────────────────────────────────────────────────────────┤
4│ Archivo .mdx ──► Parser Remark (AST md) ──► Parser Rehype (AST HTML) ──► React  │
5│ [Texto + JSX]    (remark-gfm, etc.)         (rehype-highlight, etc.)    (UI Viva)│
6└──────────────────────────────────────────────────────────────────────────────────┘

1. Sintaxis Básica de MDX #

En un archivo .mdx puedes redactar encabezados y listas con la sintaxis clásica de Markdown, e importar e incrustar componentes de React con sus propiedades (props):

1---
2title: Guía de Instalación del SDK
3---
4
5import { Tabs, TabItem } from '@/components/Tabs';
6import { AlertaInteractiva } from '@/components/Alerta';
7
8## Instalación del Cliente
9
10Elige tu gestor de paquetes preferido:
11
12<Tabs>
13  <TabItem label="npm">
14    ```bash
15    npm install @mi-empresa/sdk
16    ```
17  </TabItem>
18  <TabItem label="pnpm">
19    ```bash
20    pnpm add @mi-empresa/sdk
21    ```
22  </TabItem>
23  <TabItem label="yarn">
24    ```bash
25    yarn add @mi-empresa/sdk
26    ```
27  </TabItem>
28</Tabs>
29
30<AlertaInteractiva tipo="info" mensaje="Requiere Node.js versión 20 o superior." />

2. El Pipeline de Transformación: Remark y Rehype #

El procesamiento de Markdown y MDX se fundamenta en Árboles de Sintaxis Abstracta (AST - Abstract Syntax Trees):

1. Remark: Procesa el árbol de sintaxis de Markdown (mdast).
   • remark-gfm: Añade soporte para tablas, listas de tareas y tachado.
   • remark-math: Reconoce fórmulas matemáticas entre $.
2. Rehype: Transforma el árbol en HTML (hast).
   • rehype-highlight / rehype-prism: Resalta la sintaxis del código con temas de color.
   • rehype-autolink-headings: Genera anclas automáticas en cada encabezado.
   • rehype-katex: Renderiza expresiones matemáticas en SVG/HTML accesible.

3. Sobrescritura de Componentes Nativos (Custom Components) #

Una de las ventajas más potentes de MDX es la capacidad de reemplazar automáticamente las etiquetas HTML estándar por componentes estilizados con Tailwind CSS o con lógica avanzada:

1// Configuración de componentes en un proyecto Next.js / Astro
2import { CodeBlockWithCopy } from './CodeBlockWithCopy';
3
4const mdxComponents = {
5  // Transforma cada bloque ``` en un componente con botón de copiar código
6  pre: (props) => <CodeBlockWithCopy {...props} />,
7  // Estiliza automáticamente todas las tablas con bordes y hover
8  table: (props) => (
9    <div className="overflow-x-auto my-4">
10      <table className="min-w-full divide-y divide-gray-200" {...props} />
11    </div>
12  ),
13  // Añade enlaces de ancla interactivos a los encabezados h2
14  h2: ({ children, ...props }) => (
15    <h2 className="text-2xl font-bold text-blue-600 mt-8 mb-4 flex items-center" {...props}>
16      {children}
17    </h2>
18  ),
19};

4. Principales Frameworks de Documentación con MDX #