npm - @mannisto/astro-metadata - Versions diffs - 1.0.0-beta.3 → 1.0.0-beta.5 - Mend

@mannisto/astro-metadata 1.0.0-beta.3 → 1.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +46 -408
package/package.json +1 -1
package/src/components/Head.astro +47 -55
package/src/lib/metadata.ts +3 -0

package/README.md CHANGED Viewed

@@ -8,30 +8,7 @@
 Astro components for managing your page head — metadata, social sharing, favicons, and SEO.
-## Table of contents
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Head component](#1-head-component)
-  - [Individual components](#2-individual-components)
-  - [Metadata utility](#3-metadata-utility)
-- [Components](#components)
-  - [Canonical](#canonical)
-  - [Description](#description)
-  - [Favicon](#favicon)
-  - [Head](#head)
-  - [Keywords](#keywords)
-  - [LanguageAlternates](#languagealternates)
-  - [OpenGraph](#opengraph)
-  - [Robots](#robots)
-  - [Schema](#schema)
-  - [Title](#title)
-  - [Twitter](#twitter)
-- [Contributing](#contributing)
-- [License](#license)
 ## Installation
 ```bash
 # pnpm
 pnpm add @mannisto/astro-metadata
@@ -47,104 +24,43 @@ yarn add @mannisto/astro-metadata
 There are three ways to use this package. Pick what suits your project, or combine them freely.
-### 1. Head component
-The simplest approach. Use `Head` in your layout and pass props down from your pages. Charset and viewport are included automatically.
+### Head component
+The simplest approach — use `Head` in your layout and pass props down from pages. Title, description and image flow into Open Graph and Twitter automatically.
 ```astro
 ---
-// layouts/Layout.astro
 import { Head } from "@mannisto/astro-metadata"
-import type { HeadProps } from "@mannisto/astro-metadata"
-interface Props extends HeadProps {}
-const { title, description, ...rest } = Astro.props
 ---
 <html>
-  <Head title={title} description={description} titleTemplate="%s | My Site" {...rest} />
+  <Head
+    title="Home"
+    titleTemplate="%s | My Site"
+    description="Welcome to my site"
+    image={{ url: "/og.jpg", alt: "My Site", width: 1200, height: 630 }}
+  />
   <body>
     <slot />
   </body>
 </html>
 ```
-```astro
----
-// pages/index.astro
-import Layout from "../layouts/Layout.astro"
----
-<Layout title="Home" description="Welcome to my site">
-  <h1>Hello</h1>
-</Layout>
-```
-Best for simple sites where pages pass metadata as props to their layout.
+[Read more →](docs/usage/head.md)
-### 2. Individual components
-Use components directly inside your own `<head>`. Useful when you only need specific pieces, or want full control over the structure.
-```astro
----
-import { Title, Description, OpenGraph, Favicon } from "@mannisto/astro-metadata"
----
-<html>
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <Title value="My Page" template="%s | My Site" />
-    <Description value="Welcome to my site" />
-    <OpenGraph
-      title="My Page"
-      description="Welcome to my site"
-      image={{
-        url: "/og.jpg",
-        alt: "My Site",
-        width: 1200,
-        height: 630,
-      }}
-    />
-    <Favicon icons={[{ path: "/favicon.ico" }, { path: "/favicon.svg" }]} />
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
-Best for when you want to compose only what you need, or when `Head` is too opinionated for your setup.
-### 3. Metadata utility
-Set metadata in your page, resolve it in your layout. Eliminates prop drilling through nested layout layers.
+### Metadata API
+Set metadata in pages, resolve in layouts — no prop drilling.
 ```astro
 ---
 // pages/about.astro
 import { Metadata } from "@mannisto/astro-metadata"
-import Layout from "../layouts/Layout.astro"
 Metadata.set({
   title: "About",
   description: "Learn more about us",
-  openGraph: {
-    image: {
-      url: "/og/about.jpg",
-      alt: "About",
-    },
-  },
 })
 ---
-<Layout>
-  <h1>About</h1>
-</Layout>
 ```
 ```astro
 ---
 // layouts/Layout.astro
@@ -152,7 +68,6 @@ import { Head, Metadata } from "@mannisto/astro-metadata"
 const meta = Metadata.resolve({
   title: "My Site",
-  description: "Default description",
   titleTemplate: "%s | My Site",
 })
 ---
@@ -165,329 +80,52 @@ const meta = Metadata.resolve({
 </html>
 ```
-`Metadata.resolve()` merges page values over your layout defaults — whatever the page sets wins, everything else falls back gracefully.
-Best for sites with deeply nested layouts, or when you want to keep metadata co-located with page content.
-## Components
-### Canonical
+[Read more →](docs/usage/metadata.md)
-Renders a canonical link tag. Falls back to `Astro.url.href` when no value is provided, so every page gets a canonical tag with zero configuration.
+### Individual components
+Use components directly in your `<head>` for full control.
 ```astro
-<Canonical value="https://example.com/page" />
-```
-| Prop    | Type     | Description                                  |
-| ------- | -------- | -------------------------------------------- |
-| `value` | `string` | Canonical URL. Defaults to `Astro.url.href`. |
-### Description
-```astro
-<Description value="Welcome to my site" />
-```
-| Prop    | Type     | Description      |
-| ------- | -------- | ---------------- |
-| `value` | `string` | Page description |
-### Favicon
-Favicon support with light and dark mode variants, automatic MIME type detection, and automatic sorting.
-```astro
-<Favicon
-  icons={[
-    { path: "/favicon.ico" },
-    { path: "/favicon.svg" },
-    { path: "/favicon-96x96.png", size: 96 },
-    { path: "/apple-touch-icon.png", size: 180, apple: true },
-    { path: "/favicon-dark.svg", theme: "dark" },
-    { path: "/favicon-light.svg", theme: "light" },
-  ]}
-  manifest="/site.webmanifest"
-/>
-```
-Icons are automatically sorted in the recommended browser order: `ico` → `png` → `svg` → `apple` → themed variants. Pass `sort={false}` to preserve the original order.
-| Prop       | Type            | Default | Description                             |
-| ---------- | --------------- | ------- | --------------------------------------- |
-| `icons`    | `FaviconFile[]` | —       | List of favicon files                   |
-| `manifest` | `string`        | —       | Path to web app manifest                |
-| `sort`     | `boolean`       | `true`  | Sort icons in recommended browser order |
-#### FaviconFile
-| Prop    | Type                | Description                                                 |
-| ------- | ------------------- | ----------------------------------------------------------- |
-| `path`  | `string`            | Path to the file. MIME type is detected automatically.      |
-| `size`  | `number`            | Size in pixels. Rendered as `NxN` in the `sizes` attribute. |
-| `theme` | `"light" \| "dark"` | Adds a `prefers-color-scheme` media query                   |
-| `apple` | `boolean`           | Renders as `<link rel="apple-touch-icon">`                  |
-### Head
-Wraps the entire page head and composes all sub-components internally. Charset and viewport are always included and can be overridden if needed.
-```astro
-<Head
-  title="Home"
-  titleTemplate="%s | My Site"
-  description="Welcome to my site"
-  openGraph={{
-    image: {
-      url: "/og.jpg",
-      alt: "My Site",
-      width: 1200,
-      height: 630,
-    },
-  }}
-  favicon={{
-    icons: [{ path: "/favicon.ico" }, { path: "/favicon.svg" }],
-  }}
-/>
-```
-| Prop                 | Type                         | Default                                   | Description                                               |
-| -------------------- | ---------------------------- | ----------------------------------------- | --------------------------------------------------------- |
-| `title`              | `string`                     | —                                         | Page title. Required.                                     |
-| `titleTemplate`      | `` `${string}%s${string}` `` | —                                         | Title template. Must contain `%s`, e.g. `"%s \| My Site"` |
-| `description`        | `string`                     | —                                         | Page description                                          |
-| `canonical`          | `string`                     | `Astro.url.href`                          | Canonical URL                                             |
-| `keywords`           | `string[]`                   | —                                         | List of keywords                                          |
-| `charset`            | `string`                     | `"UTF-8"`                                 | Document charset                                          |
-| `viewport`           | `string`                     | `"width=device-width, initial-scale=1.0"` | Viewport meta content                                     |
-| `robots`             | `RobotsProps`                | —                                         | Robots directives                                         |
-| `openGraph`          | `OpenGraphProps`             | —                                         | Open Graph tags                                           |
-| `twitter`            | `TwitterProps`               | —                                         | Twitter card tags                                         |
-| `favicon`            | `FaviconProps`               | —                                         | Favicon configuration                                     |
-| `schema`             | `SchemaProps`                | —                                         | JSON-LD structured data                                   |
-| `languageAlternates` | `LanguageAlternate[]`        | —                                         | Hreflang alternate links                                  |
-#### Slots
-```astro
-<Head title="My Site">
-  <!-- Renders before charset and viewport -->
-  <meta slot="top" http-equiv="X-UA-Compatible" content="IE=edge" />
-  <!-- Renders at the end of <head> -->
-  <script src={analyticsUrl}></script>
-</Head>
-```
-### Keywords
-```astro
-<Keywords value={["astro", "seo", "metadata"]} />
-```
-| Prop    | Type       | Description      |
-| ------- | ---------- | ---------------- |
-| `value` | `string[]` | List of keywords |
-### LanguageAlternates
-Renders `<link rel="alternate" hreflang>` tags for multilingual sites. Tells search engines which language version to serve for a given region.
-```astro
-<LanguageAlternates
-  alternates={[
-    { href: "https://example.com/en", hreflang: "en" },
-    { href: "https://example.com/fi", hreflang: "fi" },
-    { href: "https://example.com", hreflang: "x-default" },
-  ]}
-/>
-```
-| Prop                    | Type                  | Description                                                    |
-| ----------------------- | --------------------- | -------------------------------------------------------------- |
-| `alternates`            | `LanguageAlternate[]` | List of alternate language pages                               |
-| `alternates[].href`     | `string`              | Full URL of the alternate page                                 |
-| `alternates[].hreflang` | `string`              | Language or region code, e.g. `en`, `fi`, `en-US`, `x-default` |
-### OpenGraph
-Renders Open Graph meta tags for rich previews when your pages are shared on social platforms. When used inside `Head`, `title`, `description` and `url` fall back to the page values automatically.
-```astro
-<OpenGraph
-  title="My Page"
-  description="Welcome to my site"
-  url="https://example.com"
-  type="website"
-  siteName="My Site"
-  locale="en_US"
-  localeAlternate={["fi_FI", "fr_FR"]}
-  image={{
-    url: "/og.jpg",
-    secureUrl: "https://example.com/og.jpg",
-    type: "image/jpeg",
-    alt: "My Site",
-    width: 1200,
-    height: 630,
-  }}
-  video={{
-    url: "https://example.com/video.mp4",
-    secureUrl: "https://example.com/video.mp4",
-    type: "video/mp4",
-    width: 1280,
-    height: 720,
-  }}
-  audio={{
-    url: "https://example.com/audio.mp3",
-    secureUrl: "https://example.com/audio.mp3",
-    type: "audio/mpeg",
-  }}
-/>
-```
-| Prop              | Type             | Default     | Description                                  |
-| ----------------- | ---------------- | ----------- | -------------------------------------------- |
-| `title`           | `string`         | —           | OG title                                     |
-| `description`     | `string`         | —           | OG description                               |
-| `url`             | `string`         | —           | Canonical URL for the OG object              |
-| `type`            | `string`         | `"website"` | OG type                                      |
-| `siteName`        | `string`         | —           | Name of the site                             |
-| `locale`          | `string`         | —           | Locale, e.g. `en_US`                         |
-| `localeAlternate` | `string[]`       | —           | Alternate locales, e.g. `["fi_FI", "fr_FR"]` |
-| `image`           | `OpenGraphImage` | —           | Image metadata                               |
-| `video`           | `OpenGraphVideo` | —           | Video metadata                               |
-| `audio`           | `OpenGraphAudio` | —           | Audio metadata                               |
-#### OpenGraphImage
-| Prop        | Type     | Description                                |
-| ----------- | -------- | ------------------------------------------ |
-| `url`       | `string` | Image URL. Required if image is set.       |
-| `secureUrl` | `string` | HTTPS image URL                            |
-| `type`      | `string` | MIME type, e.g. `"image/jpeg"`             |
-| `alt`       | `string` | Image alt text                             |
-| `width`     | `number` | Image width in pixels. Recommended: `1200` |
-| `height`    | `number` | Image height in pixels. Recommended: `630` |
-#### OpenGraphVideo
-| Prop        | Type     | Description                          |
-| ----------- | -------- | ------------------------------------ |
-| `url`       | `string` | Video URL. Required if video is set. |
-| `secureUrl` | `string` | HTTPS video URL                      |
-| `type`      | `string` | MIME type, e.g. `"video/mp4"`        |
-| `width`     | `number` | Video width in pixels                |
-| `height`    | `number` | Video height in pixels               |
-#### OpenGraphAudio
-| Prop        | Type     | Description                          |
-| ----------- | -------- | ------------------------------------ |
-| `url`       | `string` | Audio URL. Required if audio is set. |
-| `secureUrl` | `string` | HTTPS audio URL                      |
-| `type`      | `string` | MIME type, e.g. `"audio/mpeg"`       |
-### Robots
-Controls how search engines crawl and index your page. Defaults to `index, follow`.
-```astro
-<Robots archive={false} extra="max-snippet:-1, max-image-preview:large, max-video-preview:-1" />
-```
-| Prop      | Type      | Default | Description                                                             |
-| --------- | --------- | ------- | ----------------------------------------------------------------------- |
-| `index`   | `boolean` | `true`  | Allow indexing                                                          |
-| `follow`  | `boolean` | `true`  | Allow following links                                                   |
-| `archive` | `boolean` | `true`  | Allow search engines to cache the page                                  |
-| `snippet` | `boolean` | `true`  | Allow text snippets in search results                                   |
-| `extra`   | `string`  | —       | Additional directives, e.g. `"max-snippet:-1, max-image-preview:large"` |
-### Schema
-Outputs a `<script type="application/ld+json">` tag for structured data. Use it to help search engines understand your content and qualify for rich results.
-```astro
-<Schema
-  schema={{
-    "@context": "https://schema.org",
-    "@type": "Person",
-    name: "Ere Männistö",
-    url: "https://example.com",
-  }}
-/>
-```
-| Prop     | Type                      | Description    |
-| -------- | ------------------------- | -------------- |
-| `schema` | `Record<string, unknown>` | JSON-LD object |
-### Title
-Renders the `<title>` tag. The template must contain `%s`, which is replaced with the page title — TypeScript enforces this at the type level.
+---
+import { Title, Description, OpenGraph } from "@mannisto/astro-metadata"
+---
-```astro
-<Title value="My Page" template="%s | My Site" />
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <Title value="My Page" template="%s | My Site" />
+    <Description value="Welcome to my site" />
+    <OpenGraph
+      title="My Page"
+      image={{ url: "/og.jpg", alt: "My Site" }}
+    />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
 ```
-| Prop       | Type                         | Description                         |
-| ---------- | ---------------------------- | ----------------------------------- |
-| `value`    | `string`                     | Page title. Required.               |
-| `template` | `` `${string}%s${string}` `` | Template string. Must contain `%s`. |
-### Twitter
+[Read more →](docs/usage/components.md)
-Renders Twitter card meta tags for rich previews on X. When used inside `Head`, `title` and `description` fall back to the page values automatically.
-```astro
-<Twitter
-  card="summary_large_image"
-  site="@mysite"
-  creator="@myhandle"
-  url="https://example.com"
-  image={{
-    url: "/og.jpg",
-    alt: "My Site",
-  }}
-/>
-```
+## Components
-| Prop          | Type                                                      | Default                 | Description                                |
-| ------------- | --------------------------------------------------------- | ----------------------- | ------------------------------------------ |
-| `title`       | `string`                                                  | —                       | Card title                                 |
-| `description` | `string`                                                  | —                       | Card description                           |
-| `url`         | `string`                                                  | —                       | Canonical URL for the card                 |
-| `card`        | `"summary" \| "summary_large_image" \| "player" \| "app"` | `"summary_large_image"` | Card type                                  |
-| `site`        | `string`                                                  | —                       | Twitter handle of the site, e.g. `@mysite` |
-| `creator`     | `string`                                                  | —                       | Twitter handle of the content author       |
-| `image.url`   | `string`                                                  | —                       | Image URL. Required if image is set.       |
-| `image.alt`   | `string`                                                  | —                       | Image alt text                             |
+- [Canonical](docs/components/canonical.md)
+- [Description](docs/components/description.md)
+- [Favicon](docs/components/favicon.md)
+- [Head](docs/components/head.md)
+- [Keywords](docs/components/keywords.md)
+- [LanguageAlternates](docs/components/language-alternates.md)
+- [OpenGraph](docs/components/open-graph.md)
+- [Robots](docs/components/robots.md)
+- [Schema](docs/components/schema.md)
+- [Title](docs/components/title.md)
+- [Twitter](docs/components/twitter.md)
 ## Contributing
-Clone the repo and run `pnpm run init` to install dependencies, link the local package to the fixture project, and set up Playwright. Then use `pnpm test:unit`, `pnpm test:e2e`, or `pnpm test:all` to run tests, and `pnpm check` / `pnpm format` for linting and formatting. All PRs must pass `pnpm check` — enforced via GitHub Actions.
-### Project structure
-```
-astro-metadata/
-  src/
-    components/
-    lib/
-  tests/
-    e2e/
-      components/
-      fixtures/
-    unit/
-      metadata.test.ts
-  scripts/
-    init.sh
-  index.ts
-  playwright.config.ts
-  vitest.config.ts
-  biome.json
-  prettier.config.ts
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and contribution guidelines.
 ## License

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mannisto/astro-metadata",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "Astro components for managing your page head — metadata, social sharing, favicons, and SEO.",
   "license": "MIT",
   "type": "module",

package/src/components/Head.astro CHANGED Viewed

@@ -10,21 +10,23 @@ import Twitter from "./Twitter.astro"
 import Favicon from "./Favicon.astro"
 import Schema from "./Schema.astro"
 import LanguageAlternates from "./LanguageAlternates.astro"
+import type { OpenGraphImage } from "./OpenGraph.astro"
 export type Props = {
   title: string
   titleTemplate?: `${string}%s${string}`
-  description?: string
-  canonical?: string
-  keywords?: string[]
+  description?: string | false
+  canonical?: string | false
+  keywords?: string[] | false
   charset?: string
   viewport?: string
-  robots?: ComponentProps<typeof Robots>
-  openGraph?: ComponentProps<typeof OpenGraph>
-  twitter?: ComponentProps<typeof Twitter>
-  favicon?: ComponentProps<typeof Favicon>
-  schema?: ComponentProps<typeof Schema>
-  languageAlternates?: ComponentProps<typeof LanguageAlternates>["alternates"]
+  image?: OpenGraphImage | false
+  robots?: ComponentProps<typeof Robots> | false
+  openGraph?: ComponentProps<typeof OpenGraph> | false
+  twitter?: ComponentProps<typeof Twitter> | false
+  favicon?: ComponentProps<typeof Favicon> | false
+  schema?: ComponentProps<typeof Schema> | false
+  languageAlternates?: ComponentProps<typeof LanguageAlternates>["alternates"] | false
 }
 const {
@@ -35,6 +37,7 @@ const {
   keywords,
   charset = "UTF-8",
   viewport = "width=device-width, initial-scale=1.0",
+  image,
   robots,
   openGraph,
   twitter,
@@ -42,6 +45,32 @@ const {
   schema,
   languageAlternates,
 } = Astro.props
+const enabled = <T,>(value: T | false | undefined): value is T => {
+  return value !== false && value !== undefined
+}
+const og =
+  openGraph !== false
+    ? {
+        title,
+        description: enabled(description) ? description : undefined,
+        image: enabled(image) ? image : undefined,
+        url: enabled(canonical) ? canonical : undefined,
+        ...openGraph,
+      }
+    : false
+const tw =
+  twitter !== false
+    ? {
+        title,
+        description: enabled(description) ? description : undefined,
+        image: enabled(image) ? image : undefined,
+        url: enabled(canonical) ? canonical : undefined,
+        ...twitter,
+      }
+    : false
 ---
 <head>
@@ -51,53 +80,16 @@ const {
   <meta name="viewport" content={viewport} />
   <Title value={title} template={titleTemplate} />
-  <Description value={description} />
-  <Canonical value={canonical} />
-  <Keywords value={keywords} />
-  <Robots
-    index={robots?.index}
-    follow={robots?.follow}
-    archive={robots?.archive}
-    snippet={robots?.snippet}
-    extra={robots?.extra}
-  />
-  {languageAlternates && <LanguageAlternates alternates={languageAlternates} />}
-  {
-    openGraph && (
-      <OpenGraph
-        title={openGraph.title ?? title}
-        description={openGraph.description ?? description}
-        url={openGraph.url ?? canonical}
-        type={openGraph.type}
-        siteName={openGraph.siteName}
-        locale={openGraph.locale}
-        localeAlternate={openGraph.localeAlternate}
-        image={openGraph.image}
-        video={openGraph.video}
-        audio={openGraph.audio}
-      />
-    )
-  }
-  {
-    twitter && (
-      <Twitter
-        title={twitter.title ?? title}
-        description={twitter.description ?? description}
-        image={twitter.image}
-        card={twitter.card}
-        site={twitter.site}
-        creator={twitter.creator}
-        url={twitter.url ?? canonical}
-      />
-    )
-  }
-  {favicon && <Favicon icons={favicon.icons} manifest={favicon.manifest} sort={favicon.sort} />}
-  {schema && <Schema schema={schema.schema} />}
+  {enabled(description) && <Description value={description} />}
+  {enabled(canonical) && <Canonical value={canonical} />}
+  {enabled(keywords) && <Keywords value={keywords} />}
+  {enabled(robots) && <Robots {...robots} />}
+  {enabled(og) && <OpenGraph {...og} />}
+  {enabled(tw) && <Twitter {...tw} />}
+  {enabled(favicon) && <Favicon {...favicon} />}
+  {enabled(schema) && <Schema {...schema} />}
+  {enabled(languageAlternates) && <LanguageAlternates alternates={languageAlternates} />}
   <slot />
 </head>

package/src/lib/metadata.ts CHANGED Viewed

@@ -52,6 +52,9 @@ export const Metadata = {
   get keywords() {
     return store.keywords
   },
+  get image() {
+    return store.image
+  },
   get robots() {
     return store.robots
   },