@rimelight/seo 0.0.4 → 0.0.6

package/src/components/SEOHead.astro

@@ -1,11 +1,12 @@
 ---
-import type { HeadProps } from "../types.js"
+import type { HeadProps, OpenGraphMeta, TwitterMeta } from "../types.js"
 import {
   buildCanonicalUrl,
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "../meta.js"
 import { buildArticleSchema, buildBreadcrumbSchema } from "../schema.js"
 
@@ -29,6 +30,10 @@ const {
   breadcrumbs,
   markdownUrl,
   versionAlternates = [],
+  absolute = false,
+  twitterCard,
+  openGraph,
+  twitter,
 } = Astro.props as HeadProps
 
 // Resolve defaults from config if available
@@ -50,7 +55,8 @@ const displayTitle = buildPageTitle({
   ...(title !== undefined && { title }),
   siteName,
   titleTemplate,
-  ...(is404 !== undefined && { is404 })
+  ...(is404 !== undefined && { is404 }),
+  ...(absolute !== undefined && { absolute })
 })
 
 const finalDescription = description || siteDescription
@@ -72,6 +78,47 @@ const robotsContent = buildRobotsMetaContent({
   is404,
   ...(robots !== undefined && { override: robots })
 })
+
+// Deep-merged OpenGraph
+const defaultOpenGraph: OpenGraphMeta = {
+  type: ogType,
+  locale: ogLocale,
+  url: Astro.url.href,
+  title: title || siteName,
+  ...(safeDescription && { description: safeDescription }),
+  ...(absoluteOgImage && { images: [{ src: absoluteOgImage, alt: finalOgImage?.alt || siteName }] }),
+  siteName,
+  ...config?.openGraph,
+}
+const resolvedOpenGraph = deepMerge(defaultOpenGraph, openGraph || {})
+if (ogImage) {
+  resolvedOpenGraph.images = ogImage
+}
+const ogImgUrl = resolvedOpenGraph.images
+  ? (Array.isArray(resolvedOpenGraph.images) ? resolvedOpenGraph.images[0]?.src : (typeof resolvedOpenGraph.images === 'string' ? resolvedOpenGraph.images : resolvedOpenGraph.images.src))
+  : absoluteOgImage
+const ogImgAlt = resolvedOpenGraph.images
+  ? (Array.isArray(resolvedOpenGraph.images) ? resolvedOpenGraph.images[0]?.alt : (typeof resolvedOpenGraph.images === 'object' && 'alt' in resolvedOpenGraph.images ? resolvedOpenGraph.images.alt : finalOgImage?.alt || siteName))
+  : finalOgImage?.alt || siteName
+
+const absoluteResolvedOgImage = ogImgUrl ? new URL(ogImgUrl, Astro.site ?? Astro.url).toString() : undefined
+
+// Deep-merged Twitter
+const defaultTwitter: TwitterMeta = {
+  card: twitterCard || config?.twitter?.card || (absoluteResolvedOgImage ? 'summary_large_image' : 'summary'),
+  ...(twitterHandle && { site: twitterHandle, creator: twitterHandle }),
+  title: resolvedOpenGraph.title || title || siteName,
+  ...(safeDescription && { description: safeDescription }),
+  ...(absoluteResolvedOgImage && { images: absoluteResolvedOgImage }),
+  ...config?.twitter,
+}
+const resolvedTwitter = deepMerge(defaultTwitter, twitter || {})
+if (twitterCard) {
+  resolvedTwitter.card = twitterCard
+}
+if (!resolvedTwitter.card) {
+  resolvedTwitter.card = absoluteResolvedOgImage ? 'summary_large_image' : 'summary'
+}
 ---
 
 <!-- Basic Metadata -->
@@ -103,24 +150,24 @@ const robotsContent = buildRobotsMetaContent({
 ))}
 
 <!-- Open Graph / Facebook -->
-<meta property="og:type" content={ogType} />
-<meta property="og:locale" content={ogLocale} />
-<meta property="og:url" content={Astro.url.href} />
-<meta property="og:title" content={title || siteName} />
-{safeDescription && <meta property="og:description" content={safeDescription} />}
-{absoluteOgImage && <meta property="og:image" content={absoluteOgImage} />}
-{finalOgImage && <meta property="og:image:alt" content={finalOgImage.alt} />}
-<meta property="og:site_name" content={siteName} />
+<meta property="og:type" content={resolvedOpenGraph.type || 'website'} />
+<meta property="og:locale" content={resolvedOpenGraph.locale || 'en_US'} />
+<meta property="og:url" content={resolvedOpenGraph.url || Astro.url.href} />
+<meta property="og:title" content={resolvedOpenGraph.title || title || siteName} />
+{resolvedOpenGraph.description && <meta property="og:description" content={resolvedOpenGraph.description} />}
+{absoluteResolvedOgImage && <meta property="og:image" content={absoluteResolvedOgImage} />}
+{ogImgAlt && <meta property="og:image:alt" content={ogImgAlt} />}
+<meta property="og:site_name" content={resolvedOpenGraph.siteName || siteName} />
 
 <!-- Twitter -->
