@lukoweb/apitogo 0.1.67 → 0.1.69

package/docs/configuration/overview.md

@@ -1,380 +1,165 @@
 ---
-title: Configuration File
+title: Configuration overview
 sidebar_icon: file-json-2
 description:
-  Learn how to configure your APIToGo documentation site using the configuration file. Covers file
-  formats, options, examples, and best practices.
+  How APIToGo sites are configured — apitogo.config.json and .env overrides.
 ---
 
-APIToGo uses a single file for configuration. It controls the structure, metadata, style, plugins,
-and routing for your documentation.
+APIToGo sites are configured primarily with JSON and environment variables:
 
-You can find the file in the root directory of your project. It will start with `apitogo.config`.
-The file can be in either JavaScript or TypeScript format and use a `.js`, `.mjs`, `.jsx`, `.ts`, or
-`.tsx` file extension:
+| File                  | Role                                                                  |
+| --------------------- | --------------------------------------------------------------------- |
+| `apitogo.config.json` | Committed site defaults: site, modules, auth, apis, navigation, theme |
+| `.env`                | Client URLs and publish secrets (`APITOGO_CONFIG_*`, `VITE_*`)        |
 
-- `apitogo.config.ts`
-- `apitogo.config.tsx`
-- `apitogo.config.js`
-- `apitogo.config.jsx`
-- `apitogo.config.mjs`
+For portal fields (plans, auth, backend metadata), see
+**[Site configuration (manifest)](./manifest.md)**.
 
-When you create a project, a default configuration file is generated for you. This file is a good
-starting point and can be customized to suit your needs.
+:::note{title="Security"}
 
-:::note{title="Security Consideration"}
-
-The APIToGo configuration file runs on both client and server at runtime. Avoid including secrets
-directly in your config as they may be exposed to the client.
+Do not put OIDC client secrets, Stripe keys, or other secrets in JSON. Use `.env` with
+`APITOGO_CONFIG_AUTHENTICATION__*` (never commit those values).
 
 :::
 
-## Example
-
-Below is an example of the default APIToGo configuration. You can edit this configuration to suit
-your own needs.
-
-```ts title=apitogo.config.ts
-import type { ApitogoConfig } from "@lukoweb/apitogo";
-
-const config: ApitogoConfig = {
-  navigation: [
-    {
-      type: "category",
-      label: "Documentation",
-      items: ["introduction", "example"],
-    },
-    { type: "link", to: "api", label: "API Reference" },
-  ],
-  redirects: [{ from: "/", to: "/docs/introduction" }],
-  apis: {
-    type: "file",
-    input: "./apis/openapi.yaml",
-    path: "/api",
-  },
-  docs: {
-    files: "/pages/**/*.{md,mdx}",
-  },
-};
-
-export default config;
-```
-
-## Configuration options
-
-### `apis`
-
-There are multiple options for referencing your OpenAPI document. The example below uses a URL to an
-OpenAPI document, but you can also use a local file path. For full details on the options available,
-see the [API Reference](./api-reference.md).
+## Minimal example
 
