radiant-docs 0.1.7 → 0.1.9

package/template/package.json

@@ -6,10 +6,10 @@
     "dev": "astro dev",
     "start": "tsx runner.ts",
     "prebuild": "rm -rf public/pagefind",
-    "build": "astro build && pagefind --site dist",
+    "build": "astro build && node scripts/generate-og-metadata.mjs && node scripts/generate-og-images.mjs && node scripts/stamp-og-image-versions.mjs && node scripts/stamp-image-versions.mjs && pagefind --site dist && node scripts/stamp-pagefind-runtime-version.mjs && node scripts/rewrite-static-asset-host.mjs",
     "preview": "astro preview",
     "astro": "astro",
-    "search:index": "astro build && pagefind --site dist && cp -r dist/pagefind public/"
+    "search:index": "astro build && node scripts/generate-og-metadata.mjs && node scripts/generate-og-images.mjs && node scripts/stamp-og-image-versions.mjs && node scripts/stamp-image-versions.mjs && pagefind --site dist && node scripts/stamp-pagefind-runtime-version.mjs && node scripts/rewrite-static-asset-host.mjs && cp -r dist/pagefind public/"
   },
   "dependencies": {
     "@alpinejs/collapse": "^3.15.2",
@@ -18,10 +18,11 @@
     "@astrojs/alpinejs": "^0.4.9",
     "@astrojs/mdx": "^4.3.12",
     "@aws-sdk/client-s3": "^3.964.0",
-    "@expressive-code/plugin-collapsible-sections": "^0.41.4",
-    "@expressive-code/plugin-line-numbers": "^0.41.4",
+    "@fontsource/google-sans-flex": "^5.2.2",
     "@iconify-json/lucide": "^1.2.79",
+    "@iconify-json/simple-icons": "^1.2.69",
     "@readme/oas-to-snippet": "^29.3.0",
+    "@resvg/resvg-js": "^2.6.2",
     "@stoplight/spectral-core": "^1.20.0",
     "@stoplight/spectral-rulesets": "^1.22.0",
     "@tailwindcss/typography": "^0.5.19",
@@ -29,13 +30,14 @@
     "@xt0rted/expressive-code-file-icons": "^1.0.0",
     "alpinejs": "^3.15.2",
     "astro": "^5.16.4",
-    "astro-expressive-code": "^0.41.4",
     "astro-icon": "^1.1.5",
     "fs-extra": "^11.3.3",
     "mime-types": "^3.0.2",
     "oas": "^28.7.0",
     "openapi-sampler": "^1.6.2",
     "prismjs": "^1.30.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
     "simple-git": "^3.30.0",
     "tailwindcss": "^4.1.17",
     "yaml": "^2.8.2",

package/template/scripts/generate-og-images.mjs

@@ -0,0 +1,335 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Resvg } from "@resvg/resvg-js";
+
+const CWD = process.cwd();
+const DIST_DIR = path.join(CWD, "dist");
+const MANIFEST_PATH = path.join(DIST_DIR, "_og/meta.json");
+const OUTPUT_DIR = path.join(DIST_DIR, "_og/images");
+
+const OG_WIDTH = 1200;
+const OG_HEIGHT = 630;
+const OG_BACKGROUND = "#171717";
+const OG_PRIMARY_COLOR = "#737373";
+const OG_FONT_FAMILY = "DejaVu Sans, Arial, sans-serif";
+
+function trimToUndefined(value) {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+}
+
+function decodeHtmlEntities(value) {
+  if (!value || typeof value !== "string") return "";
+
+  const named = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+  };
+
+  return value
+    .replace(/&#(\d+);/g, (_, dec) => {
+      const code = Number.parseInt(dec, 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+    })
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => {
+      const code = Number.parseInt(hex, 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+    })
+    .replace(/&([a-zA-Z]+);/g, (entity, name) => {
+      const decoded = named[name.toLowerCase()];
+      return decoded ?? entity;
+    });
+}
+
+function normalizeRoutePath(routePath) {
+  if (!routePath || routePath === "/") return "/";
+  if (!routePath.startsWith("/")) routePath = `/${routePath}`;
+  return routePath.endsWith("/") ? routePath : `${routePath}/`;
+}
+
+function truncateText(value, maxLength) {
+  const text = trimToUndefined(value);
+  if (!text) return "";
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+function stripSiteSuffixFromTitle(title, siteName) {
+  const trimmedTitle = trimToUndefined(title);
+  const trimmedSiteName = trimToUndefined(siteName);
+  if (!trimmedTitle || !trimmedSiteName) return trimmedTitle ?? "";
+
+  const suffixes = [` | ${trimmedSiteName}`, ` - ${trimmedSiteName}`];
+  for (const suffix of suffixes) {
+    if (trimmedTitle.endsWith(suffix)) {
+      return trimmedTitle.slice(0, -suffix.length).trim();
+    }
+  }
+
+  return trimmedTitle;
+}
+
+function routeToImageRelativePath(routePath) {
+  const normalizedRoutePath = normalizeRoutePath(routePath);
+  if (normalizedRoutePath === "/") return "index.png";
+  return `${normalizedRoutePath.slice(1, -1)}.png`;
+}
+
+function escapeXml(value) {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function wrapText(input, maxChars, maxLines) {
+  const text = trimToUndefined(input);
+  if (!text) return [];
+
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = "";
+  let index = 0;
+
+  while (index < words.length) {
+    const word = words[index];
+    const candidate = current ? `${current} ${word}` : word;
+
+    if (candidate.length <= maxChars) {
+      current = candidate;
+      index += 1;
+      continue;
+    }
+
+    if (!current) {
+      current = word.slice(0, maxChars);
+      index += 1;
+    }
+
+    lines.push(current);
+    current = "";
+
+    if (lines.length === maxLines) {
+      break;
+    }
+  }
+
+  if (lines.length < maxLines && current) {
+    lines.push(current);
+  }
+
+  const consumedAllWords = index >= words.length;
+  if (!consumedAllWords && lines.length > 0) {
+    lines[lines.length - 1] = truncateText(lines[lines.length - 1], maxChars);
+  }
+
+  return lines.slice(0, maxLines);
+}
+
+function mimeTypeFromFilePath(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".svg") return "image/svg+xml";
+  if (extension === ".png") return "image/png";
+  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+  if (extension === ".webp") return "image/webp";
+  if (extension === ".gif") return "image/gif";
+  return undefined;
+}
+
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function resolveLocalLogoPath(logoPath) {
+  const stripped = logoPath.split("#")[0].split("?")[0];
+  const decoded = safeDecodeURIComponent(stripped);
+  const relativePath = decoded.startsWith("/") ? decoded.slice(1) : decoded;
+  const absolutePath = path.resolve(DIST_DIR, relativePath);
+  const distRoot = path.resolve(DIST_DIR) + path.sep;
+
+  if (!absolutePath.startsWith(distRoot) && absolutePath !== path.resolve(DIST_DIR)) {
+    return undefined;
+  }
+
+  return absolutePath;
+}
+
+function resolveLogoDataUri(logoPath) {
+  const resolvedLogoPath = trimToUndefined(logoPath);
+  if (!resolvedLogoPath) return undefined;
+  if (/^https?:\/\//i.test(resolvedLogoPath)) return undefined;
+
+  const localLogoPath = resolveLocalLogoPath(resolvedLogoPath);
+  if (!localLogoPath || !fs.existsSync(localLogoPath)) return undefined;
+
+  const stats = fs.statSync(localLogoPath);
+  if (!stats.isFile()) return undefined;
+
+  const mimeType = mimeTypeFromFilePath(localLogoPath);
+  if (!mimeType) return undefined;
+
+  const buffer = fs.readFileSync(localLogoPath);
+  return `data:${mimeType};base64,${buffer.toString("base64")}`;
+}
+
+function renderOgSvg({
+  title,
+  description,
+  siteName,
+  logoDataUri,
+}) {
+  const resolvedTitle = trimToUndefined(title) ?? siteName;
+  const titleLines = wrapText(resolvedTitle, 24, 2);
+  if (titleLines.length === 0) {
+    titleLines.push(siteName);
+  }
+
+  const resolvedDescription = trimToUndefined(description) ?? "";
+  const descriptionLines = wrapText(resolvedDescription, 58, 2);
+
+  const titleLineHeight = 76;
+  const descriptionLineHeight = 38;
+  const spaceBetweenTitleAndDescription = 30;
+  const bottomPadding = 56;
+  const titleBlockHeight =
+    titleLines.length * titleLineHeight +
+    spaceBetweenTitleAndDescription +
+    descriptionLines.length * descriptionLineHeight;
+  const titleBlockTop = OG_HEIGHT - bottomPadding - titleBlockHeight;
+
+  let currentY = titleBlockTop;
+  const titleSvg = titleLines
+    .map((line) => {
+      const element = `<text x="56" y="${currentY}" fill="#FFFFFF" font-family="${OG_FONT_FAMILY}" font-size="72" font-weight="700" letter-spacing="-0.02em" dominant-baseline="hanging">${escapeXml(line)}</text>`;
+      currentY += titleLineHeight;
+      return element;
+    })
+    .join("");
+
+  currentY += spaceBetweenTitleAndDescription;
+  const descriptionSvg = descriptionLines
+    .map((line) => {
+      const element = `<text x="56" y="${currentY}" fill="#FFFFFF" fill-opacity="0.82" font-family="${OG_FONT_FAMILY}" font-size="32" font-weight="400" letter-spacing="0" dominant-baseline="hanging">${escapeXml(line)}</text>`;
+      currentY += descriptionLineHeight;
+      return element;
+    })
+    .join("");
+
+  const logoSvg = logoDataUri
+    ? `<image href="${escapeXml(logoDataUri)}" x="56" y="56" width="420" height="132" preserveAspectRatio="xMinYMid meet" />`
+    : `<text x="56" y="74" fill="#FFFFFF" font-family="${OG_FONT_FAMILY}" font-size="64" font-weight="700" letter-spacing="-0.02em" dominant-baseline="hanging">${escapeXml(siteName)}</text>`;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg width="${OG_WIDTH}" height="${OG_HEIGHT}" viewBox="0 0 ${OG_WIDTH} ${OG_HEIGHT}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <radialGradient id="ogGlow" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(1540 -360) rotate(90) scale(1600)">
+      <stop offset="0" stop-color="${OG_PRIMARY_COLOR}" stop-opacity="0.56" />
+      <stop offset="0.74" stop-color="${OG_PRIMARY_COLOR}" stop-opacity="0" />
+      <stop offset="1" stop-color="${OG_PRIMARY_COLOR}" stop-opacity="0" />
+    </radialGradient>
+  </defs>
+  <rect width="${OG_WIDTH}" height="${OG_HEIGHT}" fill="${OG_BACKGROUND}" />
+  <rect width="${OG_WIDTH}" height="${OG_HEIGHT}" fill="url(#ogGlow)" />
+  ${logoSvg}
+  ${titleSvg}
+  ${descriptionSvg}
+</svg>`;
+}
+
+function writeImageForRoute({
+  routePath,
+  title,
+  description,
+  siteName,
+  logoDataUri,
+}) {
+  const svg = renderOgSvg({
+    title,
+    description,
+    siteName,
+    logoDataUri,
+  });
+
+  const resvg = new Resvg(svg, {
+    font: {
+      loadSystemFonts: true,
+      defaultFontFamily: "DejaVu Sans",
+      sansSerifFamily: "DejaVu Sans",
+    },
+  });
+
+  const pngData = resvg.render().asPng();
+  const outputRelativePath = routeToImageRelativePath(routePath);
+  const outputPath = path.join(OUTPUT_DIR, ...outputRelativePath.split("/"));
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, pngData);
+}
+
+function main() {
+  if (!fs.existsSync(DIST_DIR)) {
+    console.warn("Skipping OG image generation: dist directory not found.");
+    return;
+  }
+
+  if (!fs.existsSync(MANIFEST_PATH)) {
+    console.warn("Skipping OG image generation: OG metadata manifest not found.");
+    return;
+  }
+
+  const rawManifest = fs.readFileSync(MANIFEST_PATH, "utf8");
+  const manifest = JSON.parse(rawManifest);
+
+  const defaults = manifest?.defaults ?? {};
+  const pages = manifest?.pages ?? {};
+  const siteName = trimToUndefined(decodeHtmlEntities(defaults.siteName)) ??
+    "Documentation";
+  const logoDataUri = resolveLogoDataUri(defaults.logoDark);
+
+  const routes = Object.keys(pages).sort();
+  if (routes.length === 0) {
+    console.warn("Skipping OG image generation: no pages found in metadata.");
+    return;
+  }
+
+  let generatedCount = 0;
+  for (const routePath of routes) {
+    const page = pages[routePath] ?? {};
+    const decodedTitle = decodeHtmlEntities(page.title);
+    const decodedDescription = decodeHtmlEntities(page.description);
+
+    const cleanedTitle = stripSiteSuffixFromTitle(decodedTitle, siteName);
+    const title = truncateText(cleanedTitle || siteName, 80);
+    const fallbackDescription = `Learn about ${title} in the ${siteName} documentation.`;
+    const description = truncateText(
+      decodedDescription || fallbackDescription,
+      150,
+    );
+
+    writeImageForRoute({
+      routePath,
+      title,
+      description,
+      siteName,
+      logoDataUri,
+    });
+
+    generatedCount += 1;
+  }
+
+  console.log(
+    `✅ Generated ${generatedCount} OG image${generatedCount === 1 ? "" : "s"} in ${OUTPUT_DIR}`,
+  );
+}
+
+main();

package/template/scripts/generate-og-metadata.mjs

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const CWD = process.cwd();
+const DIST_DIR = path.join(CWD, "dist");
+const DOCS_CONFIG_PATH = path.join(CWD, "src/content/docs/docs.json");
+const OUTPUT_DIR = path.join(DIST_DIR, "_og");
+const OUTPUT_PATH = path.join(OUTPUT_DIR, "meta.json");
+
+function readDocsConfig() {
+  if (!fs.existsSync(DOCS_CONFIG_PATH)) {
+    return {};
+  }
+
+  try {
+    const raw = fs.readFileSync(DOCS_CONFIG_PATH, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function findHtmlFiles(dir, files = []) {
+  if (!fs.existsSync(dir)) return files;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      findHtmlFiles(fullPath, files);
+      continue;
+    }
+
+    if (entry.isFile() && entry.name.endsWith(".html")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function normalizeRoutePath(routePath) {
+  if (!routePath || routePath === "/") return "/";
+  if (!routePath.startsWith("/")) routePath = `/${routePath}`;
+  return routePath.endsWith("/") ? routePath : `${routePath}/`;
+}
+
+function routePathFromHtmlPath(filePath) {
+  const relative = path.relative(DIST_DIR, filePath).replace(/\\/g, "/");
+
+  if (relative === "index.html") return "/";
+  if (relative.endsWith("/index.html")) {
+    const base = relative.slice(0, -"/index.html".length);
+    return normalizeRoutePath(base);
+  }
+
+  if (relative.endsWith(".html")) {
+    return normalizeRoutePath(relative.slice(0, -".html".length));
+  }
+
+  return "/";
+}
+
+function matchMetaContent(html, attrName, attrValue) {
+  const regex = new RegExp(
+    `<meta\\s+[^>]*${attrName}\\s*=\\s*["']${attrValue}["'][^>]*content\\s*=\\s*["']([^"']*)["'][^>]*>`,
+    "i",
+  );
+  const reverseRegex = new RegExp(
+    `<meta\\s+[^>]*content\\s*=\\s*["']([^"']*)["'][^>]*${attrName}\\s*=\\s*["']${attrValue}["'][^>]*>`,
+    "i",
+  );
+  return html.match(regex)?.[1] ?? html.match(reverseRegex)?.[1] ?? "";
+}
+
+function decodeHtmlEntities(value) {
+  if (!value || typeof value !== "string") return "";
+
+  const named = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+  };
+
+  return value
+    .replace(/&#(\d+);/g, (_, dec) => {
+      const code = Number.parseInt(dec, 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+    })
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => {
+      const code = Number.parseInt(hex, 16);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : _;
+    })
+    .replace(/&([a-zA-Z]+);/g, (entity, name) => {
+      const decoded = named[name.toLowerCase()];
+      return decoded ?? entity;
+    });
+}
+
+function extractTitle(html) {
+  const ogTitle = decodeHtmlEntities(
+    matchMetaContent(html, "property", "og:title"),
+  ).trim();
+  if (ogTitle) return ogTitle;
+  return decodeHtmlEntities(
+    html.match(/<title>([^<]*)<\/title>/i)?.[1] ?? "",
+  ).trim();
+}
+
+function extractDescription(html) {
+  const description = decodeHtmlEntities(
+    matchMetaContent(html, "name", "description"),
+  ).trim();
+  if (description) return description;
+  return decodeHtmlEntities(
+    matchMetaContent(html, "property", "og:description"),
+  ).trim();
+}
+
+function main() {
+  if (!fs.existsSync(DIST_DIR)) {
+    console.warn("Skipping OG metadata generation: dist directory not found.");
+    return;
+  }
+
+  const docsConfig = readDocsConfig();
+  const logo = typeof docsConfig.logo === "object" && docsConfig.logo
+    ? docsConfig.logo
+    : {};
+
+  const htmlFiles = findHtmlFiles(DIST_DIR);
+  htmlFiles.sort();
+  const pages = {};
+
+  for (const filePath of htmlFiles) {
+    const routePath = routePathFromHtmlPath(filePath);
+    const html = fs.readFileSync(filePath, "utf8");
+
+    pages[routePath] = {
+      title: extractTitle(html),
+      description: extractDescription(html),
+    };
+  }
+
+  const metadata = {
+    defaults: {
+      siteName:
+        typeof docsConfig.title === "string" ? docsConfig.title.trim() : "",
+      logoLight:
+        typeof logo.light === "string" ? logo.light.trim() : "",
+      logoDark:
+        typeof logo.dark === "string" ? logo.dark.trim() : "",
+      background:
+        typeof docsConfig.ogBackground === "string"
+          ? docsConfig.ogBackground.trim()
+          : "",
+      primaryColor:
+        typeof docsConfig.primaryColor === "string"
+          ? docsConfig.primaryColor.trim()
+          : "",
+    },
+    pages,
+  };
+
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(metadata, null, 2), "utf8");
+  console.log(`✅ Generated OG metadata at ${OUTPUT_PATH}`);
+}
+
+main();