Sintassi estesa di Markdown: guida completa con esempi

La sintassi di base di Markdown copre la maggior parte delle esigenze di scrittura quotidiane, ma a volte serve di più. La sintassi estesa aggiunge funzionalità potenti come tabelle, note a piè di pagina, liste di attività e altro — trasformando Markdown da un semplice strumento di formattazione in un ambiente di scrittura completo.

Non tutti i processori Markdown supportano tutti gli elementi della sintassi estesa. Prima di usarli, verifica se il tuo strumento o piattaforma supporta la funzionalità specifica di cui hai bisogno. La buona notizia: la maggior parte delle piattaforme moderne — GitHub, GitLab, VS Code e i generatori di siti statici più diffusi — supportano la maggioranza di queste estensioni.

Se non hai ancora dimestichezza con le basi, inizia con la nostra guida alla sintassi di base di Markdown.

Tabelle

Le tabelle ti permettono di organizzare i dati in righe e colonne direttamente in Markdown. Usa le barre verticali (|) per separare le colonne e i trattini (-) per creare la riga di intestazione.

| Feature       | Basic Syntax | Extended Syntax |
| ------------- | ------------ | --------------- |
| Tables        | No           | Yes             |
| Footnotes     | No           | Yes             |
| Task Lists    | No           | Yes             |

Questo viene reso così:

Feature	Basic Syntax	Extended Syntax
Tables	No	Yes
Footnotes	No	Yes
Task Lists	No	Yes

Allineamento delle colonne

Controlla l'allineamento del testo aggiungendo due punti alla riga separatrice dell'intestazione:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More         |     More       |          More |

• :--- allinea a sinistra (predefinito)
• :---: centra la colonna
• ---: allinea a destra

Suggerimenti per le tabelle

• Non è necessario allineare perfettamente le barre verticali nel codice sorgente — serve solo per una migliore leggibilità
• Le tabelle supportano la formattazione in linea come grassetto, corsivo, codice e link
• Le tabelle non supportano intestazioni, citazioni, liste o immagini all'interno delle celle
• Per dati complessi, considera l'uso di tabelle HTML

Blocchi di codice delimitati

La sintassi di base supporta blocchi di codice indentati, ma i blocchi di codice delimitati sono molto più pratici. Racchiudi il tuo codice con tripli apici inversi (```) o triple tilde (~~~) e specifica un linguaggio per l'evidenziazione della sintassi.

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
```

Questo viene reso con evidenziazione della sintassi completa:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))

Linguaggi supportati

La maggior parte dei renderer supporta decine di identificatori di linguaggio. Ecco i più comuni:

Language        Identifier
--------------  ----------------
JavaScript      javascript / js
Python          python / py
TypeScript      typescript / ts
HTML            html
CSS             css
JSON            json
Bash            bash / sh
SQL             sql
Markdown        markdown / md

Best practice per i blocchi di codice

• Specifica sempre un linguaggio — abilita l'evidenziazione della sintassi e migliora la leggibilità
• Usa text o plaintext quando nessun linguaggio è applicabile
• I blocchi delimitati sono preferiti rispetto ai blocchi indentati perché supportano l'evidenziazione e non richiedono l'indentazione di ogni riga

Note a piè di pagina

Le note a piè di pagina ti permettono di aggiungere annotazioni e riferimenti senza appesantire il testo principale. Il contenuto della nota appare in fondo alla pagina.

Markdown was created by John Gruber in 2004.[^1] It has since become
the standard for technical writing.[^2]

