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à. L'invenzione di Markdown ha offerto 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à offre solo un'idea di Markdown. Per una revisione più approfondita, fare riferimento agli articoli "Descrizione della sintassi Markdown" e "Specifica di GitHub-Flavored Markdown" nell'unità Riepilogo alla fine 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. Anche questo è 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 ogni livello di intestazione da 1 a 6.
###### 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:
- First
- Secondo
- Terza
- First
- Nested
- Second
- Third
Ecco il markdown per un elenco non ordinato:
- Primi
- Annidato
- Secondo
- Terza
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
First Secondo 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
Usare il codice
Markdown fornisce il comportamento predefinito per l'utilizzo di blocchi di codice inline delimitati dal carattere di apice inverso (`). Quando si decora il testo con questo carattere, ne viene eseguito il rendering 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 alla fine 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 problema o di una richiesta pull.
- [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. |