hd-garden 0.5.1 → 0.5.3

package/scripts/brand.mjs

@@ -0,0 +1,59 @@
+/**
+ * The site's logo and icons, from `brand` in site.config.yaml:
+ *
+ *   brand:
+ *     logo: brand/logo.svg          # SVG file in the site, shown before the name; false hides it
+ *     favicon: /favicon.svg         # URL under public/
+ *     appleTouchIcon: /apple-touch-icon.png
+ *
+ * The logo is inlined so it follows the text colour: draw it with
+ * `stroke="currentColor"` or `fill="currentColor"`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+// Garden's own mark: a leaf on an h, cropped to its strokes.
+export const DEFAULT_LOGO = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="6 2 18 27" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 27V10"/><path d="M10 10C10 5.5 13.5 3.5 18 3.5C18 7.5 15 10 10 10Z"/><path d="M10 19C10 15.5 12.5 13.5 15.5 13.5S21 15.5 21 19V27"/></svg>';
+
+/** Keep only the `<svg>` element, without scripts, event handlers or external references. */
+export function cleanSvg(markup) {
+  const match = String(markup ?? "").match(/<svg\b[\s\S]*<\/svg>/iu);
+  if (!match) return "";
+  return match[0]
+    .replace(/<!--[\s\S]*?-->/gu, "")
+    .replace(/<(script|foreignObject)\b[\s\S]*?<\/\1>/giu, "")
+    .replace(/\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/giu, "")
+    .replace(/\s+(?:xlink:)?href\s*=\s*("[^"#][^"]*"|'[^'#][^']*')/giu, "")
+    // The header sets the size; the file's own width and height would fight it.
+    .replace(/^<svg\b([^>]*)>/iu, (whole, attrs) => `<svg${attrs.replace(/\s(width|height)\s*=\s*("[^"]*"|'[^']*')/giu, "")} aria-hidden="true" focusable="false">`)
+    .replace(/\s*\n\s*/gu, "");
+}
+
+const publicUrl = (value, basePath) => {
+  const url = String(value);
+  if (/^(https?:)?\/\//iu.test(url) || url.startsWith("data:")) return url;
+  return `${basePath}${url.startsWith("/") ? url : `/${url}`}`;
+};
+
+export function resolveBrand(siteRoot, config = {}, basePath = "", warn = () => {}) {
+  const brand = config?.brand ?? {};
+  let logo = "";
+  if (brand.logo !== false && brand.logo !== "none") {
+    let markup = DEFAULT_LOGO;
+    if (typeof brand.logo === "string" && brand.logo.trim()) {
+      const resolved = path.resolve(siteRoot, brand.logo.replace(/^\//u, ""));
+      if (!resolved.startsWith(path.resolve(siteRoot) + path.sep) || !fs.existsSync(resolved)) {
+        warn(`brand.logo 找不到文件 ${brand.logo}，使用默认图标。`);
+      } else {
+        markup = fs.readFileSync(resolved, "utf8");
+      }
+    }
+    logo = cleanSvg(markup);
+    if (!logo) warn(`brand.logo 不是 SVG：${brand.logo}，不显示图标。`);
+  }
+  return {
+    logo,
+    favicon: publicUrl(brand.favicon || "/favicon.svg", basePath),
+    appleTouchIcon: brand.appleTouchIcon === false ? "" : publicUrl(brand.appleTouchIcon || "/apple-touch-icon.png", basePath),
+  };
+}

package/scripts/build-content.mjs

@@ -10,6 +10,9 @@ import { countDemoWords } from "../ui/garden/word-count.mjs";
 import { referenceDomain } from "../ui/garden/references.mjs";
 import { linkAssetsForRender } from "./link-assets.mjs";
 import { cardUrls } from "../ui/garden/markdown-links.mjs";
+import { configuredSiteAddress, sameSiteMatcher } from "../ui/garden/same-site.mjs";
+import { resolveBrand } from "./brand.mjs";
+import { imageSources, readImageCache, sizeFromBytes } from "./image-sizes.mjs";
 import { buildFullIndex, buildSearchIndex } from "../ui/garden/search-index.mjs";
 import { coverImageSet, loadSharp } from "./cover-images.mjs";
 
@@ -39,6 +42,9 @@ const siteUrl = (process.env.SITE_URL ?? process.env.NEXT_PUBLIC_SITE_URL ?? "ht
 const publicBaseUrl = basePath && !siteUrl.endsWith(basePath)
   ? `${siteUrl}${basePath}`
   : siteUrl;
+// Full URLs to this address are internal links: no new tab, no card.
+const siteAddress = configuredSiteAddress(siteConfig, process.env);
+const sameSite = sameSiteMatcher(siteAddress, basePath);
 const siteName = process.env.SITE_NAME ?? siteConfig.name;
 const siteDescription = process.env.SITE_DESCRIPTION ?? siteConfig.description;
 
@@ -527,6 +533,40 @@ const thoughts = readMarkdownTree(path.join(contentRoot, "thoughts"), "thought")
   (a, b) => Date.parse(b.date) - Date.parse(a.date),
 );
 
+// Intrinsic image sizes for width/height on <img>: local files are read now,
+// remote ones come from image-sizes.json (written by scripts/image-sizes.mjs).
+function localImageFile(src) {
+  const clean = src.split(/[?#]/u, 1)[0];
+  const copied = assetFiles.get(clean)?.destination;
+  if (copied) return copied;
+  if (!clean.startsWith("/") || clean.startsWith("//")) return null;
+  let pathname;
+  try {
+    pathname = decodeURIComponent(basePath && clean.startsWith(`${basePath}/`) ? clean.slice(basePath.length) : clean);
+  } catch {
+    return null;
+  }
+  const publicDir = path.join(root, "public");
+  const file = path.resolve(publicDir, `.${pathname}`);
+  return file.startsWith(publicDir + path.sep) && fs.existsSync(file) && fs.statSync(file).isFile() ? file : null;
+}
+const remoteImageSizes = readImageCache(root).images;
+const imageSizes = {};
+for (const entry of [...posts, ...columns, ...thoughts]) {
+  for (const src of imageSources(entry.content)) {
+    if (imageSizes[src]) continue;
+    if (/^https?:\/\//iu.test(src)) {
+      const size = remoteImageSizes[src];
+      if (size?.width > 0 && size?.height > 0) imageSizes[src] = { width: size.width, height: size.height };
+      continue;
+    }
+    const file = localImageFile(src);
+    const size = file ? sizeFromBytes(fs.readFileSync(file)) : null;
+    if (size) imageSizes[src] = size;
+    else if (file) console.warn(`警告：读不到图片尺寸，这张图不带宽高：${src}`);
+  }
+}
+
 assertUnique(posts, (item) => item.path, "博文路径");
 assertUnique(columns, (item) => `${item.column}/${item.path}`, "专栏路径");
 assertUnique(
@@ -616,6 +656,7 @@ export const columns = ${JSON.stringify(columns, null, 2)} as ContentEntry[];
 export const thoughts = ${JSON.stringify(thoughts, null, 2)} as ContentEntry[];
 export const a2WordCounts = ${JSON.stringify(a2WordCounts, null, 2)} as Record<string, number>;
 export const linkAssets = ${JSON.stringify(linkAssetsForRender(root, basePath), null, 2)} as LinkAssets;
+export const imageSizes: Record<string, { width: number; height: number }> = ${JSON.stringify(imageSizes)};
 `;
 
 fs.mkdirSync(path.dirname(output), { recursive: true });
@@ -630,6 +671,10 @@ export const githubUrl = ${JSON.stringify(`https://github.com/${siteConfig.autho
 export const searchIndexUrl = ${JSON.stringify(`${basePath}/search-index.json?v=${contentHash}`)};
 // Every body as plain text, fetched in the background after load; the name changes with the text.
 export const searchFull = ${JSON.stringify({ url: `${basePath}/${fullIndex.fileName}`, hash: fullIndex.hash })};
+// Header logo (inlined SVG) and icon URLs, from brand in site.config.yaml.
+export const brand = ${JSON.stringify(resolveBrand(root, siteConfig, basePath, (line) => console.warn(line)))};
+// Full URLs to this address render as internal links.
+export const siteLinks = ${JSON.stringify({ address: siteAddress, basePath })};
 `,
 );
 fs.mkdirSync(path.join(root, "public"), { recursive: true });
@@ -701,7 +746,7 @@ const sitemapEntries = [
 // Card URLs in published entries: the only pages the link-card Worker may read.
 fs.writeFileSync(
   path.join(publicRoot, "link-allowlist.json"),
-  `${JSON.stringify({ urls: [...new Set([...posts, ...columns, ...thoughts].flatMap((entry) => cardUrls(entry.content)))].sort() }, null, 2)}\n`,
+  `${JSON.stringify({ urls: [...new Set([...posts, ...columns, ...thoughts].flatMap((entry) => cardUrls(entry.content)).filter((url) => !sameSite(url)))].sort() }, null, 2)}\n`,
 );
 fs.writeFileSync(path.join(publicRoot, "sitemap.xml"), `<?xml version="1.0" encoding="UTF-8" ?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${sitemapEntries.map((entry) => `

package/scripts/image-sizes.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Intrinsic sizes of the images in post bodies, so every <img> can carry
+ * width and height and the page does not jump as lazy images load.
+ *
+ * - Local images are read at build time with image-size (see build-content).
+ * - Remote images are probed here: only the first bytes are downloaded, never
+ *   the whole file. Results go into `image-sizes.json` (commit it), so later
+ *   builds do not fetch them again. A failed probe is logged and retried next
+ *   time; the image simply renders without a size. The build never fails.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import matter from "gray-matter";
+import { imageSize } from "image-size";
+import { isPublicUrl } from "./link-meta-core.mjs";
+import { assertPublicDns, pool } from "./link-assets.mjs";
+import { mapOutsideCode } from "../ui/garden/markdown-links.mjs";
+
+export const CACHE_FILE = "image-sizes.json";
+const HEAD_BYTES = [64 * 1024, 512 * 1024];
+const TIMEOUT_MS = 8000;
+
+// A destination may hold balanced parentheses, as in `image (9).png` written as `image%20(9).png`.
+const MD_IMAGE = /!\[[^\]]*\]\(\s*(?:<([^>\n]+)>|((?:[^()\s]|\([^()\s]*\))+))(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/gu;
+const HTML_IMAGE = /<img\b[^>]*?\bsrc\s*=\s*["']([^"']+)["']/giu;
+
+/** Image sources written in a Markdown body, outside code, in order, without repeats. */
+export function imageSources(markdown) {
+  const found = [];
+  mapOutsideCode(markdown, (text) => {
+    for (const match of text.matchAll(MD_IMAGE)) found.push(match[1] ?? match[2]);
+    for (const match of text.matchAll(HTML_IMAGE)) found.push(match[1]);
+    return text;
+  });
+  return [...new Set(found)];
+}
+
+const svgLength = (value) => {
+  const match = /^\s*([\d.]+)\s*(px)?\s*$/iu.exec(value ?? "");
+  return match ? Number(match[1]) : 0;
+};
+
+/**
+ * An SVG's size from its opening tag, even when the tag is cut off: drawing
+ * tools can put a huge attribute (draw.io's `content`) inside it.
+ */
+export function svgSizeFromHead(text) {
+  const tag = /<svg\b[^>]*/iu.exec(text)?.[0];
+  if (!tag) return null;
+  const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, "iu").exec(tag)?.[1];
+  const width = svgLength(attr("width"));
+  const height = svgLength(attr("height"));
+  if (width > 0 && height > 0) return { width: Math.round(width), height: Math.round(height) };
+  const box = (attr("viewBox") ?? "").trim().split(/[\s,]+/u).map(Number);
+  if (box.length === 4 && box[2] > 0 && box[3] > 0) {
+    if (width > 0) return { width: Math.round(width), height: Math.round((width * box[3]) / box[2]) };
+    return { width: Math.round(box[2]), height: Math.round(box[3]) };
+  }
+  return null;
+}
+
+/** `{ width, height }` from the first bytes of an image, or null. */
+export function sizeFromBytes(bytes) {
+  const head = new TextDecoder().decode(bytes.subarray(0, 4096));
+  if (/^\s*(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg\b/iu.test(head)) return svgSizeFromHead(head);
+  try {
+    const result = imageSize(bytes);
+    // EXIF orientation 5–8 turns the picture a quarter: the browser swaps the sides.
+    const turned = result.orientation >= 5 && result.orientation <= 8;
+    const width = turned ? result.height : result.width;
+    const height = turned ? result.width : result.height;
+    return width > 0 && height > 0 ? { width, height } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function readImageCache(siteRoot) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(siteRoot, CACHE_FILE), "utf8"));
+    return { images: data?.images && typeof data.images === "object" ? data.images : {} };
+  } catch {
+    return { images: {} };
+  }
+}
+
+/** Read at most `limit` bytes of the response body, then stop the download. */
+async function readHead(response, limit) {
+  if (!response.body) return new Uint8Array(await response.arrayBuffer()).slice(0, limit);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (total < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.length;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(Math.min(total, limit));
+  let offset = 0;
+  for (const chunk of chunks) {
+    const part = chunk.subarray(0, Math.min(chunk.length, bytes.length - offset));
+    bytes.set(part, offset);
+    offset += part.length;
+    if (offset >= bytes.length) break;
+  }
+  return bytes;
+}
+
+/** Fetch the head of an image, following up to 3 redirects to public hosts only. */
+async function fetchHead(url, limit, 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, {
+      redirect: "manual",
+      headers: { range: `bytes=0-${limit - 1}`, accept: "image/*", "user-agent": "Mozilla/5.0 (compatible; GardenImageSize/1.0)" },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+      await response.body?.cancel().catch(() => {});
+      current = new URL(response.headers.get("location"), current).toString();
+      continue;
+    }
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return readHead(response, limit);
+  }
+  throw new Error("too many redirects");
+}
+
+export async function probeRemoteSize(url, { fetch: fetcher = globalThis.fetch, checkHost = assertPublicDns } = {}) {
+  let lastError = "unreadable";
+  for (const limit of HEAD_BYTES) {
+    try {
+      const size = sizeFromBytes(await fetchHead(url, limit, fetcher, checkHost));
+      if (size) return size;
+    } catch (error) {
+      lastError = error?.message ?? String(error);
+      break;
+    }
+  }
+  throw new Error(lastError);
+}
+
+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] : [];
+  });
+}
+
+/** Remote image URLs across every Markdown file under content/. */
+export function collectRemoteImages(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 imageSources(content)) if (/^https?:\/\//iu.test(src)) urls.add(src);
+  }
+  return [...urls].sort();
+}
+
+export async function refreshImageSizes({ siteRoot, fetch: fetcher, checkHost, log = () => {}, concurrency = 6 }) {
+  const cache = readImageCache(siteRoot);
+  const urls = collectRemoteImages(siteRoot);
+  const images = {};
+  const missing = [];
+  for (const url of urls) {
+    if (cache.images[url]?.width > 0 && cache.images[url]?.height > 0) images[url] = cache.images[url];
+    else missing.push(url);
+  }
+  let failed = 0;
+  await pool(missing, concurrency, async (url) => {
+    try {
+      images[url] = await probeRemoteSize(url, { fetch: fetcher, checkHost });
+    } catch (error) {
+      failed += 1;
+      log(`警告：读不到图片尺寸，这张图不带宽高：${url}（${error.message}）`);
+    }
+  });
+  const sorted = Object.fromEntries(Object.keys(images).sort().map((url) => [url, images[url]]));
+  const next = `${JSON.stringify({ version: 1, images: 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} 张远程图片，新读取 ${missing.length - failed} 张，失败 ${failed} 张。`);
+  return { images: sorted, probed: missing.length - failed, 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 refreshImageSizes({ siteRoot, log: (line) => process.stdout.write(`${line}\n`) }).catch((error) => {
+    process.stdout.write(`警告：图片尺寸没有更新（${error.message}），继续构建。\n`);
+  });
+}

package/scripts/link-assets.mjs

@@ -17,7 +17,9 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import matter from "gray-matter";
 import { fetchFavicon, fetchImage, fetchPageMeta, isPublicUrl, linkHost } from "./link-meta-core.mjs";
+import { parse as parseYaml } from "yaml";
 import { markdownLinks } from "../ui/garden/markdown-links.mjs";
+import { configuredSiteAddress, sameSiteMatcher } from "../ui/garden/same-site.mjs";
 
 export const CACHE_FILE = "link-assets.json";
 export const ASSET_DIR = path.join("public", "link-assets");
@@ -49,15 +51,26 @@ function markdownFiles(directory) {
   });
 }
 
+function readSiteConfig(siteRoot) {
+  try {
+    return parseYaml(fs.readFileSync(path.join(siteRoot, "site.config.yaml"), "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+}
+
 /** External links across every post: the sites (for favicons) and the URLs. */
-export function collectSiteLinks(siteRoot) {
+export function collectSiteLinks(siteRoot, env = process.env) {
+  const config = readSiteConfig(siteRoot);
+  // Links back to this site are internal: no favicon, no card.
+  const sameSite = sameSiteMatcher(configuredSiteAddress(config, env), env.NEXT_PUBLIC_BASE_PATH ?? "");
   const hosts = new Map();
   const cards = new Set();
   const urls = new Set();
   for (const file of markdownFiles(path.join(siteRoot, "content"))) {
     const { content } = matter(fs.readFileSync(file, "utf8"));
     for (const { url, card } of markdownLinks(content)) {
-      if (!isPublicUrl(url)) continue;
+      if (!isPublicUrl(url) || sameSite(url)) continue;
       urls.add(url);
       if (card) cards.add(url);
       const host = linkHost(url);
@@ -81,14 +94,14 @@ export async function assertPublicDns(hostname) {
   }
 }
 
-function guardedFetch(fetcher) {
+export function guardedFetch(fetcher) {
   return async (url, init) => {
     await assertPublicDns(new URL(url).hostname);
     return fetcher(url, init);
   };
 }
 
-async function pool(items, size, worker) {
+export async function pool(items, size, worker) {
   const queue = [...items];
   const runners = Array.from({ length: Math.min(size, queue.length) }, async () => {
     while (queue.length) await worker(queue.shift());

package/scripts/redirects.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Pages for old addresses. `redirects` in site.config.yaml maps an old path to
+ * where the page lives now:
+ *
+ *   redirects:
+ *     /2024/01/20/go/go-gpm/: /blog/go/go-gpm/
+ *
+ * A static export (GitHub Pages and the like) has no server to answer with a
+ * 301, so each old path gets a small page that sends the reader on: a meta
+ * refresh, a script that keeps the #anchor, and rel="canonical" for search
+ * engines. Runs after the build, into dist/client.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { configuredSiteAddress } from "../ui/garden/same-site.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;
+}
+
+/** 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) {
+  const clean = from.replace(/^\/+/u, "");
+  return /\.html?$/iu.test(clean) ? clean : path.posix.join(clean.replace(/\/+$/u, ""), "index.html");
+}
+
+export function redirectPage({ href, canonical }) {
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>页面已移动</title>
+<link rel="canonical" href="${escapeHtml(canonical)}">
+<meta http-equiv="refresh" content="0; url=${escapeHtml(href)}">
+<script>location.replace(${JSON.stringify(href).replace(/</gu, "\\u003c")} + location.hash)</script>
+</head>
+<body>
+<p>页面已移到 <a href="${escapeHtml(href)}">${escapeHtml(canonical)}</a>。</p>
+</body>
+</html>
+`;
+}
+
+/**
+ * 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.
+ */
+export function writeRedirects({ outDir, config = {}, env = {}, basePath = "", log = () => {} }) {
+  const base = String(basePath ?? "").replace(/\/+$/u, "");
+  let origin = "";
+  try {
+    const address = configuredSiteAddress(config, env);
+    origin = address ? new URL(address).origin : "";
+  } catch {
+    origin = "";
+  }
+  const written = [];
+  for (const { from, to } of readRedirects(config, log)) {
+    const file = path.join(outDir, redirectFile(from));
+    if (!path.resolve(file).startsWith(path.resolve(outDir) + path.sep)) continue;
+    if (fs.existsSync(file)) {
+      log(`redirects：${from} 已经有页面，没有覆盖。`);
+      continue;
+    }
+    const external = /^https?:\/\//iu.test(to);
+    if (!external) {
+      const target = to.split(/[?#]/u, 1)[0];
+      const built = [path.join(outDir, redirectFile(target)), path.join(outDir, target.replace(/^\/+/u, ""))]
+        .some((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+      if (!built) {
+        log(`redirects：${from} 指向的 ${to} 不存在，已跳过。`);
+        continue;
+      }
+    }
+    const href = external ? to : `${base}${to}`;
+    const canonical = external || !origin ? href : `${origin}${href}`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, redirectPage({ href, canonical }));
+    written.push({ from, to: href, file });
+  }
+  return written;
+}
+
+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();
+  const outDir = path.join(siteRoot, "dist", "client");
+  try {
+    const config = parseYaml(fs.readFileSync(path.join(siteRoot, "site.config.yaml"), "utf8")) ?? {};
+    if (config.redirects && 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`) });
+      process.stdout.write(`旧地址跳转页：${written.length} 个。\n`);
+    }
+  } catch (error) {
+    process.stdout.write(`警告：旧地址跳转页没有生成（${error.message}），继续构建。\n`);
+  }
+}

package/templates/site/site.config.yaml

@@ -2,6 +2,13 @@ name: Garden
 tagline: 写作 · 记录 · 保持好奇
 description: 文章、随想和专栏。
 locale: zh_CN
+# 站点的公开地址。文章里指向这个地址的完整网址会按站内链接显示。
+# url: https://blog.example.com
+# 站点图标，不写时使用 Garden 自带的图标。
+# brand:
+#   logo: brand/logo.svg
+#   favicon: /favicon.svg
+#   appleTouchIcon: /apple-touch-icon.png
 
 author:
   name: Your Name

package/ui/garden/enhance.mjs

@@ -131,6 +131,36 @@ export function figureBreakout({
   return { left: side, right: side };
 }
 
+/**
+ * The same decision made at build time, when the image's pixel size is known:
+ * a figure in a full-width article column (`column` wide, the image card
+ * `inset` narrower) with room to spare on both sides. Returns how far the
+ * figure steps out on each side (`side`, 0 when it stays in the column) and
+ * the inline width the image gets, so its box is the right size before the
+ * file loads. The browser repeats the calculation after hydration and keeps
+ * it as the fallback for images without a known size.
+ */
+export function figureLayout({ naturalWidth = 0, attrWidth = 0, column = 740, inset = 26, density = 2, maxWidth = 1040 }) {
+  if (!(naturalWidth > 0)) return { side: 0, width: attrWidth > 0 ? attrWidth : 0 };
+  // Before any widening the image shows at its own pixels (or its width attribute), capped at the card.
+  const base = attrWidth > 0 ? Math.min(attrWidth, naturalWidth) : naturalWidth;
+  const viewport = 100000;
+  const articleLeft = (viewport - column) / 2;
+  const { left } = figureBreakout({
+    viewport,
+    articleLeft,
+    articleRight: articleLeft + column,
+    figureClient: column,
+    imageClient: Math.min(base, column - inset),
+    naturalWidth,
+    attrWidth,
+    density,
+    maxWidth,
+  });
+  const widened = figureImageWidth({ naturalWidth, attrWidth, widened: left > 0, density });
+  return { side: left, width: widened || base };
+}
+
 /**
  * Slide the TOC right of a wide element measured against the TOC's original
  * position. Hide it when the shifted TOC would not fit on screen.

package/ui/garden/image-dims.mjs

@@ -0,0 +1,43 @@
+import { figureLayout } from "./enhance.mjs";
+
+const decode = (value) => {
+  try {
+    return decodeURI(value);
+  } catch {
+    return value;
+  }
+};
+
+/** The build-time size for an image src, whether or not the renderer percent-encoded it. */
+export function lookupImageSize(sizes, src) {
+  if (!src || !sizes) return null;
+  const size = sizes[src] ?? sizes[decode(src)] ?? sizes[encodeURI(decode(src))];
+  return size?.width > 0 && size?.height > 0 ? size : null;
+}
+
+/**
+ * Attributes that give an article image its box before the file loads:
+ * width and height (the browser takes the aspect ratio from them; CSS keeps
+ * height:auto so it stays responsive) and an inline width matching what the
+ * image would show once loaded. An author-written width wins and only gains
+ * the matching height. Without a known size nothing is added.
+ */
+export function imageDimensions({ width, height } = {}, size) {
+  if (!size) return {};
+  const authoredWidth = Number(width) > 0 ? Number(width) : 0;
+  const authoredHeight = Number(height) > 0 ? Number(height) : 0;
+  // Author-written sizes are never replaced; only the missing side is filled in from the ratio.
+  if (authoredWidth || authoredHeight) {
+    const w = authoredWidth || Math.round((authoredHeight * size.width) / size.height);
+    const h = authoredHeight || Math.round((authoredWidth * size.height) / size.width);
+    return { width: w, height: h, "data-nw": size.width, "data-aw": w };
+  }
+  const { width: shown } = figureLayout({ naturalWidth: size.width });
+  return {
+    width: size.width,
+    height: size.height,
+    "data-nw": size.width,
+    "data-bw": shown,
+    style: { width: `${shown}px` },
+  };
+}