@taprootio/site-authoring 0.14.1 → 0.16.0

package/src/typed-page-reference.js

@@ -4,6 +4,7 @@ import {
   PLACE_REVIEW_RATINGS,
   TEMPLATE_ALBUM,
   TEMPLATE_ARTICLE,
+  TEMPLATE_GENERATED,
   TEMPLATE_PLACE_REVIEW,
   TEMPLATE_RECIPE,
 } from "./typed-pages.js";
@@ -35,6 +36,14 @@ const FIELD_HELP = Object.freeze({
     required: true,
     description: "Selects the template. A page's template never changes after it is created.",
   },
+  author: {
+    type: "string",
+    required: false,
+    description:
+      "Credits the page to a site author by handle (jane-doe) or to a site member who can create pages by email "
+      + "address. Pages are authorless unless you name one, and an author already on the page is never replaced. "
+      + "'authors list' shows who can be named; 'authors add' creates a site author without an account.",
+  },
   displayDate: {
     type: "YYYY-MM-DD",
     required: false,
@@ -66,8 +75,15 @@ const FIELD_HELP = Object.freeze({
     type: "UUID",
     required: true,
     description:
-      "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record; this "
-      + "CLI does not search for places.",
+      "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record. Find "
+      + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'.",
+  },
+  place: {
+    type: "UUID",
+    required: false,
+    description:
+      "The Taproot place an article or album is about, found the same way as a place review's placeId. Omit it to "
+      + "leave the page's place as it is; an empty value clears it.",
   },
   rating: {
     type: Object.keys(PLACE_REVIEW_RATINGS).join(" | "),
@@ -172,7 +188,7 @@ const TYPE_DETAILS = Object.freeze({
       { displayDate: "2023-06-18", coverImageId: EXAMPLE_IMAGE_ID },
       { body: PARAGRAPH("We parked at the end of the gravel road and walked the last mile.") },
     ),
-    dataFields: ["body: ProseMirror document (required, not empty)"],
+    dataFields: ["body: ProseMirror document (required, not empty)", "place: UUID of a Taproot place (optional; \"\" clears it)"],
   },
   [TEMPLATE_RECIPE]: {
     displayName: "Recipe",
@@ -240,6 +256,7 @@ const TYPE_DETAILS = Object.freeze({
       "introductionBody: ProseMirror document (optional)",
       "images: [{ imageId, caption, width, height }]; at least one",
       "seamless: true | false and borderWidth: 0-20 (optional; omitted inherits the site default)",
+      "place: UUID of a Taproot place (optional; \"\" clears it)",
     ],
   },
   [TEMPLATE_PLACE_REVIEW]: {
@@ -262,48 +279,106 @@ const TYPE_DETAILS = Object.freeze({
       "body: ProseMirror document (required, not empty)",
     ],
   },
+  [TEMPLATE_GENERATED]: {
+    displayName: "Generated page",
+    summary:
+      "A listing Taproot generates from the site's content: a tag, the tags index, a published year or month, a place "
+      + "archive, or a folder. You cannot create one; you customize its title, breadcrumb, description and introduction.",
+    documentExample: documentExample(
+      TEMPLATE_GENERATED,
+      {},
+      {
+        kind: "GENERATED_PAGE_KIND_TAG",
+        tagId: "0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a",
+        year: 0,
+        month: 0,
+        countryCode: "",
+        regionCode: "",
+        citySlug: "",
+        categorySlug: "",
+        customTitle: "Trail notes",
+        breadcrumbTitle: "",
+        customDescription: "Field notes from the trails I walk most often.",
+        introductionBody: PARAGRAPH("Everything I have written about walking."),
+      },
+    ),
+    dataFields: [
+      "kind and the identity fields (tagId, year, month, countryCode, regionCode, citySlug, categorySlug): what the "
+      + "page is, written by pull. Leave them as pulled; a push that changes them is refused (pages.generated_identity)",
+      "customTitle: string; empty uses the generated title (the page's reader-facing title)",
+      "breadcrumbTitle: string; empty uses the generated label (used on pages beneath this one)",
+      "customDescription: string, at most 1000 characters, about 160 shown in search results; empty uses the "
+      + "introduction's first paragraph, else the generated description",
+      "introductionBody: ProseMirror document (optional), shown above the generated listing",
+    ],
+    note:
+      "The manifest's title and description for a generated page are what the site reports, recorded for reference; "
+      + "edit customTitle and customDescription here (or with 'pages meta set'), not the manifest. "
+      + "pages push updates the page and refuses to create one (pages.generated_create), move it (pages.generated_move) "
+      + "or change its identity (pages.generated_identity). The site derives the page's title and description from "
+      + "customTitle, customDescription and introductionBody, so what a push sends for them is ignored. A source the site "
+      + "no longer has a page for is reported and skipped by a whole-workspace push.",
+  },
 });
 
 export const TYPED_PAGE_TYPES = Object.freeze(Object.keys(TYPE_DETAILS));
+/** The templates a Markdown source can declare: every typed page but the update-only generated one. */
+export const MARKDOWN_PAGE_TYPES = Object.freeze(TYPED_PAGE_TYPES.filter((type) => type !== TEMPLATE_GENERATED));
 
 function typedReference(type) {
   const details = TYPE_DETAILS[type];
+  const generated = type === TEMPLATE_GENERATED;
   return Object.freeze({
     type,
     displayName: details.displayName,
     summary: details.summary,
     workspace: Object.freeze({
       directory: `${PAGES_DIRECTORY}/`,
-      sourceRule:
-        `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
-        + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
-        + "immutable after creation: pages push refuses a source whose template differs from the live page's "
-        + "(pages.template_immutable).",
-      pull:
-        "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
-        + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
+      sourceRule: generated
+        ? `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "A generated page exists only because the site's content produces it, so its source exists only after "
+          + "'pull' and is never created by hand."
+        : `One source file per page, exactly as for a free-form page: see '${CLI_BINARY_NAME} help page free-form'. `
+          + "The template is declared in the source (front matter 'template', or the .pm.json 'template' field) and is "
+          + "immutable after creation: pages push refuses a source whose template differs from the live page's "
+          + "(pages.template_immutable).",
+      pull: generated
+        ? "pull writes each generated page as a .pm.json document, byte-stable across pulls, and keeps your edits to it "
+          + "when the site's copy has not changed. A change made on the site since the last pull is reported as a conflict."
+        : "pull writes each page of this template as a .pm.json document, byte-stable across pulls. A page you authored as "
+          + "Markdown keeps its Markdown source, and a change made on the site since the last pull is reported as a conflict.",
       formats: Object.freeze([
-        Object.freeze({
+        ...(generated ? [] : [Object.freeze({
           extension: ".md",
           purpose: "Author the page as Markdown with front matter.",
           metadata: Object.freeze(
             frontMatterKeysFor(type).map((name) => Object.freeze({ name, ...FIELD_HELP[name] })),
           ),
-        }),
+        })]),
         Object.freeze({
           extension: ".pm.json",
-          purpose:
-            "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
+          purpose: generated
+            ? "The pulled form, and the only one: { template, data }. Path comes from the manifest; title and description "
+              + "are the custom ones in data."
+            : "The pulled form: { template, displayDate?, coverImageId?, data }. Title, path and description come from the manifest.",
           dataFields: Object.freeze(details.dataFields),
         }),
       ]),
     }),
-    markdown: Object.freeze({ body: details.body, example: details.markdownExample }),
+    ...(generated ? {} : { markdown: Object.freeze({ body: details.body, example: details.markdownExample }) }),
     document: Object.freeze({ example: details.documentExample, ...(details.note ? { note: details.note } : {}) }),
     workflow: Object.freeze([
-      Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." }),
+      ...(generated
+        ? [Object.freeze({
+          command: `${CLI_BINARY_NAME} pull, then pages meta set <path> --title/--description`,
+          result: "Pull the page, then set its custom title or description (or edit the .pm.json).",
+        })]
+        : [Object.freeze({ command: `${CLI_BINARY_NAME} media upload`, result: "Upload cover and album images first." })]),
       Object.freeze({ command: `${CLI_BINARY_NAME} validate`, result: "Check the workspace before sending anything." }),
-      Object.freeze({ command: `${CLI_BINARY_NAME} pages push`, result: "Create or update an unapproved draft." }),
+      Object.freeze({
+        command: `${CLI_BINARY_NAME} pages push`,
+        result: generated ? "Update the generated page's unapproved draft." : "Create or update an unapproved draft.",
+      }),
       Object.freeze({
         command: `${CLI_BINARY_NAME} approve, deploy --staging, deploy --production`,
         result: "Stage, review and promote, as for any page.",
@@ -327,9 +402,10 @@ function formatField(field) {
 export function formatTypedPageReference(page) {
   const markdown = page.workspace.formats.find((format) => format.extension === ".md");
   const json = page.workspace.formats.find((format) => format.extension === ".pm.json");
-  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\nMarkdown front matter:\n${
-    markdown.metadata.map(formatField).join("\n")
-  }\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n.pm.json (${json.purpose})\n  data:\n${
+  const markdownSection = markdown === undefined
+    ? ""
+    : `Markdown front matter:\n${markdown.metadata.map(formatField).join("\n")}\n\nMarkdown body: ${page.markdown.body}\n\nMarkdown example:\n${page.markdown.example}\n`;
+  return `${page.displayName} (${page.type})\n${page.summary}\n\nWorkspace (${page.workspace.directory}):\n  source rule           ${page.workspace.sourceRule}\n  pull                  ${page.workspace.pull}\n\n${markdownSection}.pm.json (${json.purpose})\n  data:\n${
     json.dataFields.map((field) => `    ${field}`).join("\n")
   }\n${page.document.note === undefined ? "" : `  ${page.document.note}\n`}\n.pm.json example:\n${
     JSON.stringify(page.document.example, null, 2)

package/src/typed-pages.js

@@ -1,6 +1,7 @@
 import { FREE_FORM_TEMPLATE_VERSION, TEMPLATE_TYPE_FREE_FORM } from "./api.js";
 import { isVideoEmbedId } from "./content/video-embed-url.js";
 import { SiteAuthoringError } from "./errors.js";
+import { requireDescriptionLength } from "./page-metadata.js";
 
 /**
  * The authored page templates (TR00893).
@@ -29,6 +30,12 @@ export const TEMPLATE_ARTICLE = "article";
 export const TEMPLATE_RECIPE = "recipe";
 export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
+/**
+ * A page Taproot generates (a tag, a month, a folder). It is update-only: the
+ * owner's title, breadcrumb, description and introduction are authored, and
+ * pages push refuses to create one or to change what it is (TR01195).
+ */
+export const TEMPLATE_GENERATED = "generated";
 
 /** Wire identity and the `PageTemplate` member that carries each template's data. */
 export const PAGE_TEMPLATES = Object.freeze({
@@ -37,12 +44,13 @@ export const PAGE_TEMPLATES = Object.freeze({
   [TEMPLATE_RECIPE]: Object.freeze({ wireType: "TEMPLATE_TYPE_RECIPE", dataKey: "recipeData" }),
   [TEMPLATE_ALBUM]: Object.freeze({ wireType: "TEMPLATE_TYPE_ALBUM", dataKey: "albumData" }),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze({ wireType: "TEMPLATE_TYPE_PLACE_REVIEW", dataKey: "placeReviewData" }),
+  [TEMPLATE_GENERATED]: Object.freeze({ wireType: "TEMPLATE_TYPE_GENERATED", dataKey: "generatedPageData" }),
 });
 
 export const PAGE_TEMPLATE_NAMES = Object.freeze(Object.keys(PAGE_TEMPLATES));
 
 /** Front-matter fields every template accepts. */
-export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template"]);
+export const SHARED_FRONT_MATTER_KEYS = Object.freeze(["title", "path", "description", "template", "author"]);
 
 /**
  * The page-level fields the other templates add. A free-form page's source is
@@ -54,7 +62,8 @@ const TYPED_PAGE_FRONT_MATTER_KEYS = Object.freeze(["displayDate", "coverImage"]
 /** Front-matter fields only one template accepts. Others are refused for it. */
 const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
   [TEMPLATE_FREE_FORM]: Object.freeze([]),
-  [TEMPLATE_ARTICLE]: TYPED_PAGE_FRONT_MATTER_KEYS,
+  // `place` is the Taproot place id an article or album is about (TR01003).
+  [TEMPLATE_ARTICLE]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "place"]),
   [TEMPLATE_RECIPE]: Object.freeze([
     ...TYPED_PAGE_FRONT_MATTER_KEYS,
     "prepTimeMinutes",
@@ -64,8 +73,10 @@ const TEMPLATE_FRONT_MATTER_KEYS = Object.freeze({
     "recipeCuisine",
     "cookingMethod",
   ]),
-  [TEMPLATE_ALBUM]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "seamless", "borderWidth"]),
+  [TEMPLATE_ALBUM]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "seamless", "borderWidth", "place"]),
   [TEMPLATE_PLACE_REVIEW]: Object.freeze([...TYPED_PAGE_FRONT_MATTER_KEYS, "placeId", "rating"]),
+  // Generated pages have no Markdown form.
+  [TEMPLATE_GENERATED]: Object.freeze([]),
 });
 
 export const FRONT_MATTER_KEYS = Object.freeze(
@@ -89,10 +100,58 @@ const RATING_NAME_BY_WIRE = Object.freeze(
 // Not `isCanonicalUuid`: that accepts only RFC 4122 versions 1 to 5, and place
 // and image ids are minted by the server, which is free to use any version.
 const IDENTIFIER = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** An id the server minted, of any UUID version. */
+export const IMAGE_IDENTIFIER = IDENTIFIER;
 const DISPLAY_DATE = /^\d{4}-\d{2}-\d{2}$/u;
 const ALBUM_IMAGES_HEADING = "images";
 const RECIPE_HEADINGS = Object.freeze(["ingredients", "instructions"]);
 
+/** The generated page kinds the site reports, as the API names them (never the unknown kind). */
+export const GENERATED_PAGE_KINDS = Object.freeze([
+  "GENERATED_PAGE_KIND_TAG",
+  "GENERATED_PAGE_KIND_TAGS_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_INDEX",
+  "GENERATED_PAGE_KIND_PUBLISHED_YEAR",
+  "GENERATED_PAGE_KIND_PUBLISHED_MONTH",
+  "GENERATED_PAGE_KIND_PLACES_INDEX",
+  "GENERATED_PAGE_KIND_PLACES_COUNTRY",
+  "GENERATED_PAGE_KIND_PLACES_STATE",
+  "GENERATED_PAGE_KIND_PLACES_CITY",
+  "GENERATED_PAGE_KIND_PLACES_CATEGORY",
+  "GENERATED_PAGE_KIND_FOLDER_INDEX",
+]);
+/** What a generated page is: system-managed, so a push must send it back unchanged. */
+export const GENERATED_IDENTITY_KEYS = Object.freeze([
+  "kind",
+  "tagId",
+  "year",
+  "month",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+]);
+const GENERATED_KEYS = [
+  ...GENERATED_IDENTITY_KEYS,
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+  "introductionBody",
+];
+const GENERATED_TEXT_KEYS = [
+  "tagId",
+  "countryCode",
+  "regionCode",
+  "citySlug",
+  "categorySlug",
+  "customTitle",
+  "breadcrumbTitle",
+  "customDescription",
+];
+const GENERATED_MAXIMUM_YEAR = 9999;
+const GENERATED_MAXIMUM_MONTH = 12;
+const EMPTY_DOCUMENT = Object.freeze({ type: "doc", content: Object.freeze([]) });
+
 function fail(code, message, field) {
   return new SiteAuthoringError(code, message, { field });
 }
@@ -113,6 +172,32 @@ export function isAuthorableTemplateType(wireType) {
   return templateNameForWireType(wireType) !== undefined;
 }
 
+/** Whether a wire `templateType` is a generated page. */
+export function isGeneratedTemplateType(wireType) {
+  return wireType === PAGE_TEMPLATES[TEMPLATE_GENERATED].wireType;
+}
+
+/** The system-managed fields of a generated page's `data`, which the manifest records and a push must not change. */
+export function generatedIdentity(data) {
+  return Object.fromEntries(GENERATED_IDENTITY_KEYS.map((key) => [key, data[key]]));
+}
+
+/** The names of the identity fields that differ, for a message. */
+export function changedGeneratedIdentity(recorded, data) {
+  return GENERATED_IDENTITY_KEYS.filter((key) => recorded[key] !== data[key]);
+}
+
+/** The title a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageTitle(data, reportedTitle) {
+  // Trimmed as Taproot trims it, or a padded title would never match the key a pull recorded.
+  return data.customTitle.trim() || reportedTitle;
+}
+
+/** The description a generated page is sent with: the owner's, else the one the site last reported. */
+export function generatedPageDescription(data, reportedDescription) {
+  return data.customDescription.trim() === "" ? reportedDescription : data.customDescription.trim();
+}
+
 /** The template a canonical workspace document represents. */
 export function documentTemplate(document_) {
   return isPlainObject(document_) && typeof document_.template === "string" && document_.type === undefined
@@ -230,7 +315,7 @@ const RECIPE_KEYS = [
   "recipeCuisine",
   "cookingMethod",
 ];
-const ALBUM_KEYS = ["introductionBody", "images", "seamless", "borderWidth"];
+const ALBUM_KEYS = ["introductionBody", "images", "seamless", "borderWidth", "place"];
 const ALBUM_IMAGE_KEYS = ["imageId", "caption", "width", "height"];
 const ALBUM_MAXIMUM_BORDER_WIDTH = 20;
 const MAXIMUM_MINUTES = 100_000;
@@ -257,8 +342,24 @@ function canonicalIngredient(value) {
  * server's JSON omits defaults and may gain fields).
  */
 const DATA_BUILDERS = Object.freeze({
-  [TEMPLATE_ARTICLE]: (raw) => ({ body: raw.body }),
+  [TEMPLATE_ARTICLE]: (raw) => definedEntries([["body", raw.body], ["place", raw.place]]),
   [TEMPLATE_PLACE_REVIEW]: (raw) => ({ placeId: raw.placeId, rating: raw.rating, body: raw.body }),
+  // Defaults are written out, so a page with no custom title reads the same on every pull.
+  [TEMPLATE_GENERATED]: (raw) =>
+    definedEntries([
+      ["kind", raw.kind],
+      ["tagId", raw.tagId ?? ""],
+      ["year", raw.year ?? 0],
+      ["month", raw.month ?? 0],
+      ["countryCode", raw.countryCode ?? ""],
+      ["regionCode", raw.regionCode ?? ""],
+      ["citySlug", raw.citySlug ?? ""],
+      ["categorySlug", raw.categorySlug ?? ""],
+      ["customTitle", raw.customTitle ?? ""],
+      ["breadcrumbTitle", raw.breadcrumbTitle ?? ""],
+      ["customDescription", raw.customDescription ?? ""],
+      ["introductionBody", raw.introductionBody],
+    ]),
   [TEMPLATE_ALBUM]: (raw) =>
     definedEntries([
       ["introductionBody", raw.introductionBody],
@@ -273,6 +374,7 @@ const DATA_BUILDERS = Object.freeze({
       ],
       ["seamless", raw.seamless],
       ["borderWidth", raw.borderWidth],
+      ["place", raw.place],
     ]),
   [TEMPLATE_RECIPE]: (raw) =>
     definedEntries([
@@ -303,12 +405,22 @@ const DATA_BUILDERS = Object.freeze({
 const OPTIONAL_INTRODUCTION = (value, file, path) =>
   value === undefined ? undefined : requireDocument(value, file, path);
 
+/** A Taproot place id, or "" to clear the page's place; omitted leaves it as the site holds it. */
+function optionalPlace(value, file, path) {
+  if (value === undefined || value === "") return value;
+  requireIdentifier(value, file, path);
+  return value;
+}
+
 /** Strict checks on a source document's `data`, returning it in canonical form. */
 function canonicalSourceData(template, data, file) {
   const path = "data";
   if (template === TEMPLATE_ARTICLE) {
-    requireKeys(data, ["body"], file, path);
-    return DATA_BUILDERS[template]({ body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }) });
+    requireKeys(data, ["body", "place"], file, path);
+    return DATA_BUILDERS[template]({
+      body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }),
+      place: optionalPlace(data.place, file, `${path}.place`),
+    });
   }
   if (template === TEMPLATE_PLACE_REVIEW) {
     requireKeys(data, ["placeId", "rating", "body"], file, path);
@@ -325,6 +437,30 @@ function canonicalSourceData(template, data, file) {
       body: requireDocument(data.body, file, `${path}.body`, { nonEmpty: true }),
     });
   }
+  if (template === TEMPLATE_GENERATED) {
+    requireKeys(data, GENERATED_KEYS, file, path);
+    if (!GENERATED_PAGE_KINDS.includes(data.kind)) {
+      throw fail(
+        "pages.document_shape",
+        `'${file}' ${path}.kind must be one of ${GENERATED_PAGE_KINDS.join(", ")}.`,
+        file,
+      );
+    }
+    for (const key of GENERATED_TEXT_KEYS) {
+      if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
+    }
+    if (data.tagId !== undefined && data.tagId !== "") requireIdentifier(data.tagId, file, `${path}.tagId`);
+    if (data.year !== undefined) requireCount(data.year, file, `${path}.year`, GENERATED_MAXIMUM_YEAR);
+    if (data.month !== undefined) requireCount(data.month, file, `${path}.month`, GENERATED_MAXIMUM_MONTH);
+    // The API trims a description, so the length that counts is the trimmed one.
+    const customDescription = data.customDescription?.trim();
+    requireDescriptionLength(customDescription, `${file}:${path}.customDescription`);
+    return DATA_BUILDERS[template]({
+      ...data,
+      customDescription,
+      introductionBody: OPTIONAL_INTRODUCTION(data.introductionBody, file, `${path}.introductionBody`),
+    });
+  }
   if (template === TEMPLATE_ALBUM) {
     requireKeys(data, ALBUM_KEYS, file, path);
     const images = requireArray(data.images, file, `${path}.images`);
@@ -348,6 +484,7 @@ function canonicalSourceData(template, data, file) {
     return DATA_BUILDERS[template]({
       ...data,
       introductionBody: OPTIONAL_INTRODUCTION(data.introductionBody, file, `${path}.introductionBody`),
+      place: optionalPlace(data.place, file, `${path}.place`),
     });
   }
   requireKeys(data, RECIPE_KEYS, file, path);
@@ -427,6 +564,14 @@ export function typedDocumentFromJson(parsed, file) {
       file,
     );
   }
+  if (template === TEMPLATE_GENERATED && (parsed.displayDate !== undefined || parsed.coverImageId !== undefined)) {
+    throw fail(
+      "pages.document_shape",
+      `'${file}' is a generated page, which has no displayDate or coverImageId of its own: its document is `
+        + "{ template, data }.",
+      file,
+    );
+  }
   const displayDate = parsed.displayDate === undefined ? undefined : requireDisplayDate(parsed.displayDate, file);
   let coverImageId;
   if (parsed.coverImageId !== undefined) {
@@ -451,12 +596,15 @@ const presentIntroduction = (value) => {
   return doc !== undefined && Array.isArray(doc.content) && doc.content.length === 0 ? undefined : doc;
 };
 const listOf = (value) => (Array.isArray(value) ? value : []);
+// The site stores a page's place with its name and address; the workspace keeps only the id.
+const pagePlaceId = (value) =>
+  isPlainObject(value) && typeof value.placeId === "string" && value.placeId !== "" ? value.placeId : undefined;
 
 /** Lenient projections of what the site returned for each template's data. */
 const PAGE_PROJECTIONS = Object.freeze({
   [TEMPLATE_ARTICLE]: (raw) => {
     const body = presentDocument(raw.body);
-    return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_ARTICLE]({ body });
+    return body === undefined ? undefined : DATA_BUILDERS[TEMPLATE_ARTICLE]({ body, place: pagePlaceId(raw.place) });
   },
   [TEMPLATE_PLACE_REVIEW]: (raw) => {
     const body = presentDocument(raw.body);
@@ -464,12 +612,24 @@ const PAGE_PROJECTIONS = Object.freeze({
     if (body === undefined || rating === undefined || typeof raw.placeId !== "string") return undefined;
     return DATA_BUILDERS[TEMPLATE_PLACE_REVIEW]({ placeId: raw.placeId, rating, body });
   },
+  // A kind this package does not know cannot be pushed back safely, so it is not readable here.
+  [TEMPLATE_GENERATED]: (raw) =>
+    GENERATED_PAGE_KINDS.includes(raw.kind)
+      ? DATA_BUILDERS[TEMPLATE_GENERATED]({
+        kind: raw.kind,
+        ...Object.fromEntries(GENERATED_TEXT_KEYS.map((key) => [key, typeof raw[key] === "string" ? raw[key] : ""])),
+        year: Number.isSafeInteger(raw.year) ? raw.year : 0,
+        month: Number.isSafeInteger(raw.month) ? raw.month : 0,
+        introductionBody: presentIntroduction(raw.introductionBody),
+      })
+      : undefined,
   [TEMPLATE_ALBUM]: (raw) =>
     DATA_BUILDERS[TEMPLATE_ALBUM]({
       introductionBody: presentIntroduction(raw.introductionBody),
       images: listOf(raw.images).filter((image) => isPlainObject(image) && typeof image.imageId === "string"),
       seamless: typeof raw.seamless === "boolean" ? raw.seamless : undefined,
       borderWidth: Number.isSafeInteger(raw.borderWidth) ? raw.borderWidth : undefined,
+      place: pagePlaceId(raw.place),
     }),
   [TEMPLATE_RECIPE]: (raw) =>
     DATA_BUILDERS[TEMPLATE_RECIPE]({
@@ -505,9 +665,15 @@ export function workspaceDocumentFromPage(page, listedTemplateType) {
   if (name === TEMPLATE_FREE_FORM) return isPlainObject(raw.body) ? raw.body : undefined;
   const data = PAGE_PROJECTIONS[name](raw);
   if (data === undefined) return undefined;
+  // A generated page's date and cover are not part of its source: a push leaves them as the site holds them.
+  const generated = name === TEMPLATE_GENERATED;
   return typedDocument(name, {
-    displayDate: typeof page.displayDate === "string" && page.displayDate !== "" ? page.displayDate : undefined,
-    coverImageId: typeof page.coverImageId === "string" && page.coverImageId !== "" ? page.coverImageId : undefined,
+    displayDate: !generated && typeof page.displayDate === "string" && page.displayDate !== ""
+      ? page.displayDate
+      : undefined,
+    coverImageId: !generated && typeof page.coverImageId === "string" && page.coverImageId !== ""
+      ? page.coverImageId
+      : undefined,
     data,
   });
 }
@@ -539,7 +705,7 @@ export function contentDocuments(document_) {
 /** Whether a push sends `displayDate` for pages of this wire template type (every template but free-form). */
 export function sentDisplayDate(wireType) {
   const name = templateNameForWireType(wireType);
-  return name !== undefined && name !== TEMPLATE_FREE_FORM;
+  return name !== undefined && name !== TEMPLATE_FREE_FORM && name !== TEMPLATE_GENERATED;
 }
 
 // The nodes the API accepts in an album or recipe introduction and in a recipe
@@ -723,7 +889,12 @@ export function wireTemplate(document_) {
     ? { body: document_ }
     : template === TEMPLATE_PLACE_REVIEW
     ? { ...document_.data, rating: PLACE_REVIEW_RATINGS[document_.data.rating] }
-    : document_.data;
+    // The API reads a missing introduction as no document at all, so the empty one is sent.
+    : template === TEMPLATE_GENERATED
+    ? { ...document_.data, introductionBody: document_.data.introductionBody ?? EMPTY_DOCUMENT }
+    : document_.data.place === undefined
+    ? document_.data
+    : { ...document_.data, place: { placeId: document_.data.place } };
   return { templateType: wireType, templateVersion: FREE_FORM_TEMPLATE_VERSION, [dataKey]: data };
 }
 
@@ -939,6 +1110,16 @@ function parseFlag(fields, key, file) {
   return value === "true";
 }
 
+/** Generated pages are edited in their .pm.json source only. */
+export function generatedMarkdownFault(file) {
+  return fail(
+    "pages.generated_markdown",
+    `'${file}' declares the generated template, which has no Markdown form: a generated page is pulled as a `
+      + ".pm.json document and edited there.",
+    file,
+  );
+}
+
 /**
  * Front-matter fields the declared template does not accept.
  *
@@ -967,6 +1148,7 @@ export function templateFrontMatterFault(template, fieldNames, file) {
  * module stays pure.
  */
 export async function typedDocumentFromMarkdown({ template, fields, markdown, file, convert, resolveImage }) {
+  if (template === TEMPLATE_GENERATED) throw generatedMarkdownFault(file);
   const displayDate = fields.has("displayDate") ? requireDisplayDate(fields.get("displayDate"), file) : undefined;
   let coverImageId;
   if (fields.has("coverImage")) {
@@ -975,7 +1157,7 @@ export async function typedDocumentFromMarkdown({ template, fields, markdown, fi
   }
   let data;
   if (template === TEMPLATE_ARTICLE) {
-    data = { body: await convert(markdown) };
+    data = { body: await convert(markdown), place: fields.get("place") };
   } else if (template === TEMPLATE_PLACE_REVIEW) {
     const placeId = fields.get("placeId");
     const rating = fields.get("rating");
@@ -993,6 +1175,7 @@ export async function typedDocumentFromMarkdown({ template, fields, markdown, fi
       ...(await parseAlbumBody(markdown, { file, convert, resolveImage })),
       seamless: parseFlag(fields, "seamless", file),
       borderWidth: parseCount(fields, "borderWidth", file, ALBUM_MAXIMUM_BORDER_WIDTH),
+      place: fields.get("place"),
     };
   } else {
     data = {