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

package/src/lib/schema.ts

@@ -0,0 +1,208 @@
+import type {
+  Article,
+  BreadcrumbList,
+  Graph,
+  Organization,
+  Person,
+  Thing,
+  WebSite,
+  WithContext,
+} from "schema-dts"
+
+import { getConfig, localize } 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.
+ */
+export type SchemaData = WithContext<Thing> | Graph | 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 = {
+  /** 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". */
+  logo?: string
+  /** The profiles of the organization on other sites. */
+  sameAs?: string[]
+  /** The locale of the localized config values, e.g. `Astro.currentLocale`. */
+  locale?: string
+}
+
+export type SchemaAuthor = string | { name: string; url?: string }
+
+export type SchemaArticle = {
+  /** Defaults to "Article". */
+  type?: "Article" | "BlogPosting" | "NewsArticle"
+  title: string
+  description?: string
+  /** The paths or URLs of the images. */
+  image?: string | 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
+}
+
+/**
+ * Returns a date as an ISO 8601 text. A text stays unchanged.
+ */
+function isoDate(value: Date | string | undefined): string | undefined {
+  if (value === undefined || typeof value === "string") return value
+  return value.toISOString()
+}
+
+/**
+ * Returns an author as a schema.org person.
+ */
+function person(author: SchemaAuthor): Person {
+  if (typeof author === "string") {
+    return { "@type": "Person", name: author }
+  }
+  return {
+    "@type": "Person",
+    name: author.name,
+    url: author.url ? url(author.url) : undefined,
+  }
+}
+
+/**
+ * Returns the `WebSite` schema, with the name and the URL of the site.
+ *
+ * @example Schema.website({ locale: Astro.currentLocale })
+ */
+function website(options: SchemaWebsite = {}): WithContext<WebSite> {
+  const config = getConfig()
+  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,
+  }
+}
+
+/**
+ * Returns the `Organization` schema of the site owner.
+ *
+ * @example Schema.organization({ logo: "/logo.png" })
+ */
+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,
+  }
+}
+
+/**
+ * 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" })
+ */
+function article(options: SchemaArticle): WithContext<Article> {
+  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]
+
+  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>
+}
+
+/**
+ * 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),
+      }
+    }),
+  }
+}
+
+/**
+ * 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>`.
+ */
+export const Schema = {
+  website,
+  organization,
+  article,
+  breadcrumbs,
+
+  /**
+   * Returns the data as JSON that is safe inside a script tag.
+   *
+   * @example <script type="application/ld+json" set:html={Schema.stringify(data)} />
+   */
+  stringify(data: SchemaData | SchemaData[]): 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)
+      .replace(/</g, "\\u003c")
+      .replace(/>/g, "\\u003e")
+      .replace(/&/g, "\\u0026")
+      .replace(/\u2028/g, "\\u2028")
+      .replace(/\u2029/g, "\\u2029")
+  },
+}

package/src/lib/site.ts

@@ -0,0 +1,72 @@
+import { getConfig, localize } from "./config.ts"
+import type { MetadataConfig } from "./config.ts"
+import { pageUrl, url } from "./url.ts"
+
+/**
+ * The site values of the integration, and absolute URLs with the Astro `site` and `base`.
+ */
+export const Site = {
+  /**
+   * Returns the site values of the integration. Without the integration, all values are undefined.
+   */
+  get config(): MetadataConfig {
+    const config = getConfig()
+    return {
+      siteName: config.siteName,
+      titleTemplate: config.titleTemplate,
+      description: config.description,
+      image: config.image,
+      twitter: config.twitter,
+      themeColor: config.themeColor,
+      feeds: config.feeds,
+      robots: config.robots,
+      manifest: config.manifest,
+    }
+  },
+
+  /**
+   * Returns the name of the site for a locale.
+   *
+   * @param locale - e.g. "fi". A missing locale uses the first value.
+   */
+  name(locale?: string): string | undefined {
+    return localize(getConfig().siteName, locale)
+  },
+
+  /**
+   * Returns the full title of a page: the title in the title template, or the site name
+   * for a page without a title.
+   *
+   * @example Site.title("About") // "About | My Site"
+   */
+  title(title?: string, locale?: string): string | undefined {
+    const template = localize(getConfig().titleTemplate, locale)
+    if (!title) return Site.name(locale)
+    if (!template?.includes("%s")) return title
+
+    // A replacer function keeps "$&" and other "$" patterns in the title as text
+    return template.replace("%s", () => {
+      return title
+    })
+  },
+
+  /**
+   * Returns the absolute URL of a path, with the Astro `site` and `base`.
+   * Absolute URLs stay unchanged.
+   *
+   * @example Site.url("/og.jpg") // "https://example.com/og.jpg"
+   */
+  url(path: string): string {
+    return url(path)
+  },
+
+  /**
+   * Returns the absolute URL of a page, with or without the slash at the end,
+   * the same as the Astro `trailingSlash` and `build.format` settings.
+   *
+   * @example Site.pageUrl("/blog") // "https://example.com/blog/"
+   */
+  pageUrl(path: string): string {
+    return pageUrl(path)
+  },
+}

