app/lib/content/pipeline.mjs

Functions

Imports

It imports app/lib/content/corpus.mjs, app/lib/content/hashes.mjs, app/lib/content/og-card-text.mjs, app/lib/content/reading-time.mjs, app/lib/content/slug.mjs, app/lib/content/url-policy.mjs, app/lib/content/wide-dash.mjs, app/lib/media/classify.mjs, app/lib/media/widths.mjs. Imported by app/lib/content/load-pipeline.server.ts.

Source

1// The only markdown renderer, shared by the build and the Worker: if they could disagree, check:content
2// would fail on content nobody edited. Runs in a Worker, so no node:fs. The pipeline is Prelum's
3// (@drdustinedwards/site-helpers/render); this module holds what stays with the site: the frontmatter,
4// the media rules and the post record.
5
6import { ContentError, render } from "@drdustinedwards/site-helpers/render";
7import { createHighlight } from "@drdustinedwards/site-helpers/render/highlight";
8import { editorialPack } from "@drdustinedwards/site-helpers/render/packs";
9import { isAllowedUrl } from "@drdustinedwards/site-helpers/render/url";
10import matter from "gray-matter";
11import { z } from "zod";
12
13import { ASSET_PREFIX, classify } from "../media/classify.mjs";
14import { gitBlobSha, renderHash } from "./hashes.mjs";
15import { CONTENT_SIZES, contentSrcSet } from "../media/widths.mjs";
16import { SLUG_MAX_LENGTH, SLUG_PATTERN, postPath } from "./slug.mjs";
17
18import { readingTimeMinutes } from "./reading-time.mjs";
19import { withBacklinks, withRelated } from "./corpus.mjs";
20import { internalLinkSlug, isFurtherReadingUrl } from "./url-policy.mjs";
21
22export { LANGUAGES, SHIKI_THEMES } from "@drdustinedwards/site-helpers/render/highlight";
23
24// Re-exported: build scripts, gates and tests import these from here, the renderer's one door.
25export { ContentError, internalLinkSlug, isAllowedUrl, withBacklinks, withRelated };
26
27// YAML turns an unquoted 2026-07-27 into a Date, so both spellings arrive here.
28/** @param {unknown} value */
29const asDateString = (value) =>
30  value instanceof Date ? value.toISOString().slice(0, 10) : value;
31
32/** @param {unknown} value */
33const asDateTimeString = (value) =>
34  value instanceof Date ? value.toISOString() : value;
35
36const isoDate = z.preprocess(
37  asDateString,
38  z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "must be a YYYY-MM-DD date"),
39);
40
41const isoDateTime = z.preprocess(
42  asDateTimeString,
43  z
44    .string()
45    .refine((v) => !Number.isNaN(Date.parse(v)), "must be a parseable date-time"),
46);
47
48export { SLUG_ATTRIBUTE_PATTERN, SLUG_PATTERN, postPath } from "./slug.mjs";
49
50export const frontmatterSchema = z.object({
51  title: z.string().min(1, "must not be empty"),
52  slug: z
53    .string()
54    .regex(SLUG_PATTERN, "must be lowercase kebab-case")
55    .max(SLUG_MAX_LENGTH, `must be at most ${SLUG_MAX_LENGTH} characters`),
56  date: isoDate,
57  tags: z.array(z.string().min(1)).default([]),
58  description: z.string().min(1, "must not be empty"),
59  draft: z.boolean().default(false),
60  publish_at: isoDateTime.optional(),
61  cover: z
62    .object({
63      /**
64       * The regex refuses protocol-relative paths; isAllowedUrl is the shared protocol check and
65       * must be called, not reimplemented. Both are needed.
66       */
67      src: z
68        .string()
69        .regex(/^\/(?![/\\])/, "must be a site-absolute path, not //host or a full URL")
70        .refine(isAllowedUrl, "protocol is not allowed (https, http, mailto or relative only)"),
71      alt: z.string().min(1, "is required when cover is set"),
72    })
73    .optional(),
74  featured: z.boolean().default(false),
75  series: z.string().min(1).optional(),
76  part: z.number().int().min(1, "must be 1 or greater").optional(),
77  // Not `status`, which is the row's draft/published column. A closed set so readers learn it once.
78  writing_status: z.enum(["notes", "draft", "in progress", "finished", "obsolete"]).optional(),
79  assumed_audience: z.string().min(1).max(200).optional(),
80  key_takeaways: z.array(z.string().min(1).max(300)).min(2).max(4).optional(),
81  // isoDate because YAML parses a bare 2026-08-15 into a Date object.
82  changelog: z
83    .array(
84      z.object({
85        date: isoDate,
86        note: z.string().min(1).max(300),
87      }),
88    )
89    .min(1)
90    .max(20)
91    .optional(),
92  further_reading: z
93    .array(
94      z.object({
95        title: z.string().min(1, "must not be empty"),
96        /**
97         * isAllowedUrl is the SAME predicate the render layer uses (check:urls reads this phrase): z.url()
98         * accepts javascript:, and rehypeUrlProtocols never sees frontmatter. Internal links are /writing/ paths, not absolute URLs, so they survive the origin change at cutover.
99         */
100        url: z
101          .string()
102          .refine(isFurtherReadingUrl, "must be an absolute http(s) URL or a /writing/ path")
103          .refine(isAllowedUrl, "protocol is not allowed (https, http, mailto or relative only)"),
104      }),
105    )
106    .default([]),
107  og_title: z.string().min(1).optional(),
108  og_description: z.string().min(1).optional(),
109  /**
110   * A date, not a timestamp: the build derives it from git and the editor cannot know the time of
111   * the commit it is about to create, so only a date lets the two agree.
112   */
113  updated: isoDate.optional(),
114  // Server-owned, stamped on first publish. renderPost deliberately keeps it out of the record.
115  first_published: isoDate.optional(),
116}).superRefine((value, ctx) => {
117  if (value.series && value.part === undefined) {
118    ctx.addIssue({ code: "custom", path: ["part"], message: "is required when series is set" });
119  }
120  if (value.part !== undefined && !value.series) {
121    ctx.addIssue({ code: "custom", path: ["series"], message: "is required when part is set" });
122  }
123});
124
125export { findWideDashes } from "./wide-dash.mjs";
126
127export { readingTimeMinutes };
128
129// Isolate-wide: one highlighter, the same for every request.
130/** @type {ReturnType<typeof createHighlight> | null} */
131let highlight = null;
132
133/**
134 * Injected: a Worker refuses WebAssembly.instantiate() on bytes, so it passes an instantiator over a
135 * statically imported module. The engine is the same, so the HTML is byte-identical.
136 *
137 * @type {() => any}
138 */
139let wasmLoader = () => import("shiki/wasm");
140
141/** @param {() => any} loader */
142export function setWasmLoader(loader) {
143  wasmLoader = loader;
144  highlight = null;
145}
146
147function getHighlight() {
148  highlight ??= createHighlight({ wasm: () => wasmLoader() });
149  return highlight;
150}
151
152// The card key lives beside the card text it hashes, so a route can name a card without this renderer.
153export { ogImageKey } from "./og-card-text.mjs";
154
155/**
156 * R2 objects are keyed after /media/, static assets by their public path. An unrecognized extension
157 * returns null: a page link is not a media citation and would never join.
158 *
159 * @param {string} raw
160 * @returns {string | null}
161 */
162function mediaKeyOf(raw) {
163  if (typeof raw !== "string" || raw.length === 0) return null;
164
165  let path = raw;
166  const origin = path.match(/^(?:[a-z][a-z0-9+.-]*:)?\/\/[^/]+(\/.*)$/i);
167  if (origin) path = origin[1] ?? path;
168  // Query and fragment are not part of the key: ?w=320 is a transform request.
169  path = path.split(/[?#]/)[0] ?? "";
170  if (!path.startsWith("/")) return null;
171
172  if (path.startsWith("/media/")) {
173    const key = path.slice("/media/".length);
174    return key.length > 0 ? key : null;
175  }
176
177  try {
178    classify(path);
179  } catch {
180    return null;
181  }
182  return path;
183}
184
185/**
186 * Only /media/ keys are responsive: static assets never pass through the transform route, so their
187 * widths would 404. The link goes to the unsized original, which srcset never serves.
188 *
189 * @param {string} src
190 */
191function imageProps(src) {
192  if (!src.startsWith("/media/")) return null;
193  const key = src.slice("/media/".length);
194  return { srcSet: contentSrcSet(key), sizes: CONTENT_SIZES, href: `/media/${key}` };
195}
196
197const SITE_OPTIONS = {
198  media: { keyOf: mediaKeyOf, imageProps },
199  packs: [editorialPack({ assetPrefix: ASSET_PREFIX })],
200};
201
202/**
203 * @param {object} options
204 * @param {string} options.file label used in error messages
205 * @param {string} options.body markdown with frontmatter already stripped
206 * @param {(src: string) => Promise<{ width: number, height: number }>} options.resolveImage
207 */
208export async function renderBody({ file, body, resolveImage }) {
209  const { html, toc, hasMath, diagrams, mediaRefs, blockedUrls } = await render({
210    file,
211    body,
212    resolveImage,
213    options: { ...SITE_OPTIONS, highlight: getHighlight() },
214  });
215  return { html, toc, hasMath, diagrams, mediaRefs, blockedUrls };
216}
217
218/**
219 * @param {object} options
220 * @param {string} options.file path or label, used in error messages
221 * @param {string} options.raw the whole file including frontmatter
222 * @param {string} options.expectedSlug slug the filename implies
223 * @param {(src: string) => Promise<{ width: number, height: number }>} options.resolveImage
224 */
225export async function renderPost({ file, raw, expectedSlug, resolveImage }) {
226  const parsed = matter(raw);
227  const result = frontmatterSchema.safeParse(parsed.data);
228  if (!result.success) {
229    const detail = result.error.issues
230      .map((issue) => `${issue.path.join(".") || "(root)"} ${issue.message}`)
231      .join("; ");
232    throw new ContentError(file, `invalid frontmatter: ${detail}`);
233  }
234  const fm = result.data;
235
236  if (fm.slug !== expectedSlug) {
237    throw new ContentError(
238      file,
239      `slug "${fm.slug}" does not match the filename "${expectedSlug}"`,
240    );
241  }
242
243  const { html, toc, diagrams, mediaRefs, hasMath } = await renderBody({
244    file,
245    body: parsed.content,
246    resolveImage,
247  });
248
249  let cover = null;
250  if (fm.cover) {
251    const { width, height } = await resolveImage(fm.cover.src);
252    cover = { src: fm.cover.src, alt: fm.cover.alt, width, height };
253    // The body renderer never sees a frontmatter cover; without this it would be listed as unused.
254    const coverKey = mediaKeyOf(fm.cover.src);
255    if (coverKey) {
256      mediaRefs.push({ key: coverKey, form: "frontmatter-cover", detail: "cover image" });
257    }
258  }
259
260  return {
261    slug: fm.slug,
262    title: fm.title,
263    description: fm.description,
264    date: fm.date,
265    publishAt: fm.publish_at ?? `${fm.date}T00:00:00.000Z`,
266    draft: fm.draft,
267    tags: fm.tags,
268    cover,
269    featured: fm.featured,
270    series: fm.series ?? null,
271    part: fm.part ?? null,
272    writingStatus: fm.writing_status ?? null,
273    assumedAudience: fm.assumed_audience ?? null,
274    keyTakeaways: fm.key_takeaways ?? null,
275    changelog: fm.changelog ?? null,
276    furtherReading: fm.further_reading,
277    ogTitle: fm.og_title ?? null,
278    ogDescription: fm.og_description ?? null,
279    updated: fm.updated ?? null,
280    readingTimeMinutes: readingTimeMinutes(parsed.content),
281    // Never stored: it rides only so check:content can compare it with htmlHasMath.
282    hasMath,
283    toc,
284    diagrams,
285    mediaRefs,
286    markdown: parsed.content,
287    html,
288    sourcePath: postPath(fm.slug),
289    // Over the whole raw file, frontmatter included, because that is the blob git stores.
290    sourceBlobSha: await gitBlobSha(raw),
291    renderHash: await renderHash(html),
292  };
293}