Configurare Social Metadata & SEO

Docusaurus gestisce i metadati social a due livelli: default globali in docusaurus.config.ts, e override per pagina nel frontmatter di ogni file. Questa guida illustra entrambi, usando la configurazione di Zenzic come modello di riferimento.

Default globali (`docusaurus.config.ts`)

L'immagine OG globale e le impostazioni Twitter Card risiedono in themeConfig:

docusaurus.config.ts
const config: Config = {
  title: 'Zenzic',
  tagline: 'Documentation security layer',
  url: 'https://zenzic.dev',
  baseUrl: '/',

  themeConfig: {
    // Immagine OG + Twitter Card predefinita per ogni pagina
    image: 'assets/social/social-card.png',   // relativo a static/

    metadata: [
      { name: 'twitter:card',    content: 'summary_large_image' },
      { name: 'twitter:site',    content: '@PythonWoods' },
      { name: 'twitter:creator', content: '@PythonWoods' },
      { name: 'twitter:image:alt',
        content: 'Zenzic — The Safe Harbor for Markdown Documentation' },
      { name: 'theme-color',     content: '#4f46e5' },
      { property: 'og:image',        content: 'https://zenzic.dev/assets/social/social-card.png' },
      { property: 'og:image:width',  content: '1200' },
      { property: 'og:image:height', content: '630' },
      { property: 'og:type',         content: 'website' },
      { property: 'og:url',          content: 'https://zenzic.dev/' },
    ],
  },
};

Il path image è relativo a static/. Docusaurus antepone baseUrl automaticamente. L'og:image esplicita in metadata usa l'URL assoluto completo affinché i crawler esterni possano risolverlo senza seguire redirect.

Specifiche immagine OG

Le immagini per le social card devono essere 1200 × 630 px (rapporto 1.91:1). File più piccoli vengono ritagliati o rifiutati da LinkedIn e Twitter. Usa PNG per screenshot e grafica esportata da SVG; evita JPEG per card con testo.

Override per pagina (Frontmatter)

Qualsiasi pagina può sovrascrivere i default globali aggiungendo campi al proprio frontmatter:

docs/explanation/architecture.mdx
---
title: "Architecture — How Zenzic Works"
description: "Deep dive into the Two-Pass Pipeline, VSM, and Blood Sentinel."
image: /assets/social/social-card.png
keywords: [zenzic, architecture, vsm, pipeline, documentation linter]
---

Chiave frontmatter	Si mappa su	Note
`title`	`<title>`, `og:title`, `twitter:title`	Docusaurus aggiunge il titolo del sito automaticamente
`description`	`<meta name="description">`, `og:description`	Mantieni sotto i 155 caratteri per gli snippet di ricerca
`image`	`og:image`, `twitter:image`	Assoluto o root-relativo; sovrascrive il default globale
`keywords`	`<meta name="keywords">`	Lista separata da virgole

I post del blog usano le stesse chiavi nel blocco frontmatter, più authors e tags che Docusaurus renderizza nell'intestazione del post.

Posiziona tutti gli asset delle social card in static/assets/social/:

static/assets/social/
├── social-card.png          ← immagine OG predefinita (1200 × 630, dark)
├── social-card-light.png    ← variante light mode
├── social-card.svg          ← SVG sorgente (non servire direttamente come OG)
└── social-card-light.svg

SVG come immagine OG

La maggior parte dei crawler social (LinkedIn, Slack, iMessage) non renderizza SVG. Esporta sempre un PNG dall'SVG sorgente. I file SVG sono conservati in static/assets/social/ esclusivamente come sorgenti di design.

Per card specifiche per pagina (ad esempio un post del blog che annuncia una release), aggiungi il PNG in static/assets/social/ e referenzialo nel frontmatter del post:

---
title: "Zenzic v0.7.0 — Quartz Maturity"
image: /assets/social/social-card.png
---

Verifica

Dopo aver aggiornato i metadati, verifica l'output in locale:

npm run build && npm run serve

Poi ispeziona il <head> di qualsiasi pagina con il DevTools del browser (tab Elementi, cerca og:image). Per la verifica in produzione, usa il Twitter Card Validator o l'Open Graph Debugger — entrambi accettano un URL e mostrano i tag risolti.

Docusaurus renderizza i tag OG lato server

I meta tag OG appaiono nell'HTML prodotto dalla build, non nel dev server di Docusaurus (npm run start). Valida sempre sull'output di npm run build o sul sito in produzione, non sull'URL di sviluppo locale.

Zenzic non valida URL social esterni, ma rileva gli asset statici inutilizzati. Se aggiungi un PNG per una social card personalizzata e non lo referenzi mai nel frontmatter o in themeConfig, Zenzic lo segnala come asset inutilizzato alla prossima esecuzione di zenzic check all.

Escludi i file sorgente intenzionalmente non referenziati in zenzic.toml:

# zenzic.toml
excluded_assets = [
    "**/_category_.json",
    "assets/social/*.svg",   # SVG sorgenti — non serviti come immagini OG
]

Default globali (docusaurus.config.ts)​

Override per pagina (Frontmatter)​

Archiviazione delle immagini social​

Verifica​

Zenzic Sentinel e asset social​

Default globali (`docusaurus.config.ts`)

Override per pagina (Frontmatter)

Archiviazione delle immagini social

Verifica

Zenzic Sentinel e asset social