GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) è la versione avanzata di Markdown di GitHub con funzionalità aggiuntive progettate specificamente per lo sviluppo software e la collaborazione. Questa guida copre tutte le estensioni di sintassi speciali disponibili su GitHub.

Cos'è GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown estende la sintassi base di Markdown con funzionalità che lo rendono più utile per:

• Documentazione (README, wiki)
• Tracciamento delle issue
• Pull request
• Revisione del codice
• Gestione dei progetti

Funzioni Principali del GFM

1. Blocchi di Codice Delimitati

GFM supporta blocchi di codice delimitati con evidenziazione della sintassi specifica per linguaggio:

```javascript
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0);
}

const result = calculateSum([1, 2, 3, 4, 5]);
console.log(result); // Output: 15

2. Evidenziazione della Sintassi

GitHub supporta l'evidenziazione della sintassi per centinaia di linguaggi. Alcuni comuni includono:

# Script Bash
echo "Hello GitHub!"

# Script Python
def greet(name):
    return f"Hello, {name}!"

// Codice Java
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello GitHub!");
    }
}

3. Elenchi di Attività

Crea elenchi di attività interattivi con caselle di controllo:

- [x] Completare l'autenticazione utente
- [x] Implementare gli endpoint API
- [ ] Scrivere test unitari
  - [ ] Test backend
  - [ ] Test frontend
- [ ] Distribuire in produzione

• [x] Completare l'autenticazione utente
• [x] Implementare gli endpoint API
• [ ] Scrivere test unitari
  • [ ] Test backend
  • [ ] Test frontend
• [ ] Distribuire in produzione

4. Tabelle

GFM fornisce una sintassi semplice per creare tabelle:

| Funzionalità       | Supportata | Descrizione                     |
|--------------------|------------|---------------------------------|
| Fenced Code        | ✅         | Evidenziazione specifica        |
| Task Lists         | ✅         | Caselle di controllo interattive|
| Tables             | ✅         | Visualizzazione dati strutturati|
| Mentions           | ✅         | Notifiche utente e team         |
| Emoji              | ✅         | Espressioni visive              |

Funzionalità	Supportata	Descrizione
Fenced Code	✅	Evidenziazione specifica
Task Lists	✅	Caselle di controllo interattive
Tables	✅	Visualizzazione dati strutturati
Mentions	✅	Notifiche utente e team
Emoji	✅	Espressioni visive

5. Menzioni

Menziona utenti o team per notificarli:

@username - Menziona un utente specifico
@team-name - Menziona un team

6. Emoji

Aggiungi emoji usando shortcode:

:smile: - 😊
:thumbsup: - 👍
:heart: - ❤️
:rocket: - 🚀
:warning: - ⚠️

😄 - 😊 👍 - 👍 ❤️ - ❤️ 🚀 - 🚀 ⚠️ - ⚠️

7. Collegamento Automatico

GFM collega automaticamente determinati tipi di contenuto:

Numeri di Issue e Pull Request

#123 - Collega all'issue 123
PR #456 - Collega alla pull request 456

Hash SHA

a1b2c3d - Collega al commit con questo SHA

Menzioni Utente in Issue/PR

@username - Collega automaticamente al profilo utente

URL

https://github.com - Diventa automaticamente un collegamento

8. Barrato

GFM supporta il testo barrato:

~~Questo testo è barrato~~

Questo testo è barrato

9. Riferimenti Collegamento Automatico

GFM crea automaticamente collegamenti per:

• URL HTTP/HTTPS
• Indirizzi email
• Numeri di issue/PR GitHub
• SHA di commit

https://github.com/markdownlang/markdownlang.com
user@example.com
#123
PR #456
a1b2c3d4e5f6

10. Evidenziazione Righe nei Blocchi di Codice

Evidenzia righe specifiche nei blocchi di codice:

```javascript{2,4}
function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);
```

function calculateSum(numbers) {
  return numbers.reduce((sum, num) => sum + num, 0); // Highlighted
}

const result = calculateSum([1, 2, 3, 4, 5]); // Highlighted
console.log(result);

11. Evidenziazione Sintassi Diff

Evidenzia le modifiche nel codice con la sintassi diff:

```diff
- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };
```

- const oldFunction = () => {
-   return "old value";
- };
+
+ const newFunction = () => {
+   return "new value";
+ };

12. Markup Specifico di GitHub

Avvisi

Usa una sintassi speciale per gli avvisi nella documentazione GitHub:

> [!NOTE]
> Questo è un avviso di nota.

> [!TIP]
> Questo è un avviso di suggerimento.

> [!IMPORTANT]
> Questo è un avviso importante.

> [!WARNING]
> Questo è un avviso di avvertimento.

> [!CAUTION]
> Questo è un avviso di cautela.

NOTE

Questo è un avviso di nota.

TIP

Questo è un avviso di suggerimento.

IMPORTANT

Questo è un avviso importante.

WARNING

Questo è un avviso di avvertimento.

CAUTION

Questo è un avviso di cautela.

Collegamenti Relativi

Usa collegamenti relativi per navigare tra i file nello stesso repository:

[README](/README.md)
[Linee Guida per il Contributo](/CONTRIBUTING.md)
[Documentazione API](/docs/api.md)

Collegamenti Immagine con Testo al Passaggio del Mouse

![GitHub Logo](/images/github-logo.png "GitHub Logo - Testo al Passaggio del Mouse")

Uso Avanzato del GFM

1. Elenchi Annidati con Elenchi di Attività

Combina elenchi annidati con elenchi di attività:

## Roadmap del Progetto

### Fase 1: Pianificazione
- [x] Definire l'ambito del progetto
- [x] Identificare i requisiti
  - [x] Requisiti funzionali
  - [x] Requisiti non funzionali
- [x] Creare la timeline

### Fase 2: Sviluppo
- [x] Configurare la struttura del progetto
- [ ] Implementare le funzionalità principali
  - [x] Autenticazione
  - [ ] Dashboard
  - [ ] Integrazione API

2. Tabelle con Emoji e Collegamenti

Migliora le tabelle con emoji e collegamenti:

| Componente     | Stato              | Manutentore  |
|----------------|--------------------|--------------|
| Autenticazione | ✅ Stabile         | @johndoe     |
| Database       | ⚠️ Da Aggiornare   | @janedoe     |
| API            | 🚧 In Corso        | @bobsmith    |
| UI             | ✅ Stabile         | @alicesmith  |

Componente	Stato	Manutentore
Autenticazione	✅ Stabile	@johndoe
Database	⚠️ Da Aggiornare	@janedoe
API	🚧 In Corso	@bobsmith
UI	✅ Stabile	@alicesmith

3. Blocchi di Codice negli Elenchi

Includi blocchi di codice negli elenchi:

1. Installa le dipendenze:

   ```bash
   npm install

