@heyo-sh/create-heyo-docs 0.1.0

package/templates/astro/src/lib/seo.ts

@@ -0,0 +1,221 @@
+import {
+  navigationGroupContainsPath,
+  navigationPages,
+  navigationSectionPathForPath,
+  type ChangelogGroupConfig,
+  type DocsPage,
+  type HeyoDocsConfig,
+  type NavigationGroup,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+
+interface DocsSeoInput {
+  config: HeyoDocsConfig;
+  pathname: string;
+  page?: DocsPage;
+  endpoint?: OpenApiEndpoint;
+  changelogGroup?: ChangelogGroupConfig;
+  navigation?: NavigationGroup[];
+}
+
+function canonicalFor(
+  config: HeyoDocsConfig,
+  pathname: string,
+  page?: DocsPage,
+): string | undefined {
+  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 } : {}),
+  };
+}
+
+interface BreadcrumbItem {
+  label: string;
+  href?: string;
+}
+
+function breadcrumbItems(
+  navigation: NavigationGroup[] | undefined,
+  pathname: string,
+  title: string,
+  changelogGroup: ChangelogGroupConfig | undefined,
+): BreadcrumbItem[] {
+  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 }];
+
+  const groupHref = navigationPages(group.sections)[0]?.slug;
+  return [
+    { label: group.group, href: groupHref },
+    ...(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;
+  if (/^https?:\/\//.test(href)) return href;
+  return new URL(href, `${siteUrl}/`).toString();
+}
+
+function breadcrumbs(
+  config: HeyoDocsConfig,
+  canonical: string | undefined,
+  title: string,
+  navigation: NavigationGroup[] | undefined,
+  pathname: string,
+  changelogGroup: ChangelogGroupConfig | undefined,
+) {
+  const items = breadcrumbItems(navigation, pathname, title, changelogGroup);
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: [
+      { label: config.title, href: config.siteUrl },
+      ...items,
+    ].map((item, index, allItems) => {
+      const itemUrl =
+        index === allItems.length - 1
+          ? canonical
+          : absoluteUrl(config.siteUrl, item.href);
+      return {
+        "@type": "ListItem",
+        position: index + 1,
+        name: item.label,
+        ...(itemUrl ? { item: itemUrl } : {}),
+      };
+    }),
+  };
+}
+
+function endpointUrlTemplate(endpoint: OpenApiEndpoint) {
+  const server = endpoint.servers[0]?.replace(/\/$/, "");
+  return server ? `${server}${endpoint.path}` : endpoint.path;
+}
+
+function structuredData({
+  changelogGroup,
+  config,
+  endpoint,
+  page,
+  canonical,
+  description,
+  title,
+}: Omit<DocsSeoInput, "pathname"> & {
+  canonical?: string;
+  description: string;
+  title: string;
+}) {
+  if (endpoint) {
+    const entryPoint = {
+      "@type": "EntryPoint",
+      name:
+        endpoint.operationId ??
+        `${endpoint.method.toUpperCase()} ${endpoint.path}`,
+      httpMethod: endpoint.method.toUpperCase(),
+      urlTemplate: endpointUrlTemplate(endpoint),
+      ...(endpoint.requestBody?.contentType
+        ? { encodingType: endpoint.requestBody.contentType }
+        : {}),
+      ...(endpoint.responses[0]?.contentType
+        ? { contentType: endpoint.responses[0].contentType }
+        : {}),
+    };
+    return {
+      "@context": "https://schema.org",
+      "@type": "APIReference",
+      headline: title,
+      description,
+      ...(canonical ? { url: canonical } : {}),
+      isPartOf: website(config),
+      mainEntity: entryPoint,
+    };
+  }
+
+  if (page && changelogGroup) {
+    return {
+      "@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}` } : {}),
+            })),
+          }
+        : {}),
+    };
+  }
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    headline: title,
+    description,
+    ...(canonical ? { url: canonical } : {}),
+    isPartOf: website(config),
+  };
+}
+
+export function docsSeo(input: DocsSeoInput) {
+  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(config, pathname, page);
+
+  return {
+    title,
+    description,
+    canonical,
+    structuredData: [
+      structuredData({
+        changelogGroup,
+        config,
+        endpoint,
+        page,
+        canonical,
+        description,
+        title,
+      }),
+      breadcrumbs(
+        config,
+        canonical,
+        page?.title ?? endpoint!.title,
+        navigation,
+        pathname,
+        changelogGroup,
+      ),
+    ],
+  };
+}

package/templates/astro/src/lib/theme.ts

