Che cos'è Markdown?
Markdown è un linguaggio di markup che offre un approccio lean alla modifica dei contenuti schermando i creatori di contenuti dal sovraccarico di HTML. HTML è ottimo per eseguire il rendering del contenuto esattamente come è stato concepito, ma richiede molto spazio e può essere complicato da usare, anche in minima quantità. Markdown offre un importante compromesso tra la potenza del linguaggio HTML per la descrizione del contenuto e la semplicità del testo normale per la modifica.
In questa unità verranno descritte la struttura e la sintassi di Markdown. Verranno anche illustrate le funzionalità di GitHub-Flavored Markdown (GFM), estensioni della sintassi che consentono di integrare le funzionalità di GitHub nel contenuto.
Nota
Questa unità è pensata per offrirti un assaggio di cosa sia Markdown. Per una revisione più approfondita, fare riferimento agli articoli Descrizione della sintassi Markdown e Specifica di GitHub-Flavored Markdown nell'unità Riepilogo di questo modulo.
Sottolineare il testo
La parte più importante di qualsiasi comunicazione su GitHub è in genere il testo stesso, ma come si mostra che alcune parti del testo sono più importanti di altre?
Per usare il corsivo nel testo, è sufficiente racchiudere il testo di destinazione tra asterischi singoli (*) o caratteri di sottolineatura singoli (_). Assicurarsi di chiudere un'enfasi con lo stesso carattere di apertura. Prestare attenzione a come si combina l'uso di asterischi e caratteri di sottolineatura. Ecco vari esempi:
This is *italic* text.
This is also _italic_ text.
Questo è un testo in corsivo. Questo è anche un testo in corsivo.
Creare il testo in grassetto usando due asterischi (**) o due caratteri di sottolineatura (__).
This is **bold** text.
This is also __bold__ text.
Questo è un testo in grassetto. Anche questo è un testo in grassetto.
È anche possibile combinare enfasi diverse.
_This is **italic and bold** text_ using a single underscore for italic and double asterisks for bold.
__This is bold and *italic* text__ using double underscores for bold and single asterisks for italic.
Questo è un testo in corsivo e grassetto che usa un solo carattere di sottolineatura per il corsivo e asterischi doppi per il grassetto. Questo è un testo in grassetto e corsivo che usa caratteri di sottolineatura doppi per il grassetto e asterischi singoli per il corsivo.
Per usare un asterisco letterale, anteporre un carattere di escape, ovvero una barra rovesciata in GFM (\). In questo esempio i caratteri di sottolineatura e gli asterischi vengono visualizzati nell'output.
\_This is all \*\*plain\*\* text\_.
_Questo è un testo **normale**_.
Dichiarare intestazioni
Il codice HTML fornisce intestazioni per il contenuto, ad esempio il tag <h1>. In Markdown si usa invece il simbolo #. È sufficiente usare un simbolo # per ciascun livello di intestazione, da uno a sei.
###### This is H6 text
Questo è un testo in H6
Creare collegamenti a immagini e siti
I collegamenti di immagini e siti usano una sintassi molto simile.
[Link to Microsoft Training](/training)
Creare elenchi
È possibile definire elenchi ordinati o non ordinati. È anche possibile definire elementi annidati tramite il rientro.
- Gli elenchi ordinati iniziano con numeri.
- Gli elenchi non ordinati possono usare asterischi o trattini (
-).
Ecco il markdown per un elenco ordinato:
1. First
1. Second
1. Third
Risultato:
- Primo
- Second
- Terzo
Ecco il markdown per un elenco non ordinato:
- First
- Nested
- Second
- Third
- Primo
- Modello
- Secondo
- Terzo
Creare tabelle
Le tabelle possono essere costruite usando una combinazione di barre verticali (|) per le interruzioni di colonna e di trattini (-) per designare la riga precedente come intestazione.
First|Second
-|-
1|2
3|4
Primo Second 1 2 3 4
Citare un testo
È possibile creare citazioni usando il carattere maggiore di (>).
> This is quoted text.
Questo è un testo citato.
Riempire gli spazi vuoti con HTML inline
Se si incontra uno scenario HTML non supportato da Markdown, è possibile usare tale HTML inline.
Here is a<br />line break
Ecco una
interruzione di riga
Lavorare con il codice
Markdown fornisce un comportamento predefinito per l'utilizzo di blocchi di codice inline delimitati dal carattere backtick (`). Quando si decora il testo con questo carattere, viene visualizzato come codice.
This is `code`.
Questo è
code.
Se un segmento di codice si estende su più righe, è possibile usare tre caratteri di apice inverso (```) all'inizio e alla fine per creare un blocco di codice delimitato.
```markdown
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
GFM estende questo supporto con l'evidenziazione della sintassi per i linguaggi più diffusi. È sufficiente specificare il linguaggio nella prima sequenza di apici.
```javascript
var first = 1;
var second = 2;
var sum = first + second;
```
var first = 1; var second = 2; var sum = first + second;
Creare collegamenti incrociati per problemi e richieste pull
GFM supporta diversi formati di codice breve che semplificano la creazione di collegamenti a problemi e richieste pull. Il modo più semplice consiste nell'usare il formato #ID, ad esempio #3602. GitHub modifica automaticamente i collegamenti più lunghi in base a questo formato se li si incolla. Esistono anche altre convenzioni che è possibile seguire, ad esempio se si usano altri strumenti o si vogliono specificare altri progetti/rami.
| Tipo di riferimento | Riferimento non elaborato | Collegamento breve |
|---|---|---|
| URL per il problema o la richiesta pull | https://github.com/desktop/desktop/pull/3602 |
#3602 |
# e numero di problema o richiesta pull |
#3602 | #3602 |
GH- e numero di problema o richiesta pull |
GH-3602 | GH-3602 |
Username/Repository# e numero di problema o richiesta pull |
desktop/desktop#3602 | desktop/desktop#3602 |
Per altre informazioni, vedere l'articolo Riferimenti e URL collegati automaticamente nell'unità Riepilogo di questo modulo.
Collegare commit specifici
È possibile collegarsi a un commit incollando il relativo ID o semplicemente usando il relativo algoritmo SHA (Secure Hash Algorithm).
| Tipo di riferimento | Riferimento non elaborato | Collegamento breve |
|---|---|---|
| URL del commit | https://github.com/desktop/desktop/commit/ | |
| 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c | |
| SHA | 8304e9c271a5e5ab4fda797304cd7bcca7158c87 | 8304e9c |
| User@SHA | desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop@8304e9c |
| Username/Repository@SHA | desktop/desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87 | desktop/desktop@8304e9c |
Fare riferimento a utenti e team
Digitando un simbolo @ seguito da un nome utente GitHub, la persona riceve una notifica sul commento. Si tratta di un elemento "@menzione", perché si sta menzionando la singola persona. È anche possibile inserire @mention per i team di un'organizzazione.
@githubteacher
Tenere traccia degli elenchi di attività
È possibile creare elenchi di attività all'interno di problemi o richieste pull usando la sintassi seguente. Questi elenchi possono essere utili per tenere traccia dell'avanzamento se vengono usati nel corpo di un issue o di una pull request.
- [x] First task
- [x] Second task
- [ ] Third task
Comandi slash
I comandi slash consentono di risparmiare tempo riducendo la digitazione necessaria per creare markdown complessi.
È possibile usare i comandi slash in qualsiasi campo di descrizione o commento in problemi, richieste pull o discussioni in cui sono supportati.
| Comando | Descrizione |
|---|---|
/code |
Inserisce un blocco di codice Markdown. Selezionare la lingua. |
/details |
Inserisce un'area di dettaglio comprimibile. Si sceglie il titolo e il contenuto. |
/saved-replies |
Inserisce una risposta salvata. Si sceglie tra le risposte salvate per l'account utente. Se si aggiunge %cursor% alla risposta salvata, il comando slash posiziona il cursore in tale punto. |
/table |
Inserisce una tabella Markdown. Si sceglie il numero di colonne e righe. |
/tasklist |
Inserisce un elenco di attività. Questo comando slash funziona solo nella descrizione di un problema. |
/template |
Mostra tutti i modelli nel repository. Si sceglie il modello da inserire. Questo comando slash funziona per i modelli di problema e un modello di richiesta pull. |