app/lib/editor/frontmatter.ts

Functions

Imports

It imports app/lib/editor/intent.mjs, app/lib/error-message.mjs. Imported by app/components/admin/post-editor.tsx, app/components/admin/post-metadata.tsx, app/components/admin/revision-list.tsx, app/lib/admin/posts-actions.server.ts, app/lib/carrel/site-adapter.server.ts, app/lib/editor/action.server.ts, app/lib/editor/preview-link-action.server.ts, app/routes/admin.posts.$slug.edit.tsx, app/routes/admin.posts.$slug.revisions.tsx, app/routes/admin.posts.new.tsx, app/routes/admin.preview.ts.

Source

1import matter from "gray-matter";
2
3import { readIntent } from "./intent.mjs";
4import { draftForIntent } from "capsomer/publish-transition";
5import { errorMessage } from "../error-message.mjs";
6
7// Punctuation-bearing scalars are written as JSON strings: valid YAML double-quoted scalars that
8// escape quotes and colons without a YAML serializer.
9
10export type PostFields = {
11  title: string;
12  slug: string;
13  description: string;
14  date: string;
15  tags: string[];
16  draft: boolean;
17  publishAt: string;
18  coverSrc: string;
19  coverAlt: string;
20  body: string;
21  /** Server-owned but carried: a dropped value would make a published post read as never published. */
22  firstPublished: string;
23  /** Carried through hidden inputs so a browser save cannot erase keys set by hand or by the API. */
24  featured: boolean;
25  series: string;
26  part: string;
27  furtherReading: string;
28  ogTitle: string;
29  ogDescription: string;
30  updated: string;
31};
32
33export const EMPTY_FIELDS: PostFields = {
34  title: "",
35  slug: "",
36  description: "",
37  date: "",
38  tags: [],
39  draft: true,
40  publishAt: "",
41  coverSrc: "",
42  coverAlt: "",
43  body: "",
44  firstPublished: "",
45  featured: false,
46  series: "",
47  part: "",
48  furtherReading: "",
49  ogTitle: "",
50  ogDescription: "",
51  updated: "",
52};
53
54/** Tags as an author types them: comma or newline separated, lower-cased, blanks dropped. */
55export function parseTagInput(input: string) {
56  return input
57    .split(/[,\n]/)
58    .map((t) => t.trim().toLowerCase())
59    .filter(Boolean);
60}
61
62/** Multipart posts turn every newline into CRLF, so save and preview must both normalize here. */
63export function normalizeBody(body: string) {
64  return body.replace(/\r\n/g, "\n").trim();
65}
66
67/**
68 * The further-reading value as entries with string titles and urls, as written. A value that is not a
69 * JSON array is refused, not read as empty: read as empty, the editor would show no rows and a save
70 * would erase the post's further reading.
71 */
72function readingEntries(raw: string): ReadingItem[] {
73  if (!raw.trim()) return [];
74  let parsed: unknown;
75  try {
76    parsed = JSON.parse(raw);
77  } catch (error) {
78    const detail = errorMessage(error);
79    throw new FrontmatterError(
80      `The further reading list did not arrive as JSON (${detail}), so nothing was saved rather ` +
81        `than saving the post without it.`,
82      "furtherReading",
83    );
84  }
85  if (!Array.isArray(parsed)) {
86    throw new FrontmatterError(
87      "The further reading list did not arrive as a list, so nothing was saved rather than saving " +
88        "the post without it.",
89      "furtherReading",
90    );
91  }
92  return parsed.flatMap((item) => {
93    if (!item || typeof item !== "object") return [];
94    const { title, url } = item as Record<string, unknown>;
95    if (typeof title !== "string" || typeof url !== "string") return [];
96    return [{ title, url }];
97  });
98}
99
100/**
101 * Loose on purpose, since the schema judges the content. A half entry is dropped: it would fail
102 * the save on data the author never typed.
103 */
104function parseFurtherReading(raw: string) {
105  return readingEntries(raw).flatMap(({ title, url }) =>
106    title.trim() && url.trim() ? [{ title: title.trim(), url: url.trim() }] : [],
107  );
108}
109
110/** A field value that cannot be written into frontmatter without changing its structure. */
111export class FrontmatterError extends Error {
112  field: string;
113
114  constructor(message: string, field: string) {
115    super(message);
116    this.name = "FrontmatterError";
117    this.field = field;
118  }
119}
120
121// What would end or reshape a plain YAML scalar: a newline, a leading indicator, `: ` or ` #`, or edge
122// whitespace. These keys stay unquoted because quoting changes their type (a date, a number), so an
123// unsafe value is refused by name rather than written.
124const UNSAFE_PLAIN = /[\r\n]|^[\s\-?:,[\]{}#&*!|>'"%@`]|:\s|\s#|:$|\s$/;
125
126function plain(field: keyof PostFields, key: string, value: string) {
127  if (UNSAFE_PLAIN.test(value)) {
128    throw new FrontmatterError(
129      `The ${key} ${JSON.stringify(value)} cannot be written into the frontmatter as it is: it ` +
130        `contains a newline or YAML punctuation that would change the file's structure.`,
131      field,
132    );
133  }
134  return value;
135}
136
137// A tag inside the flow sequence stays bare when it is plainly a word, so existing files keep their
138// bytes; anything else (a comma, a bracket, a `#`, a quote) is written as a JSON string.
139const BARE_TAG = /^[a-z0-9][a-z0-9._+-]*( [a-z0-9._+-]+)*$/;
140
141function tagScalar(tag: string) {
142  return BARE_TAG.test(tag) ? tag : JSON.stringify(tag);
143}
144
145export function serializePost(fields: PostFields) {
146  const lines = [
147    "---",
148    `title: ${JSON.stringify(fields.title)}`,
149    `slug: ${plain("slug", "slug", fields.slug)}`,
150    `description: ${JSON.stringify(fields.description)}`,
151    `date: ${plain("date", "date", fields.date)}`,
152    `tags: [${fields.tags.map(tagScalar).join(", ")}]`,
153    `draft: ${fields.draft ? "true" : "false"}`,
154  ];
155
156  if (fields.publishAt.trim()) {
157    lines.push(`publish_at: ${JSON.stringify(fields.publishAt.trim())}`);
158  }
159
160  if (fields.firstPublished.trim()) {
161    lines.push(
162      `first_published: ${plain("firstPublished", "first_published", fields.firstPublished.trim())}`,
163    );
164  }
165
166  if (fields.coverSrc.trim()) {
167    lines.push("cover:");
168    lines.push(`  src: ${plain("coverSrc", "cover src", fields.coverSrc.trim())}`);
169    lines.push(`  alt: ${JSON.stringify(fields.coverAlt)}`);
170  }
171
172  // Carried keys are emitted only when set, so a post that never used one is byte-identical.
173  if (fields.featured) lines.push("featured: true");
174  if (fields.series.trim()) {
175    lines.push(`series: ${JSON.stringify(fields.series.trim())}`);
176  }
177  // Unquoted: `part` is a number in the schema and a quoted scalar is a string.
178  if (fields.part.trim()) lines.push(`part: ${plain("part", "part", fields.part.trim())}`);
179  if (fields.ogTitle.trim()) {
180    lines.push(`og_title: ${JSON.stringify(fields.ogTitle.trim())}`);
181  }
182  if (fields.ogDescription.trim()) {
183    lines.push(`og_description: ${JSON.stringify(fields.ogDescription.trim())}`);
184  }
185  if (fields.updated.trim()) {
186    lines.push(`updated: ${plain("updated", "updated", fields.updated.trim())}`);
187  }
188
189  const reading = parseFurtherReading(fields.furtherReading);
190  if (reading.length > 0) {
191    lines.push("further_reading:");
192    for (const item of reading) {
193      lines.push(`  - title: ${JSON.stringify(item.title)}`);
194      lines.push(`    url: ${JSON.stringify(item.url)}`);
195    }
196  }
197
198  lines.push("---", "");
199
200  // One blank line after the frontmatter and one trailing newline, so repeated saves do not drift.
201  return `${lines.join("\n")}\n${normalizeBody(fields.body)}\n`;
202}
203
204export function parsePost(raw: string): PostFields {
205  const parsed = matter(raw);
206  const data = parsed.data as Record<string, unknown>;
207
208  const asString = (value: unknown) => {
209    if (value instanceof Date) return value.toISOString().slice(0, 10);
210    return value === undefined || value === null ? "" : String(value);
211  };
212
213  const cover = (data.cover ?? {}) as Record<string, unknown>;
214
215  return {
216    title: asString(data.title),
217    slug: asString(data.slug),
218    description: asString(data.description),
219    date: asString(data.date),
220    tags: Array.isArray(data.tags) ? data.tags.map((t) => String(t)) : [],
221    draft: data.draft === true,
222    publishAt: data.publish_at instanceof Date
223      ? data.publish_at.toISOString()
224      : asString(data.publish_at),
225    coverSrc: asString(cover.src),
226    coverAlt: asString(cover.alt),
227    body: parsed.content.replace(/^\n+/, ""),
228    firstPublished: asString(data.first_published),
229    featured: data.featured === true,
230    series: asString(data.series),
231    part: asString(data.part),
232    // JSON, because a FormData value is a string.
233    furtherReading: Array.isArray(data.further_reading)
234      ? JSON.stringify(data.further_reading)
235      : "",
236    ogTitle: asString(data.og_title),
237    ogDescription: asString(data.og_description),
238    updated: asString(data.updated),
239  };
240}
241
242export const FR_CONTROL = "frControl";
243export const FR_TITLE = "frTitle";
244export const FR_URL = "frUrl";
245export const FR_INTERNAL = "frInternal";
246
247/** Mirrors the schema's rule for internal links. */
248const INTERNAL_PREFIX = "/writing/";
249
250type ReadingItem = { title: string; url: string };
251
252export function splitReading(raw: string) {
253  const items = readingEntries(raw);
254  return {
255    external: items.filter((item) => !item.url.startsWith(INTERNAL_PREFIX)),
256    internal: items.filter((item) => item.url.startsWith(INTERNAL_PREFIX)),
257  };
258}
259
260/**
261 * The hidden marker separates "the author removed every row" from "the control never rendered",
262 * which both arrive as no fields. A half row is kept so the schema refuses it by name.
263 */
264function furtherReadingFromForm(form: FormData, carried: string): string {
265  if (form.get(FR_CONTROL) === null) return carried;
266
267  const titles = form.getAll(FR_TITLE).map((v) => String(v));
268  const urls = form.getAll(FR_URL).map((v) => String(v));
269  const items: ReadingItem[] = [];
270
271  for (let i = 0; i < Math.max(titles.length, urls.length); i += 1) {
272    const title = (titles[i] ?? "").trim();
273    const url = (urls[i] ?? "").trim();
274    if (!title && !url) continue;
275    items.push({ title, url });
276  }
277
278  // Each checkbox value carries slug and title as JSON, so the form's field names do not grow with
279  // the blog. The title is a snapshot from when the box was ticked.
280  for (const value of form.getAll(FR_INTERNAL)) {
281    let slug = "";
282    let title = "";
283    try {
284      const parsed: unknown = JSON.parse(String(value));
285      if (parsed && typeof parsed === "object") {
286        const record = parsed as Record<string, unknown>;
287        slug = typeof record.slug === "string" ? record.slug : "";
288        title = typeof record.title === "string" ? record.title : "";
289      }
290    } catch {
291      continue;
292    }
293    if (!slug) continue;
294    items.push({ title: title.trim() || slug, url: `${INTERNAL_PREFIX}${slug}` });
295  }
296
297  return items.length > 0 ? JSON.stringify(items) : "";
298}
299
300export function fieldsFromForm(form: FormData): PostFields {
301  const get = (key: string) => String(form.get(key) ?? "");
302  return {
303    title: get("title"),
304    slug: get("slug").trim().toLowerCase(),
305    description: get("description"),
306    date: get("date"),
307    tags: parseTagInput(get("tags")),
308    // From the button pressed, not a hidden field, so it works without script. Unknown means draft.
309    draft: draftForIntent(readIntent(form)),
310    publishAt: get("publishAt"),
311    coverSrc: get("coverSrc"),
312    coverAlt: get("coverAlt"),
313    body: get("body"),
314    firstPublished: get("firstPublished"),
315    // The hidden "false" always submits and a ticked box adds "true" after it, so the LAST value wins;
316    // form.get() returns the first, which would make the checkbox do nothing.
317    featured: (() => {
318      const all = form.getAll("featured").map((v) => String(v));
319      return all.length > 0 && all[all.length - 1] === "true";
320    })(),
321    series: get("series"),
322    part: get("part"),
323    furtherReading: furtherReadingFromForm(form, get("furtherReading")),
324    ogTitle: get("ogTitle"),
325    ogDescription: get("ogDescription"),
326    updated: get("updated"),
327  };
328}