hd-garden 0.5.13 → 0.5.15

package/scripts/check-post.mjs

@@ -6,6 +6,7 @@ import { canonicalSiteDate } from "./site-date.mjs";
 import { gardenSiteRoot } from "./garden-paths.mjs";
 import { checkUiBlock } from "../ui/core/validate.mjs";
 import { checkGardenMarkdown } from "../ui/garden/check.mjs";
+import { checkFileSources } from "../ui/garden/file-paths.mjs";
 
 const siteRoot = gardenSiteRoot();
 const calloutTypes = new Set([
@@ -255,6 +256,45 @@ const scanBody = (errors, content, markdownPath, sourcePath, { warnings = [], dr
   if (fence?.lang === "embed") checkEmbed(errors, fence.body.join("\n"), sourcePath, fence.line);
 };
 
+const markdownBelow = (directory) =>
+  fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) return markdownBelow(full);
+    return entry.name.endsWith(".md") ? [full] : [];
+  });
+
+/** Does the post's Markdown point at this file (garden file, a link)? Then it is there on purpose. */
+const postUses = (postRaw, postPath, file) => {
+  const relative = path.relative(path.dirname(postPath), file).split(path.sep).join("/");
+  return postRaw.includes(`./${relative}`) || postRaw.includes(relative);
+};
+
+/**
+ * `post.md` + `post/` is the post's folder of files, and the build no longer
+ * publishes Markdown inside it as a post. Name each such file, so one that used
+ * to be a post does not disappear from the site unnoticed.
+ */
+const checkFolderMarkdown = (warnings, absolute, raw) => {
+  const contentRoot = path.join(siteRoot, "content");
+  const warn = (file, post) => warnings.push({
+    code: "folder-markdown",
+    line: 1,
+    message: `${path.relative(siteRoot, file)}: 在 ${path.relative(siteRoot, post)} 的同名目录里，不会作为文章发布。建议：它是给读者下载或预览的文件，就在文章里用 garden file 引用；要单独发布，把它移出 ${path.relative(siteRoot, post.replace(/\.md$/u, ""))}/。`,
+  });
+  const folder = absolute.replace(/\.md$/u, "");
+  if (fs.existsSync(folder) && fs.statSync(folder).isDirectory()) {
+    for (const file of markdownBelow(folder).sort()) if (!postUses(raw, absolute, file)) warn(file, absolute);
+  }
+  // Checked directly: the file itself sits in some post's folder.
+  for (let dir = path.dirname(absolute); dir.startsWith(contentRoot + path.sep); dir = path.dirname(dir)) {
+    const post = `${dir}.md`;
+    if (fs.existsSync(post)) {
+      if (!postUses(fs.readFileSync(post, "utf8"), post, absolute)) warn(absolute, post);
+      break;
+    }
+  }
+};
+
 const checkFile = (filePath) => {
   const absolute = path.resolve(siteRoot, filePath);
   const sourcePath = path.relative(siteRoot, absolute);
@@ -300,6 +340,11 @@ const checkFile = (filePath) => {
     const target = item.severity === "warning" ? warnings : errors;
     target.push({ code: item.code, line: item.line, message: `${sourcePath}: ${item.message} 建议：${item.suggestion}` });
   }
+  for (const item of checkFileSources(raw, absolute, path.join(siteRoot, "content"))) {
+    const target = item.severity === "warning" ? warnings : errors;
+    target.push({ code: item.code, line: item.line, message: `${sourcePath}: ${item.message} 建议：${item.suggestion}` });
+  }
+  checkFolderMarkdown(warnings, absolute, raw);
   return { file: sourcePath, errors, warnings };
 };
 

package/scripts/file-preview.mjs

