Alpha
Questa lezione è in fase alpha, il che significa che è stata insegnata una volta e gli autori stanno apportando modifiche basandosi sui feedback.
Perché dovrei usare GitHub o GitLab Pages per creare il mio sito
web?
Obiettivi
Spiega a cosa serve un generatore di siti statici.
Scegli lo strumento più adatto al tuo sito web/progetto.
Come funzionano i siti web
Quando usiamo un browser web per visitare una pagina del World-Wide
Web, il browser chiede informazioni a un server - un computer che
memorizza i dati rilevanti per il sito e che è configurato per ricevere
e rispondere alle richieste di tali dati. Supponendo che non ci siano
stati problemi in questa fase (ad esempio, la richiesta di una pagina
che non esiste o l’impossibilità di raggiungere il server), il nostro
browser riceve e interpreta queste informazioni per renderizzare e
visualizzare la pagina web sul nostro schermo.
Uno sviluppatore web probabilmente rimarrebbe sorpreso nel leggere
una così grossolana semplificazione, e questo è solo uno dei motivi per
cui gli sviluppatori web non sono il target di questo tutorial.
La pagina visualizzata dal browser web è il risultato della
combinazione di HTML - un formato gerarchico che
descrive gli elementi strutturali della pagina e il loro contenuto
grezzo - con CSS - un insieme ordinato di istruzioni di
stile che indicano al browser come il contenuto deve essere organizzato
e formattato - ed eventuali immagini che devono essere
incorporate nella pagina. Altre informazioni ricevute dal server, ma non
visualizzate dal browser, includono metadati,
cookies e altri elementi non visibili nell’HTML -
informazioni sul sito che potrebbero essere rilevanti per un computer ma
che probabilmente non sono interessanti per un essere umano (ci sono eccezioni
a questo) - e script che il browser può eseguire per fare qualcosa in
risposta a vari trigger.
Hello World in HTML
Quando si impara un nuovo linguaggio di programmazione, spesso si
trova un riferimento al famoso esempio Hello world. Questi
esempi sono in genere il codice più semplice in grado di produrre e
visualizzare il testo “Hello, World!” sullo schermo.
Poiché l’HTML richiede la presenza di alcuni tag e quasi sempre in
coppie corrispondenti (apertura <tag> e chiusura
</tag>), i documenti HTML tendono a diventare verbosi
piuttosto rapidamente.
Come potete immaginare, scrivere a mano lunghi documenti HTML è
piuttosto doloroso. Notate che non abbiamo specificato nulla su come e
dove il testo debba essere visualizzato.
Per ottenere questo risultato è necessario includere tag stilizzati o
istruzioni CSS (Cascading Style Sheets). Se non si forniscono istruzioni
CSS (all’interno del documento HTML o in un file separato), un browser
web farà un’ipotesi sulla disposizione degli elementi HTML nella pagina
in base alle sue impostazioni predefinite.
Richiamo
I molti tag dell’HTML
Nell’esempio Hello world di cui sopra vengono usati 5
tag diversi (html, head, title,
body e p) nella loro forma aperta
<> e chiusa </>. Vediamo anche il
tag speciale doctype che indica il formato e la versione
del documento, in questo caso, [HTML(5)][html5-wikipedia].
Esistono molti altri tag per definire:
elementi strutturali, come table,
div, span, nav,
section;
elenchi, come ul (per gli elenchi non
ordinati) e or (per gli elenchi ordinati);
elementi stilizzati, come i/em
(per i corsivi/enfasi), b/strong (per
il grosso) e u (per il testo
sottolineato);
intestazioni, numerate da h1 a h6
per i titoli e i sottotitoli progressivamente più piccoli;
elementi multimediali, come img,
video, audio per incorporare contenuti
multimediali ricchi; e
collegamenti, utilizzando l’importante tag a
(ancora) per collegarsi a sezioni della stessa pagina o ad altre pagine
dello stesso sito web o di siti esterni.
L’elenco dei tag
HTML validi è piuttosto esteso e copre una ricca gamma di
funzionalità che alimentano il world wide web di oggi.
Discussione
Esercizio: Scrivere HTML di base
Dato il testo stilizzato:
Hello, World!
scrivere l’HTML che produrrà lo stesso risultato. **Il carattere
grande è ottenuto grazie all’uso di un’intestazione.
Soluzione
HTML
<h1><em>Hello</em>, World!</h1>
Scriviamo un esempio HTML più complesso, utilizzando una tabella che
mostri il testo “Hello, World!” in diverse lingue e che si visualizzi
come segue:
L’HTML per produrre una tabella di questo tipo ha questo aspetto
(potete copiare e incollare lo snippet nel file HTML creato nell’esempio
precedente):
HTML
<table><tr><th>Language</th><th>Text</th></tr><tr><td>English</td><td>Hello, World!</td></tr><tr><td>French</td><td>Bonjour, le monde!</td></tr><tr><td>Portuguese</td><td>Olá, Mundo!</td></tr><tr><td>Serbian</td><td>Zdravo, svete!</td></tr></table>
Ogni riga è racchiusa tra i tag table
row <tr> e </tr>.
All’interno di una riga, i tag <th> e
</th> sono usati per contenere table
headings (speciali celle di tabella visualizzate in
grassetto), mentre le normali celle table
data sono contenute nei tag <td> e
</td>.
Un esempio simile scritto usando le liste HTML avrebbe il seguente
aspetto:
HTML
<ul><li>English: Hello, World!</li><li>French: Bonjour, le monde!</li><li>Portuguese: Olá, Mundo!</li><li>Serbian: Zdravo, svete!</li></ul>
Qui abbiamo usato i tag unordered
list <ul> e </ul>
per definire una lista con 4 elementi, ciascuno a sua volta avvolto in
singoli tag list item
(<li> e </li>).
Siti statici vs siti dinamici
Le pagine statiche sono quelle il cui contenuto è memorizzato su un
server in uno stato pronto per essere inviato a qualsiasi utente che
faccia una richiesta per quella pagina web. Quando viene effettuata una
richiesta, il server deve inviare solo le informazioni che compongono la
pagina web (come HTML e CSS). I siti che non cambiano spesso, come ad
esempio un sito web contenente il proprio CV, sono spesso memorizzati
come siti statici.
Al contrario, i siti dinamici sono quelli che hanno le loro
pagine generate quando un utente fa una richiesta per una pagina web. A
seconda del momento in cui viene fatta la richiesta, il contenuto può
cambiare; ad esempio, cliccando su aggiorna quando si visualizza una
discussione in un forum web, potrebbero apparire nuovi commenti. La
differenza fondamentale è che le pagine statiche devono essere generate
una sola volta, dopodiché rimangono invariate sul server, rispetto alle
pagine dinamiche che vengono rigenerate da un server ogni volta che
riceve una richiesta.
Richiamo
Esempi nel campo delle scienze della vita
Un tipico esempio di sito web statico nel campo delle
scienze della vita è la documentazione di uno strumento o di un formato
di file, come questa pagina di wwpdb.org.
Le pagine di ingresso del database
PDB, invece, caricano diversamente i contenuti sulla base degli
strumenti di visualizzazione e delle opzioni scelte dall’utente. Un
database o un webserver è di solito un sito web dinamico.
Questa lezione si concentra sui siti statici e sugli strumenti che
possono essere usati per crearli, noti come Generatori di siti
statici.
Uno dei vantaggi dell’uso dei generatori di siti statici è che
eliminano la necessità di produrre manualmente molto HTML, permettendoci
di concentrarci sul contenuto leggibile che vogliamo che le nostre
pagine contengano. Tuttavia, abbiamo bisogno di un modo per dire al
generatore come vogliamo che il nostro contenuto appaia quando viene
visualizzato nel browser. A tale scopo, utilizzeremo uno strumento
chiamato Markdown, che impareremo a conoscere in una puntata
successiva.
Figura 1.1: Alternative per la generazione di pagine. Questa
figura è una versione modificata dell’originale pubblicato in JavaScript for Data Science, ed è
riprodotta qui con il permesso dell’autore.
I siti generati staticamente sono un’ottima scelta quando le
informazioni che si desidera visualizzare su un sito web sono le stesse
indipendentemente da chi visita il sito e quando, e se è improbabile che
il contenuto delle pagine debba cambiare molto spesso. Ciò rende i
generatori di siti statici una buona scelta per i siti che forniscono
documentazione o contenuti didattici, come questa pagina: lo scopo della
pagina è fornire le stesse informazioni a ogni visitatore. Il visitatore
può arrivare, (si spera) trovare e leggere ciò di cui ha bisogno e
andarsene contento e soddisfatto.
I siti dinamici offrono molte più possibilità di fornire
interattività e contenuti personalizzati o di attualità. Tuttavia, la
loro creazione è un po’ più complicata e comporta un notevole onere
aggiuntivo per il server, non da ultimo in termini di requisiti
computazionali e di sicurezza. Tra l’altro, questo significa che, a
differenza delle pagine statiche (si veda il resto di questa lezione), è
improbabile trovare piattaforme a costo zero che vi aiutino a fornire
contenuti dinamici.
Discussione
Esercizio: Lo strumento perfetto per il
lavoro
Dati i seguenti tipi di siti web, chiedete se un generatore di siti
statici è una soluzione appropriata per implementarli.
Un sito web personale con le sezioni Chi siamo e
Progetti
Un forum o una piattaforma di discussione
Un blog o un sito di notizie della comunità
Un motore di ricerca (come google.com)
Un wiki (come wikipedia.com)
Un libro online
Soluzione
sito web personale: Nella maggior parte dei casi,
Sì. Questo tipo di contenuto è tipicamente
scritto/modificato da una sola persona e destinato ad avere un accesso
di sola lettura per i visitatori.
forum o discussione: Molto probabilmente
No. Un sito web di questo tipo richiede interattività e
modi per identificare chi ha scritto quale contenuto.
Per le domande 3 e 5 la risposta è sia Sì che
No a seconda dei requisiti e delle funzionalità
necessarie.
blog/news: Un semplice blog o un sito di notizie,
gestito da un piccolo gruppo di utenti, è perfettamente realizzabile
utilizzando un generatore statico. Per gruppi molto numerosi di creatori
di contenuti o se l’accesso agli articoli deve essere controllato
individualmente, l’uso di un generatore statico porterà a difficili
sfide tecniche.
motore di ricerca: Il più delle volte
No. Implementare qualcosa di sofisticato come la
ricerca di Google sarebbe quasi impossibile con un generatore statico.
Esistono modi per avere un semplice motore che cerca in tutte le pagine
prodotte da un generatore statico utilizzando l’indicizzazione e facendo
un uso intelligente delle caratteristiche del browser, ma questo
approccio ha molte limitazioni.
wiki: Un semplice wiki è perfettamente fattibile
con un generatore statico (ad esempio GitHub Wiki Pages),
ma diventa limitante non appena il suo contenuto deve essere modificato
o discusso da molti utenti, come nel caso di Wikipedia.
libro online: Sicuramente Sì. I
generatori statici sono perfetti per questo tipo di siti web. In genere
forniscono modi per evitare la ripetizione dei contenuti (variabili e
modelli), la creazione automatica di una Tabella dei contenuti,
e altre chicche.
Pagine GitLab
Se il sito che si vuole creare si adatta bene ai punti di forza di un
generatore di siti statici - è relativamente piccolo,
sarà aggiornato di rado, e il contenuto non ha
bisogno di essere personalizzato per il visitatore - allora
crearlo con GitLab Pages è una buona opzione. GitLab Pages è un sistema
che permette agli utenti di creare e servire siti web direttamente dai
loro repository GitLab. Il servizio è gratuito per i repository pubblici
e le pagine semplici possono essere create e servite con pochissima
configurazione.
Esamineremo un elenco di modelli, di complessità crescente. Mentre i
primi saranno basati su semplice Markdown, quelli più avanzati si
baseranno su più tecnologie (un esempio è mostrato nel diagramma
sottostante). All’inizio può sembrare opprimente, ma in questa lezione
spiegheremo la maggior parte di queste tecnologie; non tratteremo in
dettaglio solo CSS/Sass (linguaggio di styling che viene compilato in
CSS) e JavaScript/CoffeeScript (linguaggio di scripting che viene
compilato in JavaScript).
Per prima cosa, creeremo un progetto per archiviare i nostri file e
impareremo a scrivere e formattare il contenuto delle nostre pagine
usando HTML e Markdown, prima di configurare GitLab per visualizzare
questo contenuto come sito web usando GitLab Pages.
Impostazione di un progetto
Prima di iniziare a lavorare, dobbiamo creare un progetto in cui
lavorare. Questo progetto è simile a una cartella sul computer, con le
differenze principali che la cartella vive sul web in GitLab/GitHub
(anche se è possibile mantenerne una copia sul computer, se necessario)
e che la cartella utilizza un software di controllo di versione chiamato
git per tenere traccia
delle modifiche ai file. Per i nostri scopi ignoreremo il software di
controllo di versione, anche se può essere utile se si ha bisogno di
tornare a vecchie versioni (si veda Software Carpentry -
Version Control with Git per un’introduzione). In questa lezione
lavoreremo con questa cartella sul web per controllare il sito che
creeremo.
Richiamo
Accedere al proprio account GitLab
Prima di poter creare un progetto, è necessario effettuare il login
in GitLab
Ci sono due modi per creare un nuovo progetto:
Fare clic sul pulsante “+” nella barra di navigazione in alto e
scegliere “nuovo progetto”
o, se siete nella pagina dei progetti, fate clic sul
pulsante “Nuovo progetto”
Verrete reindirizzati a una pagina che fornisce tre opzioni:
Creare un progetto vuoto
Creare da un modello
Importazione del progetto Prendete il tempo necessario per leggere
le descrizioni dei diversi casi. Selezionate “Crea progetto vuoto”.
Successivamente dovrete inserire alcune informazioni sul vostro
progetto.
In questa lezione lavoreremo su un sito web generale di gruppo.
Potete immaginare che questo sito sia per il vostro gruppo di
laboratorio, per un gruppo di progetto specifico o per un altro gruppo
con cui lavorate. Nel campo “Nome del progetto”, digitate
group-website.
Il campo Project slug determinerà l’URL di accesso al
progetto e al sito web; viene generato automaticamente quando si riempie
il campo Project name. Lasciarlo così com’è.
Osservate il menu a tendina accanto al campo
Project URL. L’opzione predefinita è il proprio utente, che
si riferisce al proprio spazio dei nomi. Potrebbero essere disponibili
altri spazi dei nomi, a seconda dei gruppi a cui si appartiene. Ad
esempio, se questo è il sito web del vostro gruppo, potrebbe essere una
buona scelta selezionare lo spazio dei nomi del vostro gruppo per
ospitarlo. Questo sia per fornire un facile accesso al progetto agli
altri membri del gruppo, sia per avere il nome del gruppo (e non quello
dell’utente) nell’URL del sito. Tuttavia, inizializzeremo questo
progetto di prova nel nostro spazio dei nomi.
Possiamo anche aggiungere una descrizione (ad esempio “Progetto per
imparare a creare siti web con le pagine di GitLab”) in modo da sapere
di che progetto si tratta quando lo ritroveremo dopo il workshop.
Controlleremo anche l’opzione
Initialize repository with a README. È buona norma avere un
file README che fornisca ulteriori informazioni sul proprio repo.
Richiamo
GitLab vs GitHub
La maggior parte dei passaggi qui descritti sono molto simili in
GitHub. Ciò che GitLab chiama “Progetto”, in GitHub è un “Repository”,
quindi se il vostro istruttore confonde i due termini ecco perché.
Inoltre, i “Gruppi” sono in GitLab “organizzazioni”.
Le differenze più rilevanti riguardano il livello di visibilità e le
opzioni di configurazione. In GitHub, sono disponibili solo due opzioni
per un repository: “Pubblico” o “Privato”. GitLab dell’EMBL consente una
regolazione più specifica dei permessi attraverso l’opzione “Interno”,
cioè accessibile solo all’utente loggato. Infine, mentre GitLab permette
di inizializzare il repository solo con un README, GitHub include
l’opzione di inizializzarlo anche con un file .gitignore e di
licenza.
Una volta terminati questi passaggi, si può fare clic sul pulsante
Create Project. GitLab imposterà il repo e dovrebbe creare
un repo chiamato group-website con un file
README.md al suo interno. Quello che l’interfaccia grafica
ci ha appena aiutato a fare è fondamentalmente la seguente
procedura:
Prima di passare al capitolo successivo, date un’occhiata ai pulsanti
in alto, come Add LICENSE, Add CHANGELOG ecc.
che vi suggeriscono i possibili passi successivi. Per citarne uno, la
Licenza è sicuramente qualcosa che si potrebbe voler includere nel
proprio progetto. Non ci occuperemo di questo aspetto in dettaglio, ma
considerate che la licenza è una buona pratica (se non addirittura
necessaria) per qualsiasi progetto che includa dati o software. Il
vostro sito web, anche se molto semplice e statico, includerà una sorta
di dati, anche solo i nomi delle persone. Le tecnologie e i
modelli che userete per generarlo sono software. Una parola di
saggezza.
Punti Chiave
Un generatore di siti statici combina contenuti specifici per pagina
con elementi di layout e informazioni di stile per creare singole pagine
web.
GitHub/GitLab Pages è una buona scelta per chi ha già familiarità
con Git e GitHub/GitLab.
Questo approccio può essere utilizzato per creare un sito web/blog
relativamente piccolo con un budget limitato.
Come posso scrivere contenuti per le mie pagine web?
Come posso creare link ad altre pagine?
Obiettivi
creare semplici pagine di testo formattato
Markdown
Markdown è un linguaggio di markup leggero, cioè una convenzione per
aggiungere informazioni di stile al contenuto testuale. Come indica il
nome Markdown, gli elementi sintattici di questo linguaggio sono ridotti
al minimo. Avendo una sintassi piuttosto minimalista, il testo
formattato in Markdown è relativamente leggibile. Questo potrebbe essere
uno dei motivi per cui Markdown è diventato il linguaggio preferito per
la formattazione degli input dell’utente su siti web come, ad
esempio:
Esistono molti strumenti per il rendering del codice sorgente
Markdown. Il rendering è il processo di generazione di una visione
gradevole del contenuto utilizzando le informazioni di stile incluse nel
testo sorgente. È molto probabile che il vostro editor sia in grado di
farlo. Poiché stiamo lavorando per creare siti web utilizzando le pagine
di GitLab, utilizzeremo subito GitLab per imparare le basi di Markdown.
Il progetto GitLab creato nell’ultimo episodio contiene un file
README.md. Cliccare sul nome del file per accedervi.
L’immagine sottostante mostra la vista predefinita. Questa vista
include una vista renderizzata del contenuto all’interno del file
README.md, come quella della homepage del nostro
progetto.
I pulsanti sulla destra permettono di interagire con il file e la
visualizzazione. I primi due pulsanti, quelli con le icone, permettono
di passare da Display source a
Display rendered file. Passando il mouse su di essi, si
visualizzano i due messaggi in un tooltip. Il sorgente è la vista non
renderizzata del nostro file. Possiamo modificarla attraverso il
pulsante blu Edit. Fare clic su di esso.
Possiamo cambiare il contenuto e dare un’occhiata alla vista
renderizzata facendo clic sulla scheda Preview in alto.
Aggiungiamo Some **bold** font e vediamo cosa succede
quando lo visualizziamo in anteprima usando la scheda anteprima. Cosa è
successo al mondo in grassetto?
Per salvare il contenuto nel file README.md, si deve
cliccare sul pulsante Commit changes in fondo alla pagina.
Si noti che non si tratta di un semplice pulsante “Salva”, ma di un vero
e proprio commit. Questa versione del progetto sarà memorizzata in git
con il nome Commit message che si specificherà nel menu di
commit qui e nel ramo impostato come Target branch. Per il
momento abbiamo solo il ramo principale - quindi la scelta è ovvia - e
il messaggio di commit è precompilato con il nome del file appena
modificato. Si potrebbe voler essere più precisi nel messaggio di
commit, ma per il momento si può scegliere l’opzione predefinita.
Impegnare questa modifica.
Richiamo
Scrittura di un messaggio di commit
Un messaggio di commit è un commento breve, descrittivo e specifico
che ci aiuterà a ricordare in seguito cosa abbiamo fatto e perché. Per
saperne di più sulla scrittura di un messaggio di commit si veda questa
sezione della lezione di Git-novice.
L’interfaccia reindirizza alla pagina principale del progetto. In
alto, un messaggio dice “Le tue modifiche sono state impegnate con
successo” Le nostre modifiche sono state incluse nel file README, che
ora mostra la seconda riga con il carattere in grassetto.
Scrittura di Markdown
Ora che conosciamo l’interfaccia di modifica e la scheda di anteprima
dei nostri progetti README.md, possiamo usarlo come editor
di testo e studiare alcune caratteristiche di Markdown.
Il nostro README.md contiene già del testo e due
funzioni di formattazione:
Intestazione # group-website
Enfasi usando **bold**.
Impariamo un altro po’ di Markdown aggiungendo un po’ di
formattazione e vediamo cosa succede quando lo visualizziamo in
anteprima usando la scheda anteprima. Aggiungete quanto segue al vostro
file README.md.
MARKDOWN
# group-websiteRepo for learning how to make websites with GitLab pages## Learning MarkdownVanilla text may contain *italics* and **bold words**.This paragraph is separated from the previous one by a blank line.Line breaksare caused by two trailing spaces at the end of a line.[Carpentries Webpage](https://carpentries.org/)### Carpentries Lesson Programs:- Software Carpentry- Data Carpentry- Library Carpentry
Si può quindi fare di nuovo clic sulla scheda di anteprima per vedere
come viene resa la formattazione.
Richiamo
Gli spazi intermedi di Markdown sono
significativi
Nell’esempio precedente ci sono due spazi alla fine di
Line breaks. Questi introducono la cosiddetta
interruzione di riga dura, facendo sì che il paragrafo
continui nella riga successiva, aggiungendo un <br/>
all’HTML generato.
Se si interrompe la riga in un file markdown ma non si includono i
due spazi finali, l’HTML generato continuerà nella stessa riga
senza introdurre un <br/>. Questo si
chiama interruzione di riga morbida.
In alcuni casi è possibile che le interruzioni di riga
morbide introducano un <br/>. Questo può
accadere quando si usano diversi tipi di
markdown. {: .language-markdown }
Si può fare il commit di queste modifiche per salvarle. Ma prima,
facciamo un esercizio per provare a scrivere altro markdown.
Discussione
Esercizio: Prova il Markdown
Usate questo
cheatsheet per aggiungere quanto segue al vostro
README.md:
Un’altra intestazione di secondo livello
Un po’ di testo sotto il titolo di secondo livello che include un
link e un testo strikethrough.
Per esempio, il markdown potrebbe essere simile al seguente:
MARKDOWN
## More info on the lessonYou can find this lesson [here](https://grp-bio-it-workshops.embl-community.io/building-websites-with-gitlab/).### Four reasons you should learn Markdown:1. Less formatting than HTML2. Easy to read even with formatting3. Commonly used for websites and software development4. We ~~don't~~ use it in The Carpentries
Richiamo
Collegamenti di tipo referenziale
Finora abbiamo usato link in stile inline che hanno l’URL in
linea con il testo della descrizione, per esempio:
MARKDOWN
[Carpentries Webpage](https://carpentries.org/)
Se si usa un link più di una volta, si consideri di usare invece i
cosiddetti link in stile riferimento. I collegamenti in stile
riferimento fanno riferimento all’URL tramite un’etichetta. L’etichetta
va tra parentesi quadre [ ] subito dopo il testo
descrittivo del collegamento e poi più avanti, di solito in fondo alla
pagina, si può collegare l’etichetta all’URL a cui fa riferimento per
completare il collegamento. In questo modo si ottiene quanto segue:
Continueremo a usare Markdown e a saperne di più nel resto della
lezione. Sia che decidiate di strutturare il vostro sito web con
tecnologie basate su Markdown o su HTML, dovrete comunque conoscere
alcune nozioni di base di Markdown per modificare il vostro file README.
Il file README fornirà una guida essenziale - mostrata nella pagina di
destinazione del vostro progetto - ai vostri collaboratori e anche a voi
per capire di cosa tratta il progetto e come contribuire.
Richiamo
Tipi di Markdown
La descrizione iniziale di Markdown era informale e conteneva alcune
ambiguità, per cui nel corso degli anni sono apparse diverse
implementazioni di Markdown e variazioni della sintassi (spesso
indicate come “gusti”) per supportare varie caratteristiche ed
estensioni della sintassi. Di conseguenza, la sintassi di una variante
può non essere interpretata come ci si aspetta in un’altra: bisogna
essere consapevoli di quale sia quella utilizzata da una particolare
piattaforma. Ecco alcune varianti note:
Kramdown
(un’implementazione veloce, Ruby, open source rilasciata sotto licenza
MIT)
Mardown è anche il linguaggio della piattaforma di note collaborative
disponibile all’EMBL. È possibile accedervi [qui] (https://pad.bio-it.embl.de/). La piattaforma è basata su
CodiMD.
Discussione
Esercizio: Aggiungere i dettagli del proprio
progetto a CodiMD
Usare la sintassi Markdown per aggiungere un link nel documento di
appunti collaborativi che si sta usando per seguire questa lezione. Il
testo del link deve essere il proprio nome utente GitLab e la
destinazione il proprio repository.
Punti Chiave
Markdown è un modo relativamente semplice per scrivere testo
formattato
I tag Markdown e HTML possono essere utilizzati insieme in una
singola pagina
Consiglio di indicare i link in Markdown in stile
“reference-style”
La landing page di un sito web è convenzionalmente denominata
index.md
Come faccio a pubblicare le mie pagine tramite GitLab?
Obiettivi
pubblicare HTML sul web con GitLab Pages
Pagine GitLab
Richiamo
Solo siti web statici
Come anticipato nei capitoli precedenti, per pubblicare un sito web
con GitLab Pages si possono usare diverse tecnologie come Jekyll,
Gatsby, Hugo, Middleman, Harp, Hexo e Brunch, solo per citarne alcune. È
inoltre possibile pubblicare qualsiasi sito web statico scritto
direttamente in HTML, CSS e JavaScript. Pages non supporta
l’elaborazione dinamica lato server, come invece richiedono
.php e .asp.
La chiave per avere il sito web funzionante come previsto è il file
di configurazione di GitLab CI, chiamato .gitlab-ci.yml.
Questo file configura il modo in cui il sito web sarà costruito. È
scritto in YAML, che ha una propria sintassi che non
spiegheremo nei dettagli, quindi si consiglia di seguire questa guida
rapida prima di configurarlo. Per funzionare correttamente, deve essere
collocato nella directory principale, cioè allo stesso livello del
nostro file README, nella cartella principale del progetto.
Il fatto più importante è che con GitLab CI si ha il controllo sulle
proprie build. Non si troveranno in una scatola nera invisibile in cui
non si sa cosa stia succedendo! Sarete in grado di vedere qualsiasi
build in esecuzione dal vivo navigando nel Pipelines del
vostro progetto (lo faremo più avanti). È anche possibile aggiungere
qualsiasi comando allo script .gitlab-ci.yml. Questo
permette di fare sul server remoto praticamente tutto ciò che si fa
sulla macchina locale. Più avanti in questa lezione verranno illustrati
alcuni esempi su come eseguire comandi di compilazione personalizzati
attraverso il file .gitlab-ci.yml..
Richiamo
Lavorare localmente o in GitLab
Questa lezione non ha lo scopo di insegnare Git e come lavorare
localmente (nel proprio portatile) su un progetto versionato e gestito
in Git. Tuttavia, se si ha una conoscenza di base di Git, si possono
eseguire i passi successivi a livello locale per imparare a sviluppare
correttamente un sito web: testarlo localmente e fare il commit e il
push solo di versioni significative. Al contrario, lavorare sulla
piattaforma online ci costringerà a fare commit di versioni che non
saranno molto significative, per il gusto di imparare.
Se si ha una conoscenza di base di Git, è possibile configurare un
progetto locale per la distribuzione. Clonare il proprio
repository localmente (controllare la lezione git novice se si ha
bisogno di rivedere cosa fa il comando git clone e come
git push le modifiche da un progetto locale a uno remoto).
In breve, ora si dovrebbe eseguire, da un terminale:
e continuare a lavorare nella cartella clonata. Potete aggiungere e
modificare i vostri file tramite vim o da qualsiasi editor
di vostro gradimento - non è necessario lanciarlo dal terminale, ma
ricordatevi di tenere il terminale aperto per quando dovrete riportare
le modifiche sul remoto.
Inizieremo con l’esempio più semplice, un semplice sito HTML con
pagine GitLab.
Creiamo il file .gitlab-ci.yml direttamente nel nostro
progetto GitLab online. Avremo bisogno di lavorare su più file. Per
farlo, vogliamo aprire l’IDE Web facendo clic sul pulsante in alto a
destra del nostro progetto: Edit > Web IDE.
Se è la prima volta che lo si apre, apparirà un pannello di
personalizzazione. Ignoratelo per ora, ma sappiate che il
look-and-feel delle prossime schermate potrebbe differire da
quello che vedete in base al modello predefinito. Dovreste comunque
avere a disposizione gli stessi menu e file. In particolare, il
EXPLORER (un esploratore di file) sul lato destro elenca i
file e le cartelle del repository (al momento, dovrebbe esserci solo il
file README) e il pannello a destra mostra il contenuto di
tali file quando li si apre.
Passare il mouse sul nome del progetto nella cartella
EXPLORER per vedere un piccolo menu che include un’icona
per aggiungere file alla cartella. Fare clic su di essa e creare un file
.gitlab-ci.yml. Quindi, riempirlo con il seguente
contenuto:
Create il vostro file .gitlab-ci.yml e scriveteci
dentro:
YAML
pages:stage: deployscript:- echo 'Nothing to do...'artifacts:paths:- publiconly:- main
Questo codice crea un lavoro chiamato “pages” che dice a GitLab di
dispiegare il contenuto del sito web in
public, ogni volta che un commit viene
spinto e solo nel ramo principale. Non ha
molto da fare se non guardare il contenuto in pubblico, quindi la
configurazione dello “script” è fondamentalmente nulla (fa solo l’eco
“Nothing to do” al terminale).
Richiamo
Validazione del file gitlab-ci.yml
Prima di aggiungere qualsiasi .gitlab-ci.yml al
progetto, è possibile convalidarne la sintassi con lo strumento chiamato
[CI Lint] (https://docs.gitlab.com/ee/ci/lint.html). Per accedere a
questo strumento è necessario aver effettuato il login nel proprio
account. Lo si trova navigando nelle Pipeline del proprio progetto: c’è
un pulsante in alto a destra dello schermo. Per ulteriori informazioni,
è possibile leggere la documentazione
completa di .gitlab-ci.yml.
Richiamo
Rami Git e file GitLab CI
È possibile avere un .gitlab-ci.yml distinto per ogni
progetto, ma anche configurazioni GitLab CI distinte per ogni ramo.
Questo significa che si può testare lo script in rami paralleli prima di
inviarlo al ramo principale. Se la compilazione ha successo, si fa il
merge. In caso contrario, è possibile apportare modifiche e riprovare a
costruire senza rovinare il ramo principale.
Successivamente, creeremo la cartella public
(utilizzando l’icona nuova cartella nel menu EXPLORER),
contenente un file index.html.
Richiamo
Lavorare localmente o in GitLab
Se state lavorando in locale, potete farlo dal terminale
attraverso:
BASH
mkdir publiccat> public/index.html
popolate il nuovo file index.html con questo
contenuto:
Prima di proseguire con il capitolo, provate a immaginare quale sarà
la visualizzazione finale della pagina web risultante. Potete disegnarla
su un foglio di carta.
Richiamo
Lavorare localmente o in GitLab
se state lavorando in locale, ora eseguite il commit e il push delle
modifiche. È possibile farlo dalla cartella principale del progetto
attraverso:
BASH
git add .git commit -m"simple html in public"git push -u origin main
Se avete creato il file .gitlab-ci.yml e la cartella
public contenente il file index.html, dovreste
vederli tutti nella cartella EXPLORER. Ora, salviamo la
prima versione del nostro progetto (commit), selezionando il menu
Source control sul lato sinistro.
questo cambierà il pannello a sinistra, che elencherà i file
modificati (due file aggiunti) e chiederà all’utente di inserire un
messaggio di commit (una breve descrizione della versione del progetto
di cui si sta eseguendo il commit) nella casella di testo in alto. Il
nostro messaggio di commit in questo caso potrebbe essere: “Deploy
simple HTML through GitLab pipeline”. Inserire questo o un altro
messaggio e poi Commit to 'main'.
Tornare al progetto remoto in GitLab. La schermata seguente mostra
come dovrebbe apparire:
la cartella public contiene il file
index.html. Il comando push appena lanciato dovrebbe aver
attivato la prima pipeline. Nel menu a sinistra, scegliere
Build > Pipelines per visualizzarla.
Poiché ci siamo fermati e abbiamo controllato l’aspetto della nostra
cartella remota, la vostra pipeline potrebbe già essere . In caso contrario, è sufficiente attendere che lo
diventi.
Il vostro primo sito web è stato distribuito con successo! Vi
chiedete dove potete vederlo? Andate su Deploy > Pages.
L’URL del vostro sito web è riportato lì. Dovrebbe essere:
https://<your user name>.embl-community.io/group-website.
La schermata sottostante contiene anche un avviso interessante.
Leggere sempre questo tipo di messaggi richiesti dall’interfaccia di
GitLab, di solito sono rilevanti per l’utente. Dice: “Il controllo degli
accessi è abilitato per questo sito web di Pages; solo gli utenti
autorizzati potranno accedervi. Per rendere il sito web disponibile al
pubblico, andare in Impostazioni del progetto > Generali >
Visibilità e selezionare Tutti nella sezione Pagine” Il link rimanda
anche a un’ulteriore documentazione, se volete saperne di più. Seguite
le istruzioni se volete rendere pubblico il vostro sito web.
indipendentemente dal fatto che sia pubblico o meno, dovremmo essere
in grado di visualizzare il nostro sito web. Cliccate sul link ed eccolo
qui:
Discussione
Esercizio: Confronto con il proprio
schizzo
Il sito web appena implementato ha l’aspetto che pensavate, dato il
codice html nel file indice? Pensavate che sarebbe stato mostrato
qualcos’altro? Discutetene con il collega accanto a voi.
Discussione
Esercizio: Il template plain-html
GitLab fornisce una serie di modelli di pagine web distribuite
tramite Pages. Uno di questi si chiama “plain-html”, accessibile a questo link. La struttura
generale è abbastanza simile a quella che abbiamo appena utilizzato.
Andare alla cartella public. Ci sono due file qui, uno
style.css e uno index.html.
In questa lezione entreremo nel dettaglio del funzionamento del file
.css, ma potrebbe essere interessante dare un’occhiata alla
sua sintassi e al suo contenuto. Questo tipo di file viene utilizzato
per lo stile del contenuto HTML. Questo file specifico fornisce
istruzioni di stile per tre elementi: il body, il
navbar e il testo del collegamento (a)
all’interno della navbar, che cambia colore quando il mouse vi passa
sopra (a:hover). Non preoccupatevi ora di capire come
funziona esattamente, ma quando visualizzerete questa pagina,
ricordatevi di passare il mouse sopra i link della barra di navigazione
per vederli in azione.
Ora aprite il file index.html. Il suo contenuto è
riportato di seguito.
HTML
<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="generator" content="GitLab Pages"><title>Plain HTML site using GitLab Pages</title><link rel="stylesheet" href="style.css"></head><body><div class="navbar"><a href="https://pages.gitlab.io/plain-html/">Plain HTML Example</a><a href="https://gitlab.com/pages/plain-html/">Repository</a><a href="https://gitlab.com/pages/">Other Examples</a></div><h1>Hello World!</h1><p> This is a simple plain-HTML website on GitLab Pages, without any fancy static site generator.</p></body></html>
È ora di disegnare di nuovo! Disegnate la pagina web risultante, a
partire dal contenuto di questo file HTML. Suggerimento: la navbar è una
barra nella parte superiore della pagina, che ci permette di navigare
nel contenuto del sito.
Domanda facoltativa: come viene utilizzato il file .css?
Come fa il sito web a sapere qual è il file giusto da leggere?
Soluzione
potete andare sul sito
web distribuito per verificare come appare. Di seguito è riportata
una schermata del risultato:
C’è qualche differenza con il vostro schizzo?
Domanda facoltativa: il percorso del file .css è
specificato nel file .html, attraverso:
<link rel="stylesheet" href="style.css">.
Link utili
Ora avete gli strumenti minimi per poter giocare con HTML e css.
Potete copiare i due file dell’ultimo esercizio template nel vostro
repository e provare a modificare la dimensione del testo, il colore
della navbar, aggiungere collegamenti o la formattazione del testo. Se
decidete di creare un fork di questo repository per sperimentare, fate
come chiedono gli autori nel loro file README (un motivo in più per
consultare i file README di ogni altro progetto e compilarli con
attenzione): “Se avete biforcato questo progetto per uso personale, per
favore andate in Settings del vostro progetto e
rimuovete la relazione di biforcazione, che non sarà necessaria a meno
che non vogliate contribuire nuovamente al progetto upstream.”
Un ampio tutorial sugli elementi HTML, che include esempi di moduli,
media e link incorporati, si trova su w3schools. Oltre a
questa, molte altre risorse forniscono esercitazioni sull’HTML; potete
sicuramente sceglierne una che si adatti ai vostri gusti per saperne di
più.
Punti Chiave
GitLab serve le pagine nel tuo progetto in base a un file di
configurazione chiamato .gitlab-ci.yml
Come faccio a pubblicare pagine web tramite GitLab e Jekyll?
Obiettivi
Pubblica file Markdown come HTML sul web con GitHub Pages
Jekyll è un potente generatore di
siti statici che può aiutare nell’utilizzo di GitLab Pages. Crea
contenuti statici di siti web in HTML a partire da vari file presenti
nel repository (file Markdown, fogli di stile CSS, modelli/layout di
pagina, ecc.) Questo contenuto “compilato” viene poi servito come sito
web.
Jekyll facilita la gestione del sito web perché dipende dai modelli.
I modelli (o layout nella notazione di Jekyll) sono progetti che possono
essere riutilizzati da più pagine. Per esempio, noi (i vostri
istruttori) non abbiamo creato uno stile per ogni singolo esercizio di
questa lezione separatamente: abbiamo creato un modello che specifica
come gli esercizi devono essere mostrati (il riquadro arancione, il
riquadro delle soluzioni a discesa, ecc.) e ogni volta che tagghiamo un
blocco di testo come “Esercizio” viene mostrato in questo modo.
Tra poco parleremo dei layout di Jekyll; per ora iniziamo a imparare
Jekyll e il suo linguaggio di scripting chiamato Liquid.
Parametri globali
Anche in questo caso, attiveremo e personalizzeremo il nostro
deployment dal file .gitlab-ci.yml. Si può decidere di
modificare la versione precedente del repository
group-website, ma noi suggeriamo di crearne uno nuovo.
Seguire i passi di “Impostazione di un progetto” nell’introduzione,
se si desidera farlo. Creare/modificare il contenuto del file
.gitlab-ci.yml con:
Questo codice richiede che lo script venga eseguito nell’ambiente
dell’ultima versione di Ruby, installa la gemma Jekyll e costruisce il
sito nel percorso pubblico (creando la cartella in remoto, non ci si
deve preoccupare a questo punto). Il risultato riguarda solo il ramo
principale.
L’esecuzione di questa pipeline richiede anche un
Gemfile. Crearlo nella cartella principale con il seguente
contenuto:
source "https://rubygems.org"
gem "jekyll"
In breve, ma lo vedremo più in dettaglio, Jekyll cerca i file di
testo che iniziano con un’intestazione formattata in questo modo:
---
variable: value
other_variable: other_value
---
...stuff in the page...
e inserisce i valori di queste variabili nella pagina quando la
formatta. I tre trattini che iniziano l’intestazione devono
essere i primi tre caratteri del file: anche un solo spazio prima di
essi farà sì che Jekyll ignori il file.
Il contenuto dell’intestazione deve essere formattato come YAML e può
contenere booleani, numeri, stringhe di caratteri, elenchi e dizionari
di coppie nome/valore. I valori dell’intestazione sono indicati nella
pagina come page.variable. Ad esempio, questa pagina:
---
name: Science
---
{% raw %}Today we are going to study {{page.name}}.{% endraw %}
è tradotto in:
HTML
<html><body><p>Today we are going to study Science.</p></body></html>
:::::::::::::::::::::::::::::::::::::: challenge
Esercizio: La sintassi di Jekyll
Verificate la vostra comprensione della sintassi di Jekyll. In cosa
verrebbe tradotto questo template?
---
name: Tom
location: Heidelberg
---
{% raw %}{{page.name}} is in {{page.location}}. I believe {{page.location}} is a very nice city.{% endraw %}
Soluzione
HTML
<html><body><p>Tom is in Heidelberg. I believe Heidelberg us a very nice city.</p></body></html>
Le principali opzioni di configurazione di Jekyll sono specificate in
un altro file, chiamato _config.yml. Creiamo alcuni
parametri di configurazione per il nostro sito web.
Creare un file _config.yml nella directory principale
del sito.
Aggiungere i parametri description e email
come:
YAML
description: This project develops training materials for reseachers wanting to learn to build projectwebsites in GitLab Pages.email: team@carpentries.org
le impostazioni di configurazione globale di _config.yml
sono rese disponibili come variabile site.PARAMETER_NAME in
ogni pagina del sito. Quindi, il parametro globale email
che abbiamo definito sopra sarà accessibile come
site.email. Si noti che si tratta di parametri globali,
quindi diversi dai parametri locali specifici della pagina negli esempi
precedenti.
Per accedere al valore del parametro all’interno di una pagina, si
utilizza la notazione di Liquid per l’output del contenuto, circondando
una variabile tra parentesi graffe come
{% raw %}{{ variable }}{% endraw %}.
Richiamo
Parametri globali predefiniti
Oltre ai parametri globali definiti dall’utente, Jekyll mette a
disposizione un certo numero di utili
variabili predefinite a livello di sito all’interno del sito web:
per esempio {% raw %}{{ site.time }}{% endraw %} (l’ora
corrente) o {% raw %}{{ site.pages }}{% endraw %} (un
elenco di tutte le pagine).
Creare un file index.md nella cartella principale, con
il seguente contenuto:
MARKDOWN
{% raw %}---title: My first Jekyll page---{% endraw %}# Building Websites with Jekyll and GitLab## Description{% raw %}{{ site.description }}{% endraw %}Welcome to {% raw %}{{ page.title }}{% endraw %}Have any questions about what we do? [We'd love to hear from you!]({% raw %}mailto:{{ site.email }}{% endraw %})
Il progetto deve includere i seguenti file:
Impegnare e spingere le modifiche, quindi monitorare l’esecuzione
della pipeline e controllare il risultato finale all’URL
https://<your user name>.embl-community.io/group-website.
Discussione
Esercizio: Creare un parametro globale di
Twitter
In about.md abbiamo un URL di Twitter sotto la sezione
“Contatti”. Questa è un’informazione che potrebbe essere inserita nei
parametri globali di _config.yml, perché si potrebbe voler
ripetere in calce a ogni pagina. Apportare le modifiche al sito web per
estrarre l’URL di Twitter come parametro globale.
Soluzione
Aggiungere il parametro twitter a _config.yml:
YAML
description:"This research project develops training materials for reseachers wanting to learn to build projectwebsites in GitHub with GitHub Pages."email:"team@carpentries.org"twitter:"https://twitter.com/thecarpentries"
Utilizzare il parametro twitter in about.md:
MARKDOWN
# About## Project{% raw %}{{ site.description }}{% endraw %}## FundersWe gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.## Cite usYou can cite the project as:> *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*## Contact us- Email: [{% raw %}{{ site.email }}{% endraw %}](mailto:{% raw %}{{ site.email }}{% endraw %})- Twitter: [{% raw %}{{ site.twitter }}{% endraw %}]({% raw %}{{ site.twitter }}{% endraw %})
Si noti che non si dovrebbe vedere alcun cambiamento nel proprio
sito web. Tuttavia, ora è possibile accedere all’URL di Twitter da
qualsiasi pagina del sito, se necessario.
Parametri locali
Oltre ai parametri globali (a livello di sito) disponibili tramite la
variabile globale site, Jekyll mette a disposizione
informazioni locali (specifiche della pagina) tramite la
variabile page. Alcune di queste sono predefinite, come
page.title, che fornisce il titolo della pagina attualmente
attiva/visitata. Altri possono essere definiti autonomamente. Si veda
questo [elenco dei parametri predefiniti della pagina] (https://jekyllrb.com/docs/variables#page-variables).
È possibile definire parametri locali utilizzando la notazione YAML
all’interno di una pagina Markdown, includendola in un’intestazione di
pagina e delimitando l’intestazione con linee triple tratteggiate
---. Queste intestazioni sono chiamate front
matter e sono usate per impostare variabili e metadati sulle
singole pagine del sito Jekyll.
Qualsiasi file che contenga un blocco YAML front matter verrà
elaborato da Jekyll come un file speciale. Il front matter deve essere
la prima cosa nel file e deve avere la forma di un blocco YAML valido,
compreso tra linee triple tratteggiate.
Richiamo
I parametri globali e locali sono sensibili
alle maiuscole e minuscole
È importante notare che i parametri usati nei siti sono sensibili
alle maiuscole. Per convenzione, di solito sono tutti caratteri
minuscoli.
Ecco un esempio:
YAML
---layout: posttitle:"My first blog post"author:"Danger Mouse"---
Tra queste linee triple tratteggiate, è possibile sovrascrivere le
variabili predefinite (come page.layout o
page.title) o crearne di personalizzate di cui si ha
bisogno localmente nella pagina (come page.author). Queste
variabili saranno poi disponibili per l’accesso tramite i tag di Liquid
(ad esempio,
{% raw %}{{{% endraw %} page.title {% raw %}}}{% endraw %}
) più avanti nel file e anche in tutti i file che lo includono. Si noti
che queste variabili sono accessibili solo in quella pagina. Si otterrà
un errore se si cerca di fare riferimento a una
page.variable definita in una pagina diversa.
Discussione
Esercizio: Pratica con le variabili
locali
Esercitiamoci a creare e usare le variabili locali. Pensate a una
variabile locale che potreste voler usare solo nella vostra pagina
about.md o index.md. Se non vi viene in mente
nessuna, create una variabile locale chiamata “lezione-esempio” con il
valore di “https://carpentries.github.io/lesson-example/” e fatele
riferimento nel vostro index.md.
Cosa avete aggiunto al vostro index.md per creare questa
variabile? Dove è stata aggiunta la materia prima nel file
index.md? Come si fa riferimento a questa variabile?
Soluzione
Creare un’intestazione YAML all’inizio di index.md e
aggiungere la variabile lesson-example tra i delimitatori a
triplo trattino. Si può quindi fare riferimento al valore nella pagina
index.md come
{% raw %}{{{% endraw %} page.lesson-example {% raw %}}}{% endraw %}.
Il file dovrebbe ora apparire come:
MARKDOWN
---lesson-example: "https://carpentries.github.io/lesson-example/"---# Building Websites in GitHub## Description{% raw %}{{ site.description }}{% endraw %}More details about the project are available from the [About page](about).See some [examples of our work]({% raw %}{{{% endraw %} page.lesson-example {% raw %}}}{% endraw %}).Have any questions about what we do? [We'd love to hear from you!]({% raw %}mailto:{{ site.email }}{% endraw %})
Si noti che questa variabile non è accessibile dalla pagina
about.md ed è locale a index.md.
Aggiunta di nuove pagine
Il prossimo passo sarà creare un’altra pagina di questo sito web.
Idealmente, il nostro sito avrà più pagine e quindi, per mantenere
l’ordine, creeremo la cartella pages per memorizzarle. In
questa cartella, creare un file about.md con il seguente
contenuto:
MARKDOWN
{% raw %}---title: Aboutpermalink: /about/---{% endraw %}# About## Project{% raw %}{{ site.description }}{% endraw %}## FundersWe gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.## Cite usYou can cite the project as:> *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*## Contact us- Email: [{% raw %}{{ site.email }}{% endraw %}](mailto:{% raw %}{{ site.email }}{% endraw %})- Twitter: [@thecarpentries](https://twitter.com/thecarpentries)
Si noti che la posizione dell’URL di questa pagina è specificata
nell’intestazione, attraverso l’attributo permalink.
Questo è l’aspetto attuale delle vostre cartelle:
Ora si deve modificare il file index.md per includere un
link alla nuova pagina about, in modo da poterla raggiungere dalla
pagina principale. Aggiungere una riga al file index.md per
includere:
MARKDOWN
More details about the project are available from the [About page](about).
Il link in questa riga reindirizzerà a
https://<your user name>.embl-community.io/group-website/about,
che è l’URL della nostra nuova pagina about.
Impegnarsi, fare il push e andare sul proprio sito web per vedere le
modifiche. Si noti che i parametri del sito non saranno resi bene quando
si visualizzano i file in GitHub (saranno visualizzati come testo
{% raw %}{{ site.PARAMETER_NAME }}{% endraw %} piuttosto
che come valore reso del parametro), ma lo saranno nel sito web.
Richiamo
Riutilizzare e ridurre
I parametri globali di Jekyll sono un modo utile per mantenere tutta
la configurazione del sito in un unico posto (anche se li si usa solo
una volta). In combinazione con i layout/template di Jekyll (di cui
parleremo nel prossimo episodio), sono un ottimo modo per creare snippet
di markup riutilizzabili che possono essere ripetuti su più pagine o
addirittura su ogni pagina del sito. Il riutilizzo aiuta a ridurre la
quantità di codice da scrivere.
Link utili
Questo voleva essere solo un tutorial di base. Le possibilità di
personalizzazione dei siti con Jekyll vanno ben oltre quanto mostrato
qui, si potrebbe ad esempio:
progettazione di layout di pagina (come gli esercizi/soluzioni di
questa lezione),
lavorare con i loop per elaborare iterativamente variabili
contenenti più valori,
utilizzare i filtri per controllare il formato delle variabili
quando vengono inserite in una pagina,
e altro. Questa
lezione di The Carpentries, anche se pensata per GitHub, è una
risorsa preziosa per saperne di più su come farlo.
Se si sta cercando la documentazione ufficiale di GitLab sulle pagine
GitLab con Jekyll, seguire questo
link.
Infine, questo progetto
contiene un modello più elaborato di sito web basato su GitLab e
Jekyll.
Punti Chiave
Attraverso Jekyll, GitLab serve le pagine generate dai file
.md
Come faccio a pubblicare pagine web tramite GitLab e Sphinx?
Obiettivi
Pubblica i file reStructuredText come HTML sul web con GitHub
Pages
Sphinx è uno
strumento per generare pagine web o PDF, progettato principalmente per
creare la documentazione di un progetto. È stato originariamente creato
per la documentazione di Python, ma dispone di ottime strutture per la
documentazione di progetti software in una serie di lingue. I sistemi di
documentazione poliglotta potrebbero essere molto utili nel caso in cui
il vostro progetto aumenti di complessità o di numero di collaboratori,
quindi prendete nota di questo aspetto.
In questo capitolo della lezione utilizzeremo il linguaggio di
programmazione Python. Anche se non è strettamente necessario, vi
suggeriamo di familiarizzare con Python, poiché la sua spiegazione esula
dallo scopo di questa lezione. Si può scegliere di farlo seguendo la
lezione di The Carpentries Programming
with Python.
Discussione
Esercizio: Documentazione
In un gruppo, ogni membro deve aprire la documentazione di uno dei
seguenti pacchetti
Discutere quali sono i componenti comuni, cosa c’è di utile in questi
siti di documentazione, come affrontano i concetti generali sulla
documentazione, come sono simili e come sono diversi.
Mentre Jekyll converte i file Markdown (.md) in HTML,
Sphinx converte i file reStructureText (.rts). Sebbene
questi due formati possano sembrare molto simili a prima vista, sono
stati creati per due scopi diversi: Markdown per scrivere per il web,
reStructuredText per scrivere documentazione. Questo
post sul blog fornisce ulteriori approfondimenti su cosa significa
in pratica, il punto più importante che vorremmo sottolineare in questo
contesto è che reStructuredText è adatto anche alla conversione in PDF.
Questo lo rende uno strumento utile anche per lo sviluppo di documenti
che possono essere necessari sia online che in copia cartacea, ad
esempio materiali di formazione o l’agenda di una riunione.
Richiamo
Avvio rapido di Sphinx
Per chiarezza, i prossimi passi di questo capitolo si concentreranno
solo sui file di Sphinx che sono rilevanti per la generazione dei file
HTML. Tuttavia, installando Sphinx in locale, è possibile eseguire il
comando quickstart per avviare un progetto Sphinx di base. Si consiglia
vivamente questa opzione se si desidera approfondire la conoscenza di
come documentare con Sphinx. A questo scopo, riportiamo di seguito i
passi necessari.
Probabilmente il vostro sistema ha già installato Sphinx. Verificate
se è così digitando nel vostro terminale:
BASH
sphinx-build--version
Se non lo è, si potrà installare digitando:
BASH
pip install -U sphinx
Oppure consultare istruzioni più dettagliate per l’installazione
[qui] (https://www.sphinx-doc.org/en/master/usage/installation.html).
Una volta installato Sphinx, si può eseguire il comando quickstart per
avere una panoramica dell’insieme minimo di file necessari per costruire
la documentazione. Il comando seguente creerà un repository vuoto e vi
eseguirà questo comando:
BASH
mkdir sphinx-quickstart-testcd sphinx-quickstart-testsphinx-quickstart...Separate source and build directories (y/n)[n]:...Project name: My projectAuthor name(s):<Your name>Project release []:...Project language [en]:
Verranno generati diversi documenti. Ecco una panoramica:
I file rilevanti in questo contesto sono il file
index.rst - che è l’equivalente del nostro file
index.md nell’esempio con Jekyll - e il file
conf.py. Per questo motivo la lezione si sofferma solo su
di essi.
Creare una cartella di progetto vuota. Inizializziamo il nostro file
index.rst nella cartella principale del progetto.
MARKDOWN
.. this is a comment, it is not renderedSphinx Example Project's documentation======================================Contents:.. toctree:::maxdepth: 2
riporta l’intestazione principale del progetto e poi l’indice dei
contenuti attraverso l’“albero TOC”. Si può dare un’opzione numerica
maxdepth (noi l’abbiamo initalizzata a 2) per indicare la profondità
dell’albero; per impostazione predefinita, tutti i livelli sono inclusi.
Per saperne di più sull’albero Toc consultare questo
link. In breve, quando si aggiungono file *.rst alla nostra tabella
dei contenuti, questi devono essere elencati qui. Aggiungiamo un file
per vedere come funziona.
Creare un file about.rst, sempre nella cartella
principale, con il contenuto:
MARKDOWN
About=====Hello, this is the about page of my project.
Ora aggiungiamo questo file all’albero TOC modificando il file
index.rst:
MARKDOWN
.. this is a comment, it is not renderedSphinx Example Project's documentation======================================Contents:.. toctree:::maxdepth: 2 about.rst
Ecco fatto: la nostra home page (generata con il file
index.rst) ora rimanda alla pagina About
(about.rst). Quindi, scriviamo un file minimo
conf.py, sempre nella cartella principale.
BASH
# -- Project information -----------------------------------------------------project = 'My project'copyright = '2021, <Your name>'author = '<Your name>'release = '1.0'# -- Options for HTML output -------------------------------------------------html_theme = 'alabaster'
Per un elenco completo delle opzioni che possono essere specificate
in questo file, consultare la documentazione.
Richiamo
Avvio rapido di Sphinx
Ancora una volta, avere Sphinx installato localmente vi aiuterà nelle
fasi successive. Infatti, è possibile costruire il proprio sito web di
documentazione localmente attraverso il comando
sphinx-build . build/, da eseguire nella cartella
principale. Una volta eseguito, genererà il sito web di output nella
cartella build/. È possibile visualizzarlo semplicemente
aprendo il file index.html con il proprio browser
preferito.
Anche in questo caso, il file .gitlab-ci.yml è
necessario per specificare le istruzioni per la distribuzione in GitLab.
Compilarlo con:
YAML
pages:stage: deployimage: python:3.6script:- pip install -U sphinx- sphinx-build -b html . publicartifacts:paths:- public
Questo script: specifica il contenitore per la nostra pipeline
(Python, versione 3.6), installa Sphinx tramite Pip, esegue il comando
sphinx-build - che costruisce i file HTML nella cartella
principale (.) in una cartella public,
anch’essa creata. Infine, specifica dove trovare gli artefatti HTML
(nella cartella public appunto).
È tutto pronto. Ora dovremmo seguire ancora una volta “Impostazione
di un progetto” nell’introduzione
per impostare un progetto remoto in GitLab, impostandolo come remoto per
la nostra cartella locale con
git remote add origin <git URL>,
git add . && git commit -m <message> e poi
git push -u. Infine, monitorare l’esecuzione della pipeline
e verificare il risultato finale.
Punti Chiave
Attraverso Sphinx, GitLab serve le pagine generate dai file
.rst
Come faccio a pubblicare pagine web tramite GitLab e Jupyter
Books?
Obiettivi
Pubblica i notebook Jupyter come HTML sul web con GitHub Pages
Facciamo qualcosa di diverso, che vi suonerà un po’ più familiare se
siete abituati ai progetti Jupyter.
Dal loro sito web:
Il progetto Jupyter esiste per sviluppare software open-source,
standard aperti e servizi per il calcolo interattivo in decine di
linguaggi di programmazione.
I taccuini Jupyter consentono di creare e
condividere documenti contenenti codice attivo e testo narrativo. i
Jupyter Lab** ampliano le loro funzionalità creando un ambiente di
sviluppo interattivo (che consente di navigare nel file system e di
definire l’ambiente di codifica). Jupyter Hub è una
versione multiutente di Jupyer Lab che le istituzioni possono
implementare localmente (come abbiamo fatto noi dell’EMBL) (https://jupyterhub.embl.de/).
E libro Jupyer?
Jupyter Book è un progetto open source per la creazione di libri e
documenti di qualità a partire da materiale computazionale.
Il tutorial
completo vi guiderà attraverso le fasi di installazione e la
personalizzazione dettagliata disponibile, nel contesto di questa
lezione ci occuperemo solo delle basi. Prima di tutto, installiamo
Jupyter Book. Nel vostro terminale:
BASH
pip install -U jupyter-book
Attenzione: è necessario avere installato anche pip.
Ora, creiamo il nostro primo progetto di libro. Il comando
jupyter-book --help ci aiuterà a controllare le opzioni, ma
in questa lezione vi spoilereremo qualcosa: il comando
BASH
jupyter-book create jupyter-book-demo
il comando creerà un libro Jupyter di base in una cartella
jupyter-book-demo. Questa cartella include già i tre
elementi necessari per la creazione di un libro: un file
_config.yml, una tabella di contenuto _toc.yml
e il contenuto del libro in una raccolta di file MarkDown,
reStructuredText o Jupyter Notebook.
Dal momento che ci stiamo stancando di tutto questo sviluppo e
distribuzione, non vogliamo modificare nulla nel contenuto, ma diamo
priorità al fatto che sia pronto e funzionante in GitLab. Provate a
indovinare, cosa dobbiamo aggiungere? Un file
.gitlab-ci.yml.
Installa jupyter-book (o controlla che sia correttamente installato
in remoto).
Pulisce la cartella dai file risultanti da (eventuali) build
precedenti.
esegue il comando jupyter-book build ., che costruisce
il libro nella cartella in una sottocartella _build. Si può
controllare l’output eseguendo lo stesso comando nel terminale e ci si
renderà conto che i file HTML effettivi sono nella sottocartella
_build/html.
sposta quindi il contenuto HTML nella nostra solita cartella
public, dove sono memorizzati gli artefatti.
Discussione
Il tuo tempo per sperimentare con un
modello
Questo modello è volutamente minimale per dare la possibilità di
mettere alla prova le proprie capacità di lettura della documentazione.
Consultate le guide agli argomenti su jupyterbook.org e trovate
un modo per:
Aggiungere un’altra pagina chiamata “Informazioni” e collegata
all’indice.
Giocate con il formato dei file di questa nuova pagina, aggiungete
lo stesso tipo di contenuto nei formati MarkDown, reStructuredTex e
Notebook.
Aggiungere una figura e una didascalia.
Inserire una cella di codice. Se conoscete un qualsiasi linguaggio
di programmazione, aggiungete un semplice grafico e visualizzate
l’output di tale grafico nella vostra pagina.
Dove posso trovare progetti/temi predefiniti per il mio sito?
Obiettivi
Trovare e utilizzare modelli preesistenti per determinare le
tecnologie alla base di un progetto e gli stili del sito web
derivante
Altri modelli
Vi chiedete dove potete trovare altri esempi di progetti di pagine
GitLab? Controllate questo link.
Include più di 40 esempi, basati su diverse tecnologie. Anche in questi
casi, è buona norma rimuovere la relazione di fork se lo scopo è quello
di utilizzare il template per lo sviluppo del proprio sito web e non di
contribuire al template stesso. Alcuni esempi di template presenti in
questo repository sono:
courseware-template,
un template basato su Jekyll per il sito web di un corso. Lo si può
vedere in azione qui.
Include stili per formattare i contenuti delle lezioni, i quiz e le
diapositive.
jupyterbook,
un modello per generare libri e documenti che integrano codice Python.
Vedetelo reso qui.
Ora avete tutte le competenze necessarie per iniziare a giocare con
le pagine di GitLab. Sentitevi liberi di contattarci se avete domande o di
aprire un problema nei progetti modello per richiedere funzionalità o
sollevare problemi. Siete anche invitati a contribuire allo sviluppo dei
modelli di pagine, sia quelli esistenti che quelli nuovi che potrebbero
adattarsi ai vostri casi d’uso. Infine, consultate il prossimo capitolo
(bonus) per sapere come gestire gli errori nell’esecuzione della
pipeline, per poter risolvere eventuali errori di CI/CD!
Punti Chiave
Puoi trovare molti template preesistenti per siti su Internet
Puoi evitare lavoro superfluo basando i nuovi layout su quelli
precedenti
Come posso risolvere gli errori nelle pipeline di GitLab?
Obiettivi
Ricevi feedback da GitLab sul motivo per cui una pipeline non è
riuscita
Quando le cose vanno male
Finora abbiamo visto come utilizzare con successo varie tecnologie
per produrre un sito web. Ci sono però alcune situazioni in cui possono
fallire a causa di un errore di battitura o di informazioni mancanti.
Esamineremo uno di questi casi con un esempio di Jekyll.
Discussione
Esercizio: Risoluzione dei problemi di
Jekyll
Questo esercizio vi aiuterà a riconoscere gli errori più comuni
quando lavorate con questi elementi di un sito web Jekyll.
modificate il vostro file _config.yml e sostituite un
carattere : con uno = in una delle
variabili.
Soluzione
Per esempio, mail=team@carpentries.org invece di
mail:team@carpentries.org.
YAML
description:"This research project develops training materials for reseachers wanting to learn to build projectwebsites in GitHub with GitHub Pages."email:"team@carpentries.org"twitter:"https://twitter.com/thecarpentries
Se si naviga nel repository GitHub, si può vedere che qualcosa si
rompe in about.md, dove si usa
{% raw %}{{ site.twitter }}{% endraw %}, ma, contrariamente
a quanto si è visto prima con il Markdown non valido, Jekyll rifiuterà
di costruire il sito e produrrà un messaggio di errore.
Vedremo in seguito dove trovare i messaggi di errore e identificarne
la causa.
Se avete tenuto d’occhio la pagina di esecuzione della pipeline di
GitLab fino ad ora (CI/CD > Pipelines), potreste aver
notato che una volta che si spinge il risultato della pipeline “in
attesa”, poi inizia a “correre” e alla fine “passa”. Alla fine. Se non
lo fa, lo stato è “failed”, si può ricevere un’email al riguardo (a
seconda delle impostazioni del proprio account GitLab) e non bisogna
farsi prendere dal panico. Come possiamo invece capire cosa ha causato
l’errore e risolverlo? Lo stato “failed” è un pulsante,
clicchiamolo.
Ancora una volta, si può fare clic sul pulsante ❌ pages per accedere a maggiori dettagli, cioè al
registro completo dell’esecuzione della pipeline. Scorrendo la finestra
simile a un terminale, si può vedere come si è avviata, ha preparato gli
ambienti, ha installato le dipendenze e ha eseguito correttamente fino
al comando bundle exec jekyll build - public. Lo ricordate?
È il comando che lancia Jekyll, incluso nel file
.gitlab-ci.yml.
In base a ciò, abbiamo motivo di sospettare che l’errore sia legato
all’incapacità di Jekyll di costruire la pagina. Leggendo più
attentamente per ottenere maggiori dettagli, troviamo:
BASH
$ bundle exec jekyll build -d public------------------------------------------------Jekyll 4.2.1 Please append `--trace` to the `build` commandfor any additional information or backtrace.------------------------------------------------/usr/local/bundle/gems/safe_yaml-1.0.5/lib/safe_yaml/load.rb:143:in`parse': (/builds/hpg_ToyM/0/grp-bio-it/template-pages-jekyll/_config.yml): could not find expected ':' while scanning a simple key at line 3 column 1 (Psych::SyntaxError)
Questo significa due cose: in primo luogo, il log suggerisce un modo
per ottenere maggiori dettagli, cioè modificare il file
.gitlab-ci.yml aggiungendo --trace al comando
bundle exec jekyll build -d public, che diventa così
bundle exec jekyll build -d public --trace. Tuttavia, non
ne abbiamo bisogno: la frase successiva è abbastanza chiara. Dice che si
è verificato un errore nell’analisi del file _config.yml
perché Jekyll non ha trovato il carattere previsto :.
Poiché questo errore impedisce a Jekyll di costruire la pagina, il
processo non può continuare.
Richiamo
Il fallimento non rimuoverà il vostro sito
web
Dato il fallimento, vi starete chiedendo che fine abbia fatto il sito
web Se visitate l’indirizzo troverete che il sito è ancora
disponibile.
GitLab manterrà online la versione precedente fino a quando l’errore
non sarà risolto e una nuova compilazione sarà completata con
successo.
Dovremmo tornare al nostro file _config.yml e correggere
l’errore = che abbiamo fatto (di proposito, questa volta).
Poi si può spingere di nuovo il progetto e il problema è risolto!
Discussione
Esercizio: Pratica con la risoluzione dei
problemi di Jekyll
A volte gli errori di battitura possono cambiare il vostro sito web
in modo sorprendente. Sperimentiamo alcuni possibili problemi e vediamo
cosa succede.
Provare le modifiche elencate di seguito sul file
index.md e vedere cosa succede quando la pagina viene
visualizzata. Ogni volta si dovrà correggere l’errore precedente.
Usate una variabile globale o locale che non avete definito
prima.
Lasciare il trattino alla fine dell’intestazione YAML.
Non mettere uno spazio tra l’intestazione YAML e il resto della
pagina
Mettere l’intestazione YAML in una posizione diversa della
pagina.
Soluzione
Il punto in cui è stata usata la variabile undefined è vuoto, ma per
il resto non ci sono errori. Esempio:
MARKDOWN
Hi! {% raw %}{{ site.greeting }}{% endraw %}. What have you been up to?
L’intestazione viene visualizzata in qualche modo nel file e la
variabile definita va alla pagina indice invece che al link
impostato.
MARKDOWN
---lesson-example: "https://carpentries.github.io/lesson-example/"Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}
Questo non sembra influire sulla nostra pagina, ma spesso può
causare la rottura di pagine più complesse.
MARKDOWN
---lesson-example: "https://carpentries.github.io/lesson-example/"---Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}
Questo fa sì che l’intestazione venga visualizzata nella pagina e
interrompe il collegamento variabile creato.
MARKDOWN
Examples of our work can be found at: {% raw %}{{ page.lesson-example }}{% endraw %}---lesson-example: "https://carpentries.github.io/lesson-example/"---
Nota: assicurarsi di correggere eventuali errori introdotti
intenzionalmente nella pagina prima di andare avanti.
Punti Chiave
Se una pipeline fallisce, GitLab ti fornirà un feedback utile sul
motivo
. In caso contrario, è sufficiente attendere che lo
diventi.
