---
title: Ottimizzazione SEO
description: Gestisci titoli, descrizioni e meta tag per motori di ricerca e anteprime social. Jamdesk genera automaticamente sitemap e immagini Open Graph.
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Ottimizza la documentazione per i motori di ricerca e le anteprime social impostando titoli, descrizioni e metadati nel frontmatter.

## Cosa fa Jamdesk automaticamente

<Columns cols={3}>
  <Card title="Meta tag" icon="tags">
    Titolo e descrizione del frontmatter diventano meta tag.
  </Card>
  <Card title="Open Graph" icon="share">
    Immagini per la condivisione sui social generate per ogni pagina.
  </Card>
  <Card title="Sitemap e robots.txt" icon="sitemap">
    Sitemap XML e robots.txt generati a ogni build.
  </Card>
  <Card title="JSON-LD" icon="code">
    Dati strutturati Schema.org su ogni pagina per risultati di ricerca avanzati.
  </Card>
  <Card title="IndexNow" icon="bolt">
    Gli URL modificati vengono inviati ai motori di ricerca dopo ogni build.
  </Card>
  <Card title="Endpoint AI" icon="robot" href="/it/ai/overview">
    `llms.txt` e server MCP consentono agli strumenti AI di leggere la documentazione.
  </Card>
</Columns>

## Ottimizzare i contenuti

### Scrivere un frontmatter efficace

```yaml
---
title: User Authentication    # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication  # 120-160 characters
---
```

<Tip>
**Inserisci le parole chiave all'inizio.** «Configurazione dell'autenticazione» è meglio di «Come configurare l'autenticazione».
</Tip>

### Titoli delle pagine

- Mantieni i titoli sotto i 60 caratteri per evitare che vengano troncati nei risultati di ricerca
- Inserisci la parola chiave principale vicino all'inizio
- Assegna a ogni titolo un testo univoco nella documentazione

### Descrizioni

- Punta a 120-160 caratteri
- Riassumi cosa imparerà il lettore
- Includi le parole chiave pertinenti in modo naturale

<Note>
**Descrizione di riserva generata automaticamente.** Se nel frontmatter manca `description`, Jamdesk estrae automaticamente il primo paragrafo discorsivo del contenuto della pagina (fino a 155 caratteri). Ignora titoli, blocchi di codice, immagini e componenti MDX. La descrizione viene usata per `<meta name="description">`, Open Graph e le schede Twitter. Per ottenere risultati ottimali, è comunque consigliabile scrivere una descrizione esplicita.
</Note>

## Controllare l'indicizzazione

### Impostazioni globali del sito

In `docs.json`, configura il comportamento predefinito dei robot:

```json docs.json
{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}
```

### Controllo per singola pagina

Sovrascrivi l'impostazione di indicizzazione per pagine specifiche nel frontmatter:

```yaml
---
title: Internal Notes
noindex: true
---
```

Usa `noindex` per:
- Pagine in bozza o in corso di aggiornamento
- Documentazione interna
- Contenuti obsoleti che vuoi conservare come riferimento

### Indicizzazione per la ricerca e acquisizione AI

