@bendyline/docblocks 2.7.8 → 2.7.10

package/THIRD_PARTY_NOTICES.txt

@@ -14,8 +14,8 @@ This notice is included in the published npm tarball. Transitive packages instal
 
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
-| @bendyline/squisq | 2.13.6 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-graph | 2.13.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.13.9 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-graph | 2.13.1 | MIT | https://github.com/bendyline/squisq |
 | @types/debug | 4.1.12 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/hast | 3.0.4 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
 | @types/katex | 0.16.8 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped |
@@ -133,7 +133,7 @@ This notice is included in the published npm tarball. Transitive packages instal
 Package-local license, copying, and notice files are reproduced below. Where a published package omits its repository license, the reviewed aggregate or README identified in `Source files` supplies the retained material.
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0, @bendyline/squisq@2.13.6
+Components: @bendyline/squisq-graph@2.13.1, @bendyline/squisq@2.13.9
 Source files: node_modules/@bendyline/squisq-graph/LICENSE, node_modules/@bendyline/squisq/LICENSE
 ==============================================================================
 MIT License
@@ -159,7 +159,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0
+Components: @bendyline/squisq-graph@2.13.1
 Source files: node_modules/@bendyline/squisq-graph/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-graph
@@ -177,7 +177,7 @@ This package has no third-party runtime dependencies. The layout engine and its
 worker entry are Squisq-authored (MIT).
 
 ==============================================================================
-Components: @bendyline/squisq-graph@2.13.0
+Components: @bendyline/squisq-graph@2.13.1
 Source files: node_modules/@bendyline/squisq-graph/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-graph
@@ -189,7 +189,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 COMPONENTS
 
 ==============================================================================
-Components: @bendyline/squisq@2.13.6
+Components: @bendyline/squisq@2.13.9
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -220,7 +220,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.13.6
+Components: @bendyline/squisq@2.13.9
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

package/dist/{catalog-BQK05tne.d.ts → catalog-flfSruLW.d.ts}

@@ -1,5 +1,5 @@
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
-import { C as CatalogSortOrder } from './settings-HrrCikVX.js';
+import { C as CatalogSortOrder } from './settings-D_CL7AJA.js';
 
 /**
  * Synchronous outside-in path layout.
@@ -36,8 +36,11 @@ declare function chooseOutsideInMarkdownPath(layout: OutsideInLayout, paths: rea
  *
  * Everything here is deterministic: identical inputs produce identical bytes
  * on every surface (shell, VS Code extension host, CLI). There are no
- * timestamps, no filesystem mtimes, and no locale-sensitive ordering, so a
- * catalog committed to git only changes when the documents do.
+ * filesystem mtimes and no locale-sensitive ordering. The only clock reading
+ * is a document's first-published and last-modified dates, carried forward from
+ * the previous catalog JSON and stamped only when a document first appears or
+ * its content changes — so a catalog committed to git still only changes when
+ * the documents do.
  */
 
 declare const CATALOG_GENERATOR = "docblocks-workspace-catalog";
@@ -65,11 +68,17 @@ interface CatalogEntry {
     readonly description?: string;
     readonly author?: string;
     readonly date?: string;
+    /** When the document first appeared in the catalog JSON (ISO 8601, UTC). */
+    readonly firstPublishedDate?: string;
+    /** When the catalog JSON last picked up a change to the document's content. */
+    readonly lastModifiedDate?: string;
     readonly tags?: readonly string[];
     readonly theme?: string;
     readonly outline: readonly CatalogOutlineEntry[];
     readonly wordCount: number;
     readonly excerpt?: string;
+    /** SHA-256 hex of the source text with normalized line endings; absent when unread. */
+    readonly contentHash?: string;
     /** Present only when the catalog is configured with `content: "markdown"`. */
     readonly markdown?: string;
 }
