Ebook offline per il libro open source 📚

Se c’è una cosa che adoro dei progetti Open Source è questa: non devi “salvare il mondo” per essere utile. A volte basta un tassello piccolo, concreto… e un po’ ostinato. 😄

Negli ultimi mesi ho messo mano a un contributo per Il Libro Open Source, un progetto italiano raro (nel senso buono): un libro gratuito, scritto e mantenuto da una comunità, che prova a parlare di sviluppo software non come lista di framework, ma come percorso fatto di valori, collaborazione e crescita.

E, visto che “comunità” non è una parola decorativa, qui un ringraziamento esplicito a chi ha acceso la scintilla e continua a tenere la barra dritta: Michael Di Prisco (LinkedIn), founder del progetto.

E un grazie anche agli ambassador che tengono insieme visione, metodo e confronto: Alessandro Cappellozza (LinkedIn), Angelo Cassano (LinkedIn) e Serena Sensini (LinkedIn). La lista ufficiale è in governance/AMBASSADOR.md.

E poi, altrettanto importante: il libro è il risultato del lavoro di molti altri contributor, attivi sui contenuti e sulle revisioni. La lista è in governance/CONTRIBUTOR.md. È una di quelle cose che non fai “da solo”, anche quando pensi di farlo da solo.

Il libro era già disponibile online in formato web, qui: il-libro-open-source.github.io/book. Bellissimo, comodo, sempre aggiornato. Ma mancava una cosa che per molti lettori è quasi una necessità primaria: poterlo leggere offline, su un e-reader, senza dipendere da connessione e browser. E quindi sì: volevo leggerlo su Kobo. 📖

Perché volevo un EPUB (e non solo “per sport”) 📚

L’idea è semplice: se un contenuto è davvero aperto, dovrebbe essere fruibile. Non “solo disponibile”.

Un formato ebook porta con sé un paio di vantaggi poco glamour ma molto reali:

• lettura offline (Kobo incluso)
• impaginazione e tipografia più rilassanti rispetto al browser
• note, evidenziazioni, segnalibri

E poi c’è un aspetto quasi morale: rendere più facile la lettura significa rendere più facile anche l’accesso alla conoscenza. Il che, per un progetto che parla di comunità e Open Source, è piuttosto coerente. 🙂

Dal Markdown all’ebook: la parte “facile” che non lo è 😅

Il libro nasce in Markdown. “Ottimo!” penseresti. “È testo, cosa vuoi che sia?”

E invece no: trasformare Markdown in un ebook decente è uno di quei lavori in cui scopri che la realtà è piena di dettagli vendicativi.

Ho costruito una piccola CLI in Go per generare un EPUB a partire dai sorgenti, usando librerie nuove per me e facendo un po’ di ginnastica mentale su parsing, struttura e output.

Le sfide principali, in pratica, sono state queste:

• Conversione Markdown corretta.
  Non basta “renderizzare”: devi mantenere semantica, link, immagini, note, e farlo in modo consistente tra capitoli.
• Gerarchia e ordine dei capitoli.
  Un sito web può permettersi una navigazione ipertestuale; un ebook pretende una sequenza chiara (e una ToC affidabile).
• Blocchi di codice e syntax highlight.
  Il codice in un browser è facile da rendere leggibile. In un ebook, molto meno: font, spaziature e colori devono restare chiari anche su schermi e-ink.
• CSS e leggibilità.
  L’ebook non è una pagina web: i CSS vanno dosati, e l’obiettivo è uno solo: non far venire voglia di chiudere il Kobo dopo due pagine.
• Elementi multimediali.
  Immagini e contenuti “non testuali” vanno incorporati in modo corretto, con percorsi coerenti e senza sorprese.
• Integrazione CI/CD.
  Perché sì, l’ebook va generato automaticamente: se il libro cambia, l’artefatto deve stare al passo, senza richiedere riti manuali e sacrifici notturni a base di caffè. ☕️

Una scoperta utile: Calibre come “secondo tempo” 🧰

Dopo la prima integrazione dell’EPUB, è arrivata la richiesta naturale: “Ok, bello. E per chi usa altri dispositivi?”

Qui entra in scena una scoperta pratica: usare il converter di Calibre come passaggio successivo, in modo semplice, per ottenere anche MOBI e PDF.

Non ho cercato di inventare l’ennesimo convertitore universale (anche perché la storia ci insegna che finisce sempre con qualcuno che piange). Ho preferito un approccio pragmatico: EPUB come formato sorgente di distribuzione, poi conversione derivata e ripetibile.

Dalla mia macchina al workflow: quando diventa davvero “progetto” 🤖

La parte più soddisfacente non è stata “funziona sul mio laptop” (che, diciamolo, è un traguardo spesso sopravvalutato 😇), ma vedere il flusso validato e integrato come workflow GitHub.

Oggi la generazione degli ebook è collegata al progetto ed è pubblica:

• sorgenti del libro: Il-Libro-Open-Source/book
• repository artefatti e pipeline: Il-Libro-Open-Source/book-epub

E soprattutto: gli ebook si possono scaricare direttamente dai rilasci, qui: book-epub/releases

Perché vale la pena contribuire (anche “solo” con un tool) 🇮🇹

Ci sono due motivi per cui questo contributo, pur piccolo, mi ha lasciato addosso una sensazione bella:

Primo: collaborare con un progetto italiano che mette insieme competenze diverse (dev, contenuti, revisione, organizzazione) è un promemoria che la qualità nasce dalla somma – e non dalla performance del singolo.

Secondo: contribuire alla diffusione della conoscenza, anche in senso laterale (non scrivendo capitoli, ma rendendoli più accessibili), è una forma di cura. E sì, suona un po’ retorico. Ma funziona. 🙂

In fondo, l’Open Source non è solo “codice aperto”. È anche: “ti tolgo attrito, così puoi imparare meglio”.

Riferimenti e librerie principali 🔗

Se ti interessa approfondire il “dietro le quinte”, questi sono i punti di partenza che ho usato:

• EPUB in Go: go-shiori/go-epub
• parsing/rendering Markdown: yuin/goldmark
• conversione ebook (Calibre): manuale Calibre conversion

Chiusura (e invito implicito) 🚪

Il Libro Open Source nasce da una comunità che condivide esperienze e conoscenza, con un’idea semplice: crescere insieme e rendere lo sviluppo software più accessibile, più consapevole, meno “solo tool del mese”.

Se ti va di leggerlo offline, ora puoi farlo. Se ti va di contribuire, puoi farlo. E se ti va solo di curiosare… anche quello è un ottimo inizio. 😉