@jant/core 0.6.16 → 0.7.1

package/src/services/export.ts

@@ -29,7 +29,7 @@ import {
 } from "../lib/jant-branding.js";
 import { getRootActivityAt } from "../db/thread-activity.js";
 import { tiptapJsonToMarkdown } from "../lib/tiptap-to-markdown.js";
-import { extractBodyText } from "../lib/summary.js";
+import { extractBodyText, extractTimelineSummary } from "../lib/summary.js";
 import { getMediaUrl, getPublicUrlForProvider } from "../lib/image.js";
 import { render as renderMarkdown } from "../lib/markdown.js";
 import { formatRelativeAge, toISOString } from "../lib/time.js";
@@ -37,6 +37,7 @@ import {
   formatFrontMatter,
   type HugoCollectionRef,
   type HugoFrontMatter,
+  type HugoSmartCollectionSelection,
   type JantMedia,
 } from "../lib/hugo-markdown.js";
 // Shared design tokens — single source of truth for colors, typography,
@@ -69,6 +70,8 @@ import LAYOUT_FEATURED_LIST from "./export-theme/layouts/featured/list.html?raw"
 import LAYOUT_ARCHIVE_LIST from "./export-theme/layouts/archive/list.html?raw";
 import LAYOUT_COLLECTIONS_LIST from "./export-theme/layouts/collections/list.html?raw";
 import LAYOUT_COLLECTION_SINGLE from "./export-theme/layouts/collection/single.html?raw";
+import LAYOUT_SMART_COLLECTION_LIST from "./export-theme/layouts/smart_collection/list.html?raw";
+import PARTIAL_JANT_DATA from "./export-theme/layouts/partials/jant-data.html?raw";
 import PARTIAL_HEAD from "./export-theme/layouts/partials/head.html?raw";
 import PARTIAL_HEADER from "./export-theme/layouts/partials/header.html?raw";
 import PARTIAL_FOOTER from "./export-theme/layouts/partials/footer.html?raw";
@@ -78,31 +81,98 @@ import PARTIAL_MEDIA_GALLERY from "./export-theme/layouts/partials/media-gallery
 import PARTIAL_REPLY from "./export-theme/layouts/partials/reply.html?raw";
 import PARTIAL_THREAD_PREVIEW from "./export-theme/layouts/partials/thread-preview.html?raw";
 import PARTIAL_FEATURED_THREAD from "./export-theme/layouts/partials/featured-thread.html?raw";
+import PARTIAL_SMART_COLLECTION_MEMBERS from "./export-theme/layouts/partials/smart-collection-members.html?raw";
+import PARTIAL_COLLECTION_THREADS from "./export-theme/layouts/partials/collection-threads.html?raw";
+import PARTIAL_COLLECTION_MEMBERS from "./export-theme/layouts/partials/collection-members.html?raw";
+import PARTIAL_LATEST_MEMBERS from "./export-theme/layouts/partials/latest-members.html?raw";
+import PARTIAL_FEATURED_MEMBERS from "./export-theme/layouts/partials/featured-members.html?raw";
 import LAYOUT_RSS from "./export-theme/layouts/_default/rss.xml?raw";
 import PARTIAL_FEED_POST_CONTENT from "./export-theme/layouts/partials/feed-post-content.xml?raw";
 
+import { suggestSyncRepoName } from "../lib/github-sync-repo-name.js";
+import { getPostPath, toAbsoluteSiteUrl } from "../lib/url.js";
 import type { StorageDriver } from "../lib/storage.js";
 import { base64ToUint8Array } from "../lib/favicon.js";
+import { makeZip } from "client-zip";
 import {
   SYSTEM_NAV_KEYS,
+  isFeedNavKey,
   type Collection,
   type Media,
   type NavItem,
+  type PathRecord,
   type Post,
+  type SmartCollection,
   type SystemNavKey,
 } from "../types.js";
 
