@lukoweb/apitogo 0.2.16 → 0.2.17

package/dist/cli/cli.js

@@ -7699,15 +7699,84 @@ function stableJson(value) {
 }
 
 // src/config/v2/wrapper.ts
-import { mkdir as mkdir4, readFile as readFile5, rename as rename2, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
+import { mkdir as mkdir4, readFile as readFile6, rename as rename2, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
 import path12 from "node:path";
 
+// src/config/v2/docs-navigation.ts
+var DOCS_NAVIGATION_LABEL = "Documentation";
+var emptyBranch = () => ({ pages: /* @__PURE__ */ new Set(), folders: /* @__PURE__ */ new Map() });
+function folderLabel(name) {
+  const words = name.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+var byName = (a, b) => a.localeCompare(b);
+var toItems = (branch, prefix) => {
+  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) => page === "index" ? {
+        type: "doc",
+        file: `${prefix}${page}`,
+        path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`
+      } : `${prefix}${page}`
+    ),
+    ...folders.map(
+      (folder) => ({
+        type: "category",
+        label: folderLabel(folder),
+        collapsible: true,
+        collapsed: false,
+        items: toItems(
+          branch.folders.get(folder) ?? emptyBranch(),
+          `${prefix}${folder}/`
+        )
+      })
+    )
+  ];
+};
+function docsNavigation(routes) {
+  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 }];
+}
+
 // src/config/v2/home-redirect.ts
 import path11 from "node:path";
 import { glob as glob2 } from "glob";
 import globParent from "glob-parent";
+
+// src/lib/util/readFrontmatter.ts
+import { readFile as readFile5 } from "node:fs/promises";
+import matter from "gray-matter";
+import { parse as parse2, stringify } from "yaml";
+var yaml = {
+  parse: (input5) => parse2(input5) ?? {},
+  stringify: (obj) => stringify(obj)
+};
+var readFrontmatter = async (filePath) => {
+  const content = await readFile5(filePath, "utf-8");
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+  return matter(normalizedContent, { engines: { yaml } });
+};
+
+// src/config/v2/home-redirect.ts
 var IGNORED = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
-async function docRoutes(patterns) {
+async function docRoutes(patterns, options = {}) {
   const excluded = patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1));
   const included = patterns.filter((pattern) => !pattern.startsWith("!"));
   const routes = await Promise.all(
@@ -7718,7 +7787,13 @@ async function docRoutes(patterns) {
         ignore: [...IGNORED, ...excluded]
       });
       const parent = globParent(pattern);
-      return files.map(
+      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) => `/${path11.posix.relative(parent, file).replace(/\.mdx?$/, "")}`
       );
     })
@@ -7875,8 +7950,19 @@ function planPortal(profile, manifest) {
 var SITE_CONFIG_FILE = "apitogo.config.json";
 var REFERENCE_SPEC_FILE = "openapi/gateway.json";
 var API_REFERENCE_PATH = "api";
-function buildSiteConfig(resolved, plan2, theme, redirects = []) {
+function buildSiteConfig(resolved, plan2, theme, extras = {}) {
   const portal = resolved.portal;
+  const redirects = extras.redirects ?? [];
+  const navigation = [
+    ...extras.docsNavigation ?? [],
+    ...plan2.apiReference ? [
+      {
+        type: "link",
+        to: `/${API_REFERENCE_PATH}`,
+        label: "API Reference"
+      }
+    ] : []
+  ];
   return {
     site: {
       title: portal?.name ?? resolved.project.name,
@@ -7900,15 +7986,9 @@ function buildSiteConfig(resolved, plan2, theme, redirects = []) {
           input: `./${REFERENCE_SPEC_FILE}`,
           path: API_REFERENCE_PATH
         }
-      ],
-      navigation: [
-        {
-          type: "link",
-          to: `/${API_REFERENCE_PATH}`,
-          label: "API Reference"
-        }
       ]
     } : {},
+    ...navigation.length > 0 ? { navigation } : {},
     ...redirects.length > 0 ? { redirects } : {},
     ...theme !== void 0 ? { theme } : {},
     ...plan2.auth ? { authentication: { type: "openid", ...plan2.auth } } : {},
@@ -7943,7 +8023,7 @@ async function readTheme(resolved) {
   const file = resolved.portal?.theme;
   if (!file) return void 0;
   try {
-    return JSON.parse(await readFile5(file, "utf8"));
+    return JSON.parse(await readFile6(file, "utf8"));
   } catch {
     return void 0;
   }
@@ -8001,9 +8081,12 @@ async function preparePortal(resolved, manifest, mode, options = {}) {
       });
     }
   }
+  const hostedDocRoutes = plan2.docs ? await docRoutes(profile.docs.content, {
+    includeDrafts: mode === "development"
+  }) : [];
   const home = homeRedirect({
     hostsDocs: plan2.docs,
-    docRoutes: plan2.docs ? await docRoutes(profile.docs.content) : [],
+    docRoutes: hostedDocRoutes,
     externalDocsUrl: profile.docs.url,
     apiReferencePath: plan2.apiReference ? `/${API_REFERENCE_PATH}` : void 0,
     userPanel: plan2.userPanel
@@ -8012,7 +8095,10 @@ async function preparePortal(resolved, manifest, mode, options = {}) {
     resolved,
     plan2,
     await readTheme(resolved),
-    home ? [home] : []
+    {
+      redirects: home ? [home] : [],
+      docsNavigation: docsNavigation(hostedDocRoutes)
+    }
   );
   const wrapper = renderWrapper(plan2);
   const wrapperPath = path12.join(resolved.state.generatedDir, WRAPPER_FILE);
@@ -8057,7 +8143,7 @@ async function preparePortal(resolved, manifest, mode, options = {}) {
 
 // src/config/v2/workspace.ts
 import { createHash as createHash2 } from "node:crypto";
-import { access as access2, lstat, readFile as readFile6, rm as rm3, symlink } from "node:fs/promises";
+import { access as access2, lstat, readFile as readFile7, rm as rm3, symlink } from "node:fs/promises";
 import path13 from "node:path";
 import { glob as glob3 } from "glob";
 var exists2 = (file) => access2(file).then(
@@ -8086,7 +8172,7 @@ async function materializeWorkspace(resolved, prepared) {
   return root;
 }
 async function configFingerprint(configPath) {
-  const text = await readFile6(configPath, "utf8");
+  const text = await readFile7(configPath, "utf8");
   try {
     const raw = JSON.parse(text);
     if (raw.project) {
@@ -8135,7 +8221,7 @@ async function portalArtifactHash(resolved, manifestText, cliVersion, wrapper =
   for (const file of files) {
     hash2.update(`file:${path13.relative(resolved.configDir, file)}
 `);
-    hash2.update(await readFile6(file));
+    hash2.update(await readFile7(file));
   }
   return hash2.digest("hex");
 }
@@ -8602,7 +8688,7 @@ async function clearProjectId(dir, projectId) {
 
 // src/config/v2/ledger.ts
 init_invariant();
-import { mkdir as mkdir6, readFile as readFile7, rename as rename4, rm as rm5, writeFile as writeFile7 } from "node:fs/promises";
+import { mkdir as mkdir6, readFile as readFile8, rename as rename4, rm as rm5, writeFile as writeFile7 } from "node:fs/promises";
 import path15 from "node:path";
 var LEDGER_VERSION = 1;
 var LedgerError = class extends ApitogoError {
@@ -8619,7 +8705,7 @@ var emptyLedger = () => ({
 async function readLedger(state) {
   let text;
   try {
-    text = await readFile7(state.file, "utf8");
+    text = await readFile8(state.file, "utf8");
   } catch (error) {
     if (error.code === "ENOENT")
       return emptyLedger();
@@ -9721,7 +9807,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.16",
+  version: "0.2.17",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -11507,7 +11593,7 @@ var lookup = (schema2, path101, filePath) => {
   }
   return val;
 };
-var stringify = (obj, indent = 2) => JSON.stringify(obj, null, indent);
+var stringify2 = (obj, indent = 2) => JSON.stringify(obj, null, indent);
 var generateCode = (schema2, filePath) => {
   const { refMap, siblingsMap } = createLocalRefMap(schema2);
   const lines = [];
@@ -11524,7 +11610,7 @@ var generateCode = (schema2, filePath) => {
     mergedRefs.set(uniqueKey, varName);
     lines.push(`const ${varName} = {};`);
   }
-  const toCode = (obj) => replaceMarkers(stringify(setRefMarkers(obj, refMap)), mergedRefs);
+  const toCode = (obj) => replaceMarkers(stringify2(setRefMarkers(obj, refMap)), mergedRefs);
   const deferred = [];
   for (const [refPath, index] of refMap) {
     const value = lookup(schema2, refPath, filePath);
@@ -11535,7 +11621,7 @@ var generateCode = (schema2, filePath) => {
     const siblingEntry = value.__uniqueRefKey && siblingsMap.get(value.__uniqueRefKey);
     const target = siblingEntry ? deferred : lines;
     target.push(
-      siblingEntry ? `Object.assign(__refs[${index}], __refMap["${siblingEntry.refPath}"], ${stringify(siblingEntry.siblings)});` : `Object.assign(__refs[${index}], ${toCode(value)});`,
+      siblingEntry ? `Object.assign(__refs[${index}], __refMap["${siblingEntry.refPath}"], ${stringify2(siblingEntry.siblings)});` : `Object.assign(__refs[${index}], ${toCode(value)});`,
       `Object.defineProperty(__refs[${index}], "__$ref", { value: __refMapPaths[${index}], enumerable: false });`
     );
   }
@@ -11544,7 +11630,7 @@ var generateCode = (schema2, filePath) => {
     const varName = mergedRefs.get(uniqueKey);
     const refIndex = refMap.get(refPath);
     lines.push(
-      `Object.assign(${varName}, __refMap["${refPath}"], ${stringify(siblings)});`,
+      `Object.assign(${varName}, __refMap["${refPath}"], ${stringify2(siblings)});`,
       `Object.defineProperty(${varName}, "__$ref", { value: __refMapPaths[${refIndex}], enumerable: false });`
     );
   }
@@ -11806,22 +11892,6 @@ import { glob as glob4 } from "glob";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { mdxFromMarkdown } from "mdast-util-mdx";
 import { mdxjs } from "micromark-extension-mdxjs";
-
-// src/lib/util/readFrontmatter.ts
-import { readFile as readFile8 } from "node:fs/promises";
-import matter from "gray-matter";
-import { parse as parse2, stringify as stringify2 } from "yaml";
-var yaml = {
-  parse: (input5) => parse2(input5) ?? {},
-  stringify: (obj) => stringify2(obj)
-};
-var readFrontmatter = async (filePath) => {
-  const content = await readFile8(filePath, "utf-8");
-  const normalizedContent = content.replace(/\r\n/g, "\n");
-  return matter(normalizedContent, { engines: { yaml } });
-};
-
-// src/config/validators/NavigationSchema.ts
 init_ZudokuConfig();
 var extractTitleFromContent = (content) => content.match(/^\s*#\s(.*)$/m)?.at(1);
 var isMdxJsxElement = (node) => node.type === "mdxJsxTextElement";

package/package.json

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

@@ -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);