doccupine 0.0.87 → 0.0.89

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,9 +10,11 @@ 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 { proxyTemplate } from "./templates/proxy.js";
+import { robotsTemplate } from "./templates/app/robots.js";
+import { sitemapTemplate } from "./templates/app/sitemap.js";
 export { generateSlug, getFullSlug, escapeTemplateContent, } from "./lib/utils.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -72,6 +74,7 @@ class MDXToNextJSGenerator {
         console.log(chalk.white("   npm install && npm run dev"));
     }
     async createNextJSStructure() {
+        const siteUrl = await this.loadSiteUrl();
         const structure = {
             ...appStructure,
             "next.config.ts": nextConfigTemplate(this.analyticsConfig),
@@ -82,6 +85,7 @@ class MDXToNextJSGenerator {
             "navigation.json": `[]\n`,
             "sections.json": `[]\n`,
             "theme.json": `{}\n`,
+            "app/robots.ts": robotsTemplate(siteUrl !== null),
             "app/layout.tsx": this.generateRootLayout(),
         };
         for (const [filePath, content] of Object.entries(structure)) {
@@ -89,6 +93,7 @@ class MDXToNextJSGenerator {
             await fs.ensureDir(path.dirname(fullPath));
             await fs.writeFile(fullPath, String(await content), "utf8");
         }
+        await this.updateSitemap();
     }
     async createStartingDocs() {
         const structure = startingDocsStructure;
@@ -326,6 +331,10 @@ class MDXToNextJSGenerator {
                 if (fileName === "sections.json") {
                     await this.reloadSections();
                 }
+                if (fileName === "config.json") {
+                    await this.updateSitemap();
+                    await this.updateRobots();
+                }
             }
             catch (error) {
                 console.error(chalk.red(`❌ Error copying ${fileName}:`), error);
@@ -344,6 +353,10 @@ class MDXToNextJSGenerator {
                 if (fileName === "sections.json") {
                     await this.reloadSections();
                 }
+                if (fileName === "config.json") {
+                    await this.updateSitemap();
+                    await this.updateRobots();
+                }
             }
             catch (error) {
                 console.error(chalk.red(`❌ Error removing ${fileName}:`), error);
@@ -607,6 +620,22 @@ class MDXToNextJSGenerator {
         const { data: frontmatter } = matter(content);
         const { sectionSlug, pageSlug } = this.determineSectionForFile(file, frontmatter);
         const fullSlug = getFullSlug(pageSlug, sectionSlug);
+        let lastModified;
+        if (frontmatter.date) {
+            const parsed = new Date(frontmatter.date);
+            if (!Number.isNaN(parsed.getTime())) {
+                lastModified = parsed.toISOString();
+            }
+        }
+        if (!lastModified) {
+            try {
+                const stats = await fs.stat(fullPath);
+                lastModified = stats.mtime.toISOString();
+            }
+            catch {
+                // ignore
+            }
+        }
         return {
             slug: fullSlug,
             title: frontmatter.title || "Untitled",
@@ -617,6 +646,7 @@ class MDXToNextJSGenerator {
             categoryOrder: frontmatter.categoryOrder || 0,
             order: frontmatter.order || 0,
             section: sectionSlug,
+            lastModified,
         };
     }
     async buildAllPagesMeta() {
@@ -650,6 +680,7 @@ class MDXToNextJSGenerator {
             }
             await this.updatePagesIndex();
             await this.updateRootLayout();
+            await this.updateSitemap();
             await this.generateSectionIndexPages();
             console.log(chalk.green(`✅ Generated page for: ${filePath}`));
             await this.maybeUpdateSections();
@@ -673,6 +704,7 @@ class MDXToNextJSGenerator {
             }
             await this.updatePagesIndex();
             await this.updateRootLayout();
+            await this.updateSitemap();
             console.log(chalk.green(`✅ Removed page for: ${filePath}`));
             await this.maybeUpdateSections();
         }
@@ -754,6 +786,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";
@@ -763,8 +809,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");
@@ -786,6 +845,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;
             }
@@ -799,8 +862,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";
@@ -809,8 +882,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");
@@ -824,6 +907,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";
@@ -833,8 +930,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");
@@ -845,6 +952,72 @@ export default function Page() {
         const layoutContent = await this.generateRootLayout();
         await fs.writeFile(path.join(this.outputDir, "app", "layout.tsx"), layoutContent, "utf8");
     }
+    async loadSiteUrl() {
+        const configPath = path.join(this.rootDir, "config.json");
+        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() !== "") {
+                    return parsed.url.trim().replace(/\/$/, "");
+                }
+            }
+        }
+        catch (error) {
+            console.warn(chalk.yellow("⚠️ Error reading config.json"), error);
+        }
+        return null;
+    }
+    buildSitemapEntries(pages) {
+        const sectionSlugs = new Set((this.sectionsConfig || [])
+            .map((s) => s.slug)
+            .filter((s) => typeof s === "string" && s !== ""));
+        const entries = pages.map((page) => {
+            let priority = 0.5;
+            if (page.slug === "") {
+                priority = 1.0;
+            }
+            else if (sectionSlugs.has(page.slug)) {
+                priority = 0.8;
+            }
+            return {
+                slug: page.slug,
+                lastModified: page.lastModified,
+                changeFrequency: "weekly",
+                priority,
+            };
+        });
+        if (!entries.some((entry) => entry.slug === "")) {
+            entries.unshift({
+                slug: "",
+                changeFrequency: "weekly",
+                priority: 1.0,
+            });
+        }
+        return entries;
+    }
+    async updateSitemap() {
+        const sitemapPath = path.join(this.outputDir, "app", "sitemap.ts");
+        const siteUrl = await this.loadSiteUrl();
+        if (!siteUrl) {
+            if (await fs.pathExists(sitemapPath)) {
+                await fs.remove(sitemapPath);
+                console.log(chalk.yellow("🗑️ Removed sitemap.ts (no site URL configured)"));
+            }
+            return;
+        }
+        const pages = await this.buildAllPagesMeta();
+        const entries = this.buildSitemapEntries(pages);
+        await fs.writeFile(sitemapPath, sitemapTemplate(entries), "utf8");
+        console.log(chalk.green(`🗺️ Generated sitemap.ts with ${entries.length} page(s) using ${siteUrl}`));
+    }
+    async updateRobots() {
+        const siteUrl = await this.loadSiteUrl();
+        await fs.writeFile(path.join(this.outputDir, "app", "robots.ts"), robotsTemplate(siteUrl !== null), "utf8");
+        console.log(chalk.green(siteUrl
+            ? `🤖 Regenerated robots.ts with sitemap link`
+            : `🤖 Regenerated robots.ts (no sitemap link)`));
+    }
     async stop() {
         if (this.watcher) {
             await this.watcher.close();

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}\`,

package/dist/lib/structures.js

@@ -10,7 +10,6 @@ import { ragRoutesTemplate } from "../templates/app/api/rag/route.js";
 import { searchRoutesTemplate } from "../templates/app/api/search/route.js";
 import { routesTemplate } from "../templates/app/api/theme/routes.js";
 import { notFoundTemplate } from "../templates/app/not-found.js";
-import { robotsTemplate } from "../templates/app/robots.js";
 import { themeTemplate } from "../templates/app/theme.js";
 import { chatTemplate } from "../templates/components/Chat.js";
 import { clickOutsideTemplate } from "../templates/components/ClickOutside.js";
@@ -121,7 +120,6 @@ export const appStructure = {
     "package.json": packageJsonTemplate,
     "tsconfig.json": tsconfigTemplate,
     "app/not-found.tsx": notFoundTemplate,
-    "app/robots.ts": robotsTemplate,
     "app/theme.ts": themeTemplate,
     "app/api/mcp/route.ts": mcpRoutesTemplate,
     "app/api/rag/route.ts": ragRoutesTemplate,

package/dist/lib/types.d.ts

@@ -14,6 +14,7 @@ export interface PageMeta {
     categoryOrder: number;
     order: number;
     section: string;
+    lastModified?: string;
 }
 export interface SectionConfig {
     label: string;

package/dist/templates/app/robots.d.ts

@@ -1 +1 @@
-export declare const robotsTemplate = "import type { MetadataRoute } from \"next\";\n\nexport default function robots(): MetadataRoute.Robots {\n  return {\n    rules: {\n      userAgent: \"*\",\n      allow: \"/\",\n    },\n  };\n}\n";
+export declare const robotsTemplate: (hasSiteUrl: boolean) => string;