head.mjs

Functions

Imports

It imports xml.mjs. Imported by audit.mjs, schema.mjs.

Source

1import { escapeXml, toDate } from "./xml.mjs";
2
3/**
4 * Google truncates by pixel width (about 600px title, 920px description), so these approximate it; a 160-character counter
5 * would show text the result clips.
6 */
7export const SERP_TITLE_LIMIT = 60;
8export const SERP_DESCRIPTION_LIMIT = 155;
9
10/**
11 * @typedef {{ title: string }
12 *   | { name: string, content: string }
13 *   | { property: string, content: string }
14 *   | { tagName: "link", rel: string, href: string }
15 *   | { "script:ld+json": Record<string, unknown> }} HeadTag
16 * The descriptor shapes React Router's `meta` export takes, so a route returns `headTags(...)` as it is.
17 */
18
19/**
20 * @typedef {object} HeadImage
21 * @property {string} url absolute, or a path on `origin`
22 * @property {number} [width]
23 * @property {number} [height]
24 * @property {string} [alt]
25 */
26
27/**
28 * @typedef {object} ArticleFacts
29 * @property {Date | number | string | null} [published]
30 * @property {Date | number | string | null} [modified] falls back to `published`
31 * @property {string} [author]
32 * @property {string[]} [tags]
33 */
34
35/**
36 * @typedef {object} HeadInput
37 * @property {string} origin the site's production origin, never the request's: a workers.dev copy must not claim to be the page
38 * @property {string} path
39 * @property {string} title the `<title>`, with any site suffix already on it
40 * @property {string} description
41 * @property {HeadImage | string} image the page's card, or the site's default: a card is always sent
42 * @property {string} [siteName]
43 * @property {string} [socialTitle] `og:title` and `twitter:title`, where they differ from `title`
44 * @property {string} [socialDescription]
45 * @property {"website" | "article" | "book" | "profile"} [type]
46 * @property {string} [canonical] an absolute URL, where it is not `origin` + `path`
47 * @property {string} [locale] e.g. `en_US`
48 * @property {boolean} [noindex]
49 * @property {ArticleFacts} [article] `article:*` tags; pass the same facts to the schema's `article` so the two agree
50 */
51
52/**
53 * The full head of a public page: title, description, canonical, Open Graph and Twitter. `twitter:card` is always
54 * `summary_large_image`, because the image is required: a card without one renders as a bare link. An absent date writes no
55 * tag, since an empty `article:published_time` claims there is no date.
56 *
57 * @param {HeadInput} input
58 * @returns {HeadTag[]}
59 */
60export function headTags(input) {
61  const { origin, path, title, description, siteName, type = "website", locale, noindex, article } = input;
62  const url = input.canonical ?? absoluteUrl(origin, path);
63  const image = typeof input.image === "string" ? { url: input.image } : input.image;
64  const imageUrl = absoluteUrl(origin, image.url);
65  const socialTitle = input.socialTitle ?? title;
66  const socialDescription = input.socialDescription ?? description;
67
68  /** @type {HeadTag[]} */
69  const tags = [
70    { title },
71    { name: "description", content: description },
72    { tagName: "link", rel: "canonical", href: url },
73  ];
74  if (noindex) tags.push({ name: "robots", content: "noindex, follow" });
75  if (siteName) tags.push({ property: "og:site_name", content: siteName });
76  tags.push(
77    { property: "og:type", content: type },
78    { property: "og:title", content: socialTitle },
79    { property: "og:description", content: socialDescription },
80    { property: "og:url", content: url },
81  );
82  if (locale) tags.push({ property: "og:locale", content: locale });
83  tags.push({ property: "og:image", content: imageUrl });
84  if (image.width) tags.push({ property: "og:image:width", content: String(image.width) });
85  if (image.height) tags.push({ property: "og:image:height", content: String(image.height) });
86  if (image.alt) tags.push({ property: "og:image:alt", content: image.alt });
87  if (article) tags.push(...articleTags(article));
88  tags.push(
89    { name: "twitter:card", content: "summary_large_image" },
90    { name: "twitter:title", content: socialTitle },
91    { name: "twitter:description", content: socialDescription },
92    { name: "twitter:image", content: imageUrl },
93  );
94  if (image.alt) tags.push({ name: "twitter:image:alt", content: image.alt });
95  return tags;
96}
97
98/** @param {ArticleFacts} article @returns {HeadTag[]} */
99function articleTags(article) {
100  const { published, modified } = articleDates(article);
101  /** @type {HeadTag[]} */
102  const tags = [];
103  if (published) tags.push({ property: "article:published_time", content: published });
104  if (modified) tags.push({ property: "article:modified_time", content: modified });
105  if (article.author) tags.push({ property: "article:author", content: article.author });
106  for (const tag of article.tags ?? []) tags.push({ property: "article:tag", content: tag });
107  return tags;
108}
109
110/**
111 * The ISO dates both the Open Graph tags and the Article schema write, so the two cannot disagree. A missing or unreadable
112 * date is undefined.
113 *
114 * @param {ArticleFacts} article
115 * @returns {{ published: string | undefined, modified: string | undefined }}
116 */
117export function articleDates(article) {
118  const published = iso(article.published);
119  return { published, modified: iso(article.modified) ?? published };
120}
121
122/** @param {Date | number | string | null | undefined} value */
123function iso(value) {
124  if (value === null || value === undefined) return undefined;
125  const date = toDate(value, null);
126  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
127}
128
129/**
130 * A path on `origin` made absolute; an absolute URL is kept as it is.
131 *
132 * @param {string} origin
133 * @param {string} path
134 */
135export function absoluteUrl(origin, path) {
136  if (/^https?:\/\//.test(path)) return path;
137  return `${origin.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
138}
139
140/**
141 * The tags as HTML, for a page built without React Router (a static build). Attribute values are escaped, and `<` inside
142 * JSON-LD is written `\u003c`, so a title holding `</script>` cannot end the script element.
143 *
144 * @param {HeadTag[]} tags
145 * @returns {string}
146 */
147export function headHtml(tags) {
148  return tags
149    .map((tag) => {
150      if ("title" in tag) return `<title>${escapeXml(tag.title)}</title>`;
151      if ("script:ld+json" in tag) {
152        return `<script type="application/ld+json">${JSON.stringify(tag["script:ld+json"]).replace(/</g, "\\u003c")}</script>`;
153      }
154      if ("tagName" in tag) return `<link rel="${escapeXml(tag.rel)}" href="${escapeXml(tag.href)}">`;
155      const [key, value] = "property" in tag ? ["property", tag.property] : ["name", tag.name];
156      return `<meta ${key}="${escapeXml(value)}" content="${escapeXml(tag.content)}">`;
157    })
158    .join("\n");
159}
160
161/**
162 * Cut at a word boundary near `limit` and mark the cut, for a title or description shown where Google's result would clip it.
163 *
164 * @param {string} text
165 * @param {number} limit
166 */
167export function truncateForSerp(text, limit) {
168  if (text.length <= limit) return text;
169  const cut = text.slice(0, limit);
170  const lastSpace = cut.lastIndexOf(" ");
171  return `${(lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd()}...`;
172}