app/lib/content-pages.mjs

Functions

Imports

It imports app/lib/content/og-card-text.mjs, app/lib/dictionary-entries.mjs, app/lib/long-date.mjs, app/lib/search/records.mjs. Imported by app/lib/cv/markdown.mjs, app/lib/cv/save.server.ts, app/lib/dictionary/compile.mjs, app/lib/llms/save.server.ts, app/lib/nav.ts, app/lib/pages/compile.mjs, app/lib/pages/links.mjs, app/lib/pages/page-json-ld.ts, app/lib/pages/save.server.ts, app/lib/site-urls.server.ts, app/routes.ts, app/routes/content-page.tsx, app/routes/cv.tsx, app/routes/phages.tsx, app/routes/protocols.tsx.

Source

1/**
2 * The Research, Teaching and Software pages: markdown in content/pages/, rendered at build time into
3 * content/generated/pages.json like the About page, and served by one route module. This list is the
4 * one place their paths are named: app/routes.ts registers a route per entry, the sitemap lists each,
5 * and the build refuses a markdown file whose path is not here or an entry with no file.
6 *
7 * The 2026-09-27 cutover wrote them from the old WordPress site, its knowledge base and the lab's
8 * notebooks (cutover.md, "Pages to build before the switch").
9 */
10
11import { ogImageKey } from "./content/og-card-text.mjs";
12import { dictionaryEntryMarkdown, dictionaryEntryText } from "./dictionary-entries.mjs";
13import { longDateUTC } from "./long-date.mjs";
14import { splitSections } from "./search/records.mjs";
15
16export const CONTENT_PAGE_PATHS = /** @type {const} */ ([
17  "/research",
18  "/research/retroviruses",
19  "/research/retroviruses/human",
20  "/research/retroviruses/avian",
21  "/research/bacteriophages",
22  "/research/science-education",
23  "/research/phages",
24  // Not in cutover.md's page list, but its redirect rows land old knowledge-base addresses here.
25  "/research/protocols",
26  // The protocols themselves are procedures (content/procedures/, docs/PROCEDURES.md), drawn from D1.
27  // The phage lab calculators (job_c2b88d76b3c1). Their addresses are fixed: the citable version
28  // (Zenodo DOI, JMBE) replaces them in place, so none of these may move.
29  "/research/tools",
30  "/research/tools/titer",
31  "/research/tools/dilution",
32  "/research/tools/webbed-plate",
33  "/research/tools/moi",
34  "/research/tools/eop",
35  "/research/tools/lysate-volume",
36  "/teaching",
37  "/teaching/phage-discovery",
38  "/teaching/virus-isolation",
39  "/teaching/virus-isolation/faq",
40  "/teaching/phage-bioinformatics",
41  "/teaching/central-dogma",
42  "/teaching/study-skills",
43  "/software",
44  "/software/foxhound",
45  "/software/foxing",
46  "/software/foxing-edu",
47  "/software/germomics",
48  "/software/capsid",
49  "/software/enarratio",
50  "/software/carrel",
51  "/software/capsomer",
52  // The CV. Its entries are the files in content/cv/ (docs/CV.md), not a markdown page kept in content/pages/.
53  "/cv",
54  // The legal pages, in Carrel with the rest (job_044f96426efa). /terms is also the terms the site's data is
55  // published under: the `license` of every Dataset (app/lib/license.mjs).
56  "/privacy",
57  "/terms",
58  // The accessibility statement (job_fea2f94832b3): what the gates check, in Carrel with the legal pages but
59  // not one of them. It ships as a draft until Dustin approves its text, and the footer links it once published.
60  "/accessibility",
61]);
62
63/**
64 * The legal pages: the only ones whose front matter may state a `banner` (the one word "Draft") and a
65 * `last_updated` date, which the layout draws for every reader and the markdown twin repeats. Carrel writes
66 * both (carrel design-legal-pages.md).
67 *
68 * @type {readonly string[]}
69 */
70export const LEGAL_PAGE_PATHS = ["/privacy", "/terms"];
71
72/** The one word a legal page's `banner` may say. */
73export const LEGAL_BANNER = "Draft";
74
75/**
76 * The listed pages whose markdown is GENERATED from structured data rather than read from
77 * content/pages/: build:content renders it from app/lib/cv/markdown.mjs, so the twin, sitemap, search
78 * records and llms.txt treat /cv like every other page. Their HTML comes from their own route
79 * (app/routes/cv.tsx) and their twin from another (app/routes/cv[.md].ts), both drawn from the cv table, so
80 * pages.json and the pages table leave them out.
81 *
82 * @type {readonly string[]}
83 */
84export const CONTENT_PAGES_FROM_DATA = ["/cv"];
85
86/**
87 * The listed pages a reader can open: every one whose page is published, and the ones generated from data.
88 * llms.txt must list each of these. `published` is the published paths from whichever source the caller
89 * judges against: the page files (readPublishedPages()) in CI and the gates, the D1 rows in the llms.txt save.
90 *
91 * @param {readonly string[]} published
92 * @returns {string[]}
93 */
94export function publishedContentPagePaths(published) {
95  return CONTENT_PAGE_PATHS.filter((path) => CONTENT_PAGES_FROM_DATA.includes(path) || published.includes(path));
96}
97
98/**
99 * The listed pages that are drafts: llms.txt may name them (so a page's line can land before or after it is
100 * published, in either order) but need not.
101 *
102 * @param {readonly string[]} published as for publishedContentPagePaths
103 * @returns {string[]}
104 */
105export function draftContentPagePaths(published) {
106  const open = publishedContentPagePaths(published);
107  return CONTENT_PAGE_PATHS.filter((path) => !open.includes(path));
108}
109
110/**
111 * The pages that have a file in content/pages/, a row in the pages table and the page save, but whose
112 * route, layout and structured data are their own (app/routes/about.tsx, a ProfilePage with its photo). They
113 * are not in CONTENT_PAGE_PATHS, so the research splat, a markdown twin, a search record and the llms.txt
114 * rules never see them: moving About onto D1 changed where its prose is kept and nothing a visitor reads.
115 *
116 * @type {readonly string[]}
117 */
118export const CONTENT_PAGES_OWN_ROUTE = ["/about"];
119
120/** Every path a file in content/pages/ may name: the listed pages and the ones with a route of their own. */
121export const PAGE_FILE_PATHS = /** @type {readonly string[]} */ ([...CONTENT_PAGE_PATHS, ...CONTENT_PAGES_OWN_ROUTE]);
122
123/**
124 * The headings on these pages that the header menus link to by anchor, as `path#id`. A menu shows a
125 * section link only once it is listed here, and the build refuses an entry whose page has no heading
126 * with that id, so no menu link lands on the top of a page for want of its heading.
127 *
128 * @type {readonly string[]}
129 */
130export const CONTENT_PAGE_SECTIONS = ["/teaching#join-the-lab", "/teaching#teaching-philosophy"];
131
132/**
133 * The markdown file a path is written in: slashes to hyphens, `/research/phages` in research-phages.md.
134 *
135 * @param {string} path
136 */
137export function contentPageFile(path) {
138  return `${path.slice(1).replaceAll("/", "-")}.md`;
139}
140
141/**
142 * The markdown twin's URL: the page path plus `.md`. Not `contentPageFile`, which is the repo filename.
143 *
144 * @param {string} path
145 */
146export function contentPageMarkdownPath(path) {
147  return `${path}.md`;
148}
149
150/**
151 * The twin a machine reads. The HTML page's h1 is not in the source body, so the title is the first line,
152 * followed by the page's dictionary entry where it has one, where the page shows it. The entry is the
153 * caller's to give: the build reads it from content/dictionary, the Worker from D1 (docs/DICTIONARY.md).
154 *
155 * @param {{ path?: string, title: string, markdown: string, banner?: string, lastUpdated?: string }} page
156 * @param {import("./dictionary-entries.mjs").DictionaryEntry} [entry] the page's published entry, if any
157 */
158export function contentPageMarkdownBody(page, entry) {
159  const body = String(page.markdown ?? "").replace(/^\n+/, "");
160  const lead = entry ? `${dictionaryEntryMarkdown(entry)}\n` : "";
161  // A legal page's banner and date are facts a reader sees under the title, so the twin states them too.
162  const stated = [page.banner, page.lastUpdated ? `Last updated: ${longDateUTC(page.lastUpdated)}` : ""].filter(Boolean);
163  const legal = stated.length > 0 ? `${stated.join("\n\n")}\n\n` : "";
164  return `# ${page.title}\n\n${legal}${lead}${body}`;
165}
166
167/**
168 * The pages build:og draws a social card of their own, by the root they sit under: the root and every
169 * page below it, so a calculator added under /research/tools is carded with no edit here. Every other
170 * page keeps the site card. Adding a root cards its pages on the next build:og.
171 *
172 * @type {readonly string[]}
173 */
174export const CARDED_PAGE_ROOTS = ["/software", "/research/tools", "/cv"];
175
176/** @param {string} path */
177export function hasPageCard(path) {
178  return CARDED_PAGE_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));
179}
180
181/**
182 * What build:og draws for a page, in the shape ogImageKey hashes: the page's og:title (its SERP title)
183 * and its description, with no date line, since these pages are not dated. The `page-` prefix keeps a
184 * page's key apart from a post's, and build:og refuses two cards with one key.
185 *
186 * @param {{ path: string, seoTitle: string, description: string }} page
187 */
188export function contentPageCardInput(page) {
189  return {
190    slug: `page-${page.path.slice(1).replaceAll("/", "-")}`,
191    title: page.seoTitle,
192    description: page.description,
193    publishAt: null,
194  };
195}
196
197/**
198 * The /media path of a page's card, which its og:image names, or null for a page on the site card. The
199 * key hashes what the card draws, so a retitled page names a new card, which build:og then draws.
200 *
201 * @param {{ path: string, seoTitle: string, description: string }} page
202 * @returns {string | null}
203 */
204export function contentPageCardPath(page) {
205  return hasPageCard(page.path) ? `/media/${ogImageKey(contentPageCardInput(page))}` : null;
206}
207
208/**
209 * What a Dataset node says about a page's first markdown table, read from the markdown the page renders:
210 * its column headings, as the variables, and the span of its Year column, as an ISO 8601 interval. Null
211 * when the page has no table.
212 *
213 * @param {string} markdown
214 * @returns {{ variableMeasured: string[], temporalCoverage: string | null, rows: number } | null}
215 */
216export function markdownTableFacts(markdown) {
217  const lines = String(markdown ?? "").split("\n");
218  const rule = /^\|(\s*:?-+:?\s*\|)+\s*$/;
219  const at = lines.findIndex((line, i) => /^\|.*\|\s*$/.test(line) && rule.test(lines[i + 1] ?? ""));
220  if (at < 0) return null;
221  const cells = (/** @type {string} */ line) =>
222    line
223      .trim()
224      .replace(/^\||\|$/g, "")
225      .split("|")
226      .map((cell) => cell.trim());
227  const headings = cells(lines[at] ?? "");
228  /** @type {string[][]} */
229  const rows = [];
230  for (let i = at + 2; i < lines.length && (lines[i] ?? "").startsWith("|"); i += 1) rows.push(cells(lines[i] ?? ""));
231  const yearColumn = headings.findIndex((heading) => /^year$/i.test(heading));
232  const years =
233    yearColumn < 0
234      ? []
235      : rows.map((row) => Number(row[yearColumn])).filter((year) => Number.isInteger(year) && year > 0);
236  const first = Math.min(...years);
237  const last = Math.max(...years);
238  const temporalCoverage = years.length === 0 ? null : first === last ? String(first) : `${first}/${last}`;
239  return { variableMeasured: headings, temporalCoverage, rows: rows.length };
240}
241
242/** Google clips near these; the build refuses longer ones rather than ship a clipped result. */
243export const SEO_TITLE_MAX = 60;
244export const DESCRIPTION_MAX = 155;
245
246/** The hubs, and the trail label each gives the pages under it. */
247const HUBS = /** @type {const} */ ([
248  ["/research", "Research"],
249  ["/teaching", "Teaching"],
250  ["/software", "Software"],
251]);
252
253/**
254 * The trail above a page: its hub, the page it sits under when it is three deep (the course above its
255 * FAQ), then the page itself. A hub stands alone.
256 *
257 * @param {{ path: string, title: string }} page
258 * @param {(path: string) => string | undefined} [titleOf] the title of another listed page
259 * @returns {Array<[string, string]>}
260 */
261export function contentPageTrail(page, titleOf = () => undefined) {
262  const hub = HUBS.find(([path]) => page.path.startsWith(`${path}/`));
263  if (!hub) return [[page.title, page.path]];
264  const trail = /** @type {Array<[string, string]>} */ ([[hub[1], hub[0]]]);
265  const parent = page.path.slice(0, page.path.lastIndexOf("/"));
266  const parentTitle = parent !== hub[0] ? titleOf(parent) : undefined;
267  if (parentTitle) trail.push([parentTitle, parent]);
268  trail.push([page.title, page.path]);
269  return trail;
270}
271
272/** The search uid of a page path: a removal needs it to find the page's records. */
273export function contentPageSearchUid(/** @type {string} */ path) {
274  return `page:${path.slice(1).replaceAll("/", ":")}`;
275}
276
277/**
278 * Search inputs in the shape `recordsForPages` takes: one record for the page, one per heading, each
279 * deep-linking to the heading's own anchor.
280 *
281 * @param {Array<{ path: string, title: string, description: string, markdown: string, toc: Array<{ depth: number, id: string, text: string }> }>} pages
282 * @param {(path: string) => import("./dictionary-entries.mjs").DictionaryEntry | undefined} [entryFor] the
283 *   published dictionary entry of a page path, which leads that page's record
284 */
285export function contentPageSearchInputs(pages, entryFor = () => undefined) {
286  return pages.map((page) => {
287    const { intro, sections } = splitSections(page.markdown, page.toc);
288    const entry = entryFor(page.path);
289    return {
290      url: page.path,
291      uid: contentPageSearchUid(page.path),
292      title: page.title,
293      description: page.description,
294      intro: entry ? `${dictionaryEntryText(entry)} ${intro}` : intro,
295      sections: sections.map(({ anchor, title, body }) => ({ anchor, title, body })),
296    };
297  });
298}