doccupine 0.0.88 → 0.0.90

package/README.md

@@ -129,7 +129,7 @@ Place these JSON files in your project root (where you run `doccupine`). They ar
 | File              | Purpose                                                                                                   |
 | ----------------- | --------------------------------------------------------------------------------------------------------- |
 | `doccupine.json`  | CLI config (watchDir, outputDir, port). Auto-generated on first run.                                      |
-| `config.json`     | Site metadata: `name`, `description`, `icon`, `image` URL                                                 |
+| `config.json`     | Site metadata: `name`, `description`, `icon`, `image`, `url` (public site URL for sitemap/robots)         |
 | `theme.json`      | Theme overrides for [cherry-styled-components](https://github.com/cherry-design-system/styled-components) |
 | `navigation.json` | Manual navigation structure (overrides auto-generated)                                                    |
 | `links.json`      | Static header/footer links                                                                                |
@@ -139,7 +139,20 @@ Place these JSON files in your project root (where you run `doccupine`). They ar
 
 ## Public Directory
 
-Place static assets (images, favicons, `robots.txt`, etc.) in a `public/` directory at your project root. Doccupine copies it to the generated Next.js app on startup and watches for changes, so added, modified, or deleted files are synced automatically.
+Place static assets (images, favicons, etc.) in a `public/` directory at your project root. Doccupine copies it to the generated Next.js app on startup and watches for changes, so added, modified, or deleted files are synced automatically.
+
+## Sitemap and robots.txt
+
+Doccupine generates `robots.ts` automatically for every site. When you set a `url` in `config.json`, it also generates `sitemap.ts` covering every page (across all sections) and links the sitemap from `robots.txt`.
+
+```json
+{
+  "name": "My Docs",
+  "url": "https://docs.example.com"
+}
+```
+
+You can override the URL at deploy time by setting the `NEXT_PUBLIC_SITE_URL` environment variable. When no URL is configured (neither in `config.json` nor via env), the sitemap is skipped and `robots.txt` is emitted without a sitemap reference.
 
 ## AI Chat Setup
 

package/dist/index.js

@@ -10,11 +10,15 @@ import { appStructure, startingDocsStructure } from "./lib/structures.js";
 import { layoutTemplate } from "./lib/layout.js";
 import { ConfigManager } from "./lib/config-manager.js";
 import { findAvailablePort, generateSlug, getFullSlug, escapeTemplateContent, } from "./lib/utils.js";
-import { generateMetadataBlock, generateRuntimeOnlyMetadataBlock, } from "./lib/metadata.js";
+import { generateMetadataBlock, generateRuntimeOnlyMetadataBlock, generateJsonLdScript, } from "./lib/metadata.js";
 import { nextConfigTemplate } from "./templates/next.config.js";
+import { pnpmWorkspaceTemplate } from "./templates/pnpmWorkspace.js";
 import { proxyTemplate } from "./templates/proxy.js";
 import { robotsTemplate } from "./templates/app/robots.js";
 import { sitemapTemplate } from "./templates/app/sitemap.js";
+import { llmsIndexTemplate } from "./templates/llms/llmsIndex.js";
+import { llmsFullTemplate, } from "./templates/llms/llmsFull.js";
+import { llmsPageTemplate } from "./templates/llms/llmsPage.js";
 export { generateSlug, getFullSlug, escapeTemplateContent, } from "./lib/utils.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -43,6 +47,8 @@ class MDXToNextJSGenerator {
     sectionsConfig = null;
     /** Guards against recursive reprocessing when maybeUpdateSections() triggers processAllMDXFiles() */
     isReprocessing = false;
+    /** Tracks per-page .md files written under public/ so we can clean up stale ones on rename/delete */
+    generatedLlmsPagePaths = new Set();
     constructor(watchDir, outputDir) {
         this.watchDir = path.resolve(watchDir);
         this.outputDir = path.resolve(outputDir);
@@ -78,6 +84,7 @@ class MDXToNextJSGenerator {
         const structure = {
             ...appStructure,
             "next.config.ts": nextConfigTemplate(this.analyticsConfig),
+            "pnpm-workspace.yaml": pnpmWorkspaceTemplate,
             "proxy.ts": proxyTemplate(this.analyticsConfig),
             "analytics.json": `{}\n`,
             "config.json": `{}\n`,
@@ -94,6 +101,7 @@ class MDXToNextJSGenerator {
             await fs.writeFile(fullPath, String(await content), "utf8");
         }
         await this.updateSitemap();
+        await this.updateLlmsFiles();
     }
     async createStartingDocs() {
         const structure = startingDocsStructure;
@@ -334,6 +342,7 @@ class MDXToNextJSGenerator {
                 if (fileName === "config.json") {
                     await this.updateSitemap();
                     await this.updateRobots();
+                    await this.updateLlmsFiles();
                 }
             }
             catch (error) {
@@ -356,6 +365,7 @@ class MDXToNextJSGenerator {
                 if (fileName === "config.json") {
                     await this.updateSitemap();
                     await this.updateRobots();
+                    await this.updateLlmsFiles();
                 }
             }
             catch (error) {
@@ -681,6 +691,7 @@ class MDXToNextJSGenerator {
             await this.updatePagesIndex();
             await this.updateRootLayout();
             await this.updateSitemap();
+            await this.updateLlmsFiles();
             await this.generateSectionIndexPages();
             console.log(chalk.green(`✅ Generated page for: ${filePath}`));
             await this.maybeUpdateSections();
@@ -705,6 +716,7 @@ class MDXToNextJSGenerator {
             await this.updatePagesIndex();
             await this.updateRootLayout();
             await this.updateSitemap();
+            await this.updateLlmsFiles();
             console.log(chalk.green(`✅ Removed page for: ${filePath}`));
             await this.maybeUpdateSections();
         }
@@ -786,6 +798,20 @@ export default function SectionIndex() {
             description: fm.description,
             icon: fm.icon,
             image: fm.image,
+            canonicalPath: mdxFile.slug,
+        });
+        const jsonLd = generateJsonLdScript({
+            kind: "article",
+            canonicalPath: mdxFile.slug,
+            title: fm.title,
+            description: fm.description,
+            date: typeof fm.date === "string" ? fm.date : undefined,
+            updated: typeof fm.updated === "string"
+                ? fm.updated
+                : typeof fm.date === "string"
+                    ? fm.date
+                    : undefined,
+            image: fm.image,
         });
         const pageContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
@@ -795,8 +821,21 @@ const content = \`${escapeTemplateContent(mdxFile.content)}\`;
 
 ${metadataBlock}
 
+// Doc pages have no per-request data: theme resolves client-side via the
+// "dark" class on <html> (set before paint by the theme-init blocking
+// script). Static rendering lets every response come from the edge cache.
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Page() {
-  return <Docs content={content} />;
+  ${jsonLd.declarations}
+
+  return (
+    <>
+      ${jsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         const pagePath = path.join(this.outputDir, "app", mdxFile.slug, "page.tsx");
@@ -818,6 +857,10 @@ export default function Page() {
                     icon: frontmatter.icon,
                     image: frontmatter.image,
                     name: frontmatter.name,
+                    date: typeof frontmatter.date === "string" ? frontmatter.date : undefined,
+                    updated: typeof frontmatter.updated === "string"
+                        ? frontmatter.updated
+                        : undefined,
                 };
                 break;
             }
@@ -831,8 +874,18 @@ export default function Page() {
                 description: indexMDX.description || undefined,
                 icon: indexMDX.icon,
                 image: indexMDX.image,
+                canonicalPath: "",
             })
             : generateRuntimeOnlyMetadataBlock();
+        const homeJsonLd = generateJsonLdScript({
+            kind: "homepage",
+            canonicalPath: "",
+            title: indexMDX?.title,
+            description: indexMDX?.description || undefined,
+            date: indexMDX?.date,
+            updated: indexMDX?.updated ?? indexMDX?.date,
+            image: indexMDX?.image,
+        });
         const indexContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
 import { config } from "@/utils/config";
@@ -841,8 +894,18 @@ ${indexMDX ? `const content = \`${escapeTemplateContent(indexMDX.content)}\`;` :
 
 ${metadataBlock}
 
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Home() {
-  return <Docs content={content} />;
+  ${homeJsonLd.declarations}
+
+  return (
+    <>
+      ${homeJsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         await fs.writeFile(path.join(this.outputDir, "app", "page.tsx"), indexContent, "utf8");
@@ -856,6 +919,20 @@ export default function Home() {
             description: frontmatter.description || undefined,
             icon: frontmatter.icon,
             image: frontmatter.image,
+            canonicalPath: sectionSlug,
+        });
+        const sectionJsonLd = generateJsonLdScript({
+            kind: "article",
+            canonicalPath: sectionSlug,
+            title: frontmatter.title,
+            description: frontmatter.description,
+            date: typeof frontmatter.date === "string" ? frontmatter.date : undefined,
+            updated: typeof frontmatter.updated === "string"
+                ? frontmatter.updated
+                : typeof frontmatter.date === "string"
+                    ? frontmatter.date
+                    : undefined,
+            image: frontmatter.image,
         });
         const indexContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
@@ -865,8 +942,18 @@ const content = \`${escapeTemplateContent(mdxContent)}\`;
 
 ${metadataBlock}
 
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Page() {
-  return <Docs content={content} />;
+  ${sectionJsonLd.declarations}
+
+  return (
+    <>
+      ${sectionJsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         const pagePath = path.join(this.outputDir, "app", sectionSlug, "page.tsx");
@@ -943,6 +1030,120 @@ export default function Page() {
             ? `🤖 Regenerated robots.ts with sitemap link`
             : `🤖 Regenerated robots.ts (no sitemap link)`));
     }
+    async loadSiteMetadata() {
+        const configPath = path.join(this.rootDir, "config.json");
+        let url = null;
+        let name = "Documentation";
+        let description = "";
+        try {
+            if (await fs.pathExists(configPath)) {
+                const content = await fs.readFile(configPath, "utf8");
+                const parsed = JSON.parse(content);
+                if (typeof parsed.url === "string" && parsed.url.trim() !== "") {
+                    url = parsed.url.trim().replace(/\/$/, "");
+                }
+                if (typeof parsed.name === "string" && parsed.name.trim() !== "") {
+                    name = parsed.name.trim();
+                }
+                else if (typeof parsed.title === "string" &&
+                    parsed.title.trim() !== "") {
+                    name = parsed.title.trim();
+                }
+                if (typeof parsed.description === "string" &&
+                    parsed.description.trim() !== "") {
+                    description = parsed.description.trim();
+                }
+            }
+        }
+        catch (error) {
+            console.warn(chalk.yellow("⚠️ Error reading config.json for llms metadata"), error);
+        }
+        return { url, name, description };
+    }
+    async readPageWithBody(page) {
+        const fullPath = path.join(this.watchDir, page.path);
+        const raw = await fs.readFile(fullPath, "utf8");
+        const { content: body } = matter(raw);
+        return { ...page, body };
+    }
+    llmsManifestPath() {
+        return path.join(this.outputDir, ".doccupine-llms-manifest.json");
+    }
+    async readLlmsManifest() {
+        const manifestPath = this.llmsManifestPath();
+        try {
+            if (await fs.pathExists(manifestPath)) {
+                const raw = await fs.readFile(manifestPath, "utf8");
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed.pageFiles)) {
+                    return new Set(parsed.pageFiles.filter((entry) => typeof entry === "string"));
+                }
+            }
+        }
+        catch {
+            // ignore corrupted manifest
+        }
+        return new Set();
+    }
+    async writeLlmsManifest(pageFiles) {
+        const manifestPath = this.llmsManifestPath();
+        const payload = { pageFiles: Array.from(pageFiles).sort() };
+        const json = JSON.stringify(payload, null, 2) + "\n";
+        await fs.writeFile(manifestPath, json, "utf8");
+    }
+    async updateLlmsFiles() {
+        const publicDir = path.join(this.outputDir, "public");
+        await fs.ensureDir(publicDir);
+        const { url: baseUrl, name, description } = await this.loadSiteMetadata();
+        const pages = await this.buildAllPagesMeta();
+        const pagesWithBodies = await Promise.all(pages.map((page) => this.readPageWithBody(page)));
+        const indexContent = llmsIndexTemplate({
+            siteName: name,
+            siteDescription: description,
+            baseUrl,
+            pages,
+            sectionsConfig: this.sectionsConfig,
+        });
+        const fullContent = llmsFullTemplate({
+            siteName: name,
+            siteDescription: description,
+            baseUrl,
+            pages: pagesWithBodies,
+            sectionsConfig: this.sectionsConfig,
+        });
+        await fs.writeFile(path.join(publicDir, "llms.txt"), indexContent, "utf8");
+        await fs.writeFile(path.join(publicDir, "llms-full.txt"), fullContent, "utf8");
+        const nextRelativePaths = new Set();
+        await Promise.all(pagesWithBodies.map(async (page) => {
+            if (page.slug === "")
+                return;
+            const relPath = `${page.slug}.md`;
+            const targetPath = path.join(publicDir, relPath);
+            await fs.ensureDir(path.dirname(targetPath));
+            await fs.writeFile(targetPath, llmsPageTemplate(page, baseUrl), "utf8");
+            nextRelativePaths.add(relPath);
+        }));
+        const previousRelativePaths = new Set([
+            ...this.generatedLlmsPagePaths,
+            ...(await this.readLlmsManifest()),
+        ]);
+        for (const stale of previousRelativePaths) {
+            if (!nextRelativePaths.has(stale)) {
+                try {
+                    const stalePath = path.join(publicDir, stale);
+                    if (await fs.pathExists(stalePath)) {
+                        await fs.remove(stalePath);
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        this.generatedLlmsPagePaths = nextRelativePaths;
+        await this.writeLlmsManifest(nextRelativePaths);
+        console.log(chalk.green(`🤖 Generated llms.txt and llms-full.txt with ${pages.length} page(s)${baseUrl ? ` using ${baseUrl}` : " (relative URLs)"}`));
+    }
     async stop() {
         if (this.watcher) {
             await this.watcher.close();
@@ -1002,7 +1203,7 @@ program
     console.log(chalk.blue(`📦 Using ${packageManager}...`));
     const install = spawn(packageManager, ["install"], {
         cwd: config.outputDir,
-        stdio: "pipe",
+        stdio: "inherit",
     });
     await new Promise((resolve, reject) => {
         install.on("close", (code) => {

package/dist/lib/layout.js

@@ -48,9 +48,8 @@ ${a}            >`
     return `import type { Metadata } from "next";
 ${isGoogleFont(fontConfig) ? `import { ${fontConfig.googleFont.fontName} } from "next/font/google";` : isLocalFont(fontConfig) ? 'import localFont from "next/font/local";' : 'import { Inter } from "next/font/google";'}
 import dynamic from "next/dynamic";
-import Script from "next/script";
 import { StyledComponentsRegistry } from "cherry-styled-components";
-import { theme, themeDark } from "@/app/theme";
+import { theme } from "@/app/theme";
 import { CherryThemeProvider } from "@/components/layout/CherryThemeProvider";
 import { ChtProvider } from "@/components/Chat";
 import { SearchProvider } from "@/components/SearchDocs";
@@ -90,7 +89,18 @@ ${isGoogleFont(fontConfig)
 });`
             : 'const font = Inter({ subsets: ["latin"] });'}
 
+function resolveSiteUrl(): URL | undefined {
+  const raw = process.env.NEXT_PUBLIC_SITE_URL ?? config.url;
+  if (!raw || typeof raw !== "string") return undefined;
+  try {
+    return new URL(raw);
+  } catch {
+    return undefined;
+  }
+}
+
 export const metadata: Metadata = {
+  metadataBase: resolveSiteUrl(),
   title: config.name || "${DEFAULT_SITE_NAME}",
   description:
     config.description ||
@@ -118,24 +128,26 @@ ${hasSections
   const pages: PagesProps[] = doccupinePages;
 
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
-        {/* Prevents dark-mode FOUC on Safari/Firefox. These browsers don't support
-            Sec-CH-Prefers-Color-Scheme (handled by middleware for Chrome), so on
-            a first visit this blocking script detects prefers-color-scheme, sets
-            the theme cookie, and hides the body until router.refresh() re-renders
-            with the correct theme (see ClientThemeProvider). */}
-        <Script
-          id="theme-init"
-          strategy="beforeInteractive"
+        {/* Resolves dark mode before first paint by adding the "dark" class
+            to <html> when needed. CSS variables in GlobalStyles flip values
+            on :root vs :root.dark, so the right palette renders without a
+            React roundtrip. Inlined as a plain <script> (not next/script) so
+            it ships in the SSR HTML and runs synchronously before paint —
+            next/script with beforeInteractive is async in App Router and
+            would still show a flash. suppressHydrationWarning on <html>
+            tells React the class/colorScheme attributes are intentionally
+            different between server (no class) and client (after script). */}
+        <script
           dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").find(function(s){return s.trim().startsWith("theme=")});if(!c){var d=window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches;document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";if(d){var s=document.createElement("style");s.id="__theme-init";s.textContent="html{background:#000!important;color-scheme:dark}body{visibility:hidden}";document.head.appendChild(s)}}}catch(e){}})();\`,
+            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
           }}
         />
       </head>
       <body className={font.className}>
         <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme} themeDark={themeDark}>
+${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
 ${a}            ${chtOpen}
 ${a}              <SearchProvider pages={pages} sections={doccupineSections}>
 ${a}                <Header>
@@ -181,24 +193,26 @@ ${analyticsEnabled ? "          </PostHogProvider>\n" : ""}        </StyledCompo
   const defaultResults = transformPagesToGroupedStructure(defaultPages);
 
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
-        {/* Prevents dark-mode FOUC on Safari/Firefox. These browsers don't support
-            Sec-CH-Prefers-Color-Scheme (handled by middleware for Chrome), so on
-            a first visit this blocking script detects prefers-color-scheme, sets
-            the theme cookie, and hides the body until router.refresh() re-renders
-            with the correct theme (see ClientThemeProvider). */}
-        <Script
-          id="theme-init"
-          strategy="beforeInteractive"
+        {/* Resolves dark mode before first paint by adding the "dark" class
+            to <html> when needed. CSS variables in GlobalStyles flip values
+            on :root vs :root.dark, so the right palette renders without a
+            React roundtrip. Inlined as a plain <script> (not next/script) so
+            it ships in the SSR HTML and runs synchronously before paint —
+            next/script with beforeInteractive is async in App Router and
+            would still show a flash. suppressHydrationWarning on <html>
+            tells React the class/colorScheme attributes are intentionally
+            different between server (no class) and client (after script). */}
+        <script
           dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").find(function(s){return s.trim().startsWith("theme=")});if(!c){var d=window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches;document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";if(d){var s=document.createElement("style");s.id="__theme-init";s.textContent="html{background:#000!important;color-scheme:dark}body{visibility:hidden}";document.head.appendChild(s)}}}catch(e){}})();\`,
+            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
           }}
         />
       </head>
       <body className={font.className}>
         <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme} themeDark={themeDark}>
+${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
 ${a}            ${chtOpen}
 ${a}              <SearchProvider pages={pages}>
 ${a}                <Header />

package/dist/lib/metadata.d.ts

@@ -1,3 +1,28 @@
+export type JsonLdKind = "article" | "homepage";
+export interface JsonLdOptions {
+    kind: JsonLdKind;
+    /** Page slug ("" for homepage). Used to build the absolute URL with config.url. */
+    canonicalPath: string;
+    title?: string;
+    description?: string;
+    date?: string;
+    /** Optional last-modified date; defaults to date when present. */
+    updated?: string;
+    image?: string;
+}
+/**
+ * Returns a code snippet that:
+ *  - declares a `jsonLd` object at runtime using the site's config,
+ *  - and renders a single `<script type="application/ld+json">` element.
+ *
+ * The snippet is meant to be inlined inside a generated page component.
+ * It emits a TechArticle on every doc page; the homepage additionally
+ * emits a graph that includes an Organization entity for entity recognition.
+ */
+export declare function generateJsonLdScript(opts: JsonLdOptions): {
+    declarations: string;
+    element: string;
+};
 export interface MetadataOptions {
     title?: string;
     titleFallback: string;
@@ -6,6 +31,11 @@ export interface MetadataOptions {
     description?: string;
     icon?: string;
     image?: string;
+    /**
+     * Canonical path for this page, e.g. "" for the homepage or "components".
+     * Resolves against `metadataBase` defined in the root layout.
+     */
+    canonicalPath?: string;
 }
 export declare function generateMetadataBlock(opts: MetadataOptions): string;
 export declare function generateRuntimeOnlyMetadataBlock(): string;

package/dist/lib/metadata.js

@@ -1,4 +1,91 @@
 import { DEFAULT_FAVICON, DEFAULT_META_DESCRIPTION, DEFAULT_OG_IMAGE, DEFAULT_SITE_NAME, } from "./constants.js";
+/**
+ * Returns a code snippet that:
+ *  - declares a `jsonLd` object at runtime using the site's config,
+ *  - and renders a single `<script type="application/ld+json">` element.
+ *
+ * The snippet is meant to be inlined inside a generated page component.
+ * It emits a TechArticle on every doc page; the homepage additionally
+ * emits a graph that includes an Organization entity for entity recognition.
+ */
+export function generateJsonLdScript(opts) {
+    const safePath = opts.canonicalPath.replace(/^\/+/, "");
+    const titleLiteral = JSON.stringify(opts.title ?? DEFAULT_SITE_NAME);
+    const descLiteral = JSON.stringify(opts.description ?? DEFAULT_META_DESCRIPTION);
+    const dateLiteral = opts.date ? JSON.stringify(opts.date) : "undefined";
+    const updatedLiteral = opts.updated
+        ? JSON.stringify(opts.updated)
+        : opts.date
+            ? JSON.stringify(opts.date)
+            : "undefined";
+    const defaultFaviconLiteral = JSON.stringify(DEFAULT_FAVICON);
+    const faviconLine = opts.image
+        ? `const faviconUrl =
+      ${JSON.stringify(opts.image)} ||
+      config.icon ||
+      ${defaultFaviconLiteral};`
+        : `const faviconUrl = config.icon || ${defaultFaviconLiteral};`;
+    // Indent 10 + "description: ".length(13) + ",".length(1) = 24. Prettier
+    // wraps the value to the next line (indent 12) once total exceeds 80.
+    const descriptionLine = descLiteral.length > 56
+        ? `description:
+            ${descLiteral},`
+        : `description: ${descLiteral},`;
+    const pathLiteral = JSON.stringify(safePath);
+    const homepageGraph = opts.kind === "homepage"
+        ? `,
+        {
+          "@type": "Organization",
+          name: siteName,
+          url: baseUrl ?? undefined,
+          logo: faviconUrl,
+        }`
+        : "";
+    const declarations = `const __jsonLdBaseUrl = (() => {
+    const raw =
+      typeof process !== "undefined"
+        ? process.env.NEXT_PUBLIC_SITE_URL
+        : undefined;
+    const fromEnv = typeof raw === "string" && raw.trim() !== "" ? raw : null;
+    const fromConfig =
+      typeof config.url === "string" && config.url.trim() !== ""
+        ? config.url
+        : null;
+    return (fromEnv ?? fromConfig)?.replace(/\\/$/, "") ?? null;
+  })();
+  const __jsonLd = (() => {
+    const baseUrl = __jsonLdBaseUrl;
+    const path = ${pathLiteral};
+    const url = baseUrl ? (path ? \`\${baseUrl}/\${path}\` : baseUrl) : undefined;
+    const siteName = config.name || ${JSON.stringify(DEFAULT_SITE_NAME)};
+    ${faviconLine}
+    return {
+      "@context": "https://schema.org",
+      "@graph": [
+        {
+          "@type": "TechArticle",
+          headline: ${titleLiteral},
+          ${descriptionLine}
+          url,
+          mainEntityOfPage: url,
+          datePublished: ${dateLiteral},
+          dateModified: ${updatedLiteral},
+          author: { "@type": "Organization", name: siteName },
+          publisher: {
+            "@type": "Organization",
+            name: siteName,
+            logo: { "@type": "ImageObject", url: faviconUrl },
+          },
+        }${homepageGraph},
+      ],
+    };
+  })();`;
+    const element = `<script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(__jsonLd) }}
+      />`;
+    return { declarations, element };
+}
 function buildFieldExpression(staticValue, configKey, defaultValue) {
     if (staticValue)
         return staticValue;
@@ -18,15 +105,24 @@ function buildTitleExpression(opts) {
         : `\${config.name ? config.name + " -" : "${DEFAULT_SITE_NAME} -"}`;
     return `${prefix} ${title}`;
 }
+function buildCanonicalLine(canonicalPath) {
+    if (canonicalPath === undefined)
+        return "";
+    const safePath = canonicalPath.replace(/^\/+/, "");
+    // Relative path resolves against `metadataBase` set in the root layout.
+    // Empty string means the homepage canonical equals the base URL itself.
+    return `\n  alternates: { canonical: ${JSON.stringify("/" + safePath)} },`;
+}
 export function generateMetadataBlock(opts) {
     const title = buildTitleExpression(opts);
     const desc = buildFieldExpression(opts.description, "description", DEFAULT_META_DESCRIPTION);
     const icon = buildFieldExpression(opts.icon, "icon", DEFAULT_FAVICON);
     const image = buildFieldExpression(opts.image, "image", DEFAULT_OG_IMAGE);
+    const canonical = buildCanonicalLine(opts.canonicalPath);
     return `export const metadata: Metadata = {
   title: \`${title}\`,
   description: \`${desc}\`,
-  icons: \`${icon}\`,
+  icons: \`${icon}\`,${canonical}
   openGraph: {
     title: \`${title}\`,
     description: \`${desc}\`,
@@ -43,6 +139,7 @@ export function generateRuntimeOnlyMetadataBlock() {
   title: \`${title}\`,
   description: \`${desc}\`,
   icons: \`${icon}\`,
+  alternates: { canonical: "/" },
   openGraph: {
     title: \`${title}\`,
     description: \`${desc}\`,