# Guida Completa Markdown per Docusaurus

> **Guida di riferimento completa per la sintassi Markdown in Docusaurus**
> 
> Autore: Giuseppe  
> Ultimo aggiornamento: Settembre 2025  
> Repository: [docs.git](https://gitlab.dffm.it/giuseppe/docs.git)

---

## Indice

- [1. Frontmatter (Metadati del documento)](#1-frontmatter-metadati-del-documento)
- [2. Intestazioni](#2-intestazioni)
- [3. Formattazione del Testo](#3-formattazione-del-testo)
- [4. Liste](#4-liste)
- [5. Link e Riferimenti](#5-link-e-riferimenti)
- [6. Immagini](#6-immagini)
- [7. Blocchi di Codice](#7-blocchi-di-codice)
- [8. Tabelle](#8-tabelle)
- [9. Citazioni](#9-citazioni)
- [10. Separatori Orizzontali](#10-separatori-orizzontali)
- [11. Componenti Docusaurus Specifici](#11-componenti-docusaurus-specifici)
- [12. MDX - Componenti React](#12-mdx---componenti-react)

---

## 1. Frontmatter (Metadati del documento)

Il frontmatter è il blocco YAML all'inizio del file che definisce metadati e configurazioni del documento.

```yaml
---
id: my-doc-id
title: Titolo del Documento
sidebar_label: Label Sidebar
sidebar_position: 2
description: Descrizione del documento per SEO
keywords: [docusaurus, markdown, guida]
tags: [tutorial, documentation]
slug: /custom-url
draft: false
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
custom_edit_url: https://github.com/repo/edit/main/docs/doc.md
---
```

**Campi principali:**
- `id`: Identificatore univoco del documento
- `title`: Titolo visualizzato nella pagina
- `sidebar_label`: Etichetta nella sidebar (se diversa dal titolo)
- `sidebar_position`: Posizione numerica nella sidebar
- `description`: Meta descrizione per SEO
- `keywords`: Array di parole chiave per la ricerca
- `tags`: Tag per categorizzare il documento
- `slug`: URL personalizzato per la pagina
- `draft`: Se `true`, nasconde il documento in produzione

---

## 2. Intestazioni

Le intestazioni creano la struttura gerarchica del documento e generano automaticamente l'indice.

```markdown
# H1 - Titolo principale
## H2 - Sottotitolo
### H3 - Sezione
#### H4 - Sottosezione
##### H5 - Paragrafo
###### H6 - Sottoparagrafo
```

**Best practices:**
- Usa solo un H1 per documento
- Mantieni la gerarchia logica (H1 → H2 → H3)
- Evita di saltare livelli di intestazione

---

## 3. Formattazione del Testo

```markdown
**Testo in grassetto**
*Testo in corsivo*
***Testo in grassetto e corsivo***
~~Testo barrato~~
`Codice inline`
```

Per sottolineato ed evidenziato:
```html
<u>Testo sottolineato</u>
<mark>Testo evidenziato</mark>
```

**Risultato:**
- **Testo in grassetto**
- *Testo in corsivo*
- ***Testo in grassetto e corsivo***
- ~~Testo barrato~~
- `Codice inline`

---

## 4. Liste

### Liste non ordinate
```markdown
- Elemento 1
- Elemento 2
  - Sottoelemento 2.1
  - Sottoelemento 2.2
- Elemento 3

* Alternativa con asterisco
+ Alternativa con più
```

### Liste ordinate
```markdown
1. Primo elemento
2. Secondo elemento
   1. Sottoelemento ordinato
   2. Altro sottoelemento
3. Terzo elemento
```

### Liste di attività (Task Lists)
```markdown
- [x] Attività completata
- [ ] Attività da fare
- [x] Altra attività completata
```

---

## 5. Link e Riferimenti

```markdown
[Link esterno](https://example.com)
[Link con titolo](https://example.com "Titolo del link")
[Link a documento interno](./altro-documento.md)
[Link a sezione](#sezione-specifica)
[Link di riferimento][1]

[1]: https://example.com

<!-- Link automatici -->
https://example.com
<email@example.com>
```

**Tipi di link supportati:**
- **Esterni**: Collegamenti a siti web esterni
- **Interni**: Collegamenti ad altri documenti del progetto
- **Ancore**: Collegamenti a sezioni specifiche della stessa pagina
- **Automatici**: URL e email riconosciuti automaticamente

---

## 6. Immagini

### Sintassi Markdown base
```markdown
![Alt text](./images/immagine.png)
![Alt text](./images/immagine.png "Titolo immagine")
```

### Immagini con HTML (per controllo avanzato)
```html
<img src="./images/immagine.png" alt="Alt text" width="500" height="300" />
```

### Immagini centrate
```html
<div style={{textAlign: 'center'}}>
  <img src="./images/immagine.png" alt="Alt text" />
</div>
```

**Formati supportati:**
- PNG, JPG, JPEG, GIF, SVG
- WebP (per performance ottimizzate)
- Immagini locali e remote

---

## 7. Blocchi di Codice

### Codice inline
```markdown
Usa `console.log()` per stampare in console.
```

### Blocchi di codice con evidenziazione sintassi

JavaScript:
```javascript
function saluta(nome) {
  console.log(`Ciao, ${nome}!`);
}
saluta("Mondo");
```

Python:
```python
def saluta(nome):
    print(f"Ciao, {nome}!")

saluta("Mondo")
```

Bash:
```bash
npm install docusaurus
npm start
```

### Blocchi di codice con titolo
````markdown
```js title="src/components/HelloWorld.js"
import React from 'react';

export default function HelloWorld() {
  return <h1>Hello World!</h1>;
}
```
````

### Evidenziazione di righe specifiche
````markdown
```js {1,4-6,11}
import React from 'react';

function MyComponent() {
  const [count, setCount] = useState(0);
  const increment = () => setCount(count + 1);
  const decrement = () => setCount(count - 1);
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
    </div>
  );
}
```
````

### Code Block con numerazione righe
````markdown
```js showLineNumbers
function calculateSum(a, b) {
  return a + b;
}

const result = calculateSum(5, 3);
console.log(result);
```
````

**Linguaggi supportati:**
JavaScript, TypeScript, Python, Java, C#, PHP, Go, Rust, HTML, CSS, SQL, JSON, YAML, e molti altri.

---

## 8. Tabelle

```markdown
| Colonna 1 | Colonna 2 | Colonna 3 |
|-----------|-----------|-----------|
| Riga 1    | Dato 1    | Dato 2    |
| Riga 2    | Dato 3    | Dato 4    |
```

### Tabelle con allineamento
```markdown
| Sinistra | Centro | Destra |
|:---------|:------:|-------:|
| Testo    | Testo  | Testo  |
| Esempio  | Test   | 123    |
```

**Allineamento:**
- `:---` = Allineato a sinistra
- `:---:` = Centrato
- `---:` = Allineato a destra

---

## 9. Citazioni

```markdown
> Questa è una citazione semplice.

> Questa è una citazione
> su più righe.
```

### Citazioni complesse
```markdown
> ## Citazione con intestazione
> 
> Puoi includere **formattazione** nelle citazioni.
> 
> - Liste
> - Anche nelle citazioni
```

---

## 10. Separatori Orizzontali

```markdown
---
```

Oppure:
```markdown
***
___
```

Tutti e tre i metodi producono lo stesso risultato: una linea orizzontale di separazione.

---

## 11. Componenti Docusaurus Specifici

### Admonitions (Avvisi)

Gli admonitions sono blocchi colorati per evidenziare informazioni importanti.

```markdown
:::note
Questa è una nota informativa.
:::

:::tip
Questo è un suggerimento utile.
:::

:::info
Questa è un'informazione importante.
:::

:::warning
Questo è un avvertimento.
:::

:::danger
Questo è un avviso di pericolo.
:::
```

### Admonitions con titolo personalizzato
```markdown
:::tip Titolo personalizzato
Puoi personalizzare il titolo degli admonition.
:::

:::note[Nota con titolo personalizzato]
Sintassi alternativa per il titolo.
:::
```

### Admonitions collassabili
```markdown
:::details Clicca per espandere
Contenuto nascosto che si può espandere.
:::
```

---

## 12. MDX - Componenti React

MDX permette di utilizzare componenti React direttamente nel Markdown.

### Componenti inline
```markdown
export const Highlight = ({children, color}) => (
  <span style={{backgroundColor: color, borderRadius: '2px', color: '#fff', padding: '0.2rem'}}>
    {children}
  </span>
);

Ecco un testo <Highlight color="#25c2a0">evidenziato in verde</Highlight>.
```

### Live Code Editor
````markdown
```jsx live
function Button() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}
```
````

### Importare componenti esterni
```markdown
import MyComponent from '@site/src/components/MyComponent';

<MyComponent name="Giuseppe" />
```

---

## 13. Funzionalità Avanzate

### Footnotes (Note a piè di pagina)
```markdown
Questo è un testo con una nota[^1].

[^1]: Questa è la nota a piè di pagina.
```

### Emoji support
```markdown
:smile: :heart: :thumbsup: :rocket: :warning:

Oppure direttamente: 😄 ❤️ 👍 🚀 ⚠️
```

### Keyboard keys
```html
Premi <kbd>Ctrl</kbd>+<kbd>C</kbd> per copiare.
```

---

## 14. Diagrammi

### Mermaid (se abilitato)
````markdown
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```
````

### Diagramma di flusso
````markdown
```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
    C --> D
```
````

---

## 15. Math (se KaTeX abilitato)

### Equazioni inline
```markdown
La formula di Einstein è $E = mc^2$.
```

### Equazioni in blocco
```markdown
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

---

## 16. Best Practices

### Struttura dei file
```
docs/
├── intro.md
├── tutorial/
│   ├── _category_.json
│   ├── basics/
│   │   ├── create-document.md
│   │   └── markdown-features.md
│   └── advanced/
│       └── deploy.md
└── api/
    └── users.md
```

### File _category_.json
```json
{
  "label": "Tutorial",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "Tutorial per imparare Docusaurus."
  }
}
```

### Performance e SEO
- **Immagini ottimizzate**: Usa formati moderni (WebP) e dimensioni appropriate
- **Meta description**: Includi sempre una descrizione nel frontmatter
- **Keywords**: Utilizza parole chiave rilevanti per la ricerca
- **Struttura gerarchica**: Mantieni una gerarchia logica delle intestazioni
- **Heading sequenziali**: Usa heading in ordine (H1 → H2 → H3)

### Accessibilità
- **Alt text**: Fornisci sempre testo alternativo per le immagini
- **Struttura heading**: Usa intestazioni per strutturare il contenuto
- **Link descrittivi**: Assicurati che i link abbiano testo descrittivo
- **Contrasto colori**: Usa colori con contrasto adeguato negli elementi personalizzati

### Organizzazione contenuti
- **Naming consistency**: Usa convenzioni coerenti per nomi file e ID
- **Logical grouping**: Organizza documenti in cartelle logiche
- **Cross-references**: Crea collegamenti tra documenti correlati
- **Regular updates**: Mantieni aggiornata la documentazione

---

## Risoluzione Problemi Comuni

### Errori MDX
1. **Tag auto-chiudenti**: Usa `<img />` invece di `<img>`
2. **Attributi JSX**: Usa `className` invece di `class`
3. **Sintassi mista**: Non mischiare Markdown e JSX nello stesso blocco
4. **Import mancanti**: Importa tutti i componenti che usi

### Debug dei link
- Usa percorsi relativi per documenti interni
- Controlla che i file esistano effettivamente
- Verifica l'estensione dei file (.md vs .mdx)

### Problemi di build
- Controlla la sintassi YAML nel frontmatter
- Verifica che non ci siano caratteri speciali nei nomi file
- Assicurati che tutti gli import siano corretti

---

## Risorse Aggiuntive

- 📚 [Documentazione Ufficiale Docusaurus](https://docusaurus.io/)
- 🎯 [Markdown Guide](https://www.markdownguide.org/)
- 🔧 [MDX Documentation](https://mdxjs.com/)
- 🎨 [Infima CSS Framework](https://infima.dev/) (utilizzato da Docusaurus)

---

> **Nota**: Questa guida è stata creata per il progetto [docs.git](https://gitlab.dffm.it/giuseppe/docs.git) e può essere liberamente utilizzata e modificata secondo le esigenze del progetto.