@lukoweb/apitogo 0.2.14 → 0.2.16

package/dist/declarations/lib/plugins/markdown/index.d.ts

@@ -31,4 +31,5 @@ export type MDXImport = {
     __filepath: string;
     default: (props: MDXProps) => JSX.Element;
 };
+export declare const withIndexAliases: <T>(fileImports: Record<string, T>) => [string, T][];
 export declare const markdownPlugin: (options: MarkdownPluginOptions) => ApitogoPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.14",
+  "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) {

package/src/lib/plugins/markdown/index.tsx

@@ -35,11 +35,31 @@ export type MDXImport = {
   default: (props: MDXProps) => JSX.Element;
 };
 
+const INDEX_SUFFIX = "/index";
+
+// `index.mdx` is the page of its folder: `/index` also answers at `/`, `/guides/index` at `/guides`.
+// Without this the browser has no route for `/` (the pre-built index.html only hides that on first load).
+export const withIndexAliases = <T,>(
+  fileImports: Record<string, T>,
+): [string, T][] => {
+  const entries = Object.entries(fileImports);
+  return entries.flatMap(([routePath, value]): [string, T][] => {
+    if (!routePath.endsWith(INDEX_SUFFIX)) return [[routePath, value]];
+    const alias = routePath.slice(0, -INDEX_SUFFIX.length) || "/";
+    return alias in fileImports
+      ? [[routePath, value]]
+      : [
+          [routePath, value],
+          [alias, value],
+        ];
+  });
+};
+
 export const markdownPlugin = (
   options: MarkdownPluginOptions,
 ): ApitogoPlugin => ({
   getRoutes: () => {
-    return Object.entries(options.fileImports).map(
+    return withIndexAliases(options.fileImports).map(
       ([routePath, importPromise]) => ({
         path: routePath,
         lazy: async () => {