app/lib/seo.ts

Functions

Imports

It imports app/lib/identity.generated.mjs, app/lib/license.mjs, app/lib/publications/article-json-ld.mjs, app/lib/publications/authors.mjs, app/lib/publications/entities.mjs, app/lib/publications/paths.mjs, app/lib/site-origin.mjs. Imported by app/components/admin/settings-drawer.tsx, app/components/admin/social-previews.tsx, app/components/home-intro.tsx, app/components/home-podcast.tsx, app/components/procedure.tsx, app/components/shell-footer.tsx, app/components/site-header.tsx, app/components/taxonomy-listing.tsx, app/lib/cache-purge.server.ts, app/lib/carrel/site-adapter.server.ts, app/lib/cv/pdf-html.mjs, app/lib/feed-response.ts, app/lib/footer.ts, app/lib/llms/save.server.ts, app/lib/markdown-twin.ts, app/lib/media/upload.server.ts, app/lib/nav.ts, app/lib/pages/page-json-ld.ts, app/lib/publications/sources.server.ts, app/lib/site-urls.server.ts, app/lib/webmention/advertise.ts, app/lib/webmention/verify.server.ts, app/root.tsx, app/routes/about.tsx, app/routes/accessibility.tsx, app/routes/admin.tsx, app/routes/blog.$slug.tsx, app/routes/blog.$slug[.md].ts, app/routes/blog._index.tsx, app/routes/blog.series.$series.tsx, app/routes/blog.tags.$tag.tsx, app/routes/colophon.tsx, app/routes/contact.tsx, app/routes/content-page.tsx, app/routes/content-page[.md].ts, app/routes/cv-pdf.ts, app/routes/cv.charts[.json].ts, app/routes/cv.tsx, app/routes/cv[.md].ts, app/routes/gone.tsx, app/routes/home.tsx, app/routes/kb-library.tsx, app/routes/kb-library[.csv].ts, app/routes/kb-library[.json].ts, app/routes/kb-library[.md].ts, app/routes/lab.kind.tsx, app/routes/lab.tsx, app/routes/lab[.md].ts, app/routes/llms-full[.txt].ts, app/routes/llms.ts, app/routes/media.$.ts, app/routes/phages.tsx, app/routes/preview.$token.tsx, app/routes/privacy.tsx, app/routes/procedure.sheet.tsx, app/routes/procedure.tsx, app/routes/procedure.version.sheet.tsx, app/routes/procedure.version.tsx, app/routes/procedure.version[.md].ts, app/routes/procedure[.md].ts, app/routes/protocols.tsx, app/routes/protocols[.csv].ts, app/routes/protocols[.json].ts, app/routes/protocols[.md].ts, app/routes/publications.$slug.tsx, app/routes/publications.$slug[.bib].ts, app/routes/publications.$slug[.md].ts, app/routes/publications.$slug[.ris].ts, app/routes/publications.tsx, app/routes/publications[.bib].ts, app/routes/publications[.json].ts, app/routes/publications[.ris].ts, app/routes/robots.ts, app/routes/search.tsx, app/routes/security-txt.ts, app/routes/site-map.tsx, app/routes/sitemap.ts, app/routes/software.tsx, app/routes/systems.tsx, app/routes/systems[.md].ts, app/routes/teaching.tsx, app/routes/terms.tsx, app/routes/webmention.ts, app/routes/workspace.tsx, workers/app.ts, workers/watchdog.ts.

Source

