radiant-docs 0.1.59 → 0.1.61

package/template/package.json

@@ -47,6 +47,7 @@
     "alpinejs": "^3.15.2",
     "astro": "^5.16.4",
     "astro-icon": "^1.1.5",
+    "fontkit": "^2.0.4",
     "fs-extra": "^11.3.3",
     "mdast-util-gfm": "^3.1.0",
     "micromark-extension-gfm": "^3.0.0",
@@ -56,13 +57,13 @@
     "preact": "^10.29.0",
     "prism-themes": "^1.9.0",
     "prismjs": "^1.30.0",
-    "radiant-docs-validator": "^0.1.19",
+    "radiant-docs-validator": "^0.1.20",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "simple-git": "^3.30.0",
     "tailwindcss": "^4.2.2",
-    "vaul": "^1.1.2",
+    "wawoff2": "^2.0.1",
     "yaml": "^2.8.2",
     "zod": "^3.25.76"
   },

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

@@ -1,6 +1,15 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { Resvg } from "@resvg/resvg-js";
+import { create as createFont } from "fontkit";
+import wawoff2 from "wawoff2";
+import {
+  DEFAULT_TEXT_FONT_PRESET,
+  FONT_PRESET_OPTIONS,
+} from "radiant-docs-validator";
+
+const require = createRequire(import.meta.url);
 
 const CWD = process.cwd();
 const DIST_DIR = path.join(CWD, "dist");
