@lukoweb/apitogo 0.2.15 → 0.2.17

package/package.json

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

package/src/config/v2/docs-navigation.ts

@@ -0,0 +1,72 @@
+import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
+
+/** Label of the one header tab that holds the sidebar made from the docs pages. */
+export const DOCS_NAVIGATION_LABEL = "Documentation";
+
+type Branch = { pages: Set<string>; folders: Map<string, Branch> };
+
+const emptyBranch = (): Branch => ({ pages: new Set(), folders: new Map() });
+
+/** "getting-started" becomes "Getting started". */
+export function folderLabel(name: string): string {
+  const words = name.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+const byName = (a: string, b: string) => a.localeCompare(b);
+
+const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
+  const pages = [...branch.pages].sort((a, b) =>
+    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
+  );
+  const folders = [...branch.folders.keys()].sort(byName);
+  return [
+    // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
+    ...pages.map(
+      (page): InputNavigationItem =>
+        page === "index"
+          ? {
+              type: "doc",
+              file: `${prefix}${page}`,
+              path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`,
+            }
+          : `${prefix}${page}`,
+    ),
+    ...folders.map(
+      (folder): InputNavigationItem => ({
+        type: "category",
+        label: folderLabel(folder),
+        collapsible: true,
+        collapsed: false,
+        items: toItems(
+          branch.folders.get(folder) ?? emptyBranch(),
+          `${prefix}${folder}/`,
+        ),
+      }),
+    ),
+  ];
+};
+
+/**
+ * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
+ * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`).
+ * Without pages there is nothing to navigate, so the result is empty.
+ */
+export function docsNavigation(routes: string[]): InputNavigationItem[] {
+  const root = emptyBranch();
+  for (const route of routes) {
+    const parts = route.split("/").filter(Boolean);
+    const page = parts.pop();
+    if (!page) continue;
+    const branch = parts.reduce((current, folder) => {
+      const next = current.folders.get(folder) ?? emptyBranch();
+      current.folders.set(folder, next);
+      return next;
+    }, root);
+    branch.pages.add(page);
+  }
+  const items = toItems(root, "");
+  return items.length === 0
+    ? []
+    : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];
+}

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

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { glob } from "glob";
+import globParent from "glob-parent";
+import { readFrontmatter } from "../../lib/util/readFrontmatter.js";
+
+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[],
+  options: { includeDrafts?: boolean } = {},
+): 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);
+      // The docs plugin leaves draft pages out of a production build, so the routes must too.
+      const published = options.includeDrafts
+        ? files
+        : (
+            await Promise.all(
+              files.map(async (file) => ({
+                file,
+                draft: (await readFrontmatter(file)).data.draft === true,
+              })),
+            )
+          )
+            .filter(({ draft }) => !draft)
+            .map(({ file }) => file);
+      return published.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

@@ -1,10 +1,12 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { docsNavigation } from "./docs-navigation.js";
 import { ConfigError, type ConfigIssue } from "./errors.js";
 import {
   ReferenceSpecError,
   renderReferenceSpec,
 } from "./gateway-reference.js";
+import { docRoutes, type HomeRedirect, homeRedirect } from "./home-redirect.js";
 import {
   hasCapability,
   missingManifestServices,
@@ -243,8 +245,23 @@ export function buildSiteConfig(
   resolved: ResolvedConfigV2,
   plan: PortalPlan,
   theme?: unknown,
+  extras: { redirects?: HomeRedirect[]; docsNavigation?: unknown[] } = {},
 ): Record<string, unknown> {
   const portal = resolved.portal;
+  const redirects = extras.redirects ?? [];
+  // One header tab for the docs sidebar, and the API reference as a link next to it.
+  const navigation = [
+    ...(extras.docsNavigation ?? []),
+    ...(plan.apiReference
+      ? [
+          {
+            type: "link",
+            to: `/${API_REFERENCE_PATH}`,
+            label: "API Reference",
+          },
+        ]
+      : []),
+  ];
   return {
     site: {
       title: portal?.name ?? resolved.project.name,
@@ -274,15 +291,10 @@ export function buildSiteConfig(
               path: API_REFERENCE_PATH,
             },
           ],
-          navigation: [
-            {
-              type: "link",
-              to: `/${API_REFERENCE_PATH}`,
-              label: "API Reference",
-            },
-          ],
         }
       : {}),
+    ...(navigation.length > 0 ? { navigation } : {}),
+    ...(redirects.length > 0 ? { redirects } : {}),
     ...(theme !== undefined ? { theme } : {}),
     ...(plan.auth ? { authentication: { type: "openid", ...plan.auth } } : {}),
     ...(plan.preview ? { preview: true } : {}),
@@ -430,7 +442,27 @@ export async function preparePortal(
       });
     }
   }
-  const siteConfig = buildSiteConfig(resolved, plan, await readTheme(resolved));
+  const hostedDocRoutes = plan.docs
+    ? await docRoutes(profile.docs.content, {
+        includeDrafts: mode === "development",
+      })
+    : [];
+  const home = homeRedirect({
+    hostsDocs: plan.docs,
+    docRoutes: hostedDocRoutes,
+    externalDocsUrl: profile.docs.url,
+    apiReferencePath: plan.apiReference ? `/${API_REFERENCE_PATH}` : undefined,
+    userPanel: plan.userPanel,
+  });
+  const siteConfig = buildSiteConfig(
+    resolved,
+    plan,
+    await readTheme(resolved),
+    {
+      redirects: home ? [home] : [],
+      docsNavigation: docsNavigation(hostedDocRoutes),
+    },
+  );
   const wrapper = renderWrapper(plan);
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
   if (options.write !== false) {