サイト設定

サイト設定には、サイト全体に適用される値が保存されます。テンプレートでは、サイトの識別情報、ページネーション、日付の扱い、ソーシャルプロフィール、検索用メタデータにこれらを利用できます。

設定を構成する

EmDash 管理画面で Settings を開き、必要な値のページを選びます。

• General には、サイトタイトル、タグライン、ロゴ、favicon、公開 URL、1 ページあたりの投稿数、日付形式、タイムゾーンがあります。公開 URL は Change domain で変更します。詳しくは新しいドメインへ移行するを参照してください。
• Social には、対応するソーシャルサービスのプロフィールハンドルがあります。
• SEO には、タイトル区切り文字、デフォルトのソーシャル画像、検証値、robots.txt の内容があります。それぞれの役割については 組み込みの SEO 機能 を参照してください。

設定は、構成されるまでは任意です。テンプレートは、必要とする値のそれぞれに適切なフォールバックを用意してください。

レイアウトで設定を読む

レイアウトで複数の値が必要な場合は getSiteSettings() を使います。構成済みのキーを部分オブジェクトとして返し、メディア参照を解決してから返します。

次の基本レイアウトはサイトの識別情報の設定を使用し、構成済みの favicon、デフォルトのソーシャル画像、サイト全体の検証メタデータを EmDashHead に適用させます。

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

EmDashHead も getSiteSettings() を呼び出します。リクエストキャッシュにより、この呼び出しは別の設定クエリを実行せず、レイアウトの結果を再利用します。

サーバーレンダリングされるコンテンツページでは、コンテンツ参照を createPublicPageContext() に渡し、getEmDashEntry() でエントリーを取得します。すると EmDashHead が、サイトのデフォルトの上にエントリーの SEO パネルの値を適用します。コンテンツページの完全なパターンは、コンテンツページに SEO メタデータをレンダリングするを参照してください。

1 つの設定を読む

コンポーネントで 1 つの値だけが必要で、親がまだ設定オブジェクトを取得していない場合は getSiteSetting() を使います。

次のコンポーネントは、構成済みのタイムゾーンでタイムスタンプをフォーマットします。

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

dateFormat 設定は、MMMM d, yyyy のようなパターン文字列です。Intl.DateTimeFormat はこの構文を解釈しません。テンプレートでそのまま正確に適用する必要がある場合は、パターン文字列に対応したフォーマットライブラリを使用してください。

ソーシャルプロフィールをレンダリングする

ソーシャル設定には、完全なリンクではなく、ハンドルやユーザー名が保存されます。どのプロフィールを表示するかはテンプレートが決め、構成済みの各値をそのサービスの URL に変換します。

次のコンポーネントは、構成済みの X と GitHub のプロフィールをレンダリングします。

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

構成済みの Facebook、Instagram、LinkedIn、YouTube の値にも同じパターンを適用します。これらのフィールドには、管理画面で入力したページ、プロフィール、チャンネル、ハンドルの値が保存されます。公開 URL の形式はテーマが引き続き担当します。

メディア設定を使う

ロゴ、favicon、デフォルトのソーシャル画像は、メディア参照として保存されます。読み取り時に、EmDash は現在の URL と、判明している場合はコンテンツタイプ、幅、高さを追加します。参照先のメディアアイテムが削除されている場合、これらの解決済みの値が存在しないことがあるため、画像をレンダリングする前に url を確認してください。

これらの画像のいずれかを管理画面で削除するには、Remove ボタンを使います。API クライアントと MCP クライアントは、そのフィールドを null に設定することで logo、favicon、seo.defaultOgImage を削除できます。フィールドを省略すると、現在の値は変更されません。seo と social 内のフィールドも同様です。変更したいフィールドだけを送信し、テキストフィールドをクリアするには空文字列を送信します。

サイト設定には、ロゴと favicon が 1 つずつあります。ダーク画像のバリアントは EmDash の画像フィールドに属し、そこでエディターが対になる画像を選べて、Image コンポーネントが両者を切り替えられます。このパターンについてはダークモードを参照してください。

ランタイム API リファレンスでは、設定キーとクエリの戻り値の型を説明しています。プログラムから変更する場合は、Bearer トークンで認証し、状態を変更するすべてのリクエストに X-EmDash-Request: 1 を追加します。リクエストボディとレスポンスについては、設定エンドポイントを参照してください。