@lukoweb/apitogo 0.2.15 → 0.2.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/home-redirect.ts

@@ -0,0 +1,81 @@
+import path from "node:path";
+import { glob } from "glob";
+import globParent from "glob-parent";
+
+export type HomeRedirect = { from: string; to: string };
+
+const IGNORED = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+
+/**
+ * The routes the docs plugin gives the pages these globs match: the path inside the glob's folder, without the
+ * extension. Missing folders and negated globs are fine, they just match nothing.
+ */
+export async function docRoutes(patterns: string[]): Promise<string[]> {
+  const excluded = patterns
+    .filter((pattern) => pattern.startsWith("!"))
+    .map((pattern) => pattern.slice(1));
+  const included = patterns.filter((pattern) => !pattern.startsWith("!"));
+
+  const routes = await Promise.all(
+    included.map(async (pattern) => {
+      const files = await glob(pattern, {
+        absolute: true,
+        posix: true,
+        ignore: [...IGNORED, ...excluded],
+      });
+      const parent = globParent(pattern);
+      return files.map(
+        (file) =>
+          `/${path.posix.relative(parent, file).replace(/\.mdx?$/, "")}`,
+      );
+    }),
+  );
+  return [...new Set(routes.flat())].sort();
+}
+
+/** The page a visitor lands on when the site has no home page: the top-most page, then the first by name. */
+export function pickLandingRoute(routes: string[]): string | undefined {
+  const depth = (route: string) => route.split("/").length;
+  return [...routes].sort(
+    (a, b) => depth(a) - depth(b) || a.localeCompare(b),
+  )[0];
+}
+
+export type HomeRedirectInput = {
+  /** APItoGo builds the docs pages. */
+  hostsDocs: boolean;
+  /** Routes of those pages (see `docRoutes`). */
+  docRoutes: string[];
+  /** Where the docs live when someone else hosts them. */
+  externalDocsUrl?: string;
+  /** The portal has an API reference page, at this path. */
+  apiReferencePath?: string;
+  /** The portal has console pages (sign-in, keys, plans). */
+  userPanel: boolean;
+};
+
+/**
+ * Where `/` should go when the portal has no page of its own there. Without this a visitor of the home page sees
+ * "Page not found".
+ *
+ * - Hosted docs without an index page: the first page, so the team's own docs never need an extra file.
+ * - Hosted docs without any page: the API reference, when there is one.
+ * - External docs and no console: the external docs site, as the portal has nothing else to show.
+ */
+export function homeRedirect(
+  input: HomeRedirectInput,
+): HomeRedirect | undefined {
+  if (input.hostsDocs) {
+    if (input.docRoutes.some((route) => route === "/" || route === "/index"))
+      return undefined;
+    const landing = pickLandingRoute(input.docRoutes);
+    if (landing) return { from: "/", to: landing };
+    return input.apiReferencePath
+      ? { from: "/", to: input.apiReferencePath }
+      : undefined;
+  }
+  if (input.externalDocsUrl && !input.userPanel) {
+    return { from: "/", to: input.externalDocsUrl };
+  }
+  return undefined;
+}

package/src/config/v2/wrapper.ts

@@ -5,6 +5,7 @@ import {
   ReferenceSpecError,
   renderReferenceSpec,
 } from "./gateway-reference.js";
+import { docRoutes, type HomeRedirect, homeRedirect } from "./home-redirect.js";
 import {
   hasCapability,
   missingManifestServices,
@@ -243,6 +244,7 @@ export function buildSiteConfig(
   resolved: ResolvedConfigV2,
   plan: PortalPlan,
   theme?: unknown,
+  redirects: HomeRedirect[] = [],
 ): Record<string, unknown> {
   const portal = resolved.portal;
   return {
@@ -283,6 +285,7 @@ export function buildSiteConfig(
           ],
         }
       : {}),
+    ...(redirects.length > 0 ? { redirects } : {}),
     ...(theme !== undefined ? { theme } : {}),
     ...(plan.auth ? { authentication: { type: "openid", ...plan.auth } } : {}),
     ...(plan.preview ? { preview: true } : {}),
@@ -430,7 +433,19 @@ export async function preparePortal(
       });
     }
   }
-  const siteConfig = buildSiteConfig(resolved, plan, await readTheme(resolved));
+  const home = homeRedirect({
+    hostsDocs: plan.docs,
+    docRoutes: plan.docs ? await docRoutes(profile.docs.content) : [],
+    externalDocsUrl: profile.docs.url,
+    apiReferencePath: plan.apiReference ? `/${API_REFERENCE_PATH}` : undefined,
+    userPanel: plan.userPanel,
+  });
+  const siteConfig = buildSiteConfig(
+    resolved,
+    plan,
+    await readTheme(resolved),
+    home ? [home] : [],
+  );
   const wrapper = renderWrapper(plan);
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
   if (options.write !== false) {