@@ -11,7 +20,93 @@ 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";
+const DEFAULT_OG_FONT_FAMILY = "DejaVu Sans, Arial, sans-serif";
+const FONT_PRESET_ID_SET = new Set(FONT_PRESET_OPTIONS);
+const OG_FONT_SUBSETS = ["latin", "latin-ext"];
+const baseFontCache = new Map();
+const weightedFontCache = new Map();
+
+const FONT_PRESETS = {
+  "google-sans": {
+    family: "Google Sans Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/google-sans",
+      fileId: "google-sans",
+    },
+  },
+  inter: {
+    family: "Inter Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/inter",
+      fileId: "inter",
+    },
+  },
+  "inter-tight": {
+    family: "Inter Tight Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/inter-tight",
+      fileId: "inter-tight",
+    },
+  },
+  geist: {
+    family: "Geist Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/geist",
+      fileId: "geist",
+    },
+  },
+  "source-sans-3": {
+    family: "Source Sans 3 Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/source-sans-3",
+      fileId: "source-sans-3",
+    },
+  },
+  "source-serif-4": {
+    family: "Source Serif 4 Variable, DejaVu Serif, Georgia, serif",
+    fontsource: {
+      packageName: "@fontsource-variable/source-serif-4",
+      fileId: "source-serif-4",
+    },
+  },
+  "public-sans": {
+    family: "Public Sans Variable, DejaVu Sans, Arial, sans-serif",
+    fontsource: {
+      packageName: "@fontsource-variable/public-sans",
+      fileId: "public-sans",
+    },
+  },
+  "geist-mono": {
+    family: "Geist Mono Variable, DejaVu Sans Mono, monospace",
+    fontsource: {
+      packageName: "@fontsource-variable/geist-mono",
+      fileId: "geist-mono",
+    },
+  },
+  "jetbrains-mono": {
+    family: "JetBrains Mono Variable, DejaVu Sans Mono, monospace",
+    fontsource: {
+      packageName: "@fontsource-variable/jetbrains-mono",
+      fileId: "jetbrains-mono",
+    },
+  },
+  "google-sans-code": {
+    family: "Google Sans Code Variable, DejaVu Sans Mono, monospace",
+    fontsource: {
+      packageName: "@fontsource-variable/google-sans-code",
+      fileId: "google-sans-code",
+    },
+  },
+  "system-sans": {
+    family: DEFAULT_OG_FONT_FAMILY,
+  },
+  "system-serif": {
+    family: "DejaVu Serif, Georgia, serif",
+  },
+  "system-mono": {
+    family: "DejaVu Sans Mono, monospace",
+  },
+};
 
 function trimToUndefined(value) {
   return typeof value === "string" && value.trim().length > 0
@@ -19,6 +114,78 @@ function trimToUndefined(value) {
     : undefined;
 }
 
+function normalizeFontPresetId(value) {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  return FONT_PRESET_ID_SET.has(normalized) ? normalized : undefined;
+}
+
+function getFontPreset(presetId) {
+  return FONT_PRESETS[presetId] ?? FONT_PRESETS[DEFAULT_TEXT_FONT_PRESET];
+}
+
+async function getBaseFontsourceFont(fontsource, subset) {
+  const cacheKey = `${fontsource.packageName}:${subset}`;
+  const cachedFont = baseFontCache.get(cacheKey);
+  if (cachedFont) return cachedFont;
+
+  const fontPath = require.resolve(
+    `${fontsource.packageName}/files/${fontsource.fileId}-${subset}-wght-normal.woff2`,
+  );
+  const woff2Buffer = fs.readFileSync(fontPath);
+  const ttfBuffer = Buffer.from(await wawoff2.decompress(woff2Buffer));
+  const font = createFont(ttfBuffer);
+  baseFontCache.set(cacheKey, font);
+  return font;
+}
+
+function getWeightedFont(font, fontsource, subset, fontWeight) {
+  const cacheKey = `${fontsource.packageName}:${subset}:${fontWeight}`;
+  const cachedFont = weightedFontCache.get(cacheKey);
+  if (cachedFont) return cachedFont;
+
+  const weightAxis = font.variationAxes?.wght;
+  const weightedFont = weightAxis
+    ? font.getVariation({
+        wght: Math.max(weightAxis.min, Math.min(weightAxis.max, fontWeight)),
+      })
+    : font;
+
+  weightedFontCache.set(cacheKey, weightedFont);
+  return weightedFont;
+}
+
+async function getFontsourceFonts(fontsource, fontWeight) {
+  if (!fontsource) return [];
+
+  const fonts = [];
+  for (const subset of OG_FONT_SUBSETS) {
+    const font = await getBaseFontsourceFont(fontsource, subset);
+    fonts.push(getWeightedFont(font, fontsource, subset, fontWeight));
+  }
+
+  return fonts;
+}
+
+async function getFontRenderer(presetId, fontWeight) {
+  const fontPreset = getFontPreset(presetId);
+  return {
+    family: fontPreset.family,
+    fonts: await getFontsourceFonts(fontPreset.fontsource, fontWeight),
+  };
+}
+
+async function resolveOgFontConfig(fonts) {
+  const textFontId =
+    normalizeFontPresetId(fonts?.text) ?? DEFAULT_TEXT_FONT_PRESET;
+  const headingFontId = normalizeFontPresetId(fonts?.heading) ?? textFontId;
+
+  return {
+    titleFont: await getFontRenderer(headingFontId, 700),
+    descriptionFont: await getFontRenderer(textFontId, 400),
+  };
+}
+
 function decodeHtmlEntities(value) {
   if (!value || typeof value !== "string") return "";
 
@@ -89,6 +256,131 @@ function escapeXml(value) {
     .replace(/'/g, "'");
 }
 
+function findGlyphFont(fonts, codePoint) {
+  for (const font of fonts) {
+    if (font.hasGlyphForCodePoint(codePoint)) {
+      return font;
+    }
+  }
+  return fonts[0];
+}
+
+function splitTextIntoFontRuns(line, fonts) {
+  const runs = [];
+  for (const character of Array.from(line)) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === undefined) continue;
+
+    const font = findGlyphFont(fonts, codePoint);
+    const previousRun = runs[runs.length - 1];
+    if (previousRun?.font === font) {
+      previousRun.text += character;
+    } else {
+      runs.push({ font, text: character });
+    }
+  }
+
+  return runs;
+}
+
+function renderPathTextLine({
+  line,
+  x,
+  top,
+  fontRenderer,
+  fontSize,
+  fill,
+  fillOpacity,
+  letterSpacingEm = 0,
+}) {
+  const fonts = fontRenderer.fonts ?? [];
+  const primaryFont = fonts[0];
+  if (!primaryFont) {
+    return "";
+  }
+
+  const primaryScale = fontSize / primaryFont.unitsPerEm;
+  const baselineY = top + primaryFont.ascent * primaryScale;
+  const letterSpacingPx = fontSize * letterSpacingEm;
+  const pathData = [];
+  let cursorX = x;
+
+  for (const run of splitTextIntoFontRuns(line, fonts)) {
+    const font = run.font;
+    const scale = fontSize / font.unitsPerEm;
+    const glyphRun = font.layout(run.text);
+
+    for (let index = 0; index < glyphRun.glyphs.length; index += 1) {
+      const glyph = glyphRun.glyphs[index];
+      const position = glyphRun.positions[index] ?? {};
+      const glyphPath = glyph.path;
+      const xOffset = (position.xOffset ?? 0) * scale;
+      const yOffset = (position.yOffset ?? 0) * scale;
+
+      if (glyphPath.commands.length > 0) {
+        pathData.push(
+          glyphPath
+            .transform(
+              scale,
+              0,
+              0,
+              -scale,
+              cursorX + xOffset,
+              baselineY - yOffset,
+            )
+            .toSVG(),
+        );
+      }
+
+      cursorX +=
+        ((position.xAdvance ?? glyph.advanceWidth ?? 0) * scale) +
+        letterSpacingPx;
+    }
+  }
+
+  if (pathData.length === 0) {
+    return "";
+  }
+
+  const opacityAttribute =
+    fillOpacity === undefined ? "" : ` fill-opacity="${fillOpacity}"`;
+
+  return `<path d="${pathData.join(" ")}" fill="${fill}"${opacityAttribute} />`;
+}
+
+function renderTextLine({
+  line,
+  x,
+  top,
+  fontRenderer,
+  fontSize,
+  fontWeight,
+  fill,
+  fillOpacity,
+  letterSpacingEm = 0,
+}) {
+  const pathText = renderPathTextLine({
+    line,
+    x,
+    top,
+    fontRenderer,
+    fontSize,
+    fill,
+    fillOpacity,
+    letterSpacingEm,
+  });
+  if (pathText) return pathText;
+
+  const opacityAttribute =
+    fillOpacity === undefined ? "" : ` fill-opacity="${fillOpacity}"`;
+  const letterSpacing = letterSpacingEm === 0 ? 0 : `${letterSpacingEm}em`;
+  return `<text x="${x}" y="${top}" fill="${fill}"${opacityAttribute} font-family="${escapeXml(
+    fontRenderer.family,
+  )}" font-size="${fontSize}" font-weight="${fontWeight}" letter-spacing="${letterSpacing}" dominant-baseline="hanging">${escapeXml(
+    line,
+  )}</text>`;
+}
+
 function wrapText(input, maxChars, maxLines) {
   const text = trimToUndefined(input);
   if (!text) return [];
@@ -188,6 +480,8 @@ function renderOgSvg({
   description,
   siteName,
   logoDataUri,
+  titleFont,
+  descriptionFont,
 }) {
   const resolvedTitle = trimToUndefined(title) ?? siteName;
   const titleLines = wrapText(resolvedTitle, 24, 2);
@@ -211,7 +505,16 @@ function renderOgSvg({
   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>`;
+      const element = renderTextLine({
+        line,
+        x: 56,
+        top: currentY,
+        fontRenderer: titleFont,
+        fontSize: 72,
+        fontWeight: 700,
+        fill: "#FFFFFF",
+        letterSpacingEm: -0.02,
+      });
       currentY += titleLineHeight;
       return element;
     })
@@ -220,7 +523,16 @@ function renderOgSvg({
   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>`;
+      const element = renderTextLine({
+        line,
+        x: 56,
+        top: currentY,
+        fontRenderer: descriptionFont,
+        fontSize: 32,
+        fontWeight: 400,
+        fill: "#FFFFFF",
+        fillOpacity: 0.82,
+      });
       currentY += descriptionLineHeight;
       return element;
     })
@@ -228,7 +540,16 @@ function renderOgSvg({
 
   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>`;
+    : renderTextLine({
+        line: siteName,
+        x: 56,
+        top: 74,
+        fontRenderer: titleFont,
+        fontSize: 64,
+        fontWeight: 700,
+        fill: "#FFFFFF",
+        letterSpacingEm: -0.02,
+      });
 
   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">
@@ -253,12 +574,15 @@ function writeImageForRoute({
   description,
   siteName,
   logoDataUri,
+  ogFontConfig,
 }) {
   const svg = renderOgSvg({
     title,
     description,
     siteName,
     logoDataUri,
+    titleFont: ogFontConfig.titleFont,
+    descriptionFont: ogFontConfig.descriptionFont,
   });
 
   const resvg = new Resvg(svg, {
@@ -266,6 +590,8 @@ function writeImageForRoute({
       loadSystemFonts: true,
       defaultFontFamily: "DejaVu Sans",
       sansSerifFamily: "DejaVu Sans",
+      serifFamily: "DejaVu Serif",
+      monospaceFamily: "DejaVu Sans Mono",
     },
   });
 
@@ -276,7 +602,7 @@ function writeImageForRoute({
   fs.writeFileSync(outputPath, pngData);
 }
 
-function main() {
+async function main() {
   if (!fs.existsSync(DIST_DIR)) {
     console.warn("Skipping OG image generation: dist directory not found.");
     return;
@@ -295,6 +621,7 @@ function main() {
   const siteName = trimToUndefined(decodeHtmlEntities(defaults.siteName)) ??
     "Documentation";
   const logoDataUri = resolveLogoDataUri(defaults.logoDark);
+  const ogFontConfig = await resolveOgFontConfig(defaults.fonts);
 
   const routes = Object.keys(pages).sort();
   if (routes.length === 0) {
@@ -322,6 +649,7 @@ function main() {
       description,
       siteName,
       logoDataUri,
+      ogFontConfig,
     });
 
     generatedCount += 1;
@@ -332,4 +660,8 @@ function main() {
   );
 }
 
-main();
+main().catch((error) => {
+  console.error("Failed to generate OG images.");
+  console.error(error);
+  process.exitCode = 1;
+});

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

@@ -1,11 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+import {
+  DEFAULT_TEXT_FONT_PRESET,
+  FONT_PRESET_OPTIONS,
+} from "radiant-docs-validator";
 
 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");
+const FONT_PRESET_ID_SET = new Set(FONT_PRESET_OPTIONS);
 
 function readDocsConfig() {
   if (!fs.existsSync(DOCS_CONFIG_PATH)) {
@@ -106,6 +111,29 @@ function getLogoImagePath(variant) {
   return typeof variant.image === "string" ? variant.image.trim() : "";
 }
 
+function normalizeFontPresetId(value) {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  return FONT_PRESET_ID_SET.has(normalized) ? normalized : undefined;
+}
+
+function resolveOgFonts(docsConfig) {
+  const theme =
+    docsConfig?.theme && typeof docsConfig.theme === "object"
+      ? docsConfig.theme
+      : {};
+  const fonts =
+    theme.fonts && typeof theme.fonts === "object" && !Array.isArray(theme.fonts)
+      ? theme.fonts
+      : {};
+  const text = normalizeFontPresetId(fonts.text) ?? DEFAULT_TEXT_FONT_PRESET;
+
+  return {
+    text,
+    heading: normalizeFontPresetId(fonts.heading) ?? text,
+  };
+}
+
 function extractTitle(html) {
   const ogTitle = decodeHtmlEntities(
     matchMetaContent(html, "property", "og:title"),
@@ -165,6 +193,7 @@ function main() {
         typeof docsConfig.primaryColor === "string"
           ? docsConfig.primaryColor.trim()
           : "",
+      fonts: resolveOgFonts(docsConfig),
     },
     pages,
   };

package/template/src/components/Footer.astro

@@ -38,7 +38,7 @@ const footerLinks = footer?.links
   ? await Promise.all(
       footer.links.map(async (link) => ({
         ...link,
-        href: await resolveConfiguredHref(link.href, config.hiddenPageRoutes),
+        href: await resolveConfiguredHref(link.href, config),
       })),
     )
   : [];

package/template/src/components/Header.astro

@@ -112,21 +112,15 @@ const navbarLinks = config.navbar?.links
   ? await Promise.all(
       config.navbar.links.map(async (link) => ({
         ...link,
-        href: await resolveConfiguredHref(link.href, config.hiddenPageRoutes),
+        href: await resolveConfiguredHref(link.href, config),
       })),
     )
   : [];
 const navbarSecondaryHref = config.navbar?.secondary
-  ? await resolveConfiguredHref(
-      config.navbar.secondary.href,
-      config.hiddenPageRoutes,
-    )
+  ? await resolveConfiguredHref(config.navbar.secondary.href, config)
   : "";
 const navbarPrimaryHref = config.navbar?.primary
-  ? await resolveConfiguredHref(
-      config.navbar.primary.href,
-      config.hiddenPageRoutes,
-    )
+  ? await resolveConfiguredHref(config.navbar.primary.href, config)
   : "";
 ---
 
@@ -137,7 +131,6 @@ const navbarPrimaryHref = config.navbar?.primary
       "sm:bg-background/85 sm:backdrop-blur-[18px] sm:backdrop-saturate-50 sm:border-b-neutral-100/85 sm:dark:border-neutral-800/85 sm:bg-clip-padding",
   ]}
   data-pagefind-ignore
-  data-vaul-scale-chrome
 >
   <div class="flex h-full">
     <div class="lg:w-[283px] h-full">