package/src/lib/url.ts

@@ -0,0 +1,79 @@
+import { getConfig } from "./config.ts"
+
+/**
+ * Returns true for a URL with a scheme ("https:", "data:") or a protocol-relative URL ("//").
+ */
+function isAbsolute(value: string): boolean {
+  return /^[a-z][a-z\d+.-]*:/i.test(value) || value.startsWith("//")
+}
+
+/**
+ * Adds the Astro `base` to a path: "/og.jpg" becomes "/docs/og.jpg".
+ * A path that already starts with the base stays unchanged.
+ *
+ * @param path - A path in the site, e.g. "/og.jpg".
+ * @returns The path with the base.
+ */
+export function withBase(path: string): string {
+  if (isAbsolute(path)) return path
+
+  const base = (import.meta.env.BASE_URL ?? "/").replace(/\/$/, "")
+  const clean = path.startsWith("/") ? path : `/${path}`
+  if (!base || clean === base || clean.startsWith(`${base}/`)) return clean
+  return `${base}${clean}`
+}
+
+/**
+ * Returns the absolute URL of a path in the site, with the Astro `site` and `base`:
+ * "/og.jpg" becomes "https://example.com/docs/og.jpg". Absolute URLs stay unchanged.
+ * Without `site` in the Astro config, the result is the path with the base.
+ *
+ * @param path - A path in the site, e.g. "/og.jpg".
+ * @returns The absolute URL.
+ */
+export function url(path: string): string {
+  if (isAbsolute(path)) return path
+
+  const site = import.meta.env.SITE
+  const pathname = withBase(path)
+  return site ? new URL(pathname, site).href : pathname
+}
+
+/**
+ * Adds or removes the slash at the end of a page path, the same as Astro:
+ * - `trailingSlash: "always"` adds the slash, and `"never"` removes it.
+ * - With `"ignore"`, `build.format` decides: "directory" adds the slash, and "file" removes it.
+ *   With "preserve", the path stays unchanged.
+ * Paths with a file extension, a query or a hash stay unchanged.
+ * Without the integration, the path stays unchanged.
+ *
+ * @param path - A page path, e.g. "/blog".
+ * @returns The path with or without the slash at the end.
+ */
+export function pagePath(path: string): string {
+  const { trailingSlash, buildFormat } = getConfig()
+  if (!trailingSlash || path === "/" || /[?#]/.test(path)) return path
+
+  const last = path.split("/").pop() ?? ""
+  if (last.includes(".")) return path
+
+  let slash = trailingSlash === "always"
+  if (trailingSlash === "ignore") {
+    if (buildFormat === "preserve") return path
+    slash = buildFormat !== "file"
+  }
+  const clean = path.replace(/\/+$/, "")
+  return slash ? `${clean}/` : clean || "/"
+}
+
+/**
+ * Returns the absolute URL of a page, with the slash at the end that Astro uses.
+ * Absolute URLs stay unchanged.
+ *
+ * @param path - A page path, e.g. "/blog".
+ * @returns The absolute URL, e.g. "https://example.com/blog/".
+ */
+export function pageUrl(path: string): string {
+  if (isAbsolute(path)) return path
+  return url(pagePath(path))
+}

package/src/routes/favicon.ts

@@ -0,0 +1,14 @@
+import type { APIRoute } from "astro"
+
+import { Favicon } from "../lib/favicon.ts"
+
+export const prerender = true
+
+// The integration adds this route one time for each favicon file.
+// The path without the base tells which file to generate.
+export const GET: APIRoute = ({ url }) => {
+  const base = import.meta.env.BASE_URL.replace(/\/$/, "")
+  const path =
+    base && url.pathname.startsWith(`${base}/`) ? url.pathname.slice(base.length) : url.pathname
+  return Favicon.generate(path)
+}

package/src/routes/manifest.ts

@@ -0,0 +1,18 @@
+import type { APIRoute, GetStaticPaths } from "astro"
+
+import { Manifest } from "../lib/manifest.ts"
+
+export const prerender = true
+
+export const getStaticPaths: GetStaticPaths = () => {
+  return Manifest.paths().map((path) => {
+    return { params: { lang: path.lang }, props: { locale: path.locale } }
+  })
+}
+
+export const GET: APIRoute = ({ props }) => {
+  const manifest = Manifest.build(props.locale)
+  return new Response(JSON.stringify(manifest, null, 2), {
+    headers: { "Content-Type": "application/manifest+json" },
+  })
+}

package/src/runtime.ts

@@ -0,0 +1,16 @@
+export type { Feed, Localized, MetadataConfig, MetadataImage, ThemeColor } from "./lib/config.ts"
+export type { FaviconFile, ResolvedFaviconFile } from "./lib/favicon-files.js"
+export type { FaviconConfig, FaviconLink, ManifestIcon } from "./lib/favicon.ts"
+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,
+  SchemaData,
+  SchemaOrganization,
+  SchemaWebsite,
+} from "./lib/schema.ts"
+export { Schema } from "./lib/schema.ts"
+export { Site } from "./lib/site.ts"

package/src/toolbar/app.ts

@@ -0,0 +1,72 @@
+import { defineToolbarApp } from "astro/toolbar"
+
+import { styleBadge } from "./toolbar-badge.ts"
+
+import "./views/metadata-panel.ts"
+
+import { checkPage, collect, summarize } from "./data.ts"
+import type { MetadataPanel } from "./views/metadata-panel.ts"
+
+export default defineToolbarApp({
+  init(canvas, app) {
+    styleBadge()
+
+    const panel = document.createElement("astro-metadata-panel") as MetadataPanel
+    canvas.append(panel)
+    let open = false
+
+    // The badge shows the worst problem of the page
+    async function updateBadge() {
+      const { checks } = await checkPage()
+      const { level } = summarize(checks)
+      if (level) {
+        app.toggleNotification({ state: true, level })
+      } else {
+        app.toggleNotification({ state: false })
+      }
+    }
+
+    async function load() {
+      panel.data = undefined
+      panel.data = await collect()
+    }
+
+    function setOpen(state: boolean) {
+      app.toggleState({ state })
+    }
+
+    app.onToggled(({ state }) => {
+      open = state
+      if (state) load()
+    })
+
+    panel.addEventListener("close", () => {
+      setOpen(false)
+    })
+
+    // Alt+M (Option+M on a Mac) opens and closes the panel. Escape closes it.
+    // `code` is the key, not the character: Option+M types "µ" on a Mac.
+    document.addEventListener("keydown", (event) => {
+      const target = event.target as HTMLElement | null
+      if (target?.closest("input, textarea, select, [contenteditable]")) return
+
+      if (event.altKey && event.code === "KeyM") {
+        event.preventDefault()
+        setOpen(!open)
+      } else if (event.key === "Escape" && open) {
+        setOpen(false)
+      }
+    })
+
+    // View transitions change the page without a full load
+    document.addEventListener("astro:after-swap", () => {
+      updateBadge()
+      if (open) load()
+    })
+
+    updateBadge()
+
+    // ?metadata in the URL opens the panel when the page loads
+    if (new URLSearchParams(location.search).has("metadata")) setOpen(true)
+  },
+})

package/src/toolbar/assets.ts

@@ -0,0 +1,81 @@
+import type { Asset, HeadData, PageAssets } from "../lib/checks.js"
+import { getConfig } from "../lib/config.ts"
+
+/**
+ * Returns the URL to load a file from, or undefined for a file on another site.
+ * A file of the site loads from the dev server, because the `site` URL is the
+ * production site, where a new file does not exist yet.
+ */
+function devUrl(url: string): URL | undefined {
+  let parsed: URL
+  try {
+    parsed = new URL(url, location.href)
+  } catch {
+    return undefined
+  }
+  if (parsed.origin === location.origin) return parsed
+
+  const site = getConfig().site
+  if (!site || parsed.origin !== new URL(site).origin) return undefined
+  return new URL(`${parsed.pathname}${parsed.search}`, location.origin)
+}
+
+/**
+ * Returns the real size of an image, or undefined for a format that the browser
+ * can not measure, e.g. SVG.
+ */
+async function imageSize(blob: Blob): Promise<{ width: number; height: number } | undefined> {
+  try {
+    const bitmap = await createImageBitmap(blob)
+    const size = { width: bitmap.width, height: bitmap.height }
+    bitmap.close()
+    return size
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Loads a file of the page: whether it loads, its type, its size in bytes,
+ * and the size of an image.
+ */
+async function loadAsset(url: string, measure: boolean): Promise<Asset | undefined> {
+  const source = devUrl(url)
+  if (!source) return undefined
+
+  try {
+    const response = await fetch(source)
+    if (!response.ok) return { url, ok: false, status: response.status }
+
+    const blob = await response.blob()
+    const type = blob.type || response.headers.get("content-type")?.split(";")[0]
+    const size = measure ? await imageSize(blob) : undefined
+    return { url, ok: true, type, bytes: blob.size, ...size }
+  } catch {
+    return { url, ok: false }
+  }
+}
+
+/**
+ * Loads the `og:image` and the favicons of the page from the dev server.
+ * The build reads the same files from the output folder.
+ */
+export async function loadAssets(head: HeadData): Promise<PageAssets> {
+  const imageUrl = head.meta["og:image"]
+  const links = head.links.filter((link) => {
+    return /(^|\s)(icon|apple-touch-icon)(\s|$)/i.test(link.rel ?? "") && Boolean(link.href)
+  })
+
+  const [image, ...icons] = await Promise.all([
+    imageUrl ? loadAsset(imageUrl, true) : Promise.resolve(undefined),
+    ...links.map((link) => {
+      return loadAsset(link.href, false)
+    }),
+  ])
+  return {
+    image,
+    icons: icons.filter((icon): icon is Asset => {
+      return icon !== undefined
+    }),
+  }
+}