@heyo-sh/create-heyo-docs 0.1.0

package/templates/react-router/app/root.tsx

@@ -0,0 +1,140 @@
+import type { ReactNode } from "react";
+import {
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+  type LinksFunction,
+  type MetaFunction,
+} from "react-router";
+import { pathnameFromMarkdownPath } from "@heyo-sh/heyo-docs";
+import type { Route } from "./+types/root";
+
+import "./app.css";
+import { ThemeProvider } from "./components/theme-provider";
+import config from "../heyo-docs.config";
+import { getThemeScript, THEME_STORAGE_KEY } from "./lib/theme";
+
+export const meta: MetaFunction = () => {
+  const canonical = config.siteUrl ? `${config.siteUrl}/` : undefined;
+
+  return [
+    { title: config.title },
+    { name: "description", content: config.description },
+    { name: "robots", content: "index, follow" },
+    { name: "referrer", content: "strict-origin-when-cross-origin" },
+    { property: "og:type", content: "website" },
+    { property: "og:site_name", content: config.title },
+    { property: "og:title", content: config.title },
+    { property: "og:description", content: config.description },
+    { name: "twitter:card", content: "summary" },
+    { name: "twitter:title", content: config.title },
+    { name: "twitter:description", content: config.description },
+    ...(canonical
+      ? [
+          { property: "og:url", content: canonical },
+          {
+            tagName: "link" as const,
+            rel: "canonical",
+            href: canonical,
+          },
+        ]
+      : []),
+    {
+      "script:ld+json": {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        name: config.title,
+        description: config.description,
+        ...(config.siteUrl ? { url: config.siteUrl } : {}),
+      },
+    },
+  ];
+};
+
+export const links: LinksFunction = () => [
+  { rel: "icon", href: "/favicon.ico", sizes: "any" },
+  { rel: "icon", href: "/favicon.svg", type: "image/svg+xml" },
+  {
+    rel: "icon",
+    href: "/favicon-96x96.png",
+    sizes: "96x96",
+    type: "image/png",
+  },
+  {
+    rel: "apple-touch-icon",
+    href: "/apple-touch-icon.png",
+    sizes: "180x180",
+  },
+  { rel: "manifest", href: "/site.webmanifest" },
+  ...(config.groups.some((group) => group.type === "changelog")
+    ? [
+        {
+          rel: "alternate",
+          href: "/rss.xml",
+          type: "application/rss+xml",
+          title: `${config.title} updates`,
+        },
+      ]
+    : []),
+];
+
+export function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="color-scheme" content="light dark" />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: getThemeScript(THEME_STORAGE_KEY, config.mode),
+          }}
+        />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <ThemeProvider
+          defaultTheme={config.mode}
+          storageKey={THEME_STORAGE_KEY}
+        >
+          {children}
+          <ScrollRestoration />
+          <Scripts />
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  return <Outlet />;
+}
+
+const MARKDOWN_RESOURCE_PREFIX = "/__heyo-docs/markdown";
+
+/**
+ * Follows the Fumadocs React Router pattern: Markdown needs a resource route,
+ * while this middleware keeps the public URL as `/<page>.md`.
+ */
+const markdownMiddleware: Route.MiddlewareFunction = async (
+  { request },
+  next,
+) => {
+  const url = new URL(request.url);
+  if (
+    !url.pathname.startsWith(`${MARKDOWN_RESOURCE_PREFIX}/`) &&
+    pathnameFromMarkdownPath(url.pathname) !== undefined
+  ) {
+    const target = new URL(
+      `${MARKDOWN_RESOURCE_PREFIX}${url.pathname}${url.search}`,
+      url,
+    );
+    return Response.redirect(target, 307);
+  }
+  return next();
+};
+
+export const middleware = [markdownMiddleware];

package/templates/react-router/app/routes/docs.tsx