-```ts
+```json title=config.json
 {
-  // ...
-  "apis": {
-    "type": "url",
-    "input": "https://petstore3.swagger.io/api/v3/openapi.json",
-    "path": "/api"
-  }
-  // ...
-}
-```
-
-### `site`
-
-Controls global page attributes across the site, including logos and the site title.
-
-**Example:**
-
-```ts
-{
-  // ...
   "site": {
-    "title": "Our Documentation",
+    "title": "My API",
     "logo": {
-      "src": {
-        "light": "/logos/apitogo-light.svg",
-        "dark": "/logos/apitogo-dark.svg"
-      },
-      "width": "99px"
+      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
+      "alt": "My API",
+      "width": "130px"
     }
-  }
-  // ...
-}
-```
-
-### `navigation`
-
-Defines navigation for both the top bar and the sidebar. Items can be categories, links or custom
-pages.
-
-```ts
-{
-  // ...
+  },
+  "authentication": {
+    "enabled": true,
+    "type": "dev-portal"
+  },
+  "modules": {
+    "docs": { "files": "/pages/**/*.{md,mdx}" },
+    "landing": { "enabled": true, "path": "/", "layout": "landing" },
+    "userPanel": {
+      "enabled": true,
+      "dashboard": { "enabled": true },
+      "userManagement": { "enabled": true }
+    }
+  },
   "navigation": [
     { "type": "category", "label": "Docs", "items": ["introduction"] },
     { "type": "link", "to": "api", "label": "API Reference" }
-  ]
-  // ...
+  ],
+  "redirects": [{ "from": "/", "to": "/introduction" }],
+  "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
 }
 ```
 
-### `theme`
+Scaffolded projects and MCP (`create_dev_portal` / `apply_product_intent`) produce this layout. You
+can change the site via MCP tools or by editing files — see [MCP overview](../mcp/overview.md).
+
+## Modules vs legacy root keys
 
-Allows you to control the dark and light themes that persist across each MDX page, and the API
-reference.
+Prefer `modules.*`:
 
-You can customize your theme as much as you want using
-[ShadCDN UI theme variables](https://ui.shadcn.com/docs/theming#list-of-variables). In the example
-below only the `primary` and `primaryForeground` variables are used but you can add any additional
-variables from ShadCDN UI that you would like to change.
+| Prefer                         | Legacy (still migrated on load) |
+| ------------------------------ | ------------------------------- |
+| `modules.docs`                 | root `docs`                     |
+| `modules.userPanel.apiKeys`    | root `apiKeys`                  |
+| `modules.userPanel.plans.*`    | root `plans` / `pricing.enabled` |
 
-**Tip**: Use the
-[ShadCDN UI Theme Generator](https://zippystarter.com/tools/shadcn-ui-theme-generator) to create a
-great looking theme based off your primary color.
+## Common options
+
+These fields usually live in `apitogo.config.json`.
+
+### `apis`
 
-**Example:**
+OpenAPI input as a local file or URL. See [API Reference](./api-reference.md).
 
-```ts
+```json
 {
-  // ...
-  "theme": {
-    "light": {
-      "primary": "316 100% 50%",
-      "primaryForeground": "360 100% 100%"
-    },
-    "dark": {
-      "primary": "316 100% 50%",
-      "primaryForeground": "360 100% 100%"
+  "apis": [
+    {
+      "type": "file",
+      "input": "./apis/openapi.yaml",
+      "path": "api"
     }
-  }
-  // ...
+  ]
 }
 ```
 
-### `metadata`
+### `site`
 
-Controls the site metadata for your documentation. All possible options are outlined in the example
-below.
+Site title and logo (`site.title`, `site.logo`).
 
-**Example:**
+### `navigation`
 
-```ts
-{
-  // ...
-  "metadata": {
-    "title": "Example Website Title",
-    "description": "This is an example description for the website.",
-    "logo": "https://example.com/logo.png",
-    "favicon": "https://example.com/favicon.ico",
-    "generator": "Website Generator 1.0",
-    "applicationName": "Example App",
-    "referrer": "no-referrer",
-    "keywords": ["example", "website", "metadata", "SEO"],
-    "authors": ["John Doe", "Jane Smith"],
-    "creator": "John Doe",
-    "publisher": "Example Publisher Inc."
-  }
-  // ...
-}
-```
+Top bar and sidebar: categories, links, custom pages (custom pages with React elements belong in
+TSX). See [Navigation](./navigation.mdx).
 
-### `docs`
+### `theme`
 
-Configures where your non API reference documentation can be found in your folder structure. The
-default is shown in the example below and you don't need to change it unless you want a different
-structure in place, or to have it match an existing structure that you already have.
+Light/dark theme tokens and optional `customCss`. See
+[Colors & theme](../customization/colors-theme.mdx).
 
-**Example:**
+### `metadata`
 
-```ts
-{
-  // ...
-  "docs": {
-    "files": "/pages/**/*.{md,mdx}"
-  }
-  // ...
-}
-```
+HTML metadata (`title`, `favicon`, `description`, etc.).
 
-### `sitemap`
+### `modules.docs`
 
-Controls the sitemap for your documentation. All possible options are outlined in the example below.
+Docs glob and options (publish Markdown, LLMs, default page options). Prefer this over root `docs`.
+See [Docs module](./docs.md).
 
