@lukoweb/apitogo 0.2.59 → 0.2.61

package/docs/quickstart.md

@@ -13,6 +13,8 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 ## Prerequisites
 
 - **Node.js 20+**
+- **The `apitogo` CLI, installed globally:** `npm install -g @lukoweb/apitogo` (see
+  [Install the CLI](./cli/setup.md))
 - An account on [apitogo.com](https://apitogo.com) (needed to deploy, not to try it locally)
 
 ## Get started
@@ -22,7 +24,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Create the project**
 
    ```bash
-   npx @lukoweb/apitogo@latest create --template full
+   apitogo create --template full
    ```
 
    It asks for a name, makes a folder for it and writes everything a working product needs:
@@ -37,7 +39,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 
    ```bash
    cd <your project folder>
-   npx apitogo run
+   apitogo run
    ```
 
    Open `http://localhost:3000`. The console signs in with a demo account (`demo@apitogo.local` /
@@ -47,7 +49,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Sign in to APItoGo**
 
    ```bash
-   npx apitogo login
+   apitogo login
    ```
 
    A browser window opens; sign in there.
@@ -55,7 +57,7 @@ that checks API keys and limits, sign-in for your users, and plans they pick. On
 1. **Deploy**
 
    ```bash
-   npx apitogo deploy
+   apitogo deploy
    ```
 
    The first deploy creates the project (it asks which hosting plan: Free, Starter or Professional),

package/docs/writing.mdx

@@ -1,68 +1,68 @@
----
-title: Writing
-sidebar_icon: book-open-text
-description: A guide to writing documentation in APIToGo using Markdown and MDX.
----
-
-Get started with creating rich documentation in APIToGo using Markdown and MDX. This guide covers
-the essentials to help you begin documenting your project.
-
-## Quick Start
-
-1. **Create a markdown file** in `apitogo/portal/pages/`
-2. **Add frontmatter** with title and metadata
-3. **Write content** using Markdown or MDX
-
-The page shows in the sidebar on its own.
-
-### Basic Document Structure
-
-```md
----
-title: My Document
-sidebar_icon: file-text
----
-
-Your content goes here using standard Markdown syntax.
-```
-
-## Adding to Navigation
-
-The sidebar is built from the files: every page in `apitogo/portal/pages/` (or the folders
-`portal.docs.content` names) is listed, and each folder becomes a section. A folder's `index` page
-comes first, then pages with an `order`, lowest first, then the rest by name:
-
-```md
----
-title: Authentication
-order: 2
----
-```
-
-A page with `draft: true` is left out of deployed portals.
-
-## File Organization
-
-Organize your documentation files in logical directories:
-
-```
-pages/
-├── getting-started/
-│   ├── installation.md
-│   └── quick-start.md
-├── guides/
-│   ├── authentication.md
-│   └── deployment.md
-└── api/
-    └── reference.md
-```
-
-## What's Next?
-
-Explore the detailed guides to enhance your documentation:
-
-- **[Markdown Overview](/docs/markdown/overview)** - Complete markdown syntax reference
-- **[Frontmatter](/docs/markdown/frontmatter)** - Document metadata and configuration
-- **[MDX](/docs/markdown/mdx)** - Interactive components in markdown
-- **[Admonitions](/docs/markdown/admonitions)** - Callouts and alerts
-- **[Code Blocks](/docs/markdown/code-blocks)** - Syntax highlighting and features
+---
+title: Writing
+sidebar_icon: book-open-text
+description: A guide to writing documentation in APIToGo using Markdown and MDX.
+---
+
+Get started with creating rich documentation in APIToGo using Markdown and MDX. This guide covers
+the essentials to help you begin documenting your project.
+
+## Quick Start
+
+1. **Create a markdown file** in `apitogo/portal/pages/`
+2. **Add frontmatter** with title and metadata
+3. **Write content** using Markdown or MDX
+
+The page shows in the sidebar on its own.
+
+### Basic Document Structure
+
+```md
+---
+title: My Document
+sidebar_icon: file-text
+---
+
+Your content goes here using standard Markdown syntax.
+```
+
+## Adding to Navigation
+
+The sidebar is built from the files: every page in `apitogo/portal/pages/` (or the folders
+`portal.docs.content` names) is listed, and each folder becomes a section. A folder's `index` page
+comes first, then pages with an `order`, lowest first, then the rest by name:
+
+```md
+---
+title: Authentication
+order: 2
+---
+```
+
+A page with `draft: true` is left out of deployed portals.
+
+## File Organization
+
+Organize your documentation files in logical directories:
+
+```
+pages/
+├── getting-started/
+│   ├── installation.md
+│   └── quick-start.md
+├── guides/
+│   ├── authentication.md
+│   └── deployment.md
+└── api/
+    └── reference.md
+```
+
+## What's Next?
+
+Explore the detailed guides to enhance your documentation:
+
+- **[Markdown Overview](/docs/markdown/overview)** - Complete markdown syntax reference
+- **[Frontmatter](/docs/markdown/frontmatter)** - Document metadata and configuration
+- **[MDX](/docs/markdown/mdx)** - Interactive components in markdown
+- **[Admonitions](/docs/markdown/admonitions)** - Callouts and alerts
+- **[Code Blocks](/docs/markdown/code-blocks)** - Syntax highlighting and features

package/package.json

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

package/src/config/apitogo-config-core.ts

@@ -558,8 +558,18 @@ function syncAuthentication(normalized: ApitogoJsonConfig): void {
     return;
   }
 
+  // `authentication.enabled: false` turns sign-in off: no provider at all, so the header shows no "Log in" and
+  // "Get started". Without this the block below gave it a dev-portal type, and the auth plugin loads a provider for
+  // any type. The user panel needs sign-in, so with the panel on it still wins.
+  if (!userPanelEnabled && authentication?.enabled === false) {
+    delete normalized.authentication;
+    return;
+  }
+
   const auth = authentication ?? {};
-  auth.enabled = userPanelEnabled;
+  // Only the panel sets `enabled`: writing `false` here would read as "turned off" when the config is normalized
+  // again, and drop an OpenID provider that a portal without the panel still signs in with. Readers check `=== true`.
+  if (userPanelEnabled) auth.enabled = true;
   // A portal that signs in with an OpenID provider (the project's identity, with no plans backend) keeps it: the
   // dev-portal defaults below (native sign-up, an empty provider list, the demo sign-in form) belong to the
   // dev-portal provider only.

package/src/config/v2/resolve.ts

@@ -19,6 +19,16 @@ function fromConfig(configDir: string, value: string): string {
     : toGlobPath(path.resolve(configDir, value));
 }
 
+/**
+ * A header link. `to` is where it goes. A page link also has `page`, the absolute path of its file (a React page or a
+ * Markdown page), which the portal serves at `/<file name>` (so `to` is that address) and keeps out of the docs sidebar.
+ */
+export type ResolvedHeaderLink = { label: string; to: string; page?: string };
+
+/** The address of a header page: its file name without the extension, `about.tsx` is `/about`. */
+export const headerPageRoute = (file: string): string =>
+  `/${path.basename(file).replace(/\.(mdx?|tsx)$/i, "")}`;
+
 export type ResolvedPortal = {
   enabled: boolean;
   dir: string;
@@ -36,6 +46,8 @@ export type ResolvedPortal = {
   landing?: string;
   /** Absolute path of the footer component, when the portal has one (API-129). */
   footer?: string;
+  /** Links of the header's top menu (`portal.header.links`), in their order. Empty when there are none. */
+  headerLinks: ResolvedHeaderLink[];
   /** The header logo, when the portal has one: absolute paths (inside the portal's `public/`) or https URLs (API-129). */
   logo?: { light: string; dark: string; alt?: string };
   requireAuth: boolean | { exclude: string[] };
@@ -159,6 +171,13 @@ export function resolveConfigV2(
       ...(portal.footer
         ? { footer: path.resolve(configDir, portal.footer) }
         : {}),
+      headerLinks: (portal.header?.links ?? []).map(
+        (link): ResolvedHeaderLink => {
+          if ("to" in link) return { label: link.label, to: link.to };
+          const page = path.resolve(configDir, link.page);
+          return { label: link.label, to: headerPageRoute(page), page };
+        },
+      ),
       ...(portal.logo
         ? {
             logo:

package/src/config/v2/rules.ts

@@ -4,6 +4,7 @@ import { glob } from "glob";
 import { parse as parseYaml } from "yaml";
 import { billingNeeded, stripeKeySecretName } from "./billing.js";
 import type { ConfigIssue } from "./errors.js";
+import { docRoutes } from "./home-redirect.js";
 import { isLogoUrl, type ResolvedConfigV2, toGlobPath } from "./resolve.js";
 import type { ConfigV2 } from "./schema.js";
 import { findTsxPages } from "./tsx-pages.js";
@@ -255,6 +256,7 @@ async function portalRules(
       message: `the file ${path.relative(resolved.configDir, portal.footer)} does not exist.`,
       hint: "Create it, or remove portal.footer.",
     });
+  await headerLinksRule(portal, resolved, out);
   const publicDir = path.join(portal.dir, "public");
   for (const file of new Set(
     [portal.logo?.light, portal.logo?.dark].filter(
@@ -323,6 +325,92 @@ async function docsContentRule(
   });
 }
 
+/** Addresses the portal itself uses, so a header page cannot take them. */
+const RESERVED_HEADER_ROUTES = [
+  "/",
+  "/index",
+  "/api",
+  "/pricing",
+  "/account",
+  "/login",
+  "/signup",
+];
+
+/**
+ * Header pages (`portal.header.links[].page`) are React or Markdown files the portal serves at `/<file name>`, outside
+ * the sidebar. A wrong one would fail the build or quietly take another page's address, so check says so first.
+ */
+async function headerLinksRule(
+  portal: NonNullable<ResolvedConfigV2["portal"]>,
+  resolved: ResolvedConfigV2,
+  out: Collector,
+) {
+  const pages = portal.headerLinks
+    .map((link, index) => ({ link, index }))
+    .filter(({ link }) => link.page !== undefined);
+  if (pages.length === 0) return;
+  const hostsDocs = portal.docs.enabled && portal.docs.provider === "apitogo";
+  const docs = hostsDocs
+    ? [
+        ...(await docRoutes(portal.docs.content, { includeDrafts: true })),
+        ...(await findTsxPages(portal.docs.content)).map((page) => page.route),
+      ]
+    : [];
+  const seen = new Set<string>();
+  for (const { link, index } of pages) {
+    const file = link.page as string;
+    const at = `portal.header.links[${index}].page`;
+    const shown = path.relative(resolved.configDir, file);
+    if (!hostsDocs) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_NO_DOCS",
+        path: at,
+        message: `the header page ${shown} needs hosted docs, which this portal does not have.`,
+        hint: 'Header pages are served with the docs pages: set portal.docs.provider to "apitogo", or link an address with "to" instead.',
+      });
+      continue;
+    }
+    if (!/\.(mdx?|tsx)$/i.test(file)) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_INVALID",
+        path: at,
+        message: `the header page ${shown} is neither a React page nor a Markdown page.`,
+        hint: "Use a .tsx file (its default export is the page) or a .md / .mdx file.",
+      });
+      continue;
+    }
+    if (!(await isFile(file))) {
+      out.error({
+        code: "PORTAL_FILE_MISSING",
+        path: at,
+        message: `the file ${shown} does not exist.`,
+        hint: "Create it (`apitogo config --page-slug <name> --page-title <title> --page-header`), or remove the link.",
+      });
+      continue;
+    }
+    const route = link.to;
+    if (RESERVED_HEADER_ROUTES.includes(route.toLowerCase())) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_ROUTE_TAKEN",
+        path: at,
+        message: `the header page ${shown} would be served at ${route}, which the portal uses itself.`,
+        hint: "Rename the file: its name is the page's address.",
+      });
+      continue;
+    }
+    if (docs.includes(route) || seen.has(route)) {
+      out.error({
+        code: "PORTAL_HEADER_PAGE_ROUTE_TAKEN",
+        path: at,
+        message: `the header page ${shown} would be served at ${route}, which another page already has.`,
+        hint: 'Rename the file: its name is the page\'s address. A docs page that should be in the header too can be linked with "to" instead.',
+      });
+      continue;
+    }
+    seen.add(route);
+  }
+}
+
 // --- gateway (2.4) --------------------------------------------------------------------------------------------------
 
 function isIpLiteral(hostname: string): boolean {

package/src/config/v2/schema.ts

@@ -31,6 +31,32 @@ const pathList = z.array(nonEmpty);
 
 const enabled = z.boolean().optional();
 
+const headerLabel = z
+  .string()
+  .trim()
+  .min(1, { error: "must not be empty" })
+  .max(40, { error: "must be 40 characters or fewer" });
+
+/**
+ * A link in the portal header's top menu: a page of its own (a React `.tsx` or Markdown file, served at `/<file name>`
+ * and kept out of the docs sidebar) or an address (`/path` on the portal, or `https://` elsewhere).
+ */
+const HeaderLinkSchema = z.union(
+  [
+    z.strictObject({ label: headerLabel, page: path }),
+    z.strictObject({
+      label: headerLabel,
+      to: z.string().regex(/^(\/(?!\/)|https:\/\/)/, {
+        error: 'must start with "/" or "https://"',
+      }),
+    }),
+  ],
+  {
+    error:
+      'must be { "label": "...", "page": "path/to/page.tsx" } or { "label": "...", "to": "/path or https://..." }',
+  },
+);
+
 export const PortalSchema = z.strictObject({
   enabled,
   dir: path.optional(),
@@ -49,6 +75,8 @@ export const PortalSchema = z.strictObject({
   landing: path.optional(),
   /** The footer: a React component file shown under every page except the console's (API-129). */
   footer: path.optional(),
+  /** Links of the header's top menu, after the built-in ones (Documentation, API Reference; the plans add Pricing). */
+  header: z.strictObject({ links: z.array(HeaderLinkSchema) }).optional(),
   /**
    * The logo in the portal header: one image, or one per color scheme (API-129). `dark` is optional; without it the
    * light image is used in both.

package/src/config/v2/wrapper.ts

@@ -24,7 +24,7 @@ import {
 } from "./manifest.js";
 import { type PortalProfile, portalProfile } from "./portal-profile.js";
 import { protectedRoutesFor } from "./protected-routes.js";
-import { isLogoUrl, type ResolvedConfigV2 } from "./resolve.js";
+import { isLogoUrl, type ResolvedConfigV2, toGlobPath } from "./resolve.js";
 import { findTsxPages, TSX_PAGE_ELEMENT_PREFIX } from "./tsx-pages.js";
 
 export const WRAPPER_FILE = "apitogo.config.tsx";
@@ -71,6 +71,8 @@ const PLANS_CONSOLE_CAPABILITIES = [
 export type PortalPlan = {
   /** Docs pages, navigation and search APItoGo builds. */
   docs: boolean;
+  /** The search box the site shows; only for docs APItoGo hosts. Absent: the site has no search. */
+  search?: "pagefind";
   /** OpenAPI reference pages and playground, built from the gateway's OpenAPI file. */
   apiReference: boolean;
   /** Where the reference points its calls, and the header of the API key; set when `apiReference` is true. */
@@ -215,6 +217,12 @@ export function planPortal(
 
   if (!profile.enabled) return plan;
 
+  // The build already writes the Pagefind index for hosted docs; the site shows the search box only when its config
+  // names the search. Inkeep needs keys that `portal.search` cannot carry yet, so it is left out, not half-registered.
+  if (profile.pipelines.search === "pagefind") plan.search = "pagefind";
+  else if (profile.pipelines.search === "inkeep")
+    skip("search", "inkeep needs keys that portal.search cannot hold yet");
+
   // The API page is built from the gateway's OpenAPI file and calls the gateway, so it needs the gateway's address.
   if (profile.pipelines.openapi) {
     if (!gateway) skip("api reference", "services.json has no gateway entry");
@@ -314,6 +322,29 @@ export const REFERENCE_SPEC_FILE = "openapi/gateway.json";
 /** Route of the API reference page. */
 export const API_REFERENCE_PATH = "api";
 
+const MARKDOWN_PAGE = /\.mdx?$/i;
+
+/** Placeholder of a React header page in the site config; the wrapper puts the component in its place. */
+export const HEADER_PAGE_ELEMENT_PREFIX = "apitogo:header-page:";
+
+/** The React header pages (`portal.header.links[].page` ending in `.tsx`), each with its wrapper placeholder. */
+export function headerTsxPages(
+  resolved: ResolvedConfigV2,
+  plan: PortalPlan,
+): { id: string; route: string; label: string; file: string }[] {
+  if (!plan.docs) return [];
+  return (resolved.portal?.headerLinks ?? [])
+    .flatMap((link) =>
+      link.page && /\.tsx$/i.test(link.page)
+        ? [{ route: link.to, label: link.label, file: link.page }]
+        : [],
+    )
+    .map((page, index) => ({
+      ...page,
+      id: `${HEADER_PAGE_ELEMENT_PREFIX}${index}`,
+    }));
+}
+
 /**
  * The site settings (title, modules, docs globs, theme, sign-in) in the shape the existing build reads from
  * `apitogo.config.json`. It is generated, never edited, and lives in `generated/`.
@@ -334,9 +365,31 @@ export function buildSiteConfig(
 ): Record<string, unknown> {
   const portal = resolved.portal;
   const redirects = extras.redirects ?? [];
+  // Header pages are pages the sidebar leaves out. A Markdown one is served by the docs plugin from its own file; a React
+  // one is a hidden custom page, whose placeholder the wrapper replaces with the component. Both need hosted docs.
+  const headerLinks = portal?.headerLinks ?? [];
+  const headerPages = plan.docs
+    ? headerLinks.flatMap((link) =>
+        link.page && MARKDOWN_PAGE.test(link.page) ? [link.page] : [],
+      )
+    : [];
+  const shownHeaderLinks = headerLinks
+    .filter((link) => !link.page || plan.docs)
+    .map((link) => ({
+      label: link.label,
+      to: link.to,
+      ...(link.to.startsWith("https://") ? { target: "_blank" } : {}),
+    }));
   // One header tab for the docs sidebar, and the API reference as a link next to it.
   const navigation = [
     ...(extras.docsNavigation ?? []),
+    ...headerTsxPages(resolved, plan).map((page) => ({
+      type: "custom-page",
+      path: page.route,
+      label: page.label,
+      element: page.id,
+      display: "hide",
+    })),
     ...(plan.apiReference
       ? [
           {
@@ -384,12 +437,14 @@ export function buildSiteConfig(
     ...(plan.docs
       ? {
           docs: {
-            files: portal?.docs.content.map((glob) =>
-              contentGlob(resolved.configDir, glob),
-            ),
+            files: [
+              ...(portal?.docs.content ?? []),
+              ...headerPages.map(toGlobPath),
+            ].map((glob) => contentGlob(resolved.configDir, glob)),
           },
         }
       : {}),
+    ...(plan.search ? { search: { type: plan.search } } : {}),
     ...(plan.apiReference
       ? {
           apis: [
@@ -403,15 +458,18 @@ export function buildSiteConfig(
       : {}),
     ...(navigation.length > 0 ? { navigation } : {}),
     // The sidebar link above is only seen inside the docs; the header is what every page shows. A header navigation
-    // replaces the docs tab, so the docs get a header link of their own.
-    ...(plan.apiReference
+    // replaces the docs tab, so the docs get a header link of their own. The tenant's own links (portal.header) follow.
+    ...(plan.apiReference || shownHeaderLinks.length > 0
       ? {
           header: {
             navigation: [
               ...(plan.docs && extras.docsPath
                 ? [{ label: "Documentation", to: extras.docsPath }]
                 : []),
-              { label: "API Reference", to: `/${API_REFERENCE_PATH}` },
+              ...(plan.apiReference
+                ? [{ label: "API Reference", to: `/${API_REFERENCE_PATH}` }]
+                : []),
+              ...shownHeaderLinks,
             ],
           },
         }
@@ -755,13 +813,19 @@ export async function preparePortal(
         (page) => !markdownRoutes.includes(page.route),
       )
     : [];
+  const importPathOf = (file: string) =>
+    `./${CONTENT_LINK}/${path
+      .relative(resolved.configDir, file)
+      .split(path.sep)
+      .join("/")}`;
   const wrapperPages: WrapperPage[] = tsxPages.map((page, index) => ({
     id: `${TSX_PAGE_ELEMENT_PREFIX}${index}`,
-    importPath: `./${CONTENT_LINK}/${path
-      .relative(resolved.configDir, page.file)
-      .split(path.sep)
-      .join("/")}`,
+    importPath: importPathOf(page.file),
   }));
+  // React header pages are imported the same way; their placeholders are in the navigation, outside the sidebar.
+  const headerWrapperPages: WrapperPage[] = headerTsxPages(resolved, plan).map(
+    (page) => ({ id: page.id, importPath: importPathOf(page.file) }),
+  );
   const hostedDocRoutes = [
     ...new Set([...markdownRoutes, ...tsxPages.map((page) => page.route)]),
   ].sort();
@@ -863,7 +927,15 @@ export async function preparePortal(
       protectedRoutes: protectedRoutesFor({
         requireAuth: resolved.portal?.requireAuth,
         hasAuth: !!plan.auth,
-        docRoutes: hostedDocRoutes,
+        // A header page is a docs page too, so a portal behind login keeps it behind login.
+        docRoutes: plan.docs
+          ? [
+              ...hostedDocRoutes,
+              ...(resolved.portal?.headerLinks ?? []).flatMap((link) =>
+                link.page ? [link.to] : [],
+              ),
+            ]
+          : hostedDocRoutes,
         apiReferencePath: plan.apiReference
           ? `/${API_REFERENCE_PATH}`
           : undefined,
@@ -872,7 +944,7 @@ export async function preparePortal(
   );
   const wrapper = renderWrapper(
     plan,
-    wrapperPages,
+    [...wrapperPages, ...headerWrapperPages],
     resolved.portal?.footer
       ? wrapperImport(contentFile(resolved.configDir, resolved.portal.footer))
       : undefined,