@mannisto/astro-metadata 2.0.0-alpha.5 → 2.0.0

package/README.md

@@ -1,25 +1,12 @@
 # Astro Metadata
 
-![banner](./assets/banner.png)
+![banner](./docs/banner.png)
 
 ![Astro](https://img.shields.io/badge/astro-%232C2052.svg?style=for-the-badge&logo=astro&logoColor=white)
 ![npm version](https://img.shields.io/npm/v/@mannisto/astro-metadata?style=for-the-badge)
 ![license](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)
 
-The page metadata for Astro: the title, the description, the canonical URL, social cards, favicons, the web app manifest and structured data. Set the site values one time, and give each page only its own values.
-
-- [Install](#install)
-- [Configuration](#configuration)
-- [Metadata component](#metadata-component)
-- [Favicons](#favicons)
-- [Web app manifest](#web-app-manifest)
-- [Structured data](#structured-data)
-- [Checks](#checks)
-- [API](#api)
-- [Good to know](#good-to-know)
-- [Migrate from v1](#migrate-from-v1)
-- [Contributing](#contributing)
-- [License](#license)
+The page metadata for Astro: the title, the description, the canonical URL, social cards, favicons, the web app manifest and structured data. Set the site values one time, and give each page only its own values. In dev, an app in the Astro dev toolbar checks each page.
 
 ## Install
 
@@ -43,12 +30,28 @@ export default defineConfig({
       siteName: "Acme Studio",
       titleTemplate: "%s | Acme Studio",
       description: "Tools for small teams.",
-      image: { url: "/og.jpg", alt: "Acme Studio", width: 1200, height: 630 },
-      twitter: { site: "@acmestudio" },
+      image: {
+        url: "/og.jpg",
+        alt: "Acme Studio",
+        width: 1200,
+        height: 630,
+      },
+      twitter: {
+        site: "@acmestudio",
+      },
       themeColor: "#111111",
-      feeds: [{ href: "/rss.xml", title: "News" }],
-      favicon: { source: "./src/assets/logo.svg" },
-      manifest: { name: "Acme Studio" },
+      feeds: [
+        {
+          href: "/rss.xml",
+          title: "News",
+        },
+      ],
+      favicon: {
+        source: "./src/assets/logo.svg",
+      },
+      manifest: {
+        name: "Acme Studio",
+      },
     }),
   ],
 })
@@ -69,32 +72,10 @@ Set `site` in the Astro config. The canonical URL and the social images must be
 | `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). |
+| `debug` | `true` | The dev toolbar app (`client`) and the build log (`build`). 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). |
 
-### Translations
-
-Each text can be one string, or an object with one string for each locale:
-
-```typescript
-metadata({
-  siteName: { en: "Acme Studio", fi: "Acme Studio Suomi" },
-  titleTemplate: { en: "%s | Acme Studio", fi: "%s | Acme Studio Suomi" },
-})
-```
-
-`<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
 
 Put `<Metadata>` into the `<head>` of your layout, and give it the values of the page:
@@ -164,7 +145,98 @@ The page values override the site values. For example, `title="About"` gives:
 | `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`.
+`<Metadata>` renders a tag only when the tag has a value. For example, the robots tag is necessary only with `index` or `follow` set to `false`.
+
+### Single components
+
+`<Metadata>` renders all tags. To render only some of them, use the single components. They take the same props as `<Metadata>`, and they use the same site values:
+
+```astro
+---
+import { Canonical, OpenGraph, Title } from "@mannisto/astro-metadata/components"
+---
+
+<Title title="About" />
+<Canonical />
+<OpenGraph title="About" />
+```
+
+| Component | Tags |
+|---|---|
+| `<Title>` | `title` |
+| `<Description>` | `description` |
+| `<Canonical>` | The canonical link |
+| `<Robots>` | `robots` |
+| `<ThemeColor>` | `theme-color` |
+| `<OpenGraph>` | `og:*` and `article:*` |
+| `<Twitter>` | `twitter:*` |
+| `<Favicon>` | The favicon links |
+| `<Manifest>` | The manifest link |
+| `<Feeds>` | The feed links |
+| `<LanguageAlternates>` | The hreflang links |
+| `<Schema>` | The structured data |
+
+## Multiple languages
+
+### Translations
+
+Each text can be one string, or an object with one string for each locale:
+
+```typescript
+metadata({
+  siteName: "Acme Studio",
+  description: {
+    en: "Tools for small teams.",
+    fi: "Työkaluja pienille tiimeille.",
+  },
+})
+```
+
+`<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
+
+On a site with more than one language, `<Metadata>` finds the language of each page and its other language versions by itself. This works with [`@mannisto/astro-i18n`](https://github.com/eremannisto/astro-i18n) and with the [native i18n of Astro](https://docs.astro.build/en/guides/internationalization/). You do not need extra code.
+
+Each page then tells search engines and social sites its language, and where the same page is in the other languages:
+
+```html
+<meta property="og:locale" content="en_US">
+<meta property="og:locale:alternate" content="fi_FI">
+<link rel="alternate" hreflang="en" href="https://example.com/about/">
+<link rel="alternate" hreflang="fi" href="https://example.com/fi/about/">
+<link rel="alternate" hreflang="x-default" href="https://example.com/about/">
+```
+
+With `@mannisto/astro-i18n`, the URLs also follow your `prefixDefaultLocale` option, for example `/about` and not `/en/about`.
+
+With another i18n library, give the language of the page in `locale`, and the language versions in `hreflang`. `<Metadata>` makes the same tags from them:
+
+```astro
+<Metadata
+  locale="fi"
+  hreflang={[
+    {
+      hreflang: "en",
+      href: "/about",
+    },
+    {
+      hreflang: "fi",
+      href: "/fi/about",
+    },
+    {
+      hreflang: "x-default",
+      href: "/about",
+    },
+  ]}
+/>
+```
+
+A page that has no other language versions, for example a 404 page, can turn off the links:
+
+```astro
+<Metadata hreflang={[]} />
+```
 
 ## Favicons
 
@@ -197,11 +269,25 @@ To generate other files, give a `files` list. It replaces the default files:
 favicon: {
   source: "./src/assets/logo.svg",
   files: [
-    { path: "/favicon.ico", sizes: [16, 32, 48] },
-    { path: "/favicon.svg" },
-    { path: "/apple-touch-icon.png", size: 180 },
-    { path: "/favicon-96.png", size: 96 },
-    { path: "/favicon-512.png", size: 512 },
+    {
+      path: "/favicon.ico",
+      sizes: [16, 32, 48],
+    },
+    {
+      path: "/favicon.svg",
+    },
+    {
+      path: "/apple-touch-icon.png",
+      size: 180,
+    },
+    {
+      path: "/favicon-96.png",
+      size: 96,
+    },
+    {
+      path: "/favicon-512.png",
+      size: 512,
+    },
   ],
 }
 ```
@@ -249,7 +335,19 @@ metadata({
 })
 ```
 
-Your own manifest endpoint can use the generated icons with `Favicon.icons()`.
+Your own manifest endpoint can use the generated icons with `Site.icons()`:
+
+```typescript
+// src/pages/site.webmanifest.ts
+import { Site } from "@mannisto/astro-metadata/runtime"
+
+export const GET = () => {
+  return Response.json({
+    name: Site.name(),
+    icons: Site.icons(),
+  })
+}
+```
 
 ## Structured data
 
@@ -278,7 +376,11 @@ For a personal site, use `publisher: { type: "Person" }`. Set `schema: false` to
   title="Hello"
   type="article"
   published={post.date}
-  author={{ name: "Acme Writer", url: "/about", twitter: "@acmewriter" }}
+  author={{
+    name: "Acme Writer",
+    url: "/about",
+    twitter: "@acmewriter",
+  }}
 />
 ```
 
@@ -287,8 +389,14 @@ For a personal site, use `publisher: { type: "Person" }`. Set `schema: false` to
 ```astro
 <Metadata
   breadcrumbs={[
-    { name: "Home", url: "/" },
-    { name: "Blog", url: "/blog" },
+    {
+      name: "Home",
+      url: "/",
+    },
+    {
+      name: "Blog",
+      url: "/blog",
+    },
   ]}
 />
 ```
@@ -296,40 +404,75 @@ For a personal site, use `publisher: { type: "Person" }`. Set `schema: false` to
 **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" }} />
+<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.
 
+## Dev toolbar app
+
+Run `astro dev`, and open the Metadata app in the dev toolbar. The app checks the current page, and shows its tags and its link previews. Click a problem to open the row of its tag.
+
+<table>
+  <tr>
+    <td><img src="./docs/screenshots/01.png" alt="The Overview tab with no problems" width="260"></td>
+    <td><img src="./docs/screenshots/02.png" alt="The Overview tab with an error, two warnings and two notes" width="260"></td>
+    <td><img src="./docs/screenshots/03.png" alt="The Social section with the Open Graph tags" width="260"></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/screenshots/04.png" alt="The Structured data section with the JSON-LD of the page" width="260"></td>
+    <td><img src="./docs/screenshots/05.png" alt="The Previews tab with the Google and Twitter (X) previews" width="260"></td>
+    <td><img src="./docs/screenshots/06.png" alt="The Raw tab with the tags of the head" width="260"></td>
+  </tr>
+</table>
+
 ## Checks
 
-The integration checks the metadata of each page. Each problem has a level:
+The dev toolbar app checks the current page. The build checks all prerendered pages, and compares them, for example for the same title on two pages. It logs the errors and the warnings:
 
-| Level | Meaning | Examples |
+```
+[WARN] [@mannisto/astro-metadata] /about/index.html
+  - The page has no description.
+```
+
+| Level | Description | Examples |
 | --- | --- | --- |
-| Error | The metadata is broken. | No title, placeholder text such as `undefined`, two canonical links, invalid JSON-LD, an `og:image` that does not load |
-| Warning | Fix it for better results. | A long title, the same title on two pages, no `twitter:card`, an `og:image` over 600 KB, an hreflang page that does not link back |
+| Error | The metadata is broken. | No title, placeholder text such as `undefined`, invalid JSON-LD, an `og:image` that does not load |
+| Warning | Fix it for better results. | A long title, the same title on two pages, an `og:image` over 600 KB |
 | Info | Good to know. | `noindex`, a short description, no `og:image:alt` |
 
-The checks look at three things:
-
-- **The head of each page:** the tags, the structured data and the hreflang links. A page with `noindex` gets no search and sharing checks.
-- **The files of each page:** the `og:image` and the favicons. The checks load them, and compare the real image size, format and file size with the tags. Files on other sites are not checked.
-- **All pages together:** the same title or description on two pages, and hreflang links that do not link back. Only the build can compare the pages.
+To turn off the checks, use `debug`:
 
-The results show in two places:
+```typescript
+// No dev toolbar app
+metadata({
+  debug: {
+    client: false,
+  },
+})
 
-- **In dev:** Open the Metadata app in the Astro dev toolbar. It shows the problems of the current page. Click a problem to open the row of its tag. The app also shows the link previews of Google, Twitter (X), Facebook, LinkedIn, WhatsApp, Discord and Slack, and all metadata tags.
-- **In the build:** The integration logs the errors and the warnings of the prerendered pages:
+// No build log
+metadata({
+  debug: {
+    build: false,
+  },
+})
 
-```
-[WARN] [@mannisto/astro-metadata] /about/index.html
-  - The page has no description.
+// Neither
+metadata({
+  debug: false,
+})
 ```
 
 ### Turn off rules
 
-All rules and their ids are in [`src/lib/rules.js`](./src/lib/rules.js). Give the ids of the rules to turn off in `rules.ignore`. This applies to the dev toolbar app and to the build:
+Give the ids of the rules in `rules.ignore`. All rules and their ids are in [`src/lib/rules.js`](./src/lib/rules.js).
 
 ```typescript
 metadata({
@@ -341,7 +484,7 @@ metadata({
 
 ### Custom rules
 
-Add your own rules in `rules.custom`. A rule has an `id`, a `level` (`"error"`, `"warning"` or `"info"`), a `message`, and a `check` function that returns `true` when the page has the problem:
+Add your own rules in `rules.custom`. A rule has an `id`, a `level` (`"error"`, `"warning"` or `"info"`), a `message` and a `check` function. The function returns `true` when the page has the problem:
 
 ```typescript
 metadata({
@@ -376,11 +519,11 @@ The rule can also have:
 - `field`, the tag of the problem, for example `"og:title"`. A click on the problem in the dev toolbar app opens its row.
 - `indexed: true`, to skip the rule on a noindex page.
 
-The custom rules run in the build and in the dev toolbar app. In dev, the dev server runs them, because they are functions in the Astro config. Text between backticks in a message shows as code in the dev toolbar app. The `MetadataRule` type gives your editor completion.
+Text between backticks in a message shows as code in the dev toolbar app. The `MetadataRule` type gives your editor completion.
 
 ### Ignore pages
 
-Some pages do not need checks, for example a 404 page or the drafts. Give their paths in `pages.ignore`, without the base. In a pattern, `*` matches one part of the path, and `**` matches any number of parts:
+Give the paths of the pages without checks in `pages.ignore`, without the base. `*` matches one part of the path, and `**` matches any number of parts:
 
 ```typescript
 metadata({
@@ -390,46 +533,36 @@ metadata({
 })
 ```
 
-The build does not check these pages, and does not compare them with the other pages. The dev toolbar app shows all values of these pages, but no problems.
-
-Set `debug: { build: false }` to hide the build warnings, `debug: { client: false }` to remove the dev toolbar app, and `debug: false` to turn off both.
+The dev toolbar app still shows the values of these pages, but no problems.
 
 ## API
 
+`Site` returns the values that you set in the integration, for example for a footer, a feed or your own manifest:
+
 ```typescript
-import { Favicon, Manifest, Schema, Site } from "@mannisto/astro-metadata/runtime"
+import { Site } from "@mannisto/astro-metadata/runtime"
+
+Site.description({ locale: "fi" })
 ```
 
-| Method | Returns | Description |
-|---|---|---|
-| `Site.config` | `MetadataConfig` | The site values of the integration |
-| `Site.name("fi")` | `string` | The site name of a locale |
-| `Site.title("About", "fi")` | `string` | The page title in the title template |
-| `Site.url("/og.jpg")` | `string` | The absolute URL of a path |
-| `Site.pageUrl("/about")` | `string` | The absolute URL of a page, with the trailing slash of Astro |
-| `Favicon.config` | `FaviconConfig` | The favicon config, or `undefined` without the `favicon` option |
-| `Favicon.files` | `ResolvedFaviconFile[]` | The generated files |
-| `Favicon.links()` | `FaviconLink[]` | The link tags of the generated files |
-| `Favicon.icons()` | `ManifestIcon[]` | The icons for a web app manifest |
-| `Favicon.url("/favicon.ico")` | `string` | The URL of a file, with the base and a hash |
-| `Favicon.generate("/favicon-32.png")` | `Promise<Response>` | Generates a file of the config |
-| `Manifest.config` | `ManifestConfig \| string` | The `manifest` option |
-| `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.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 |
+| Method | Returns |
 |---|---|
-| `<Metadata>` | See [Metadata component](#metadata-component) |
+| `Site.name()` | `siteName` |
+| `Site.template()` | `titleTemplate` |
+| `Site.description()` | `description` |
+| `Site.image()` | `image`, with an absolute URL |
+| `Site.twitter()` | `twitter`, with the default card |
+| `Site.themeColor()` | `themeColor` |
+| `Site.icons()` | The generated favicons, for the `icons` of a web app manifest |
+
+A translated text returns the text of `locale`, or the first text without `locale`. An option that is not set returns `undefined`.
 
 Import the types from `@mannisto/astro-metadata/runtime`, for example `import type { MetadataImage } from "@mannisto/astro-metadata/runtime"`.
 
 ## Good to know
 
-- **CMS data.** Give CMS values to `<Metadata>` as props. The site values of the integration are fixed at startup, and a change restarts the dev server.
-- **Trailing slash.** The canonical URL and the `hreflang` links follow the `trailingSlash` setting of Astro. With `"ignore"`, `build.format` decides.
+- **CMS data.** Give CMS values to `<Metadata>` as props. The integration reads its site values one time at startup, and a change restarts the dev server.
+- **Trailing slash.** The canonical URL and the `hreflang` links follow the `trailingSlash` option 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.
 
@@ -441,7 +574,10 @@ Version 2 is a new API. The main changes:
 
 ```diff
 - <Head title="About" titleTemplate="%s | My Site" description="..." />
-+ metadata({ titleTemplate: "%s | My Site", description: "..." })
++ metadata({
++   titleTemplate: "%s | My Site",
++   description: "...",
++ })
 ```
 
 ### Use `<Metadata>` inside your own `<head>`
@@ -458,19 +594,18 @@ Version 2 is a new API. The main changes:
 + </head>
 ```
 
-### Replace the removed components
+### Use the new props of the single components
 
-`Title`, `Description`, `Canonical`, `Robots`, `OpenGraph`, `Twitter`, `Favicon`, `LanguageAlternates`, `Keywords` and `Schema` are removed. `<Metadata>` renders their tags.
+The single components take the props of `<Metadata>`, and `<Metadata>` renders all of them. There is no `Keywords` component, because search engines do not use the tag.
 
 ```diff
 - <LanguageAlternates alternates={links} />
-- <Schema schema={data} />
-+ <Metadata hreflang={links} schema={data} />
++ <LanguageAlternates hreflang={links} />
 ```
 
 ### Replace the `Metadata` store
 
-`Metadata.set()` and `Metadata.resolve()` are removed. Give the values as props to your layout.
+v2 has no `Metadata.set()` and `Metadata.resolve()`. Give the values as props to your layout.
 
 ### Replace the robots object and the `false` props
 
@@ -483,7 +618,11 @@ Version 2 is a new API. The main changes:
 
 ```diff
 - <Head favicon={{ icons: [{ path: "/favicon.ico" }] }} />
-+ metadata({ favicon: { source: "./src/assets/logo.svg" } })
++ metadata({
++   favicon: {
++     source: "./src/assets/logo.svg",
++   },
++ })
 ```
 
 ## Contributing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mannisto/astro-metadata",
-  "version": "2.0.0-alpha.5",
-  "description": "Metadata for Astro: page tags, social cards, favicons, the web app manifest and structured data.",
+  "version": "2.0.0",
+  "description": "Metadata for Astro: page tags, social cards, favicons, the web app manifest, structured data and a dev toolbar app that checks your pages.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/eremannisto/astro-metadata#readme",

package/src/components/Canonical.astro

@@ -0,0 +1,10 @@
+---
+import { pageCanonical } from "../lib/page.ts"
+import type { MetadataProps } from "../lib/page.ts"
+
+export type Props = Pick<MetadataProps, "canonical">
+
+const canonical = pageCanonical(Astro, Astro.props)
+---
+
+<link rel="canonical" href={canonical} />

package/src/components/Description.astro

@@ -0,0 +1,10 @@
+---
+import { pageDescription, pageLocale } from "../lib/page.ts"
+import type { MetadataProps } from "../lib/page.ts"
+
+export type Props = Pick<MetadataProps, "description" | "locale">
+
+const description = pageDescription(Astro.props, pageLocale(Astro, Astro.props))
+---
+
+{description && <meta name="description" content={description} />}

package/src/components/Favicon.astro

@@ -0,0 +1,9 @@
+---
+import { Favicon } from "../lib/favicon.ts"
+---
+
+{
+  Favicon.links().map((link) => {
+    return <link rel={link.rel} type={link.type} href={link.href} sizes={link.sizes} />
+  })
+}

package/src/components/Feeds.astro

@@ -0,0 +1,29 @@
+---
+import { getConfig, localize } from "../lib/config.ts"
+import { pageLocale } from "../lib/page.ts"
+import type { MetadataProps } from "../lib/page.ts"
+import { withBase } from "../lib/url.ts"
+
+export type Props = Pick<MetadataProps, "locale">
+
+const locale = pageLocale(Astro, Astro.props)
+
+const FEED_TYPES = {
+  rss: "application/rss+xml",
+  atom: "application/atom+xml",
+  json: "application/feed+json",
+}
+---
+
+{
+  getConfig().feeds?.map((feed) => {
+    return (
+      <link
+        rel="alternate"
+        type={FEED_TYPES[feed.type ?? "rss"]}
+        title={localize(feed.title, locale)}
+        href={withBase(feed.href)}
+      />
+    )
+  })
+}

package/src/components/LanguageAlternates.astro

@@ -0,0 +1,13 @@
+---
+import { pageHreflang } from "../lib/page.ts"
+import type { MetadataProps } from "../lib/page.ts"
+import { pageUrl } from "../lib/url.ts"
+
+export type Props = Pick<MetadataProps, "hreflang">
+---
+
+{
+  pageHreflang(Astro, Astro.props).map((link) => {
+    return <link rel="alternate" hreflang={link.hreflang} href={pageUrl(link.href)} />
+  })
+}

package/src/components/Manifest.astro

@@ -0,0 +1,11 @@
+---
+import { Manifest } from "../lib/manifest.ts"
+import { pageLocale } from "../lib/page.ts"
+import type { MetadataProps } from "../lib/page.ts"
+
+export type Props = Pick<MetadataProps, "locale">
+
+const manifest = Manifest.url(pageLocale(Astro, Astro.props))
+---
+
+{manifest && <link rel="manifest" href={manifest} />}