@@ -0,0 +1,179 @@
+import {
+  createDocsModel,
+  DocsApp,
+  findDocsPage,
+  findOpenApiEndpoint,
+  openApiEndpointDataPath,
+  openApiEndpointDetail,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+import {
+  Link,
+  useLoaderData,
+  useParams,
+  type LoaderFunctionArgs,
+  type MetaFunction,
+} from "react-router";
+import { forwardRef, type ComponentPropsWithoutRef } from "react";
+
+import config from "../../heyo-docs.config";
+import { iconSet } from "../heyo-docs-icons";
+import { useTheme } from "../components/theme-provider";
+import { pages } from "virtual:heyo-docs-content";
+import { openApiDocuments } from "virtual:heyo-docs-openapi";
+import { openApiEndpoints } from "virtual:heyo-docs-openapi/index";
+
+function pathnameFor(params: Record<string, string | undefined>): string {
+  const path = params["*"]?.replace(/^\/+|\/+$/g, "");
+  return path ? `/${path}` : "/";
+}
+
+const RouterLink = forwardRef<HTMLAnchorElement, ComponentPropsWithoutRef<"a">>(
+  function RouterLink({ href = "/", ...props }, ref) {
+    return <Link {...props} ref={ref} to={href} />;
+  },
+);
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const pathname = pathnameFor(params);
+  const model = createDocsModel(config, pages, [], openApiEndpoints);
+  const page = findDocsPage(model.pages, pathname);
+  const endpoint = findOpenApiEndpoint(model.endpoints, pathname);
+  if (!page && !endpoint) throw new Response("Not Found", { status: 404 });
+
+  if (!endpoint) return {};
+
+  // Prerendering serialises this operation-specific data with its static route,
+  // so the browser's first paint already contains the complete API reference.
+  if (typeof window === "undefined") {
+    const serverModel = createDocsModel(config, pages, openApiDocuments);
+    const currentOpenApiEndpoint = findOpenApiEndpoint(
+      serverModel.endpoints,
+      pathname,
+    );
+    return {
+      currentOpenApiEndpoint: currentOpenApiEndpoint
+        ? openApiEndpointDetail(currentOpenApiEndpoint)
+        : undefined,
+    };
+  }
+
+  // Client transitions wait for the static shard before committing the new
+  // route. This prevents rendering the compact index and replacing it later.
+  const response = await fetch(openApiEndpointDataPath(endpoint.slug));
+  if (!response.ok)
+    throw new Response("OpenAPI endpoint data could not be loaded", {
+      status: response.status,
+    });
+  return {
+    currentOpenApiEndpoint: (await response.json()) as OpenApiEndpoint,
+  };
+}
+
+export const meta: MetaFunction = ({ params }) => {
+  const model = createDocsModel(config, pages, [], openApiEndpoints);
+  const pathname = pathnameFor(params);
+  const page = findDocsPage(model.pages, pathname);
+  const endpoint = findOpenApiEndpoint(model.endpoints, pathname);
+  if (!page && !endpoint)
+    return [
+      { title: `Not found | ${config.title}` },
+      { name: "robots", content: "noindex" },
+    ];
+  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 =
+    page?.seo.canonical ??
+    (config.siteUrl ? `${config.siteUrl}${pathname}` : undefined);
+  return [
+    { title },
+    { name: "description", content: description },
+    { name: "robots", content: "index, follow" },
+    { property: "og:type", content: "article" },
+    { property: "og:site_name", content: config.title },
+    { property: "og:title", content: title },
+    { property: "og:description", content: description },
+    { name: "twitter:card", content: "summary" },
+    { name: "twitter:title", content: title },
+    { name: "twitter:description", content: description },
+    ...(canonical
+      ? [
+          { property: "og:url", content: canonical },
+          {
+            tagName: "link" as const,
+            rel: "canonical",
+            href: canonical,
+          },
+        ]
+      : []),
+    {
+      "script:ld+json": [
+        {
+          "@context": "https://schema.org",
+          "@type": "WebSite",
+          name: config.title,
+          description: config.description,
+          ...(config.siteUrl ? { url: config.siteUrl } : {}),
+        },
+        {
+          "@context": "https://schema.org",
+          "@type": "TechArticle",
+          headline: page?.title ?? endpoint!.title,
+          description,
+          ...(canonical ? { url: canonical } : {}),
+          isPartOf: {
+            "@type": "WebSite",
+            name: config.title,
+            ...(config.siteUrl ? { url: config.siteUrl } : {}),
+          },
+        },
+      ],
+    },
+  ];
+};
+
+export default function DocsRoute() {
+  const { currentOpenApiEndpoint } = useLoaderData<typeof loader>();
+  return (
+    <DocsShell
+      currentOpenApiEndpoint={currentOpenApiEndpoint}
+      pathname={pathnameFor(useParams())}
+    />
+  );
+}
+
+function DocsShell({
+  currentOpenApiEndpoint,
+  pathname,
+}: {
+  currentOpenApiEndpoint?: OpenApiEndpoint;
+  pathname: string;
+}) {
+  const { mounted, resolvedTheme, setTheme } = useTheme();
+
+  return (
+    <DocsApp
+      config={config}
+      currentOpenApiEndpoint={currentOpenApiEndpoint}
+      iconSet={iconSet}
+      link={RouterLink}
+      openApiEndpoints={openApiEndpoints}
+      openApiRequestUrl="/heyo-docs-internal/openapi-request"
+      pages={pages}
+      pathname={pathname}
+      isDark={mounted ? resolvedTheme === "dark" : undefined}
+      onThemeToggle={
+        mounted
+          ? () => setTheme(resolvedTheme === "dark" ? "light" : "dark")
+          : undefined
+      }
+    />
+  );
+}
+
+export function ErrorBoundary() {
+  return <DocsShell pathname="/__not-found" />;
+}

