@heyo-sh/create-heyo-docs 0.1.0

package/templates/next/app/lib/seo.ts

@@ -0,0 +1,189 @@
+import type { Metadata } from "next";
+import {
+  type ChangelogGroupConfig,
+  type DocsPage,
+  type HeyoDocsConfig,
+  type NavigationGroup,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+import {
+  navigationGroupContainsPath,
+  navigationPages,
+  navigationSectionPathForPath,
+} from "@heyo-sh/heyo-docs/node";
+
+interface DocsSeoInput {
+  config: HeyoDocsConfig;
+  pathname: string;
+  page?: DocsPage;
+  endpoint?: OpenApiEndpoint;
+  changelogGroup?: ChangelogGroupConfig;
+  navigation: NavigationGroup[];
+}
+
+function canonicalFor({ config, pathname, page }: DocsSeoInput) {
+  return (
+    page?.seo.canonical ??
+    (config.siteUrl ? `${config.siteUrl}${pathname}` : undefined)
+  );
+}
+
+function website(config: HeyoDocsConfig) {
+  return {
+    "@type": "WebSite",
+    name: config.title,
+    ...(config.siteUrl ? { url: config.siteUrl } : {}),
+  };
+}
+
+function breadcrumbItems({
+  changelogGroup,
+  navigation,
+  pathname,
+  title,
+}: Pick<DocsSeoInput, "changelogGroup" | "navigation" | "pathname"> & {
+  title: string;
+}) {
+  if (changelogGroup) return [{ label: changelogGroup.group, href: pathname }];
+  const group = navigation.find((candidate) =>
+    navigationGroupContainsPath(candidate, pathname),
+  );
+  const sections = group
+    ? navigationSectionPathForPath(group.sections, pathname)
+    : undefined;
+  if (!group) return [{ label: title, href: pathname }];
+  return [
+    { label: group.group, href: navigationPages(group.sections)[0]?.slug },
+    ...(sections ?? []).map((section) => ({
+      label: section.section,
+      href: navigationPages([section])[0]?.slug,
+    })),
+    { label: title, href: pathname },
+  ];
+}
+
+function absoluteUrl(siteUrl: string | undefined, href: string | undefined) {
+  if (!siteUrl || !href) return undefined;
+  return /^https?:\/\//.test(href)
+    ? href
+    : new URL(href, `${siteUrl}/`).toString();
+}
+
+/** Next Metadata plus JSON-LD for MDX, changelog and generated API pages. */
+export function docsSeo(input: DocsSeoInput): {
+  metadata: Metadata;
+  structuredData: unknown[];
+} {
+  const { changelogGroup, config, endpoint, navigation, page, pathname } =
+    input;
+  const title = page?.seo.title ?? `${endpoint!.title} | ${config.title}`;
+  const description =
+    page?.seo.description ??
+    endpoint?.description ??
+    `${endpoint!.method.toUpperCase()} ${endpoint!.path} API endpoint.`;
+  const canonical = canonicalFor(input);
+  const pageType = endpoint
+    ? {
+        "@context": "https://schema.org",
+        "@type": "APIReference",
+        headline: title,
+        description,
+        ...(canonical ? { url: canonical } : {}),
+        isPartOf: website(config),
+        mainEntity: {
+          "@type": "EntryPoint",
+          name:
+            endpoint.operationId ??
+            `${endpoint.method.toUpperCase()} ${endpoint.path}`,
+          httpMethod: endpoint.method.toUpperCase(),
+          urlTemplate: endpoint.servers[0]
+            ? `${endpoint.servers[0].replace(/\/$/, "")}${endpoint.path}`
+            : endpoint.path,
+          ...(endpoint.requestBody?.contentType
+            ? { encodingType: endpoint.requestBody.contentType }
+            : {}),
+          ...(endpoint.responses[0]?.contentType
+            ? { contentType: endpoint.responses[0].contentType }
+            : {}),
+        },
+      }
+    : changelogGroup
+      ? {
+          "@context": "https://schema.org",
+          "@type": "CollectionPage",
+          headline: title,
+          description,
+          ...(canonical ? { url: canonical } : {}),
+          isPartOf: website(config),
+          ...(page?.changelogUpdates?.length
+            ? {
+                hasPart: page.changelogUpdates.map((update) => ({
+                  "@type": "TechArticle",
+                  headline: update.label,
+                  ...(update.tags.length
+                    ? { keywords: update.tags.join(", ") }
+                    : {}),
+                  ...(canonical ? { url: `${canonical}#${update.id}` } : {}),
+                })),
+              }
+            : {}),
+        }
+      : {
+          "@context": "https://schema.org",
+          "@type": "TechArticle",
+          headline: title,
+          description,
+          ...(canonical ? { url: canonical } : {}),
+          isPartOf: website(config),
+        };
+  const crumbs = breadcrumbItems({
+    changelogGroup,
+    navigation,
+    pathname,
+    title: page?.title ?? endpoint!.title,
+  });
+  const structuredData = [
+    pageType,
+    {
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { label: config.title, href: config.siteUrl },
+        ...crumbs,
+      ].map((item, index, items) => ({
+        "@type": "ListItem",
+        position: index + 1,
+        name: item.label,
+        ...((
+          index === items.length - 1
+            ? canonical
+            : absoluteUrl(config.siteUrl, item.href)
+        )
+          ? {
+              item:
+                index === items.length - 1
+                  ? canonical
+                  : absoluteUrl(config.siteUrl, item.href),
+            }
+          : {}),
+      })),
+    },
+  ];
+  return {
+    metadata: {
+      title,
+      description,
+      robots: { index: true, follow: true },
+      alternates: canonical ? { canonical } : undefined,
+      openGraph: {
+        type: "article",
+        siteName: config.title,
+        title,
+        description,
+        ...(canonical ? { url: canonical } : {}),
+      },
+      twitter: { card: "summary", title, description },
+    },
+    structuredData,
+  };
+}