[^1]: John Gruber's original Markdown project is documented on
    [Daring Fireball](https://daringfireball.net/projects/markdown/).
[^2]: Markdown is used by GitHub, Stack Overflow, Reddit, and
    countless other platforms.

I numeri di riferimento vengono resi come link in apice nel testo, con le note complete elencate in fondo al documento.

Regole di sintassi delle note

• Il riferimento della nota usa [^identifier] — l'identificatore può essere un numero o una parola (senza spazi)
• La definizione della nota inizia con [^identifier]: seguito dal contenuto
• Le note con più paragrafi richiedono indentazione (quattro spazi o un tab) per i paragrafi successivi
• Le definizioni delle note possono essere posizionate ovunque nel documento — vengono sempre rese in fondo

Here's a footnote with multiple paragraphs.[^note]

[^note]: This is the first paragraph of the footnote.

    This is the second paragraph, indented with four spaces.

    You can even include code: `console.log("hello")`

ID delle intestazioni

Gli ID delle intestazioni personalizzati ti permettono di creare link ancora precisi a sezioni specifiche del tuo documento. Aggiungi l'ID tra parentesi graffe dopo il testo dell'intestazione.

### My Custom Section {#custom-section}

Questo genera:

<h3 id="custom-section">My Custom Section</h3>

Collegamento agli ID delle intestazioni

Una volta che un'intestazione ha un ID, puoi collegarti direttamente ad essa:

Jump to [My Custom Section](#custom-section).

Questo è particolarmente utile per creare un sommario manuale all'inizio di documenti lunghi:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)
- [FAQ](#faq)

Nota di compatibilità

Molti processori (incluso GitHub) generano automaticamente ID delle intestazioni dal testo, anche senza la sintassi {#id}. Tuttavia, impostare esplicitamente gli ID offre un controllo completo e garantisce un comportamento coerente tra le piattaforme.

Liste di definizioni

Le liste di definizioni sono perfette per glossari, FAQ e qualsiasi contenuto in cui è necessario associare termini alle loro spiegazioni.

Markdown
: A lightweight markup language for creating formatted text
  using a plain-text editor.

HTML
: The standard markup language for documents designed to be
  displayed in a web browser.

YAML
: A human-readable data serialization language commonly used
  for configuration files.

Questo genera il seguente HTML:

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for creating formatted text
      using a plain-text editor.</dd>
  <dt>HTML</dt>
  <dd>The standard markup language for documents designed to be
      displayed in a web browser.</dd>
</dl>

Definizioni multiple

Un termine può avere più di una definizione:

Markdown
: A lightweight markup language.
: A tool used by developers and writers worldwide.

Nota di compatibilità

Le liste di definizioni non sono supportate da tutti i processori. GitHub Flavored Markdown non le supporta, ma molti generatori di siti statici e strumenti di documentazione sì.

Testo barrato

Il testo barrato visualizza una linea orizzontale attraverso il testo, indicando contenuto eliminato o obsoleto. Racchiudi il testo con doppie tilde (~~).

The project deadline is ~~Friday~~ Monday.
~~Old information~~ has been replaced with updated content.

Questo viene reso così:

The project deadline is Friday Monday.

Output HTML:

<p>The project deadline is <del>Friday</del> Monday.</p>

Il testo barrato è ampiamente supportato — fa parte di GitHub Flavored Markdown (GFM) e funziona sulla maggior parte delle piattaforme moderne.

Liste di attività

Le liste di attività (chiamate anche caselle di controllo o liste di cose da fare) creano checklist interattive. Usa - [ ] per gli elementi non completati e - [x] per quelli completati.

- [x] Research extended syntax features
- [x] Write first draft
- [x] Add code examples for each section
- [ ] Create cover image
- [ ] Proofread and edit
- [ ] Publish the article

Questo viene reso così:

• Research extended syntax features
• Write first draft
• Add code examples for each section
• Create cover image
• Proofread and edit
• Publish the article

Casi d'uso delle liste di attività

Le liste di attività sono particolarmente popolari in:

• Issue e pull request di GitHub — tracciare il progresso degli elementi di lavoro
• Documentazione di progetto — delineare i passaggi di un processo
• Note delle riunioni — registrare le azioni da intraprendere con il loro stato

Su piattaforme come GitHub, queste caselle di controllo sono interattive — puoi cliccarle per attivarle o disattivarle direttamente nella vista resa.

Emoji

Ci sono due modi per aggiungere emoji ai tuoi documenti Markdown.

Copia e incolla

L'approccio più semplice — copia un emoji da qualsiasi fonte e incollalo direttamente nel tuo testo:

That's a great idea! 🎉 Let's ship it! 🚀

Questo funziona ovunque perché gli emoji sono caratteri Unicode standard.

Codici brevi

Alcune piattaforme supportano i codici brevi degli emoji — parole chiave racchiuse tra due punti:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

I codici brevi più comuni includono:

Shortcode              Emoji
---------------------  -----
:smile:                😄
:rocket:               🚀
:thumbsup:             👍
:warning:              ⚠️
:heavy_check_mark:     ✔️
:x:                    ❌
:fire:                 🔥
:star:                 ⭐

Nota di compatibilità

I codici brevi degli emoji variano tra le piattaforme. GitHub, Slack e Discord supportano ciascuno set diversi. Gli emoji copiati e incollati funzionano universalmente e sono la scelta più sicura per documenti multipiattaforma.

Evidenziazione

L'evidenziazione attira l'attenzione su parole o frasi chiave dando loro uno sfondo colorato. Racchiudi il testo con doppi segni di uguale (==).

This is ==critically important== information.

Questo genera:

<p>This is <mark>critically important</mark> information.</p>

Alternativa HTML

Se il tuo processore Markdown non supporta la sintassi ==, usa direttamente il tag HTML <mark>:

This is <mark>critically important</mark> information.

Entrambi gli approcci producono lo stesso risultato — testo evidenziato che si distingue dal contenuto circostante.

Nota di compatibilità

La sintassi ==highlight== non è ampiamente supportata. Funziona in alcuni processori ma non in GitHub Flavored Markdown. Se la compatibilità è importante, usa il tag HTML <mark>.

Pedice e apice

Questi elementi sono essenziali per la notazione scientifica, le espressioni matematiche e le formule chimiche.

Pedice

Usa tilde singole (~) per racchiudere il testo in pedice:

The chemical formula for water is H~2~O.
Carbon dioxide is CO~2~.

Questo viene reso come: H₂O e CO₂.

Equivalente HTML:

<p>The chemical formula for water is H<sub>2</sub>O.</p>

Apice

Usa accenti circonflessi (^) per racchiudere il testo in apice:

The equation is E = mc^2^.
This is the 3^rd^ edition.

Questo viene reso come: E = mc² e 3^a edizione.

Equivalente HTML:

<p>The equation is E = mc<sup>2</sup>.</p>

Alternativa HTML

Se il tuo processore non supporta la sintassi ~ e ^, usa direttamente i tag HTML:

H<sub>2</sub>O is water.
E = mc<sup>2</sup> is Einstein's famous equation.

Questo approccio HTML funziona in praticamente tutti i renderer Markdown.

Link URL automatici

La maggior parte dei processori Markdown converte automaticamente gli URL grezzi in link cliccabili senza alcuna sintassi speciale:

Visit https://example.com for more information.

Questo viene reso come un link cliccabile anche senza la sintassi [text](url).

Disabilitare i link automatici

A volte vuoi mostrare un URL come testo semplice senza renderlo cliccabile. Racchiudilo tra apici inversi per renderlo come codice in linea:

`https://example.com`

Questo mostra l'URL come codice invece che come link cliccabile — utile nella documentazione dove stai spiegando schemi di URL invece di linkare ad essi.

Quando usare link espliciti

Sebbene i link automatici siano comodi, la sintassi dei link espliciti offre più controllo:

<!-- Automatic: shows raw URL -->
https://example.com

<!-- Explicit: shows custom text -->
[Visit our website](https://example.com)

Usa link espliciti quando desideri un testo ancora descrittivo — è meglio per la leggibilità e la SEO.

Riferimento rapido

Ecco tutti gli elementi della sintassi estesa a colpo d'occhio:

Element              Syntax                     Support
-------------------  -------------------------  --------
Table                | Col | Col |              Wide
Fenced Code Block    ``` code ```               Wide
Footnote             [^1] / [^1]: text          Moderate
Heading ID           ### Heading {#id}          Moderate
Definition List      Term / : Definition        Limited
Strikethrough        ~~text~~                   Wide
Task List            - [x] / - [ ]             Wide
Emoji (shortcode)    :emoji_name:               Varies
Highlight            ==text==                   Limited
Subscript            H~2~O                      Limited
Superscript          X^2^                       Limited
Auto URL Link        https://...                Wide

Inizia a usare la sintassi estesa

Ora conosci tutti i principali elementi della sintassi estesa. Ecco come metterli in pratica:

1. Verifica la tua piattaforma: Controlla quali funzionalità supporta il tuo processore Markdown. GitHub, VS Code e la maggior parte dei generatori di siti statici gestiscono bene gli elementi ampiamente supportati.

2. Usa le alternative HTML: Per le funzionalità con supporto limitato (evidenziazione, pedice, apice), le alternative con tag HTML funzionano quasi ovunque.

3. Esercitati con contenuti reali: Prova ad aggiungere una tabella al tuo prossimo README, note a piè di pagina al tuo prossimo post del blog o liste di attività al tuo prossimo piano di progetto.

4. Converti con sicurezza: Quando il tuo documento è pronto per essere condiviso, converti Markdown in PDF per un output pronto per la stampa con supporto per tabelle e formule LaTeX, esporta in HTML per la pubblicazione web, o genera un documento Word per la revisione degli stakeholder — tutti gli elementi della sintassi estesa inclusi.

Tra la sintassi di base e queste funzionalità estese, ora hai il toolkit Markdown completo. Se sei completamente nuovo con Markdown, inizia con Cos'è Markdown per le basi essenziali. Qualunque cosa tu stia scrivendo — documentazione, post del blog, specifiche tecniche o piani di progetto — Markdown ti copre.