Post Image

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.