Introduzione

Overview

Teaching: 0 min
Exercises: 0 min

Questions

What is static web content?

Why should I use GitHub or GitLab Pages to create my website?

Objectives

Explain what a static site generator does.

Choose the appropriate tool for your website/project.

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 inorridito 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][qwantz-easter-egg-ext] 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.

Il più semplice HTML valido Hello world è:

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <p>Hello, World!</p>
  </body>
</html>

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.

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][html5-tags] è piuttosto esteso e copre una ricca gamma di funzionalità che alimentano il world wide web di oggi.

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
<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: Esempio di tabella
HTML

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):

<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: Esempio di
lista 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.

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][js4ds], 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.

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.

(1) Un sito web personale con le sezioni Chi siamo e Progetti

(2) Un forum o una piattaforma di discussione

(3) Un blog o un sito di notizie della comunità

(4) Un motore di ricerca (come google.com)

(5) Un wiki (come wikipedia.com)

(6) Un libro online

Soluzione

(1) 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.

(2) 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.

(3) 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.

(4) 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.

(5) 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.

(6) 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).

Siti web statici nel diagramma della panoramica tecnologica di GitHub
Pages

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.

Accedere al proprio account GitLab

Prima di poter creare un repo, è necessario effettuare il login nel EMBL GitLab

Ci sono due modi per creare un nuovo progetto:

Fare clic sul pulsante “+” nella barra di navigazione in alto e scegliere “nuovo progetto”

Plus button

o, se siete nella pagina dei progetti, fate clic sul pulsante “Nuovo progetto”

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.

Pagina vuota del nuovo repository

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.

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:

mkdir group-website
cd group-website
git init
cat > README.md
git add README.md
git commit -m "Initial commit"

Su un server remoto. Il ramo predefinito è main.

repository Github per il sito web del
gruppo

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.

[qwantz-easter-egg-ext]: https://chrome.google.com/webstore/detail/dinosaur-comics-easter-eg/bojkkeeefjmeogpgnlomodfkkfkfhabj [js4ds]: http://js4ds.org [html5-tags]: https://www.w3schools.com/TAGS/default.asp

Key Points

A static site generator combines page-specific content with layout elements and styling information to construct individual webpages.

GitHub/GitLab Pages is a good choice for people who are already familiar with Git and GitHub/GitLab.

This approach can be used to create a relatively small website/blog on a limited budget.

Scrivere con Markdown

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How can I write content for my webpages?

How do I link to other pages?

Objectives

create simple pages of formatted text

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:

Dove iniziare a scrivere Markdown?

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.

anteprima README

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.

Interfaccia di modifica del file README dei siti web del
gruppo

Possiamo cambiare il contenuto e dare un’occhiata alla vista renderizzata facendo clic sulla scheda Preview in alto.

Anteprima del contenuto renderizzato del file README dei siti web del
gruppo

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.

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.

Dopo il commit delle modifiche al README

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.

# group-website
Repo for learning how to make websites with GitLab pages

## Learning Markdown

Vanilla text may contain *italics* and **bold words**.

This paragraph is separated from the previous one by a blank line.
Line breaks
are 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.

Anteprima della formattazione aggiunta al
README

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 sapori 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.

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~~.

un titolo di terzo livello

un elenco numerato

Bonus: Aggiungi questa immagine https://github.com/carpentries/carpentries.org/blob/main/images/TheCarpentries-opengraph.png
Soluzione di esempio

Per esempio, il markdown potrebbe essere simile al seguente:
## More info on the lesson
You 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 HTML
2. Easy to read even with formatting
3. Commonly used for websites and software development
4. We ~~don't~~ use it in The Carpentries