package/templates/react-router/app/routes/home.tsx

@@ -0,0 +1 @@
+export { default, loader, meta, ErrorBoundary } from "./docs";

package/templates/react-router/app/routes/llms-full.ts

@@ -0,0 +1,13 @@
+import { llmsFull } from "@heyo-sh/heyo-docs";
+import type { LoaderFunctionArgs } from "react-router";
+
+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 function loader({ request }: LoaderFunctionArgs) {
+  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/react-router/app/routes/llms.ts

@@ -0,0 +1,13 @@
+import { llmsIndex } from "@heyo-sh/heyo-docs";
+import type { LoaderFunctionArgs } from "react-router";
+
+import config from "../../heyo-docs.config";
+import { pages } from "virtual:heyo-docs-content/server";
+
+/** A concise, discoverable index of every documentation page. */
+export function loader({ request }: LoaderFunctionArgs) {
+  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/react-router/app/routes/markdown.ts

@@ -0,0 +1,25 @@
+import { markdownForPage, pathnameFromMarkdownPath } from "@heyo-sh/heyo-docs";
+import type { LoaderFunctionArgs } from "react-router";
+
+import { pages } from "virtual:heyo-docs-content/server";
+
+/**
+ * Resource route used by the root middleware to serve `*.md` paths. Keeping
+ * it route-only makes React Router send the Response body directly.
+ */
+export function loader({ params }: LoaderFunctionArgs) {
+  const pagePathname = pathnameFromMarkdownPath(`/${params["*"] ?? ""}`);
+  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/react-router/app/routes/openapi-request.ts

@@ -0,0 +1,159 @@
+import {
+  createDocsModel,
+  findOpenApiEndpoint,
+  type OpenApiEndpoint,
+} from "@heyo-sh/heyo-docs";
+import type { ActionFunctionArgs } from "react-router";
+
+import config from "../../heyo-docs.config";
+import { pages } from "virtual:heyo-docs-content";
+import { openApiDocuments } from "virtual:heyo-docs-openapi";
+
+interface OpenApiRequestPayload {
+  bearerToken: string;
+  body?: string;
+  endpointSlug: string;
+  parameters: Record<string, string>;
+  server: string;
+}
+
+/**
+ * Sends documented API calls from the server, so browsers do not need the API
+ * to expose CORS headers. Targets are limited to servers from the OpenAPI file.
+ */
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method !== "POST")
+    return new Response("Method Not Allowed", {
+      headers: { Allow: "POST" },
+      status: 405,
+    });
+
+  const payload = await requestPayload(request);
+  if (!payload)
+    return new Response("Invalid OpenAPI request.", { status: 400 });
+
+  const model = createDocsModel(config, pages, openApiDocuments);
+  const endpoint = findOpenApiEndpoint(model.endpoints, payload.endpointSlug);
+  if (!endpoint) return new Response("Endpoint not found.", { status: 404 });
+  if (endpoint.servers.length && !endpoint.servers.includes(payload.server))
+    return new Response("API server is not declared in the OpenAPI schema.", {
+      status: 400,
+    });
+  if (!endpoint.servers.length && payload.server)
+    return new Response("This endpoint does not declare an API server.", {
+      status: 400,
+    });
+
+  const headers = requestHeaders(
+    endpoint,
+    payload.parameters,
+    payload.bearerToken,
+  );
+  const url = requestUrl(
+    endpoint,
+    payload.server,
+    payload.parameters,
+    request.url,
+  );
+
+  try {
+    const response = await fetch(url, {
+      method: endpoint.method.toUpperCase(),
+      headers,
+      body: payload.body,
+    });
+    const responseHeaders = new Headers();
+    const contentType = response.headers.get("content-type");
+    if (contentType) responseHeaders.set("content-type", contentType);
+    const body = [204, 205, 304].includes(response.status)
+      ? null
+      : await response.arrayBuffer();
+    return new Response(body, {
+      headers: responseHeaders,
+      status: response.status,
+      statusText: response.statusText,
+    });
+  } catch {
+    return new Response("The API server could not be reached.", {
+      status: 502,
+    });
+  }
+}
+
+async function requestPayload(
+  request: Request,
+): Promise<OpenApiRequestPayload | undefined> {
+  try {
+    const value: unknown = await request.json();
+    if (!isRecord(value)) return undefined;
+    const endpointSlug = stringValue(value.endpointSlug);
+    const server = stringValue(value.server);
+    if (!endpointSlug || server === undefined) return undefined;
+    return {
+      bearerToken: stringValue(value.bearerToken) ?? "",
+      body: stringValue(value.body),
+      endpointSlug,
+      parameters: stringRecord(value.parameters),
+      server,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function requestUrl(
+  endpoint: OpenApiEndpoint,
+  server: string,
+  parameters: Record<string, string>,
+  requestUrl: string,
+) {
+  let path = endpoint.path.replace(/\{([^}]+)\}/g, (match, name: string) => {
+    const value = parameters[`path:${name}`];
+    return value ? encodeURIComponent(value) : match;
+  });
+  const query = new URLSearchParams();
+  for (const parameter of endpoint.parameters) {
+    if (parameter.in !== "query") continue;
+    const value = parameters[`query:${parameter.name}`];
+    if (value) query.set(parameter.name, value);
+  }
+  const search = query.toString();
+  path = `${path}${search ? `?${search}` : ""}`;
+  return server
+    ? `${server.replace(/\/$/, "")}${path}`
+    : new URL(path, requestUrl).toString();
+}
+
+function requestHeaders(
+  endpoint: OpenApiEndpoint,
+  parameters: Record<string, string>,
+  bearerToken: string,
+) {
+  const headers = new Headers();
+  for (const parameter of endpoint.parameters) {
+    if (parameter.in !== "header") continue;
+    const value = parameters[`header:${parameter.name}`];
+    if (value) headers.set(parameter.name, value);
+  }
+  if (endpoint.requestBody?.contentType)
+    headers.set("Content-Type", endpoint.requestBody.contentType);
+  if (bearerToken) headers.set("Authorization", `Bearer ${bearerToken}`);
+  return headers;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringRecord(value: unknown): Record<string, string> {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}

package/templates/react-router/app/routes/page.tsx

@@ -0,0 +1 @@
+export { default, loader, meta, ErrorBoundary } from "./docs";

package/templates/react-router/app/routes/robots.ts

@@ -0,0 +1,19 @@
+import type { Route } from "./+types/robots";
+
+import config from "../../heyo-docs.config";
+
+export function loader({ request }: Route.LoaderArgs) {
+  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/react-router/app/routes/rss.ts

@@ -0,0 +1,13 @@
+import { rssXml } from "@heyo-sh/heyo-docs";
+import type { LoaderFunctionArgs } from "react-router";
+
+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 function loader({ request }: LoaderFunctionArgs) {
+  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/react-router/app/routes/sitemap.ts

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

package/templates/react-router/app/routes.ts

@@ -0,0 +1,13 @@
+import { index, route, type RouteConfig } from "@react-router/dev/routes";
+
+export default [
+  index("routes/home.tsx"),
+  route("robots.txt", "routes/robots.ts"),
+  route("sitemap.xml", "routes/sitemap.ts"),
+  route("rss.xml", "routes/rss.ts"),
+  route("llms.txt", "routes/llms.ts"),
+  route("llms-full.txt", "routes/llms-full.ts"),
+  route("__heyo-docs/markdown/*", "routes/markdown.ts"),
+  route("heyo-docs-internal/openapi-request", "routes/openapi-request.ts"),
+  route("*", "routes/page.tsx"),
+] satisfies RouteConfig;

package/templates/react-router/app/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/react-router/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-mira",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/app.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "remixicon",
+  "rtl": false,
+  "aliases": {
+    "components": "~/components",
+    "utils": "~/lib/utils",
+    "ui": "~/components/ui",
+    "lib": "~/lib",
+    "hooks": "~/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/templates/react-router/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.