Trabajar con elementos personalizados y códigos cortos MDX

MDX es una característica excelente para cosas como blogs, presentaciones de diapositivas y documentación de componentes. Le permite escribir Markdown sin preocuparse por los elementos HTML, su formato y ubicación, mientras agrega la magia de los componentes personalizados de React cuando sea necesario.

Aprovechemos esa magia y veamos cómo podemos personalizar MDX reemplazando elementos de Markdown con nuestros propios componentes MDX. En el proceso, introduciremos el concepto de “códigos cortos” cuando usemos esos componentes.

Como advertencia, los fragmentos de código aquí se basan en GatsbyJS y React , pero MDX también se puede escribir con diferentes marcos . Si necesita una introducción a MDX, comience aquí primero . Este artículo amplía ese con conceptos más avanzados.

Configurar un diseño

Casi siempre queremos representar nuestras páginas basadas en MDX en un diseño común. De esta manera se pueden combinar con otros componentes en nuestro sitio web. Podemos especificar un Layoutcomponente predeterminado con el complemento MDX que estamos usando. Por ejemplo. Podemos definir un diseño con el gatsby-plugin-mdxcomplemento de esta manera:

{  resolve: `gatsby-plugin-mdx`,  options: {    defaultLayouts: {      default: path.resolve('./src/templates/blog-post.js'),    },    // ...other options  }}

Esto requeriría que el src/templates/blog-post.jsarchivo contenga un componente que represente el childrenaccesorio que recibe.

import { MDXRenderer } from 'gatsby-plugin-mdx';
function BlogPost({ children }) {  return (    div{children}/div  );}
export default BlogPost;

Si estamos creando páginas mediante programación, tendríamos que usar un componente llamado MDXRendererpara lograr lo mismo, como se especifica en los documentos de Gatsby .

Elementos de rebajas personalizados

Si bien MDX es un formato que nos permite escribir componentes HTML y React personalizados, su poder es representar Markdown con contenido personalizado. Pero, ¿qué pasaría si quisiéramos personalizar cómo se representan estos elementos de Markdown en la pantalla?

Seguramente podríamos escribir un complemento de comentarios para ello , pero MDX nos proporciona una solución mejor y más sencilla. De forma predeterminada, estos son algunos de los elementos que Markdown representa:

Para reemplazar estos valores predeterminados con nuestros componentes personalizados de React, MDX se envía con un Providercomponente llamado MDXProvider. Se basa en la API React Context para inyectar nuevos componentes personalizados y fusionarlos con los valores predeterminados proporcionados por MDX.

import React from 'react';import { MDXProvider } from "@mdx-js/react";import Image from './image-component';
function Layout({ children }) {  return (    MDXProvider      components={{        h1: (props) = h1 {...props} className="text-xl font-light" /        img: Image,      }}           {children}    /MDXProvider  );}
export default Layout;

En este ejemplo, cualquier encabezado H1 ( #) en el archivo MDX será reemplazado por la implementación personalizada especificada en la Providerpropiedad del componente, mientras que todos los demás elementos continuarán usando los valores predeterminados. En otras palabras, MDXProviderpodemos tomar nuestro marcado personalizado para un elemento H1, fusionarlo con los valores predeterminados de MDX y luego aplicar el marcado personalizado cuando escribimos el Título 1 ( #) en un archivo MDX.

MDX y componentes personalizados

Personalizar elementos MDX es genial, pero ¿qué pasa si queremos introducir nuestros propios componentes en la mezcla?

---title: Importing Components---import Playground from './Playground';
Here is a look at the `Playground` component that I have been building:
Playground /

Podemos importar un componente a un archivo MDX y usarlo de la misma manera que lo haríamos con cualquier componente de React. Y, claro, si bien esto funciona bien para algo como una demostración de componentes en una publicación de blog, ¿qué pasa si queremos usar Playground en todas las publicaciones de blog? Sería complicado importarlos a todas las páginas. En cambio. MDX nos presenta la opción de utilizar códigos cortos. Así es como la documentación MDX describe los códigos cortos:

[Un código abreviado] le permite exponer componentes a todos sus documentos en su aplicación o sitio web. Esta es una característica útil para componentes comunes como incrustaciones de YouTube, tarjetas de Twitter o cualquier otra cosa que se use con frecuencia en sus documentos.

Para incluir códigos cortos en una aplicación MDX, tenemos que confiar MDXProvidernuevamente en el componente.

import React from 'react';import { MDXProvider } from "@mdx-js/react";import Playground from './playground-wrapper';
function Layout({ children }) {  return (    MDXProvider      components={{        h1: (props) = h1 {...props} className="text-xl font-light" /        Playground,      }}           {children}    /MDXProvider  );}
export default Layout;

Una vez que hayamos incluido componentes personalizados en el objeto de componentes, podemos proceder a usarlos sin importarlos en archivos MDX.

---title: Demoing concepts---
Here's the demo for the new concept:
Playground /
 Look ma! No imports

Manipular directamente componentes secundarios

En React, obtenemos API de nivel superior para manipular a los niños React.Children. Podemos usarlos para pasar nuevos accesorios a componentes secundarios que cambian su orden o determinan su visibilidad. MDX nos proporciona un componente contenedor especial para acceder a los componentes secundarios pasados ​​por MDX.

Para agregar un contenedor, podemos usar MDXProvidercomo hicimos antes:

import React from "react";import { MDXProvider } from "@mdx-js/react";const components = {  wrapper: ({ children, ...props }) = {    const reversedChildren = React.Children.toArray(children).reverse();    return {reversedChildren}/;  },};export default (props) = (  MDXProvider components={components}    main {...props} /  /MDXProvider);

Este ejemplo invierte los elementos secundarios para que aparezcan en el orden inverso al que los escribimos.

Incluso podemos volvernos locos y animar a todos los niños MDX a medida que entran:

import React from "react";import { MDXProvider } from "@mdx-js/react";import { useTrail, animated, config } from "react-spring";
const components = {  wrapper: ({ children, ...props }) = {    const childrenArray = React.Children.toArray(children);    const trail = useTrail(childrenArray.length, {      xy: [0, 0],      opacity: 1,      from: { xy: [30, 50], opacity: 0 },      config: config.gentle,      delay: 200,    });    return (      section        {trail.map(({ y, opacity }, index) = (          animated.div            key={index}            style={{              opacity,              transform: xy.interpolate((x, y) = `translate3d(${x}px,${y}px,0)`),            }}                      {childrenArray[index]}          /animated.div        ))}      /section    );  },};
export default (props) = (  MDXProvider components={components}    main {...props} /  /MDXProvider);

Terminando

MDX está diseñado con flexibilidad desde el primer momento, pero ampliarlo con un complemento puede hacer que haga aún más. Esto es lo que pudimos hacer en poco tiempo gracias a gatsby-plugin-mdx:

1. Cree componentes de diseño predeterminados que ayuden a formatear la salida MDX.
2. Reemplace los elementos HTML predeterminados representados desde Markdown con componentes personalizados
3. Utilice códigos cortos para deshacernos de la importación de componentes en cada archivo.
4. Manipule a los niños directamente para cambiar la salida MDX.

Nuevamente, esto es solo otra gota más en el océano en lo que respecta a lo que hace MDX para ayudar a que la escritura de contenido para sitios estáticos sea más fácil.

Más sobre MDX

• Una introducción a MDX
• Documentación front-end, guías de estilo y el auge de MDX