Presentaciones con Marp

Este curso quería rehacer las transparencias de una de mis asignaturas de programación y llevaba tiempo rondándome la idea de usar markdown. Con markdown es muy sencillo escribir texto, y en especial insertar fragmentos de código con resaltado automático de sintaxis. En este post cuento mi experiencia con el sistema Marp.

En primer lugar te animo a que visites la página oficial para hacerte idea del potencial y la sencillez que tiene la herramienta. Además encontrarás ejemplos y tutoriales muy sencillos de seguir. Lo que cuento a continuación es lo que he hecho para personalizarlo a mis necesidades.

¿Quién es quién?

Lo primero que me resultó confuso de Marp fue saber qué necesitaba y dónde localizarme dentro del ecosistema. Hago aquí mi propio resumen:

• Marp for VS Code

  Es la forma más sencilla de empezar y, si es suficiente para tus necesidades, estás de enhorabuena porque es muy sencillo y elegante. Básicamente se integra dentro de Visual Studio Code y te permite editar en markdown a la vez que visualizas en tiempo real el aspecto final de la presentación.

  El único problema de esta opción es que no te permite instalar plugins que amplíen las funcionalidades base de Marp. Esto se debe a la política de seguridad del propio Visual Studio Code. Traté de saltarme estas restricciones modificando el propio plugin pero no me acabó funcionando, así que finalmente opté por la siguiente opción.

• Marp CLI

  Como su propio nombre indica es una interfaz en línea de comandos (Command Line Interface) para trabajar con Marp. Se instala desde Node.js y te ofrece un nuevo comando marp:

  • marp slide-deck.md: permite convertir la presentación markdown a HTML
  • marp --pdf slide-deck.md: conversión a PDF (lo que habitualmente uso)
  • marp --preview slide-deck.md: abre un navegador con una visualización en tiempo real de los cambios
  • etc. (volveré más adelante a este comando)

• Marpit

  Es la plataforma que va por debajo de las anteriores y permite renderizar código markdown desde una página web.

• markdown-it

  Es la plataforma en la que se basa Marpit, pero no es un sistema específico de presentaciones, por lo que no tiene el concepto de slide. El interés que tiene esta plataforma para nuestro caso es que hay muchos plugins disponibles para ella, mientras que para Marpit hay pocos. Aunque lo recomendable sería emplear plugins de Marpit, en la práctica podemos usar muchos de los plugins de markdown-it.

Integrando todo

Como utilizar el plugin de VS Code se me quedaba muy limitado, finalmente he acabado utilizando Marp CLI e instalando varios plugins de markdown-it. El comando con el que ejecuto todo es:

marp --engine ./engine.js --theme ./theme.css --preview slide-deck.md

El fichero engine.js es necesario para cargar en Marp los plugins de markdown-it que he instalado. En mi caso:

const { Marp } = require('@marp-team/marp-core')
const markdownItContainer = require('markdown-it-container')

module.exports = (opts) => new Marp(opts)
    .use(markdownItContainer, 'columns')
    .use(markdownItContainer, 'note')
    .use(require('markdown-it-mark'))
    .use(require('markdown-it-smartarrows'))
    .use(require('markdown-it-center-text'))
    .use(require('markdown-it-wiki-toc'), {tocTitle: null, maxDepth: 2})
    .use(require('markdown-it-attrs'))
    .use(require('markdown-it-sup'))
    .use(require('markdown-it-multimd-table'), {multiline: true, rowspan: true})

Los módulos markdown-it- son los plugins de markdown-it que he instalado para incluir funcionalidades como: texto a dos columnas, tabla de contenidos, crear tags propios, etc.

Por otro lado en theme.css he incluido los estilos que utilizo en todas mis presentaciones (una por cada tema de la asignatura) de forma que no tengo que duplicarlos en cada una de ellas y todas tienen un aspecto uniforme. Para ello importo el tema que me interese de los predefinidos y lo personalizo a mi gusto. Ejemplo:

@import 'default';

* {
    color: #23373B;
}

h1, h2, h3, h4, h5, h6 {
    margin-top: 0px;
}

...

Para llegar al diseño final volví un poco loco al desarrollador de Marp, que atendió muy bien y al momento mis múltiples inquietudes. Recomiendo echar un vistazo al la sección de discusiones y de issues del repositorio de Marp CLI.