En este artículo queremos dejar unas notas para cualquier persona que necesite trabajar con Markdown en aplicaciones Laravel. Veremos que no tiene mucha dificultad ya que todo lo vamos a conseguir mediante un paquete adicional llamado graham-campbell/markdown que vamos a explicar para que sepas instalar, configurar o usar en tus controladores o vistas.

Usar Markdown en Laravel es muy sencillo. Lo vamos a abordar a lo largo de los siguientes puntos.

• ¿Por qué usar Markdown?
• Paquete graham-campbell/markdown
• Configuración del paquete Markdown
• Facade Markdown
• Directiva @markdown

¿Por qué usar Markdown?

Markdown es un formato de definición de documentos enriquecidos. Consiste en una notación ligera para producir los típicos elementos que puedes conseguir con HTML, como párrafos, encabezados, listas y otros contenidos.

Usar Markdown en las aplicaciones es muy apropiado porque nos permite ofrecer al usuario una manera de introducir contenido con formato pero sin los inconvenientes de cara a la seguridad que podría tener permitirle escribir en HTML.

Mientras que HTML permite campos como <iframe> o <script> que pueden ser fuente de problemas diversos como los ataques por inyección de código XSS (Cross-site scripting), Markdown no los incluye.

Por tanto, si queremos que nuestros usuarios puedan introducir contenido con formato en algún lugar de la aplicación, si trabajamos con HTML estamos obligados a validar, sanitizar y filtrar las etiquetas introducidas. Sin embargo, con markdown tenemos un contenido inocuo, que contiene únicamente elementos inofensivos de cara a la seguridad. Este es el motivo por el que siempre conviene usar Markdown al almacenar contenido enriquecido escrito por el usuario.

Paquete graham-campbell/markdown

Este es el package más importante para usar Markdown en Laravel. Contiene una serie de funcionalidades básicas para convertir el markdown en HTML, incluso agrega una nueva directiva en los templates blade para cargar markdown de manera sencilla.

Este package tiene diversas versiones y dependiendeo de nuestra versión de Laravel tendremos que usar una u otra. Para tener una lista actualizada de versiones del paquete y las versiones de Laravel para las que son compatibles es mejor acudir a la documentación de graham-campbell/markdown.

El paquete tiene versiones compatibles desde Laravel 5 en adelante. Si fuera necesario consulta esta FAQ para saber qué versión de Laravel tienes en un proyecto.

Instalamos el paquete, en la versión que sea adecuada para nuestro proyecto Laravel, con un comando como este:

composer require "graham-campbell/markdown:^15.0"

Esta versión de graham-campbell/markdown 15.0 es compatible con Laravel 8, 9 y 10, que es la versión de Laravel más nueva en el momento de escribir este artículo.

Configuración del paquete Markdown

A continuación tienes generalmente que publicar el archivo de configuración del paquete, para personalizar su funcionamiento en tu aplicación Laravel.

sail php artisan vendor:publish

En el listado de items para publicar selecciona "Provider: GrahamCampbell\Markdown\MarkdownServiceProvider".

Entonces se publicará un archivo llamado config/markdown.php en tu proyecto, junto con otros archivos de configuración de Laravel. Ese archivo de configuración está perfectamente comentado por lo que no tendrás problemas para interpretarlo.

Facade Markdown

Si estamos dentro de un controlador podemos usar el facade Markdown para convertir una cadena de texto en formato Markdown en un HTML.

use GrahamCampbell\Markdown\Facades\Markdown;
//… 
Markdown::convert('Esto es markdown')->getContent(); // Devuelve <p>Esto es markdown</p>

Directiva @markdown

Si estamos dentro del código de una vista podemos usar la directiva @markdown para convertir una cadena que tengamos con formato Markdown en su valor con etiquetas HTML.

@markdown('# Encabezado 1')

Esto haría que en la vista se escribiera <h1>Encabezado 1</h1>. No hace falta escapar la salida, será HTML como si lo hubiéramos escrito tal cual en la vista.

Por supuesto, podemos traernos el markdown de un modelo que nos hayan enviado a la vista.

@markdown($quote->information)

Otra posibilidad es escribir el markdown directamente en la vista, con un código como este:

@markdown
# Escribimos markdown

Directamente sobre la vista **Laravel blade**.
@endmarkdown

Además otra posibilidad que ofrece es usar archivos con extensión ".md" ".md.php" o ".md.blade.php" como vistas Laravel Blade, aunque esto nunca lo he necesitado.

Puedes leer la documentación del package para encontrar más información sobre sus posibilidades y las opciones de configuración que nos ofrece. Aunque a decir verdad en la mayoría de las ocasiones no necesitarás más de lo que he comentado en este artículo.