站点设置

站点设置保存适用于整个站点的值。模板可以用它们来获取站点身份、分页、日期处理、社交资料和搜索元数据。

配置设置

在 EmDash 管理后台打开 Settings，然后选择包含你所需值的页面：

• General 包含站点标题、标语、logo、favicon、公开 URL、每页文章数、日期格式和时区。请使用 Change domain 更改公开 URL，详见迁移到新域名。
• Social 包含受支持社交服务的资料用户名。
• SEO 包含标题分隔符、默认社交图片、验证值和 robots.txt 内容。每一项的作用请参阅内置 SEO 功能。

设置在配置之前是可选的。模板应为其所需的每个值提供合适的回退。

在布局中读取设置

当布局需要多个值时，请使用 getSiteSettings()。它会将已配置的键作为部分对象返回，并在返回之前解析媒体引用。

以下基础布局使用站点身份设置，并让 EmDashHead 应用已配置的 favicon、默认社交图片和全站验证元数据：

---
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 元数据。

读取单个设置

当组件只需要一个值，且其父组件尚未获取设置对象时，请使用 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 的格式仍由主题负责。

使用媒体设置

logo、favicon 和默认社交图片以媒体引用的形式保存。读取时，EmDash 会添加当前 URL，以及已知的内容类型、宽度和高度。如果被引用的媒体项已被删除，这些解析出的值可能不存在，因此在渲染图片之前请检查 url。

可在管理后台中使用 Remove 按钮删除其中一张图片。API 和 MCP 客户端可以通过将字段设置为 null 来删除 logo、favicon 或 seo.defaultOgImage；省略某个字段则保持其当前值不变。seo 和 social 内的字段同样如此：只发送你想更改的字段，发送空字符串则清除文本字段。

站点设置只保存一个 logo 和一个 favicon。深色图片变体属于 EmDash 图片字段，编辑可以在其中选择对应的另一张图片，Image 组件可以在两者之间切换。该模式请参阅深色模式。

运行时 API 参考记录了设置键和查询返回类型。如需以编程方式修改，请使用 Bearer 令牌进行身份验证，并在每个会改变状态的请求中添加 X-EmDash-Request: 1。请求体和响应请参阅设置端点。