@rimelight/seo 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rimelight Entertainment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/seo",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "description": "Rimelight Entertainment's SEO Package",
   "homepage": "https://rimelight.com/docs",
@@ -30,12 +30,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "check": "pnpm audit --audit-level=moderate && vp check --fix && astro check"
-  },
   "devDependencies": {
-    "@rimelight/config": "workspace:*",
-    "astro": "7.2.2",
+    "@rimelight/config": "0.0.3",
+    "astro": "7.2.7",
     "typescript": "6.0.3"
   },
   "peerDependencies": {
@@ -44,5 +41,7 @@
   "engines": {
     "node": ">=26.7.0"
   },
-  "packageManager": "pnpm@11.22.0"
-}
+  "scripts": {
+    "check": "vp check --fix && astro check"
+  }
+}

package/src/components/AgentDirective.astro

@@ -0,0 +1,25 @@
+---
+interface Props {
+  /** Absolute or site-relative URL for this page's markdown version. */
+  markdownUrl?: string | undefined
+  /** Absolute or site-relative URL for the top-level llms.txt index. */
+  llmsUrl?: string | undefined
+  class?: string | undefined
+}
+
+const {
+  markdownUrl,
+  llmsUrl = "/llms.txt",
+  class: className = "sr-only"
+} = Astro.props
+---
+
+<aside class={className} data-ai-agent-directive>
+  This page is available in Markdown format. Markdown is recommended for AI and agentic consumption.
+  {markdownUrl && (
+    <>
+      See <a href={markdownUrl}>{markdownUrl}</a> for this page, or{" "}
+    </>
+  )}
+  <a href={llmsUrl}>{llmsUrl}</a> for the full documentation and content index.
+</aside>

package/src/components/SEOHead.astro

@@ -7,6 +7,7 @@ import {
   buildRobotsMetaContent,
   buildWebSiteSchema
 } from "../meta.js"
+import { buildArticleSchema, buildBreadcrumbSchema } from "../schema.js"
 
 const {
   title,
@@ -23,6 +24,10 @@ const {
   charset = 'utf-8',
   viewport = 'width=device-width, initial-scale=1',
   rssFeed,
+  articleSchema,
+  breadcrumbs,
+  markdownUrl,
+  versionAlternates = [],
 } = Astro.props as HeadProps
 
 // Resolve defaults from config if available
@@ -85,6 +90,12 @@ const robotsContent = buildRobotsMetaContent({
   <link rel="alternate" hreflang={alt.hreflang} href={alt.href} />
 ))}
 
+<!-- Agent & Version Alternates -->
+{markdownUrl && <link rel="alternate" type="text/markdown" href={markdownUrl} title="Markdown Format" />}
+{versionAlternates.map((alt) => (
+  <link rel="alternate" data-version={alt.version} href={alt.href} />
+))}
+
 <!-- Open Graph / Facebook -->
 <meta property="og:type" content={ogType} />
 <meta property="og:locale" content={ogLocale} />
@@ -122,3 +133,16 @@ const robotsContent = buildRobotsMetaContent({
     buildWebSiteSchema(config, Astro.site?.toString())
   )} />
 )}
+
+{articleSchema && (
+  <script type="application/ld+json" is:inline set:html={JSON.stringify(
+    buildArticleSchema(articleSchema)
+  )} />
+)}
+
+{breadcrumbs && breadcrumbs.length > 0 && (
+  <script type="application/ld+json" is:inline set:html={JSON.stringify(
+    buildBreadcrumbSchema(breadcrumbs)
+  )} />
+)}
+

package/src/index.ts