-```ts
+### `sitemap`
+
+```json
 {
-  // ...
   "sitemap": {
-    // The base url for your site
-    // Required
     "siteUrl": "https://example.com",
-    // The change frequency for the pages
-    // Defaults to daily
     "changefreq": "daily",
-    // The priority for the pages
-    // Defaults to 0.7
     "priority": 0.7,
-    // The output directory for the sitemap
-    // Defaults to undefined
-    "outDir": "sitemaps/",
-    // Whether to include the last modified date
-    // Defaults to true
     "autoLastmod": true,
-    // The pages to exclude from the sitemap
-    // Can also be a function that returns an array of paths
-    // () => Promise<string[]>
-    "exclude": ["/404", "/private/page"]
+    "exclude": ["/404"]
   }
-  // ...
 }
 ```
 
 ### `redirects`
 
-Implements any page redirects you want to use. This gives you control over the resource names in the
-URL.
-
-**Example:**
-
-```ts
+```json
 {
-  // ...
   "redirects": [
-    { "from": "/", "to": "/documentation/introduction" },
-    { "from": "/documentation", "to": "/documentation/introduction" }
+    { "from": "/", "to": "/introduction" },
+    { "from": "/docs", "to": "/introduction" }
   ]
-  // ...
-}
-```
-
-### `port`
-
-The port on which the development server will run. Defaults to `3000`. This option can also be
-passed to the CLI as `--port' (which takes precedence).
-
-```ts
-{
-  "port": 9001
-}
-```
-
-If the port is already in use, the next available port will be used.
-
-### `basePath`
-
-Sets the base path for your documentation site. This is useful when you want to host your
-documentation under a specific path.
-
-```ts
-{
-  basePath: "/docs",
-  // A page defined as `/intro` would result in: https://example.com/docs/intro
-}
-```
-
-### `canonicalUrlOrigin`
-
-Sets the canonical [origin URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin) for
-your documentation site. This is used for SEO purposes and helps search engines understand the
-preferred version of a page.
-
-```ts
-{
-  basePath: '/docs',
-  canonicalUrlOrigin: "https://example.com",
-  // visiting the page `/intro` would result in:
-  // https://example.com/docs/intro
-}
-```
-
-This is the resulting HTML that will be added to the `<head>` of your pages:
-
-```html
-<link rel="canonical" href="https://example.com/docs/intro" />
-```
-
-### `cdnUrl`
-
-Configures the CDN URL for your documentation site's assets. You can provide either a string for a
-single CDN URL or an object to specify different URLs for base and media assets.
-
-```ts
-// Single CDN URL
-{
-  cdnUrl: "https://cdn.example.com"
-}
-
-// Separate URLs for base and media assets
-{
-  cdnUrl: {
-    base: "https://cdn.example.com",
-    media: "https://media.example.com"
-  }
 }
 ```
 
-### `https`
+### `port`, `basePath`, `canonicalUrlOrigin`, `cdnUrl`, `https`
 
-Enables HTTPS for the dev server. `key` and `cert` are required and `ca` is optional.
+Dev-server and hosting helpers (often in JSON or still settable from a TS config for advanced
+sites):
 
-```ts
-{
-  "https": {
-    "key": "/path/to/key.pem",
-    "cert": "/path/to/cert.pem",
-    "ca": "/path/to/ca.pem"
-  }
-}
-```
+- `port` — default `3000` (CLI `--port` wins)
+- `basePath` — host under a subpath
+- `canonicalUrlOrigin` — SEO canonical origin
+- `cdnUrl` — string or `{ base, media }`
+- `https` — `{ key, cert, ca? }` for the local HTTPS server
 
 ### `enableStatusPages`
 
-Enables static generation of status pages for your site. This results in several files (404.html,
-500.html, etc.) being generated in the `dist` directory. This is useful as many hosting providers
-will serve these files automatically when a user visits a non-existent page or encounters an error.
-
-This option is enabled by default, but you can disable it if you don't need these pages.
-
-```ts
-{
-  enableStatusPages: false;
-}
-```
-
-## Multiple Files
+When `true` (default), the build emits static status pages such as `404.html` in `dist`.
 
-The configuration file is a standard JavaScript or TypeScript file, so you can split it into
-multiple files if you prefer. This can be useful if you have a large configuration or want to keep
-your code organized.
+## Navigation
 
-For example, if you wanted to move your navigation configuration to a separate file, you could
-create a new file called `navigation.ts` and export the navigation configuration from there.
+Put navigation in `apitogo.config.json`, or keep large trees in a separate module (for example
+`sidebar.ts`) and wire them into your site config.
 
-```ts
-// navigation.ts
-import type { Navigation } from "@lukoweb/apitogo";
+## Related
 
-export const navigation: Navigation = [
-  {
-    type: "category",
-    label: "Documentation",
-    items: ["example", "other-example"],
-  },
-];
-```
-
-Then you can import the navigation configuration into your main configuration file.
-
-```ts title=apitogo.config.ts
-// apitogo.config.ts
-import type { ApitogoConfig } from "@lukoweb/apitogo";
-import { navigation } from "./navigation";
-
-const config = {
-  // ...
-  navigation,
-  // ...
-};
-
-export default config;
-```
+- [Manifest (`apitogo.config.json`)](./manifest.md)
+- [Make config (CLI)](./make-config.mdx)
+- [Authentication](./authentication.md)
+- [MCP overview](../mcp/overview.md)

package/docs/configuration/protected-routes.md

@@ -25,7 +25,7 @@ We are working on an additional offering that secures this data server-side.
 The simplest way to protect routes is to provide an array of path patterns. Users must be
 authenticated to access these routes.
 
-```typescript title="apitogo.config.ts"
+```typescript title="config"
 {
   // ...
   protectedRoutes: [
@@ -47,7 +47,7 @@ to access.
 For more complex authorization logic, you can provide a record mapping route patterns to custom
 callback functions:
 
-```typescript title="apitogo.config.ts"
+```typescript title="config"
 {
   // ...
   protectedRoutes: {
@@ -98,7 +98,7 @@ but lack permission. This is useful for building role-based or attribute-based a
 - **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
   page is displayed instead of the route content.
 
-```typescript title="apitogo.config.ts"
+```typescript title="config"
 {
   // ...
   protectedRoutes: {

package/docs/configuration/search.md

@@ -87,14 +87,15 @@ documentation sites. You can apply for the free DocSearch program or use your ow
 npm install @zudoku/plugin-search-algolia
 ```
 