package/templates/next/app/lib/theme.ts

@@ -0,0 +1,61 @@
+export type Theme = "dark" | "light" | "system";
+export type ResolvedTheme = Exclude<Theme, "system">;
+
+export const DEFAULT_THEME: Theme = "system";
+export const THEME_STORAGE_KEY = "heyo-docs-theme";
+
+const themeValues = new Set<Theme>(["light", "dark", "system"]);
+
+export function isTheme(value: string | null): value is Theme {
+  return value !== null && themeValues.has(value as Theme);
+}
+
+export function getStoredTheme(
+  storageKey: string,
+  fallbackTheme: Theme,
+): Theme {
+  if (typeof window === "undefined") return fallbackTheme;
+  try {
+    const storedTheme = window.localStorage.getItem(storageKey);
+    return isTheme(storedTheme) ? storedTheme : fallbackTheme;
+  } catch {
+    return fallbackTheme;
+  }
+}
+
+export function applyTheme(theme: Theme): ResolvedTheme {
+  const resolvedTheme =
+    theme === "system"
+      ? window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light"
+      : theme;
+  const root = window.document.documentElement;
+  root.classList.remove("light", "dark");
+  root.classList.add(resolvedTheme);
+  root.style.colorScheme = resolvedTheme;
+  return resolvedTheme;
+}
+
+export function getThemeScript(storageKey: string, defaultTheme: Theme) {
+  return `(() => {
+  const storageKey = ${JSON.stringify(storageKey)};
+  const fallbackTheme = ${JSON.stringify(defaultTheme)};
+  const isTheme = (value) => value === "light" || value === "dark" || value === "system";
+  const storedTheme = (() => {
+    try {
+      const value = window.localStorage.getItem(storageKey);
+      return isTheme(value) ? value : fallbackTheme;
+    } catch {
+      return fallbackTheme;
+    }
+  })();
+  const resolvedTheme = storedTheme === "system"
+    ? window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
+    : storedTheme;
+  const root = document.documentElement;
+  root.classList.remove("light", "dark");
+  root.classList.add(resolvedTheme);
+  root.style.colorScheme = resolvedTheme;
+})();`;
+}

package/templates/next/app/llms-full.txt/route.ts

