@lukoweb/apitogo 0.2.59 → 0.2.61

package/docs/components/slot.mdx

@@ -1,116 +1,116 @@
----
-title: Slot
-sidebar_icon: between-horizontal-start
-description:
-  Use the low-level Slot component for advanced slot management in custom pages and MDX content.
----
-
-The `Slot` component provides low-level access to APIToGo's slot system, allowing you to
-programmatically manage content injection in custom pages and React components.
-
-## Import
-
-```tsx
-import { Slot } from "@lukoweb/apitogo/components";
-```
-
-## Components
-
-The Slot system consists of two main components:
-
-### Slot.Target
-
-Renders content that has been injected into a specific slot.
-
-```tsx
-<Slot.Target name="my-slot" fallback={<div>No content</div>} />
-```
-
-**Props:**
-
-- `name` (required): The slot name to render content for
-- `fallback` (optional): Content to show when no slot content is available
-
-### Slot.Source
-
-Injects content into a specific slot. This component renders nothing but registers content to be
-displayed by `Slot.Target` components.
-
-```tsx
-<Slot.Source name="my-slot" type="append">
-  <div>Content to inject</div>
-</Slot.Source>
-```
-
-**Props:**
-
-- `name` (required): The slot name to inject content into
-- `type` (optional): How to handle multiple content sources
-  - `"replace"` (default): Replace existing content
-  - `"prepend"`: Add before existing content
-  - `"append"`: Add after existing content
-- `children`: The content to inject
-
-## Usage Example
-
-```tsx
-function MyCustomPage() {
-  return (
-    <div>
-      <h1>My Page</h1>
-
-      {/* Render slot content here */}
-      <Slot.Target name="custom-page-header" />
-
-      {/* Inject content into a slot */}
-      <Slot.Source name="custom-page-header">
-        <div className="bg-blue-100 p-4 rounded">Custom header content</div>
-      </Slot.Source>
-
-      <p>Page content here...</p>
-    </div>
-  );
-}
-```
-
-## Type Safety
-
-The Slot component is fully type-safe. All predefined slot names are available with autocomplete:
-
-```tsx
-// These will show autocomplete for available slot names
-<Slot.Target name="head-navigation-end" />
-<Slot.Source name="footer-before">Content</Slot.Source>
-```
-
-### Adding Custom Slot Names
-
-To add your own slot names with full type safety, augment the `CustomSlotNames` type:
-
-```tsx
-// types/slots.d.ts
-declare module "@lukoweb/apitogo" {
-  type CustomSlotNames = "my-custom-header" | "sidebar-extra";
-}
-```
-
-## Integration with Configuration
-
-The Slot component works with configuration-based slots. Content defined in your
-`apitogo.config.json` and content injected via `Slot.Source` components will be combined according
-to the `type` parameter.
-
-```tsx
-// In your site config
-slots: {
-  "page-header": <div>Config header</div>
-}
-
-// In your component
-<Slot.Source name="page-header" type="append">
-  <Button>Go Home</Button>
-</Slot.Source>
-
-// Renders both: Config header, then Component button
-<Slot.Target name="page-header" />
-```
+---
+title: Slot
+sidebar_icon: between-horizontal-start
+description:
+  Use the low-level Slot component for advanced slot management in custom pages and MDX content.
+---
+
+The `Slot` component provides low-level access to APIToGo's slot system, allowing you to
+programmatically manage content injection in custom pages and React components.
+
+## Import
+
+```tsx
+import { Slot } from "@lukoweb/apitogo/components";
+```
+
+## Components
+
+The Slot system consists of two main components:
+
+### Slot.Target
+
+Renders content that has been injected into a specific slot.
+
+```tsx
+<Slot.Target name="my-slot" fallback={<div>No content</div>} />
+```
+
+**Props:**
+
+- `name` (required): The slot name to render content for
+- `fallback` (optional): Content to show when no slot content is available
+
+### Slot.Source
+
+Injects content into a specific slot. This component renders nothing but registers content to be
+displayed by `Slot.Target` components.
+
+```tsx
+<Slot.Source name="my-slot" type="append">
+  <div>Content to inject</div>
+</Slot.Source>
+```
+
+**Props:**
+
+- `name` (required): The slot name to inject content into
+- `type` (optional): How to handle multiple content sources
+  - `"replace"` (default): Replace existing content
+  - `"prepend"`: Add before existing content
+  - `"append"`: Add after existing content
+- `children`: The content to inject
+
+## Usage Example
+
+```tsx
+function MyCustomPage() {
+  return (
+    <div>
+      <h1>My Page</h1>
+
+      {/* Render slot content here */}
+      <Slot.Target name="custom-page-header" />
+
+      {/* Inject content into a slot */}
+      <Slot.Source name="custom-page-header">
+        <div className="bg-blue-100 p-4 rounded">Custom header content</div>
+      </Slot.Source>
+
+      <p>Page content here...</p>
+    </div>
+  );
+}
+```
+
+## Type Safety
+
+The Slot component is fully type-safe. All predefined slot names are available with autocomplete:
+
+```tsx
+// These will show autocomplete for available slot names
+<Slot.Target name="head-navigation-end" />
+<Slot.Source name="footer-before">Content</Slot.Source>
+```
+
+### Adding Custom Slot Names
+
+To add your own slot names with full type safety, augment the `CustomSlotNames` type:
+
+```tsx
+// types/slots.d.ts
+declare module "@lukoweb/apitogo" {
+  type CustomSlotNames = "my-custom-header" | "sidebar-extra";
+}
+```
+
+## Integration with Configuration
+
+The Slot component works with configuration-based slots. Content defined in your
+`apitogo.config.json` and content injected via `Slot.Source` components will be combined according
+to the `type` parameter.
+
+```tsx
+// In your site config
+slots: {
+  "page-header": <div>Config header</div>
+}
+
+// In your component
+<Slot.Source name="page-header" type="append">
+  <Button>Go Home</Button>
+</Slot.Source>
+
+// Renders both: Config header, then Component button
+<Slot.Target name="page-header" />
+```

