Capitolo 4: Scrivere il tuo primo articolo

I formati TOML, YAML e JSON

Hugo ti consente di utilizzare 3 diverse notazioni di dati nel file di configurazione e nella parte anteriore di ogni pagina di contenuto. TOML, YAML e JSON sono tutti linguaggi popolari che raggiungono lo stesso obiettivo di specificare coppie chiave -> valore. La lingua predefinita per Hugo è TOML, dato che si tratta di uno dei formati file di configurazione più semplice da comprendere e scrivere.

Sintassi TOML

TOML condivide tratti con altri formati di file utilizzati per la configurazione delle applicazioni e la serializzazione dei dati, come YAML e JSON. TOML e JSON sono entrambi semplici e usano tipi di dati onnipresenti, rendendoli facili da codificare o analizzare con le macchine. TOML e YAML enfatizzano entrambi le caratteristiche di leggibilità umana, come i commenti che rendono più facile capire lo scopo di una data linea. TOML differisce nel combinare queste caratteristiche, permettendo commenti (a differenza di JSON) ma preservando la semplicità (a differenza di YAML).

Un qualsiasi parametro in TOML è definito come: nomeParametro = valore dove nomeParametro è il nome del parametro che vogliamo dare mentre valore rappresenta il dato che si vuole memorizzare. TOML è case-sensitive (nomeVariabile è diverso da Nomevariabile). Per semplicità, considerate il linguaggio TOML come una tabella a doppia colonna, la prima rappresenta il nome del parametro mentre la seconda è il valore contenuto.

Alcune avvertenze per iniziare ad utilizzare il linguaggio TOML:

I valori possono essere:
- stringhe – tra apici singoli oppure tra apici doppi, es: “ciao”;
- stringhe composte da più linee – in questo caso si utilizza """ all’inizio e alla fine;
- numeri – interi, razionali, es: +4, -2, 10e8, ma anche binari (prefisso 0b), esadecimali (prefisso 0o) o esadecimali (prefisso 0x);
- booleani (true/false)
- date (compatibili con RFC 3339 o ISO 8601)
- array (racchiudendo i valori con [ e ] separati da una virgola, es: [1, 2, "banana"]);
- tabelle
Non può essere messa più di una variabile su una riga;
Si può commentare, utilizzando #;
Il nome del parametro può contenere solo lettere ASCII, underscores e trattini (A-Za-z0-9_-);

Il formato Markdown

Puoi inserire qualsiasi tipo di file nelle tue cartelle /content, ma Hugo usa principalmente due tipi di formati: HTML e Markdown. Di seguito una semplice guida su come utilizzare il Markdown.

Titoli

Uno o più simboli # definiscono le gerarchie nella titolazione, è importante lasciare un spazio fra il simbolo e il testo.

# Titolo 1
## Titolo 2
### Titolo 3
#### Titolo 4
##### Titolo 5
###### Titolo 6

Formattazione al testo

Grassetto

Il grassetto si ottiene mettendo due asterischi prima e dopo il testo, senza spazi.

ciao, **questo è un testo grassetto**

Corsivo

Il corsivo si ottiene mettendo un simbolo _ (underscore) prima e dopo il testo, senza spazi, oppure un singolo asterisco *.

_testo testo testo_
oppure
*testo testo testo*

La prima forma è utile quando si vuole utilizzare assieme al grassetto, sia totalmente che parzialmente in varie combinazioni:

testo **testo** testo_
_testo **testo testo**_
**_testo testo testo_**

diventa:

testo testo testo_
testo testo testo
testo testo testo

Blocco di citazione

Per un blocco di testo citato, si mette il simbolo > più uno spazio all’inizio di ogni capoverso, se sono presenti più capoversi si mette il simbolo > nel rigo vuoto di separazione.

> Primo capoverso, ancora il primo capoverso, ancora il primo
capoverso, ecc.
> /* questo è lo spazio fra due capoversi. */
> Secondo capoverso

Lista numerata

Iniziare ogni voce della lista con un numero + punto + spazio + testo. Per annidare una lista iniziare il rigo con 4 spazi + quanto sopra. Per ulteriori annidamenti inserire ulteriori 4 spazi.

Primo capoverso, ancora il primo capoverso, ancora il primo capoverso, ecc.

Secondo capoverso
Ecc.

Notare che non ha importanza quale numero si inserisce (vedere ad esempio l’elenco “Pippo, Pluto, Paperino”). Si può usare anche sempre lo stesso, provvederà il visualizzatore a numerare la sequenza in modo corretto.

Lista non numerata

Per le liste non numerate si usa un trattino - + spazio + testo. Al posto del trattino si può usare un asterisco o un segno +. Per annidare aggiungere 4 spazi.

Codice

Un rigo di codice o un comando inserito in un testo si mette tra due simboli ` senza spazi all’inizio e alla fine della parola o della riga. Queste virgolette, che poi sarebbero l’accento grave (backtick in inglese), nella tastiera Mac italiana si ottengono con Alt + backslash (a sinistra del tasto 1), nella mia tastiera (Mac inglese internazionale) si trova a sinistra della Z. Gli utenti Windows con tastiera italiana devono usare il tastierino numerico digitando ALT + 96. Gli utenti Linux ALT + ’ (apostrofo normale).

Linea di separazione

Per tracciare una linea di separazione scrivere tre asterischi seguiti da una riga vuota.

***

Non dimenticare di lasciare una riga vuota dopo i tre asterischi.

Link

In questo modo per linkare un sito:

[Alt](link)

Alt

Immagini

Per inserire delle immagini: punto esclamativo +\ [testo descrittivo dell’immagine] + (link all’immagine). È consigliabile sistemare le immagini in una cartella dedicata, che sia collocata nello stesso spazio dove è salvato il file che si sta digitando. Volendo inserire una didascalia all’immagine si scrive immediatamente al di sotto in corsivo, avendo cura di non lasciare righe vuote.