@lukoweb/apitogo 0.2.16 → 0.2.18

package/dist/declarations/cli/platform/helpers/npm-build.d.ts

@@ -12,6 +12,10 @@ export interface NpmInstallResult {
     durationMs: number;
     installLog: string;
 }
+export declare function runNpmCommand(args: string[], cwd: string): Promise<{
+    durationMs: number;
+    log: string;
+}>;
 export declare function runNpmInstall(sourceDirectory: string, options?: {
     nodeVersion?: string;
 }): Promise<NpmInstallResult>;

package/package.json

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

@@ -1,6 +1,7 @@
 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 };
 
@@ -10,7 +11,10 @@ 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[]> {
+export async function docRoutes(
+  patterns: string[],
+  options: { includeDrafts?: boolean } = {},
+): Promise<string[]> {
   const excluded = patterns
     .filter((pattern) => pattern.startsWith("!"))
     .map((pattern) => pattern.slice(1));
@@ -24,7 +28,20 @@ export async function docRoutes(patterns: string[]): Promise<string[]> {
         ignore: [...IGNORED, ...excluded],
       });
       const parent = globParent(pattern);
-      return files.map(
+      // 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?$/, "")}`,
       );

package/src/config/v2/wrapper.ts

@@ -1,5 +1,6 @@
 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,
@@ -244,9 +245,23 @@ export function buildSiteConfig(
   resolved: ResolvedConfigV2,
   plan: PortalPlan,
   theme?: unknown,
-  redirects: HomeRedirect[] = [],
+  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,
@@ -276,15 +291,9 @@ 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 } } : {}),
@@ -433,9 +442,14 @@ export async function preparePortal(
       });
     }
   }
+  const hostedDocRoutes = plan.docs
+    ? await docRoutes(profile.docs.content, {
+        includeDrafts: mode === "development",
+      })
+    : [];
   const home = homeRedirect({
     hostsDocs: plan.docs,
-    docRoutes: plan.docs ? await docRoutes(profile.docs.content) : [],
+    docRoutes: hostedDocRoutes,
     externalDocsUrl: profile.docs.url,
     apiReferencePath: plan.apiReference ? `/${API_REFERENCE_PATH}` : undefined,
     userPanel: plan.userPanel,
@@ -444,7 +458,10 @@ export async function preparePortal(
     resolved,
     plan,
     await readTheme(resolved),
-    home ? [home] : [],
+    {
+      redirects: home ? [home] : [],
+      docsNavigation: docsNavigation(hostedDocRoutes),
+    },
   );
   const wrapper = renderWrapper(plan);
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);