package/docs/configuration/api-reference.md

@@ -31,7 +31,7 @@ The page shows your API as people call it, through the gateway, not as it runs b
 - Operations in `gateway.policies.operations.public` show no security, since they need no key.
 - Operations in `gateway.policies.operations.deny` are left out.
 
-Before the first deploy the gateway has no address yet, so `npx apitogo run` leaves the page out and
+Before the first deploy the gateway has no address yet, so `apitogo run` leaves the page out and
 says so. It appears once the gateway is deployed.
 
 ## Try it

package/docs/configuration/authentication.md

@@ -72,7 +72,7 @@ Add an OpenID Connect provider next to email and password. Its client secret is
 ```
 
 ```bash
-npx apitogo secrets set MICROSOFT_CLIENT_SECRET
+apitogo secrets set MICROSOFT_CLIENT_SECRET
 ```
 
 Set `"native": false` to offer only the connections.
@@ -108,8 +108,8 @@ The API reference's Try it then also offers **Signed-in user**, which sends that
 
 ## Local preview
 
-`npx apitogo run` before the first deploy has no sign-in service yet. The console then signs in with
-a demo account, so you can try every page:
+`apitogo run` before the first deploy has no sign-in service yet. The console then signs in with a
+demo account, so you can try every page:
 
 ```text
 demo@apitogo.local / password

package/docs/configuration/footer.mdx