![Carpentries Logo](https://github.com/carpentries/carpentries.org/raw/main/images/TheCarpentries-opengraph.png)

Collegamenti di tipo referenziale

Finora abbiamo usato link in stile inline che hanno l’URL in linea con il testo della descrizione, per esempio:
[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:
[Carpentries Webpage][carpentries]

[carpentries]: https://carpentries.org/

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.

Sapori 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:

GitLab-flavored Markdown (usato in questa lezione e da GitLab)

[GitHub-flavored Markdown][github-flavored-markdown] (usato da GitHub)

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.

Esercizio: Aggiungere i dettagli del proprio repository 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.

[github-flavored-markdown]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Key Points

Markdown is an relatively easy way to write formatted text

Markdown and HTML tags can be used together in a single page

I recommend writing Markdown links ‘reference-style’

The landing page for a website is conventionally named index.md

Ospitare pagine su GitLab

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish my pages via GitLab?

Objectives

publish HTML on the web with GitLab Pages

Pagine GitLab

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..

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:
git clone https://git.embl.de/<your username>/group-website.git
cd group-website
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.

Modifica 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:

pages:
  stage: deploy
  script:
    - echo 'Nothing to do...'
  artifacts:
    paths:
      - public
  only:
    - 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).

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.

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.

Lavorare localmente o in GitLab

Se state lavorando in locale, potete farlo dal terminale attraverso:
mkdir public
cat > public/index.html

popolate il nuovo file index.html con questo contenuto:

<html>
    <head>
        <title>Home</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

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.

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:
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.

pulsante di controllo della versione IDE

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'.

IDE version control

Tornare al progetto remoto in GitLab. La schermata seguente mostra come dovrebbe apparire:

Schermata del progetto HTML semplice

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.

Prima pipeline in esecuzione

Poiché ci siamo fermati e abbiamo controllato l’aspetto della nostra cartella remota, la vostra pipeline potrebbe già essere passed . 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.

L'URL della pagina in Impostazioni>Pagine

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:

Sito web semplice

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.

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.
<!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ù.

Key Points

GitLab serves pages in your project according to a configuration file called .gitlab-ci.yml

Pagine GitLab con Jekyll

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Jekyll?

Objectives

Publish Markdown files as HTML on the web with GitHub Pages

Jekyll è un potente generatore di siti statici che può stare dietro a 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:

image: ruby:latest

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  only:
    - main

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
---
Today we are going to study {{page.name}}.

è tradotto in:

<html>
  <body>
    <p>Today we are going to study Science.</p>
  </body>
</html>

Esercizio: La sintassi di Jekyll

Verificate la vostra comprensione della sintassi di Jekyll. In cosa verrebbe tradotto questo template?
---
name: Tom
location: Heidelberg
---
{{page.name}} is in {{page.location}}. I believe {{page.location}} is a very nice city.
Soluzione
<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:

description: This project develops training materials for reseachers wanting to learn to build project
websites 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 {{ variable }}.

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 {{ site.time }} (l’ora corrente) o {{ site.pages }} (un elenco di tutte le pagine).

Creare un file index.md nella cartella principale, con il seguente contenuto:

---
title: My first Jekyll page
---

# Building Websites with Jekyll and GitLab

## Description
{{ site.description }}
Welcome to {{ page.title }}

Have any questions about what we do? [We'd love to hear from you!](mailto:{{ site.email }})

Il progetto deve includere i seguenti file:

Basic Jekyll

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.

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:
description: "This research project develops training materials for reseachers wanting to learn to build project
websites in GitHub with GitHub Pages."
email: "team@carpentries.org"
twitter: "https://twitter.com/thecarpentries"
Utilizzare il parametro twitter in about.md:
# About

## Project

{{ site.description }}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

> *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{{ site.email }}](mailto:{{ site.email }})
- Twitter: [{{ site.twitter }}]({{ site.twitter }})
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.

Materia prima

Da sito web di 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.

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:

---
layout: post
title: "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, {{ page.title }} ) 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.

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 {{ page.lesson-example }}. Il file dovrebbe ora apparire come:
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---

# Building Websites in GitHub

## Description
{{ site.description }}

More details about the project are available from the [About page](about).

See some [examples of our work]({{ page.lesson-example }}).

Have any questions about what we do? [We'd love to hear from you!](mailto:{{ site.email }})
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:

---
title: About
permalink: /about/
---

# About

## Project

{{ site.description }}

## Funders

We gratefully acknowledge funding from the XYZ Founding Council, under grant number 'abc'.

## Cite us

You can cite the project as:

>    *The Carpentries 2019 Annual Report. Zenodo. https://doi.org/10.5281/zenodo.3840372*

## Contact us

- Email: [{{ site.email }}](mailto:{{ site.email }})
- 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:

Informazioni su Jekyll

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:

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 {{ site.PARAMETER_NAME }} piuttosto che come valore reso del parametro), ma lo saranno nel sito web.

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.

Key Points

Through Jekyll, GitLab serves pages are generated from .md files

Pagine GitLab con Sphinx

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Sphinx?

Objectives

Publish reStructuredText files as HTML on the web with 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.

Esercizio: Documentazione

In un gruppo, ogni membro deve aprire la documentazione di uno dei seguenti pacchetti

pytest

seaborn

numpy

scipy-cookbook

scikit-learn

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.

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:
sphinx-build --version
Se non lo è, si potrà installare digitando:
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:
mkdir sphinx-quickstart-test
cd sphinx-quickstart-test
sphinx-quickstart
...
Separate source and build directories (y/n) [n]:
...
Project name: My project
Author 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.

.. this is a comment, it is not rendered

Sphinx 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:

About
=====

Hello, this is the about page of my project.

Ora aggiungiamo questo file all’albero TOC modificando il file index.rst:

.. this is a comment, it is not rendered

Sphinx 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.

# -- 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.

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:

pages:
  stage: deploy
  image: python:3.6
  script:
    - pip install -U sphinx
    - sphinx-build -b html . public
  artifacts:
    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

` e poi `git push -u`. Infine, monitorare l'esecuzione della pipeline e verificare il risultato finale. [cc-by-human]: https://creativecommons.org/licenses/by/4.0/ [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode [ci]: http://communityin.org/ [coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html [coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html [concept-maps]: https://carpentries.github.io/instructor-training/05-memory/ [contrib-covenant]: https://contributor-covenant.org/ [contributing]: /blob//CONTRIBUTING.md [cran-checkpoint]: https://cran.r-project.org/package=checkpoint [cran-knitr]: https://cran.r-project.org/package=knitr [cran-stringr]: https://cran.r-project.org/package=stringr [dc-lessons]: http://www.datacarpentry.org/lessons/ [email]: mailto:team@carpentries.org [filters]: https://jekyllrb.com/docs/liquid/filters/ [github-importer]: https://import.github.com/ [importer]: https://github.com/new/import [jekyll-collection]: https://jekyllrb.com/docs/collections/ [jekyll-install]: https://jekyllrb.com/docs/installation/ [jekyll-windows]: http://jekyll-windows.juthilo.com/ [jekyll]: https://jekyllrb.com/ [jupyter]: https://jupyter.org/ [kramdown]: https://kramdown.gettalong.org/ [lc-lessons]: https://librarycarpentry.org/lessons/ [lesson-aio]: ../aio/index.html [lesson-coc]: ../CODE_OF_CONDUCT.html [lesson-example]: https://carpentries.github.io/lesson-example/ [lesson-license]: ../LICENSE.html [lesson-mainpage]: ../index.html [lesson-reference]: ../reference.html [lesson-setup]: ../setup.html [mit-license]: https://opensource.org/licenses/mit-license.html [morea]: https://morea-framework.github.io/ [numfocus]: https://numfocus.org/ [osi]: https://opensource.org [pandoc]: https://pandoc.org/ [paper-now]: https://github.com/PeerJ/paper-now [python-gapminder]: https://swcarpentry.github.io/python-novice-gapminder/ [pyyaml]: https://pypi.org/project/PyYAML/ [r-markdown]: https://rmarkdown.rstudio.com/ [rstudio]: https://www.rstudio.com/ [ruby-install-guide]: https://www.ruby-lang.org/en/downloads/ [ruby-installer]: https://rubyinstaller.org/ [rubygems]: https://rubygems.org/pages/download/ [styles]: https://github.com/carpentries/styles/ [swc]: https://software-carpentry.org/ [swc-git]: http://swcarpentry.github.io/git-novice/ [swc-lessons]: https://software-carpentry.org/lessons/ [swc-releases]: https://github.com/swcarpentry/swc-releases [swc-shell]: http://swcarpentry.github.io/shell-novice/ [training]: https://carpentries.github.io/instructor-training/ [workshop-repo]: https://github.com/carpentries/workshop-template [yaml]: http://yaml.org/

Key Points

Through Sphinx, GitLab serves pages are generated from .rst files

Pagine GitLab con libri Jupyter

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I publish web pages through GitLab and Jupyter books?

Objectives

Publish Jupyter notebooks as HTML on the web with 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:

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

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.

pages:
  stage: deploy
  image: python:slim
  script:
    - pip install -U jupyter-book
    - jupyter-book clean .
    - jupyter-book build .
    - mv _build/html public
  artifacts:
    paths:
      - public

Questo pezzo di codice:

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.

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.

Per funzioni di codice più avanzate, controllare come rendere il codice eseguibile

Controllare la galleria di libri Jupyter per trarre ispirazione!

Key Points

Through Jupyter books, you’ll be able to integrate interactive components and code in your web pages

Modelli di GitLab

Overview

Teaching: 0 min
Exercises: 0 min

Questions

Where can I find pre-built projects/themes for my site?

Objectives

Find and fork pre-existing templates to determine the technologies behind a project and the styles of the deriving website

Modelli di Bio-IT

I modelli che abbiamo sviluppato insieme sono disponibili nella nostra piattaforma GitLab:

Potrebbero essere leggermente arricchiti rispetto a quanto abbiamo visto in questa lezione, per esempio il modello HTML semplice presenta anche un file .css, ma sono tenuti al minimo di proposito. Se volete usarli come base per un vostro progetto, dovreste fornirli. Se lo si fa per sviluppare un proprio progetto e non per contribuire al template stesso, si deve poi rimuovere la relazione di fork. Esaminiamo insieme il processo.

fork di un repository tramite il pulsante Fork

Fare il fork di un progetto facendo clic sul pulsante “Fork” a destra del titolo del progetto. Si aprirà un menu (mostrato di seguito) molto simile a quello che appare quando si apre un nuovo progetto. Si può decidere di mantenere il progetto privato e di modificarne il titolo e la descrizione. È anche possibile inserirlo nel gruppo/spazio dei nomi pertinente.

Una volta terminato, rimuovere la relazione di fork. È possibile modificare le impostazioni del progetto nel menu a sinistra della pagina del progetto, seguendo: Settings > General > Advanced e poi scorrere fino alla scheda “Rimuovi relazione di fork”.

rimuovere la relazione fork

Una volta fatto questo, si può clonare il repository in locale e iniziare a modificare il template. Se avete bisogno di un riassunto su clonazione, biforcazione, push e pull in Git, date un’occhiata a questa lezione di The Carpentries.

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.
hugo blog template, il template per costruire blog basato su Hugo.
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!

Key Points

You can find many pre-existing templates for sites on the Internet

You can find the presented themes for sites in our local GitLab

You can avoid duplicated effort by basing new layouts on previous ones

Quando le cose vanno male

Overview

Teaching: 0 min
Exercises: 0 min

Questions

How do I troubleshoot errors in the GitLab pipelines?

Objectives

Get feedback from GitLab about why a pipeline failed

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.

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.
description: "This research project develops training materials for reseachers wanting to learn to build project
websites 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 {{ site.twitter }}, 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.

cliccare sul pulsante fallito per accedere al log della
pipeline

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:

$ bundle exec jekyll build -d public
                    ------------------------------------------------
      Jekyll 4.2.1   Please append `--trace` to the `build` command
                     for 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.

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!

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:
Hi! {{ site.greeting }}. 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.
---
lesson-example: "https://carpentries.github.io/lesson-example/"

Examples of our work can be found at: {{ page.lesson-example }}
Questo non sembra influire sulla nostra pagina, ma spesso può causare la rottura di pagine più complesse.
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---
Examples of our work can be found at: {{ page.lesson-example }}
Questo fa sì che l’intestazione venga visualizzata nella pagina e interrompe il collegamento variabile creato.
Examples of our work can be found at: {{ page.lesson-example }}
---
lesson-example: "https://carpentries.github.io/lesson-example/"
---
Nota: assicurarsi di correggere eventuali errori introdotti intenzionalmente nella pagina prima di andare avanti.

Key Points

If a pipeline fails, GitLab will provide you useful feedback on why

Costruire siti web con GitLab

Introduzione

Overview

Come funzionano i siti web

Hello World in HTML

I molti tag dell’HTML

Esercizio: Scrivere HTML di base

Hello, World!

Soluzione

Siti statici vs siti dinamici

Esempi nel campo delle scienze della vita

Esercizio: Lo strumento perfetto per il lavoro

Soluzione

Pagine GitLab

Impostazione di un progetto

Accedere al proprio account GitLab

GitLab vs GitHub

Key Points

Scrivere con Markdown

Overview

Markdown

Dove iniziare a scrivere Markdown?

Scrittura di un messaggio di commit

Scrittura di Markdown

Gli spazi intermedi di Markdown sono significativi

Esercizio: Prova il Markdown

Soluzione di esempio

Collegamenti di tipo referenziale

Sapori di Markdown

Esercizio: Aggiungere i dettagli del proprio repository a CodiMD

Key Points

Ospitare pagine su GitLab

Overview

Pagine GitLab

Solo siti web statici

Lavorare localmente o in GitLab

Validazione del file gitlab-ci.yml

Rami Git e file GitLab CI

Lavorare localmente o in GitLab

Lavorare localmente o in GitLab

Esercizio: Confronto con il proprio schizzo

Esercizio: Il template plain-html

Soluzione

Link utili

Key Points

Pagine GitLab con Jekyll

Overview

Parametri globali

Esercizio: La sintassi di Jekyll

Soluzione

Parametri globali predefiniti

Esercizio: Creare un parametro globale di Twitter

Soluzione

Parametri locali

Materia prima

I parametri globali e locali sono sensibili alle maiuscole e minuscole

Esercizio: Pratica con le variabili locali

Soluzione

Aggiunta di nuove pagine

Riutilizzare e ridurre

Link utili

Key Points

Pagine GitLab con Sphinx

Overview

Esercizio: Documentazione

Avvio rapido di Sphinx

Avvio rapido di Sphinx

Key Points

Pagine GitLab con libri Jupyter

Overview

Il tuo tempo per sperimentare con un modello

Key Points

Modelli di GitLab

Overview

Modelli di Bio-IT

Altri modelli

Key Points

Quando le cose vanno male

Overview

Quando le cose vanno male