-<meta property="twitter:card" content="summary_large_image" />
+<meta property="twitter:card" content={resolvedTwitter.card} />
 <meta property="twitter:url" content={Astro.url.href} />
-<meta property="twitter:title" content={title || siteName} />
-{safeDescription && <meta property="twitter:description" content={safeDescription} />}
-{absoluteOgImage && <meta property="twitter:image" content={absoluteOgImage} />}
-{finalOgImage && <meta property="twitter:image:alt" content={finalOgImage.alt} />}
-{twitterHandle && <meta property="twitter:site" content={twitterHandle} />}
-{twitterHandle && <meta property="twitter:creator" content={twitterHandle} />}
+<meta property="twitter:title" content={resolvedTwitter.title || title || siteName} />
+{resolvedTwitter.description && <meta property="twitter:description" content={resolvedTwitter.description} />}
+{absoluteResolvedOgImage && <meta property="twitter:image" content={absoluteResolvedOgImage} />}
+{ogImgAlt && <meta property="twitter:image:alt" content={ogImgAlt} />}
+{resolvedTwitter.site && <meta property="twitter:site" content={resolvedTwitter.site} />}
+{resolvedTwitter.creator && <meta property="twitter:creator" content={resolvedTwitter.creator} />}
 
 <!-- Icons & Manifest -->
 <link rel="icon" type={faviconType} href={favicon} />

package/src/env.d.ts

@@ -1,3 +1,33 @@
-declare module "*.astro" {
-  export default {} as import("astro/runtime/server").AstroComponentFactory
-}
+declare module "*.astro" {
+  export default {} as import("astro/runtime/server").AstroComponentFactory
+}
+
+declare module "virtual:rimelight-seo-config" {
+  const config: import("./integration.js").RimelightSeoOptions
+  export default config
+}
+
+declare module "virtual:rimelight-seo/options" {
+  const config: import("./integration.js").RimelightSeoOptions
+  export default config
+}
+
+declare module "virtual:rimelight-seo/config" {
+  export const SEO_LOCALES: import("./types.js").LocaleConfig | undefined
+  export const PRIVATE_PATH_PREFIXES: string[] | undefined
+  export const seoEntries: (() => Promise<import("./types.js").SeoEntry[]>) | undefined
+  export const rssEntries: (() => Promise<import("./types.js").RssItem[]>) | undefined
+}
+
+declare module "virtual:rimelight-seo/site-config" {
+  export const siteConfig: import("./types.js").SiteConfig | Record<string, any>
+}
+
+declare module "virtual:rimelight-seo/db" {
+  export const db: any
+  export const pages: any
+}
+
+declare module "virtual:rimelight-seo/corpus" {
+  export const corpusPages: any[]
+}

package/src/index.ts

@@ -2,17 +2,26 @@ export type {
   ChangeFreq,
   LocaleConfig,
   RobotsOptions,
+  RobotsRouteOptions,
   SeoEntry,
   SitemapAlternate,
   SitemapUrl,
+  SitemapOptions,
   UserAgentRule,
   SiteConfig,
   OGImage,
   RSSFeed,
+  RssItem,
+  RssFeedOptions,
+  RssOptions,
   HeadProps,
+  OpenGraphMeta,
+  TwitterMeta,
   LlmsPage,
   LlmsTxtOptions,
   LlmsFullTxtOptions,
+  LlmsRouteOptions,
+  LlmsFullRouteOptions,
   ArticleSchemaOptions,
   BreadcrumbItem
 } from "./types.js"