@@ -1,89 +1,89 @@
----
-title: Footer
-sidebar_label: Footer
-sidebar_icon: panel-bottom-dashed
-description: >-
-  The portal's footer is a React file you own, named by portal.footer. It shows under every page
-  except the console's.
----
-
-The footer is a React file in your folder, **`apitogo/portal/footer/Footer.tsx`**, named by
-`portal.footer` in `apitogo.config.json`:
-
-```json title=apitogo.config.json
-{
-  "portal": {
-    "footer": "apitogo/portal/footer/Footer.tsx"
-  }
-}
-```
-
-It shows under the home page, the docs, the API reference and the pricing page. It is not shown on
-the console's pages (`/account`, `/login`, `/signup`).
-
-`apitogo add portal` writes a starter footer and the setting. Remove `portal.footer` to have no
-footer.
-
-## The starter footer
-
-The starter uses `FooterSection` from `@lukoweb/apitogo-module-landing`, so it matches the home
-page. Change anything in it:
-
-```tsx title=apitogo/portal/footer/Footer.tsx
-import { FooterSection } from "@lukoweb/apitogo-module-landing";
-
-const NAME = "Books API";
-
-export default function Footer() {
-  return (
-    <FooterSection
-      footer={{
-        brand: { name: NAME, tagline: "Documentation, API keys and plans for the Books API." },
-        columns: [
-          {
-            title: "Developers",
-            links: [
-              { label: "Documentation", href: "/introduction" },
-              { label: "API Reference", href: "/api" },
-              { label: "Pricing", href: "/pricing" },
-            ],
-          },
-          {
-            title: "Company",
-            links: [{ label: "Contact", href: "mailto:hello@example.com" }],
-          },
-        ],
-        social: [{ icon: "github", href: "https://github.com/example", label: "GitHub" }],
-        copyright: `© ${new Date().getFullYear()} ${NAME}`,
-      }}
-    />
-  );
-}
-```
-
-`FooterSection` takes:
-
-| Field       | What it is                                                                  |
-| ----------- | --------------------------------------------------------------------------- |
-| `brand`     | `name`, an optional `tagline`, and an optional `logoSrc` (an image address) |
-| `columns`   | Link columns: a `title` and `links` of `{ label, href }`                    |
-| `social`    | Icon links: `icon` (`github`, `x`), `href` and an optional `label`          |
-| `copyright` | The last line; by default `© <year> <name>. All rights reserved.`           |
-
-## Your own footer
-
-The file can render anything: it is a React component, and its default export is the footer. Use the
-theme's classes (`bg-background`, `text-muted-foreground`, `border-t`) so it follows light and dark
-mode:
-
-```tsx title=apitogo/portal/footer/Footer.tsx
-export default function Footer() {
-  return (
-    <footer className="border-t bg-background py-8 text-center text-sm text-muted-foreground">
-      © {new Date().getFullYear()} Books API · <a href="/pricing">Pricing</a>
-    </footer>
-  );
-}
-```
-
-`apitogo check` reports a `portal.footer` that names a file that does not exist.
+---
+title: Footer
+sidebar_label: Footer
+sidebar_icon: panel-bottom-dashed
+description: >-
+  The portal's footer is a React file you own, named by portal.footer. It shows under every page
+  except the console's.
+---
+
+The footer is a React file in your folder, **`apitogo/portal/footer/Footer.tsx`**, named by
+`portal.footer` in `apitogo.config.json`:
+
+```json title=apitogo.config.json
+{
+  "portal": {
+    "footer": "apitogo/portal/footer/Footer.tsx"
+  }
+}
+```
+
+It shows under the home page, the docs, the API reference and the pricing page. It is not shown on
+the console's pages (`/account`, `/login`, `/signup`).
+
+`apitogo add portal` writes a starter footer and the setting. Remove `portal.footer` to have no
+footer.
+
+## The starter footer
+
+The starter uses `FooterSection` from `@lukoweb/apitogo-module-landing`, so it matches the home
+page. Change anything in it:
+
+```tsx title=apitogo/portal/footer/Footer.tsx
+import { FooterSection } from "@lukoweb/apitogo-module-landing";
+
+const NAME = "Books API";
+
+export default function Footer() {
+  return (
+    <FooterSection
+      footer={{
+        brand: { name: NAME, tagline: "Documentation, API keys and plans for the Books API." },
+        columns: [
+          {
+            title: "Developers",
+            links: [
+              { label: "Documentation", href: "/introduction" },
+              { label: "API Reference", href: "/api" },
+              { label: "Pricing", href: "/pricing" },
+            ],
+          },
+          {
+            title: "Company",
+            links: [{ label: "Contact", href: "mailto:hello@example.com" }],
+          },
+        ],
+        social: [{ icon: "github", href: "https://github.com/example", label: "GitHub" }],
+        copyright: `© ${new Date().getFullYear()} ${NAME}`,
+      }}
+    />
+  );
+}
+```
+
+`FooterSection` takes:
+
+| Field       | What it is                                                                  |
+| ----------- | --------------------------------------------------------------------------- |
+| `brand`     | `name`, an optional `tagline`, and an optional `logoSrc` (an image address) |
+| `columns`   | Link columns: a `title` and `links` of `{ label, href }`                    |
+| `social`    | Icon links: `icon` (`github`, `x`), `href` and an optional `label`          |
+| `copyright` | The last line; by default `© <year> <name>. All rights reserved.`           |
+
+## Your own footer
+
+The file can render anything: it is a React component, and its default export is the footer. Use the
+theme's classes (`bg-background`, `text-muted-foreground`, `border-t`) so it follows light and dark
+mode:
+
+```tsx title=apitogo/portal/footer/Footer.tsx
+export default function Footer() {
+  return (
+    <footer className="border-t bg-background py-8 text-center text-sm text-muted-foreground">
+      © {new Date().getFullYear()} Books API · <a href="/pricing">Pricing</a>
+    </footer>
+  );
+}
+```
+
+`apitogo check` reports a `portal.footer` that names a file that does not exist.

