@lukoweb/apitogo 0.2.56 → 0.2.57

package/docs/configuration/docs.md

@@ -1,282 +0,0 @@
----
-title: Documentation
-navigation_label: Documentation
-navigation_icon: book
----
-
-APIToGo uses a file-based routing system for documentation pages, similar to many modern frameworks.
-This page explains how routing works and how to customize it.
-
-## File Based Routing
-
-By default, APIToGo automatically creates routes for all Markdown and MDX files based on their file
-path. Files are served at URLs that match their file structure, minus the file extension.
-
-### Basic Examples
-
-```text title="File tree"
-pages/
-├── introduction.md         → /introduction
-├── quickstart.mdx          → /quickstart
-├── guides/
-│   ├── getting-started.md  → /guides/getting-started
-│   └── advanced.md         → /guides/advanced
-└── api/
-    └── reference.md        → /api/reference
-```
-
-### File Extensions
-
-Both `.md` and `.mdx` files are supported:
-
-- `.md` files support standard Markdown with frontmatter
-- `.mdx` files support JSX components within Markdown
-
-The file extension is automatically removed from the URL.
-
-## Custom Paths
-
-You can override the default file-based routing by specifying custom paths in your navigation
-configuration. When a file has a custom path, it will only be accessible at that custom path, not at
-its original file-based path.
-
-### Navigation Configuration
-
-```tsx {5-6,13-14} title="config" showLineNumbers
-export default {
-  navigation: [
-    {
-      type: "doc",
-      file: "guides/getting-started.md",
-      path: "start-here", // Custom path
-      label: "Start Here",
-    },
-    {
-      type: "category",
-      label: "Advanced",
-      link: {
-        file: "guides/advanced.md",
-        path: "advanced-guide", // Custom path for category link
-      },
-      items: [
-        // ... other items
-      ],
-    },
-  ],
-};
-```
-
-In this example:
-
-- `guides/getting-started.md` is accessible at `/start-here` (not `/guides/getting-started`)
-- `guides/advanced.md` is accessible at `/advanced-guide` (not `/guides/advanced`)
-
-## Configuration Options
-
-Configure docs routing and behavior through the `docs` section in your config:
-
-```tsx title="config"
-export default {
-  docs: {
-    files: ["/pages/**/*.{md,mdx}"],
-    defaultOptions: {
-      toc: true,
-      disablePager: false,
-      showLastModified: true,
-      suggestEdit: {
-        url: "https://github.com/your-org/your-repo/edit/main/docs",
-        text: "Edit this page",
-      },
-    },
-  },
-};
-```
-
-### `files`
-
-**Type:** `string | string[]`  
-**Default:** `"/pages/**/*.{md,mdx}"`
-
-Glob patterns that specify which files to include as documentation pages. You can provide a single
-pattern or an array of patterns.
-
-```tsx title="config"
-// Single pattern
-docs: {
-  files: "/content/**/*.md";
-}
-
-// Multiple patterns
-docs: {
-  files: ["/pages/**/*.{md,mdx}", "/guides/**/*.md", "/tutorials/**/*.mdx"];
-}
-```
-
-### `defaultOptions`
-
-Default options applied to all documentation pages. These can be overridden on individual pages
-using frontmatter.
-
-#### `toc`
-
-**Type:** `boolean`  
-**Default:** `true`
-
-Whether to show the table of contents (TOC) by default.
-
-```tsx title="config"
-docs: {
-  defaultOptions: {
-    toc: false; // Hide TOC by default
-  }
-}
-```
-
-#### `disablePager`
-
-**Type:** `boolean`  
-**Default:** `false`
-
-Whether to disable the previous/next page navigation by default.
-
-```tsx title="config"
-docs: {
-  defaultOptions: {
-    disablePager: true; // Disable pager by default
-  }
-}
-```
-
-#### `showLastModified`
-
-**Type:** `boolean`  
-**Default:** `false`
-
-Whether to show the last modified date by default.
-
-```tsx title="config"
-docs: {
-  defaultOptions: {
-    showLastModified: true; // Show last modified date
-  }
-}
-```
-
-#### `suggestEdit`
-
-**Type:** `{ url: string; text?: string }`  
-**Default:** `undefined`
-
-Configuration for the "Edit this page" link.
-
-```tsx title="config"
-docs: {
-  defaultOptions: {
-    suggestEdit: {
-      url: "https://github.com/your-org/your-repo/edit/main/docs",
-      text: "Edit this page on GitHub"  // Optional custom text
-    }
-  }
-}
-```
-
-The `url` should be a template where the file path will be appended. For example, if your docs are
-in a `docs/pages/` directory, the URL might be
-`https://github.com/your-org/your-repo/edit/main/docs/pages`.
-
-#### `copyPage`
-
-**Type:** `boolean` **Default:** `undefined`
-
-Whether to show a copy button in the page header that allows users to copy the page markdown. This
-feature requires `publishMarkdown` to be enabled (see below).
-
-```tsx title="config"
-docs: {
-  defaultOptions: {
-    copyPage: true; // Enable copy button for all pages
-  }
-}
-```
-
-The copy button provides:
-
-- A primary "Copy page" action that copies the markdown to clipboard
-- A dropdown with additional options:
-  - Copy link to page
-  - Open markdown file (requires `publishMarkdown: true`)
-  - AI assistant options (Claude, ChatGPT by default — see [AI Assistants](./ai-assistants.md) to
-    customize)
-
-> **Note:** The copy button requires `publishMarkdown: true` to be set in your docs config. If
-> `copyPage` is enabled but `publishMarkdown` is not, a warning will be displayed.
-
-### `publishMarkdown`
-
-**Type:** `boolean` **Default:** `false`
-
-When enabled, generates `.md` files for each documentation page during build. Pages can then be
-accessed at their URL path with the `.md` extension appended (e.g., `/docs/quickstart.md`).
-
-```tsx title="config"
-docs: {
-  publishMarkdown: true,
-}
-```
-
-The generated markdown files:
-
-- Have frontmatter removed for cleaner content
-- Are accessible at `{page-url}.md` in both development and production
-- Are required for the `copyPage` button functionality
-- Are used by LLM features (see [llms.txt configuration](/docs/configuration/llms) for more details)
-
-### `llms`
-
-**Type:** `object` **Default:** `undefined`
-
-Configuration for generating LLM-friendly documentation files. See the
-[llms.txt configuration](/docs/configuration/llms) page for complete documentation.
-
-```tsx title="config"
-docs: {
-  llms: {
-    llmsTxt: true,        // Generate llms.txt summary file
-    llmsTxtFull: true,    // Generate llms-full.txt with complete content
-    includeProtected: false
-  }
-}
-```
-
-## Overriding Defaults
-
-You can override [default options](#defaultoptions) on individual pages using frontmatter:
-
-```markdown
----
-toc: false
-disablePager: true
-showLastModified: false
----
-
-# My Page
-
-This page has custom options that override the defaults.
-```
-
-## Route Resolution
-
-APIToGo resolves routes in the following order:
-
-1. **Custom paths from navigation** - If a file has a custom path defined in navigation, it's served
-   at that path
-2. **File-based paths** - All other files are served at their file-based paths
-
-## Best Practices
-
-1. **Use descriptive file names** - File names become part of the URL, so make them clear and
-   SEO-friendly
-2. **Organize with folders** - Use folder structure to group related content
-3. **Custom paths for better UX** - Use custom paths for important pages that need memorable URLs
-   (sometimes also called slugs)
-4. **Consistent naming** - Use consistent naming conventions for files and folders

package/docs/configuration/llms.md

@@ -1,90 +0,0 @@
----
-title: LLM-Friendly Documentation Export
-navigation_label: llms.txt
-navigation_icon: bot
----
-
-APIToGo can generate LLM-friendly versions of your documentation following the
-[llms.txt](https://llmstxt.org/) specification.
-
-During build, you can optionally generate:
-
-- **`.md` files** - Individual pages with frontmatter removed (via `publishMarkdown`)
-- **`llms.txt`** - Summary with links to all pages
-- **`llms-full.txt`** - Complete documentation in one file
-
-All options are disabled by default.
-
-## Configuration
-
-LLM features are configured through the `docs` section in your config:
-
-```tsx title="config"
-export default {
-  docs: {
-    files: "pages/**/*.{md,mdx}", // Your markdown files
-    publishMarkdown: true, // Generate .md files
-    llms: {
-      llmsTxt: true, // Generate llms.txt
-      llmsTxtFull: true, // Generate llms-full.txt
-      includeProtected: false, // Exclude protected routes
-    },
-  },
-};
-```
-
-All options are disabled by default.
-
-:::tip
-
-When enabled, markdown files are generated during build and deleted after creating the `llms.txt`
-files unless `publishMarkdown: true` is set (see
-[`publishMarkdown` docs](/docs/configuration/docs#publishmarkdown)).
-
-:::
-
-### `llmsTxt`
-
-**Type:** `boolean` **Default:** `false`
-
-Generates an `llms.txt` file with links to all documentation pages:
-
-```markdown title="llms.txt"
-# Documentation
-
-- [Quickstart](/docs/quickstart.md): Get started with APIToGo
-- [Writing](/docs/writing.md): A guide to writing documentation
-```
-
-### `llmsTxtFull`
-
-**Type:** `boolean` **Default:** `false`
-
-Generates `llms-full.txt` containing the complete content of all pages.
-
-### `includeProtected`
-
-**Type:** `boolean` **Default:** `false`
-
-By default, protected routes are excluded. Set to `true` to include them in the generated files.
-
-## Output
-
-Generated files are available in the output directory after build:
-
-```text
-dist/
-├── llms.txt           # Generated if llmsTxt: true
-├── llms-full.txt      # Generated if llmsTxtFull: true
-└── docs/
-    ├── quickstart.md  # Generated if publishMarkdown: true
-    ├── writing.md
-    └── ...
-```
-
-**Important:** Individual `.md` files are only kept in the final build if `publishMarkdown: true`.
-If only `llmsTxt` or `llmsTxtFull` is enabled, the `.md` files are generated temporarily during the
-build but deleted after the `llms.txt` files are created.
-
-Redirect pages, error pages (400, 404, 500), and protected routes (unless `includeProtected: true`)
-are automatically excluded from all generated files.

package/docs/configuration/manifest.md

@@ -1,129 +0,0 @@
-# Site configuration (apitogo.config.json)
-
-Dev portal sites use `apitogo.config.json` for site settings, plans, authentication, and backend
-metadata, with optional `.env` overrides for secrets and local tweaks.
-
-## Files
-
-| File                  | Purpose                                                     |
-| --------------------- | ----------------------------------------------------------- |
-| `apitogo.config.json` | Committed defaults: site, modules, authentication, backend  |
-| `.env`                | Public client vars + publish secrets via `APITOGO_CONFIG_*` |
-
-## Canonical shape
-
-```json
-{
-  "site": {
-    "title": "My API",
-    "logo": {
-      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
-      "alt": "My API",
-      "width": "130px"
-    }
-  },
-  "authentication": {
-    "enabled": true,
-    "type": "dev-portal",
-    "apiBaseUrl": "https://your-dev-portal-api.example.com"
-  },
-  "gateway": {
-    "authMode": "bringYourOwnOidc",
-    "oidcMetadataUrl": "https://login.example.com/.well-known/openid-configuration",
-    "publicRoutes": ["/health"],
-    "cors": {
-      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
-    }
-  },
-  "modules": {
-    "docs": { "files": "/pages/**/*.{md,mdx}" },
-    "landing": { "enabled": true, "path": "/", "layout": "landing" },
-    "userPanel": {
-      "enabled": true,
-      "dashboard": { "enabled": true },
-      "userManagement": { "enabled": true },
-      "plans": {
-        "enabled": true,
-        "items": [
-          {
-            "sku": "free",
-            "displayName": "Free",
-            "priceAmount": 0
-          }
-        ]
-      }
-    }
-  },
-  "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
-}
-```
-
-- **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
-- **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
-- **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
-  `modules.userPanel.plans.items`. Edit the manifest by hand. In a config version 2 project,
-  `npx apitogo config` writes plans to `apitogo/plans.json` instead. See
-  [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
-- **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
-- **Gateway:** top-level `gateway` (not under `authentication`). See [Gateway CORS](#gateway-cors)
-  and [Gateway plans](./plans.md).
-
-## Gateway CORS
-
-Browser calls from your developer portal (and any other SPA) to the API gateway are cross-origin.
-APItoGo always allows the portal site origin. Add extra origins under `gateway.cors.allowedOrigins`
-when tenant apps or local frontends call the gateway:
-
-```json
-{
-  "gateway": {
-    "cors": {
-      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
-    }
-  }
-}
-```
-
-| Rule            | Detail                                                                              |
-| --------------- | ----------------------------------------------------------------------------------- |
-| Portal origin   | Always allowed by the platform (`https://{your-portal-host}`). Do not list it here. |
-| Extra origins   | Absolute `http://` or `https://` origins only — no path, query, or fragment.        |
-| Wildcard        | `"*"` is allowed (replaces the list; credentials stay off).                         |
-| Empty / omitted | Portal playground still works; only extras are missing.                             |
-
-Apply with `npx apitogo deploy` / `publish_dev_portal` so APIM policies pick up the change.
-
-## Environment variables
-
-Public client URL (mirrors `authentication.apiBaseUrl`):
-
-```sh
-VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-Nested config overrides (uppercase SCREAMING_SNAKE path segments; camelCase still accepted):
-
-```sh
-APITOGO_CONFIG_SITE__TITLE=My Local Site
-APITOGO_CONFIG_PRICING__ENABLED=true
-APITOGO_CONFIG_PROJECT_ID=your-local-project-id
-APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-Publish secrets (uncomment in `.env`, never commit):
-
-```sh
-APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
-APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
-APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
-```
-
-## Related
-
-- [Gateway plans](./plans.md)
-- [Authentication](./authentication.md)
-- [Overview](./overview.md)
-- [MCP overview](../mcp/overview.md)
-- [Environment variables](../guides/environment-variables.md)