@bdocs/plugin-math

El plugin @bdocs/plugin-math integra KaTeX en Boltdocs. Transforma automáticamente los delimitadores LaTeX estándar ($ y $) en ecuaciones matemáticas bellamente renderizadas en tiempo de compilación, sin necesidad de configuración.

Demo en Vivo

Aquí hay matemáticas en línea: $E = mc^2$, y matemáticas en bloque:

La fórmula cuadrática $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ encuentra las raíces de $ax^2 + bx + c = 0$.

Instalación y Inicio Rápido

Comienza añadiendo el paquete del plugin a tu proyecto de documentación.

1. Instalar el paquete

pnpm add @bdocs/plugin-math

2. Registrar el plugin

Añade el plugin al arreglo plugins en tu archivo de configuración:

import { defineConfig } from 'boltdocs'
import mathPlugin from '@bdocs/plugin-math'

export default defineConfig({
  plugins: [mathPlugin()],
})

Conceptos y Arquitectura

El plugin matemático utiliza un pipeline de transformación en tiempo de compilación para mantener tus páginas rápidas:

1. Transformación AST: Cuando Boltdocs parsea tus archivos MDX, el compilador Remark del plugin escanea los nodos de texto buscando delimitadores $...$ y $...$. Los transforma directamente en componentes React <Math> y <BlockMath> en el AST de MDX.

2. Renderizado del Lado del Cliente: KaTeX renderiza las expresiones LaTeX en HTML semántico en tiempo de ejecución mediante katex.renderToString(). El resultado se inyecta usando dangerouslySetInnerHTML — sin iframes, sin desplazamientos de diseño.

3. CSS vía CDN: Los estilos de KaTeX se cargan desde un CDN, manteniendo tu bundle ligero. Importa la hoja de estilos desde @bdocs/plugin-math/style.css si tu bundler soporta importaciones CSS.

Uso

Matemáticas en Línea

Envuelve expresiones cortas con un solo delimitador $:

La famosa ecuación $E = mc^2$ relaciona energía y masa.

Matemáticas en Bloque

Usa delimitadores $ para ecuaciones centradas independientes:

$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$

Fracciones

$
\frac{a}{b} \quad \frac{x + y}{x - y}
$

Sumatorias y Productos

$
\sum_{k=0}^{\infty} \frac{1}{k^2} = \frac{\pi^2}{6}
\qquad
\prod_{i=1}^{n} x_i
$

Integrales

$
\int_{a}^{b} f(x) \, dx
\qquad
\oint_{C} \vec{F} \cdot d\vec{r}
$

Matrices

$
\begin{pmatrix}
a_{11} & a_{12} & \dots & a_{1n} \\
a_{21} & a_{22} & \dots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{m1} & a_{m2} & \dots & a_{mn}
\end{pmatrix}
$

Sistemas de Ecuaciones

$
\begin{cases}
x + y = 10 \\
x - y = 4
\end{cases}
$

Ejemplo Combinado

La fórmula cuadrática $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ da
las raíces de $ax^2 + bx + c = 0$. El discriminante es:

$
\Delta = b^2 - 4ac
$

Cuando $\Delta > 0$, hay dos raíces reales distintas.

Referencia de la API

Opciones del Plugin

La función mathPlugin() no acepta opciones. Funciona directamente con cero configuración.

Componente Math

Propiedades soportadas al usar el componente React <Math /> directamente en MDX.

Componente BlockMath

Propiedades soportadas al usar el componente React <BlockMath /> directamente.

Sintaxis de Componentes

Para casos de uso avanzados, puedes invocar los componentes JSX directamente:

Inline: <Math>E = mc^2</Math>

Block: <BlockMath>\sum_{i=1}^{n} i</BlockMath>

Referencia Rápida de KaTeX

Comandos LaTeX comunes soportados por KaTeX:

Fracciones y Raíces

Letras Griegas

Operadores

Delimitadores

Símbolos

Acentos

Matrices

Solución de Problemas

Las ecuaciones no se renderizan

• Verifica la Configuración: Asegúrate de que mathPlugin() esté registrado en el arreglo de plugins de tu boltdocs.config.ts.
• Revisa los Delimitadores: Usa un solo $ para matemáticas en línea y doble $ para matemáticas en bloque. No se requieren espacios entre el delimitador y la expresión.

Falta el CSS de KaTeX

El plugin carga los estilos de KaTeX desde un CDN. Si faltan estilos, importa el archivo CSS en tu layout o hoja de estilos:

@import url('https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css');

Errores de sintaxis LaTeX

Cuando KaTeX encuentra sintaxis LaTeX inválida, la expresión sin procesar se muestra como texto de respaldo. Revisa la consola del navegador para mensajes de error específicos. Los problemas más comunes incluyen:

• Llaves { / } sin cerrar
• Falta \ antes de comandos
• Nombres de operadores inválidos
• Caracteres especiales sin escape como _ o &

Las matrices se desbordan

Para matrices anchas o ecuaciones largas, el contenedor de matemáticas en bloque habilita el desplazamiento horizontal automáticamente. No se necesita CSS adicional.