radiant-docs 0.1.7 → 0.1.8

package/template/scripts/stamp-og-image-versions.mjs

@@ -0,0 +1,199 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const CWD = process.cwd();
+const DIST_DIR = path.join(CWD, "dist");
+const OG_IMAGES_DIR = path.join(DIST_DIR, "_og/images");
+const VERSION_LENGTH = 12;
+
+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 routePathToOgImageRelativePath(routePath) {
+  const normalizedRoutePath = normalizeRoutePath(routePath);
+  if (normalizedRoutePath === "/") return "index.png";
+  return `${normalizedRoutePath.slice(1, -1)}.png`;
+}
+
+function hashFile(filePath) {
+  const buffer = fs.readFileSync(filePath);
+  return crypto
+    .createHash("sha256")
+    .update(buffer)
+    .digest("hex")
+    .slice(0, VERSION_LENGTH);
+}
+
+function updateVersionInUrl(urlValue, version) {
+  if (typeof urlValue !== "string" || urlValue.trim().length === 0) {
+    return urlValue;
+  }
+
+  const decoded = urlValue.trim().replace(/&/g, "&");
+  const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(decoded);
+  const isProtocolRelative = decoded.startsWith("//");
+  const isAbsolutePath = decoded.startsWith("/");
+
+  let parsed;
+  try {
+    if (hasScheme) {
+      parsed = new URL(decoded);
+    } else if (isProtocolRelative) {
+      parsed = new URL(`https:${decoded}`);
+    } else {
+      parsed = new URL(decoded, "https://radiant.invalid/");
+    }
+  } catch {
+    return urlValue;
+  }
+
+  parsed.searchParams.set("v", version);
+
+  let encoded;
+  if (hasScheme) {
+    encoded = parsed.toString();
+  } else if (isProtocolRelative) {
+    encoded = `//${parsed.host}${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } else if (isAbsolutePath) {
+    encoded = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  } else {
+    encoded = `${parsed.pathname.replace(/^\//, "")}${parsed.search}${parsed.hash}`;
+  }
+
+  return encoded.replace(/&/g, "&");
+}
+
+function replaceMetaImageUrl(html, attrName, attrValue, version) {
+  const patterns = [
+    new RegExp(
+      `(<meta\\s+[^>]*${attrName}\\s*=\\s*["']${attrValue}["'][^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*>)`,
+      "gi",
+    ),
+    new RegExp(
+      `(<meta\\s+[^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*${attrName}\\s*=\\s*["']${attrValue}["'][^>]*>)`,
+      "gi",
+    ),
+  ];
+
+  let found = false;
+  let changed = false;
+  let nextHtml = html;
+
+  for (const pattern of patterns) {
+    nextHtml = nextHtml.replace(pattern, (_, prefix, currentUrl, suffix) => {
+      found = true;
+      const updatedUrl = updateVersionInUrl(currentUrl, version);
+      if (updatedUrl !== currentUrl) {
+        changed = true;
+      }
+      return `${prefix}${updatedUrl}${suffix}`;
+    });
+  }
+
+  return { html: nextHtml, found, changed };
+}
+
+function main() {
+  if (!fs.existsSync(DIST_DIR)) {
+    console.warn("Skipping OG version stamping: dist directory not found.");
+    return;
+  }
+
+  if (!fs.existsSync(OG_IMAGES_DIR)) {
+    console.warn("Skipping OG version stamping: OG images directory not found.");
+    return;
+  }
+
+  const htmlFiles = findHtmlFiles(DIST_DIR).sort();
+  if (htmlFiles.length === 0) {
+    console.warn("Skipping OG version stamping: no HTML files found in dist.");
+    return;
+  }
+
+  let updatedCount = 0;
+  let missingOgCount = 0;
+  let missingMetaCount = 0;
+
+  for (const htmlPath of htmlFiles) {
+    const routePath = routePathFromHtmlPath(htmlPath);
+    const ogImageRelativePath = routePathToOgImageRelativePath(routePath);
+    const ogImagePath = path.join(OG_IMAGES_DIR, ...ogImageRelativePath.split("/"));
+
+    if (!fs.existsSync(ogImagePath)) {
+      missingOgCount += 1;
+      continue;
+    }
+
+    const version = hashFile(ogImagePath);
+    const sourceHtml = fs.readFileSync(htmlPath, "utf8");
+
+    const ogResult = replaceMetaImageUrl(
+      sourceHtml,
+      "property",
+      "og:image",
+      version,
+    );
+    const twitterResult = replaceMetaImageUrl(
+      ogResult.html,
+      "name",
+      "twitter:image",
+      version,
+    );
+
+    if (!ogResult.found && !twitterResult.found) {
+      missingMetaCount += 1;
+      continue;
+    }
+
+    if (twitterResult.html !== sourceHtml) {
+      fs.writeFileSync(htmlPath, twitterResult.html, "utf8");
+      updatedCount += 1;
+    }
+  }
+
+  console.log(
+    `✅ OG version stamping complete. Updated ${updatedCount}/${htmlFiles.length} HTML files (missing OG image: ${missingOgCount}, missing meta tags: ${missingMetaCount}).`,
+  );
+}
+
+main();

package/template/scripts/stamp-pagefind-runtime-version.mjs

@@ -0,0 +1,140 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const CWD = process.cwd();
+const DIST_DIR = path.join(CWD, "dist");
+const PAGEFIND_DIR = path.join(DIST_DIR, "pagefind");
+const PAGEFIND_RUNTIME_PATH = path.join(PAGEFIND_DIR, "pagefind.js");
+const VERSION_LENGTH = 12;
+
+function findFilesRecursively(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()) {
+      findFilesRecursively(fullPath, files);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function normalizeRuntimeSourceForHash(source) {
+  return source
+    .replaceAll(
+      /pagefind-entry\.json\?(?:ts=\$\{Date\.now\(\)\}|v=[^"'`)]*)/g,
+      "pagefind-entry.json?__VERSION__",
+    )
+    .replaceAll(
+      /wasm\.\$\{language\}\.pagefind(?:\?v=[^"'`)]*)?/g,
+      "wasm.${language}.pagefind?__VERSION__",
+    )
+    .replaceAll(
+      /wasm\.unknown\.pagefind(?:\?v=[^"'`)]*)?/g,
+      "wasm.unknown.pagefind?__VERSION__",
+    );
+}
+
+function deriveContentVersion(runtimeSource) {
+  const hash = crypto.createHash("sha256");
+  const normalizedRuntimeSource = normalizeRuntimeSourceForHash(runtimeSource);
+
+  const pagefindFiles = findFilesRecursively(PAGEFIND_DIR).sort();
+  for (const filePath of pagefindFiles) {
+    const relativePath = path.relative(PAGEFIND_DIR, filePath).replace(/\\/g, "/");
+    hash.update(relativePath);
+    hash.update("\0");
+
+    if (filePath === PAGEFIND_RUNTIME_PATH) {
+      hash.update(normalizedRuntimeSource);
+    } else {
+      hash.update(fs.readFileSync(filePath));
+    }
+
+    hash.update("\0");
+  }
+
+  return hash.digest("hex").slice(0, VERSION_LENGTH);
+}
+
+function deriveVersion(runtimeSource) {
+  const commitSha = process.env.COMMIT_SHA?.trim().toLowerCase();
+  if (commitSha && /^[a-f0-9]{7,40}$/.test(commitSha)) {
+    return {
+      version: commitSha.slice(0, VERSION_LENGTH),
+      source: "commit-sha",
+    };
+  }
+
+  return {
+    version: deriveContentVersion(runtimeSource),
+    source: "content-hash",
+  };
+}
+
+function stampRuntimeScript(runtimeSource, encodedVersion) {
+  let replacements = 0;
+
+  let next = runtimeSource.replaceAll(
+    /pagefind-entry\.json\?(?:ts=\$\{Date\.now\(\)\}|v=[^"'`)]*)/g,
+    () => {
+      replacements += 1;
+      return `pagefind-entry.json?v=${encodedVersion}`;
+    },
+  );
+
+  next = next.replaceAll(
+    /wasm\.\$\{language\}\.pagefind(?:\?v=[^"'`)]*)?/g,
+    () => {
+      replacements += 1;
+      return `wasm.\${language}.pagefind?v=${encodedVersion}`;
+    },
+  );
+
+  next = next.replaceAll(
+    /wasm\.unknown\.pagefind(?:\?v=[^"'`)]*)?/g,
+    () => {
+      replacements += 1;
+      return `wasm.unknown.pagefind?v=${encodedVersion}`;
+    },
+  );
+
+  return { next, replacements };
+}
+
+function main() {
+  if (!fs.existsSync(PAGEFIND_RUNTIME_PATH)) {
+    console.warn(
+      "Skipping Pagefind runtime version stamping: dist/pagefind/pagefind.js not found.",
+    );
+    return;
+  }
+
+  const runtimeSource = fs.readFileSync(PAGEFIND_RUNTIME_PATH, "utf8");
+  const { version, source } = deriveVersion(runtimeSource);
+  const encodedVersion = encodeURIComponent(version);
+
+  const runtimeResult = stampRuntimeScript(runtimeSource, encodedVersion);
+  if (runtimeResult.next !== runtimeSource) {
+    fs.writeFileSync(PAGEFIND_RUNTIME_PATH, runtimeResult.next, "utf8");
+  } else if (runtimeResult.replacements === 0) {
+    console.warn(
+      "Pagefind runtime version stamping made no runtime changes. Runtime format may have changed.",
+    );
+  }
+
+  console.log(
+    `✅ Pagefind runtime version stamping complete (version=${version}, source=${source}, runtimeReplacements=${runtimeResult.replacements}).`,
+  );
+}
+
+main();

package/template/src/components/Footer.astro

@@ -0,0 +1,94 @@
+---
+import Icon from "./ui/Icon.astro";
+import { getConfig } from "../lib/validation";
+import LogoLink from "./LogoLink.astro";
+
+const config = await getConfig();
+const { footer } = config;
+
+if (!footer) return null;
+
+const socialIcons: Record<string, string> = {
+  x: "simple-icons:x",
+  website: "lucide:globe",
+  facebook: "simple-icons:facebook",
+  youtube: "simple-icons:youtube",
+  discord: "simple-icons:discord",
+  slack: "simple-icons:slack",
+  github: "simple-icons:github",
+  linkedin: "simple-icons:linkedin",
+  instagram: "simple-icons:instagram",
+  "hacker-news": "simple-icons:ycombinator",
+  medium: "simple-icons:medium",
+  telegram: "simple-icons:telegram",
+  bluesky: "simple-icons:bluesky",
+  threads: "simple-icons:threads",
+  reddit: "simple-icons:reddit",
+  podcast: "lucide:podcast",
+};
+
+---
+
+<footer class="border-t border-border-light pt-16" data-pagefind-ignore>
+  <div class="flex flex-col items-center gap-6">
+    <!-- Branding -->
+    <LogoLink
+      class="flex items-center gap-2.5 text-xl font-bold text-neutral-800 dark:text-neutral-100"
+    />
+    <!-- Socials -->
+    {
+      footer.socials && (
+        <div class="flex items-center justify-center gap-6">
+          {Object.entries(footer.socials).map(([platform, url]) => (
+            <a
+              href={url}
+              class="text-neutral-400 hover:text-neutral-600 dark:text-neutral-500 dark:hover:text-neutral-300 transition-all duration-300 transform hover:scale-105"
+              target="_blank"
+              rel="noopener noreferrer"
+              title={platform}
+            >
+              <Icon
+                name={socialIcons[platform] || "lucide:external-link"}
+                class="w-[18px] h-[18px]"
+              />
+            </a>
+          ))}
+        </div>
+      )
+    }
+    {
+      footer.links && (
+        <div class="flex flex-wrap justify-center gap-x-8 gap-y-3">
+          {footer.links.map((link) => (
+            <a
+              href={link.href}
+              class="text-sm text-neutral-500 hover:text-neutral-900 dark:text-neutral-400 dark:hover:text-neutral-100 transition-colors duration-300"
+            >
+              {link.text}
+            </a>
+          ))}
+        </div>
+      )
+    }
+  </div>
+
+  <!-- Links -->
+</footer>
+
+<div
+  class="mt-20 py-8 border-t border-neutral-100 dark:border-neutral-800/60 flex flex-col sm:flex-row justify-between items-center gap-4"
+>
+  <p class="text-[13px] text-neutral-400 dark:text-neutral-500">
+    &copy; {new Date().getFullYear()}
+    {config.title}. All rights reserved.
+  </p>
+  <a
+    href="https://radiant.io"
+    class="group flex items-center gap-1.5 text-[13px] text-neutral-400 dark:text-neutral-500 hover:text-neutral-600 dark:hover:text-neutral-300 transition-colors duration-200"
+  >
+    Built with <span
+      class="group-hover:text-neutral-900 dark:group-hover:text-neutral-100 font-medium duration-200"
+      >Radiant Docs</span
+    >
+  </a>
+</div>

package/template/src/components/Header.astro

@@ -1,40 +1,22 @@
 ---
-import { Icon } from "astro-icon/components";
+import Icon from "./ui/Icon.astro";
 import { getConfig } from "../lib/validation";
 import Search from "./Search.astro";
+import LogoLink from "./LogoLink.astro";
 
 const config = await getConfig();
-
-function getLogoUrl(logoPath: string | undefined): string | null {
-  if (!logoPath) return null;
-
-  // Normalize path: remove leading slash if present
-  const normalizedPath = logoPath.startsWith("/")
-    ? logoPath.slice(1)
-    : logoPath;
-
-  // Return public URL - Vite plugin ensures file exists in public
-  return `/${normalizedPath}`;
-}
-
-// Load light and dark logos
-const lightLogoUrl = getLogoUrl(config.logo?.light);
-const darkLogoUrl = getLogoUrl(config.logo?.dark);
-
-// Get the href for the logo link (defaults to "/")
-const logoHref = config.logo?.href || "/";
 ---
 
 <header
   class:list={[
-    "fixed z-30 inset-x-1 top-0 h-16 mt-1 border-x border-t border-border rounded-t-xl overflow-hidden",
+    "fixed z-30 inset-x-1 top-0 h-16 mt-1 border-x border-t border-border rounded-t-xl overflow-hidden border-b border-b-border-light",
     config.navbar?.blur
-      ? "bg-background/80 backdrop-blur-[18px] backdrop-saturate-200"
+      ? "bg-background/80 backdrop-blur-[18px] backdrop-saturate-50 border-b-neutral-100/85 bg-clip-padding"
       : "bg-background",
   ]}
   data-pagefind-ignore
 >
-  <div class="flex h-full border-b border-b-border-light">
+  <div class="flex h-full">
     <div class="lg:w-[283px] h-full">
       <div class="flex gap-3 lg:block h-full lg:border-r border-border-light">
         <button
@@ -57,44 +39,7 @@ const logoHref = config.logo?.href || "/";
             </div>
           </div>
         </button>
-        <a
-          href={logoHref}
-          class="h-full flex items-center justify-center gap-2 lg:gap-3 text-xl font-bold text-neutral-800 dark:text-neutral-100"
-        >
-          {
-            lightLogoUrl || darkLogoUrl ? (
-              <>
-                {/* Light mode: show light logo if available, otherwise show title */}
-                {lightLogoUrl ? (
-                  <img
-                    src={lightLogoUrl}
-                    class="max-h-[40px] w-auto max-w-[200px] object-contain dark:hidden"
-                    alt="Logo"
-                  />
-                ) : (
-                  <span class="dark:hidden">{config.title}</span>
-                )}
-
-                {/* Dark mode: show dark logo if available, otherwise show title */}
-                {darkLogoUrl ? (
-                  <img
-                    src={darkLogoUrl}
-                    class="max-h-[40px] w-auto max-w-[200px] object-contain hidden dark:block"
-                    alt="Logo"
-                  />
-                ) : (
-                  <span class="hidden dark:block">{config.title}</span>
-                )}
-              </>
-            ) : (
-              config.title
-            )
-          }
-          <span
-            class="text-[10px] text-neutral-500 font-semibold bg-neutral-100 dark:bg-neutral-800 px-2 py-px mt-0.5 rounded-full border border-neutral-200 dark:border-neutral-700/70 shadow-xs"
-            >Docs</span
-          >
-        </a>
+        <LogoLink />
       </div>
     </div>
     <div class="flex-1 flex">
@@ -122,7 +67,7 @@ const logoHref = config.logo?.href || "/";
                       {l.icon && (
                         <Icon
                           class="ml-0.5"
-                          name={`lucide:${l.icon}`}
+                          name={l.icon}
                           width="16"
                           height="16"
                         />
@@ -135,14 +80,14 @@ const logoHref = config.logo?.href || "/";
               {config.navbar.secondary && (
                 <a
                   class:list={[
-                    "items-center gap-1.5 px-3 py-[5px] text-sm font-[450] bg-white text-neutral-600 hover:text-neutral-700 rounded-md border border-neutral-200 shadow-xs hover:shadow-sm transition-all whitespace-nowrap",
+                    "items-center gap-1.5 px-3 py-[5px] text-sm bg-white text-neutral-600 hover:text-neutral-700 rounded-md border border-neutral-200 shadow-xs hover:shadow-sm transition-all whitespace-nowrap",
                     config.navbar.primary ? "hidden lg:flex" : "flex",
                   ]}
                   href={config.navbar.secondary.href}
                 >
                   {config.navbar.secondary.icon && (
                     <Icon
-                      name={`lucide:${config.navbar.secondary.icon}`}
+                      name={config.navbar.secondary.icon}
                       width="16"
                       height="16"
                     />
@@ -153,13 +98,13 @@ const logoHref = config.logo?.href || "/";
               {config.navbar.primary && (
                 <a
                   class:list={[
-                    "flex items-center gap-1.5 px-5 py-[5px] text-sm font-medium rounded-md bg-neutral-900 text-white/95 hover:text-white duration-200 shadow-[inset_0_1px_0_rgb(255,255,255,0.3),0_0_0_1px_var(--color-neutral-800)] transition-all whitespace-nowrap",
+                    "flex items-center gap-1.5 px-5 py-[5px] text-sm rounded-md bg-neutral-900 text-white/95 hover:text-white duration-200 shadow-[inset_0_1px_0_rgb(255,255,255,0.3),0_0_0_1px_var(--color-neutral-800)] transition-all whitespace-nowrap",
                   ]}
                   href={config.navbar.primary.href}
                 >
                   {config.navbar.primary.icon && (
                     <Icon
-                      name={`lucide:${config.navbar.primary.icon}`}
+                      name={config.navbar.primary.icon}
                       width="16"
                       height="16"
                     />