@@ -26,13 +35,22 @@ export {
 
 export { buildRobotsTxt } from "./robots.js"
 
+export { buildRssXml, escapeXml } from "./rss.js"
+
 export {
   buildCanonicalUrl,
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "./meta.js"
 
 export { buildLlmsTxt, buildLlmsFullTxt } from "./llms.js"
 export { buildArticleSchema, buildBreadcrumbSchema } from "./schema.js"
+export type { OgFontConfig, OgLayoutOptions, OgRenderConfig } from "./og.js"
+
+import { rimelightSeo } from "./integration.js"
+export type { RimelightSeoOptions } from "./integration.js"
+export { rimelightSeo }
+export default rimelightSeo

package/src/integration.ts

@@ -0,0 +1,172 @@
+import type { AstroIntegration } from "astro"
+import path from "node:path"
+import fs from "node:fs"
+import { fileURLToPath } from "node:url"
+import type { RimelightSeoOptions } from "./types.js"
+
+export { type RimelightSeoOptions } from "./types.js"
+
+export function rimelightSeo(options: RimelightSeoOptions = {}): AstroIntegration {
+  return {
+    name: "@rimelight/seo",
+    hooks: {
+      "astro:config:setup": ({ injectRoute, updateConfig, config }) => {
+        const rootDir = fileURLToPath(config.root)
+
+        // Resolve site files
+        const findFile = (candidates: string[]): string | null => {
+          for (const c of candidates) {
+            const resolved = path.resolve(rootDir, c)
+            if (fs.existsSync(resolved)) return resolved
+          }
+          return null
+        }
+
+        const seoConfigPath = findFile([
+          "src/config/seo.config.ts",
+          "src/config/seo.config.js",
+          "src/config/seo.config.mjs"
+        ])
+
+        const siteConfigPath = findFile([
+          "src/config/site.config.ts",
+          "src/config/site.config.js",
+          "src/config/site.config.mjs"
+        ])
+
+        const dbPath = findFile(["src/db/index.ts", "src/db/index.js", "src/db/index.mjs"])
+
+        const corpusPath = findFile([
+          "src/config/llms.corpus.ts",
+          "src/config/llms.corpus.js",
+          "src/config/llms.corpus.mjs"
+        ])
+
+        // Inject routes
+        if (options.robots !== false) {
+          const pattern =
+            typeof options.robots === "object" && options.robots.path
+              ? options.robots.path
+              : "/robots.txt"
+          injectRoute({
+            pattern,
+            entrypoint: "@rimelight/seo/routes/robots.txt.ts"
+          })
+        }
+
+        if (options.sitemap !== false) {
+          const pattern =
+            typeof options.sitemap === "object" && options.sitemap.path
+              ? options.sitemap.path
+              : "/sitemap.xml"
+          injectRoute({
+            pattern,
+            entrypoint: "@rimelight/seo/routes/sitemap.xml.ts"
+          })
+        }
+
+        if (options.rss !== false) {
+          const pattern =
+            typeof options.rss === "object" && options.rss.path ? options.rss.path : "/rss.xml"
+          injectRoute({
+            pattern,
+            entrypoint: "@rimelight/seo/routes/rss.xml.ts"
+          })
+        }
+
+        if (options.llms !== false) {
+          const pattern =
+            typeof options.llms === "object" && options.llms.path ? options.llms.path : "/llms.txt"
+          injectRoute({
+            pattern,
+            entrypoint: "@rimelight/seo/routes/llms.txt.ts"
+          })
+        }
+
+        if (options.llmsFull !== false) {
+          const pattern =
+            typeof options.llmsFull === "object" && options.llmsFull.path
+              ? options.llmsFull.path
+              : "/llms-full.txt"
+          injectRoute({
+            pattern,
+            entrypoint: "@rimelight/seo/routes/llms-full.txt.ts"
+          })
+        }
+
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "vite-plugin-rimelight-seo",
+                resolveId(id) {
+                  if (
+                    id === "virtual:rimelight-seo-config" ||
+                    id === "virtual:rimelight-seo/options"
+                  ) {
+                    return "\0virtual:rimelight-seo/options"
+                  }
+                  if (id === "virtual:rimelight-seo/config") {
+                    return "\0virtual:rimelight-seo/config"
+                  }
+                  if (id === "virtual:rimelight-seo/site-config") {
+                    return "\0virtual:rimelight-seo/site-config"
+                  }
+                  if (id === "virtual:rimelight-seo/db") {
+                    return "\0virtual:rimelight-seo/db"
+                  }
+                  if (id === "virtual:rimelight-seo/corpus") {
+                    return "\0virtual:rimelight-seo/corpus"
+                  }
+                  return null
+                },
+                load(id) {
+                  if (id === "\0virtual:rimelight-seo/options") {
+                    return `export default ${JSON.stringify(options)};`
+                  }
+                  if (id === "\0virtual:rimelight-seo/config") {
+                    if (seoConfigPath) {
+                      return `import * as customConfig from ${JSON.stringify(seoConfigPath)};
+export const SEO_LOCALES = customConfig.SEO_LOCALES;
+export const PRIVATE_PATH_PREFIXES = customConfig.PRIVATE_PATH_PREFIXES || [];
+export const seoEntries = customConfig.seoEntries;
+export const rssEntries = customConfig.rssEntries;
+export default customConfig;`
+                    }
+                    return `export const SEO_LOCALES = undefined;
+export const PRIVATE_PATH_PREFIXES = [];
+export const seoEntries = async () => [];
+export const rssEntries = undefined;`
+                  }
+                  if (id === "\0virtual:rimelight-seo/site-config") {
+                    if (siteConfigPath) {
+                      return `export * from ${JSON.stringify(siteConfigPath)};`
+                    }
+                    return `export const siteConfig = { name: "Site", description: "", url: "" };`
+                  }
+                  if (id === "\0virtual:rimelight-seo/db") {
+                    if (dbPath) {
+                      return `export * from ${JSON.stringify(dbPath)};`
+                    }
+                    return `export const db = null;
+export const pages = null;`
+                  }
+                  if (id === "\0virtual:rimelight-seo/corpus") {
+                    if (corpusPath) {
+                      return `export * from ${JSON.stringify(corpusPath)};`
+                    }
+                    return `export const corpusPages = [];`
+                  }
+                  return null
+                }
+              }
+            ]
+          }
+        })
+      }
+    }
+  }
+}
+
+export default rimelightSeo
+