I metadati `robots` e `noindex` controllano i **motori di ricerca**: determinano se una pagina appare su Google e in `sitemap.xml`. Non hanno effetto sui file `llms.txt` e `llms-full.txt` letti dagli strumenti AI. Per interromperne la pubblicazione, imposta `seo.ai.llmsTxt` su `false` (vedi [Disattivare llms.txt](https://jamdesk.com/docs/it/ai/llms-txt#disattiva-llmstxt)). I due controlli sono indipendenti: una pagina può essere indicizzata dai motori di ricerca ma esclusa dall'acquisizione AI, o viceversa.

## URL canonici

Se la documentazione è accessibile da più URL, imposta un URL canonico:

```yaml
---
title: Getting Started
canonical: https://docs.example.com/getting-started
---
```

Puoi anche impostare una base canonica globale del sito in `docs.json`. Jamdesk vi aggiunge il
percorso di ogni pagina, così ciascuna pagina riceve il proprio URL canonico corretto:

```json docs.json
{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}
```

## Anteprime social e Open Graph

Jamdesk genera automaticamente per ogni pagina una scheda social brandizzata da 1200×630. Puoi sovrascrivere qualsiasi tag social nel frontmatter. Puoi usare **chiavi piatte di primo livello** oppure un blocco **`seo:` annidato**. Entrambe le modalità funzionano; se la stessa chiave è impostata in entrambi i modi, prevale il valore di primo livello.

<Card title="Anteprima OpenGraph" icon="share-nodes" href="https://jamdesk.com/utilities/opengraph-preview" horizontal>
  Scopri come viene visualizzata la scheda di una pagina su X, Facebook, LinkedIn e altre piattaforme e convalida i relativi tag Open Graph con lo strumento OpenGraph Preview.
</Card>

<CodeGroup>
```yaml Flat (top-level)
---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---
```

```yaml Nested (seo block)
---
title: API Reference
description: REST API endpoints and authentication
seo:
  "og:title": API Reference — Acme
  "og:image": /images/api-social-card.png
  "twitter:card": summary_large_image
  x-custom-tag: any custom meta value
---
```
</CodeGroup>

### Tag supportati

| Gruppo | Tag |
|-------|------|
| Open Graph | `og:title`, `og:description`, `og:image`, `og:image:width`, `og:image:height`, `og:image:alt`, `og:url`, `og:type`, `og:site_name`, `og:locale`, `og:video`, `og:audio` |
| Articolo | `og:type: article` con `article:published_time`, `article:modified_time`, `article:author`, `article:section`, `article:tag` |
| Twitter / X | `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`, `twitter:image:alt`, `twitter:site`, `twitter:creator`, `twitter:player`, tag delle schede app |
| Altro | `keywords`, `author`, `robots`, `googlebot`, `google-site-verification`, `theme-color` e qualsiasi tag personalizzato (inserisci i tag personalizzati in `seo:`) |

<Note>
**Dimensioni personalizzate dell'immagine OG.** `og:image:width` e `og:image:height` si applicano solo quando
[`customImage`](#personalizzare-la-scheda-social) è `"replace"`. Impostali nello stesso punto dell'`og:image` a cui si riferiscono: nel frontmatter della pagina o in `seo.metatags`. La scheda generata ha sempre dimensioni 1200×630.
</Note>

<Note>
**Tag personalizzati.** I tag meta arbitrari (ad es. `x-pinterest`) vengono emessi come `<meta name="...">`.
Inseriscili nel blocco `seo:`. Se sono indicati come chiavi piatte, vengono rilevate solo le chiavi SEO riconosciute.
</Note>

### Tipo di scheda Twitter / X

Il tag `twitter:card` determina il layout usato da X e dalle altre piattaforme quando viene condiviso un link:

| Valore | Aspetto |
|-------|--------------------|
| `summary` | Miniatura quadrata piccola a sinistra, titolo e descrizione accanto. Compatta. |
| `summary_large_image` | Immagine grande a tutta larghezza in alto, titolo e descrizione sotto. La versione più grande e d'impatto. |

Per una scheda brandizzata da 1200×630, usa `summary_large_image` per visualizzare l'immagine a tutta larghezza.

### Immagine predefinita globale del sito

Imposta un'immagine social di riserva per ogni pagina in `docs.json`. Qualsiasi pagina con un proprio `og:image` sovrascrive questa impostazione:

```json docs.json
{
  "seo": {
    "metatags": {
      "og:image": "https://docs.acme.com/images/default-card.png"
    }
  }
}
```

<Tip>
**Controlla l'anteprima prima della pubblicazione.** Dopo una build, incolla l'URL della pagina nello strumento [OpenGraph Preview](https://jamdesk.com/utilities/opengraph-preview) per controllare come viene visualizzata la scheda su ciascuna piattaforma e convalidare i tag Open Graph. Lo strumento controlla anche le dimensioni dell'immagine e spiega come risolvere eventuali problemi.
</Tip>

### Personalizzare la scheda social

La scheda generata mantiene l'aspetto attuale a meno che tu non aggiunga `seo.socialCard` a `docs.json`.
Imposta solo le chiavi che vuoi modificare:

```json docs.json
{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}
```

| Chiave | Predefinito | Effetto |
|-----|---------|--------|
| `theme` | `"light"` | `"dark"` usa testo chiaro su sfondo scuro e l'immagine `logo.dark`. |
| `brandColor` | `false` | `true` applica `colors.primary` alla barra inferiore e al badge della sezione. Se imposti `colors.light`, la scheda scura lo usa. Se non hai `colors`, la scheda usa il colore di accento del tema. `false` mantiene il rosso predefinito. |
| `accentBar` | `true` | `false` rimuove la barra colorata lungo il bordo inferiore della scheda. |
| `siteName` | `true` | `false` nasconde il nome del sito sotto il logo. Usalo se il logo mostra già il nome. |
| `customImage` | `"background"` | `"background"` sovrappone il titolo della pagina all'`og:image`. `"replace"` usa l'`og:image` come scheda completa. |

La scheda può visualizzare solo loghi SVG, PNG e JPG. Durante la build del sito, Jamdesk converte in WebP i file PNG e JPG del logo presenti nel repository; perciò, di solito la scheda mostra invece la favicon e mantiene il nome del sito, anche con `siteName: false`. Usa un logo SVG per visualizzare il logo completo sulla scheda e `logo.dark` su una scheda scura.

Se il colore del brand non risalta abbastanza sulla scheda, il testo del badge usa il colore del testo normale. La barra mantiene il colore del brand, a meno che questo non sia quasi identico allo sfondo della scheda. In tal caso la barra è grigia.

Per impostazione predefinita, Jamdesk sovrappone il titolo della pagina all'`og:image`. Se l'immagine contiene già testo o elementi grafici, imposta `"customImage": "replace"` per mostrarla così com'è.

Quando l'`og:image` è lo sfondo della scheda, scegli il `theme` più adatto: `dark` per un'immagine scura, `light` per una chiara.

In modalità `replace`, Jamdesk non sovrappone alcun titolo all'immagine. Se `seo.metatags` imposta `og:image`, tutte le pagine usano quell'immagine; una pagina che imposta un proprio `og:image` usa invece il proprio. Solo le pagine che non hanno né l'uno né l'altro ricevono una scheda generata. Usa un'immagine PNG o JPG da 1200×630. Alcune piattaforme non visualizzano immagini WebP o SVG.

I siti social memorizzano nella cache le anteprime dei link; quindi, dopo aver modificato queste impostazioni, un link già condiviso può continuare a mostrare la vecchia scheda per un po'. Controlla la nuova scheda con lo strumento
[OpenGraph Preview](https://jamdesk.com/utilities/opengraph-preview).

<Note>
Le versioni meno recenti della CLI di Jamdesk rifiutano `seo.socialCard` in `jamdesk validate` e
`jamdesk dev`. Aggiorna con `npm i -g jamdesk@latest`.
</Note>

## Sitemap e robots.txt

Ogni sito Jamdesk genera automaticamente `sitemap.xml` e `robots.txt` a ogni build.

| File | Scopo |
|------|---------|
| `sitemap.xml` | Elenca tutte le pagine con le date dell'ultima modifica per i motori di ricerca |
| `robots.txt` | Consente l'accesso a tutti i crawler e indica loro la sitemap |

### Dove trovarli

Gli URL dipendono dal fatto che la documentazione si trovi su un dominio principale o in un sottopercorso `/docs`:

<Tabs>
  <Tab title="Dominio principale">
    Se la documentazione si trova alla radice del dominio (ad es. `docs.acme.com` o `acme.jamdesk.app`):

    ```bash
    https://docs.acme.com/sitemap.xml
    https://docs.acme.com/robots.txt
    ```
  </Tab>
  <Tab title="Sottopercorso /docs">
    Se la documentazione si trova in `/docs` sul sito principale, come in questo sito su `jamdesk.com/docs`:

    ```bash
    https://jamdesk.com/docs/sitemap.xml
    https://jamdesk.com/docs/robots.txt
    ```
  </Tab>
</Tabs>

### Cosa contiene la sitemap

- Tutte le pagine pubblicate, tranne quelle con `noindex` o `hidden` nel frontmatter
- Date dell'ultima modifica indicate nel frontmatter, se disponibili
- Frequenza di aggiornamento settimanale

### Escludere pagine dalla sitemap

Aggiungi `noindex` al frontmatter per escludere una pagina sia dalla sitemap sia dai motori di ricerca:

```yaml
---
title: Internal Notes
noindex: true
---
```

Anche le pagine con `hidden: true` vengono escluse automaticamente.

## Dati strutturati JSON-LD

Ogni pagina include automaticamente dati strutturati [schema.org](https://schema.org) in un tag `<script type="application/ld+json">` con due schemi:

- `WebSite`: nome, URL e descrizione del sito (da `docs.json`).
- `BreadcrumbList`: percorso di navigazione dalla Home alla pagina corrente, derivato dalla configurazione `navigation`.

Non è necessaria alcuna configurazione. I motori di ricerca li usano per mostrare risultati avanzati, come i breadcrumb nei risultati di ricerca.

<Tip>
**Verifica il markup.** Incolla l'URL di una pagina nel [test dei risultati avanzati di Google](https://search.google.com/test/rich-results) per verificare che i dati strutturati vengano rilevati.
</Tip>

## IndexNow

Dopo ogni build, Jamdesk invia automaticamente gli URL delle pagine modificate a [IndexNow](https://www.indexnow.org) per accelerarne l'indicizzazione nei motori di ricerca. In questo modo Bing, Yandex e gli altri motori di ricerca partecipanti vengono informati delle modifiche ai contenuti senza dover attendere il successivo ciclo di scansione.

- Si attiva dopo ogni build completata correttamente
- Invia solo le pagine effettivamente modificate
- Non blocca il processo e non ritarda mai la build
- Non richiede configurazione

## Buone pratiche

Segui questa lista di controllo prima della pubblicazione:

<Note>
**Lista di controllo pre-pubblicazione**

- **Titoli univoci.** Ogni pagina ha un titolo descrittivo distinto, inferiore a 60 caratteri.
- **Descrizioni accurate.** Le descrizioni riassumono la pagina in 120-160 caratteri.
- **Gerarchia logica dei titoli.** I titoli seguono una gerarchia chiara: un H1, poi H2 → H3.
- **Link descrittivi.** I link interni usano un testo significativo, mai «clicca qui».
- **Testo alternativo delle immagini.** Ogni immagine ha un testo alternativo per l'accessibilità e la ricerca per immagini.
- **Immagine social.** Imposta un `og:image` personalizzato nelle pagine principali oppure usa la scheda generata automaticamente. Verificala con lo strumento [OpenGraph Preview](https://jamdesk.com/utilities/opengraph-preview).
</Note>

## Articoli correlati

<Columns cols={2}>
  <Card title="Riferimento frontmatter" icon="file-lines" href="/it/content/frontmatter">
    Tutte le opzioni frontmatter disponibili
  </Card>
  <Card title="Riferimento docs.json" icon="gear" href="/it/config/docs-json-reference">
    Opzioni di configurazione globali del sito
  </Card>
  <Card title="Strumento OpenGraph Preview" icon="share-nodes" href="https://jamdesk.com/utilities/opengraph-preview">
    Visualizza in anteprima e convalida le schede social su tutte le piattaforme
  </Card>
</Columns>