@@ -0,0 +1,10 @@
+import { llmsFull } from "@heyo-sh/heyo-docs/node";
+
+import { config, markdownPages } from "../lib/docs";
+
+export function GET(request: Request) {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(llmsFull(markdownPages, siteUrl), {
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+}

package/templates/next/app/llms.txt/route.ts

@@ -0,0 +1,10 @@
+import { llmsIndex } from "@heyo-sh/heyo-docs/node";
+
+import { config, markdownPages } from "../lib/docs";
+
+export function GET(request: Request) {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(llmsIndex(markdownPages, config, siteUrl), {
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+}

package/templates/next/app/not-found.tsx

@@ -0,0 +1,13 @@
+import type { Metadata } from "next";
+
+import config from "../heyo-docs.config";
+import { NextDocsApp } from "./components/docs-app";
+
+export const metadata: Metadata = {
+  title: `Not found | ${config.title}`,
+  robots: { index: false, follow: false },
+};
+
+export default function NotFound() {
+  return <NextDocsApp pathname="/__not-found" />;
+}

package/templates/next/app/robots.txt/route.ts

@@ -0,0 +1,16 @@
+import { config } from "../lib/docs";
+
+export function GET(request: Request) {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(
+    [
+      "User-agent: *",
+      "Allow: /",
+      "Disallow: /__heyo-docs/",
+      "",
+      `Sitemap: ${siteUrl}/sitemap.xml`,
+      "",
+    ].join("\n"),
+    { headers: { "content-type": "text/plain; charset=utf-8" } },
+  );
+}

package/templates/next/app/rss.xml/route.ts

@@ -0,0 +1,10 @@
+import { rssXml } from "@heyo-sh/heyo-docs/node";
+
+import { config, markdownPages } from "../lib/docs";
+
+export function GET(request: Request) {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(rssXml(markdownPages, config, siteUrl), {
+    headers: { "content-type": "application/rss+xml; charset=utf-8" },
+  });
+}

package/templates/next/app/sitemap.xml/route.ts

@@ -0,0 +1,14 @@
+import { sitemapXml } from "@heyo-sh/heyo-docs/node";
+
+import { config, docsModel } from "../lib/docs";
+
+export function GET(request: Request) {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(
+    sitemapXml(
+      siteUrl,
+      [...docsModel.pages, ...docsModel.endpoints].map((page) => page.slug),
+    ),
+    { headers: { "content-type": "application/xml; charset=utf-8" } },
+  );
+}

package/templates/next/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-mira",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/app.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/templates/next/content/getting-started.mdx

@@ -0,0 +1,16 @@
+---
+title: Getting started
+description: Run your new documentation site locally.
+---
+
+# Getting started
+
+Install dependencies with your chosen package manager and start the development server.
+
+## Create a page
+
+Create `content/guides/deploying.mdx` to get the `/guides/deploying` route. Its frontmatter controls its title and description.
+
+## Configure the documentation
+
+Use `heyo-docs.config.ts` to change the title, colors, tabs, sidebar groups, footer links and selected theme without regenerating your project. Add pages or directories to a section's `pages` list to control the sidebar order.

package/templates/next/content/index.mdx

@@ -0,0 +1,22 @@
+---
+title: Welcome to {{PROJECT_NAME}}
+description: Everything you need to document your product with Heyo Docs.
+---
+
+# Welcome to {{PROJECT_NAME}}
+
+Start with this page, then add focused MDX files to the `content` directory. Heyo Docs turns the directory structure into routes; use `groups` in `heyo-docs.config.ts` to control sidebar navigation and its order.
+
+## What is included?
+
+- A Next.js App Router application.
+- The selected documentation theme from `heyo-docs`.
+- Searchable page metadata, SEO tags, `robots.txt`, a sitemap, RSS, LLM files, Markdown mirrors, and a 404 page.
+
+## Edit this page
+
+```mdx
+## A new section
+
+Content updates reload in development.
+```

package/templates/next/content/mdx-components.mdx

@@ -0,0 +1,41 @@
+---
+title: MDX components
+description: Every built-in MDX component is available without an import.
+---
+
+# MDX components
+
+Every built-in component is available in a Next.js MDX page without an import.
+
+## Callout
+
+<Callout
+  type="tip"
+  title="No imports needed"
+  description="Use the documentation components directly in your MDX files."
+/>
+
+## Tabs
+
+<Tabs defaultValue="npm" variant="line">
+  <Tab title="npm" value="npm">
+    npm run dev
+  </Tab>
+  <Tab title="Bun" value="bun">
+    bun run dev
+  </Tab>
+</Tabs>
+
+## Code blocks
+
+`CodeBlock` preserves every newline as a hard code line.
+
+<CodeBlock language="tsx" title="app/page.tsx" showLineNumbers>
+  {`export default function Page() {
+  return <h1>Hello</h1>;
+}`}
+</CodeBlock>
+
+## More components
+
+`Accordion`, `Button`, `Columns`, `File`, `GitHub`, `HoverCard`, `Image`, `Mermaid`, `RelatedTopics`, `Steps`, `Tree`, `Video`, and the remaining primitives use the same MDX contract as every Heyo Docs template.

package/templates/next/heyo-docs.config.ts

@@ -0,0 +1,24 @@
+import { heyoDocs } from "@heyo-sh/heyo-docs/config";
+
+export default heyoDocs({
+  title: "{{PROJECT_NAME}}",
+  description: "Developer documentation",
+  content: "./content",
+  theme: "{{THEME}}",
+  mode: "system",
+  groups: [
+    {
+      group: "Documentation",
+      icon: "globe",
+      sections: [
+        {
+          section: "Get started",
+          pages: ["index"],
+        },
+      ],
+    },
+  ],
+  branding: { name: "{{PROJECT_NAME}}" },
+  // Set this before deploying to publish canonical and absolute social URLs.
+  // siteUrl: "https://docs.example.com",
+});

package/templates/next/mdx.d.ts

@@ -0,0 +1,6 @@
+declare module "*.mdx" {
+  import type { ComponentType } from "react";
+
+  const MDXContent: ComponentType;
+  export default MDXContent;
+}

package/templates/next/next-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+import "./.next/types/root-params.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/next/next.config.ts

@@ -0,0 +1,23 @@
+import createMDX from "@next/mdx";
+import type { NextConfig } from "next";
+import { heyoDocsMdxOptions } from "@heyo-sh/heyo-docs/next";
+
+const nextConfig: NextConfig = {
+  pageExtensions: ["ts", "tsx", "md", "mdx"],
+  async rewrites() {
+    return {
+      beforeFiles: [
+        {
+          source: "/:path*.md",
+          destination: "/heyo-docs-internal/markdown/:path*",
+        },
+      ],
+    };
+  },
+};
+
+const withMdx = createMDX({
+  options: heyoDocsMdxOptions({ root: process.cwd() }) as never,
+});
+
+export default withMdx(nextConfig);

package/templates/next/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "packageManager": "{{PACKAGE_MANAGER}}",
+  "scripts": {
+    "predev": "tsx scripts/generate-heyo-docs.ts",
+    "dev": "concurrently --kill-others-on-fail \"next dev\" \"tsx scripts/generate-heyo-docs.ts --watch\"",
+    "build": "tsx scripts/generate-heyo-docs.ts && next build",
+    "start": "next start",
+    "typecheck": "tsx scripts/generate-heyo-docs.ts && tsc --noEmit"
+  },
+  "dependencies": {
+    "@fontsource-variable/figtree": "^5.3.0",
+    "@remixicon/react": "^4.9.0",
+    "@heyo-sh/heyo-docs": "{{HEYO_DOCS_VERSION}}",
+    "next": "16.3.2",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "shadcn": "^4.19.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@next/mdx": "16.3.2",
+    "@mdx-js/loader": "3.1.0",
+    "@mdx-js/react": "3.1.0",
+    "@tailwindcss/postcss": "^4.1.14",
+    "@types/node": "24.10.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "concurrently": "^9.2.1",
+    "rehype-slug": "6.0.0",
+    "remark-frontmatter": "5.0.0",
+    "remark-gfm": "^4.0.1",
+    "tailwindcss": "^4.1.14",
+    "tsx": "^4.20.6",
+    "typescript": "5.9.3"
+  }
+}

package/templates/next/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};