@@ -9,7 +9,12 @@ export type {
   SiteConfig,
   OGImage,
   RSSFeed,
-  HeadProps
+  HeadProps,
+  LlmsPage,
+  LlmsTxtOptions,
+  LlmsFullTxtOptions,
+  ArticleSchemaOptions,
+  BreadcrumbItem
 } from "./types.js"
 
 export {
@@ -28,3 +33,9 @@ export {
   buildRobotsMetaContent,
   buildWebSiteSchema
 } from "./meta.js"
+
+export { buildLlmsTxt, buildLlmsFullTxt } from "./llms.js"
+export { buildArticleSchema, buildBreadcrumbSchema } from "./schema.js"
+
+export { default as SEOHead } from "./components/SEOHead.astro"
+export { default as AgentDirective } from "./components/AgentDirective.astro"

package/src/llms.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vite-plus/test"
+import { buildLlmsTxt, buildLlmsFullTxt } from "./llms.js"
+
+describe("seo-llms", () => {
+  it("builds standard /llms.txt with sections and pages", () => {
+    const output = buildLlmsTxt({
+      site: "https://rimelight.com",
+      title: "Rimelight Documentation",
+      description: "Docs for developers and AI agents.",
+      pages: [
+        {
+          title: "Introduction",
+          url: "https://rimelight.com/en/docs/overview/introduction",
+          markdownUrl: "https://rimelight.com/en/docs/overview/introduction.md",
+          description: "Getting started guide",
+          section: "Overview"
+        },
+        {
+          title: "Architecture",
+          url: "https://rimelight.com/en/docs/overview/architecture",
+          markdownUrl: "https://rimelight.com/en/docs/overview/architecture.md",
+          section: "Overview"
+        }
+      ]
+    })
+
+    expect(output).toContain("# Rimelight Documentation")
+    expect(output).toContain(
+      "Full corpus (all pages, one document): https://rimelight.com/llms-full.txt"
+    )
+    expect(output).toContain("### Overview")
+    expect(output).toContain(
+      "- [Introduction](https://rimelight.com/en/docs/overview/introduction.md) — Getting started guide"
+    )
+    expect(output).toContain(
+      "- [Architecture](https://rimelight.com/en/docs/overview/architecture.md)"
+    )
+  })
+
+  it("builds full corpus /llms-full.txt", () => {
+    const output = buildLlmsFullTxt({
+      site: "https://rimelight.com",
+      title: "Rimelight Docs",
+      pages: [
+        {
+          title: "Quickstart",
+          url: "https://rimelight.com/en/docs/quickstart",
+          description: "Step-by-step tutorial",
+          version: "v1",
+          markdown: "Run `vp dev` to start the development server."
+        }
+      ]
+    })
+
+    expect(output).toContain("# Rimelight Docs — Full Documentation Corpus")
+    expect(output).toContain("## Quickstart")
+    expect(output).toContain("URL: https://rimelight.com/en/docs/quickstart")
+    expect(output).toContain("Version: v1")
+    expect(output).toContain("Run `vp dev` to start the development server.")
+  })
+})

package/src/llms.ts

@@ -0,0 +1,124 @@
+export interface LlmsPage {
+  title: string
+  url: string
+  description?: string
+  markdownUrl?: string
+  section?: string
+}
+
+export interface LlmsTxtOptions {
+  site: string
+  title: string
+  description?: string
+  fullCorpusUrl?: string
+  pages: LlmsPage[]
+  sections?: Array<{ label: string; url: string }>
+}
+
+export interface LlmsFullTxtOptions {
+  site: string
+  title: string
+  description?: string
+  pages: Array<{
+    title: string
+    url: string
+    description?: string
+    markdown: string
+    version?: string
+  }>
+}
+
+/**
+ * Builds standard /llms.txt document format for AI discovery.
+ */
+export function buildLlmsTxt(options: LlmsTxtOptions): string {
+  const {
+    site,
+    title,
+    description,
+    fullCorpusUrl = `${site.replace(/\/$/, "")}/llms-full.txt`,
+    pages,
+    sections = []
+  } = options
+
+  const lines = [
+    `# ${title}`,
+    "",
+    description || "Documentation index for AI agents.",
+    "",
+    `Full corpus (all pages, one document): ${fullCorpusUrl}`,
+    ""
+  ]
+
+  if (sections.length > 0) {
+    lines.push("## Sections", "")
+    for (const sec of sections) {
+      lines.push(`- [${sec.label}](${sec.url})`)
+    }
+    lines.push("")
+  }
+
+  lines.push("## Pages", "")
+
+  // Group pages by section if present, or flat
+  const grouped = new Map<string, LlmsPage[]>()
+  for (const page of pages) {
+    const sec = page.section || "General"
+    if (!grouped.has(sec)) grouped.set(sec, [])
+    grouped.get(sec)!.push(page)
+  }
+
+  if (grouped.size === 1 && grouped.has("General")) {
+    for (const page of pages) {
+      const pageUrl = page.markdownUrl || page.url
+      const desc = page.description ? ` — ${page.description}` : ""
+      lines.push(`- [${page.title}](${pageUrl})${desc}`)
+    }
+  } else {
+    for (const [secName, secPages] of grouped.entries()) {
+      lines.push(`### ${secName}`, "")
+      for (const page of secPages) {
+        const pageUrl = page.markdownUrl || page.url
+        const desc = page.description ? ` — ${page.description}` : ""
+        lines.push(`- [${page.title}](${pageUrl})${desc}`)
+      }
+      lines.push("")
+    }
+  }
+
+  lines.push("")
+  return lines.join("\n")
+}
+
+/**
+ * Builds concatenated /llms-full.txt single corpus document for AI agents.
+ */
+export function buildLlmsFullTxt(options: LlmsFullTxtOptions): string {
+  const { title, description, pages } = options
+  const parts = [
+    `# ${title} — Full Documentation Corpus`,
+    "",
+    description || "Complete documentation corpus for AI agents.",
+    "",
+    "---",
+    ""
+  ]
+
+  for (const page of pages) {
+    const metaHeader = [
+      `## ${page.title}`,
+      "",
+      `URL: ${page.url}`,
+      ...(page.description ? [`Description: ${page.description}`] : []),
+      ...(page.version ? [`Version: ${page.version}`] : []),
+      "",
+      page.markdown.trim(),
+      "",
+      "---",
+      ""
+    ]
+    parts.push(...metaHeader)
+  }
+
+  return parts.join("\n")
+}

package/src/schema.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vite-plus/test"
+import { buildArticleSchema, buildBreadcrumbSchema } from "./schema.js"
+
+describe("seo-schema", () => {
+  it("builds TechArticle JSON-LD schema", () => {
+    const schema = buildArticleSchema({
+      type: "TechArticle",
+      title: "Building on Cloudflare Workers",
+      description: "A complete guide to edge rendering",
+      url: "https://rimelight.com/blog/cloudflare-workers",
+      datePublished: new Date("2026-08-01T12:00:00Z"),
+      authorName: "Idan",
+      image: "https://rimelight.com/og/article.png"
+    })
+
+    expect(schema["@context"]).toBe("https://schema.org")
+    expect(schema["@type"]).toBe("TechArticle")
+    expect(schema.headline).toBe("Building on Cloudflare Workers")
+    expect(schema.author).toEqual({ "@type": "Person", "name": "Idan" })
+    expect(schema.datePublished).toBe("2026-08-01T12:00:00.000Z")
+  })
+
+  it("builds BreadcrumbList JSON-LD schema", () => {
+    const schema = buildBreadcrumbSchema([
+      { name: "Home", url: "https://rimelight.com" },
+      { name: "Docs", url: "https://rimelight.com/en/docs" },
+      { name: "Installation", url: "https://rimelight.com/en/docs/installation" }
+    ])
+
+    expect(schema["@type"]).toBe("BreadcrumbList")
+    expect(schema.itemListElement).toHaveLength(3)
+    expect(schema.itemListElement[0]).toEqual({
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://rimelight.com"
+    })
+    expect(schema.itemListElement[2]).toEqual({
+      "@type": "ListItem",
+      "position": 3,
+      "name": "Installation",
+      "item": "https://rimelight.com/en/docs/installation"
+    })
+  })
+})

package/src/schema.ts

@@ -0,0 +1,95 @@
+export interface ArticleSchemaOptions {
+  type?: "TechArticle" | "Article" | "BlogPosting"
+  title: string
+  description?: string
+  url: string
+  datePublished?: string | Date
+  dateModified?: string | Date
+  authorName?: string
+  authorUrl?: string
+  image?: string
+  publisherName?: string
+  publisherLogo?: string
+}
+
+export interface BreadcrumbItem {
+  name: string
+  url: string
+}
+
+/**
+ * Builds Schema.org Article / TechArticle / BlogPosting JSON-LD.
+ */
+export function buildArticleSchema(options: ArticleSchemaOptions): Record<string, any> {
+  const {
+    type = "TechArticle",
+    title,
+    description,
+    url,
+    datePublished,
+    dateModified,
+    authorName,
+    authorUrl,
+    image,
+    publisherName = "Rimelight Entertainment",
+    publisherLogo
+  } = options
+
+  const schema: Record<string, any> = {
+    "@context": "https://schema.org",
+    "@type": type,
+    "headline": title,
+    "mainEntityOfPage": {
+      "@type": "WebPage",
+      "@id": url
+    }
+  }
+
+  if (description) schema.description = description
+  if (image) schema.image = image
+
+  if (datePublished) {
+    schema.datePublished =
+      datePublished instanceof Date ? datePublished.toISOString() : datePublished
+  }
+
+  if (dateModified) {
+    schema.dateModified = dateModified instanceof Date ? dateModified.toISOString() : dateModified
+  } else if (datePublished) {
+    schema.dateModified = schema.datePublished
+  }
+
+  if (authorName) {
+    schema.author = {
+      "@type": "Person",
+      "name": authorName,
+      ...(authorUrl ? { url: authorUrl } : {})
+    }
+  }
+
+  if (publisherName) {
+    schema.publisher = {
+      "@type": "Organization",
+      "name": publisherName,
+      ...(publisherLogo ? { logo: { "@type": "ImageObject", "url": publisherLogo } } : {})
+    }
+  }
+
+  return schema
+}
+
+/**
+ * Builds Schema.org BreadcrumbList JSON-LD.
+ */
+export function buildBreadcrumbSchema(items: BreadcrumbItem[]): Record<string, any> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": items.map((item, index) => ({
+      "@type": "ListItem",
+      "position": index + 1,
+      "name": item.name,
+      "item": item.url
+    }))
+  }
+}

package/src/types.ts

@@ -216,4 +216,23 @@ export interface HeadProps {
    * RSS feed configuration
    */
   rssFeed?: RSSFeed
+  /**
+   * Article or BlogPosting JSON-LD configuration
+   */
+  articleSchema?: import("./schema.js").ArticleSchemaOptions
+  /**
+   * Breadcrumb list for JSON-LD structured data
+   */
+  breadcrumbs?: import("./schema.js").BreadcrumbItem[]
+  /**
+   * URL for this page's raw Markdown alternate twin
+   */
+  markdownUrl?: string
+  /**
+   * Version alternates for multi-version documentation
+   */
+  versionAlternates?: Array<{ version: string; href: string }>
 }
+
+export type { LlmsPage, LlmsTxtOptions, LlmsFullTxtOptions } from "./llms.js"
+export type { ArticleSchemaOptions, BreadcrumbItem } from "./schema.js"