2. Esegui il server di sviluppo:

   npm run dev

3. Build per produzione:

   npm run build

### 4. Blocchi di Citazione con Codice

Combina citazioni con blocchi di codice:

```markdown
> **Suggerimento Pro:** Usa il seguente comando per controllare rapidamente lo stato di Git:
>
> ```bash
> git status
> ```

Suggerimento Pro: Usa il seguente comando per controllare rapidamente lo stato di Git:

git status

GFM in Diversi Contesti GitHub

File README

I file README supportano tutte le funzionalità GFM e vengono renderizzati automaticamente sulle pagine del repository.

Issue e Pull Request

• Usa elenchi di attività per tracciare i progressi
• Menziona i membri del team per la collaborazione
• Includi snippet di codice con evidenziazione della sintassi
• Riferisciti a issue/PR correlate usando la sintassi #123

Commenti

• Usa emoji per reazioni rapide
• Riferisciti a righe nel codice con commenti alle righe
• Usa blocchi di citazione per rispondere a punti specifici

Wiki

• Organizza il contenuto con pagine annidate
• Usa tabelle per dati strutturati
• Includi esempi di codice con evidenziazione della sintassi

Migliori Pratiche

1. Stile del Codice

<!-- ✅ Buono -->
```javascript
// Usa nomi di funzione descrittivi
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function f(i){return i.reduce((a,b)=>a+b.p,0)}```

2. Design delle Tabelle

<!-- ✅ Buono -->
| Funzionalità | Descrizione | Stato |
|--------------|-------------|-------|
| Funzionalità 1 | Breve descrizione | ✅ |
| Funzionalità 2 | Altra descrizione | 🚧 |

<!-- ❌ Da Evitare -->
| Funzionalità | Descrizione | Stato | | | |
|--------------|-------------|-------|---|---|---|
| Funzionalità 1 | Questa descrizione è troppo lunga e rende la tabella difficile da leggere sui dispositivi mobili | ✅ | | | |

3. Uso degli Elenchi di Attività

<!-- ✅ Buono -->
## Sprint Backlog
- [x] Completare la pagina del profilo utente
- [ ] Implementare la funzionalità di ricerca
  - [x] API Backend
  - [ ] Componente Frontend
- [ ] Scrivere documentazione

<!-- ❌ Da Evitare -->
- [ ] Attività 1
- [ ] Attività 2
- [ ] Attività 3
- [ ] Attività 4
- [ ] Attività 5
(Troppe attività senza organizzazione)

GFM vs Markdown Standard

Funzionalità	Markdown Standard	GitHub Flavored Markdown
Blocchi di Codice Delimitati	❌	✅
Evidenziazione della Sintassi	❌	✅
Elenchi di Attività	❌	✅
Tabelle	❌	✅
Barrato	❌	✅
Emoji	❌	✅
Menzioni	❌	✅
Collegamento Automatico	Limitato	Estensivo

Strumenti per Lavorare con GFM

Editor Locali

• Visual Studio Code - Anteprima GFM ed estensioni
• Typora - Rendering GFM in tempo reale
• Mark Text - Supporto GFM

Strumenti Online

• GitHub Gist - Crea e condividi snippet GFM
• Dillinger - Editor GFM online
• StackEdit - Supporto GFM con sincronizzazione cloud

Strumenti da Riga di Comando

• glow - Renderer GFM per terminale
• pandoc - Converti GFM in altri formati
• marked - Parser GFM per Node.js

Problemi Comuni e Soluzioni

1. Blocco di Codice Non Evidenziato

Problema: Il blocco di codice non mostra l'evidenziazione della sintassi

Soluzione: Assicurati di specificare il linguaggio corretto:

<!-- ✅ Corretto -->
```javascript
console.log("Hello");