@@ -0,0 +1,138 @@
+/**
+ * The 预览 of a Markdown file in a `garden file` block, rendered at build time.
+ *
+ * The HTML goes to its own file next to the copied Markdown and is fetched
+ * only when a reader opens the preview, so the article page does not carry
+ * it. It is read with the posts' Markdown syntax (markdownSyntaxPlugins) and
+ * the posts' rehype steps: raw HTML, KaTeX, heading ids, highlighting.
+ * What only React adds to a post (copy buttons, Mermaid, link cards) is not
+ * there: a preview is a document to read.
+ *
+ * The client puts this HTML into the page, so anything that would run is
+ * removed here: script-like elements, on* attributes, javascript: and other
+ * non-http URLs (images may still use data:).
+ */
+import rehypeHighlight from "rehype-highlight";
+import rehypeKatex from "rehype-katex";
+import rehypeRaw from "rehype-raw";
+import rehypeSlug from "rehype-slug";
+import rehypeStringify from "rehype-stringify";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+import { markdownSyntaxPlugins } from "../ui/garden/markdown-syntax.mjs";
+
+const DROPPED_ELEMENTS = new Set(["script", "noscript", "iframe", "frame", "frameset", "object", "embed", "applet", "base", "link", "meta", "form", "template"]);
+const URL_PROPERTIES = new Set(["href", "src", "action", "formAction", "poster", "cite", "background", "xLinkHref"]);
+const SAFE_URL = /^(?:https?:|mailto:|tel:|#|\/(?!\/)|\.{0,2}\/|[^:/?#]+(?:[/?#]|$))/iu;
+
+const isSafeUrl = (name, value, tagName) => {
+  const url = String(value).trim().replace(/[\u0000-\u001f\s]+/gu, "");
+  if (name === "src" && tagName === "img" && /^data:image\/(?:png|gif|jpe?g|webp|avif);/iu.test(url)) return true;
+  return SAFE_URL.test(url);
+};
+
+/** Removes what could run once the HTML is in the page. */
+export function rehypePreviewSafety() {
+  return (tree) => {
+    visit(tree, "element", (node, index, parent) => {
+      if (DROPPED_ELEMENTS.has(node.tagName)) {
+        parent.children.splice(index, 1);
+        return index;
+      }
+      for (const name of Object.keys(node.properties ?? {})) {
+        const value = node.properties[name];
+        if (/^on/iu.test(name) || name === "srcDoc" || name === "style" && /expression|url\s*\(\s*['"]?\s*javascript:/iu.test(String(value))) {
+          delete node.properties[name];
+        } else if (URL_PROPERTIES.has(name) && !isSafeUrl(name, value, node.tagName)) {
+          delete node.properties[name];
+        } else if (name === "srcSet" && [].concat(value).some((part) => !isSafeUrl("srcset", String(part).trim().split(/\s+/u)[0], node.tagName))) {
+          delete node.properties[name];
+        }
+      }
+      if (node.tagName === "a" && /^https?:/iu.test(String(node.properties?.href ?? ""))) {
+        node.properties.target = "_blank";
+        node.properties.rel = ["noopener", "noreferrer"];
+      }
+      return undefined;
+    });
+  };
+}
+
+/**
+ * The markup the article's own styles expect, so the drawer looks like the
+ * article: tables scroll inside .table-wrap, code blocks are pre.code with
+ * their language, outside links carry .ext. (Copy buttons, link cards and
+ * favicons are article-only.)
+ */
+export function rehypePreviewShape() {
+  return (tree) => {
+    visit(tree, "element", (node, index, parent) => {
+      if (node.tagName === "table" && !(parent?.type === "element" && parent.properties?.className?.includes?.("table-wrap"))) {
+        parent.children[index] = {
+          type: "element",
+          tagName: "div",
+          properties: { className: ["table-wrap"], role: "region", ariaLabel: "表格，可横向滚动", tabIndex: 0 },
+          children: [node],
+        };
+        return "skip";
+      }
+      if (node.tagName === "pre") {
+        const code = node.children.find((child) => child.type === "element" && child.tagName === "code");
+        const language = [].concat(code?.properties?.className ?? []).map(String).find((name) => name.startsWith("language-"))?.slice(9);
+        node.properties.className = [...[].concat(node.properties.className ?? []), "code"];
+        if (language) node.properties.dataLanguage = language.toUpperCase();
+      }
+      if (node.tagName === "a" && node.properties?.target === "_blank") {
+        node.properties.className = [...[].concat(node.properties.className ?? []), "ext"];
+      }
+      return undefined;
+    });
+  };
+}
+
+/** Markdown → the preview's HTML. `idPrefix` keeps heading ids apart from the article's own. */
+export function renderFilePreview(markdown, { idPrefix = "gf-" } = {}) {
+  return String(
+    unified()
+      .use(remarkParse)
+      .use(markdownSyntaxPlugins)
+      .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeRaw)
+      .use(rehypeKatex)
+      .use(rehypeSlug, { prefix: idPrefix })
+      .use(rehypeHighlight)
+      .use(rehypePreviewSafety)
+      .use(rehypePreviewShape)
+      .use(rehypeStringify)
+      .processSync(markdown),
+  );
+}
+
+const escapeText = (value) => String(value).replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+
+/**
+ * The published preview: a small standalone page, so a reader without
+ * JavaScript who follows the 预览 link gets something readable. The drawer
+ * takes only what is inside <main>.
+ */
+export function previewDocument(html, { title = "预览" } = {}) {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeText(title)}</title>
+<style>body{margin:0;background:#fbfaf7;color:#1f1e1c;font:16px/1.75 -apple-system,BlinkMacSystemFont,"PingFang SC","Noto Sans SC",sans-serif}main{max-width:720px;margin:0 auto;padding:32px 20px 64px}img{max-width:100%;height:auto}pre{overflow:auto;padding:12px 14px;background:#f2f0ea;border-radius:8px}code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em}.table-wrap{overflow-x:auto}table{border-collapse:collapse}th,td{border:1px solid #ddd8cc;padding:6px 10px}a{color:inherit}.katex-html{display:none}@media (prefers-color-scheme:dark){body{background:#191918;color:#e9e6df}pre{background:#252422}th,td{border-color:#3a3833}}</style>
+</head>
+<body><main class="gf-preview-doc">
+${html}
+</main></body>
+</html>
+`;
+}
+
+/** Where the preview of a copied file is published: next to it. */
+export const previewFileName = (fileName) => `${fileName}.preview.html`;

package/scripts/file-sizes.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Sizes of remote files named in `garden file` fences (OSS and other https
+ * links), so the card can say 「ZIP · 48 MB」 without the page asking anyone.
+ *
+ * Every build sends one HEAD request per URL (a one-byte range request when
+ * HEAD gives no length). Results go into `file-sizes.json`; commit it. When a
+ * request fails, the last known size is kept. A file that never answered has
+ * no size on its card. The build never fails here.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import matter from "gray-matter";
+import { isPublicUrl } from "./link-meta-core.mjs";
+import { assertPublicDns, pool } from "./link-assets.mjs";
+import { scanFences, parseGardenBlock } from "../ui/garden/parse.mjs";
+import { isRemoteSrc, maskHtmlComments, readFileProps } from "../ui/garden/file-block.mjs";
+
+export const CACHE_FILE = "file-sizes.json";
+const TIMEOUT_MS = 8000;
+const HEADERS = { "user-agent": "Mozilla/5.0 (compatible; GardenFileSize/1.0)" };
+
+export function readFileSizeCache(siteRoot) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(siteRoot, CACHE_FILE), "utf8"));
+    return { files: data?.files && typeof data.files === "object" ? data.files : {} };
+  } catch {
+    return { files: {} };
+  }
+}
+
+/** Remote `src` values in the `garden file` fences of one Markdown body. */
+export function remoteFileSources(markdown) {
+  const found = [];
+  for (const fence of scanFences(maskHtmlComments(markdown))) {
+    if (!/^garden\s+file\b/iu.test(fence.info ?? "")) continue;
+    const block = parseGardenBlock(fence.info, fence.body);
+    if (!block || block.error) continue;
+    for (const file of readFileProps(block.props).files) if (isRemoteSrc(file.src)) found.push(file.src);
+  }
+  return [...new Set(found)];
+}
+
+const lengthOf = (response) => {
+  const range = /\/(\d+)\s*$/u.exec(response.headers.get("content-range") ?? "")?.[1];
+  if (range) return Number(range);
+  const length = Number(response.headers.get("content-length"));
+  return Number.isFinite(length) && length > 0 && response.status !== 206 ? length : 0;
+};
+
+async function request(url, method, fetcher, checkHost) {
+  let current = url;
+  for (let hop = 0; hop < 4; hop += 1) {
+    if (!isPublicUrl(current)) throw new Error("not a public URL");
+    await checkHost(new URL(current).hostname);
+    const response = await fetcher(current, {
+      method,
+      redirect: "manual",
+      headers: method === "GET" ? { ...HEADERS, range: "bytes=0-0" } : HEADERS,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    await response.body?.cancel().catch(() => {});
+    if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+      current = new URL(response.headers.get("location"), current).toString();
+      continue;
+    }
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return lengthOf(response);
+  }
+  throw new Error("too many redirects");
+}
+
+/** Size in bytes of a remote file: HEAD first, then a one-byte range GET. */
+export async function probeFileSize(url, { fetch: fetcher = globalThis.fetch, checkHost = assertPublicDns } = {}) {
+  let headError = null;
+  try {
+    const size = await request(url, "HEAD", fetcher, checkHost);
+    if (size > 0) return size;
+  } catch (error) {
+    headError = error;
+    if (error?.message === "not a public URL") throw error;
+  }
+  const size = await request(url, "GET", fetcher, checkHost).catch((error) => {
+    throw headError ?? error;
+  });
+  if (size > 0) return size;
+  throw new Error("no length");
+}
+
+function markdownFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) return markdownFiles(full);
+    return /\.mdx?$/iu.test(entry.name) ? [full] : [];
+  });
+}
+
+export function collectRemoteFiles(siteRoot) {
+  const urls = new Set();
+  for (const file of markdownFiles(path.join(siteRoot, "content"))) {
+    const { content } = matter(fs.readFileSync(file, "utf8"));
+    for (const src of remoteFileSources(content)) urls.add(src);
+  }
+  return [...urls].sort();
+}
+
+/**
+ * Asks every remote file for its size and writes the cache. A failed request
+ * keeps the cached size; a URL that never answered stays out of the cache.
+ */
+export async function refreshFileSizes({ siteRoot, fetch: fetcher, checkHost, log = () => {}, concurrency = 6 }) {
+  const cache = readFileSizeCache(siteRoot);
+  const urls = collectRemoteFiles(siteRoot);
+  const files = {};
+  let failed = 0;
+  await pool(urls, concurrency, async (url) => {
+    try {
+      files[url] = { size: await probeFileSize(url, { fetch: fetcher, checkHost }) };
+    } catch (error) {
+      failed += 1;
+      const cached = cache.files[url];
+      if (cached?.size > 0) {
+        files[url] = cached;
+        log(`警告：读不到文件大小，沿用上次的结果：${url}（${error.message}）`);
+      } else {
+        log(`警告：读不到文件大小，这个文件不显示大小：${url}（${error.message}）`);
+      }
+    }
+  });
+  const sorted = Object.fromEntries(Object.keys(files).sort().map((url) => [url, files[url]]));
+  const next = `${JSON.stringify({ version: 1, files: sorted }, null, 2)}\n`;
+  const file = path.join(siteRoot, CACHE_FILE);
+  const previous = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (next !== previous && (urls.length || previous)) fs.writeFileSync(file, next);
+  log(`文件大小：${urls.length} 个远程文件，读到 ${urls.length - failed} 个，失败 ${failed} 个。`);
+  return { files: sorted, failed };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  await refreshFileSizes({ siteRoot, log: (line) => process.stdout.write(`${line}\n`) }).catch((error) => {
+    process.stdout.write(`警告：文件大小没有更新（${error.message}），继续构建。\n`);
+  });
+}

package/scripts/prepare-pages-output.mjs

@@ -21,6 +21,12 @@ const forbiddenFileNames = new Set([
   "wrangler.jsonc",
 ]);
 const forbiddenExtensions = new Set([".map", ".md", ".ts", ".tsx"]);
+// The build copies into media/ only the files a post links to (images, garden file downloads):
+// a Markdown file there is a download the author offers, not leaked source.
+const publishedExtensions = { media: new Set([".md"]) };
+
+const isPublishedFile = (relativePath) =>
+  publishedExtensions[relativePath.split("/", 1)[0]]?.has(path.extname(relativePath)) === true;
 const deploymentVersionPlaceholder = "00000000-0000-4000-8000-000000000000";
 
 function fail(message) {
@@ -55,7 +61,7 @@ async function inspectTree(root, directory = root) {
     if (forbiddenFileNames.has(entry.name)) {
       fail(`不允许源码配置：${relativePath}`);
     }
-    if (entry.isFile() && forbiddenExtensions.has(path.extname(entry.name))) {
+    if (entry.isFile() && forbiddenExtensions.has(path.extname(entry.name)) && !isPublishedFile(relativePath)) {
       fail(`不允许源码或 Source Map：${relativePath}`);
     }
     if (entry.isDirectory()) await inspectTree(root, absolutePath);

package/scripts/redirects.mjs

@@ -20,47 +20,14 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { configuredSiteAddress } from "../ui/garden/same-site.mjs";
+import { withTrailingSlash } from "../ui/garden/site-href.mjs";
+import { resolveBrand } from "./brand.mjs";
 
 const escapeHtml = (value) => String(value).replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
 
-/** Valid `{ from, to }` pairs from the config; anything malformed is reported and skipped. */
-export function readRedirects(config = {}, warn = () => {}) {
-  const map = config?.redirects;
-  if (!map) return [];
-  if (typeof map !== "object" || Array.isArray(map)) {
-    warn("redirects 应写成「旧路径: 新地址」的映射，已忽略。");
-    return [];
-  }
-  const pairs = [];
-  for (const [rawFrom, rawTo] of Object.entries(map)) {
-    let from = String(rawFrom).trim();
-    const to = String(rawTo ?? "").trim();
-    try {
-      from = decodeURI(from);
-    } catch {
-      // keep as written
-    }
-    if (!from.startsWith("/") || from.startsWith("//") || from === "/" || /(^|\/)\.\.?(\/|$)/u.test(from) || /[?#]/u.test(from)) {
-      warn(`redirects：旧路径 ${rawFrom} 必须是站内路径（以 / 开头，不带 ?、# 和 ..），已跳过。`);
-      continue;
-    }
-    if (!(to.startsWith("/") && !to.startsWith("//")) && !/^https?:\/\//iu.test(to)) {
-      warn(`redirects：${rawFrom} 的新地址 ${rawTo} 应以 / 开头或是完整网址，已跳过。`);
-      continue;
-    }
-    pairs.push({ from, to });
-  }
-  return pairs;
-}
-
-/** `/columns/<slug>/` → `/columns/#<slug>` for every valid column slug in columns.yaml. */
-export function columnRedirects(columnsConfig = {}) {
-  const columns = Array.isArray(columnsConfig?.columns) ? columnsConfig.columns : [];
-  return columns
-    .map((column) => (column && typeof column.slug === "string" ? column.slug.trim() : ""))
-    .filter((slug) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug))
-    .map((slug) => ({ from: `/columns/${slug}/`, to: `/columns/#${slug}` }));
-}
+// Shared with the article renderer, which rewrites links to old addresses (ui/garden/internal-links.mjs).
+export { columnRedirects, readRedirects } from "../ui/garden/internal-links.mjs";
+import { columnRedirects, readRedirects } from "../ui/garden/internal-links.mjs";
 
 /** The file an old path is served from: `/a/b/` and `/a/b` → a/b/index.html, `/a/b.html` → a/b.html. */
 export function redirectFile(from) {
@@ -68,13 +35,15 @@ export function redirectFile(from) {
   return /\.html?$/iu.test(clean) ? clean : path.posix.join(clean.replace(/\/+$/u, ""), "index.html");
 }
 
-export function redirectPage({ href, canonical }) {
+export function redirectPage({ href, canonical, icon = "" }) {
+  // The site's own icon, so the browser does not go looking for /favicon.ico.
+  const iconLink = icon ? `\n<link rel="icon" href="${escapeHtml(icon)}"${/\.svg(?:[?#]|$)/iu.test(icon) ? ' type="image/svg+xml"' : ""}>` : "";
   return `<!doctype html>
 <html lang="zh-CN">
 <head>
 <meta charset="utf-8">
 <title>页面已移动</title>
-<link rel="canonical" href="${escapeHtml(canonical)}">
+<link rel="canonical" href="${escapeHtml(canonical)}">${iconLink}
 <meta http-equiv="refresh" content="0; url=${escapeHtml(href)}">
 <script>location.replace(${JSON.stringify(href).replace(/</gu, "\\u003c")}${href.includes("#") ? "" : " + location.hash"})</script>
 </head>
@@ -86,11 +55,17 @@ export function redirectPage({ href, canonical }) {
 }
 
 /**
- * Write one page per redirect into `outDir`. A redirect is skipped, with a
- * warning, when a real page already lives at the old path or when a site path
- * it points to was not built. Never throws for a bad entry.
+ * Write one page per redirect into `outDir`. Returns what was written, how
+ * many pages the valid entries call for, and the entries that got no page.
+ *
+ * A malformed entry (not a site path, a bad target, the same old path twice)
+ * is left out with a warning and does not count. A valid entry is skipped,
+ * also with a warning, when a real page already lives at the old path or when
+ * the site path it points to was not built. Both are problems with that one
+ * entry, so they do not stop the build: `written` plus `skipped` makes up
+ * `expected`.
  */
-export function writeRedirects({ outDir, config = {}, env = {}, basePath = "", log = () => {}, extra = [] }) {
+export function generateRedirects({ outDir, config = {}, env = {}, basePath = "", log = () => {}, extra = [], icon = "" }) {
   const base = String(basePath ?? "").replace(/\/+$/u, "");
   let origin = "";
   try {
@@ -100,15 +75,32 @@ export function writeRedirects({ outDir, config = {}, env = {}, basePath = "", l
     origin = "";
   }
   const written = [];
+  const skipped = [];
   const configured = readRedirects(config, log);
   // Configured redirects win over generated ones for the same old path.
   const taken = new Set(configured.map(({ from }) => redirectFile(from)));
-  const pairs = [...configured, ...extra.filter(({ from }) => !taken.has(redirectFile(from)))];
+  const candidates = [...configured, ...extra.filter(({ from }) => !taken.has(redirectFile(from)))];
+  const seen = new Set();
+  const pairs = [];
+  for (const pair of candidates) {
+    const file = redirectFile(pair.from);
+    if (seen.has(file)) {
+      log(`redirects：${pair.from} 和前面的旧路径是同一个页面，已跳过。`);
+      continue;
+    }
+    seen.add(file);
+    pairs.push(pair);
+  }
   for (const { from, to } of pairs) {
     const file = path.join(outDir, redirectFile(from));
-    if (!path.resolve(file).startsWith(path.resolve(outDir) + path.sep)) continue;
+    if (!path.resolve(file).startsWith(path.resolve(outDir) + path.sep)) {
+      log(`redirects：${from} 不在站点目录里，已跳过。`);
+      skipped.push({ from, to, reason: "outside" });
+      continue;
+    }
     if (fs.existsSync(file)) {
       log(`redirects：${from} 已经有页面，没有覆盖。`);
+      skipped.push({ from, to, reason: "page-exists" });
       continue;
     }
     const external = /^https?:\/\//iu.test(to);
@@ -118,30 +110,63 @@ export function writeRedirects({ outDir, config = {}, env = {}, basePath = "", l
         .some((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
       if (!built) {
         log(`redirects：${from} 指向的 ${to} 不存在，已跳过。`);
+        skipped.push({ from, to, reason: "missing-target" });
         continue;
       }
     }
-    const href = external ? to : `${base}${to}`;
+    // A static export serves pages as folders: the target keeps the trailing slash like every site link.
+    const href = external ? to : withTrailingSlash(`${base}${to}`);
     const canonical = external || !origin ? href : `${origin}${href}`;
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, redirectPage({ href, canonical }));
+    fs.writeFileSync(file, redirectPage({ href, canonical, icon }));
     written.push({ from, to: href, file });
   }
-  return written;
+  return { written, expected: pairs.length, skipped };
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+/** The pages written by `generateRedirects`. Never throws for a bad entry. */
+export function writeRedirects(options) {
+  return generateRedirects(options).written;
+}
+
+/**
+ * The build step. A bad entry, a missing target and a page already at the old
+ * path only print a warning. Exit code 1 when the step throws, or when the
+ * pages written are not the valid entries minus the ones skipped with a
+ * warning (a page went missing without a reason).
+ */
+export function runRedirectStep({ siteRoot, env = process.env, out = process.stdout, err = process.stderr, generate = generateRedirects }) {
   const outDir = path.join(siteRoot, "dist", "client");
   try {
     const config = parseYaml(fs.readFileSync(path.join(siteRoot, "site.config.yaml"), "utf8")) ?? {};
     const columnsFile = path.join(siteRoot, "content", "columns.yaml");
     const extra = fs.existsSync(columnsFile) ? columnRedirects(parseYaml(fs.readFileSync(columnsFile, "utf8")) ?? {}) : [];
-    if ((config.redirects || extra.length) && fs.existsSync(outDir)) {
-      const written = writeRedirects({ outDir, config, env: process.env, basePath: process.env.NEXT_PUBLIC_BASE_PATH ?? "", log: (line) => process.stdout.write(`警告：${line}\n`), extra });
-      process.stdout.write(`旧地址跳转页：${written.length} 个。\n`);
+    if (!config.redirects && !extra.length) return 0;
+    if (!fs.existsSync(outDir)) throw new Error(`找不到构建产物 ${path.relative(siteRoot, outDir)}`);
+    const basePath = env.NEXT_PUBLIC_BASE_PATH ?? "";
+    const { written, expected, skipped } = generate({
+      outDir,
+      config,
+      env,
+      basePath,
+      icon: resolveBrand(siteRoot, config, basePath.replace(/\/+$/u, "")).favicon,
+      log: (line) => out.write(`警告：${line}\n`),
+      extra,
+    });
+    out.write(`旧地址跳转页：${written.length} 个${skipped.length ? `，跳过 ${skipped.length} 个（见上面的警告）` : ""}。\n`);
+    const due = expected - skipped.length;
+    if (written.length !== due) {
+      err.write(`错误：旧地址跳转页应生成 ${due} 个（${expected} 条有效配置，跳过 ${skipped.length} 条），实际生成了 ${written.length} 个，构建中止。\n`);
+      return 1;
     }
+    return 0;
   } catch (error) {
-    process.stdout.write(`警告：旧地址跳转页没有生成（${error.message}），继续构建。\n`);
+    err.write(`错误：旧地址跳转页生成失败（${error.message}），构建中止。\n`);
+    return 1;
   }
 }
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const siteRoot = process.env.GARDEN_SITE ? path.resolve(process.env.GARDEN_SITE) : process.cwd();
+  process.exitCode = runRedirectStep({ siteRoot });
+}

package/templates/garden-blocks.md

@@ -126,3 +126,14 @@ intent: |
 ---
 <State batch={1} />
 ```
+
+## file · 文件
+
+给读者一份可以下载的文件：规格包、PDF、示例代码。Markdown、HTML、PDF 还能在页面里预览。
+
+不该用：只是引用一个网页时用 card；要在正文里直接展示的图表或页面用 html。
+
+```garden file
+src: ./post-name/spec.zip
+note: 一句话说明里面有什么
+```

package/templates/garden-snippets.plist

@@ -117,5 +117,14 @@ intent: |
     <key>shortcut</key>
     <string>;ginteractive</string>
   </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden file
+src: ./post-name/spec.zip
+note: 一句话说明里面有什么
+```</string>
+    <key>shortcut</key>
+    <string>;gfile</string>
+  </dict>
 </array>
 </plist>

package/ui/core/transform.mjs

@@ -3,6 +3,7 @@ import { parse as parseYaml } from "yaml";
 import { compileUiBlock, jsonFence, readPayload } from "./compile.mjs";
 import { findBlocks, scanFences } from "./fence.mjs";
 import { renderStatic } from "./static.mjs";
+import { fileFeedMarkdown, fileSearchText } from "../garden/file-block.mjs";
 
 /**
  * Turns authored `ui` / `intent` fences into what the site renders.
@@ -59,6 +60,17 @@ function widgetCaption(body) {
   }
 }
 
+/** Props of a `garden file` fence (authored or built), or null for any other fence. */
+function fileFenceProps(fence) {
+  if (fence.lang !== "garden" || !/^file(?:\s|$)/iu.test(fence.info ?? "")) return null;
+  try {
+    const data = parseYaml(fence.body);
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
 function replaceFences(content, replacer) {
   let output = content;
   for (const fence of [...scanFences(content)].reverse()) {
@@ -94,6 +106,8 @@ export function contentToSearchText(content) {
     }
     if (fence.lang === "intent") return " ";
     if (fence.lang === "widget") return ` ${widgetCaption(fence.body).caption} `;
+    const file = fileFenceProps(fence);
+    if (file) return ` ${fileSearchText(file)} `;
     return undefined;
   });
 }
@@ -113,6 +127,8 @@ export function contentForFeed(content, { pageUrl = "", siteUrl = "" } = {}) {
       const href = absolute(src, siteUrl);
       return `${caption}${href ? `（[打开图表](${href})）` : ""}`;
     }
+    const file = fileFenceProps(fence);
+    if (file) return fileFeedMarkdown(file, { siteUrl });
     return undefined;
   });
 }
@@ -132,6 +148,8 @@ export function contentForDistribution(content, { pageUrl = "", siteUrl = "" } =
       const href = absolute(src, siteUrl);
       return `${caption}${href ? `（[打开图表](${href})）` : ""}`;
     }
+    const file = fileFenceProps(fence);
+    if (file) return fileFeedMarkdown(file, { siteUrl });
     return undefined;
   });
 }