@mannisto/astro-metadata 2.0.0-alpha.1 → 2.0.0-alpha.3

package/README.md

@@ -68,6 +68,7 @@ Set `site` in the Astro config. The canonical URL and the social images must be
 | `robots` | — | `index: false` or `follow: false` for all pages, for example on a staging site. `extra`: other directives, for example `"max-image-preview:large"`. |
 | `favicon` | — | Generates the favicons from one image. See [Favicons](#favicons). |
 | `manifest` | — | Generates the web app manifest, or links your own. See [Web app manifest](#web-app-manifest). |
+| `schema` | — | The structured data of the site: `publisher` is the organization or the person behind the site. `false` turns it off. See [Structured data](#structured-data). |
 | `debug` | `true` | The Metadata app in the dev toolbar (`client`) and the checks in the build log (`build`). Set `false` to turn off both, or `{ client: false }` or `{ build: false }` to turn off one. See [Checks](#checks). |
 | `rules` | — | `ignore`: the ids of the check rules to turn off. `custom`: your own rules. See [Checks](#checks). |
 | `pages` | — | `ignore`: the pages without checks, as path patterns, for example `["/404", "/drafts/**"]`. See [Checks](#checks). |
@@ -83,7 +84,16 @@ metadata({
 })
 ```
 
-`<Metadata>` uses the text of `Astro.currentLocale`, or of its `locale` prop. A locale without a text uses the first text.
+`<Metadata>` uses the text of the locale of the page, or of its `locale` prop. A locale without a text uses the first text.
+
+### Locales
+
+`<Metadata>` reads the locales from your i18n setup. You do not need extra code:
+
+- **[`@mannisto/astro-i18n`](https://github.com/eremannisto/astro-i18n):** the locale, the public URL of the page (`/about` and not `/en/about`) and the hreflang links.
+- **The `i18n` option of Astro:** the locale and the hreflang links.
+
+The hreflang links contain the page in each locale, and `x-default` for the default locale. To give your own links, use the `hreflang` prop. `hreflang={[]}` turns the links off, for example on a 404 page.
 
 ## Metadata component
 
@@ -143,13 +153,16 @@ The page values override the site values. For example, `title="About"` gives:
 | `description` | `description` | The page description. |
 | `image` | `image` | The social image: `url`, `alt`, `width` and `height`. |
 | `type` | `"website"` | The Open Graph type, for example `"article"`. |
-| `author` | — | The Twitter (X) handle of the author, for example `"@acmewriter"`. |
-| `canonical` | The current page | The canonical path or URL. |
+| `author` | — | The author of an article: a name, or `{ name, url, twitter }`. `twitter` gives `twitter:creator`. |
+| `published` | — | The publication date of an article. |
+| `modified` | — | The date of the last change of an article. |
+| `canonical` | The current page | The canonical path or URL. With `@mannisto/astro-i18n`, the default is the public URL of the page. |
 | `index` | `true` | `false` keeps the page out of search results. |
 | `follow` | `true` | `false` tells search engines not to follow the links. |
-| `hreflang` | — | The hreflang links: the page in each locale, and `x-default`: `{ hreflang, href }[]`. |
-| `schema` | — | Structured data. See [Structured data](#structured-data). |
-| `locale` | `Astro.currentLocale` | The locale of the translated site values. |
+| `hreflang` | From the i18n setup | The hreflang links: the page in each locale, and `x-default`: `{ hreflang, href }[]`. See [Locales](#locales). |
+| `breadcrumbs` | — | The path from the home page to the page: `{ name, url }[]`. See [Structured data](#structured-data). |
+| `schema` | — | Structured data items of your own, for example a `Product`. See [Structured data](#structured-data). |
+| `locale` | The locale of the page | The locale of the translated site values. See [Locales](#locales). |
 
 A tag is rendered only when it has a value. For example, the robots tag is necessary only with `index` or `follow` set to `false`.
 
@@ -240,33 +253,53 @@ Your own manifest endpoint can use the generated icons with `Favicon.icons()`.
 
 ## Structured data
 
-The `Schema` builders make the most common JSON-LD types. They fill in the site name and make all URLs absolute.
+`<Metadata>` renders the structured data (JSON-LD) of each page by itself. You only give the values of the page.
 
-```astro
----
-import { Metadata } from "@mannisto/astro-metadata/components"
-import { Schema } from "@mannisto/astro-metadata/runtime"
----
+**The site.** Each page gets the `WebSite` and its publisher: by default, an organization with the site name. Give the logo and the profiles in the config:
+
+```typescript
+metadata({
+  siteName: "Acme Studio",
+  schema: {
+    publisher: {
+      logo: "/logo.png",
+      sameAs: ["https://github.com/acme-studio"],
+    },
+  },
+})
+```
+
+For a personal site, use `publisher: { type: "Person" }`. Set `schema: false` to turn off the site data.
+
+**An article.** Set `type="article"`. The article uses the title, the description and the image of the page:
 
+```astro
 <Metadata
   title="Hello"
   type="article"
-  schema={[
-    Schema.article({
-      title: "Hello",
-      published: new Date("2026-09-01"),
-      author: { name: "Acme Writer", url: "/about" },
-      url: "/blog/hello",
-    }),
-    Schema.breadcrumbs([
-      { name: "Home", url: "/" },
-      { name: "Blog", url: "/blog" },
-    ]),
+  published={post.date}
+  author={{ name: "Acme Writer", url: "/about", twitter: "@acmewriter" }}
+/>
+```
+
+**Breadcrumbs.** Give the path from the home page to the page:
+
+```astro
+<Metadata
+  breadcrumbs={[
+    { name: "Home", url: "/" },
+    { name: "Blog", url: "/blog" },
   ]}
 />
 ```
 
-The `schema` prop also takes your own objects. The types come from [`schema-dts`](https://github.com/google/schema-dts), so your editor completes the schema.org fields.
+**Your own items.** Give other types, for example a `Product` or an `Event`, in `schema`. The types come from [`schema-dts`](https://github.com/google/schema-dts), so your editor completes the schema.org fields:
+
+```astro
+<Metadata schema={{ "@type": "Event", name: "Opening night", startDate: "2026-11-01" }} />
+```
+
+All items go into one graph. The items link to each other with `@id`, and all URLs are absolute.
 
 ## Checks
 
@@ -384,10 +417,7 @@ import { Favicon, Manifest, Schema, Site } from "@mannisto/astro-metadata/runtim
 | `Manifest.url("fi")` | `string` | The URL of the manifest of a locale |
 | `Manifest.build("fi")` | `object` | The manifest of a locale |
 | `Manifest.paths()` | `ManifestPath[]` | The generated manifest files |
-| `Schema.website()` | `WebSite` | The website, with the site name and URL |
-| `Schema.organization()` | `Organization` | The organization: `name`, `url`, `logo`, `sameAs` |
-| `Schema.article()` | `Article` | An article: `title`, `description`, `image`, `published`, `modified`, `author`, `url`, `type` |
-| `Schema.breadcrumbs()` | `BreadcrumbList` | The path to the current page: `{ name, url }[]` |
+| `Schema.graph(page)` | `Graph` | The structured data that `<Metadata>` renders for a page |
 | `Schema.stringify(data)` | `string` | JSON that is safe inside a script tag |
 
 | Component | Props |
@@ -402,18 +432,6 @@ Import the types from `@mannisto/astro-metadata/runtime`, for example `import ty
 - **Trailing slash.** The canonical URL and the `hreflang` links follow the `trailingSlash` setting of Astro. With `"ignore"`, `build.format` decides.
 - **`sharp`.** The favicons use the `sharp` package that Astro installs. If you install Astro without its optional dependencies, install `sharp` yourself.
 - **Files in `public/`.** A file in `public/` with the same path as a generated favicon replaces the generated file. The integration shows a warning.
-- **With @mannisto/astro-i18n.** Give the locale and the hreflang links to `<Metadata>`:
-
-  ```astro
-  ---
-  import { Locale } from "@mannisto/astro-i18n/runtime"
-  import { Metadata } from "@mannisto/astro-metadata/components"
-
-  const { code } = Locale.use(Astro)
-  ---
-
-  <Metadata locale={code} hreflang={Locale.hreflang(Astro.url, Astro.site!)} />
-  ```
 
 ## Migrate from v1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mannisto/astro-metadata",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.3",
   "description": "Metadata for Astro: page tags, social cards, favicons, the web app manifest and structured data.",
   "license": "MIT",
   "type": "module",

package/src/components/Metadata.astro

@@ -2,9 +2,10 @@
 import { localize } from "../lib/config.ts"
 import type { MetadataImage } from "../lib/config.ts"
 import { Favicon } from "../lib/favicon.ts"
+import { i18n } from "../lib/i18n.ts"
 import { Manifest } from "../lib/manifest.ts"
 import { Schema } from "../lib/schema.ts"
-import type { SchemaData } from "../lib/schema.ts"
+import type { SchemaAuthor, SchemaBreadcrumb, SchemaData } from "../lib/schema.ts"
 import { Site } from "../lib/site.ts"
 import { withBase } from "../lib/url.ts"
 
@@ -22,30 +23,51 @@ export type Props = {
   description?: string
   /** The social image. Defaults to the image of the config. */
   image?: MetadataImage
-  /** The Open Graph type, e.g. "article". Defaults to "website". */
+  /**
+   * The Open Graph type. Defaults to "website". "article" also adds the `Article`
+   * structured data, with the title, the description, the image and the dates.
+   */
   type?: string
-  /** The Twitter (X) handle of the author, e.g. "@acmewriter". */
-  author?: string
-  /** The canonical path or URL. Defaults to the current page. */
+  /**
+   * The author of an article: a name, or `{ name, url, twitter }`. The Twitter (X) handle
+   * gives `twitter:creator`.
+   */
+  author?: SchemaAuthor | SchemaAuthor[]
+  /** The publication date of an article. */
+  published?: Date | string
+  /** The date of the last change of an article. */
+  modified?: Date | string
+  /**
+   * The canonical path or URL. Defaults to the current page. With `@mannisto/astro-i18n`,
+   * the default is the public URL of the page.
+   */
   canonical?: string
   /** Set to false to keep the page out of search results. Defaults to true. */
   index?: boolean
   /** Set to false to tell search engines not to follow the links. Defaults to true. */
   follow?: boolean
   /**
-   * The hreflang links: the page in each locale, and `x-default`.
-   * The output of `Locale.hreflang()` of @mannisto/astro-i18n fits here.
+   * The hreflang links: the page in each locale, and `x-default`. With `@mannisto/astro-i18n`
+   * or the `i18n` option of Astro, the links are made for you. `[]` turns them off.
    */
   hreflang?: HreflangLink[]
-  /** JSON-LD structured data, e.g. from the `Schema` builders. */
+  /** The path from the home page to this page. It adds the `BreadcrumbList` structured data. */
+  breadcrumbs?: SchemaBreadcrumb[]
+  /**
+   * Structured data items of your own, e.g. a `Product`. They go into the structured data
+   * of the page, with the site from the config.
+   */
   schema?: SchemaData | SchemaData[]
-  /** The locale of the localized config values. Defaults to `Astro.currentLocale`. */
+  /**
+   * The locale of the page. Defaults to `Astro.currentLocale`, or the locale of
+   * `@mannisto/astro-i18n`.
+   */
   locale?: string
 }
 
 const props = Astro.props
 const config = Site.config
-const locale = props.locale ?? Astro.currentLocale
+const locale = props.locale ?? Astro.currentLocale ?? i18n?.locale(Astro)
 
 const siteName = Site.name(locale)
 const title = Site.title(props.title, locale)
@@ -57,7 +79,10 @@ const image =
 // Social cards show the page title without the template: og:site_name has the site name
 const socialTitle = props.title ?? siteName
 
-const canonical = Site.pageUrl(props.canonical ?? Astro.url.pathname)
+const canonical = Site.pageUrl(props.canonical ?? i18n?.path(Astro) ?? Astro.url.pathname)
+
+// The page in each locale: from the props, or from the i18n setup of the project
+const hreflang = props.hreflang ?? i18n?.alternates(Astro) ?? []
 
 // Search engines index and follow by default, so the tag is only necessary for other values
 const index = props.index ?? config.robots?.index ?? true
@@ -70,9 +95,39 @@ const robots = [!index && "noindex", !follow && "nofollow", config.robots?.extra
 // are specific to Twitter (X) are necessary
 const card = image ? (config.twitter?.card ?? "summary_large_image") : "summary"
 
+// The authors as a list, for the Twitter (X) handles and the article tags
+const authors = props.author === undefined ? [] : [props.author].flat()
+const creator = authors
+  .map((author) => {
+    return typeof author === "string" ? undefined : author.twitter
+  })
+  .find(Boolean)
+const article = props.type === "article"
+
+const schema = Schema.graph({
+  url: canonical,
+  title: props.title ?? siteName,
+  description,
+  image: image ? Site.url(image.url) : undefined,
+  locale,
+  type: props.type,
+  published: props.published,
+  modified: props.modified,
+  author: props.author,
+  breadcrumbs: props.breadcrumbs,
+  items: props.schema === undefined ? undefined : [props.schema].flat(),
+})
+
 const themeColor = config.themeColor
 const manifest = Manifest.url(locale)
 
+/**
+ * Returns a date as an ISO 8601 text. A text stays unchanged.
+ */
+function isoDate(value: Date | string): string {
+  return typeof value === "string" ? value : value.toISOString()
+}
+
 const FEED_TYPES = {
   rss: "application/rss+xml",
   atom: "application/atom+xml",
@@ -111,9 +166,19 @@ const FEED_TYPES = {
     </>
   )
 }
+{
+  article && props.published && (
+    <meta property="article:published_time" content={isoDate(props.published)} />
+  )
+}
+{
+  article && props.modified && (
+    <meta property="article:modified_time" content={isoDate(props.modified)} />
+  )
+}
 <meta name="twitter:card" content={card} />
 {config.twitter?.site && <meta name="twitter:site" content={config.twitter.site} />}
-{props.author && <meta name="twitter:creator" content={props.author} />}
+{creator && <meta name="twitter:creator" content={creator} />}
 
 {
   Favicon.links().map((link) => {
@@ -134,12 +199,8 @@ const FEED_TYPES = {
   })
 }
 {
-  props.hreflang?.map((link) => {
+  hreflang.map((link) => {
     return <link rel="alternate" hreflang={link.hreflang} href={Site.pageUrl(link.href)} />
   })
 }
-{
-  props.schema && (
-    <script is:inline type="application/ld+json" set:html={Schema.stringify(props.schema)} />
-  )
-}
+{schema && <script is:inline type="application/ld+json" set:html={Schema.stringify(schema)} />}

package/src/integration.js

@@ -19,6 +19,7 @@ const SITE_KEYS = [
   "feeds",
   "robots",
   "manifest",
+  "schema",
 ]
 
 // The Lit modules of the dev toolbar app
@@ -54,6 +55,129 @@ function findSharp(root) {
   }
 }
 
+// The module that `<Metadata>` reads the locale values from. Without an i18n setup,
+// it has no adapter.
+const I18N_FILE = fileURLToPath(new URL("./lib/i18n.ts", import.meta.url))
+
+/**
+ * Returns the adapter module for `@mannisto/astro-i18n`. The module imports the runtime of
+ * the project by its path, because with pnpm this package can not see it by its name.
+ *
+ * @param {string} runtime - The absolute path of `@mannisto/astro-i18n/runtime`.
+ * @returns {string}
+ */
+function astroI18nAdapter(runtime) {
+  return `import { Locale } from ${JSON.stringify(runtime)}
+
+export const i18n = {
+  locale(page) {
+    return Locale.fromURL(page.url)
+  },
+  path(page) {
+    return Locale.url(Locale.fromURL(page.url), page.url.pathname)
+  },
+  alternates(page) {
+    const path = page.url.pathname
+    const links = Locale.supported.map((code) => {
+      return { hreflang: code, href: Locale.url(code, path) }
+    })
+    return [...links, { hreflang: "x-default", href: Locale.url(Locale.defaultLocale, path) }]
+  },
+}
+`
+}
+
+/**
+ * Returns the adapter module for the `i18n` option of Astro.
+ *
+ * @param {NonNullable<import("astro").AstroConfig["i18n"]>} i18n
+ * @param {string} base - The `base` of the Astro config.
+ * @returns {string}
+ */
+function nativeI18nAdapter(i18n, base) {
+  // A locale is a code, or a path with codes, e.g. { path: "spanish", codes: ["es"] }
+  const locales = i18n.locales.map((entry) => {
+    return typeof entry === "string"
+      ? { path: entry, code: entry }
+      : { path: entry.path, code: entry.codes[0] }
+  })
+
+  return `import { getRelativeLocaleUrl } from "astro:i18n"
+
+const LOCALES = ${JSON.stringify(locales)}
+const DEFAULT_LOCALE = ${JSON.stringify(i18n.defaultLocale)}
+const BASE = ${JSON.stringify(base.replace(/\/$/, ""))}
+
+// Returns the path of the page without the base and the locale prefix, e.g. "about/"
+function pagePath(page) {
+  let path = page.url.pathname
+  if (BASE && path.startsWith(BASE)) path = path.slice(BASE.length) || "/"
+  const parts = path.split("/")
+  const prefixed = LOCALES.some((locale) => {
+    return locale.path === parts[1]
+  })
+  return (prefixed ? parts.slice(2) : parts.slice(1)).join("/")
+}
+
+export const i18n = {
+  locale(page) {
+    return page.currentLocale
+  },
+  path(page) {
+    return page.url.pathname
+  },
+  alternates(page) {
+    const path = pagePath(page)
+    const links = LOCALES.map((locale) => {
+      return { hreflang: locale.code, href: getRelativeLocaleUrl(locale.code, path) }
+    })
+    return [...links, { hreflang: "x-default", href: getRelativeLocaleUrl(DEFAULT_LOCALE, path) }]
+  },
+}
+`
+}
+
+/**
+ * Returns the adapter module for the i18n setup of the project, or undefined without one.
+ *
+ * @param {import("astro").AstroConfig} config
+ * @param {import("astro").AstroIntegrationLogger} logger
+ * @returns {string | undefined}
+ */
+function i18nAdapter(config, logger) {
+  const astroI18n = config.integrations.some((integration) => {
+    return integration.name === "@mannisto/astro-i18n"
+  })
+  if (astroI18n) {
+    try {
+      const fromProject = createRequire(fileURLToPath(new URL("./package.json", config.root)))
+      return astroI18nAdapter(fromProject.resolve("@mannisto/astro-i18n/runtime"))
+    } catch {
+      logger.warn("@mannisto/astro-i18n is in the config, but its runtime was not found.")
+      return undefined
+    }
+  }
+  if (config.i18n) return nativeI18nAdapter(config.i18n, config.base)
+  return undefined
+}
+
+/**
+ * Returns a Vite plugin that replaces the i18n module of `<Metadata>` with an adapter.
+ *
+ * @param {string} adapter - The code of the adapter module.
+ * @returns {import("vite").Plugin}
+ */
+function i18nPlugin(adapter) {
+  return {
+    name: "astro-metadata:i18n",
+    enforce: "pre",
+    load(id) {
+      if (id.split("?")[0] === I18N_FILE) return adapter
+      return undefined
+    },
+  }
+}
+
 /**
  * Loads sharp for the image sizes of the build checks, or undefined without sharp.
  *
@@ -428,9 +552,13 @@ export default function metadata(options = {}) {
           if (options[key] !== undefined) runtime[key] = options[key]
         }
 
+        // <Metadata> reads the locale, the page URL and the hreflang links from the i18n setup
+        const adapter = i18nAdapter(config, logger)
+
         // The config is plain data, so it goes to the components as a build-time constant
         updateConfig({
           vite: {
+            plugins: adapter ? [i18nPlugin(adapter)] : [],
             define: { __ASTRO_METADATA__: JSON.stringify(runtime) },
             // The dev toolbar app uses Lit. Without this list, Vite finds Lit only when the
             // app loads, and the page reloads one time.

package/src/lib/config.ts

@@ -1,5 +1,6 @@
 import type { FaviconInfo } from "./favicon.ts"
 import type { ManifestConfig } from "./manifest.ts"
+import type { SchemaConfig } from "./schema.ts"
 
 /**
  * A text value: one string for all locales, or one string for each locale.
@@ -69,6 +70,11 @@ export type MetadataConfig = {
   }
   /** The web app manifest: an object to generate it, or the path of your own manifest. */
   manifest?: ManifestConfig | string
+  /**
+   * The structured data of the site. Each page gets the `WebSite` and its publisher:
+   * by default an organization with the site name. Set to false to turn it off.
+   */
+  schema?: SchemaConfig
 }
 
 /**

package/src/lib/i18n.ts

@@ -0,0 +1,22 @@
+/** The values of the Astro page that the i18n adapter reads. */
+export type I18nPage = {
+  url: URL
+  currentLocale?: string
+}
+
+/**
+ * Reads the locale values of a page from the i18n setup of the project:
+ * `@mannisto/astro-i18n`, or the `i18n` option of Astro.
+ */
+export type I18nAdapter = {
+  /** The locale of the page, e.g. "fi". */
+  locale(page: I18nPage): string | undefined
+  /** The public path of the page, e.g. "/about" for the default locale without a prefix. */
+  path(page: I18nPage): string
+  /** The path of the page in each locale, and `x-default`. */
+  alternates(page: I18nPage): { hreflang: string; href: string }[]
+}
+
+// Without an i18n setup, there is no adapter. The integration replaces this module with
+// an adapter for `@mannisto/astro-i18n` or for the `i18n` option of Astro.
+export const i18n: I18nAdapter | undefined = undefined

package/src/lib/rules.js

@@ -712,8 +712,37 @@ function indexedPages(pages) {
   })
 }
 
+/**
+ * Returns true for a page with an hreflang link to the canonical URL of another page.
+ *
+ * @param {import("./rules").SitePage} page
+ * @param {import("./rules").SitePage} other
+ * @returns {boolean}
+ */
+function linksTo(page, other) {
+  const url = findLink(other.head, "canonical")
+  if (!url) return false
+  return hreflangLinks(page.head).some((link) => {
+    return link.href === url
+  })
+}
+
+/**
+ * Returns true for two pages that are versions of one page in other locales:
+ * one of the pages has an hreflang link to the other.
+ *
+ * @param {import("./rules").SitePage} a
+ * @param {import("./rules").SitePage} b
+ * @returns {boolean}
+ */
+function isLocaleVersion(a, b) {
+  return linksTo(a, b) || linksTo(b, a)
+}
+
 /**
  * Returns a problem for each page with a value that other pages also have.
+ * The versions of a page in other locales can have the same value, e.g. the name of
+ * an artwork in its title, so they do not count.
  *
  * @param {import("./rules").SitePage[]} pages
  * @param {(page: import("./rules").SitePage) => string | undefined} valueOf
@@ -721,29 +750,27 @@ function indexedPages(pages) {
  * @returns {import("./rules").SiteProblem[]}
  */
 function duplicates(pages, valueOf, name) {
-  /** @type {Map<string, string[]>} */
+  /** @type {Map<string, import("./rules").SitePage[]>} */
   const groups = new Map()
   for (const page of indexedPages(pages)) {
     const value = valueOf(page)
-    if (value) groups.set(value, [...(groups.get(value) ?? []), page.path])
+    if (value) groups.set(value, [...(groups.get(value) ?? []), page])
   }
 
-  return [...groups.values()]
-    .filter((paths) => {
-      return paths.length > 1
-    })
-    .flatMap((paths) => {
-      return paths.map((path) => {
-        const others = paths.filter((other) => {
-          return other !== path
-        })
-        const list =
-          others.length === 1
-            ? others[0]
-            : `${others[0]} and ${count(others.length - 1, "other page")}`
-        return { path, message: `The ${name} is the same as on ${list}.` }
+  return [...groups.values()].flatMap((group) => {
+    return group.flatMap((page) => {
+      const others = group.filter((other) => {
+        return other !== page && !isLocaleVersion(page, other)
       })
+      if (others.length === 0) return []
+
+      const list =
+        others.length === 1
+          ? others[0].path
+          : `${others[0].path} and ${count(others.length - 1, "other page")}`
+      return [{ path: page.path, message: `The ${name} is the same as on ${list}.` }]
     })
+  })
 }
 
 /**

package/src/lib/schema.ts

@@ -1,69 +1,74 @@
-import type {
-  Article,
-  BreadcrumbList,
-  Graph,
-  Organization,
-  Person,
-  Thing,
-  WebSite,
-  WithContext,
-} from "schema-dts"
+import type { Graph, Thing, WithContext } from "schema-dts"
 
 import { getConfig, localize } from "./config.ts"
+import type { Localized } from "./config.ts"
 import { url } from "./url.ts"
 
 /**
- * The data of a JSON-LD script. The schema.org types give the editor completion,
- * and other objects are also accepted.
+ * A structured data item of your own, e.g. a `Product` or an `Event`. The schema.org types
+ * give the editor completion, and other objects are also accepted. `@context` is not
+ * necessary: the items go into one graph with the context.
  */
-export type SchemaData = WithContext<Thing> | Graph | Record<string, unknown>
+export type SchemaData = Thing | WithContext<Thing> | Record<string, unknown>
 
-export type SchemaWebsite = {
-  /** Defaults to `siteName` in the config. */
-  name?: string
-  /** Defaults to `description` in the config. */
-  description?: string
-  /** Defaults to the site root. */
-  url?: string
-  /** The locale of the localized config values, e.g. `Astro.currentLocale`. */
-  locale?: string
-}
-
-export type SchemaOrganization = {
+/**
+ * The organization or the person behind the site. It is the publisher of the site and of
+ * the articles.
+ */
+export type SchemaPublisher = {
+  /** Defaults to "Organization". */
+  type?: "Organization" | "Person"
   /** Defaults to `siteName` in the config. */
-  name?: string
-  /** Defaults to the site root. */
-  url?: string
-  /** The path or URL of the logo, e.g. "/logo.png". */
+  name?: Localized
+  /** The path or URL of the logo of an organization, e.g. "/logo.png". */
   logo?: string
-  /** The profiles of the organization on other sites. */
+  /** The profiles on other sites, e.g. the GitHub or LinkedIn page. */
   sameAs?: string[]
-  /** The locale of the localized config values, e.g. `Astro.currentLocale`. */
-  locale?: string
 }
 
-export type SchemaAuthor = string | { name: string; url?: string }
+/** The `schema` option: the structured data of the site. Set to false to turn it off. */
+export type SchemaConfig =
+  | false
+  | {
+      publisher?: SchemaPublisher
+    }
+
+/** The author of an article: a name, or a name with a profile URL and a Twitter (X) handle. */
+export type SchemaAuthor =
+  | string
+  | {
+      name: string
+      /** The path or URL of the profile page of the author, e.g. "/about". */
+      url?: string
+      /** The Twitter (X) handle of the author, e.g. "@acmewriter". */
+      twitter?: string
+    }
+
+/** A step in the breadcrumbs: from the home page to the current page. */
+export type SchemaBreadcrumb = {
+  name: string
+  /** The path or URL of the page, e.g. "/exhibitions". */
+  url: string
+}
 
-export type SchemaArticle = {
-  /** Defaults to "Article". */
-  type?: "Article" | "BlogPosting" | "NewsArticle"
-  title: string
+/** The values of a page that the structured data uses. `<Metadata>` gives them. */
+export type SchemaPage = {
+  /** The absolute URL of the page. */
+  url: string
+  /** The title of the page without the title template. */
+  title?: string
   description?: string
-  /** The paths or URLs of the images. */
-  image?: string | string[]
+  /** The absolute URL of the social image. */
+  image?: string
+  locale?: string
+  /** The Open Graph type: "article" adds an `Article`. */
+  type?: string
   published?: Date | string
   modified?: Date | string
   author?: SchemaAuthor | SchemaAuthor[]
-  /** The URL of the article page, e.g. `Astro.url.pathname`. */
-  url?: string
-  /** The locale of the article. The publisher name uses it too. */
-  locale?: string
-}
-
-export type SchemaBreadcrumb = {
-  name: string
-  /** The path or URL of the page, e.g. "/exhibitions". */
-  url: string
+  breadcrumbs?: SchemaBreadcrumb[]
+  /** Your own items. */
+  items?: SchemaData[]
 }
 
 /**
@@ -74,13 +79,19 @@ function isoDate(value: Date | string | undefined): string | undefined {
   return value.toISOString()
 }
 
+/**
+ * Returns the authors as a list.
+ */
+function authorList(author: SchemaPage["author"]): SchemaAuthor[] {
+  if (author === undefined) return []
+  return Array.isArray(author) ? author : [author]
+}
+
 /**
  * Returns an author as a schema.org person.
  */
-function person(author: SchemaAuthor): Person {
-  if (typeof author === "string") {
-    return { "@type": "Person", name: author }
-  }
+function person(author: SchemaAuthor): Record<string, unknown> {
+  if (typeof author === "string") return { "@type": "Person", name: author }
   return {
     "@type": "Person",
     name: author.name,
@@ -89,113 +100,111 @@ function person(author: SchemaAuthor): Person {
 }
 
 /**
- * Returns the `WebSite` schema, with the name and the URL of the site.
- *
- * @example Schema.website({ locale: Astro.currentLocale })
+ * Returns the publisher of the site, or undefined without a name.
  */
-function website(options: SchemaWebsite = {}): WithContext<WebSite> {
+function publisher(page: SchemaPage, id: string): Record<string, unknown> | undefined {
   const config = getConfig()
+  const options = (config.schema || undefined)?.publisher ?? {}
+  const name = localize(options.name, page.locale) ?? localize(config.siteName, page.locale)
+  if (!name) return undefined
+
+  const type = options.type ?? "Organization"
   return {
-    "@context": "https://schema.org",
-    "@type": "WebSite",
-    name: options.name ?? localize(config.siteName, options.locale),
-    description: options.description ?? localize(config.description, options.locale),
-    url: url(options.url ?? "/"),
-    inLanguage: options.locale,
+    "@type": type,
+    "@id": id,
+    name,
+    url: url("/"),
+    logo: type === "Organization" && options.logo ? url(options.logo) : undefined,
+    sameAs: options.sameAs,
   }
 }
 
 /**
- * Returns the `Organization` schema of the site owner.
- *
- * @example Schema.organization({ logo: "/logo.png" })
+ * Returns an item without `@context`: the graph has the context.
  */
-function organization(options: SchemaOrganization = {}): WithContext<Organization> {
-  const config = getConfig()
-  return {
-    "@context": "https://schema.org",
-    "@type": "Organization",
-    name: options.name ?? localize(config.siteName, options.locale),
-    url: url(options.url ?? "/"),
-    logo: options.logo ? url(options.logo) : undefined,
-    sameAs: options.sameAs,
-  }
+function withoutContext(item: SchemaData): Record<string, unknown> {
+  const copy = { ...(item as Record<string, unknown>) }
+  delete copy["@context"]
+  return copy
 }
 
 /**
- * Returns the `Article` schema of a page. The publisher is the site from the config.
- *
- * @example Schema.article({ title, published: post.date, author: "Acme Writer" })
+ * Returns the structured data of a page as one graph:
+ * - the `WebSite` and its publisher, from the config,
+ * - an `Article` for a page with the type "article",
+ * - a `BreadcrumbList` for a page with breadcrumbs,
+ * - and your own items.
+ * The items link to each other with `@id`. Returns undefined without items.
  */
-function article(options: SchemaArticle): WithContext<Article> {
+function graph(page: SchemaPage): Graph | undefined {
   const config = getConfig()
-  const siteName = localize(config.siteName, options.locale)
-  const images = typeof options.image === "string" ? [options.image] : options.image
-  const authors = Array.isArray(options.author) ? options.author : [options.author]
+  const site = url("/")
+  const items: Record<string, unknown>[] = []
+
+  const owner = config.schema === false ? undefined : publisher(page, `${site}#publisher`)
+  const ownerLink = owner ? { "@id": owner["@id"] } : undefined
+
+  if (config.schema !== false && owner) {
+    items.push({
+      "@type": "WebSite",
+      "@id": `${site}#website`,
+      name: owner.name,
+      description: localize(config.description, page.locale),
+      url: site,
+      inLanguage: page.locale,
+      publisher: ownerLink,
+    })
+    items.push(owner)
+  }
 
-  return {
-    "@context": "https://schema.org",
-    "@type": options.type ?? "Article",
-    headline: options.title,
-    description: options.description,
-    image: images?.map((image) => {
-      return url(image)
-    }),
-    datePublished: isoDate(options.published),
-    dateModified: isoDate(options.modified),
-    author: options.author
-      ? authors.flatMap((author) => {
-          return author ? [person(author)] : []
-        })
-      : undefined,
-    publisher: siteName
-      ? {
-          "@type": "Organization",
-          name: siteName,
-          url: url("/"),
-        }
-      : undefined,
-    mainEntityOfPage: options.url ? url(options.url) : undefined,
-    inLanguage: options.locale,
-  } as WithContext<Article>
-}
+  if (page.type === "article") {
+    const authors = authorList(page.author)
+    items.push({
+      "@type": "Article",
+      "@id": `${page.url}#article`,
+      headline: page.title,
+      description: page.description,
+      image: page.image ? [page.image] : undefined,
+      datePublished: isoDate(page.published),
+      dateModified: isoDate(page.modified),
+      author: authors.length > 0 ? authors.map(person) : undefined,
+      publisher: ownerLink,
+      mainEntityOfPage: page.url,
+      inLanguage: page.locale,
+    })
+  }
 
-/**
- * Returns the `BreadcrumbList` schema: the path from the home page to the current page.
- *
- * @example Schema.breadcrumbs([{ name: "Home", url: "/" }, { name: "Blog", url: "/blog" }])
- */
-function breadcrumbs(items: SchemaBreadcrumb[]): WithContext<BreadcrumbList> {
-  return {
-    "@context": "https://schema.org",
-    "@type": "BreadcrumbList",
-    itemListElement: items.map((item, index) => {
-      return {
-        "@type": "ListItem",
-        position: index + 1,
-        name: item.name,
-        item: url(item.url),
-      }
-    }),
+  if (page.breadcrumbs && page.breadcrumbs.length > 0) {
+    items.push({
+      "@type": "BreadcrumbList",
+      "@id": `${page.url}#breadcrumbs`,
+      itemListElement: page.breadcrumbs.map((step, index) => {
+        return { "@type": "ListItem", position: index + 1, name: step.name, item: url(step.url) }
+      }),
+    })
   }
+
+  for (const item of page.items ?? []) {
+    items.push(withoutContext(item))
+  }
+
+  if (items.length === 0) return undefined
+  return { "@context": "https://schema.org", "@graph": items } as unknown as Graph
 }
 
 /**
- * Builders for common JSON-LD schemas. They fill in values from the config of the
- * integration and make all URLs absolute. Give the result to `<Metadata schema>`.
+ * The structured data of the pages. `<Metadata>` renders it: the site from the config,
+ * and the article, the breadcrumbs and your own items of a page.
  */
 export const Schema = {
-  website,
-  organization,
-  article,
-  breadcrumbs,
+  graph,
 
   /**
-   * Returns the data as JSON that is safe inside a script tag.
+   * Returns the data as JSON that is safe inside a script tag. Empty values are removed.
    *
    * @example <script type="application/ld+json" set:html={Schema.stringify(data)} />
    */
-  stringify(data: SchemaData | SchemaData[]): string {
+  stringify(data: unknown): string {
     // Escape the characters that can end the script tag or break the JavaScript parser.
     // A value such as "</script>" in the schema then stays inside the JSON.
     return JSON.stringify(data)

package/src/lib/site.ts

@@ -21,6 +21,7 @@ export const Site = {
       feeds: config.feeds,
       robots: config.robots,
       manifest: config.manifest,
+      schema: config.schema,
     }
   },
 

package/src/runtime.ts

@@ -5,12 +5,12 @@ export { Favicon } from "./lib/favicon.ts"
 export type { ManifestConfig, ManifestPath } from "./lib/manifest.ts"
 export { Manifest } from "./lib/manifest.ts"
 export type {
-  SchemaArticle,
   SchemaAuthor,
   SchemaBreadcrumb,
+  SchemaConfig,
   SchemaData,
-  SchemaOrganization,
-  SchemaWebsite,
+  SchemaPage,
+  SchemaPublisher,
 } from "./lib/schema.ts"
 export { Schema } from "./lib/schema.ts"
 export { Site } from "./lib/site.ts"

package/src/toolbar/data.ts

@@ -109,7 +109,11 @@ function jsonLd(): JsonLd[] {
     const source = script.textContent ?? ""
     try {
       const data = JSON.parse(source)
-      const items = Array.isArray(data) ? data : [data]
+      // The items of a list, or of a graph
+      const list = Array.isArray(data) ? data : [data]
+      const items = list.flatMap((item) => {
+        return Array.isArray(item?.["@graph"]) ? item["@graph"] : [item]
+      })
       const types = items.map((item) => {
         return String(item?.["@type"] ?? "?")
       })

package/src/toolbar/ui/table/table.css

@@ -31,11 +31,6 @@ tr {
     background: var(--zinc-800);
   }
 
-  /* The row of a problem after a click on the problem */
-  &.highlight :is(th, td) {
-    animation: highlight 1.6s ease-out;
-  }
-
   /* The child rows are indented under their row */
   &.child th {
     padding-left: calc(var(--space-400) + var(--space-400));
@@ -116,9 +111,3 @@ td {
     transform: rotate(90deg);
   }
 }
-
-@keyframes highlight {
-  from {
-    background: var(--blue-900);
-  }
-}

package/src/toolbar/ui/table/table.ts

@@ -34,42 +34,42 @@ export class Table extends LitElement {
   static properties = {
     rows: { attribute: false },
     opened: { state: true },
-    highlighted: { state: true },
   }
   static styles = unsafeCSS(styles)
 
   declare rows: TableRow[]
   /** The indexes of the open rows. */
   declare opened: Set<number>
-  /** The key of the marked row. */
-  declare highlighted: string | undefined
 
   constructor() {
     super()
     this.rows = []
     this.opened = new Set()
-    this.highlighted = undefined
   }
 
   /**
-   * Scrolls to the row with a key and marks it for a moment.
+   * Scrolls to the row with a key and marks it for a moment. Each call starts the mark again,
+   * also while the mark of an earlier call still shows.
    *
    * @returns False when the table has no row with the key.
    */
   async highlight(key: string): Promise<boolean> {
-    const found = this.rows.some((row) => {
-      return row.key === key
-    })
-    if (!found) return false
-
-    // A new value restarts the animation of a row that is already marked
-    this.highlighted = undefined
-    await this.updateComplete
-    this.highlighted = key
     await this.updateComplete
-    this.renderRoot
-      .querySelector("tr.highlight")
-      ?.scrollIntoView({ block: "center", behavior: "smooth" })
+    const row = [...this.renderRoot.querySelectorAll<HTMLElement>("tr[data-key]")].find(
+      (element) => {
+        return element.dataset.key === key
+      }
+    )
+    if (!row) return false
+
+    row.scrollIntoView({ block: "center", behavior: "smooth" })
+    const color = getComputedStyle(this).getPropertyValue("--blue-900")
+    for (const cell of row.querySelectorAll("th, td")) {
+      cell.animate([{ background: color }, { background: "transparent" }], {
+        duration: 1600,
+        easing: "ease-out",
+      })
+    }
     return true
   }
 
@@ -108,9 +108,7 @@ export class Table extends LitElement {
 
   renderRow(row: TableRow, label: unknown, notes: boolean, child: boolean) {
     return html`
-      <tr
-        class="${child ? "child" : ""} ${row.key && row.key === this.highlighted ? "highlight" : ""}"
-      >
+      <tr class=${child ? "child" : ""} data-key=${row.key ?? nothing}>
         <th>${label}</th>
         <td>${this.renderValue(row)}</td>
         ${

package/src/toolbar/views/metadata-panel.css

@@ -2,10 +2,14 @@
   box-sizing: border-box;
 }
 
+/*
+ * The z-index of the Audit app window of Astro: above the site, e.g. a fixed navigation,
+ * and under the toolbar bar (2000000010). The toolbar element has no stacking context.
+ */
 .panel {
   position: fixed;
   inset: 0 0 0 auto;
-  z-index: 1;
+  z-index: 2000000009;
   display: flex;
   flex-direction: column;
   width: var(--panel-width, 480px);