Come Usare DocPad Per Creare Un Sito Web

DocPad è uno strumento per la creazione di siti statici, che permette di scriverne
i contenuti in vari linguaggi quali HTML, Markdown, specificarne gli stili con Less e Sass,
definirne parti dinamiche in Javascript, Coffescript e molti altri linguaggi.

In questo articolo realizzeremo un semplice sito web utilizzando DocPad.

1. Installazione

DocPad richiede Node come prerequisito. Assicuriamoci di aver installato sul nostro sistema almeno la versione
0.12 o seguente. Per verificarlo digitiamo:

$ node -v
v6.11.4

Ad esempio nel nostro sistema è installata la versione v6.11.4 di Node che è più che sufficiente.

Aggiorniamo ora npm ed installiamo DocPad:

npm install -g npm
npm install -g docpad

2. Set Up della Cartella di Progetto

Creiamo una cartella che conterrà le defininioni del contenuto del nostro sito. Buona norma è quella di dare alla cartella
un nome che riconduce al progetto DocPad, quindi scegliamo per questo esempio "hello-world":

mkdir hello-world
cd hello-world
docpad init

DocPad procederà al set up dello scheletro del sito web e svariati messaggi ci informeranno circa il progresso
dell'attività. Il processo si concluderà comunque nel giro di massimo qualche minuto, anche in funzione della banda
disponibile alla nostra macchina, poichè varie dipendenze devono essere scaricate da Internet:

info: Welcome to DocPad v6.79.4 (global installation: ...\node_modules\docpad)
[...]
info: Installing the No Skeleton skeleton into C:\Users\danidemi\workspace\repos\diventa-pro\tutorials-docpad\hello-world
This can take a moment...
[...]
npm notice created a lockfile as package-lock.json. You should commit this file.
[...]
added 193 packages in 47.207s

3. Analisi della Struttura Creata

DocPad ha creato la seguente struttura:

/
├───node_modules
└───src
    ├───documents
    ├───files
    └───layouts

Purtroppo init, almeno alla versione docpad v6.79.4 oggetto di questo articolo, inizializza una struttura di
directory che non è aggiornata al nuovo layout standard previsto da DocPad stesso. E' necessario quindi rimuovere
due cartelle e creare due nuove:

> rmdir src\documents
> rmdir src\files
> mkdir src\render
> mkdir src\static 

La struttura dovrebbe diventare quindi la seguente:

/
├───node_modules
└───src
    ├───layouts
    ├───render
    └───static

• node_modules\, come in tutti i progetti gestiti da npm contiene i moduli node necessari al progetto.
• src\static\ è la cartella dove memorizzare tutte le risorse che non necessitano di elaborazione, quali le immagini.
• src\render\, in questa cartella dovranno essere salvati tutti i file che devono essere trasformati da DocPad, ad esempio: file .md (markdown) trasformati in .html oppure .less (less.js) trasformati in .css.
• src\layout\ qui vengono memorizzati i layout, documenti .html che specificano un aspetto generale comune a più pagine, all'interno del quale viene identificato un punto in cui sono innestati i contenuti generati dai file contenuti nella cartella src\render\.

4. Creazione del Contenuto In Markdown

Installiamo prima di tutto il preprocessore Markdown di DocPad:

> docpad install marked

DocPad stampa vari messaggi che ci informano del progresso:

info: Welcome to DocPad v6.79.4 (local installation: ...\hello-world\node_modules\docpad)
[...]
info: Environment: development
[...]
+ docpad-plugin-marked@2.4.0
added 2 packages in 3.549s

Creiamo ora nella cartella src\render un file con nome index.html.md. La "doppia" estensione indica a DocPad di intendere
il file come Markdown (a causa dell'estensione finale .md) da renderizzare come file HTML (visto che l'estensione più interna
è .html).

# Hello World

La mia prima pagina realizzata con [_DocPad_](https://docpad.org/)

5. Generazione del Sito Web e Anteprima

Invochiamo ora DocPad in modo che generi il sito HTML corrispondente al contenuto che abbiamo creato:

> docpad run

DocPad produce un output molto interessante:

info: Welcome to DocPad v6.79.4 (local installation: ...\hello-world\node_modules\docpad)
[...]
info: Plugins: marked
[...]
info: Server started on http://0.0.0.0:9778
info: In your web browser use http://127.0.0.1:9778
info: Generating...
info: Generated 1/1 files in 0.126 seconds
info: Watching setup starting...
[...]
info: The action completed successfully

Si può notare ora come sia apparsa una nuova cartella out\ nella home del progetto. Tale cartella contiene
il sito generato da DocPad a partire dai contenuti forniti.

Se puntiamo il nostro browser all'URL specificato da DocPad: http://127.0.0.1:9778 possiamo visualizzare il nostro sito
grazie ad un web server integrato in DocPad stesso.

6. Conclusioni

DocPad è sicuramente un tool da prendere in considerazione se si vuole gestire un sito
statico. Il suo meccanismo a plug-in e la conseguente possibilità di scrivere il contenuto
in diversi formati come Markdown molto più user friendly per la creazioni di contenuti ne fanno
uno strumento interessantissimo.

Il codice sorgente di questo esempio è disponibile su GitHub.