package/docs/configuration/gateway.md

@@ -188,7 +188,7 @@ with a secret that only the gateway sends:
 ```
 
 ```bash
-npx apitogo secrets set GATEWAY_SECRET
+apitogo secrets set GATEWAY_SECRET
 ```
 
 The value is a reference, never the secret itself. The secret is stored encrypted and never shown
@@ -221,11 +221,11 @@ If you have no place to host your API, the platform can run your code. Set the o
 | `healthPath`     | Path the platform probes to check that your API is up.                                                      |
 | `exclude`        | More paths to leave out, in `.gitignore` syntax.                                                            |
 
-`npx apitogo add gateway --origin managed` makes the `source` folder when it does not exist and
-tells you it is empty; put your code there. `npx apitogo check` warns while the folder has no code.
+`apitogo add gateway --origin managed` makes the `source` folder when it does not exist and tells
+you it is empty; put your code there. `apitogo check` warns while the folder has no code.
 
-`npx apitogo project create` prepares the hosting for your code. `npx apitogo deploy` then uploads
-the OpenAPI file and the config, uploads your code and waits until it runs, and the gateway starts
+`apitogo project create` prepares the hosting for your code. `apitogo deploy` then uploads the
+OpenAPI file and the config, uploads your code and waits until it runs, and the gateway starts
 sending calls to it. A deploy with the same code uploads nothing. A .NET project is published for
 you (this needs the .NET SDK on your machine), or you can point `source` at a folder that is already
 published.
@@ -249,15 +249,15 @@ if (req.headers[header] !== process.env.APITOGO_ORIGIN_SECRET) {
 Run these before you deploy:
 
 ```bash
-npx apitogo check
-npx apitogo plan
+apitogo check
+apitogo plan
 ```
 
 `check` finds mistakes in the file, offline. `plan` shows what a deploy would change and changes
 nothing. Then deploy and test the address that `apitogo status` shows:
 
 ```bash
