Git & GitHub Real World Vademecum
Parte VI: Documentazione
Il codice è per i computer. Il README.md è per noi umani - recruiter che sfogliano il tuo GitHub, colleghi che devono capire il progetto, te stesso tra 6 mesi quando non ricordi più perché hai scritto quel codice in quel modo.
Un progetto senza README è come un prodotto Amazon senza descrizione e senza foto: nessuno lo userà e in pochi lo capiranno. Il README è la prima cosa che la gente vede quando apre il tuo repository, è letteralmente la faccia del tuo progetto.
18. README.md e Sintassi Markdown
Markdown è un linguaggio super semplice per formattare testo. Lo usi su GitHub, Discord, Reddit, Notion e tantissimi altri posti. Ecco la guida completa:
Titoli e Sottotitoli:
| Sintassi | Risultato |
|---|---|
# Titolo Principale | Titolo H1 (Gigante) |
## Sottotitolo | Titolo H2 (Grande) |
### Sezione | Titolo H3 (Medio) |
#### Sotto-sezione | Titolo H4 (Piccolo) |
Formattazione Testo:
| Sintassi | Risultato |
|---|---|
**Grassetto** | Grassetto |
*Corsivo* o _Corsivo_ | Corsivo |
***Grassetto e Corsivo*** | Grassetto e Corsivo |
~~Barrato~~ | |
`Codice in linea` | Codice in linea |
Link e Immagini:
| Sintassi | Risultato |
|---|---|
[Testo del link](https://google.com) | Link cliccabile |
 | Immagine visualizzata |
 | Immagine da file locale |
Liste:
Lista non ordinata (con pallini):
- Primo elemento
- Secondo elemento
- Sotto-elemento (indentato con 2 spazi)
- Altro sotto-elemento
- Terzo elemento
Lista ordinata (con numeri):
1. Primo passo
2. Secondo passo
3. Terzo passo
Liste con checkbox (task list):
- [x] Task completato
- [ ] Task da fare
- [ ] Altro task da fare
Blocchi di Codice:
Per codice inline usa i backtick singoli: const x = 5
Per blocchi di codice multilinea usa tre backtick:
```javascript
function saluta(nome) {
console.log(`Ciao ${nome}!`);
}
```
Specifica il linguaggio dopo i tre backtick iniziali per avere syntax highlighting colorato (javascript, html, css, bash, ecc.)
Citazioni:
> Questa è una citazione.
> Può occupare più righe.
> **Nota importante:** Le citazioni sono ottime per evidenziare note o avvertimenti.
Linea Orizzontale (Separatore):
---
Oppure:
***
Tabelle:
Le tabelle in Markdown hanno una struttura semplice. La prima riga contiene le intestazioni, la seconda riga definisce le colonne (con ---), e le righe successive contengono i dati.
Struttura base:
| Colonna 1 | Colonna 2 | Colonna 3 |
| --- | --- | --- |
| Dato A | Dato B | Dato C |
| Dato D | Dato E | Dato F |
Come si vede renderizzata:
| Colonna 1 | Colonna 2 | Colonna 3 |
|---|---|---|
| Dato A | Dato B | Dato C |
| Dato D | Dato E | Dato F |
Allineamento del testo:
Puoi controllare l'allineamento del testo in ogni colonna usando i due punti : nella riga dei separatori:
:---→ Allineamento a sinistra (default):---:→ Allineamento al centro---:→ Allineamento a destra
Esempio con allineamenti diversi:
| Sinistra | Centro | Destra |
| :--- | :---: | ---: |
| Testo | Testo | Testo |
| A | B | C |
Come si vede renderizzata:
| Sinistra | Centro | Destra |
|---|---|---|
| Testo | Testo | Testo |
| A | B | C |
Ricorda: L'allineamento è utile per tabelle con numeri (meglio a destra) o titoli (meglio al centro).