@@ -106,6 +115,23 @@ declare function createWorkspaceCatalog(title: string, entries: readonly Catalog
  */
 declare function serializeCatalogJson(catalog: WorkspaceCatalog): string;
 declare function isGeneratedCatalogJson(text: string): boolean;
+/** The dates a previously generated catalog recorded for one document. */
+interface CatalogDateRecord {
+    readonly firstPublishedDate: string;
+    readonly lastModifiedDate: string;
+    readonly contentHash?: string;
+}
+/**
+ * Per-path date history from a previously generated catalog JSON. Anything
+ * malformed is skipped, so the worst case is a document dated as new.
+ */
+declare function readCatalogDateHistory(text: string): Map<string, CatalogDateRecord>;
+/**
+ * Date each entry. A document keeps the dates `history` holds for its path;
+ * it is stamped `now` when it first appears, and its `lastModifiedDate`
+ * moves to `now` when its content hash changes.
+ */
+declare function stampCatalogDates(catalog: WorkspaceCatalog, history: ReadonlyMap<string, CatalogDateRecord>, now: Date): WorkspaceCatalog;
 /** Insert the generator marker directly after the doctype so it cannot affect quirks mode. */
 declare function stampCatalogHtml(html: string, inputsDigest: string): string;
 declare function readCatalogHtmlDigest(text: string): string | null;
@@ -119,4 +145,4 @@ declare function relativeCatalogLink(fromDirectory: string, toPath: string): str
  */
 declare function buildCatalogMarkdownDocument(catalog: WorkspaceCatalog, outputPath: string): MarkdownDocument;
 
-export { type CatalogEntry as C, OUTSIDE_IN_FORMAT_IDS as O, type WorkspaceCatalog as W, CATALOG_FORMAT_VERSION as a, CATALOG_GENERATOR as b, CATALOG_LIMITS as c, type CatalogDocumentFormat as d, type CatalogEntryHints as e, type CatalogOutlineEntry as f, type CatalogSource as g, type OutsideInFormatId as h, type OutsideInLayout as i, buildCatalogMarkdownDocument as j, catalogEntryForUnreadable as k, catalogEntryFromDocument as l, catalogEntryFromMarkdown as m, chooseOutsideInMarkdownPath as n, createWorkspaceCatalog as o, isGeneratedCatalogHtml as p, isGeneratedCatalogJson as q, readCatalogHtmlDigest as r, relativeCatalogLink as s, relocateOutsideInLayout as t, resolveOutsideInLayout as u, serializeCatalogJson as v, sortCatalogEntries as w, stampCatalogHtml as x };
+export { stampCatalogHtml as A, type CatalogEntry as C, OUTSIDE_IN_FORMAT_IDS as O, type WorkspaceCatalog as W, CATALOG_FORMAT_VERSION as a, CATALOG_GENERATOR as b, CATALOG_LIMITS as c, type CatalogDateRecord as d, type CatalogDocumentFormat as e, type CatalogEntryHints as f, type CatalogOutlineEntry as g, type CatalogSource as h, type OutsideInFormatId as i, type OutsideInLayout as j, buildCatalogMarkdownDocument as k, catalogEntryForUnreadable as l, catalogEntryFromDocument as m, catalogEntryFromMarkdown as n, chooseOutsideInMarkdownPath as o, createWorkspaceCatalog as p, isGeneratedCatalogHtml as q, isGeneratedCatalogJson as r, readCatalogDateHistory as s, readCatalogHtmlDigest as t, relativeCatalogLink as u, relocateOutsideInLayout as v, resolveOutsideInLayout as w, serializeCatalogJson as x, sortCatalogEntries as y, stampCatalogDates as z };

package/dist/{chunk-R2JX5N3F.js → chunk-3CCINQX5.js}

@@ -1,3 +1,128 @@
+// src/workspace-settings/sha256.ts
+var ROUND_CONSTANTS = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var INITIAL_HASH = [
+  1779033703,
+  3144134277,
+  1013904242,
+  2773480762,
+  1359893119,
+  2600822924,
+  528734635,
+  1541459225
+];
+function rotateRight(value, bits) {
+  return value >>> bits | value << 32 - bits;
+}
+function sha256Bytes(input) {
+  const blocks = new Uint8Array(Math.ceil((input.length + 9) / 64) * 64);
+  blocks.set(input);
+  blocks[input.length] = 128;
+  const view = new DataView(blocks.buffer);
+  const bitLength = input.length * 8;
+  view.setUint32(blocks.length - 8, Math.floor(bitLength / 4294967296));
+  view.setUint32(blocks.length - 4, bitLength >>> 0);
+  const hash = [...INITIAL_HASH];
+  const schedule = new Uint32Array(64);
+  for (let offset = 0; offset < blocks.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) schedule[i] = view.getUint32(offset + i * 4);
+    for (let i = 16; i < 64; i += 1) {
+      const early = schedule[i - 15];
+      const late = schedule[i - 2];
+      const s0 = rotateRight(early, 7) ^ rotateRight(early, 18) ^ early >>> 3;
+      const s1 = rotateRight(late, 17) ^ rotateRight(late, 19) ^ late >>> 10;
+      schedule[i] = schedule[i - 16] + s0 + schedule[i - 7] + s1;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choice = e & f ^ ~e & g;
+      const temp1 = h + s1 + choice + ROUND_CONSTANTS[i] + schedule[i] >>> 0;
+      const s0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = a & b ^ a & c ^ b & c;
+      const temp2 = s0 + majority >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    const round = [a, b, c, d, e, f, g, h];
+    for (let i = 0; i < 8; i += 1) hash[i] = hash[i] + round[i] >>> 0;
+  }
+  const digest = new Uint8Array(32);
+  const out = new DataView(digest.buffer);
+  for (let i = 0; i < 8; i += 1) out.setUint32(i * 4, hash[i]);
+  return digest;
+}
+
 // src/workspace-settings/catalog.ts
 var CATALOG_GENERATOR = "docblocks-workspace-catalog";
 var CATALOG_FORMAT_VERSION = 1;
@@ -168,11 +293,14 @@ function orderedEntry(entry) {
     "description",
     "author",
     "date",
+    "firstPublishedDate",
+    "lastModifiedDate",
     "tags",
     "theme",
     "outline",
     "wordCount",
     "excerpt",
+    "contentHash",
     "markdown"
   ];
   for (const key of keys) {
@@ -202,6 +330,50 @@ var CATALOG_JSON_MARKER = /^\uFEFF?\{\s*"generator"\s*:\s*"docblocks-workspace-c
 function isGeneratedCatalogJson(text) {
   return CATALOG_JSON_MARKER.test(text.slice(0, 256));
 }
+var CATALOG_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2}))?$/;
+var CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+function catalogDate(value) {
+  return typeof value === "string" && CATALOG_DATE_PATTERN.test(value) && Number.isFinite(Date.parse(value)) ? value : void 0;
+}
+function readCatalogDateHistory(text) {
+  const history = /* @__PURE__ */ new Map();
+  if (!isGeneratedCatalogJson(text)) return history;
+  let parsed;
+  try {
+    parsed = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    return history;
+  }
+  const documents = parsed?.documents;
+  if (!Array.isArray(documents)) return history;
+  for (const document of documents) {
+    if (!document || typeof document !== "object") continue;
+    const record = document;
+    const first = catalogDate(record.firstPublishedDate);
+    if (typeof record.path !== "string" || !first) continue;
+    const hash = record.contentHash;
+    history.set(record.path, {
+      firstPublishedDate: first,
+      lastModifiedDate: catalogDate(record.lastModifiedDate) ?? first,
+      ...typeof hash === "string" && CONTENT_HASH_PATTERN.test(hash) ? { contentHash: hash } : {}
+    });
+  }
+  return history;
+}
+function stampCatalogDates(catalog, history, now) {
+  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  return {
+    ...catalog,
+    documents: catalog.documents.map((entry) => {
+      const previous = history.get(entry.path);
+      return {
+        ...entry,
+        firstPublishedDate: previous?.firstPublishedDate ?? timestamp,
+        lastModifiedDate: previous && previous.contentHash === entry.contentHash ? previous.lastModifiedDate : timestamp
+      };
+    })
+  };
+}
 var CATALOG_HTML_MARKER = /<!-- docblocks-workspace-catalog v1 inputs=sha256:([0-9a-f]{64}) -->/;
 var CATALOG_HTML_MARKER_SCAN_CHARACTERS = 2048;
 function stampCatalogHtml(html, inputsDigest) {
@@ -277,8 +449,10 @@ function buildCatalogMarkdownDocument(catalog, outputPath) {
   return { type: "document", children };
 }
 async function sha256Hex(text) {
-  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
-  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  const bytes = new TextEncoder().encode(text);
+  const subtle = globalThis.crypto?.subtle;
+  const digest = subtle ? new Uint8Array(await subtle.digest("SHA-256", bytes)) : sha256Bytes(bytes);
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
 // src/workspace-settings/outside-in-layout.ts
@@ -369,6 +543,8 @@ export {
   createWorkspaceCatalog,
   serializeCatalogJson,
   isGeneratedCatalogJson,
+  readCatalogDateHistory,
+  stampCatalogDates,
   stampCatalogHtml,
   readCatalogHtmlDigest,
   isGeneratedCatalogHtml,

package/dist/{chunk-BC42VRYW.js → chunk-Q7DU2EEB.js}

@@ -13,6 +13,7 @@ var WORKSPACE_SETTINGS_LIMITS = {
   maxFileBytes: 64 * 1024,
   maxTitleCharacters: 256,
   maxPathCharacters: 1024,
+  maxUrlCharacters: 2048,
   maxSchemaCharacters: 2048,
   maxExcludes: 64,
   minKeep: 1,
@@ -21,6 +22,7 @@ var WORKSPACE_SETTINGS_LIMITS = {
 var WORKSPACE_THEME_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 var CATALOG_SORT_ORDERS = ["title", "path", "date"];
 var CATALOG_JSON_CONTENT_MODES = ["metadata", "markdown"];
+var WORKSPACE_OUTPUT_TEMPLATE_FORMATS = ["html"];
 var EMPTY_WORKSPACE_SETTINGS = Object.freeze({
   version: WORKSPACE_SETTINGS_VERSION
 });
@@ -85,6 +87,63 @@ function boundedPath(value, label) {
   if (!path) fail(`${label} must not be the workspace root.`);
   return path;
 }
+var OUTPUT_TEMPLATE_EXTENSIONS = {
+  html: [".html", ".htm"]
+};
+function validateOutputTemplatePath(value, format) {
+  const label = `documents.outputTemplates.${format}`;
+  const path = boundedPath(value, label);
+  const lower = path.toLowerCase();
+  if (!OUTPUT_TEMPLATE_EXTENSIONS[format].some((extension) => lower.endsWith(extension))) {
+    fail(`${label} must end with ${OUTPUT_TEMPLATE_EXTENSIONS[format].join(" or ")}.`);
+  }
+  return path;
+}
+function checkOutputTemplatePath(value, format) {
+  try {
+    return { ok: true, path: validateOutputTemplatePath(value, format) };
+  } catch (error) {
+    return { ok: false, message: shapeMessage(error) };
+  }
+}
+function validateSiteUrl(value) {
+  const label = "documents.siteUrl";
+  if (typeof value !== "string" || value.length === 0 || value.length > WORKSPACE_SETTINGS_LIMITS.maxUrlCharacters) {
+    fail(
+      `${label} must be a URL of at most ${WORKSPACE_SETTINGS_LIMITS.maxUrlCharacters} characters.`
+    );
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail(`${label} must be an absolute URL, such as "https://example.com/posts/".`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    fail(`${label} must be an http or https URL.`);
+  }
+  if (url.search || url.hash || value.includes("?") || value.includes("#")) {
+    fail(`${label} must not have a query or fragment.`);
+  }
+  return value;
+}
+function optionalSiteUrl(value) {
+  return value === void 0 ? void 0 : validateSiteUrl(value);
+}
+function checkSiteUrl(value) {
+  try {
+    return { ok: true, url: validateSiteUrl(value) };
+  } catch (error) {
+    return { ok: false, message: shapeMessage(error) };
+  }
+}
+function parseOutputTemplates(value) {
+  if (value === void 0) return void 0;
+  const record = exactRecord(value, "documents.outputTemplates", WORKSPACE_OUTPUT_TEMPLATE_FORMATS);
+  return compact({
+    html: record.html === void 0 ? void 0 : validateOutputTemplatePath(record.html, "html")
+  });
+}
 var OUTPUT_EXTENSIONS = {
   html: [".html", ".htm"],
   json: [".json"]
@@ -146,6 +205,7 @@ function compact(value) {
   const entries = Object.entries(value).filter(([, field]) => field !== void 0);
   return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 }
+var DOCUMENT_SETTINGS_KEYS = ["defaultTheme", "outputTemplates", "siteUrl"];
 function parseWorkspaceSettings(value) {
   const root = isRecord(value) ? value : fail("Workspace settings must be a JSON object.");
   const version = root.version;
@@ -169,9 +229,11 @@ function parseWorkspaceSettings(value) {
   }
   let documents;
   if (root.documents !== void 0) {
-    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    const record = exactRecord(root.documents, "documents", DOCUMENT_SETTINGS_KEYS);
     documents = compact({
-      defaultTheme: optionalTheme(record.defaultTheme, "documents.defaultTheme")
+      defaultTheme: optionalTheme(record.defaultTheme, "documents.defaultTheme"),
+      outputTemplates: parseOutputTemplates(record.outputTemplates),
+      siteUrl: optionalSiteUrl(record.siteUrl)
     });
   }
   let versionHistory;
@@ -278,7 +340,12 @@ function serializeWorkspaceSettings(settings) {
   if (normalized.$schema !== void 0) ordered.$schema = normalized.$schema;
   ordered.version = normalized.version;
   if (normalized.documents) {
-    ordered.documents = pick(normalized.documents, ["defaultTheme"]);
+    const { outputTemplates } = normalized.documents;
+    ordered.documents = {
+      ...pick(normalized.documents, ["defaultTheme"]),
+      ...outputTemplates ? { outputTemplates: pick(outputTemplates, WORKSPACE_OUTPUT_TEMPLATE_FORMATS) } : {},
+      ...pick(normalized.documents, ["siteUrl"])
+    };
   }
   if (normalized.versionHistory) {
     ordered.versionHistory = pick(normalized.versionHistory, ["enabled", "keep"]);
@@ -340,7 +407,7 @@ function optionalSection(key, value) {
 }
 function diffWorkspaceSettings(before, after) {
   const base = before ?? EMPTY_WORKSPACE_SETTINGS;
-  const documents = diffFields(base.documents, after.documents, ["defaultTheme"]);
+  const documents = diffFields(base.documents, after.documents, DOCUMENT_SETTINGS_KEYS);
   const versionHistory = diffFields(base.versionHistory, after.versionHistory, ["enabled", "keep"]);
   const top = diffFields(
     base.catalog,
@@ -378,12 +445,14 @@ function parseWorkspaceSettingsPatch(value) {
   const nullable = (field, parse) => field === null ? null : parse(field);
   const result = {};
   if (root.documents !== void 0) {
-    const record = exactRecord(root.documents, "documents", ["defaultTheme"]);
+    const record = exactRecord(root.documents, "documents", DOCUMENT_SETTINGS_KEYS);
     result.documents = compact({
       defaultTheme: nullable(
         record.defaultTheme,
         (input) => optionalTheme(input, "documents.defaultTheme")
-      )
+      ),
+      outputTemplates: nullable(record.outputTemplates, parseOutputTemplates),
+      siteUrl: nullable(record.siteUrl, optionalSiteUrl)
     }) ?? {};
   }
   if (root.versionHistory !== void 0) {
@@ -451,11 +520,20 @@ function tryApplyWorkspaceSettingsPatch(base, patch) {
   }
 }
 function isDefaultWorkspaceSettings(settings) {
-  return settings?.documents?.defaultTheme === void 0 && settings?.versionHistory?.enabled === void 0 && settings?.versionHistory?.keep === void 0 && settings?.catalog?.html?.enabled !== true && settings?.catalog?.json?.enabled !== true;
+  return settings?.documents?.defaultTheme === void 0 && settings?.documents?.outputTemplates === void 0 && settings?.documents?.siteUrl === void 0 && settings?.versionHistory?.enabled === void 0 && settings?.versionHistory?.keep === void 0 && settings?.catalog?.html?.enabled !== true && settings?.catalog?.json?.enabled !== true;
 }
 function resolveWorkspaceDefaultThemeId(settings) {
   return settings?.documents?.defaultTheme;
 }
+function resolveWorkspaceOutputTemplate(settings, format) {
+  const templates = settings?.documents?.outputTemplates;
+  return format === "html" ? templates?.html : void 0;
+}
+function resolveWorkspaceSiteUrl(settings) {
+  const url = settings?.documents?.siteUrl;
+  if (url === void 0) return void 0;
+  return url.endsWith("/") ? url : `${url}/`;
+}
 function resolveFallbackThemeId(frontmatterThemeId, settings) {
   if (frontmatterThemeId) return void 0;
   return resolveWorkspaceDefaultThemeId(settings);
@@ -494,7 +572,12 @@ export {
   WORKSPACE_THEME_ID_PATTERN,
   CATALOG_SORT_ORDERS,
   CATALOG_JSON_CONTENT_MODES,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   EMPTY_WORKSPACE_SETTINGS,
+  validateOutputTemplatePath,
+  checkOutputTemplatePath,
+  validateSiteUrl,
+  checkSiteUrl,
   validateCatalogOutputPath,
   checkCatalogOutputPath,
   parseWorkspaceSettings,
@@ -508,6 +591,8 @@ export {
   tryApplyWorkspaceSettingsPatch,
   isDefaultWorkspaceSettings,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
+  resolveWorkspaceSiteUrl,
   resolveFallbackThemeId,
   resolveWorkspaceVersioningEnabled,
   resolveCatalogOutputs

package/dist/{settings-HrrCikVX.d.ts → settings-D_CL7AJA.d.ts}

@@ -21,6 +21,7 @@ declare const WORKSPACE_SETTINGS_LIMITS: {
     readonly maxFileBytes: number;
     readonly maxTitleCharacters: 256;
     readonly maxPathCharacters: 1024;
+    readonly maxUrlCharacters: 2048;
     readonly maxSchemaCharacters: 2048;
     readonly maxExcludes: 64;
     readonly minKeep: 1;
@@ -32,9 +33,28 @@ declare const CATALOG_SORT_ORDERS: readonly ["title", "path", "date"];
 type CatalogSortOrder = (typeof CATALOG_SORT_ORDERS)[number];
 declare const CATALOG_JSON_CONTENT_MODES: readonly ["metadata", "markdown"];
 type CatalogJsonContent = (typeof CATALOG_JSON_CONTENT_MODES)[number];
+/** Rendered formats a workspace can name a default page template for. */
+declare const WORKSPACE_OUTPUT_TEMPLATE_FORMATS: readonly ["html"];
+type WorkspaceOutputTemplateFormat = (typeof WORKSPACE_OUTPUT_TEMPLATE_FORMATS)[number];
+/** Workspace-relative page template path, by rendered output format. */
+type WorkspaceOutputTemplates = {
+    readonly [Format in WorkspaceOutputTemplateFormat]?: string;
+};
 interface WorkspaceDocumentSettings {
     /** Theme for documents whose frontmatter names none. */
     readonly defaultTheme?: string;
+    /**
+     * Page template for rendered documents whose frontmatter names none
+     * (`squisq-output-template`). A document's own choice, including `none`,
+     * always wins.
+     */
+    readonly outputTemplates?: WorkspaceOutputTemplates;
+    /**
+     * Public `http(s)` address the workspace root is published at, such as
+     * `https://example.com/posts/`. Rendered Web pages use it to give their
+     * social preview pictures the absolute URLs social sites require.
+     */
+    readonly siteUrl?: string;
 }
 interface WorkspaceVersionHistorySettings {
     /** Absent inherits the app-wide preference. */
@@ -76,6 +96,26 @@ type WorkspaceSettingsParseResult = {
     readonly status: 'invalid' | 'unsupported-version';
     readonly message: string;
 };
+/** Validate a configured page template path for one rendered format. */
+declare function validateOutputTemplatePath(value: unknown, format: WorkspaceOutputTemplateFormat): WorkspacePath;
+/** Try-form for UI validation messages. */
+declare function checkOutputTemplatePath(value: unknown, format: WorkspaceOutputTemplateFormat): {
+    ok: true;
+    path: WorkspacePath;
+} | {
+    ok: false;
+    message: string;
+};
+/** Validate a configured site address: an absolute `http(s)` URL with no query or fragment. */
+declare function validateSiteUrl(value: unknown): string;
+/** Try-form for UI validation messages. */
+declare function checkSiteUrl(value: unknown): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    message: string;
+};
 type CatalogOutputKind = 'html' | 'json';
 /**
  * Validate a configured catalog output path. Outputs may never land inside
@@ -135,7 +175,8 @@ declare function tryApplyWorkspaceSettingsPatch(base: WorkspaceSettings | null,
 };
 /**
  * True when settings change nothing about how DocBlocks treats the folder: no
- * default theme, no version-history choice, and no catalog output turned on.
+ * default theme, page template, or site address, no version-history choice,
+ * and no catalog output turned on.
  * Fields that only configure a disabled output (a catalog title, path, order,
  * or page theme) are inert. Such settings are never worth creating a
  * `.docblocks/` folder for.
@@ -143,6 +184,13 @@ declare function tryApplyWorkspaceSettingsPatch(base: WorkspaceSettings | null,
 declare function isDefaultWorkspaceSettings(settings: WorkspaceSettings | null | undefined): boolean;
 /** The workspace default theme, or undefined to use the built-in default. */
 declare function resolveWorkspaceDefaultThemeId(settings: WorkspaceSettings | null | undefined): string | undefined;
+/** The workspace default page template for a rendered format, workspace-relative. */
+declare function resolveWorkspaceOutputTemplate(settings: WorkspaceSettings | null | undefined, format: string): string | undefined;
+/**
+ * The address the workspace root is published at, as a folder URL (ending in
+ * `/`) that workspace paths resolve against, or undefined when none is set.
+ */
+declare function resolveWorkspaceSiteUrl(settings: WorkspaceSettings | null | undefined): string | undefined;
 /**
  * The theme a renderer should be told about explicitly. Every Squisq
  * exporter lets an explicit theme beat the document's own frontmatter, so a
@@ -167,4 +215,4 @@ interface ResolvedCatalogOutputs {
 /** Effective catalog configuration, or null when no output is enabled. */
 declare function resolveCatalogOutputs(settings: WorkspaceSettings | null | undefined): ResolvedCatalogOutputs | null;
 
-export { resolveCatalogOutputs as A, resolveFallbackThemeId as B, type CatalogSortOrder as C, DEFAULT_CATALOG_HTML_PATH as D, EMPTY_WORKSPACE_SETTINGS as E, resolveWorkspaceDefaultThemeId as F, resolveWorkspaceVersioningEnabled as G, serializeWorkspaceSettings as H, tryApplyWorkspaceSettingsPatch as I, validateCatalogOutputPath as J, type ResolvedCatalogOutputs as R, UnsupportedWorkspaceSettingsVersionError as U, type WorkspaceSettings as W, type WorkspaceSettingsPatch as a, CATALOG_JSON_CONTENT_MODES as b, CATALOG_SORT_ORDERS as c, type CatalogJsonContent as d, type CatalogOutputKind as e, DEFAULT_CATALOG_JSON_PATH as f, DEFAULT_CATALOG_TITLE as g, WORKSPACE_SETTINGS_DIRECTORY as h, WORKSPACE_SETTINGS_LIMITS as i, WORKSPACE_SETTINGS_PATH as j, WORKSPACE_SETTINGS_VERSION as k, WORKSPACE_THEME_ID_PATTERN as l, type WorkspaceCatalogHtmlSettings as m, type WorkspaceCatalogJsonSettings as n, type WorkspaceCatalogSettings as o, type WorkspaceDocumentSettings as p, type WorkspaceSettingsParseResult as q, type WorkspaceVersionHistorySettings as r, applyWorkspaceSettingsPatch as s, checkCatalogOutputPath as t, diffWorkspaceSettings as u, isDefaultWorkspaceSettings as v, isEmptyWorkspaceSettingsPatch as w, parseWorkspaceSettings as x, parseWorkspaceSettingsPatch as y, parseWorkspaceSettingsText as z };
+export { isDefaultWorkspaceSettings as A, isEmptyWorkspaceSettingsPatch as B, type CatalogSortOrder as C, DEFAULT_CATALOG_HTML_PATH as D, EMPTY_WORKSPACE_SETTINGS as E, parseWorkspaceSettings as F, parseWorkspaceSettingsPatch as G, parseWorkspaceSettingsText as H, resolveCatalogOutputs as I, resolveFallbackThemeId as J, resolveWorkspaceDefaultThemeId as K, resolveWorkspaceOutputTemplate as L, resolveWorkspaceSiteUrl as M, resolveWorkspaceVersioningEnabled as N, serializeWorkspaceSettings as O, tryApplyWorkspaceSettingsPatch as P, validateCatalogOutputPath as Q, type ResolvedCatalogOutputs as R, validateOutputTemplatePath as S, validateSiteUrl as T, UnsupportedWorkspaceSettingsVersionError as U, type WorkspaceSettings as W, type WorkspaceSettingsPatch as a, CATALOG_JSON_CONTENT_MODES as b, CATALOG_SORT_ORDERS as c, type CatalogJsonContent as d, type CatalogOutputKind as e, DEFAULT_CATALOG_JSON_PATH as f, DEFAULT_CATALOG_TITLE as g, WORKSPACE_OUTPUT_TEMPLATE_FORMATS as h, WORKSPACE_SETTINGS_DIRECTORY as i, WORKSPACE_SETTINGS_LIMITS as j, WORKSPACE_SETTINGS_PATH as k, WORKSPACE_SETTINGS_VERSION as l, WORKSPACE_THEME_ID_PATTERN as m, type WorkspaceCatalogHtmlSettings as n, type WorkspaceCatalogJsonSettings as o, type WorkspaceCatalogSettings as p, type WorkspaceDocumentSettings as q, type WorkspaceOutputTemplateFormat as r, type WorkspaceOutputTemplates as s, type WorkspaceSettingsParseResult as t, type WorkspaceVersionHistorySettings as u, applyWorkspaceSettingsPatch as v, checkCatalogOutputPath as w, checkOutputTemplatePath as x, checkSiteUrl as y, diffWorkspaceSettings as z };

package/dist/vscode/index.d.ts

@@ -1,4 +1,4 @@
-import { W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-HrrCikVX.js';
+import { W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-D_CL7AJA.js';
 import '../workspace-path-CWVrcuPL.js';
 
 /**

package/dist/vscode/index.js

@@ -1,7 +1,7 @@
 import {
   parseWorkspaceSettings,
   parseWorkspaceSettingsPatch
-} from "../chunk-BC42VRYW.js";
+} from "../chunk-Q7DU2EEB.js";
 import {
   HOST_WIRE_LIMITS,
   isBoundedString

package/dist/workspace-index/index.d.ts

@@ -1,8 +1,8 @@
 import { o as FileSystemProviderV2, n as FileSystemProviderCapabilities } from '../v2-DwxWjFC0.js';
 import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
-import { d as CatalogDocumentFormat, f as CatalogOutlineEntry } from '../catalog-BQK05tne.js';
+import { e as CatalogDocumentFormat, g as CatalogOutlineEntry } from '../catalog-flfSruLW.js';
 import '@bendyline/squisq/markdown';
-import '../settings-HrrCikVX.js';
+import '../settings-D_CL7AJA.js';
 
 /**
  * What the index reads from. Only read methods are reachable, so the index

package/dist/workspace-index/index.js

@@ -3,7 +3,7 @@ import {
   chooseOutsideInMarkdownPath,
   normalizeLineEndings,
   resolveOutsideInLayout
-} from "../chunk-R2JX5N3F.js";
+} from "../chunk-3CCINQX5.js";
 import {
   isCompanionDirectoryName,
   isDiscoverableWorkspaceEntry,

package/dist/workspace-settings/index.d.ts

@@ -1,7 +1,7 @@
-import { R as ResolvedCatalogOutputs, W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-HrrCikVX.js';
-export { b as CATALOG_JSON_CONTENT_MODES, c as CATALOG_SORT_ORDERS, d as CatalogJsonContent, e as CatalogOutputKind, C as CatalogSortOrder, D as DEFAULT_CATALOG_HTML_PATH, f as DEFAULT_CATALOG_JSON_PATH, g as DEFAULT_CATALOG_TITLE, E as EMPTY_WORKSPACE_SETTINGS, U as UnsupportedWorkspaceSettingsVersionError, h as WORKSPACE_SETTINGS_DIRECTORY, i as WORKSPACE_SETTINGS_LIMITS, j as WORKSPACE_SETTINGS_PATH, k as WORKSPACE_SETTINGS_VERSION, l as WORKSPACE_THEME_ID_PATTERN, m as WorkspaceCatalogHtmlSettings, n as WorkspaceCatalogJsonSettings, o as WorkspaceCatalogSettings, p as WorkspaceDocumentSettings, q as WorkspaceSettingsParseResult, r as WorkspaceVersionHistorySettings, s as applyWorkspaceSettingsPatch, t as checkCatalogOutputPath, u as diffWorkspaceSettings, v as isDefaultWorkspaceSettings, w as isEmptyWorkspaceSettingsPatch, x as parseWorkspaceSettings, y as parseWorkspaceSettingsPatch, z as parseWorkspaceSettingsText, A as resolveCatalogOutputs, B as resolveFallbackThemeId, F as resolveWorkspaceDefaultThemeId, G as resolveWorkspaceVersioningEnabled, H as serializeWorkspaceSettings, I as tryApplyWorkspaceSettingsPatch, J as validateCatalogOutputPath } from '../settings-HrrCikVX.js';
-import { C as CatalogEntry, W as WorkspaceCatalog } from '../catalog-BQK05tne.js';
-export { a as CATALOG_FORMAT_VERSION, b as CATALOG_GENERATOR, c as CATALOG_LIMITS, d as CatalogDocumentFormat, e as CatalogEntryHints, f as CatalogOutlineEntry, g as CatalogSource, O as OUTSIDE_IN_FORMAT_IDS, h as OutsideInFormatId, i as OutsideInLayout, j as buildCatalogMarkdownDocument, k as catalogEntryForUnreadable, l as catalogEntryFromDocument, m as catalogEntryFromMarkdown, n as chooseOutsideInMarkdownPath, o as createWorkspaceCatalog, p as isGeneratedCatalogHtml, q as isGeneratedCatalogJson, r as readCatalogHtmlDigest, s as relativeCatalogLink, t as relocateOutsideInLayout, u as resolveOutsideInLayout, v as serializeCatalogJson, w as sortCatalogEntries, x as stampCatalogHtml } from '../catalog-BQK05tne.js';
+import { R as ResolvedCatalogOutputs, W as WorkspaceSettings, a as WorkspaceSettingsPatch } from '../settings-D_CL7AJA.js';
+export { b as CATALOG_JSON_CONTENT_MODES, c as CATALOG_SORT_ORDERS, d as CatalogJsonContent, e as CatalogOutputKind, C as CatalogSortOrder, D as DEFAULT_CATALOG_HTML_PATH, f as DEFAULT_CATALOG_JSON_PATH, g as DEFAULT_CATALOG_TITLE, E as EMPTY_WORKSPACE_SETTINGS, U as UnsupportedWorkspaceSettingsVersionError, h as WORKSPACE_OUTPUT_TEMPLATE_FORMATS, i as WORKSPACE_SETTINGS_DIRECTORY, j as WORKSPACE_SETTINGS_LIMITS, k as WORKSPACE_SETTINGS_PATH, l as WORKSPACE_SETTINGS_VERSION, m as WORKSPACE_THEME_ID_PATTERN, n as WorkspaceCatalogHtmlSettings, o as WorkspaceCatalogJsonSettings, p as WorkspaceCatalogSettings, q as WorkspaceDocumentSettings, r as WorkspaceOutputTemplateFormat, s as WorkspaceOutputTemplates, t as WorkspaceSettingsParseResult, u as WorkspaceVersionHistorySettings, v as applyWorkspaceSettingsPatch, w as checkCatalogOutputPath, x as checkOutputTemplatePath, y as checkSiteUrl, z as diffWorkspaceSettings, A as isDefaultWorkspaceSettings, B as isEmptyWorkspaceSettingsPatch, F as parseWorkspaceSettings, G as parseWorkspaceSettingsPatch, H as parseWorkspaceSettingsText, I as resolveCatalogOutputs, J as resolveFallbackThemeId, K as resolveWorkspaceDefaultThemeId, L as resolveWorkspaceOutputTemplate, M as resolveWorkspaceSiteUrl, N as resolveWorkspaceVersioningEnabled, O as serializeWorkspaceSettings, P as tryApplyWorkspaceSettingsPatch, Q as validateCatalogOutputPath, S as validateOutputTemplatePath, T as validateSiteUrl } from '../settings-D_CL7AJA.js';
+import { C as CatalogEntry, W as WorkspaceCatalog } from '../catalog-flfSruLW.js';
+export { a as CATALOG_FORMAT_VERSION, b as CATALOG_GENERATOR, c as CATALOG_LIMITS, d as CatalogDateRecord, e as CatalogDocumentFormat, f as CatalogEntryHints, g as CatalogOutlineEntry, h as CatalogSource, O as OUTSIDE_IN_FORMAT_IDS, i as OutsideInFormatId, j as OutsideInLayout, k as buildCatalogMarkdownDocument, l as catalogEntryForUnreadable, m as catalogEntryFromDocument, n as catalogEntryFromMarkdown, o as chooseOutsideInMarkdownPath, p as createWorkspaceCatalog, q as isGeneratedCatalogHtml, r as isGeneratedCatalogJson, s as readCatalogDateHistory, t as readCatalogHtmlDigest, u as relativeCatalogLink, v as relocateOutsideInLayout, w as resolveOutsideInLayout, x as serializeCatalogJson, y as sortCatalogEntries, z as stampCatalogDates, A as stampCatalogHtml } from '../catalog-flfSruLW.js';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
 import { v as FileSystemVersion, o as FileSystemProviderV2 } from '../v2-DwxWjFC0.js';
 import { a as WorkspacePath } from '../workspace-path-CWVrcuPL.js';
@@ -37,6 +37,27 @@ declare const WORKSPACE_SETTINGS_JSON_SCHEMA: {
                     readonly type: "string";
                     readonly pattern: string;
                 };
+                readonly outputTemplates: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Page templates for rendered documents whose frontmatter names none (squisq-output-template). A document’s own choice, including \"none\", always wins.";
+                    readonly properties: {
+                        readonly html: {
+                            readonly pattern: "\\.html?$";
+                            readonly description: "Workspace-relative HTML page template for Web pages, such as \"_templates/post.html\". Its unnamed <slot> receives the page content.";
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 1024;
+                        };
+                    };
+                };
+                readonly siteUrl: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly pattern: "^https?://[^?#]+$";
+                    readonly maxLength: 2048;
+                    readonly description: "Public address this folder is published at, such as \"https://example.com/posts/\". Gives rendered Web pages absolute social preview image URLs.";
+                };
             };
         };
         readonly versionHistory: {
@@ -154,6 +175,11 @@ interface WorkspaceOutputsRenderer {
     }): string | Promise<string>;
     /** Parse rendered HTML that has no Markdown companion yet. Optional. */
     importHtml?(html: string): MarkdownDocument | Promise<MarkdownDocument>;
+    /**
+     * True for an HTML page template — the chrome other pages are generated
+     * through, not a document of its own — which the catalog leaves out. Optional.
+     */
+    isPageTemplate?(html: string): boolean;
 }
 declare const WORKSPACE_OUTPUT_LIMITS: {
     readonly maxDocuments: 5000;
@@ -188,6 +214,8 @@ interface RefreshWorkspaceOutputsOptions {
     /** Compute everything, write nothing. */
     readonly dryRun?: boolean;
     readonly limits?: Partial<WorkspaceOutputLimits>;
+    /** Time stamped on new or changed documents in the catalog JSON. Defaults to now. */
+    readonly now?: Date;
 }
 type WorkspaceOutputStatus = 'written' | 'unchanged' | 'blocked' | 'would-write';
 interface WorkspaceOutputResult {
@@ -211,7 +239,7 @@ declare function isCatalogRelevantPath(path: string, settings: WorkspaceSettings
 /** True for the workspace settings directory or anything inside it. */
 declare function isWorkspaceSettingsPath(path: string): boolean;
 /** Walk the workspace and build its catalog without writing anything. */
-declare function collectWorkspaceCatalog(io: WorkspaceOutputsIO, resolved: ResolvedCatalogOutputs, renderer: Pick<WorkspaceOutputsRenderer, 'importHtml'>, options?: Omit<RefreshWorkspaceOutputsOptions, 'force' | 'dryRun'>): Promise<WorkspaceCatalog>;
+declare function collectWorkspaceCatalog(io: WorkspaceOutputsIO, resolved: ResolvedCatalogOutputs, renderer: Pick<WorkspaceOutputsRenderer, 'importHtml' | 'isPageTemplate'>, options?: Omit<RefreshWorkspaceOutputsOptions, 'force' | 'dryRun' | 'now'>): Promise<WorkspaceCatalog>;
 /**
  * Regenerate every enabled catalog output for one workspace. Throws
  * {@link WorkspaceOutputsLimitError} when over budget, `FsError('aborted')`

package/dist/workspace-settings/index.js

@@ -11,6 +11,8 @@ import {
   createWorkspaceCatalog,
   isGeneratedCatalogHtml,
   isGeneratedCatalogJson,
+  normalizeLineEndings,
+  readCatalogDateHistory,
   readCatalogHtmlDigest,
   relativeCatalogLink,
   relocateOutsideInLayout,
@@ -18,8 +20,9 @@ import {
   serializeCatalogJson,
   sha256Hex,
   sortCatalogEntries,
+  stampCatalogDates,
   stampCatalogHtml
-} from "../chunk-R2JX5N3F.js";
+} from "../chunk-3CCINQX5.js";
 import {
   CATALOG_JSON_CONTENT_MODES,
   CATALOG_SORT_ORDERS,
@@ -28,6 +31,7 @@ import {
   DEFAULT_CATALOG_TITLE,
   EMPTY_WORKSPACE_SETTINGS,
   UnsupportedWorkspaceSettingsVersionError,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   WORKSPACE_SETTINGS_DIRECTORY,
   WORKSPACE_SETTINGS_LIMITS,
   WORKSPACE_SETTINGS_PATH,
@@ -35,6 +39,8 @@ import {
   WORKSPACE_THEME_ID_PATTERN,
   applyWorkspaceSettingsPatch,
   checkCatalogOutputPath,
+  checkOutputTemplatePath,
+  checkSiteUrl,
   diffWorkspaceSettings,
   isDefaultWorkspaceSettings,
   isEmptyWorkspaceSettingsPatch,
@@ -44,11 +50,15 @@ import {
   resolveCatalogOutputs,
   resolveFallbackThemeId,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
+  resolveWorkspaceSiteUrl,
   resolveWorkspaceVersioningEnabled,
   serializeWorkspaceSettings,
   tryApplyWorkspaceSettingsPatch,
-  validateCatalogOutputPath
-} from "../chunk-BC42VRYW.js";
+  validateCatalogOutputPath,
+  validateOutputTemplatePath,
+  validateSiteUrl
+} from "../chunk-Q7DU2EEB.js";
 import {
   SQUISQ_RUNTIME_DIRECTORY_NAME,
   isDiscoverableWorkspaceEntry,
@@ -92,6 +102,25 @@ var WORKSPACE_SETTINGS_JSON_SCHEMA = {
         defaultTheme: {
           ...themeId,
           description: "Theme for documents whose frontmatter does not name one. A document\u2019s own theme always wins."
+        },
+        outputTemplates: {
+          type: "object",
+          additionalProperties: false,
+          description: 'Page templates for rendered documents whose frontmatter names none (squisq-output-template). A document\u2019s own choice, including "none", always wins.',
+          properties: {
+            html: {
+              ...relativePath,
+              pattern: "\\.html?$",
+              description: 'Workspace-relative HTML page template for Web pages, such as "_templates/post.html". Its unnamed <slot> receives the page content.'
+            }
+          }
+        },
+        siteUrl: {
+          type: "string",
+          format: "uri",
+          pattern: "^https?://[^?#]+$",
+          maxLength: WORKSPACE_SETTINGS_LIMITS.maxUrlCharacters,
+          description: 'Public address this folder is published at, such as "https://example.com/posts/". Gives rendered Web pages absolute social preview image URLs.'
         }
       }
     },
@@ -351,7 +380,7 @@ async function collectWorkspaceCatalog(io, resolved, renderer, options = {}) {
       const text = new TextDecoder("utf-8").decode(read.data);
       if (target.mode === "markdown") {
         entry = await catalogEntryFromMarkdown(target.source, text, { includeMarkdown });
-      } else if (isGeneratedCatalogHtml(text)) {
+      } else if (isGeneratedCatalogHtml(text) || renderer.isPageTemplate?.(text)) {
         entry = null;
       } else if (renderer.importHtml) {
         const head = text.slice(0, 64 * 1024);
@@ -362,6 +391,7 @@ async function collectWorkspaceCatalog(io, resolved, renderer, options = {}) {
       } else {
         entry = catalogEntryForUnreadable(target.source);
       }
+      if (entry) entry = { ...entry, contentHash: await sha256Hex(normalizeLineEndings(text)) };
     }
     cache?.set(target.source.path, {
       readPath: target.readPath,
@@ -426,7 +456,9 @@ async function writeOutput(io, request, limits, options) {
       return blocked(`${path} is an edited document. Choose another catalog path.`);
     }
   }
-  const bytes = new TextEncoder().encode(await request.produce());
+  const bytes = new TextEncoder().encode(
+    await request.produce(existing ? new TextDecoder("utf-8").decode(existing.data) : null)
+  );
   if (bytes.byteLength > limits.maxOutputBytes) {
     return blocked(
       `The catalog would exceed ${Math.round(limits.maxOutputBytes / 1024 / 1024)} MiB and was not written.`
@@ -451,13 +483,20 @@ async function refreshWorkspaceOutputs(io, settings, renderer, options = {}) {
   if (resolved.json) {
     throwIfAborted(options.signal);
     const content = resolved.json.content;
+    const now = options.now ?? /* @__PURE__ */ new Date();
     outputs.push(
       await writeOutput(
         io,
         {
           kind: "json",
           path: resolved.json.path,
-          produce: async () => serializeCatalogJson(content === "markdown" ? catalog : metadataCatalog)
+          produce: async (previous) => serializeCatalogJson(
+            stampCatalogDates(
+              content === "markdown" ? catalog : metadataCatalog,
+              readCatalogDateHistory(previous ?? ""),
+              now
+            )
+          )
         },
         limits,
         options
@@ -771,6 +810,7 @@ export {
   WORKSPACE_OUTPUTS_DEBOUNCE_MS,
   WORKSPACE_OUTPUTS_MAX_WAIT_MS,
   WORKSPACE_OUTPUT_LIMITS,
+  WORKSPACE_OUTPUT_TEMPLATE_FORMATS,
   WORKSPACE_SETTINGS_DIRECTORY,
   WORKSPACE_SETTINGS_JSON_SCHEMA,
   WORKSPACE_SETTINGS_LIMITS,
@@ -784,6 +824,8 @@ export {
   catalogEntryFromDocument,
   catalogEntryFromMarkdown,
   checkCatalogOutputPath,
+  checkOutputTemplatePath,
+  checkSiteUrl,
   chooseOutsideInMarkdownPath,
   collectWorkspaceCatalog,
   createWorkspaceCatalog,
@@ -800,6 +842,7 @@ export {
   parseWorkspaceSettings,
   parseWorkspaceSettingsPatch,
   parseWorkspaceSettingsText,
+  readCatalogDateHistory,
   readCatalogHtmlDigest,
   readWorkspaceSettings,
   refreshWorkspaceOutputs,
@@ -809,12 +852,17 @@ export {
   resolveFallbackThemeId,
   resolveOutsideInLayout,
   resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceOutputTemplate,
+  resolveWorkspaceSiteUrl,
   resolveWorkspaceVersioningEnabled,
   saveWorkspaceSettingsPatch,
   serializeCatalogJson,
   serializeWorkspaceSettings,
   sortCatalogEntries,
+  stampCatalogDates,
   stampCatalogHtml,
   tryApplyWorkspaceSettingsPatch,
-  validateCatalogOutputPath
+  validateCatalogOutputPath,
+  validateOutputTemplatePath,
+  validateSiteUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks",
-  "version": "2.7.8",
+  "version": "2.7.10",
   "description": "Core data structures and filesystem abstractions for DocBlocks",
   "license": "MIT",
   "author": "Bendyline",
@@ -126,7 +126,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "2.13.6",
+    "@bendyline/squisq": "2.13.9",
     "zod": "3.25.76"
   }
 }