1// Relative, not `~/`: tsconfig.node.json also compiles this file and has no path mapping.
2import { IDENTITY } from "./identity.generated.mjs";
3import { TERMS_PATH } from "./license.mjs";
4import { canonicalAuthor } from "./publications/authors.mjs";
5import { schemaTypeFor } from "./publications/article-json-ld.mjs";
6import { decodeEntities } from "./publications/entities.mjs";
7import { paperPath } from "./publications/paths.mjs";
8
9import { SITE_ORIGIN } from "./site-origin.mjs";
10
11export { SITE_ORIGIN };
12
13/** The `license` of every Dataset: the site's terms page (app/lib/license.mjs). */
14export const LICENSE_URL = `${SITE_ORIGIN}${TERMS_PATH}`;
15
16const DEFAULT_OG_IMAGE = `${SITE_ORIGIN}/dustin-edwards-og-image.png`;
17
18// The person, the role, the headship, the department and the university are the CV's: derived from
19// content/cv/profile.md and appointments.md by app/lib/identity.mjs (written to identity.generated.mjs at build),
20// so a CV change reaches the site settings, the titles, the About text and the structured data.
21// `role` is the visible identity line; `jobTitle` is the Person record's, which also names the headship
22// (Dustin, 2026-09-28). `affiliation` is structured data (worksFor), so it stays short and literal; `org` is the full line for people to read.
23// The description is the name and the role only (Dustin, 2026-10-15: "It should be just 'Dr. Dustin Edwards,
24// Professor and Virologist'"). "Dr." is the doctorate the CV states, so it follows the degree rather than being typed.
25const HONORIFIC = /^(Ph\.?D|M\.?D|D\.?V\.?M|Ed\.?D|D\.?Sc)\.?$/i.test(IDENTITY.degree) ? "Dr. " : "";
26export const SITE = {
27  name: IDENTITY.name,
28  role: IDENTITY.role,
29  jobTitle: IDENTITY.jobTitle,
30  affiliation: IDENTITY.affiliation,
31  // The university and its system, for the home hero and the About panel. `affiliation` stays the short form worksFor needs.
32  org: IDENTITY.org,
33  department: IDENTITY.department,
34  eyebrow: IDENTITY.role,
35  tagline: `${IDENTITY.role}, ${IDENTITY.department}, ${IDENTITY.affiliation}.`,
36  description: `${HONORIFIC}${IDENTITY.name}, ${IDENTITY.role}`,
37} as const;
38
39// Shared by the public route and the admin preview, so the preview cannot silently disagree.
40type PostSocialFields = {
41  slug: string;
42  title: string;
43  description?: string | null;
44  ogTitle?: string | null;
45  ogDescription?: string | null;
46  coverImage?: string | null;
47  ogImage?: string | null;
48};
49
50export function postSocial(post: PostSocialFields) {
51  const canonical = `${SITE_ORIGIN}/writing/${post.slug}`;
52  const description = post.description ?? SITE.description;
53  const socialImage = post.coverImage ?? post.ogImage ?? null;
54  return {
55    canonical,
56    pageTitle: `${post.title} | ${SITE.name}`,
57    description,
58    socialTitle: post.ogTitle ?? post.title,
59    socialDescription: post.ogDescription ?? description,
60    image: socialImage ? `${SITE_ORIGIN}${socialImage}` : DEFAULT_OG_IMAGE,
61    usingDefaultImage: socialImage === null,
62  };
63}
64
65/**
66 * `summary_large_image` always: the image falls back to the site mark, and a `twitter:card` without
67 * an image renders as a bare link.
68 */
69export function pageMeta(page: {
70  title: string;
71  description: string;
72  path: string;
73  image?: string;
74  ogType?: "website" | "article";
75}) {
76  const url = `${SITE_ORIGIN}${page.path}`;
77  const image = page.image ?? DEFAULT_OG_IMAGE;
78  return [
79    { title: page.title },
80    { name: "description", content: page.description },
81    { tagName: "link", rel: "canonical", href: url },
82    { property: "og:title", content: page.title },
83    { property: "og:description", content: page.description },
84    { property: "og:url", content: url },
85    { property: "og:type", content: page.ogType ?? "website" },
86    { property: "og:image", content: image },
87    { name: "twitter:card", content: "summary_large_image" },
88    { name: "twitter:image", content: image },
89  ];
90}
91
92/**
93 * Google truncates by pixel width (about 600px title, 920px description), so these approximate it;
94 * the description field's own 160-character counter would show text the result clips.
95 */
96export const SERP_TITLE_LIMIT = 60;
97export const SERP_DESCRIPTION_LIMIT = 155;
98
99export function truncateForSerp(text: string, limit: number) {
100  if (text.length <= limit) return text;
101  const cut = text.slice(0, limit);
102  const lastSpace = cut.lastIndexOf(" ");
103  return `${(lastSpace > limit * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd()}...`;
104}
105
106/** The home page's Person: the same node as `personNode`, joined to it by the shared `@id`. */
107export function personJsonLd(origin: string) {
108  return personNode(origin);
109}
110
111/**
112 * The About page is a ProfilePage about the same Person the home page describes: the shared `@id` is
113 * what makes the two one entity rather than two people with one name.
114 */
115export function profilePageJsonLd(origin: string, page: { path: string; description: string }) {
116  const { "@context": context, ...person } = personNode(origin);
117  return {
118    "@context": context,
119    "@type": "ProfilePage",
120    "@id": `${origin}${page.path}`,
121    url: `${origin}${page.path}`,
122    name: `About ${SITE.name}`,
123    description: page.description,
124    mainEntity: person,
125  };
126}
127
128/**
129 * Needs no `Vary`: the theme is part of the cache key in `workers/app.ts`. Never add
130 * must-revalidate, proxy-revalidate, no-cache or s-maxage: each disables stale-while-revalidate at
131 * Cloudflare (RFC 9111 4.2.4). Browser max-age stays 0 because purges cannot reach a browser.
132 */
133export const SHARED_CACHE_CONTROL = "public, max-age=0";
134
135/** A response whose address changes when its bytes do (hashed media, uploads). */
136export const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
137
138/** The small text files crawlers read (robots.txt, security.txt, llms.txt). */
139export const HOURLY_CACHE_CONTROL = "public, max-age=3600";
140
141/**
142 * A day fresh is safe because every write purges by tag, every deploy starts cold, and a page that
143 * lists posts expires at the next scheduled publish_at. Never parse a lifetime back out of a string:
144 * a failed parse has to substitute a false lifetime.
145 */
146const EDGE_FRESH_SECONDS = 86_400;
147const EDGE_STALE_SECONDS = 604_800;
148
149// Short because the home page carries the latest Germomics episode, which no write purges.
150export const HOME_EDGE_FRESH_SECONDS = 600;
151
152/**
153 * A publish_at seconds away would otherwise send a max-age near zero, and every read until it passed
154 * would be a render. A minute is the most a scheduled post can lag its time for it.
155 */
156const SCHEDULED_FLOOR_SECONDS = 60;
157
158const edgeCacheControl = (fresh: number) =>
159  `max-age=${fresh}, stale-while-revalidate=${EDGE_STALE_SECONDS}`;
160
161/**
162 * Sent as `Cloudflare-CDN-Cache-Control`, not `s-maxage`: `s-maxage` implies proxy-revalidate, so
163 * Cloudflare refuses to serve stale and every read past the lifetime blocks on a render.
164 */
165export const EDGE_CACHE_CONTROL = edgeCacheControl(EDGE_FRESH_SECONDS);
166
167/** Short because the colophon's site-health tile age is the watchdog's liveness. */
168export const HEALTH_EDGE_CACHE_CONTROL = edgeCacheControl(600);
169
170/**
171 * The edge policy for a page that lists posts. A scheduled post goes live with no write to purge on,
172 * so the page expires when the next one does; with nothing scheduled it is the plain policy.
173 */
174export function scheduledEdgeCacheControl(
175  now: Date,
176  nextPublishAt: Date | null,
177  fresh: number = EDGE_FRESH_SECONDS,
178): string {
179  if (!nextPublishAt) return edgeCacheControl(fresh);
180  const untilPublish = Math.ceil((nextPublishAt.getTime() - now.getTime()) / 1000);
181  return edgeCacheControl(Math.min(fresh, Math.max(SCHEDULED_FLOOR_SECONDS, untilPublish)));
182}
183
184export const EDGE_CACHE_HEADER = "Cloudflare-CDN-Cache-Control";
185
186// A misspelled tag is a purge that silently does nothing: `cache.purge` succeeds on an unmatched tag.
187export function cacheTags(slug?: string): string {
188  return slug ? `post:${slug},posts` : "posts";
189}
190
191/**
192 * The tags of a document that lists both posts and procedures (the sitemap), in the comma-list
193 * `cacheTags()` uses. `purgePosts` and `purgeProcedures` each reach it. The literal is the one
194 * `PROCEDURES_CACHE_TAG` names (app/kb/procedures/route.ts); test/worker/cache-tags.test.ts pins both.
195 */
196export const POSTS_AND_PROCEDURES_CACHE_TAGS = `${cacheTags()},procedures`;
197
198const PAGES_CACHE_TAG = "pages";
199
200/**
201 * The Renderer stamps `EDGE_CACHE_CONTROL` beside `SHARED_CACHE_CONTROL`; pass `edge` only to depart
202 * from that default.
203 */
204export function publicHtmlHeaders(tag: string = PAGES_CACHE_TAG, edge?: string) {
205  return {
206    "Cache-Control": SHARED_CACHE_CONTROL,
207    "Cache-Tag": tag,
208    ...(edge ? { [EDGE_CACHE_HEADER]: edge } : {}),
209  };
210}
211
212export const HTML_VARY_ACCEPT = "Accept";
213
214/**
215 * Also applied by `workers/app.ts` to any response with no `Cache-Control`, and to cookie-bearing
216 * requests on the HTML routes.
217 */
218export const NO_STORE_CACHE_CONTROL = "private, no-store";
219
220type ArticleSeo = {
221  slug: string;
222  title: string;
223  description: string | null;
224  publishAt: Date | null;
225  updatedAt: Date | null;
226  coverImage: string | null;
227  ogImage?: string | null;
228  tags: string[];
229};
230
231// Derived once so the JSON-LD and Open Graph outputs cannot drift apart.
232function articleFacts(origin: string, post: ArticleSeo) {
233  return {
234    publishedTime: post.publishAt?.toISOString(),
235    modifiedTime: (post.updatedAt ?? post.publishAt)?.toISOString(),
236    authorName: SITE.name,
237    authorUrl: origin,
238    tags: post.tags,
239  };
240}
241
242// An absent date yields no property: an empty `article:published_time` claims there is no date.
243export function articleOpenGraph(origin: string, post: ArticleSeo) {
244  const facts = articleFacts(origin, post);
245  const tags: Array<{ property: string; content: string }> = [];
246  if (facts.publishedTime) {
247    tags.push({ property: "article:published_time", content: facts.publishedTime });
248  }
249  if (facts.modifiedTime) {
250    tags.push({ property: "article:modified_time", content: facts.modifiedTime });
251  }
252  tags.push({ property: "article:author", content: facts.authorName });
253  for (const tag of facts.tags) {
254    tags.push({ property: "article:tag", content: tag });
255  }
256  return tags;
257}
258
259export function articleJsonLd(origin: string, post: ArticleSeo) {
260  const facts = articleFacts(origin, post);
261  return {
262    "@context": "https://schema.org",
263    "@type": "Article",
264    headline: post.title,
265    description: post.description ?? undefined,
266    datePublished: facts.publishedTime,
267    dateModified: facts.modifiedTime,
268    image: postSocial({
269      slug: post.slug,
270      title: post.title,
271      description: post.description,
272      coverImage: post.coverImage,
273      ogImage: post.ogImage ?? null,
274    }).image,
275    keywords: facts.tags.length > 0 ? facts.tags.join(", ") : undefined,
276    mainEntityOfPage: { "@type": "WebPage", "@id": `${origin}/writing/${post.slug}` },
277    author: { "@type": "Person", name: facts.authorName, url: facts.authorUrl },
278    publisher: { "@type": "Person", name: SITE.name, url: origin },
279  };
280}
281
282export function breadcrumbJsonLd(origin: string, trail: Array<[string, string]>) {
283  return {
284    "@context": "https://schema.org",
285    "@type": "BreadcrumbList",
286    itemListElement: trail.map(([name, path], i) => ({
287      "@type": "ListItem",
288      position: i + 1,
289      name,
290      item: `${origin}${path}`,
291    })),
292  };
293}
294
295export function webSiteJsonLd(origin: string) {
296  return {
297    "@context": "https://schema.org",
298    "@type": "WebSite",
299    name: SITE.name,
300    description: SITE.description,
301    url: origin,
302  };
303}
304
305export const PUBLICATIONS_URL = "/research/publications";
306
307export const PUBLICATIONS_DESCRIPTION =
308  "Peer-reviewed work by Dustin Edwards on retroviruses, bacteriophage genomics, and science education, with full text hosted here.";
309
310export const OWNER_ORCID = "https://orcid.org/0000-0001-6409-8041";
311export const OWNER_SCHOLAR =
312  "https://scholar.google.com/citations?user=lfzCCXwAAAAJ";
313export const OWNER_PUBMED =
314  "https://pubmed.ncbi.nlm.nih.gov/?term=Edwards+Dustin%5BAuthor%5D&sort=date";
315export const OWNER_FACULTY_PAGE = "https://faculty.tarleton.edu/dcedwards/";
316
317// Confirmed by Dustin, 2026-09-28 (#200); each ties to Tarleton.
318const OWNER_SEA_PHAGES = "https://seaphages.org/faculty/318/";
319const OWNER_SCOPUS = "https://www.scopus.com/authid/detail.uri?authorId=57204587587";
320const OWNER_LOOP = "https://loop.frontiersin.org/people/2520780";
321const OWNER_GITHUB = "https://github.com/DrDustinEdwards";
322const OWNER_LINKEDIN = "https://www.linkedin.com/in/dustin-edwards-152235274/";
323const OWNER_WIKIDATA = "https://www.wikidata.org/wiki/Q141630373";
324
325// The headshot (Dustin, 2026-09-28), uploaded to MEDIA from Tarleton's file so nothing here links to
326// another server. The square crop leads: search engines prefer it for a Person.
327export const OWNER_PHOTO = {
328  key: "dustin-edwards-headshot-a4b25f04061613b9-1365x2048.jpg",
329  width: 1365,
330  height: 2048,
331} as const;
332const OWNER_PHOTO_SQUARE = {
333  key: "dustin-edwards-headshot-square-090e58f805bc9e9f-1365x1365.jpg",
334  width: 1365,
335  height: 1365,
336} as const;
337
338function photoObject(origin: string, photo: { key: string; width: number; height: number }) {
339  const url = `${origin}/media/${photo.key}`;
340  return { "@type": "ImageObject", url, contentUrl: url, width: photo.width, height: photo.height };
341}
342
343export const GERMOMICS_URL = "https://germomics.com/";
344export const GERMOMICS_X_URL = "https://x.com/Germomics";
345
346// The footer's `rel="me"` profiles, in order. `check:machine-readable` reads this list.
347export const OWNER_PROFILES = [OWNER_SCHOLAR, OWNER_ORCID, OWNER_PUBMED] as const;
348
349const OWNER_SAME_AS = [
350  ...OWNER_PROFILES,
351  OWNER_FACULTY_PAGE,
352  OWNER_SEA_PHAGES,
353  OWNER_SCOPUS,
354  OWNER_LOOP,
355  OWNER_GITHUB,
356  OWNER_LINKEDIN,
357  OWNER_WIKIDATA,
358  GERMOMICS_URL,
359  GERMOMICS_X_URL,
360];
361
362// What he is known for.
363const OWNER_KNOWS_ABOUT = [
364  "Virology",
365  "Bacteriophages",
366  "Phage genomics",
367  "Avian retroviruses",
368  "Retroviruses",
369  "Science education",
370];
371
372export function personId(origin: string) {
373  return `${origin}/#person`;
374}
375
376/** Not a duplicate of `personJsonLd`: this `@id` joins papers to a person. */
377export function personNode(origin: string) {
378  return {
379    "@context": "https://schema.org",
380    "@type": "Person",
381    "@id": personId(origin),
382    ...personFacts(origin),
383  };
384}
385
386/** What both Person nodes say about the owner, in their key order. No alternate names. */
387function personFacts(origin: string) {
388  return {
389    name: SITE.name,
390    honorificSuffix: IDENTITY.degree,
391    jobTitle: SITE.jobTitle,
392    image: [photoObject(origin, OWNER_PHOTO_SQUARE), photoObject(origin, OWNER_PHOTO)],
393    description: SITE.description,
394    url: origin,
395    worksFor: {
396      "@type": "CollegeOrUniversity",
397      name: SITE.affiliation,
398      url: "https://www.tarleton.edu/",
399      department: {
400        "@type": "Organization",
401        name: SITE.department,
402      },
403    },
404    knowsAbout: OWNER_KNOWS_ABOUT,
405    sameAs: OWNER_SAME_AS,
406  };
407}
408
409// Registries spell his name several ways, so this reads the exact alias table the exports use: a
410// surname-plus-initial rule claimed any "D* Edwards" co-author as the owner in JSON-LD.
411export function isSiteOwner(name: string) {
412  return canonicalAuthor(name) === SITE.name;
413}
414
415// Only the owner's entry becomes an `@id` reference; replacing the whole array would drop co-authors.
416// Every record has its own page (app/lib/publications/by-slug.ts), so each article takes that page as
417// its `@id` and `url`, the same node the paper page describes in full; a hosted PDF is its encoding.
418export function publicationsJsonLd(
419  origin: string,
420  items: {
421    title: string;
422    authors: string[];
423    year: number;
424    journal: string | null;
425    slug: string;
426    /** Null for a submitted manuscript, which has no DOI yet. */
427    doi: string | null;
428    pdfPath: string | null;
429    /** The curated type, so a chapter here is the same Chapter its own page describes. */
430    type?: string;
431  }[],
432) {
433  const id = personId(origin);
434  return [
435    personNode(origin),
436    ...items.map((p) => ({
437      "@context": "https://schema.org",
438      "@type": p.type ? schemaTypeFor(p.type) : "ScholarlyArticle",
439      "@id": origin + paperPath(p.slug),
440      // Decoding is safe here: `jsonLd()` escapes `<` and `>` on the way into the script element.
441      headline: decodeEntities(p.title),
442      name: decodeEntities(p.title),
443      author: p.authors.map((name) =>
444        isSiteOwner(name) ? { "@id": id } : { "@type": "Person", name: canonicalAuthor(name) },
445      ),
446      datePublished: String(p.year),
447      ...(p.journal
448        ? { isPartOf: { "@type": "Periodical", name: decodeEntities(p.journal) } }
449        : {}),
450      ...(p.doi
451        ? {
452            identifier: { "@type": "PropertyValue", propertyID: "DOI", value: p.doi },
453            sameAs: `https://doi.org/${p.doi}`,
454          }
455        : {}),
456      url: origin + paperPath(p.slug),
457      ...(p.pdfPath
458        ? {
459            encoding: {
460              "@type": "MediaObject",
461              encodingFormat: "application/pdf",
462              contentUrl: origin + p.pdfPath,
463            },
464          }
465        : {}),
466    })),
467  ];
468}