-npx apitogo deploy --only gateway
+apitogo deploy --only gateway
 curl -i https://YOUR-GATEWAY-ADDRESS/health
 curl -i https://YOUR-GATEWAY-ADDRESS/orders
 ```

package/docs/configuration/make-config.mdx

@@ -7,7 +7,7 @@ description: >-
   and plans.
 ---
 
-The **`npx apitogo config`** command changes a project made by `apitogo create` or `apitogo init`
+The **`apitogo config`** command changes a project made by `apitogo create` or `apitogo init`
 (config version 2). It edits **`apitogo.config.json`**, writes docs pages under
 **`apitogo/portal/pages/`**, and keeps plans in **`apitogo/plans.json`**.
 
@@ -32,13 +32,22 @@ page in `guides/quickstart.tsx` shows under a **Guides** section at `/guides/qui
 are React components by default; pass `--page-format mdx` for a Markdown page. See
 [Custom pages](../guides/custom-pages.md).
 
+A page that belongs in the header's top menu instead of the sidebar (Partners, About, Contact) takes
+`--page-header`: the React page goes to `apitogo/portal/header-pages/<slug>.tsx` (`.mdx` with
+`--page-format mdx`) and a link is added to `portal.header.links`. See
+[Header links](./portal.md#header-links).
+
+```bash
+apitogo config --page-slug partners --page-title Partners --page-header
+```
+
 Changing a gateway or plan needs that service in the project. Add it first with
 `apitogo add gateway` or `apitogo add plans`.
 
 ## Interactive wizard
 
-On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at once. Type `done`
-(the default) to finish.
+On a TTY, bare `apitogo config` opens the wizard. Each answer is applied at once. Type `done` (the
+default) to finish.
 
 - **`backend`**: folder of your API code, runtime (`nodejs` / `python` / `dotnet`) and version
 - **`openapi`**: an OpenAPI file to add to `gateway.specs`
@@ -46,7 +55,7 @@ On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at
 - **`plan`**: title, fixed or custom price, rate limit per minute, quota per 30 days; added to
   `plans.json`
 
-Payments go through Stripe. When you add a **paid** plan, `npx apitogo deploy` asks for your Stripe
+Payments go through Stripe. When you add a **paid** plan, `apitogo deploy` asks for your Stripe
 secret key the first time (if the project has none yet). Free and contact-us plans need no key. Paid
 plans also need Starter or Professional platform hosting.
 
@@ -65,6 +74,7 @@ plans also need Starter or Professional platform hosting.
 | `--page-title <title>`      | Title of the page (required when adding)                              |
 | `--page-content <markdown>` | Markdown body of the page                                             |
 | `--page-update`             | Change an existing page instead of adding one                         |
+| `--page-header`             | Link the page from the header's top menu instead of the sidebar       |
 | `--plan <json>`             | Add a plan to `plans.json`, or replace the plan with the same `sku`   |
 | `--patch <json>`            | Deep-merge a JSON object into `apitogo.config.json`                   |
 | `--json`                    | Print a JSON summary on stdout                                        |
@@ -85,12 +95,12 @@ A plan uses the `plans.json` shape:
 Examples:
 
 ```bash
-npx apitogo config
-npx apitogo config --title "Books API"
-npx apitogo config --page-slug guides/quickstart --page-title "Quickstart"
-npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
-npx apitogo config --source server --runtime nodejs --runtime-version NODE_22_LTS
-npx apitogo config --patch '{"portal":{"search":"none"}}'
+apitogo config
+apitogo config --title "Books API"
+apitogo config --page-slug guides/quickstart --page-title "Quickstart"
+apitogo config --plan '{"sku":"free","displayName":"Free"}'
+apitogo config --source server --runtime nodejs --runtime-version NODE_22_LTS
+apitogo config --patch '{"portal":{"search":"none"}}'
 ```
 
 ## See also

package/docs/configuration/overview.md

@@ -84,13 +84,13 @@ names a project secret:
 "plans": { "billing": { "apiKey": "secret:STRIPE_API_KEY" } }
 ```
 
-Store the value with `npx apitogo secrets set STRIPE_API_KEY`. Deploy asks for the secrets it needs
-and stores them for you. A value written straight into the config is refused.
+Store the value with `apitogo secrets set STRIPE_API_KEY`. Deploy asks for the secrets it needs and
+stores them for you. A value written straight into the config is refused.
 
 ## Check before you deploy
 
 ```bash
-npx apitogo check
+apitogo check
 ```
 
 `check` reads the config and the files it names, and says what is missing or wrong, with a hint for

package/docs/configuration/plans.md

@@ -25,7 +25,7 @@ The plans themselves live in **`apitogo/plans.json`**. `apitogo add plans` creat
 `apitogo config` adds plans interactively or with `--plan` (a plan with the same `sku` is replaced):
 
 ```bash
-npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
+apitogo config --plan '{"sku":"free","displayName":"Free"}'
 ```
 
 ## plans.json
@@ -89,7 +89,7 @@ Each card lists, in this order:
 2. The plan's `features`
 3. The endpoints it includes: the ones in `includedActions`, or every operation of the gateway
 
-`npx apitogo run` shows the same cards as the deployed portal.
+`apitogo run` shows the same cards as the deployed portal.
 
 ## Paid plans
 
@@ -124,11 +124,11 @@ request is emailed to the project's sales contact, or to its owner.
 ## Deploy
 
 ```bash
-npx apitogo deploy --only plans
+apitogo deploy --only plans
 ```
 
-deploys the plans, their limits on the gateway and the pricing page. A plain `npx apitogo deploy`
-does it together with everything else.
+deploys the plans, their limits on the gateway and the pricing page. A plain `apitogo deploy` does
+it together with everything else.
 
 ## Hosting plans are something else
 

package/docs/configuration/portal.md

@@ -36,6 +36,7 @@ its starter files.
 | `landing`     | none                                 | A React file shown at `/`, the home page                                    |
 | `footer`      | none                                 | A React file shown under every page except the console's                    |
 | `logo`        | none (the header shows `name`)       | The header logo ([below](#logo))                                            |
+| `header`      | none                                 | Your own links in the header's top menu ([below](#header-links))            |
 | `theme`       | `apitogo/portal/theme.json`          | Colors and fonts ([Colors & theme](../customization/colors-theme.mdx))      |
 | `console`     | `{ "enabled": true }`                | The sign-in, plans, keys and usage pages, when identity or plans is on      |
 | `search`      | `pagefind`                           | `pagefind`, `inkeep` or `none`                                              |
@@ -71,6 +72,41 @@ setting to have none. See [Landing page](../customization/landing-page.md) and
 
 When there is a home page, `/` shows it, and an `index` page of the docs opens at `/index`.
 
+## Header links
+
+`header.links` adds your own links to the top menu, after **Documentation** and **API Reference**
+(the plans service adds **Pricing** itself). A link is either a page of its own or an address:
+
+```json
+"header": {
+  "links": [
+    { "label": "Partners", "page": "apitogo/portal/header-pages/partners.tsx" },
+    { "label": "Status", "to": "https://status.example.com" }
+  ]
+}
+```
+
+- **`page`**: a React page (`.tsx`, its default export is the page) or a Markdown page (`.md`,
+  `.mdx`), served at `/<file name>` (`partners.tsx` is `/partners`). It is a page of its own: the
+  docs sidebar does not list it. It needs hosted docs, and a portal with `requireAuth` keeps it
+  behind sign-in like the docs.
+- **`to`**: a path on the portal (`/blog`) or an `https://` address, which opens in a new tab.
+
+The CLI makes the file and the link in one step:
+
+```bash
+apitogo config --page-slug partners --page-title Partners --page-header
+```
+
+The page is a React component in `apitogo/portal/header-pages/partners.tsx`; add `--page-format mdx`
+for a Markdown page instead. Its title (`export const title`) is the link's label.
+`--page-update --page-title` with `--page-header` renames the page and its link and leaves your code
+as it is. Links show in the order of the list; edit it to reorder them.
+
+`apitogo check` refuses a page that is missing, is not `.tsx`, `.md` or `.mdx`, or would take an
+address the portal already uses (`/pricing`, `/account`, `/api`, `/login`, `/signup` or a docs
+page).
+
 ## logo
 
 An image in the portal's `public/` folder, or an `https://` address: