app/lib/seo-checks.ts

Functions

Imports

It imports app/lib/legal.ts. Imported by app/components/editor/search-sharing.tsx, app/lib/seo.server.ts, app/routes/editor.tsx.

Source

1// The search and sharing checks on a post's text, and the link card it will make: the title a search
2// result shows, the description under it, images in the body with no alt text, and a post with no card
3// image. They flag; the writer decides, and nothing here holds a save or a publish. Pure, so the editor
4// runs them as Dustin types and the MCP tools run the same code on a draft.
5//
6// The limits are Prelum's (@drdustinedwards/site-helpers/head), the numbers the sites' own head tags and
7// site audit use, so a draft is held to what the published page is measured against. Prelum sets no
8// floor for a description; DESCRIPTION_MIN is Carrel's.
9//
10// Each site names these fields differently, so SOCIAL_FIELDS holds one entry per site, as FIGURES in
11// site-markdown.ts does: shared by the server and the browser.
12
13import { SERP_DESCRIPTION_LIMIT, SERP_TITLE_LIMIT, truncateForSerp } from "@drdustinedwards/site-helpers/head";
14import { readKey, splitSource } from "@dustinedwards/site-api/frontmatter";
15
16import { legalTypeOf } from "~/lib/legal";
17
18/** Under this many characters a description says too little for a result to show it; a search engine writes its own. */
19const DESCRIPTION_MIN = 50;
20
21type SocialFields = {
22  /** The keys the search title is read from, the first with a value winning. */
23  title: readonly string[];
24  /** What the site adds to the title in a search result, in its own words. */
25  titleSuffix?: string;
26  /** The keys of the title on a link card; the search title's keys when absent. */
27  cardTitle?: readonly string[];
28  description: readonly string[];
29  cardDescription?: readonly string[];
30  /** The card image's key (`cover.src` is `src` under `cover:`); null for a site with no per-post image. */
31  image: string | null;
32};
33
34const SOCIAL_FIELDS: Record<string, SocialFields> = {
35  // dustinedwards-info app/lib/seo.ts postSocial: the page title is "<title> | Dustin Edwards", the card
36  // takes og_title and og_description over them, and the image is the cover, else the site mark.
37  dustinedwards: {
38    title: ["title"],
39    titleSuffix: " | Dustin Edwards",
40    cardTitle: ["og_title", "title"],
41    description: ["description"],
42    cardDescription: ["og_description", "description"],
43    image: "cover.src",
44  },
45  // germomics app/lib/carrel/source.ts: seoTitle and seoDescription over title and excerpt.
46  germomics: { title: ["seoTitle", "title"], description: ["seoDescription", "excerpt"], image: "coverImage" },
47  // foxhound app/lib/carrel/source.ts: no image field.
48  foxhound: { title: ["title"], description: ["excerpt"], image: null },
49  // foxing apps/web/app/lib/carrel/journal-source.ts.
50  foxing: { title: ["title"], description: ["excerpt"], image: "cover_image_url" },
51};
52
53const DEFAULT_FIELDS: SocialFields = { title: ["title"], description: ["description", "excerpt"], image: null };
54
55export type SeoFinding = {
56  check: "title" | "description" | "image-alt" | "card-image";
57  message: string;
58  /** The words concerned, when there are any to quote. */
59  excerpt: string | null;
60  /** The source line, for an image in the body. */
61  line: number | null;
62};
63
64/** What a shared link and a search result will show, as far as the post's own text decides it. */
65export type SocialPreview = {
66  /** The search result's title and description, cut where a result clips them. */
67  search: { title: string; description: string };
68  card: { title: string; description: string; image: string | null };
69  /** The site's host name, for a preview with no address yet. */
70  host: string | null;
71  /** The address the site publishes the post at; null until it has one. */
72  url: string | null;
73};
74
75export type SeoCheck = { findings: SeoFinding[]; preview: SocialPreview };
76
77/** A JSON-source site writes `null` for an empty field. */
78function value(front: string | null, key: string): string {
79  const [parent, child] = key.split(".");
80  let raw: string;
81  if (child) {
82    // A nested key: `child:` indented under `parent:`, as dustinedwards.info writes its cover.
83    const block = new RegExp(`^${parent}:[ \\t]*\\r?\\n((?:[ \\t]+.*(?:\\r?\\n|$))*)`, "m").exec(front ?? "");
84    const line = block?.[1]!.split(/\r?\n/).find((l) => new RegExp(`^\\s+${child}:`).test(l));
85    raw = line ? readKey(line.trim(), child) : "";
86  } else {
87    raw = readKey(front, key);
88  }
89  const v = raw.trim();
90  return v === "null" || v === "~" ? "" : v;
91}
92
93function first(front: string | null, keys: readonly string[]): string {
94  for (const key of keys) {
95    const v = value(front, key);
96    if (v) return v;
97  }
98  return "";
99}
100
101const plural = (n: number) => `${n} character${n === 1 ? "" : "s"}`;
102
103/** Each image in a body with no alt text, or an empty one: Markdown, HTML and a `:::figure` directive. Code is skipped. */
104function imagesWithoutAlt(source: string): { excerpt: string; line: number }[] {
105  const text = source.replace(/\r\n/g, "\n");
106  const { body } = splitSource(text);
107  const startLine = text.slice(0, text.length - body.length).split("\n").length;
108  const found: { excerpt: string; line: number }[] = [];
109  let fence: string | null = null;
110  body.split("\n").forEach((raw, i) => {
111    const marker = /^\s{0,3}(`{3,}|~{3,})/.exec(raw)?.[1];
112    if (marker && (fence === null || marker[0] === fence[0])) {
113      fence = fence === null ? marker : null;
114      return;
115    }
116    if (fence !== null) return;
117    const line = raw.replace(/`[^`]*`/g, "");
118    for (const m of line.matchAll(/!\[([^\]]*)\](\([^)]*\)|\[[^\]]*\])/g)) {
119      if (!m[1]!.trim()) found.push({ excerpt: m[0], line: startLine + i });
120    }
121    for (const m of line.matchAll(/<img\b[^>]*>/gi)) {
122      const alt = /\balt\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(m[0]);
123      if (!alt || !(alt[1] ?? alt[2] ?? alt[3] ?? "").trim()) found.push({ excerpt: m[0], line: startLine + i });
124    }
125    for (const m of line.matchAll(/^\s*:{2,}figure\{([^}]*)\}/g)) {
126      const alt = /\balt\s*=\s*"([^"]*)"/.exec(m[1]!);
127      if (!alt || !alt[1]!.trim()) found.push({ excerpt: m[0].trim(), line: startLine + i });
128    }
129  });
130  return found;
131}
132
133/**
134 * The checks and the preview for a post's whole source on `site`, or null for anything that is not a post
135 * (a legal page, another kind such as a phage, a source with no frontmatter). A null `kind` is a post.
136 * `origin` makes a site path absolute; `path` is the post's public path, which the site gives once it is published.
137 */
138export function seoCheck(site: string, source: string, page: { kind: string | null; origin: string | null; path: string | null }): SeoCheck | null {
139  const fields = SOCIAL_FIELDS[site] ?? DEFAULT_FIELDS;
140  const { front } = splitSource(source.replace(/\r\n/g, "\n"));
141  if (front === null || (page.kind ?? "post") !== "post" || legalTypeOf(source) !== null) return null;
142  const findings: SeoFinding[] = [];
143
144  const title = first(front, fields.title);
145  const searchTitle = title ? `${title}${fields.titleSuffix ?? ""}` : "";
146  if (!title) {
147    findings.push({ check: "title", message: "No title: a search result has nothing to show for this post.", excerpt: null, line: null });
148  } else if (searchTitle.length > SERP_TITLE_LIMIT) {
149    const added = fields.titleSuffix ? ` with the site's "${fields.titleSuffix.trim()}"` : "";
150    findings.push({
151      check: "title",
152      message: `The search title is ${plural(searchTitle.length)}${added}; results clip at about ${SERP_TITLE_LIMIT}.`,
153      excerpt: searchTitle,
154      line: null,
155    });
156  }
157
158  const description = first(front, fields.description);
159  if (!description) {
160    findings.push({ check: "description", message: "No description: a search engine writes its own from the page, and a link card shows none.", excerpt: null, line: null });
161  } else if (description.length > SERP_DESCRIPTION_LIMIT) {
162    findings.push({ check: "description", message: `The description is ${plural(description.length)}; results clip at about ${SERP_DESCRIPTION_LIMIT}.`, excerpt: description, line: null });
163  } else if (description.length < DESCRIPTION_MIN) {
164    findings.push({ check: "description", message: `The description is ${plural(description.length)}, under ${DESCRIPTION_MIN}: too short to say what the post is.`, excerpt: description, line: null });
165  }
166
167  for (const image of imagesWithoutAlt(source)) {
168    findings.push({ check: "image-alt", message: "An image with no alt text: a screen reader and a search engine get nothing from it.", excerpt: image.excerpt, line: image.line });
169  }
170
171  const image = fields.image ? value(front, fields.image) : "";
172  if (fields.image && !image) {
173    findings.push({ check: "card-image", message: "No card image: a shared link shows the site's default image, or none.", excerpt: null, line: null });
174  }
175
176  const absolute = (url: string) => (url.startsWith("/") && page.origin ? `${page.origin.replace(/\/+$/, "")}${url}` : url);
177  return {
178    findings,
179    preview: {
180      search: { title: truncateForSerp(searchTitle, SERP_TITLE_LIMIT), description: truncateForSerp(description, SERP_DESCRIPTION_LIMIT) },
181      card: {
182        title: first(front, fields.cardTitle ?? fields.title),
183        description: first(front, fields.cardDescription ?? fields.description),
184        image: image ? absolute(image) : null,
185      },
186      host: page.origin ? new URL(page.origin).host : null,
187      url: page.path && page.origin ? absolute(page.path) : null,
188    },
189  };
190}