-/** A file entry in the exported Hugo site. */
-export interface ExportFile {
+/** A file of the exported Hugo site whose text or bytes the export holds. */
+export interface ExportContentFile {
   path: string;
   content: string | Uint8Array;
+  /**
+   * Scaffolding the destination owns once it exists. A fresh export always
+   * carries it — the ZIP is a new tree, and `site export --directory` refuses
+   * a non-empty directory — but GitHub Sync writes it only when the
+   * repository does not have it yet, so an edit there survives every later
+   * push. Deploy config is the case that needs this: the Worker name has to
+   * be corrected by hand when it does not match the Worker already serving
+   * the domain.
+   */
+  scaffoldOnce?: boolean;
+}
+
+/**
+ * A media file of the exported site, named but not read: the archive streams
+ * it from storage as it is written. Reading every bundled file up front held a
+ * site's media in memory, and on a Docker site with 3 GB of local media the
+ * container was killed before it answered.
+ */
+export interface ExportStoredFile {
+  path: string;
+  storageKey: string;
+}
+
+/** A file entry in the exported Hugo site. */
+export type ExportFile = ExportContentFile | ExportStoredFile;
+
+/**
+ * @param file - An export file entry
+ * @returns Whether its bytes are still in storage
+ * @example
+ * if (isStoredExportFile(file)) await readStoredExportFile(file, storage);
+ */
+export function isStoredExportFile(file: ExportFile): file is ExportStoredFile {
+  return "storageKey" in file;
+}
+
+/**
+ * Read a stored export file's bytes, for a consumer that needs them whole.
+ *
+ * @param file - A stored export file
+ * @param storage - The site's storage
+ * @returns The bytes, or null when the object is gone
+ * @example
+ * const bytes = await readStoredExportFile(file, storage);
+ */
+export async function readStoredExportFile(
+  file: ExportStoredFile,
+  storage: StorageDriver,
+): Promise<Uint8Array | null> {
+  const object = await storage.get(file.storageKey);
+  if (!object?.body) return null;
+  return new Uint8Array(await new Response(object.body).arrayBuffer());
 }
 
 export interface ExportService {
   /** Generate a flat list of files for a complete Hugo site. */
   generateHugoFiles(): Promise<ExportFile[]>;
-  /** Generate a ZIP archive of the Hugo site. */
-  generateHugoSite(): Promise<Uint8Array>;
+  /**
+   * The Hugo site as a ZIP stream. Stored media is read from storage one file
+   * at a time as the stream is consumed, so memory stays flat whatever the
+   * size of the site; the archive switches to ZIP64 past 4 GiB.
+   */
+  generateHugoSite(): Promise<ReadableStream<Uint8Array>>;
 }
 
 export interface SiteConfig {
@@ -110,6 +180,10 @@ export interface SiteConfig {
   siteUrl: string;
   siteDescription: string;
   siteLanguage: string;
+  /** Whether the source site serves per-language browsing views. */
+  multilingualEnabled: boolean;
+  /** Non-primary content languages, in switcher order. */
+  additionalLanguages: readonly string[];
   showJantBrandingOnHome: boolean;
   /** Whether anonymous JSON reads are enabled on the source Jant site. */
   publicApiEnabled: boolean;
@@ -117,6 +191,8 @@ export interface SiteConfig {
   rssFeedsEnabled: boolean;
   /** "latest" or "featured" — drives the default RSS nav link in the exported site. */
   mainRssFeed: string;
+  /** "list" or "grid" — the layout the exported archive page opens with. */
+  archiveDefaultLayout: string;
   siteFooter: string;
   showHeaderAvatar: boolean;
   siteAvatarUrl: string;
@@ -137,7 +213,16 @@ export interface SiteConfig {
   sitePathPrefix?: string;
   navItems: Pick<
     NavItem,
-    "type" | "systemKey" | "label" | "url" | "position" | "placement"
+    | "type"
+    | "systemKey"
+    | "label"
+    | "targetTitle"
+    | "url"
+    | "position"
+    | "placement"
+    | "collectionId"
+    | "smartCollectionId"
+    | "postId"
   >[];
   /** Items per page for Hugo pagination — kept in sync with the main site's PAGE_SIZE. */
   pageSize: number;
@@ -161,6 +246,16 @@ type ExportedCollectionDirectoryItem =
       recentActivityLabel?: string | null;
       recentActivityIso?: string | null;
     }
+  | {
+      type: "smart_collection";
+      sequence: string;
+      slug: string;
+      title: string;
+      descriptionHtml?: string | null;
+      entryCount?: number;
+      recentActivityLabel?: string | null;
+      recentActivityIso?: string | null;
+    }
   | {
       type: "divider";
       label: string | null;
@@ -170,12 +265,14 @@ type ExportedCollectionDirectoryItem =
       sequence: string;
       label: string;
       url: string;
+      /** The link description as the author wrote it, or null if empty. */
+      description?: string | null;
       /** Rendered HTML of the link description, or null if empty. */
       descriptionHtml?: string | null;
     };
 
 interface ExportCollectionDirectorySourceItem {
-  type: "collection" | "divider" | "link";
+  type: "collection" | "smart_collection" | "divider" | "link";
   label?: string | null;
   url?: string | null;
   description?: string | null;
@@ -187,6 +284,13 @@ interface ExportCollectionDirectorySourceItem {
     threadCount?: number;
     recentActivityAt?: number;
   };
+  smartCollection?: {
+    slug: string;
+    title: string;
+    description?: string | null;
+    threadCount?: number;
+    recentActivityAt?: number;
+  };
 }
 
 interface SiteIconAssets {
@@ -249,13 +353,24 @@ export function createExportService(
      * base64-encodes attachment bytes.
      */
     bundleMedia?: boolean;
+    /**
+     * Name of the GitHub repository this export is destined for, when it has
+     * one. It decides the Worker name in `wrangler.jsonc`: Cloudflare names a
+     * Worker after the repository it was imported from, and requires the two
+     * to match. GitHub Sync passes it; a ZIP export has no repository and
+     * falls back to the repository name Sync would suggest for the site.
+     */
+    repoName?: string | null;
   } = {},
 ): ExportService {
   return {
     async generateHugoFiles() {
       const collectionDirectoryDataPromise =
         typeof services.collections.listDirectoryData === "function"
-          ? services.collections.listDirectoryData()
+          ? // The export builds a public static site, so it sees what a
+            // signed-out reader sees. Language narrowing is not applied: the
+            // export walks every language itself.
+            services.collections.listDirectoryData({ isAuthenticated: false })
           : Promise.resolve(null);
 
       // 1. Query all data
@@ -281,6 +396,7 @@ export function createExportService(
         slugMap,
         aliasMap,
         collectionSlugMap,
+        standalonePaths,
       ] = await Promise.all([
         services.collections.getCollectionsByPostIds(rootPostIds),
         services.collections.getCollectionEntriesByThreadIds(rootPostIds),
@@ -288,6 +404,7 @@ export function createExportService(
         services.paths.getPostSlugMap(allPostIds),
         services.paths.getPostAliases(rootPostIds),
         services.paths.getCollectionSlugMap(allCollections.map((c) => c.id)),
+        services.paths.listStandalonePaths(),
       ]);
       // Denormalized title lookup so front-matter collection refs can
       // include a title label without templates having to resolve another
@@ -304,14 +421,56 @@ export function createExportService(
         allPosts,
         collectionsByRoot,
       );
-      const exportedCollectionDirectoryItems =
-        buildExportedCollectionDirectoryItems(
-          collectionDirectoryData?.items ??
-            allCollections.map((collection) => ({
-              id: collection.id,
+      // Smart collections travel as their conditions (a section page per
+      // smart collection, below): a site importing the export recreates them,
+      // and the Hugo theme applies the same conditions to the posts it has, so
+      // the page keeps up with the repository instead of freezing the matches
+      // of the day it was exported.
+      const exportedSmartCollections: {
+        smartCollection: SmartCollection;
+        selection: HugoSmartCollectionSelection;
+      }[] = [];
+      const smartCollectionSlugMap = new Map<string, string>();
+      for (const smartCollection of collectionDirectoryData?.smartCollections ??
+        []) {
+        const selection = toExportedSelection(
+          smartCollection.selection,
+          collectionSlugMap,
+        );
+        if (!selection) {
+          // eslint-disable-next-line no-console -- A dropped page must leave a trace
+          console.warn(
+            `Export: smart collection /${smartCollection.slug} filters by a collection that no longer exists, so it was left out.`,
+          );
+          continue;
+        }
+        smartCollectionSlugMap.set(smartCollection.id, smartCollection.slug);
+        exportedSmartCollections.push({ smartCollection, selection });
+      }
+      const exportableDirectoryItems: ExportCollectionDirectorySourceItem[] =
+        collectionDirectoryData?.items
+          ? collectionDirectoryData.items
+              .filter(
+                (item) =>
+                  item.type !== "smart_collection" ||
+                  (item.smartCollection !== undefined &&
+                    smartCollectionSlugMap.has(item.smartCollection.id)),
+              )
+              .map((item) => ({
+                type: item.type,
+                label: item.label,
+                url: item.url,
+                description: item.description,
+                collection: item.collection,
+                smartCollection: item.smartCollection,
+              }))
+          : allCollections.map((collection) => ({
               type: "collection" as const,
               collection,
-            })),
+            }));
+      const exportedCollectionDirectoryItems =
+        buildExportedCollectionDirectoryItems(
+          exportableDirectoryItems,
           collectionSlugMap,
           collectionMetrics,
         );
@@ -323,9 +482,14 @@ export function createExportService(
         list.push(reply);
         repliesByThread.set(reply.threadId, list);
       }
-      // Sort replies by createdAt within each thread
+      // Thread order, as `posts.getThread` reads it: after the root, which
+      // leads as `_index.md`, creation time, then ID.
       for (const list of repliesByThread.values()) {
-        list.sort((a, b) => a.createdAt - b.createdAt);
+        list.sort(
+          (a, b) =>
+            a.createdAt - b.createdAt ||
+            (a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+        );
       }
 
       // 3. Build file list
@@ -376,6 +540,19 @@ export function createExportService(
         });
       }
 
+      // Smart collection landing pages: the conditions, which the theme's
+      // `smart-collection-members` partial applies to the exported posts.
+      for (const { smartCollection, selection } of exportedSmartCollections) {
+        exportFiles.push({
+          path: `content/${smartCollection.slug}/_index.md`,
+          content: await buildSmartCollectionSection(
+            smartCollection,
+            selection,
+            siteConfig.rssFeedsEnabled,
+          ),
+        });
+      }
+
       // Section + home scaffolding.
       exportFiles.push({
         path: "hugo.toml",
@@ -397,13 +574,33 @@ export function createExportService(
       const usedSlugs = new Set<string>();
       for (const s of slugMap.values()) usedSlugs.add(s);
       for (const s of collectionSlugMap.values()) usedSlugs.add(s);
-      if (!usedSlugs.has("featured")) {
+      for (const s of smartCollectionSlugMap.values()) usedSlugs.add(s);
+      const hasFeaturedSection = !usedSlugs.has("featured");
+      if (hasFeaturedSection) {
         exportFiles.push({
           path: "content/featured/_index.md",
           content: await buildFeaturedSection(siteConfig.rssFeedsEnabled),
         });
       }
 
+      // Feed subscribers are the one audience the export can lose silently:
+      // their reader polls a `/feed` address that this site does not serve.
+      // With feeds off there is nothing to redirect to, and the live site had
+      // no feeds to have been subscribed to either. The author's own
+      // redirects go in too; an old feed address is often one of them.
+      const redirectSections = [
+        siteConfig.rssFeedsEnabled
+          ? buildFeedRedirects(siteConfig.mainRssFeed, hasFeaturedSection)
+          : null,
+        buildCustomUrlRedirects(standalonePaths),
+      ].filter((section): section is string => section !== null);
+      if (redirectSections.length > 0) {
+        exportFiles.push({
+          path: "static/_redirects",
+          content: redirectSections.join("\n"),
+        });
+      }
+
       // Single data file consumed by templates via `hugo.Data.jant`. The
       // collection directory lives on the same object as `directory` so
       // everything Jant owns round-trips in one place.
@@ -413,6 +610,12 @@ export function createExportService(
           siteConfig,
           iconAssets,
           exportedCollectionDirectoryItems,
+          {
+            postSlugs: slugMap,
+            collectionSlugs: collectionSlugMap,
+            smartCollectionSlugs: smartCollectionSlugMap,
+            standalonePaths,
+          },
         ),
       });
 
@@ -461,6 +664,10 @@ export function createExportService(
         path: "themes/jant/layouts/collection/single.html",
         content: LAYOUT_COLLECTION_SINGLE,
       });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/jant-data.html",
+        content: PARTIAL_JANT_DATA,
+      });
       exportFiles.push({
         path: "themes/jant/layouts/partials/head.html",
         content: PARTIAL_HEAD,
@@ -497,6 +704,30 @@ export function createExportService(
         path: "themes/jant/layouts/partials/featured-thread.html",
         content: PARTIAL_FEATURED_THREAD,
       });
+      exportFiles.push({
+        path: "themes/jant/layouts/smart_collection/list.html",
+        content: LAYOUT_SMART_COLLECTION_LIST,
+      });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/smart-collection-members.html",
+        content: PARTIAL_SMART_COLLECTION_MEMBERS,
+      });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/collection-threads.html",
+        content: PARTIAL_COLLECTION_THREADS,
+      });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/collection-members.html",
+        content: PARTIAL_COLLECTION_MEMBERS,
+      });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/latest-members.html",
+        content: PARTIAL_LATEST_MEMBERS,
+      });
+      exportFiles.push({
+        path: "themes/jant/layouts/partials/featured-members.html",
+        content: PARTIAL_FEATURED_MEMBERS,
+      });
       exportFiles.push({
         path: "themes/jant/layouts/_default/rss.xml",
         content: LAYOUT_RSS,
@@ -546,28 +777,48 @@ export function createExportService(
 
       exportFiles.push({
         path: "README.md",
-        content: buildReadme(siteConfig.siteName),
+        content: buildReadme(siteConfig, hasFeaturedSection),
       });
       exportFiles.push({
         path: ".gitignore",
         content: buildGitignore(),
       });
+      exportFiles.push({
+        path: WRANGLER_CONFIG_PATH,
+        content: buildWranglerConfig(siteConfig, deps.repoName),
+        scaffoldOnce: true,
+      });
 
       return exportFiles;
     },
 
     async generateHugoSite() {
       const exportFiles = await this.generateHugoFiles();
-      const { zipSync } = await import("fflate");
-      const encoder = new TextEncoder();
-      const files: Record<string, Uint8Array> = {};
-      for (const file of exportFiles) {
-        files[file.path] =
-          typeof file.content === "string"
-            ? encoder.encode(file.content)
-            : file.content;
+      const storage = deps.storage ?? null;
+      const lastModified = new Date();
+
+      async function* entries() {
+        for (const file of exportFiles) {
+          if (!isStoredExportFile(file)) {
+            yield { name: file.path, lastModified, input: file.content };
+            continue;
+          }
+
+          const object = storage ? await storage.get(file.storageKey) : null;
+          if (!object?.body) {
+            // The archive is already streaming; say which file is missing
+            // rather than leave it out without a trace.
+            // eslint-disable-next-line no-console -- A dropped file must leave a trace
+            console.warn(
+              `Export: ${file.storageKey} is missing from storage, so ${file.path} is not in the archive.`,
+            );
+            continue;
+          }
+          yield { name: file.path, lastModified, input: object.body };
+        }
       }
-      return zipSync(files);
+
+      return makeZip(entries());
     },
   };
 }
@@ -676,6 +927,25 @@ function buildExportedCollectionEntriesForThread(
   return resolved;
 }
 
+/**
+ * Whether the site's timeline cuts this post's text short.
+ *
+ * Shares the boundary with the served feed rather than approximating it: Hugo
+ * has its own summary rule and would cut somewhere else, so the answer is
+ * computed here and carried as front matter.
+ *
+ * @param post - The post being exported
+ * @returns true when the timeline shows less than the post's page
+ * @example
+ * isPostTruncated(longArticle); // true
+ */
+function isPostTruncated(post: Post): boolean {
+  return (
+    extractTimelineSummary(post.body, !!post.title, { namespace: post.id })
+      ?.hasMore === true
+  );
+}
+
 function collectionEntriesToRefs(
   entries: readonly ExportedCollectionEntry[],
 ): HugoCollectionRef[] {
@@ -844,12 +1114,39 @@ async function buildThreadBundle(
   // Root aliases = historical root slugs + every reply slug (so
   // /{reply-slug}/ gets a Hugo alias page that redirects/anchors to
   // the thread root).
-  const aliases = [...rootAliases];
-  for (const reply of threadReplies) {
-    const replySlug = slugMap.get(reply.id) ?? reply.slug;
-    aliases.push(`/${replySlug}/`);
+  //
+  // A draft or private root is not built, so its alias pages would have no
+  // target: Hugo still writes them, `.Permalink` resolves to the empty
+  // string, and the result is a page that redirects to itself. The thread
+  // is unpublished, so its historical URLs are unpublished with it.
+  const rootIsUnpublished =
+    root.status === "draft" || root.visibility === "private";
+  const aliases: string[] = [];
+  if (!rootIsUnpublished) {
+    aliases.push(...rootAliases);
+    for (const reply of threadReplies) {
+      const replySlug = slugMap.get(reply.id) ?? reply.slug;
+      aliases.push(`/${replySlug}/`);
+    }
   }
 
+  // The `<id>` Jant's feeds give this Thread's entry, kept as the string it
+  // was. A reader recognises an entry it has seen by that string alone, and
+  // the Hugo page's own URL differs from it — a trailing slash always, and
+  // the slug where Jant uses a custom path — so an exported feed that used
+  // the page URL would show every entry to every subscriber again after the
+  // move. RFC 4287 §4.2.6 asks for exactly this: an entry's ID must not
+  // change when its feed is migrated or exported.
+  const siteUrl = siteConfig.siteUrl.trim();
+  const feedId =
+    !rootIsUnpublished && siteUrl
+      ? toAbsoluteSiteUrl(
+          getPostPath(rootSlug, rootAliases[0]),
+          siteUrl,
+          siteConfig.sitePathPrefix,
+        )
+      : undefined;
+
   // Root front matter.
   const rootMedia = mediaByPost.get(root.id) ?? [];
   const rootEmissions = rootMedia.map((m) =>
@@ -863,6 +1160,10 @@ async function buildThreadBundle(
       root.publishedAt !== null
         ? toISOString(root.publishedAt)
         : toISOString(root.createdAt),
+    created:
+      root.publishedAt !== null && root.createdAt !== root.publishedAt
+        ? toISOString(root.createdAt)
+        : undefined,
     updated:
       root.updatedAt && root.updatedAt !== root.publishedAt
         ? toISOString(root.updatedAt)
@@ -878,15 +1179,19 @@ async function buildThreadBundle(
         : undefined,
     slug: rootSlug,
     type: "post",
-    draft:
-      root.status === "draft" || root.visibility === "private"
-        ? true
-        : undefined,
+    draft: rootIsUnpublished ? true : undefined,
     aliases: aliases.length > 0 ? aliases : undefined,
+    feed_id: feedId,
     format: root.format,
     status: root.status,
     visibility: root.visibility,
+    // Language is Thread-uniform, so only the root emits it; the importer
+    // re-derives replies from their root. `translation_group` is an opaque
+    // shared key — importing the whole site keeps translated posts linked.
+    language: root.language ?? undefined,
+    translation_group: root.translationGroupId ?? undefined,
     summary_text: getArchiveSummaryText(root) ?? undefined,
+    truncated: isPostTruncated(root) || undefined,
     link_url: root.format === "link" && root.url ? root.url : undefined,
     source_name: root.format === "quote" && root.title ? root.title : undefined,
     source_url: root.format === "quote" && root.url ? root.url : undefined,
@@ -906,7 +1211,7 @@ async function buildThreadBundle(
     media: rootMediaList.length > 0 ? rootMediaList : undefined,
   };
 
-  const rootBody = root.body ? tiptapJsonToMarkdown(root.body) : "";
+  const rootBody = root.body ? postBodyToMarkdown(root.body, rootSlug) : "";
   files.push({
     path: `content/${rootSlug}/_index.md`,
     content: `${await formatFrontMatter(rootFrontMatter)}\n${rootBody}${rootBody.endsWith("\n") ? "" : "\n"}`,
@@ -922,7 +1227,7 @@ async function buildThreadBundle(
     media: rootMedia[i] as Media,
   }))) {
     if (emission.inlinePath) {
-      const file = await readMediaResourceFile(
+      const file = toStoredMediaFile(
         storage,
         media.storageKey,
         emission.inlinePath,
@@ -930,7 +1235,7 @@ async function buildThreadBundle(
       if (file) files.push(file);
     }
     if (emission.inlinePosterPath && media.posterKey) {
-      const posterFile = await readMediaResourceFile(
+      const posterFile = toStoredMediaFile(
         storage,
         media.posterKey,
         emission.inlinePosterPath,
@@ -939,8 +1244,8 @@ async function buildThreadBundle(
     }
   }
 
-  // Replies as nested leaf bundles.
-  for (const reply of threadReplies) {
+  // Replies as nested leaf bundles, in Thread order.
+  for (const [replyIndex, reply] of threadReplies.entries()) {
     const replySlug = slugMap.get(reply.id) ?? reply.slug;
     const replyMedia = mediaByPost.get(reply.id) ?? [];
     const replyEmissions = replyMedia.map((m) =>
@@ -954,12 +1259,17 @@ async function buildThreadBundle(
         reply.publishedAt !== null
           ? toISOString(reply.publishedAt)
           : toISOString(reply.createdAt),
+      created:
+        reply.publishedAt !== null && reply.createdAt !== reply.publishedAt
+          ? toISOString(reply.createdAt)
+          : undefined,
       updated:
         reply.updatedAt && reply.updatedAt !== reply.publishedAt
           ? toISOString(reply.updatedAt)
           : undefined,
       slug: replySlug,
       type: "post",
+      weight: replyIndex + 1,
       draft:
         reply.status === "draft" || reply.visibility === "private"
           ? true
@@ -969,6 +1279,7 @@ async function buildThreadBundle(
       status: reply.status,
       visibility: reply.visibility,
       summary_text: getArchiveSummaryText(reply) ?? undefined,
+      truncated: isPostTruncated(reply) || undefined,
       link_url: reply.format === "link" && reply.url ? reply.url : undefined,
       source_name:
         reply.format === "quote" && reply.title ? reply.title : undefined,
@@ -983,7 +1294,9 @@ async function buildThreadBundle(
       media: replyMediaList.length > 0 ? replyMediaList : undefined,
     };
 
-    const replyBody = reply.body ? tiptapJsonToMarkdown(reply.body) : "";
+    const replyBody = reply.body
+      ? postBodyToMarkdown(reply.body, replySlug)
+      : "";
     files.push({
       path: `content/${rootSlug}/${replySlug}/index.md`,
       content: `${await formatFrontMatter(replyFrontMatter)}\n${replyBody}${replyBody.endsWith("\n") ? "" : "\n"}`,
@@ -994,7 +1307,7 @@ async function buildThreadBundle(
       media: replyMedia[i] as Media,
     }))) {
       if (emission.inlinePath) {
-        const file = await readMediaResourceFile(
+        const file = toStoredMediaFile(
           storage,
           media.storageKey,
           emission.inlinePath,
@@ -1002,7 +1315,7 @@ async function buildThreadBundle(
         if (file) files.push(file);
       }
       if (emission.inlinePosterPath && media.posterKey) {
-        const posterFile = await readMediaResourceFile(
+        const posterFile = toStoredMediaFile(
           storage,
           media.posterKey,
           emission.inlinePosterPath,
@@ -1016,25 +1329,17 @@ async function buildThreadBundle(
 }
 
 /**
- * Read a media record's bytes from storage and return an ExportFile so
- * they can be bundled next to the post as a Hugo page resource. Returns
- * null when storage is unavailable or the object cannot be read, in
- * which case the front matter entry still points at the resource name
- * and the CLI's pull-media step (or a later sync) can fill it in.
+ * Name a media object for the archive to bundle as `static/media/…`. Its
+ * bytes are read when the archive is written. Null when the export has no
+ * storage, in which case the front matter entry still points at the file and
+ * the CLI's pull-media step can fill it in.
  */
-async function readMediaResourceFile(
+function toStoredMediaFile(
   storage: StorageDriver | null,
   storageKey: string,
   bundlePath: string,
-): Promise<ExportFile | null> {
-  if (!storage) return null;
-  try {
-    const bytes = await readStorageObjectBytes(storage, storageKey);
-    if (!bytes) return null;
-    return { path: bundlePath, content: bytes };
-  } catch {
-    return null;
-  }
+): ExportStoredFile | null {
+  return storage ? { path: bundlePath, storageKey } : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -1096,6 +1401,48 @@ async function buildCollectionSection(
   return `${await formatFrontMatter(frontMatter)}\n`;
 }
 
+/**
+ * A smart collection's conditions as its section page carries them: the
+ * stored selection, with the collection named by slug rather than ID so an
+ * import into another site can resolve it. Null when the collection it names
+ * is gone.
+ */
+function toExportedSelection(
+  selection: SmartCollection["selection"],
+  collectionSlugs: ReadonlyMap<string, string>,
+): HugoSmartCollectionSelection | null {
+  const { collection, media, ...rest } = selection;
+  const exported: HugoSmartCollectionSelection = { ...rest };
+  if (collection !== undefined) {
+    const slug = collection[0] ? collectionSlugs.get(collection[0]) : undefined;
+    if (!slug) return null;
+    exported.collection = slug;
+  }
+  if (media !== undefined) {
+    exported.media = typeof media === "string" ? media : [...media];
+  }
+  return exported;
+}
+
+async function buildSmartCollectionSection(
+  smartCollection: SmartCollection,
+  selection: HugoSmartCollectionSelection,
+  rssFeedsEnabled: boolean,
+): Promise<string> {
+  const frontMatter: HugoFrontMatter = {
+    title: smartCollection.title,
+    slug: smartCollection.slug,
+    type: "smart_collection",
+    summary_text: smartCollection.description ?? undefined,
+    sort_order: smartCollection.sort,
+    display_layout: smartCollection.layout ?? undefined,
+    selection,
+    // Opt into Atom output at /{slug}/index.xml.
+    outputs: rssFeedsEnabled ? ["html", "rss"] : ["html"],
+  };
+  return `${await formatFrontMatter(frontMatter)}\n`;
+}
+
 // ---------------------------------------------------------------------------
 // Summary extraction (kept from the previous exporter)
 // ---------------------------------------------------------------------------
@@ -1260,6 +1607,7 @@ function buildExportedCollectionDirectoryItems(
         sequence: sequenceLabels[index] ?? "",
         label: item.label,
         url: item.url,
+        description: description || null,
         descriptionHtml: description
           ? renderMarkdown(description, {
               namespace: `collection-directory-link-${sequenceLabels[index] ?? index}`,
@@ -1269,6 +1617,31 @@ function buildExportedCollectionDirectoryItems(
       return;
     }
 
+    if (item.type === "smart_collection") {
+      const smartCollection = item.smartCollection;
+      if (!smartCollection?.slug) return;
+      const smartDescription = smartCollection.description?.trim();
+      exportedItems.push({
+        type: "smart_collection",
+        sequence: sequenceLabels[index] ?? "",
+        slug: smartCollection.slug,
+        title: smartCollection.title || smartCollection.slug,
+        descriptionHtml: smartDescription
+          ? renderMarkdown(smartDescription, {
+              namespace: `smart-collection-${smartCollection.slug}`,
+            })
+          : null,
+        entryCount: smartCollection.threadCount,
+        recentActivityLabel: formatCollectionActivityLabel(
+          smartCollection.recentActivityAt,
+        ),
+        recentActivityIso: formatCollectionActivityIso(
+          smartCollection.recentActivityAt,
+        ),
+      });
+      return;
+    }
+
     const collection = item.collection;
     if (!collection?.id) {
       return;
@@ -1356,13 +1729,21 @@ function buildExportedCollectionMetrics(
 // Nav item resolution
 // ---------------------------------------------------------------------------
 
+/**
+ * Label to bake into the static site.
+ *
+ * Mirrors `getNavItemDisplayLabel`: a stored label is the author's own words
+ * and wins, an empty one means the item follows what it points at. The export
+ * has no i18n runtime, so built-in destinations fall back to their English
+ * default rather than a translated one.
+ */
 function resolveNavItemLabel(item: SiteConfig["navItems"][number]): string {
   if (item.label) return item.label;
   if (item.systemKey) {
     const definition = SYSTEM_NAV_KEYS[item.systemKey as SystemNavKey];
     if (definition) return definition.defaultLabel;
   }
-  return item.label;
+  return item.targetTitle?.trim() || item.label;
 }
 
 /**
@@ -1389,7 +1770,10 @@ function resolveNavItemUrl(
   }
   if (item.systemKey === "collections") return "/collections/";
   if (item.systemKey === "archive") return "/archive/";
-  if (item.systemKey === "rss") {
+  // `subscribe` addresses a Jant route, and the exported site has no page at
+  // it. Rather than exporting a nav entry that 404s, it resolves to the feed
+  // that page would have recommended — the same file `rss` points at.
+  if (item.systemKey === "rss" || item.systemKey === "subscribe") {
     return mainRssFeed === "featured" ? "/featured/index.xml" : "/index.xml";
   }
   return item.url;
@@ -1419,7 +1803,12 @@ function buildHugoToml(config: SiteConfig): string {
     `languageCode = "${escapeTomlString(language)}"`,
     `defaultContentLanguage = "${escapeTomlString(language)}"`,
     'theme = "jant"',
-    `paginate = ${config.pageSize}`,
+    // No site-level `paginate` / `[pagination] pagerSize`: every paginated
+    // template calls `.Paginate` with an explicit page size taken from
+    // `params.page_size` / `params.archive_page_size`, so a site-level value
+    // would never be read. `paginate` was also deprecated in Hugo v0.128.0
+    // and has since been removed, so emitting it fails the build outright on
+    // any version that only knows `[pagination] pagerSize`.
     "enableRobotsTXT = true",
     // Disable Hugo's built-in taxonomies — jant has no tags or categories
     // and the default empty /tags/ and /categories/ pages are noise. This
@@ -1468,6 +1857,7 @@ function buildHugoToml(config: SiteConfig): string {
     "[params]",
     `  description = "${escapeTomlString(config.siteDescription)}"`,
     `  main_rss_feed = "${escapeTomlString(config.mainRssFeed)}"`,
+    `  archive_default_layout = "${escapeTomlString(config.archiveDefaultLayout)}"`,
     `  public_api_enabled = ${config.publicApiEnabled}`,
     `  rss_feeds_enabled = ${config.rssFeedsEnabled}`,
     `  show_jant_branding_on_home = ${config.showJantBrandingOnHome}`,
@@ -1495,10 +1885,42 @@ function buildHugoToml(config: SiteConfig): string {
   return `${parts.join("\n")}\n`;
 }
 
+/** What `data/jant.toml` needs to name nav targets and standalone URLs. */
+interface JantDataTargets {
+  postSlugs: ReadonlyMap<string, string>;
+  collectionSlugs: ReadonlyMap<string, string>;
+  smartCollectionSlugs: ReadonlyMap<string, string>;
+  standalonePaths: readonly PathRecord[];
+}
+
+/** The key and slug `data/jant.toml` names a nav item's target by. */
+function resolveNavItemTarget(
+  item: SiteConfig["navItems"][number],
+  targets: JantDataTargets,
+): { key: string; slug: string } | null {
+  const slug =
+    item.type === "collection" && item.collectionId
+      ? targets.collectionSlugs.get(item.collectionId)
+      : item.type === "smart_collection" && item.smartCollectionId
+        ? targets.smartCollectionSlugs.get(item.smartCollectionId)
+        : item.type === "page" && item.postId
+          ? targets.postSlugs.get(item.postId)
+          : undefined;
+  if (!slug) return null;
+  const key =
+    item.type === "collection"
+      ? "collection_slug"
+      : item.type === "smart_collection"
+        ? "smart_collection_slug"
+        : "post_slug";
+  return { key, slug };
+}
+
 function buildJantDataToml(
   config: SiteConfig,
   iconAssets: SiteIconAssets,
   directoryItems: readonly ExportedCollectionDirectoryItem[],
+  targets: JantDataTargets,
 ): string {
   const footerHtml = config.siteFooter
     ? renderMarkdown(config.siteFooter, { namespace: "site-footer" })
@@ -1510,7 +1932,10 @@ function buildJantDataToml(
     `site_name = "${escapeTomlString(config.siteName)}"`,
     `site_description = "${escapeTomlString(config.siteDescription)}"`,
     `site_language = "${escapeTomlString(config.siteLanguage)}"`,
+    `multilingual_enabled = ${config.multilingualEnabled}`,
+    `additional_languages = "${escapeTomlString(config.additionalLanguages.join(","))}"`,
     `main_rss_feed = "${escapeTomlString(config.mainRssFeed)}"`,
+    `archive_default_layout = "${escapeTomlString(config.archiveDefaultLayout)}"`,
     `public_api_enabled = ${config.publicApiEnabled}`,
     `rss_feeds_enabled = ${config.rssFeedsEnabled}`,
     `show_jant_branding_on_home = ${config.showJantBrandingOnHome}`,
@@ -1547,13 +1972,14 @@ function buildJantDataToml(
   }
 
   for (const item of config.navItems) {
-    // `settings` is authenticated-only and has no corresponding page in the
-    // static Hugo site — drop it at export time so it never shows up in nav.
-    if (item.systemKey === "settings") continue;
+    // `settings` has no page in the static site; the theme skips it, and the
+    // entry stays so an import back into Jant keeps it. Both feed entries
+    // resolve to a feed file, so with feeds off both would export a link to
+    // something that was never written.
     if (
       !config.rssFeedsEnabled &&
       item.type === "system" &&
-      item.systemKey === "rss"
+      isFeedNavKey(item.systemKey)
     ) {
       continue;
     }
@@ -1566,13 +1992,22 @@ function buildJantDataToml(
     );
     parts.push(`system_key = "${escapeTomlString(item.systemKey ?? "")}"`);
     parts.push(`placement = "${escapeTomlString(item.placement ?? "header")}"`);
+    // `label` above is what the theme shows. The author's own wording, when
+    // there is one, and the target by slug are what an import restores.
+    if (item.label) {
+      parts.push(`custom_label = "${escapeTomlString(item.label)}"`);
+    }
+    const target = resolveNavItemTarget(item, targets);
+    if (target) {
+      parts.push(`${target.key} = "${escapeTomlString(target.slug)}"`);
+    }
   }
 
   for (const item of directoryItems) {
     parts.push("");
     parts.push("[[directory]]");
     parts.push(`type = "${escapeTomlString(item.type)}"`);
-    if (item.type === "collection") {
+    if (item.type === "collection" || item.type === "smart_collection") {
       parts.push(`sequence = "${escapeTomlString(item.sequence)}"`);
       parts.push(`slug = "${escapeTomlString(item.slug)}"`);
       parts.push(`title = "${escapeTomlString(item.title)}"`);
@@ -1602,6 +2037,9 @@ function buildJantDataToml(
       parts.push(`sequence = "${escapeTomlString(item.sequence)}"`);
       parts.push(`label = "${escapeTomlString(item.label)}"`);
       parts.push(`url = "${escapeTomlString(item.url)}"`);
+      if (item.description) {
+        parts.push(`description = "${escapeTomlString(item.description)}"`);
+      }
       if (item.descriptionHtml) {
         parts.push(
           `description_html = "${escapeTomlString(item.descriptionHtml)}"`,
@@ -1610,13 +2048,254 @@ function buildJantDataToml(
     }
   }
 
+  // Custom URLs that name no post or collection. Post aliases travel in each
+  // root's `aliases:`; these would otherwise not travel at all.
+  for (const record of targets.standalonePaths) {
+    parts.push("");
+    parts.push("[[custom_url]]");
+    parts.push(`path = "${escapeTomlString(record.path)}"`);
+    parts.push(`kind = "${escapeTomlString(record.kind)}"`);
+    if (record.kind === "redirect" && record.redirectToPath) {
+      parts.push(`to = "/${escapeTomlString(record.redirectToPath)}"`);
+      parts.push(`status = ${record.redirectType ?? 301}`);
+    }
+    if (record.kind === "archive" && record.archiveQuery) {
+      parts.push(`archive_query = "${escapeTomlString(record.archiveQuery)}"`);
+    }
+  }
+
   return `${parts.join("\n")}\n`;
 }
 
+/**
+ * The author's redirects as `_redirects` rules, or null when there are none.
+ *
+ * @param standalonePaths - Custom URLs that name no post or collection
+ * @returns The `_redirects` section
+ * @example
+ * buildCustomUrlRedirects([redirectFromAtomXml]); // "# Redirects...\n/atom.xml  /feed  301\n"
+ */
+function buildCustomUrlRedirects(
+  standalonePaths: readonly PathRecord[],
+): string | null {
+  const rules = standalonePaths
+    .filter((record) => record.kind === "redirect" && record.redirectToPath)
+    .map(
+      (record) =>
+        [
+          `/${record.path}`,
+          `/${record.redirectToPath}`,
+          record.redirectType ?? 301,
+        ] as const,
+    );
+  if (rules.length === 0) return null;
+
+  const width = Math.max(...rules.map(([from]) => from.length));
+  return `# Redirects set up under Settings → Custom URLs on the live site.
+
+${rules.map(([from, to, status]) => `${from.padEnd(width)}  ${to}  ${status}`).join("\n")}
+`;
+}
+
 // ---------------------------------------------------------------------------
-// README + .gitignore
+// README + .gitignore + _redirects + wrangler.jsonc
 // ---------------------------------------------------------------------------
 
+/** Repo-relative path of the Cloudflare Workers deploy config. */
+export const WRANGLER_CONFIG_PATH = "wrangler.jsonc";
+
+/**
+ * Normalize a string into a name Cloudflare accepts for a Worker: lowercase
+ * letters, digits, and hyphens, at most 63 characters.
+ */
+function toWorkerName(raw: string): string {
+  return (
+    raw
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, "-")
+      // 63 characters is Cloudflare's limit; trimming hyphens comes after the
+      // cut so a truncated name cannot end on one.
+      .slice(0, 63)
+      .replace(/^-+|-+$/g, "")
+  );
+}
+
+/**
+ * Pick the Worker name for `wrangler.jsonc`.
+ *
+ * Cloudflare requires this name to match the Worker in the dashboard, and its
+ * repository-import flow names a new Worker after the repository — so the
+ * repository name is the one value that lines up without the user editing
+ * anything. An export with no repository behind it (a ZIP, or
+ * `site export --directory`) uses the repository name the GitHub Sync
+ * settings page prefills for this site, so pushing the export to a repository
+ * created with that default still matches.
+ *
+ * @param repoName - The destination repository's name, without the owner.
+ * @param siteUrl - The exported site's URL, used when there is no repository.
+ * @returns A name Cloudflare accepts.
+ * @example
+ * deriveWorkerName("owenyoung-blog", "https://notes.example.com"); // "owenyoung-blog"
+ * deriveWorkerName(null, "https://notes.example.com"); // "notes-jant-sync"
+ */
+export function deriveWorkerName(
+  repoName: string | null | undefined,
+  siteUrl: string,
+): string {
+  return (
+    toWorkerName(repoName ?? "") || toWorkerName(suggestSyncRepoName(siteUrl))
+  );
+}
+
+/**
+ * Build the Cloudflare Workers deploy config for the exported site.
+ *
+ * Workers Builds has no "build output directory" field — that one belongs to
+ * Pages — so `public/` can only be declared here. Without this file the
+ * dashboard's default deploy command (`npx wrangler deploy`) fails on a repo
+ * that has no Worker name to deploy under.
+ *
+ * `build.command` is here because nothing else runs Hugo. Workers Builds
+ * detects frameworks from a `package.json`, which a Hugo site does not have,
+ * so importing this repository leaves the build command empty and the deploy
+ * fails on a `public/` that was never generated. Wrangler runs a custom build
+ * before deploying, assets-only Workers included, which makes
+ * `npx wrangler deploy` self-sufficient — on Cloudflare's image, on any CI,
+ * and in a local checkout. Cloudflare's image ships Hugo extended, so the
+ * command needs no install step; anyone who does fill in a dashboard build
+ * command should leave it empty here to keep Hugo from running twice.
+ *
+ * Deliberately absent:
+ * - `main`: a site with only static assets is a valid assets-only Worker.
+ * - `not_found_handling`: the theme emits no `404.html` to point it at.
+ *
+ * @param config - The exported site's configuration.
+ * @param repoName - The destination repository's name, when there is one.
+ * @returns The contents of `wrangler.jsonc`.
+ * @example
+ * buildWranglerConfig(config, "my-blog"); // '{\n  // Cloudflare Workers …'
+ */
+function buildWranglerConfig(
+  config: SiteConfig,
+  repoName: string | null | undefined,
+): string {
+  const name = deriveWorkerName(repoName, config.siteUrl);
+  // `compatibility_date` pins the Workers runtime behavior to what shipped on
+  // the day this export was generated, which is what a new Worker wants.
+  const compatibilityDate = new Date().toISOString().slice(0, 10);
+  return `{
+  // Cloudflare Workers deploy config for the built site.
+  //
+  // "name" must match the Worker's name in the Cloudflare dashboard: Workers
+  // Builds fails the build when they differ, and a deploy run by hand under
+  // another name goes to another Worker. A Worker imported from a repository
+  // is named after the repository, so Jant uses the repository name when it
+  // knows it, and otherwise the name GitHub Sync suggests for this site's
+  // repository.
+  //
+  // Jant writes this file once and never overwrites it, so your edits stay.
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": ${JSON.stringify(name)},
+  "compatibility_date": ${JSON.stringify(compatibilityDate)},
+  // Wrangler runs this before it uploads, so "npx wrangler deploy" builds the
+  // site first. Leave the build command in the Cloudflare dashboard empty, or
+  // Hugo runs twice.
+  "build": {
+    "command": "hugo --gc --minify"
+  },
+  "assets": {
+    "directory": "./public"
+  }
+}
+`;
+}
+
+/**
+ * Build the `static/_redirects` file that keeps existing feed subscribers
+ * working after the site moves to this export.
+ *
+ * Jant serves its feeds under `/feed` (`/feed`, `/latest/feed`,
+ * `/featured/feed`, `/archive/feed`, `/{collection}/feed`); Hugo serves the
+ * same documents as `index.xml` inside each section. The two namespaces do
+ * not overlap, so every subscriber's saved address 404s the moment the
+ * exported site goes up.
+ *
+ * Hugo's `aliases:` mechanism cannot cover this the way it covers post URLs:
+ * an alias page is a meta-refresh plus a script, and feed readers fetch and
+ * parse XML without running either. Only an HTTP redirect reaches them, which
+ * is host configuration rather than Hugo output — so the export emits the one
+ * format two common static hosts read verbatim (Cloudflare Pages and Netlify).
+ * Hosts that do not read `_redirects` ignore the file; the README carries the
+ * rule for them to translate.
+ *
+ * @param mainRssFeed - The site's main feed setting, "latest" or "featured".
+ * @param hasFeaturedSection - Whether the export emitted a featured section.
+ *   It is skipped when a post or collection already owns the `featured` slug,
+ *   and pointing a redirect at a feed that was never built would turn a live
+ *   subscription into a 404 rather than leaving it merely stale.
+ * @returns The `_redirects` file body.
+ * @example
+ * buildFeedRedirects("latest", true); // "# ...\n/feed  /index.xml  301\n..."
+ */
+function buildFeedRedirects(
+  mainRssFeed: string,
+  hasFeaturedSection: boolean,
+): string {
+  const LATEST = "/index.xml";
+  const FEATURED = "/featured/index.xml";
+  // `/feed` follows the site's main-feed setting, mirroring `renderMainFeed`.
+  // Without a featured section there is nothing to point it at, so it falls
+  // back to the latest feed: a wider feed than the reader subscribed to, but
+  // a live one.
+  const main =
+    mainRssFeed === "featured" && hasFeaturedSection ? FEATURED : LATEST;
+  const featured = hasFeaturedSection ? FEATURED : LATEST;
+
+  const rules: [string, string][] = [
+    ["/feed", main],
+    ["/latest/feed", LATEST],
+    ["/featured/feed", featured],
+    ["/archive/feed", "/archive/index.xml"],
+  ];
+  const legacy: [string, string][] = [
+    ["/feed/latest", LATEST],
+    ["/feed/all", LATEST],
+    ["/feed/featured", featured],
+    ["/feed/atom.xml", main],
+    ["/feed/latest/atom.xml", LATEST],
+    ["/feed/all/atom.xml", LATEST],
+    ["/feed/featured/atom.xml", featured],
+  ];
+
+  // The format only needs whitespace between the columns; padding to the
+  // widest source path keeps the file readable for whoever has to translate
+  // it into another host's redirect syntax.
+  const width = Math.max(
+    ...[...rules, ...legacy].map(([from]) => from.length),
+    "/:slug/feed".length,
+  );
+  const line = ([from, to]: [string, string]) =>
+    `${from.padEnd(width)}  ${to}  301`;
+
+  return `# Feed addresses moved in this export.
+#
+# Jant served its feeds under /feed; Hugo serves them as index.xml inside each
+# section. Cloudflare Pages and Netlify read this file and issue the redirects
+# below, so readers who subscribed to the old addresses keep receiving posts.
+# Other hosts ignore this file — see README.md for the same rules to translate
+# into your host's configuration.
+
+${rules.map(line).join("\n")}
+
+# Aliases the live site answered with a 308. They would die at the same moment.
+${legacy.map(line).join("\n")}
+
+# Collection feeds, by slug. Collections are the only root-level sections that
+# emit Atom, so any other slug 404s here exactly as it did on the live site.
+${line(["/:slug/feed", "/:slug/index.xml"])}
+`;
+}
+
 function buildGitignore(): string {
   return `# Hugo build output
 public/
@@ -1634,14 +2313,126 @@ Thumbs.db
 `;
 }
 
-function buildReadme(siteName: string): string {
+/**
+ * Render a two-column Markdown table with padded cells.
+ *
+ * The values differ per site, so building the rows by hand would leave the
+ * committed README ragged for some exports and aligned for others.
+ *
+ * @param headers - The two column headers.
+ * @param rows - Cell pairs; each cell is wrapped in backticks.
+ * @returns The table as Markdown, without a trailing newline.
+ * @example
+ * renderMarkdownTable(["Jant", "This export"], [["/feed", "/index.xml"]]);
+ */
+/**
+ * Convert a stored post body to the export's Markdown, naming the post when
+ * it can't be converted. An export that dropped the body would read as a
+ * complete archive and restore as an empty post.
+ *
+ * @param body - Stored TipTap JSON
+ * @param slug - The post's slug, for the error
+ * @returns The body as Markdown
+ * @throws {Error} When the stored body isn't a TipTap document
+ * @example
+ * postBodyToMarkdown('{"type":"doc","content":[]}', "hello"); // ""
+ */
+function postBodyToMarkdown(body: string, slug: string): string {
+  try {
+    return tiptapJsonToMarkdown(body);
+  } catch (error) {
+    throw new Error(
+      `Couldn't convert the body of /${slug} to Markdown: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+function renderMarkdownTable(
+  headers: [string, string],
+  rows: [string, string][],
+): string {
+  const cells = rows.map(
+    ([from, to]) => [`\`${from}\``, `\`${to}\``] as [string, string],
+  );
+  const widths: [number, number] = [
+    Math.max(headers[0].length, ...cells.map((r) => r[0].length)),
+    Math.max(headers[1].length, ...cells.map((r) => r[1].length)),
+  ];
+  const line = (a: string, b: string) =>
+    `| ${a.padEnd(widths[0])} | ${b.padEnd(widths[1])} |`;
+  return [
+    line(headers[0], headers[1]),
+    `| ${"-".repeat(widths[0])} | ${"-".repeat(widths[1])} |`,
+    ...cells.map((r) => line(r[0], r[1])),
+  ].join("\n");
+}
+
+/**
+ * Build the export's README.
+ *
+ * @param config - The exported site's configuration.
+ * @param hasFeaturedSection - Whether a featured section was emitted, which
+ *   decides where the feed redirects point.
+ * @returns Markdown for `README.md` at the root of the export.
+ * @example
+ * buildReadme(config, true); // "# My Site — Hugo Export\n..."
+ */
+function buildReadme(config: SiteConfig, hasFeaturedSection: boolean): string {
+  const siteName = config.siteName;
+  const featuredFeed = hasFeaturedSection
+    ? "/featured/index.xml"
+    : "/index.xml";
+  const mainFeed =
+    config.mainRssFeed === "featured" ? featuredFeed : "/index.xml";
+  // Nothing to say about feeds on a site that publishes none, and no
+  // `_redirects` file was written for it either.
+  const staticListing = config.rssFeedsEnabled
+    ? "\n  _redirects              — Feed redirects (see Feeds above)"
+    : "";
+  // The Notes list below says post URLs survive the move. Left alone, that
+  // reads as a promise about every URL, and feed addresses are the exception.
+  const feedNote = config.rssFeedsEnabled
+    ? "\n- Feed addresses are the exception: they move to `index.xml` and stay reachable only through `static/_redirects`. See [Feeds](#feeds)."
+    : "";
+  // Same reason: without feeds there is no `static/_redirects` to explain.
+  const redirectsNote = config.rssFeedsEnabled
+    ? "`static/_redirects` needs no configuration here. Hugo copies it to `public/_redirects` and Workers applies the rules as published.\n\n"
+    : "";
+  // Nothing to say about feeds on a site that publishes none, and no
+  // `_redirects` file was written for it either.
+  const feedRows: [string, string][] = [
+    ["/feed", mainFeed],
+    ["/latest/feed", "/index.xml"],
+    ["/featured/feed", featuredFeed],
+    ["/archive/feed", "/archive/index.xml"],
+    ["/{collection}/feed", "/{collection}/index.xml"],
+  ];
+  const feedTable = renderMarkdownTable(["Jant", "This export"], feedRows);
+  const feedsSection = config.rssFeedsEnabled
+    ? `## Feeds
+
+The feed addresses changed. Jant served them under \`/feed\`; Hugo serves them as \`index.xml\` inside each section:
+
+${feedTable}
+
+A reader who is already subscribed holds one of the old addresses, and a feed reader that gets a 404 stops delivering posts. \`static/_redirects\` maps every old address to its new one with a 301. Cloudflare Pages and Netlify read that file as published; on any other host, translate its rules into that host's redirect configuration before you point the domain here.
+
+Hugo's \`aliases:\` cannot cover this. An alias page redirects with a meta refresh and a script, and feed readers fetch XML without running either — only an HTTP redirect reaches them.
+
+Feed entries keep the IDs Jant gave them, so feed readers don't show old posts again. Each root post stores its ID in \`feed_id\`: the post's address on Jant, which is not its page URL here. Don't change \`feed_id\`, or feed readers show that post again. A post you add here without one uses its page URL.
+
+The **Subscribe** entry in the site navigation points at \`${mainFeed}\`. The exported site has no \`/subscribe\` page; that page belongs to the Jant runtime.
+
+`
+    : "";
   return `# ${siteName} — Hugo Export
 
 This is a static site exported from [Jant](https://github.com/jant-me/jant), ready to build with [Hugo](https://gohugo.io/).
 
 ## Install Hugo
 
-This export targets Hugo **extended 0.160.1+**.
+This export targets Hugo **extended 0.147.7+**.
 
 **macOS (Homebrew):**
 
@@ -1679,10 +2470,27 @@ hugo --minify
 
 The output goes to the \`public/\` directory. Upload it to any static host (Netlify, Vercel, Cloudflare Pages, GitHub Pages, etc.).
 
-## Project structure
+## Deploy to Cloudflare Workers
+
+\`wrangler.jsonc\` at the root is the deploy config: it names the Worker, runs \`hugo --gc --minify\`, and points the upload at \`public/\`. Connect this repository to Cloudflare Workers Builds and leave the commands Cloudflare offers as they are:
+
+| Field           | Value                          |
+| --------------- | ------------------------------ |
+| Build command   | leave empty                    |
+| Deploy command  | \`npx wrangler deploy\`          |
+| Version command | \`npx wrangler versions upload\` |
+
+The build belongs to \`wrangler.jsonc\` rather than to that field: Workers Builds reads a \`package.json\` to detect a framework, a Hugo site has none, and an empty build command deploys a \`public/\` that was never built. Filling the field in as well makes Hugo run twice.
+
+Check one thing before the first deploy: \`name\` in \`wrangler.jsonc\` has to match the Worker's name in the Cloudflare dashboard. Workers Builds fails the build when they differ, and a deploy run by hand under another name goes to another Worker. A Worker imported from a repository is named after the repository, so an export pushed by GitHub Sync uses the repository name. A downloaded export has no repository and uses the name GitHub Sync suggests when it creates one for this site. If the Worker is named something else, change \`name\` to match — Cloudflare names each build token \`<worker-name> build token\`, so the token list is one place to read it.
+
+Jant writes \`wrangler.jsonc\` once and never overwrites it, so a corrected name survives later syncs.
+
+${redirectsNote}${feedsSection}## Project structure
 
 \`\`\`
 hugo.toml                 — Site configuration (baseURL, title, theme, params)
+wrangler.jsonc            — Cloudflare Workers deploy config (see Deploy above)
 content/
   _index.md               — Home section
   archive/_index.md       — Archive section
@@ -1695,7 +2503,7 @@ content/
 data/
   jant.toml               — Nav items, branding, display preferences, ordered collections directory
 themes/jant/              — Bundled Hugo theme (overrideable via layouts/ at the site root)
-static/                   — Copy files here to add them to the published site
+static/                   — Copy files here to add them to the published site${staticListing}
 \`\`\`
 
 ## Customizing
@@ -1721,7 +2529,7 @@ Safe to re-run; files already on disk are reused. Anything that fails to downloa
 ## Notes
 
 - Each thread is a Hugo branch bundle. Replies live as nested leaf bundles with \`build.render = "never"\` so they do not produce standalone URLs; they render inside the thread page.
-- \`/{reply-slug}/\` URLs are preserved via \`aliases:\` on the root post, so old links still land on the right thread anchor.
+- \`/{reply-slug}/\` URLs are preserved via \`aliases:\` on the root post, so old links still land on the right thread anchor.${feedNote}
 - Media is emitted under \`static/media/{id}.ext\` and referenced from a flat \`media:\` array on each post. When a storage provider has a configured public URL (R2/S3/local proxy), the exporter links to the provider URL instead of re-bundling the bytes.
 - Posts with \`draft: true\` in front matter are only built when you pass \`--buildDrafts\` to \`hugo\` / \`hugo serve\`.
 `;