Saper creare e pubblicare pagine web online, in particolare pagine tecniche con report prodotti in R o Python, ma anche siti web più generali, libri online, blog o singole pagine, è una competenza fondamentale per giovani ricercatori e ricercatrici. Queste abilità permettono di condividere il proprio lavoro in ottica collaborativa, garantire riproducibilità e trasparenza secondo i principi dell’Open Science, e contribuire alla Terza Missione, nel senso di valorizzazione dei prodotti scientifici, diffusione della conoscenza e divulgazione verso utenti non-accademici (collaboratori in aziende, case editrici, professionisti, clinici, ecc.).
Questa pagina web e questo stesso blog sono stati creati con il sistema di publishing Quarto (anche rmarkdown va benissimo se si lavora principalmente con R), ma si tratta solo di una delle opzioni disponibili. Pagine HTML, PDF o altri tipi di documenti possono essere prodotti in molti modi diversi e diffusi online tramite GitHub Pages. Per capire cosa è possibile realizzare, ecco alcuni esempi concreti di prodotti sviluppati con Quarto (o strumenti simili) e pubblicati su GitHub Pages:
- siti personali con taglio accademico (es. https://drganghe.github.io);
- libri online (es. https://lakens.github.io/statistical_inferences/, con tanto di versione pdf impaginata);
- blog (es. https://www.jessesadler.com/);
- corsi e materiali didattici (es. Basics of R for Data Science; Corsi ARCA; Psicostat teaching);
Il presente tutorial dà per scontato che abbiate già più o meno un’idea di come creare i documenti che desiderate e vi guida nei passaggi successivi in modo semplice, passo per passo e con screenshot, fino alla pubblicazione online tramite GitHub Pages. GitHub è uno strumento estremamente potente per tutti gli obiettivi citati sopra.
Il tutorial è rivolto soprattutto a utenti Windows. Chi utilizza Linux o macOS può adattare facilmente i passaggi, chiedere aiuto all’AI oppure consultare altri tutorial specifici. → Nel caso, questa pagina scritta da Filippo Gambarota può essere di aiuto!
Obiettivi del tutorial
- Installare e configurare Git su Windows.
- Creare un account GitHub.
- Creare un semplice report Quarto con RStudio.
- Effettuare commit e push verso una repository GitHub.
- Pubblicare un sito tramite GitHub Pages.
Installazione di Git su Windows
Andare sul sito https://git-scm.com/
Cliccare su Download for Windows (o per il proprio sistema operativo), scaricare la versione più recente e salvare il file .exe.
Avviare l’installer e proseguire con tutte le opzioni di default fino al termine dell’installazione.
Creazione di un account GitHub
Andare sul sito https://github.com/
Cliccare su Sign up (in alto a destra) per registrarsi e compilare:
- Email (noi useremo
qualsiasitizio81@gmail.com)
- Username (noi useremo
qualsiasitizio81)
- Password a piacere
- Eventuali altre informazioni richieste
Confermare l’email tramite il codice ricevuto, se richiesto.
Configurazione di Git
Ora configuriamo Git sul computer e lo colleghiamo al vostro account GitHub. Per prima cosa apriamo il terminale. Possiamo farlo andando sul Desktop o in una cartella qualsiasi, cliccando con il tasto destro e scegliendo l’opzione per aprire il terminale, oppure cercando Windows PowerShell tra le applicazioni (potrebbe essere necessario avere i permessi di amministratore). Dovremmo vedere una schermata simile alla seguente:
Ora impostiamo i parametri principali di Git, ovvero il nome utente, l’email associata e il nome predefinito del branch iniziale:
git config --global user.name "Tizio Qualsiasi"
git config --global user.email "qualsiasitizio81@gmail.com"
git config --global init.defaultBranch main
A questo punto verifichiamo che la configurazione sia corretta e che il nome utente e l’email siano stati memorizzati:
git config --global --list
Creazione della repository (repo) su GitHub
Torniamo su GitHub, avendo effettuato l’accesso con il nostro account, e creiamo una nuova repository (repo):
Compiliamo il nome della repository (noi abbiamo scelto “my-great-report” per questa illustrazione) e procediamo con la creazione. Per facilitare l’attivazione successiva di GitHub Pages, lasciamo la visibilità impostata su Public:
Clonare la repo sul proprio computer
La repository appena creata è vuota. La cosa più semplice e comoda è clonarla subito in locale sul nostro computer: otterremo una normale cartella (già configurata con Git) su cui possiamo lavorare come su qualsiasi altra cartella.
Per clonare la repo in locale, dobbiamo prima copiare il suo link, che è la prima cosa che vediamo quando entriamo nella repository (ancora vuota) su GitHub:
Ora andiamo nel punto del nostro computer in cui vogliamo creare, in locale, la cartella corrispondente alla nostra repo (potremo poi comunque spostarla altrove, come qualsiasi altra cartella). Per farlo apriamo il terminale cliccando con il tasto destro del mouse, ad esempio sul Desktop:
A questo punto digitiamo git clone, seguito dal link precedentemente copiato dalla repo su GitHub. Ad esempio:
git clone https://github.com/qualsiasitizio81/my-great-report.git
È possibile che Git ci mostri un avviso indicando che stiamo clonando una repository vuota, ma va benissimo così: lo sappiamo già.
Dopo il comando git clone troveremo una cartella con lo stesso nome della repo, che rappresenta il clone locale della repository:
Se apriamo questa cartella probabilmente la vedremo completamente vuota, oppure, se in Windows abbiamo attivato la visualizzazione dei file nascosti, potremmo vedere al suo interno una cartella nascosta chiamata .git. In questo secondo caso non dobbiamo toccare né rinominare la cartella .git, perché contiene tutte le informazioni necessarie che collegano la cartella locale alla repository su GitHub.
A questo punto abbiamo una cartella locale, nel nostro esempio chiamata my-great-report, collegata alla repo su GitHub. Possiamo rinominare o spostare questa cartella dove vogliamo. L’importante è non toccare la cartella (eventualmente visibile) chiamata .git al suo interno.
La cartella locale my-great-report non è sincronizzata automaticamente con la repository GitHub. Per inviare i documenti su GitHub, dopo averli creati ed elaborati in locale, dovremo usare i comandi di Git per fare commit e push, mentre per scaricare eventuali aggiornamenti fatti da altri collaboratori useremo pull. Prima di vedere questi passaggi, però, facciamo un intermezzo su Quarto e su come creare file HTML.
Installazione di Quarto e creazione di file HTML
Installazione di Quarto
Questo passaggio non è necessario se avete già un sistema per creare pagine HTML, ma lo presentiamo come opzione consigliata. In realtà, non è nemmeno obbligatorio creare file HTML: dipende da cosa volete fare con Git e GitHub. Mostriamo comunque l’installazione di Quarto perché è particolarmente utile per diffondere pagine web in ottica Open Science e Terza Missione. Naturalmente, potreste usare GitHub anche solo per condividere dati, script o codice.
Assumiamo che vogliate creare e pubblicare pagine web e che siate familiari con l’ecosistema R. Supponiamo inoltre che abbiate già installato R e RStudio (o un altro IDE). Procediamo quindi con l’installazione del sistema di publishing Quarto. Come detto sopra, anche rmarkdown va benissimo per creare pagine HTML, ma Quarto è molto più potente, soprattutto per siti web, blog, libri, presentazioni e documenti complessi.
Andare sul sito https://quarto.org/ e scaricare Quarto per Windows. Il file .exe è facilmente reperibile alla pagina https://quarto.org/docs/get-started/. Scaricate il file di installazione e seguite tutti i passaggi raccomandati per installare Quarto localmente.
Una volta conclusa l’installazione, verifichiamola aprendo il terminale / Windows PowerShell e digitando:
quarto check
Il comando dovrebbe essere riconosciuto correttamente.
Creazione di un report e del file HTML
Se scegliete di usare Quarto, si apre un mondo di possibilità per la pubblicazione e la divulgazione online. Qui mostriamo solo un esempio semplice di creazione di un report basilare in Quarto Markdown.
Dopo aver installato Quarto, RStudio (oppure Positron, consigliato come alternativa moderna) riconoscerà automaticamente i file Quarto, che hanno estensione .qmd. Da RStudio potete crearne uno nuovo tramite:
File > New File > Quarto Document...
.qmd) da RStudio
A questo punto potete scrivere il vostro report in linguaggio Markdown, integrando eventualmente chunk eseguibili di codice R, Python o altri linguaggi (se installati).
Quando il report è pronto (o mentre lo state ancora scrivendo, per vedere l’anteprima), potete cliccare su Render: verrà generato automaticamente il file .html accanto al file .qmd.
Il formato predefinito è HTML, ma se avete installato TinyTeX potete produrre anche PDF, utile per articoli, documenti tecnici o slide. Per il momento ci concentriamo sull’HTML, che è la scelta più semplice per la pubblicazione online.
Dopo il render, accanto al file .qmd troverete il file .html e la cartella associata. Nel mio esempio il file si chiama index, ma potete chiamarlo come preferite. Tuttavia, usare index è particolarmente conveniente perché un file chiamato index.html viene automaticamente riconosciuto come home page di un sito web, permettendo di ottenere un URL più semplice e pulito.
Commit & Push su GitHub
Ora che avete preparato i vostri file nella cartella locale, non resta che inviarli online su GitHub. Avendo Git installato e configurato, il procedimento è semplice. Apriamo il terminale direttamente nella cartella della repository locale (nel nostro caso my-great-report):
A questo punto digitiamo i seguenti comandi:
git add .
git commit -m "first commit"
git push
git add .aggiunge tutti i file presenti nella cartella all’area di staging (il punto.significa “aggiungi tutto”).
git commit -m "first commit"registra le modifiche in un nuovo commit; il messaggio dopo-mè obbligatorio.
git pushinvia effettivamente il commit alla repository su GitHub, rendendolo disponibile online.
add, commit e push per inviare i file su GitHub
La prima volta che eseguite git push, GitHub potrebbe richiedere un’ulteriore autenticazione tramite una finestra simile alla seguente. Seguite le istruzioni e completate l’accesso:
Una volta completato il processo, se tutto è andato a buon fine, tornando nella vostra repository online su GitHub vedrete che non è più vuota, ma contiene i file appena inviati. Perfetto!
Creazione di GitHub Pages
Questo ultimo passaggio serve solo se vogliamo creare un sito web basato sulla nostra repository. Non è obbligatorio: potremmo decidere di mantenere la repo privata, usarla solo con i collaboratori e non generare alcun sito. Tuttavia, se vogliamo rendere i nostri documenti HTML accessibili online tramite link, allora dobbiamo attivare GitHub Pages.
Ricordiamo anche che, salvo avere un account GitHub a pagamento, la repository deve avere visibilità Public (non Private) per poter utilizzare GitHub Pages.
Torniamo quindi su GitHub, apriamo la nostra repository e clicchiamo su Settings:
Scorriamo verso il basso fino alla sezione Pages:
Lasciamo l’opzione Source: Deploy from a branch (di solito è il default).
Poco sotto, in Branch, clicchiamo su None e selezioniamo invece main.
Infine clicchiamo su Save:
Nota importante: se lavoriamo con un progetto Quarto più complesso (ad esempio un sito, un blog o un libro), il contenuto renderizzato potrebbe trovarsi dentro una sottocartella chiamata docs o simili. In questo caso dovremo selezionare quella cartella al posto di / (root).
Dopo un minuto circa, aggiorniamo la pagina. Dovremmo vedere due conferme:
- Che il deploy è attivo su:
main > / (root)
- Che il sito è stato pubblicato, con il messaggio: “Your site is live at …”
L’URL generato sarà simile a:
https://<vostro-username>.github.io/<nome-repository>/
Se nella repository è presente un file index.html, questo verrà usato automaticamente come home page. Per questo motivo nominare il file principale index è particolarmente conveniente.
Gli altri file saranno accessibili tramite URL del tipo:
https://<vostro-username>.github.io/<nome-repository>/<nome-documento>.html
(oppure .pdf, .png, ecc.)
A questo punto possiamo verificare che la pagina sia effettivamente online:
Prossimi passi
Per qualsiasi progetto più avanzato, e in particolare per creare siti web strutturati, blog, libri online o documenti tecnici complessi, sarà necessario approfondire l’uso di Quarto, insieme ai linguaggi che lo supportano, come HTML, CSS, TeX, e altri strumenti che permettono di personalizzare la presentazione dei contenuti.
Questa sezione offre però alcuni comandi di base utili per iniziare a sviluppare progetti più articolati. I comandi vanno lanciati dal terminale, all’interno della cartella in cui intendete sviluppare il progetto, idealmente la stessa cartella collegata alla vostra repository GitHub se il vostro obiettivo è pubblicare online tramite GitHub Pages.
Comandi utili di Quarto
Creare un nuovo progetto generico
quarto create-project myproject
Renderizzare il progetto e generare le pagine
quarto render
Creare un progetto di tipo “sito web”
quarto create-project mywebsite --type website
Creare un progetto di tipo “blog”
quarto create-project myblog --type website:blog
Creare un progetto di tipo “libro online”
quarto create-project mybook --type book
Per tutto il resto, compresi temi avanzati, personalizzazioni grafiche, gestione di siti complessi e integrazioni con R, Python o bibliografie, si rimanda alla documentazione ufficiale: Guida completa di Quarto. Al seguente link trovate anche un’utilissima gallery di esempi: https://examples.quarto.pub/.
⚠️ Nota importante per il lavoro collaborativo su GitHub
Se state lavorando insieme ad altre persone sulla stessa repository, ricordate due regole fondamentali:
Prima di iniziare la vostra sessione di lavoro fate sempre:
git pull
per scaricare eventuali aggiornamenti caricati dai collaboratori.Evitare di lavorare in parallelo sugli stessi file, perché questo può portare a conflitti difficili da risolvere.
In generale, è buona pratica coordinarsi e lavorare in sequenza oppure su file diversi.