console.log("Hello"); // Usando jsx invece di javascript per codice non-JSX

### 2. Caselle di Controllo degli Elenchi di Attività Non Funzionanti

**Problema:** Le caselle di controllo degli elenchi di attività non sono interattive

**Soluzione:** Assicurati di usare la sintassi corretta (spazio tra `-` e `[ ]`):

```markdown
<!-- ✅ Corretto -->
- [ ] Attività

<!-- ❌ Errato -->
-[ ] Attività (nessuno spazio)
-[x] Attività (nessuno spazio)

3. Tabella Non Renderizzata Correttamente

Problema: Le colonne della tabella sono disallineate

Soluzione: Assicurati che le barre verticali siano allineate correttamente:

<!-- ✅ Corretto -->
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

<!-- ❌ Errato -->
|Column 1|Column 2|
|--|--|
|Data 1|Data 2|

Prossimi Passaggi

• Impara la sintassi base di Markdown
• Visualizza il cheat sheet della sintassi
• Esercitati con GitHub Gist
• Leggi la documentazione ufficiale GitHub GFM

---

GitHub Flavored Markdown è uno strumento potente per la comunicazione e la collaborazione nello sviluppo software. Padroneggiando queste funzionalità, puoi creare documentazione più efficace, tracciare meglio le issue e collaborare in modo più efficiente con il tuo team.