Ottimizzazione SEO

Imposta titoli, descrizioni e metadati nel frontmatter per controllare come la tua documentazione appare nei motori di ricerca e nelle anteprime social.

Cosa fa Jamdesk automaticamente

Ottimizzare i contenuti

Scrivere un frontmatter efficace

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

Titoli delle pagine

• Mantieni il titolo sotto i 60 caratteri, contando anche il nome del sito aggiunto dal formato del titolo. I titoli più lunghi vengono troncati nei risultati di ricerca
• Includi la parola chiave principale vicino all'inizio
• Rendi unico ogni titolo nella tua documentazione

Per impostazione predefinita, il titolo nella scheda del browser e nei risultati di ricerca è Titolo della pagina — Nome del sito. Cambialo con seo.titleTemplate in docs.json. Inserisci %s dove va il titolo della pagina:

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

Una pagina intitolata Getting started mostra quindi Getting started | Acme. Usa "%s" da solo per omettere il nome del sito. Un template senza %s fa fallire la build. jamdesk validate mostra l'errore. Le anteprime dei link (og:title e twitter:title) mostrano ancora solo il titolo della pagina.

Alcune pagine non usano il template. Una pagina senza title mostra il tuo name seguito da "Documentation", ad esempio Acme Documentation, oppure solo il tuo name se termina già con "Docs" o "Documentation". Una pagina il cui titolo coincide con il tuo name mostra solo quel titolo.

jamdesk validate e jamdesk dev accettano seo.titleTemplate dalla versione 1.1.220 della CLI. Aggiorna con npm i -g jamdesk@latest.

Descrizioni

• Punta a 120-160 caratteri
• Riassumi ciò che il lettore imparerà
• Includi parole chiave pertinenti in modo naturale

Controllare l'indicizzazione

Impostazioni globali del sito

Imposta il comportamento predefinito dei robot in docs.json:

{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}

Controllo per singola pagina

Sovrascrivi l'indicizzazione per pagine specifiche nel frontmatter:

---
title: Internal Notes
noindex: true
---

Usa noindex per:

• Pagine in bozza o in lavorazione
• Documentazione interna
• Contenuti obsoleti che conservi come riferimento

Indicizzazione per la ricerca e acquisizione AI

I metadati robots e noindex controllano i motori di ricerca: se una pagina compare su Google e nel tuo sitemap.xml. Non hanno effetto sui file llms.txt e llms-full.txt letti dagli strumenti AI. Imposta seo.ai.llmsTxt su false per smettere di pubblicarli (vedi Disattivare llms.txt). I due controlli sono indipendenti: una pagina può essere indicizzata dai motori di ricerca ma esclusa dall'ingestione AI, o viceversa.

URL canonici

Imposta un canonical se la tua documentazione è raggiungibile da più URL:

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

Puoi anche impostare una base canonical per l'intero sito in docs.json. Jamdesk aggiunge a essa il percorso di ogni pagina:

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

Anteprime social e Open Graph

Jamdesk genera una card social 1200×630 con il tuo brand per ogni pagina. Sovrascrivi qualsiasi tag social nel frontmatter con chiavi piatte di primo livello o con un blocco annidato seo:. Il valore piatto di primo livello prevale quando la stessa chiave è impostata in entrambi i modi.

---
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
---

Tag supportati

Tipo di scheda Twitter / X

Il tag twitter:card controlla quale layout usano X (e altre piattaforme) quando il tuo link viene condiviso:

Usa summary_large_image per una card 1200×630 con il tuo brand. Mostra l'immagine a tutta larghezza.

Immagine predefinita globale del sito

Imposta un'immagine social di riserva per ogni pagina in docs.json. Ogni pagina che imposta il proprio og:image la sovrascrive:

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

Personalizzare la scheda social

La card generata mantiene l'aspetto attuale finché non aggiungi seo.socialCard a docs.json. Imposta solo le chiavi che vuoi cambiare:

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

La card può disegnare solo logo SVG, PNG e JPG. Jamdesk converte i file logo PNG e JPG del tuo repository in WebP al momento della build. Di solito la card mostra invece la tua favicon e mantiene il nome del sito, anche con siteName: false. Usa un logo SVG per mostrare il logo completo sulla card. Usa un logo.dark SVG per una card scura.

La card non può disegnare testo dentro un logo SVG: quel testo risulta vuoto. Converti il testo in contorni (path) nello strumento di design ed esporta di nuovo l'SVG. In Figma, seleziona il testo e usa Flatten. In Illustrator, usa Type > Create Outlines. La build mostra un suggerimento quando trova testo nel logo SVG della card. I logo impostati con un URL completo (https://...) non vengono controllati.

Il testo del badge torna al colore di testo normale quando il tuo colore brand non si distingue dallo sfondo della card. La barra mantiene il tuo colore brand a meno che quel colore non coincida quasi con lo sfondo: in quel caso la barra è grigia.

Per impostazione predefinita, Jamdesk disegna il titolo della pagina sopra il tuo og:image. Imposta "customImage": "replace" per mostrare un'immagine che ha già il proprio testo o design così com'è.

Scegli il theme che corrisponde a un og:image usato come sfondo della card: dark per un'immagine scura, light per una chiara.

In modalità replace, Jamdesk non disegna alcun titolo sull'immagine. Un og:image in seo.metatags si applica a ogni pagina. Una pagina che imposta il proprio og:image usa quello. Solo le pagine senza nessuno dei due ricevono una card generata. Usa un PNG o JPG 1200×630. Alcune piattaforme non mostrano immagini WebP o SVG.

I siti social mettono in cache le anteprime dei link. Un link già condiviso può mantenere la vecchia card per un po' dopo che cambi queste impostazioni. Controlla la nuova card con lo strumento Anteprima OpenGraph.

Sitemap e robots.txt

Jamdesk genera sitemap.xml e robots.txt a ogni build.

Dove trovarli

Gli URL dipendono dal fatto che la documentazione sia su un dominio radice o sotto un sottopercorso /docs:

https://docs.acme.com/sitemap.xml
https://docs.acme.com/robots.txt

Cosa contiene la sitemap

• Tutte le pagine pubblicate (esclusi i casi con frontmatter noindex o hidden)
• Date di ultima modifica dal frontmatter quando disponibili
• Frequenza di modifica settimanale

Escludere pagine dalla sitemap

Aggiungi noindex al frontmatter per tenere una pagina fuori dalla sitemap e dai motori di ricerca:

---
title: Internal Notes
noindex: true
---

Anche le pagine con hidden: true sono escluse.

Dati strutturati JSON-LD

Ogni pagina include dati strutturati schema.org come tag <script type="application/ld+json"> con due schemi:

• WebSite: il nome del sito, l'URL e la descrizione (da docs.json).
• BreadcrumbList: il percorso di navigazione da Home alla pagina corrente, derivato dalla configurazione navigation.

Non serve alcuna configurazione. I motori di ricerca li usano per risultati arricchiti come i percorsi di navigazione (breadcrumb) nei risultati di ricerca.

IndexNow

Jamdesk invia gli URL delle pagine modificate a IndexNow dopo ogni build. Bing, Yandex e altri motori di ricerca partecipanti vengono a conoscenza delle modifiche senza attendere il loro prossimo ciclo di scansione.

• Si attiva dopo ogni build riuscita
• Invia solo le pagine modificate
• Non bloccante: non ritarda mai la build
• Nessuna configurazione richiesta

Buone pratiche

Passa in rassegna questa checklist prima di pubblicare:

Articoli correlati