-### Configuration
+The published package name is still `@zudoku/plugin-search-algolia` (APIToGo Algolia search plugin).
+Add it via the `plugins` array in your site config.
 
-Import the plugin and add it to the `plugins` array in your APIToGo configuration:
+### Configuration
 
 ```typescript
 import { algoliaSearchPlugin } from "@zudoku/plugin-search-algolia";
 
-const config = {
+export default {
   plugins: [
     algoliaSearchPlugin({
       appId: "YOUR_APP_ID",

package/docs/configuration/site.md

@@ -14,7 +14,7 @@ We offer you to customize the main aspects of your APIToGo site's appearance and
 
 **Title**, **logo** can be configured in under the `site` property:
 
-```tsx title=apitogo.config.tsx
+```tsx title=config
 const config = {
   site: {
     title: "My API Documentation",
@@ -37,7 +37,7 @@ const config = {
 
 Set the title of your site next to the logo in the header:
 
-```tsx title=apitogo.config.tsx
+```tsx title=config
 {
   site: {
     title: "My API Documentation",
@@ -49,7 +49,7 @@ Set the title of your site next to the logo in the header:
 
 Configure the site's logo with different versions for light and dark themes:
 
-```tsx title=apitogo.config.tsx
+```tsx title=config
 {
   site: {
     logo: {
@@ -81,7 +81,7 @@ We allow you to fully customize all colors, borders, etc - read more about it in
 
 Add a banner message to the top of the page:
 
-```tsx title=apitogo.config.tsx
+```tsx title=config
 {
   site: {
     banner: {
@@ -102,7 +102,7 @@ details.
 
 Here's a comprehensive example showing all available page configuration options:
 
-```tsx title=apitogo.config.tsx
+```tsx title=config
 {
   site: {
     title: "My API Documentation",

package/docs/configuration/slots.mdx

@@ -11,7 +11,7 @@ They allow you to extend the default layout and functionality without modifying
 
 ## Configuration
 
-You can define slots in your `apitogo.config.tsx` file using the `slots` property:
+You can define slots in your `apitogo.config.json` file using the `slots` property:
 
 ```tsx
 import type { ApitogoConfig } from "@lukoweb/apitogo";

package/docs/custom-plugins.md

@@ -65,7 +65,7 @@ const apiIdentityPlugin: ApitogoPlugin = {
   },
 };
 
-// In your apitogo.config.tsx
+// In your site config
 const config: ApitogoConfig = {
   // ... other config
   plugins: [apiIdentityPlugin],

package/docs/customization/colors-theme.mdx

@@ -34,7 +34,7 @@ You can manually define colors for both light and dark modes, either by extendin
 hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by
 [Tailwind CSS](https://tailwindcss.com):
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     light: {
@@ -136,7 +136,7 @@ the great [tweakcn](https://tweakcn.com/) visual theme editor.
    <Framed align="start">![](./tweakcn2.webp)</Framed>
 
 1. Add it to your configuration:
-   ```ts title=apitogo.config.ts
+   ```ts title=config
    const config = {
      theme: {
        registryUrl: "https://tweakcn.com/r/themes/northern-lights.json",
@@ -152,7 +152,7 @@ the great [tweakcn](https://tweakcn.com/) visual theme editor.
 
 You can still override specific values if needed:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     registryUrl: "https://tweakcn.com/api/registry/theme/xyz123",
@@ -169,7 +169,7 @@ const config = {
 
 Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     customCss: `
@@ -191,7 +191,7 @@ Changes to `customCss` require restarting the development server to take effect.
 
 ### CSS String
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     customCss: `
@@ -205,7 +205,7 @@ const config = {
 
 ### CSS Object
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     customCss: {
@@ -223,7 +223,7 @@ APIToGo comes with a built-in default theme based on
 [shadcn/ui zinc base colors](https://ui.shadcn.com/docs/theming#zinc). If you want to start
 completely from scratch without any default styling, you can disable the default theme:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     noDefaultTheme: true,
@@ -239,7 +239,7 @@ complete control over your theme. Changing this requires to restart the developm
 
 Here's a comprehensive example combining multiple theming approaches:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     // Import base theme from registry