Implementación de archivos Markdown para un blog de tutoriales con modo oscuro y copia al portapapeles
Hoy en día, hay muchos sitios web con los que podemos crear un blog y empezar a escribir, pero si queremos escribir artículos técnicos como tutoriales, necesitaremos mostrar código para ejemplificar el tutorial.
En este caso, los mismos sitios web ofrecen la opción de escribir código y mostrarlo en un formato diferente al del texto, por ejemplo, aquí en Medium. Y ¿Cómo da el sitio un formato diferente a este bloque de texto?
En la mayoría de los casos, utilizan Markdown. Markdown es un lenguaje de marcado que facilita el formateo del texto utilizando una serie de caracteres de forma especial.
En este tutorial aprenderemos a sacar partido a Markdown con React. Desarrollaremos la base de un blog en el que queremos compartir tutoriales de programación.
También añadiremos un par de funcionalidades más a los bloques de código que nos permiten cambiar el estilo o el tema y copiar el código.
¿Qué es Markdown?
Es un lenguaje de marcado que, en principio, fue diseñado para producir textos cuyo destino iba a ser la web de forma más rápida y sencilla que si utilizáramos directamente HTML.
En resumen, es una herramienta de software que convierte el lenguaje en HTML válido. Digamos que queremos escribir un título de nivel 1. En HTML esto se hace con la etiqueta h1. Por lo tanto, escribiríamos
Sin embargo, usando Markdown no necesitaríamos escribir la etiqueta, sino simplemente poner una almohadilla al principio:
Aquí puedes encontrar todo sobre Markdown.
Escribir bloques de código en Markdown
Un elemento muy utilizado en Markdown, especialmente para los blogs de desarrolladores, es el bloque de código delimitado. Si queremos mostrar un bloque de código, en nuestro artículo, creamos un bloque de código delimitado con una "valla" de marcas de retroceso antes y después del código, como sigue:
Lo que hace Markdown es convertir ese bloque de código cercado en un elemento.
Resaltar la sintaxis de un bloque de código delimitado
En Markdown, podemos resaltar bloques de código delimitados. Esta función nos permite añadir el resaltado por colores para diferentes lenguajes de programación.
Para añadir el resaltado de sintaxis, sólo tenemos que especificar el lenguaje junto con los signos de retroceso.
Ahora que sabemos lo que es Markdown, vamos a ver cómo podemos utilizarlo dentro de React.
Blog de tutoriales
Configuración
Creamos nuestra aplicación con el siguiente comando:
Instalamos las dependencias que necesitaremos en el proyecto:
- markdown-to-jsx para renderizar archivos markdown con react.
- react-syntax-highlighter para resaltar un bloque de código con un tema.
- react-copy-to-clipboard para copiar al portapapeles el bloque de código.
Después de eso, creamos la siguiente estructura para el proyecto:
Para mostrar archivos markdown con React, utilizaremos una biblioteca que convierte markdown a JSX llamada markdown-to-jsx.
Con esta librería, podremos trabajar con componentes de React dentro de archivos markdown. Para ello, vamos a seguir los siguientes pasos.
1 — Dentro de la carpeta de tutoriales, creamos un nuevo archivo .md, en este caso, tutorial1.md, y añadimos el contenido Markdown que queremos mostrar.
Para ejemplificar o simular un tutorial que queramos mostrar en nuestro blog, he tomado una parte de la documentación de React. Además, he sustituido los bloques de código Markdown nativos por nuestro componente <code>
Es decir, en lugar de escribir el código dentro de las comillas invertidas que utiliza Markdown, escribimos el código dentro de las etiquetas Code. Hemos llamado así a este componente porque en las propiedades overrides{} del componente <Markdown/> le hemos asignado ese nombre. Puede ser el nombre que queramos.
Utilizar el gancho del Estado
La página de introducción utilizó este ejemplo para familiarizarse con los ganchos:
Empezaremos a aprender sobre Hooks comparando este código con un ejemplo de clase equivalente.
Ejemplo de clase equivalente
Si ya has utilizado clases en React, este código debería resultarte familiar:
El estado comienza como { count: 0 }, e incrementamos state.count cuando el usuario hace clic en un botón llamando a this.setState(). Utilizaremos fragmentos de esta clase a lo largo de la página.
NOTA:
Puede que te preguntes por qué estamos usando un contador aquí en lugar de un ejemplo más realista. Esto es para ayudarnos a centrarnos en la API mientras todavía estamos dando nuestros primeros pasos con Hooks.
Lo entenderemos mejor a continuación.
2 — En la carpeta de componentes creamos nuestro componente <Post/> e importamos el paquete markdown-to-jsx.
3 — Configurar el estado. Configuramos el estado que utilizaremos para almacenar el contenido Markdown. Inicialmente, establecemos la variable postContent a una cadena en blanco y la colocamos entre las etiquetas <Markdown>.
También tenemos un nombre de archivo que sirve para elegir dinámicamente el archivo Markdown que queremos.
4 — Obtener y mostrar el archivo Markdown. Una vez cargado nuestro componente, dentro de un useEffect() utilizamos la importación como función.
La importación utilizada de esta manera actúa como una promesa y devuelve la ruta absoluta a nuestro archivo Markdown.
A continuación, recuperamos el archivo Markdown que queremos utilizando la API Fetch. Una vez que recuperamos el archivo, debemos analizar la respuesta como un archivo de texto y luego almacenar la respuesta analizada en nuestra postContent variable.
5 — El componente <Markdown> que importamos de markdown-to-jsx tiene una propiedad llamada options, que a su vez tiene una propiedad overrides que nos permite incrustar componentes React en archivos Markdown recibiendo sus propiedades.
En este caso, queremos sustituir los bloques de código Markdown por un componente que crearemos nosotros mismos.
Resaltar bloques de código con un tema y copiar al portapapeles
Ya hemos visto que Markdown ofrece resaltado de código cuando añadimos el tipo de lenguaje que estamos visualizando, pero ¿qué pasa si queremos dar un tema a ese bloque de código como tema en VS?
Para ello, usaremos react-syntax-highlighter, esta librería ofrece resaltado de código para una variedad de lenguajes, y usando Prism, que es otro resaltador de sintaxis ligero, podemos acceder a una lista de temas o estilos para nuestro código.
1 — Creamos otro componente que llamaremos <code/> que será el que mostrará los bloques de código. Importamos Syntax Highlighter, PrismLight, y el estilo que queramos, en este caso, seleccionamos dos estilos, uno para el modo oscuro y otro para el modo claro.
2 — Syntax Highlighter nos pide que registremos los lenguajes con los que vamos a trabajar, nosotros registramos jsx.
3 — Syntax Highlighter recibe dos propiedades, el idioma a resaltar y el estilo, estas propiedades las recibiremos de nuestro componente <Post/> junto con el bloque de código que pasaremos como hijos.
4 — Copy To Clipboard nos ayudará a copiar el contenido del código en el portapapeles, este componente recibe una propiedad llamada text que es lo que queremos copiar. Pasaremos la propiedad de los hijos que pasamos a Syntax Highlighter.
5 — Como copiar al portapapeles comúnmente es un icono lo haremos de la misma manera, un icono que sirve para copiar y una vez copiado el texto mostraremos el icono de pago durante 1000 ms. Hay varias formas de indicar al usuario que el texto ha sido copiado, como un mensaje de una alerta, etc.
6 — La última funcionalidad que queremos añadir a nuestro componente <Code/> es poder elegir entre un tema oscuro o claro. Lo haremos simplemente con los iconos que se suelen utilizar en estos casos, un icono de sol y otro de luna. Este botón lo que hará es cambiar el estado que tengamos en ese momento por su opuesto para mostrar el estilo correspondiente.
Últimos pasos
Ya tenemos listos nuestros principales componentes , <Post/> and <Code/>, ahora sólo tenemos que integrarlos donde queramos para nuestro blog. Para este sencillo ejercicio, sólo he tomado el componente principal <App/> como si fuera una página de nuestro blog. Puedes crear la estructura que te convenga para tu proyecto y tus propios estilos.
Este es el aspecto de nuestro blog:
Vea la demostración en línea aquí.
Conclusión
En este tutorial hemos visto lo fácil que es trabajar con archivos Markdown dentro de React y aprovechar lo que podríamos dar al usar Markdown para escribir un blog.
Pero podríamos sacar una ventaja más de Markdown ya que al ser un lenguaje en el que no necesariamente hay que escribir código sino solo texto, estos archivos podrían ser escritos por personas que no son programadores.
Espero que este tutorial haya sido útil y que puedas utilizar lo aprendido en tus próximos proyectos.