package/src/meta.test.ts

@@ -4,7 +4,8 @@ import {
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "./meta.js"
 
 const BASE = "https://example.com"
@@ -49,6 +50,29 @@ describe("buildPageTitle", () => {
       "404 - Not Found | My Site"
     )
   })
+
+  it("bypasses title template when absolute is true", () => {
+    expect(buildPageTitle({ ...opts, title: "Landing Page", absolute: true })).toBe("Landing Page")
+  })
+})
+
+describe("deepMerge", () => {
+  it("deep merges nested objects", () => {
+    const base = {
+      openGraph: { type: "website", siteName: "Base", locale: "en_US" },
+      twitter: { card: "summary", site: "@base" }
+    }
+    const override = {
+      openGraph: { siteName: "Override" },
+      twitter: { card: "summary_large_image" }
+    }
+    const result = deepMerge(base, override)
+    expect(result.openGraph.type).toBe("website")
+    expect(result.openGraph.siteName).toBe("Override")
+    expect(result.openGraph.locale).toBe("en_US")
+    expect(result.twitter.card).toBe("summary_large_image")
+    expect(result.twitter.site).toBe("@base")
+  })
 })
 
 describe("buildSafeDescription", () => {

package/src/meta.ts

@@ -12,19 +12,49 @@ export function buildCanonicalUrl(url: string | URL, base: string | URL): string
   return path.includes("?") ? path.replace(/\/?$/, "") : path.replace(/\/?$/, "/")
 }
 
+/**
+ * Deep merge two metadata or configuration objects.
+ */
+export function deepMerge<T extends Record<string, any>>(
+  base: T,
+  override?: Record<string, any>
+): T {
+  if (!override) return { ...base }
+  const result: Record<string, any> = { ...base }
+  for (const key of Object.keys(override)) {
+    const baseVal = base[key]
+    const overrideVal = override[key]
+    if (
+      baseVal &&
+      overrideVal &&
+      typeof baseVal === "object" &&
+      typeof overrideVal === "object" &&
+      !Array.isArray(baseVal) &&
+      !Array.isArray(overrideVal)
+    ) {
+      result[key] = deepMerge(baseVal, overrideVal)
+    } else if (overrideVal !== undefined) {
+      result[key] = overrideVal
+    }
+  }
+  return result as T
+}
+
 /**
  * Build a page title using a site's title template. Falls back to siteName for untitled pages; uses
- * a 404 label for error pages.
+ * a 404 label for error pages. Supports absolute title bypass.
  */
 export function buildPageTitle(opts: {
   title?: string
   siteName: string
   titleTemplate: string
   is404?: boolean
+  absolute?: boolean
 }): string {
-  const { title, siteName, titleTemplate, is404 } = opts
+  const { title, siteName, titleTemplate, is404, absolute } = opts
   if (is404) return `404 - Not Found | ${siteName}`
   if (!title) return siteName
+  if (absolute) return title
   return titleTemplate.replace("%s", title)
 }