@@ -0,0 +1,74 @@
+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 getSystemTheme(): ResolvedTheme {
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+export function resolveTheme(theme: Theme): ResolvedTheme {
+  return theme === "system" ? getSystemTheme() : theme;
+}
+
+export function applyTheme(theme: Theme): ResolvedTheme {
+  const resolvedTheme = resolveTheme(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/astro/src/pages/[...slug].astro

@@ -0,0 +1,50 @@
+---
+import { AstroDocsApp } from "../components/docs-app";
+import DocsLayout from "../layouts/docs-layout.astro";
+import { docsContext, pathnameForSlug } from "../lib/docs";
+import { docsSeo } from "../lib/seo";
+import { openApiEndpointDetail } from "@heyo-sh/heyo-docs";
+import { pages } from "virtual:heyo-docs-content";
+import { openApiEndpoints } from "virtual:heyo-docs-openapi/index";
+
+export async function getStaticPaths() {
+  return [...pages, ...openApiEndpoints].map(({ slug }) => ({
+    params: { slug: slug === "/" ? undefined : slug.slice(1) },
+  }));
+}
+
+const pathname = pathnameForSlug(Astro.params.slug);
+const context = docsContext(pathname);
+const exists = Boolean(context.page || context.endpoint);
+if (!exists) Astro.response.status = 404;
+const currentOpenApiEndpoint = context.endpoint
+  ? openApiEndpointDetail(context.endpoint)
+  : undefined;
+
+const seo = exists
+  ? docsSeo({ ...context, pathname })
+  : {
+      title: `Not found | ${context.config.title}`,
+      description: context.config.description,
+      structuredData: [
+        {
+          "@context": "https://schema.org",
+          "@type": "WebSite",
+          name: context.config.title,
+          description: context.config.description,
+          ...(context.config.siteUrl ? { url: context.config.siteUrl } : {}),
+        },
+      ],
+    };
+---
+
+<DocsLayout
+  {...seo}
+  robots={exists ? "index, follow" : "noindex"}
+>
+  <AstroDocsApp
+    client:load
+    currentOpenApiEndpoint={currentOpenApiEndpoint}
+    pathname={pathname}
+  />
+</DocsLayout>

package/templates/astro/src/pages/[...slug].md.ts

@@ -0,0 +1,28 @@
+import type { APIRoute } from "astro";
+import { markdownForPage, pathnameFromMarkdownPath } from "@heyo-sh/heyo-docs";
+
+import { pages } from "virtual:heyo-docs-content/server";
+
+export function getStaticPaths() {
+  return pages.map((page) => ({
+    params: { slug: page.slug === "/" ? "index" : page.slug.slice(1) },
+  }));
+}
+
+/** Serves every documentation page as stable, frontmatter-free Markdown. */
+export const GET: APIRoute = ({ params }) => {
+  const pagePathname = pathnameFromMarkdownPath(`/${params.slug ?? ""}.md`);
+  const page = pagePathname
+    ? pages.find((candidate) => candidate.slug === pagePathname)
+    : undefined;
+
+  if (!page)
+    return new Response("Not Found", {
+      status: 404,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+
+  return new Response(markdownForPage(page), {
+    headers: { "content-type": "text/markdown; charset=utf-8" },
+  });
+};

package/templates/astro/src/pages/heyo-docs-internal/openapi-request.ts

@@ -0,0 +1,8 @@
+import type { APIRoute } from "astro";
+
+import { handleOpenApiRequest } from "../../lib/openapi-request";
+
+/** The only dynamic OpenAPI surface: a same-origin proxy for Try it requests. */
+export const prerender = false;
+
+export const POST: APIRoute = ({ request }) => handleOpenApiRequest(request);

package/templates/astro/src/pages/llms-full.txt.ts

@@ -0,0 +1,13 @@
+import type { APIRoute } from "astro";
+import { llmsFull } from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { pages } from "virtual:heyo-docs-content/server";
+
+/** The complete documentation corpus, ready for an LLM to consume. */
+export const GET: APIRoute = ({ request }) => {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(llmsFull(pages, siteUrl), {
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+};

package/templates/astro/src/pages/llms.txt.ts

@@ -0,0 +1,13 @@
+import type { APIRoute } from "astro";
+import { llmsIndex } from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { pages } from "virtual:heyo-docs-content/server";
+
+/** A concise, discoverable index of every documentation page. */
+export const GET: APIRoute = ({ request }) => {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(llmsIndex(pages, config, siteUrl), {
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+};

package/templates/astro/src/pages/robots.txt.ts

@@ -0,0 +1,19 @@
+import type { APIRoute } from "astro";
+
+import config from "../../heyo-docs.config";
+
+export const GET: APIRoute = ({ 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/astro/src/pages/rss.xml.ts

@@ -0,0 +1,13 @@
+import type { APIRoute } from "astro";
+import { rssXml } from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { pages } from "virtual:heyo-docs-content/server";
+
+/** RSS 2.0 feed for every `<Update>` in the configured changelog groups. */
+export const GET: APIRoute = ({ request }) => {
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(rssXml(pages, config, siteUrl), {
+    headers: { "content-type": "application/rss+xml; charset=utf-8" },
+  });
+};

package/templates/astro/src/pages/sitemap.xml.ts

@@ -0,0 +1,19 @@
+import type { APIRoute } from "astro";
+import { sitemapXml } from "@heyo-sh/heyo-docs";
+
+import config from "../../heyo-docs.config";
+import { createDocsModel } from "@heyo-sh/heyo-docs";
+import { openApiDocuments } from "virtual:heyo-docs-openapi";
+import { pages } from "virtual:heyo-docs-content";
+
+export const GET: APIRoute = ({ request }) => {
+  const model = createDocsModel(config, pages, openApiDocuments);
+  const siteUrl = config.siteUrl ?? new URL(request.url).origin;
+  return new Response(
+    sitemapXml(
+      siteUrl,
+      [...model.pages, ...model.endpoints].map((page) => page.slug),
+    ),
+    { headers: { "content-type": "application/xml; charset=utf-8" } },
+  );
+};

package/templates/astro/src/styles/app.css

@@ -0,0 +1,8 @@
+@import "@fontsource-variable/figtree";
+@import "@heyo-sh/heyo-docs/theme/{{THEME}}.css";
+
+:root {
+  --heyo-docs-font-family: "Figtree Variable", sans-serif;
+}
+
+/* Add project-specific token overrides and theme styles below this import. */

package/templates/astro/src/virtual.d.ts

@@ -0,0 +1,19 @@
+declare module "virtual:heyo-docs-content" {
+  import type { DocsPage } from "@heyo-sh/heyo-docs";
+  export const pages: DocsPage[];
+}
+
+declare module "virtual:heyo-docs-content/server" {
+  import type { MarkdownPage } from "@heyo-sh/heyo-docs";
+  export const pages: MarkdownPage[];
+}
+
+declare module "virtual:heyo-docs-openapi" {
+  import type { OpenApiDocumentSource } from "@heyo-sh/heyo-docs";
+  export const openApiDocuments: OpenApiDocumentSource[];
+}
+
+declare module "virtual:heyo-docs-openapi/index" {
+  import type { OpenApiEndpoint } from "@heyo-sh/heyo-docs";
+  export const openApiEndpoints: OpenApiEndpoint[];
+}

package/templates/astro/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "allowJs": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}

package/templates/next/app/[[...slug]]/page.tsx

@@ -0,0 +1,59 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { openApiEndpointDetail } from "@heyo-sh/heyo-docs/node";
+
+import { NextDocsApp } from "../components/docs-app";
+import { docsContext, docsModel, pathnameForSegments } from "../lib/docs";
+import { docsSeo } from "../lib/seo";
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>;
+}
+
+/** Every known MDX and OpenAPI route is emitted as static HTML at build time. */
+export const dynamic = "force-static";
+
+export async function generateStaticParams() {
+  return [...docsModel.pages, ...docsModel.endpoints].map(({ slug }) => ({
+    slug: slug === "/" ? [] : slug.slice(1).split("/"),
+  }));
+}
+
+export async function generateMetadata({
+  params,
+}: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const pathname = pathnameForSegments(slug);
+  const context = docsContext(pathname);
+  if (!context.page && !context.endpoint)
+    return {
+      title: `Not found | ${context.config.title}`,
+      robots: { index: false, follow: false },
+    };
+  return docsSeo({ ...context, pathname }).metadata;
+}
+
+export default async function DocsPage({ params }: PageProps) {
+  const { slug } = await params;
+  const pathname = pathnameForSegments(slug);
+  const context = docsContext(pathname);
+  if (!context.page && !context.endpoint) notFound();
+  const { structuredData } = docsSeo({ ...context, pathname });
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: JSON.stringify(structuredData).replace(/</g, "\\u003c"),
+        }}
+      />
+      <NextDocsApp
+        currentOpenApiEndpoint={
+          context.endpoint ? openApiEndpointDetail(context.endpoint) : undefined
+        }
+        pathname={pathname}
+      />
+    </>
+  );
+}

package/templates/next/app/app.css

@@ -0,0 +1,8 @@
+@import "@fontsource-variable/figtree";
+@import "@heyo-sh/heyo-docs/theme/{{THEME}}.css";
+
+:root {
+  --heyo-docs-font-family: "Figtree Variable", sans-serif;
+}
+
+/* Add project-specific token overrides and theme styles below this import. */