@hagicode/hagilight 0.14.1-dev.152.1.1b8dd12 → 0.15.1-dev.156.1.05ffbd0

package/README.md

@@ -49,6 +49,64 @@ The values come from `HAGILIGHT_BUILD_BRANCH` and `HAGILIGHT_BUILD_COMMIT`, then
 
 `github.head_ref` is set on pull requests and `github.ref_name` on pushes. A shallow clone still reports its commit, because `git rev-parse HEAD` reads the checkout.
 
+## SEO head
+
+`@hagicode/hagilight/SEOHead` writes the canonical link, the title, description and image tags, and these generated tags. Each appears once, and a tag is left out when its value cannot be determined:
+
+- `og:url` is the canonical URL.
+- `og:type` is `website`, or the `ogType` prop.
+- `og:site_name` is the `siteSeo.title`.
+- `og:locale` comes from the `locale` prop, else `Astro.currentLocale`, in `ll_CC` form: `zh-CN` gives `zh_CN`, `zh-Hant` gives `zh_TW`, and a bare `en` gives `en_US`. A tag with no unambiguous region gets no `og:locale`.
+- `twitter:card` is `summary_large_image` when an image resolves, otherwise `summary`.
+
+It also writes a default `WebSite` and `Organization` JSON-LD block, built from the site title and the site URL with its base path. The `Organization` name defaults to the site title.
+
+```astro
+<SEOHead
+  site={site}
+  siteSeo={{ title: 'Example Docs' }}
+  page={{ url: pageUrl, title, description }}
+  locale="zh-CN"
+  ogType="article"
+  organization={{ name: 'Example Labs', logo: 'https://example.com/logo.png', alternateName: 'EL' }}
+  structuredData={pageStructuredData}
+/>
+```
+
+Your own tags win. A managed tag you pass in `head` keeps your value, and the generated twin is not written. Open Graph and Twitter keys match whether you write them as `property` or `name`, so `<meta name="og:type">` also suppresses the generated `og:type`. A default `WebSite` or `Organization` block is skipped when your `structuredData`, or a `script[type="application/ld+json"]` head entry, declares that `@type` at the top level or inside `@graph`. Unparseable JSON-LD does not stop the page and does not suppress a default block.
+
+To turn the default structured data off, pass `defaultStructuredData={false}`. Your own `structuredData` is still rendered.
+
+### Preview image format
+
+Social crawlers cannot read every image format, so `SEOHead` checks the preview image at build time. The image is `page.image`, or `siteSeo.image` when the page declares none. Its format is read from the extension of its path, ignoring case, query and fragment; the image bytes are not read.
+
+| Format | Extensions | Result |
+| --- | --- | --- |
+| Crawler-compatible | `.jpg`, `.jpeg`, `.png`, `.gif` | Declared exactly as given. Nothing is fetched or re-encoded. |
+| Convertible | `.avif`, `.webp` | A remote `http://` or `https://` image becomes a JPEG at quality 80, written under the build output. The declared address is that file under the site's own origin. |
+| Unrecognised | anything else, such as `.svg` or no extension | Declared exactly as given, with a build warning. |
+
+The output is never larger than 1200×630 and is never enlarged, so a smaller image keeps its size: a 640×400 image stays 640×400, a 1024×768 image becomes 1024×630, and a 1600×1000 image becomes 1200×630.
+
+A convertible image given as a site-root path is not converted. It is declared as given, with the same kind of warning. Pages that share one convertible image share one converted file.
+
+Convertible images on a remote host need that host in the site's own `image.domains` (or `image.remotePatterns`) in its Astro config:
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  image: { domains: ['images.example.com'] },
+});
+```
+
+A failed conversion fails the build. The unconverted image is never declared in its place. The build fails in these cases:
+
+- The host is not permitted: `Hagilight could not convert the SEO image <address>: its host <host> is not permitted. Add <host> to image.domains in the Astro config.`
+- The image cannot be fetched, returns an error status, or cannot be decoded: Astro reports the failure and names the image address.
+
+The build warning reads `Hagilight SEO image <address> was kept as declared: its format was not checked for crawler compatibility.`, or, for a site-root convertible image, `... site-root images are not converted, so its format was not checked for crawler compatibility.`
+
 ## llms.txt
 
 `hagilight()` writes `/llms.txt` after the build, following the [llms.txt](https://llmstxt.org/) layout: the site name as the H1, the home page description as a blockquote summary, and one H2 section of links per top-level path segment. It is generated from the built HTML, so it works for plain Astro and Starlight sites alike and needs no content collection.

package/SEOHead.astro

@@ -1,10 +1,21 @@
 ---
+import { getImage } from 'astro:assets';
 import {
+  buildDefaultStructuredData,
   composeCanonicalSeoHead,
+  composeSocialCardHead,
   resolveSeoMetadata,
   serializeJsonLd,
+  type DefaultOrganizationOptions,
   type HeadEntry,
 } from '@hagicode/hagilight-core/seo';
+import {
+  OG_IMAGE_FORMAT,
+  OG_IMAGE_HEIGHT,
+  OG_IMAGE_QUALITY,
+  OG_IMAGE_WIDTH,
+  classifyOgImage,
+} from '@hagicode/hagilight-core/og-image';
 
 interface Props {
   page?: {
@@ -22,6 +33,10 @@ interface Props {
   basePath?: string;
   head?: HeadEntry[];
   structuredData?: Record<string, unknown> | Record<string, unknown>[];
+  locale?: string;
+  ogType?: string;
+  organization?: DefaultOrganizationOptions;
+  defaultStructuredData?: boolean;
 }
 
 const {
@@ -31,24 +46,91 @@ const {
   basePath = import.meta.env.BASE_URL,
   head = [],
   structuredData = [],
+  locale = Astro.currentLocale,
+  ogType,
+  organization,
+  defaultStructuredData = true,
 } = Astro.props;
 const site = configuredSite?.toString();
 const currentPageUrl = site
   ? new URL(`${Astro.url.pathname}${Astro.url.search}${Astro.url.hash}`, site).href
   : undefined;
+const CONVERTED_IMAGE_OPTIONS = {
+  width: OG_IMAGE_WIDTH,
+  height: OG_IMAGE_HEIGHT,
+  fit: 'cover',
+  format: OG_IMAGE_FORMAT,
+  quality: OG_IMAGE_QUALITY,
+} as const;
+// getImage returns paths that already include the configured base, and resolveSeoImageUrl adds it again.
+const configuredBase = import.meta.env.BASE_URL;
+
+function isAbsoluteHttpUrl(value: string): boolean {
+  return /^https?:\/\//iu.test(value);
+}
+
+function siteRootPath(src: string): string {
+  return src.startsWith(configuredBase) ? `/${src.slice(configuredBase.length)}` : src;
+}
+
+// Only AVIF and WebP are converted. Anything else is kept as declared, and a failed conversion fails the build.
+async function resolveDeclaredImage(reference: string | undefined): Promise<string | undefined> {
+  if (reference === undefined) return undefined;
+  const classification = classifyOgImage(reference);
+  if (classification === 'compatible') return reference;
+  if (classification === 'unrecognised') {
+    console.warn(`Hagilight SEO image ${reference} was kept as declared: its format was not checked for crawler compatibility.`);
+    return reference;
+  }
+  if (!isAbsoluteHttpUrl(reference)) {
+    console.warn(`Hagilight SEO image ${reference} was kept as declared: site-root images are not converted, so its format was not checked for crawler compatibility.`);
+    return reference;
+  }
+  let image: { src: string };
+  try {
+    image = await getImage({ ...CONVERTED_IMAGE_OPTIONS, src: reference });
+  } catch (error) {
+    throw new Error(`Hagilight could not convert the SEO image ${reference}: ${(error as Error).message}`, { cause: error });
+  }
+  // Astro returns the remote address unchanged, without an error, when the host is not in image.domains.
+  if (isAbsoluteHttpUrl(image.src)) {
+    const host = new URL(reference).hostname;
+    throw new Error(`Hagilight could not convert the SEO image ${reference}: its host ${host} is not permitted. Add ${host} to image.domains in the Astro config.`);
+  }
+  return siteRootPath(image.src);
+}
+
+const declaredImage = await resolveDeclaredImage(page.image ?? siteSeo.image);
 const metadata = {
-  ...resolveSeoMetadata({ pageSeo: page, siteSeo, site, basePath }),
+  ...resolveSeoMetadata({ pageSeo: { ...page, image: declaredImage }, siteSeo, site, basePath }),
   site,
 };
 const canonicalUrl = page.url?.toString() ?? currentPageUrl;
-const composedHead = composeCanonicalSeoHead(head, metadata, {
+const canonicalHead = composeCanonicalSeoHead(head, metadata, {
   canonicalUrl,
   explicitHead: [head],
 });
+const canonicalLink = canonicalHead.find(({ tag, attrs }) => tag === 'link' && attrs?.rel === 'canonical');
+const composedHead = composeSocialCardHead(canonicalHead, {
+  url: typeof canonicalLink?.attrs?.href === 'string' ? canonicalLink.attrs.href : undefined,
+  type: ogType,
+  siteName: siteSeo.title,
+  locale,
+  image: metadata.image,
+}, [head]);
 const dataValues = Array.isArray(structuredData) ? structuredData : [structuredData];
+const defaultValues = buildDefaultStructuredData({
+  siteName: siteSeo.title,
+  site,
+  basePath,
+  enabled: defaultStructuredData,
+  organization,
+  structuredData: dataValues,
+  head,
+});
 ---
 
 {composedHead.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
-{dataValues.map((value) => (
+{[...defaultValues, ...dataValues].map((value) => (
   <script type="application/ld+json" set:html={serializeJsonLd(value)} />
 ))}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.14.1-dev.152.1.1b8dd12",
+  "version": "0.15.1-dev.156.1.05ffbd0",
   "type": "module",
   "description": "Astro integrations and components for HagiCode sites",
   "repository": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.4",
-    "@hagicode/hagilight-core": "0.14.1-dev.152.1.1b8dd12"
+    "@hagicode/hagilight-core": "0.15.1-dev.156.1.05ffbd0"
   },
   "keywords": [
     "hagicode",