Impostazioni del sito

Le impostazioni del sito contengono valori che si applicano all’intero sito. I template possono usarle per l’identità del sito, la paginazione, la gestione delle date, i profili social e i metadati di ricerca.

Configurare le impostazioni

Apri Settings nell’amministrazione di EmDash, poi scegli la pagina con i valori che ti servono:

• General contiene il titolo del sito, il sottotitolo, il logo, il favicon, l’URL pubblico, i post per pagina, il formato della data e il fuso orario. Cambia l’URL pubblico con Change domain; consulta Passare a un nuovo dominio.
• Social contiene gli handle di profilo per i servizi social supportati.
• SEO contiene il separatore del titolo, l’immagine social predefinita, i valori di verifica e il contenuto di robots.txt. Consulta Funzionalità SEO integrate per sapere a cosa serve ciascuno.

Le impostazioni sono facoltative finché non vengono configurate. Un template dovrebbe prevedere un fallback adeguato per ogni valore di cui ha bisogno.

Leggere le impostazioni in un layout

Usa getSiteSettings() quando un layout ha bisogno di più valori. Restituisce le chiavi configurate come oggetto parziale e risolve i riferimenti ai media prima di restituirli.

Il layout di base seguente usa le impostazioni di identità del sito e lascia che EmDashHead applichi il favicon configurato, l’immagine social predefinita e i metadati di verifica validi per tutto il sito:

---
import { getSiteSettings } from "emdash";
import { createPublicPageContext } from "emdash/page";
import { EmDashHead } from "emdash/ui";

interface Props {
  title?: string;
  description?: string;
}

const { title, description } = Astro.props;
const settings = await getSiteSettings();
const siteTitle = settings.title ?? "My site";
const fullTitle = title ? `${title} — ${siteTitle}` : siteTitle;
const pageDescription = description ?? settings.tagline;

const page = createPublicPageContext({
  Astro,
  kind: "custom",
  pageType: "website",
  title: fullTitle,
  pageTitle: title ?? siteTitle,
  description: pageDescription,
  siteName: siteTitle,
});
---

<!doctype html>
<html lang={Astro.currentLocale ?? "en"}>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>{fullTitle}</title>
    <EmDashHead page={page} />
  </head>
  <body>
    <header>
      <a href="/" aria-label={siteTitle}>
        {settings.logo?.url ? (
          <img
            src={settings.logo.url}
            alt={settings.logo.alt ?? siteTitle}
            width={settings.logo.width}
            height={settings.logo.height}
          />
        ) : (
          siteTitle
        )}
      </a>
      {settings.tagline && <p>{settings.tagline}</p>}
    </header>

    <main>
      <slot />
    </main>
  </body>
</html>

Anche EmDashHead chiama getSiteSettings(). La cache delle richieste fa sì che quella chiamata riutilizzi il risultato del layout invece di eseguire un’altra query sulle impostazioni.

In una pagina di contenuto renderizzata sul server, passa il riferimento al contenuto a createPublicPageContext() e recupera la voce con getEmDashEntry(). EmDashHead applica quindi i valori del pannello SEO della voce sopra i valori predefiniti del sito. Consulta Renderizzare i metadati SEO in una pagina di contenuto per il pattern completo di una pagina di contenuto.

Leggere un’impostazione

Usa getSiteSetting() quando un componente ha bisogno di un solo valore e il suo genitore non ha ancora recuperato l’oggetto delle impostazioni.

Il componente seguente formatta un timestamp nel fuso orario configurato:

---
import { getSiteSetting } from "emdash";

interface Props {
  date: Date;
}

const { date } = Astro.props;
const timezone = await getSiteSetting("timezone") ?? "UTC";
const formatted = new Intl.DateTimeFormat(Astro.currentLocale, {
  dateStyle: "long",
  timeZone: timezone,
}).format(date);
---

<time datetime={date.toISOString()}>{formatted}</time>

L’impostazione dateFormat è una stringa di pattern come MMMM d, yyyy. Intl.DateTimeFormat non interpreta quella sintassi; usa una libreria di formattazione che supporti le stringhe di pattern quando il template deve applicarla esattamente.

Renderizzare i profili social

Le impostazioni social memorizzano handle o nomi utente anziché link completi. Il template decide quali profili mostrare e trasforma ogni valore configurato nell’URL del servizio.

Il componente seguente renderizza i profili X e GitHub configurati:

---
import { getSiteSetting } from "emdash";

const social = await getSiteSetting("social");
const xHandle = social?.twitter?.replace(/^@/, "");
---

{(xHandle || social?.github) && (
  <nav aria-label="Social profiles">
    <ul>
      {xHandle && (
        <li>
          <a href={`https://x.com/${xHandle}`} rel="me noopener" target="_blank">
            X
          </a>
        </li>
      )}
      {social?.github && (
        <li>
          <a
            href={`https://github.com/${social.github}`}
            rel="me noopener"
            target="_blank"
          >
            GitHub
          </a>
        </li>
      )}
    </ul>
  </nav>
)}

Applica lo stesso pattern ai valori configurati per Facebook, Instagram, LinkedIn e YouTube. Questi campi memorizzano il valore di pagina, profilo, canale o handle inserito nell’amministrazione; il tema resta responsabile del formato dell’URL pubblico.

Usare le impostazioni media

Il logo, il favicon e l’immagine social predefinita sono memorizzati come riferimenti ai media. In lettura, EmDash aggiunge l’URL corrente e, se noti, il tipo di contenuto, la larghezza e l’altezza. Se l’elemento media referenziato è stato eliminato, questi valori risolti possono mancare, quindi controlla url prima di renderizzare un’immagine.

Rimuovi una di queste immagini nell’amministrazione con il relativo pulsante Remove. I client API e MCP possono rimuovere logo, favicon o seo.defaultOgImage impostando quel campo su null; omettere un campo lascia invariato il suo valore attuale. Lo stesso vale per i campi all’interno di seo e social: invia solo i campi che vuoi modificare e invia una stringa vuota per cancellare un campo di testo.

Le impostazioni del sito contengono un logo e un favicon. Una variante scura dell’immagine appartiene a un campo immagine di EmDash, dove l’editor può scegliere la controparte e il componente Image può passare dall’una all’altra. Consulta Modalità Scura per questo pattern.

Il riferimento dell’API di runtime documenta le chiavi delle impostazioni e i tipi restituiti dalle query. Per le modifiche programmatiche, autenticati con un token Bearer e aggiungi X-EmDash-Request: 1 a ogni richiesta che modifica lo stato. Consulta gli endpoint delle impostazioni per i corpi delle richieste e le risposte.