Creare Slides in Markdown Usando Pandoc, Reveal.js e Docker
In questo articolo, ti mostreremo come creare presentazioni in Markdown utilizzando Pandoc e reveal.js all'interno di un container Docker. Questo approccio ha il vantaggio di fornire un ambiente isolato e replicabile, ideale per lavorare su diverse piattaforme senza preoccuparti delle specifiche del sistema operativo.
Markdown è un linguaggio di markup leggero, conosciuto per la sua semplicità e leggibilità. È molto popolare per scrivere documentazione e contenuti web, e lo useremo come base per le nostre slide.
Pandoc è uno strumento versatile per la conversione di documenti. Può trasformare i file Markdown in vari formati, inclusi HTML e PDF. Utilizzeremo Pandoc per convertire i nostri file Markdown in presentazioni HTML.
reveal.js è un potente framework per creare presentazioni HTML interattive e moderne. Offre molte funzionalità avanzate, tra cui transizioni eleganti, layout responsive e supporto per il codice evidenziato. Combinandolo con Pandoc, possiamo generare facilmente presentazioni professionali da semplici file Markdown.
Docker è una piattaforma che consente di creare, distribuire e eseguire applicazioni in container. Utilizzando Docker, possiamo configurare un ambiente di sviluppo standardizzato che funziona su qualsiasi piattaforma supportata da Docker, garantendo che le nostre slide possano essere generate e visualizzate correttamente ovunque.
Seguendo questa guida, imparerai come configurare un container Docker con Pandoc e reveal.js e come usarlo per creare presentazioni Markdown su qualsiasi sistema operativo.
Configurazione Ambiente Docker
Dockerfile
Dopo aver installato Docker sul tuo pc, avvia la creazione dell'ambiente
creando un Dockerfile, come segue:
# Usa l'immagine base di Debian
FROM debian:latest
# Installa gli strumenti necessari
RUN apt-get update && \
apt-get install -y pandoc git && \
git clone https://github.com/hakimel/reveal.js.git /opt/reveal.js && \
apt-get clean
# Imposta la directory di lavoro
WORKDIR /slides
# Esporta la directory di reveal.js come variabile d'ambiente
ENV REVEALJS_URL=/opt/reveal.js
il Dockerfile consente l'installazione della distribuzione Debian e
l'installazione dei pacchetti necessari alla generazione delle slide.
Successivamente imposta la WORKDIR e la variabile d'ambiente REVEALJS_URL
che indica il path della cartella che contiene il framework.
Configurazione di Docker Compose
Per avere una configurazione più semplice e moderna, conviene creare il
docker-compose.yml, come segue:
version: '3.8'
services:
pandoc-revealjs:
build: .
volumes:
- ./slides:/slides
working_dir: /slides
stdin_open: true
tty: true
Il file crea un container, denominato pandoc-revealjs, che installa tutto
quanto descritto nel Dockerfile. Il file monta un volume per poter condividere
la cartella slides, presente all'interno della cartella di progetto sul tuo
pc, sulla cartella del container nel quale devono essere memorizzate le slide.
Montare questo volume ti consente di modificare il contenuto delle slide in
locale senza dover lavorare direttamente sul container.
Creazione delle Slide in Markdown
Nella cartella slides puoi cominciare a creare
le tue slide.
Le slide in Markdown prevedono dei metadati all'inizio e successivamente
seguono la sintassi del markdown. Una slide dalla seguente è suddivisa dai
caratteri ---. Vediamo un esempio che chiarirà meglio tutto.
---
title: "Titolo della Presentazione"
author: "Il Tuo Nome"
date: "2024-06-19"
---
# Titolo della Presentazione
## Slide 1
Contenuto della prima slide.
---
## Slide 2
Contenuto della seconda slide.
---
## Slide 3
Contenuto della terza slide.
Il precedente esempio crea una presentazione con 3 slide ognuna con il proprio
titolo che segue il simbolo ##. Puoi salvare il precedente esempio
all'interno di un file slides.md.
Generazione delle Slide con Docker
Supponiamo che la struttura del nostro progetto sia la seguente:
ROOT_PROJECT
|-- Dockerfile
|-- docker-compose.yml
|-- slides/
Per creare ed avviare il container docker, eseguiamo i seguenti passi.
1. Spostati sulla root di progetto
cd ROOT_PROJECT
2. Crea l'immagine Docker
docker-compose build
3. Avvia il container
docker-compose up -d
4. Accedi al container
docker-compose exec pandoc-revealjs /bin/bash
5. Genera le slide con Pandoc
pandoc -t revealjs -s -o slides.html slides.md -V revealjs-url=$REVEALJS_URL --self-contained
Questo comando genera il file slides.html all'interno della cartella dove
sono presenti i file markdown. Dato che la cartella slides è montata come
volume Docker, troverai questo file anche sul tuo pc. Aprilo con il tuo browser
preferito e vedrai le slide create.
Opzione self-contained
Il comando Pandoc richiamato al punto 5 prevede come ultima opzione
self-contained. La presenza di questa opzione è facoltativa ma nel nostro
esempio è fondamentale. Se provi a rimuovere tale opzione, e a ricaricare sul
browser le slide generate, ti accorgerai che le slide sono prive di stile.
Questo è dovuto al fatto che il file .html generato, non riesce a trovare il
framework reveal.js, poiché esso è presente sul container Docker, ma non sul pc
locale. L'opzione consente di copiare il contenuto di reveal.js all'interno del
file html e quindi di rendere la presentazione portabile senza dover avere
reveal.js scaricato sul sistema.
In alternativa all'opzione self-contained, avrestoi dovuto copiare la
cartella reveal.js all'interno della cartella slides del filesystem.
Conclusioni
In questo articolo hai imparato come creare presentazioni professionali utilizzando markdown, Pandoc, reveal.js e Docker. Utilizzando Docker, quanto descritto può essere eseguito su qualsiasi piattaforma: Windows, OSX, Linux.
