@lukoweb/apitogo 0.1.24 → 0.1.37

package/docs/configuration/sentry.mdx

@@ -0,0 +1,44 @@
+---
+sidebar_icon: bug
+---
+
+# Sentry
+
+Sentry is a popular error tracking tool that helps you monitor and fix crashes in real time. It
+provides you with detailed error reports, so you can quickly identify and resolve issues before they
+affect your users.
+
+## Enable Sentry
+
+1. To enable it you have to first install the optional dependency `@sentry/react`.
+
+```bash
+npm install --save @sentry/react
+```
+
+2. And then set the `SENTRY_DSN` environment variable in your APIToGo project.
+
+```bash
+
+SENTRY_DSN=https://your-sentry-dsn
+```
+
+## Release management
+
+However this does not handle release management for you. For that you can
+[create a custom `vite.config.ts`](./vite-config) and use the `@sentry/vite-plugin` plugin.
+
+```ts
+import { sentryVitePlugin } from "@sentry/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    sentryVitePlugin({
+      authToken: "your-token",
+      org: "your-org",
+      project: "your-project",
+    }),
+  ],
+});
+```

package/docs/configuration/site.md

@@ -0,0 +1,124 @@
+---
+sidebar_label: Branding & Layout
+sidebar_icon: layout-dashboard
+description:
+  Customize your APIToGo site's branding, logo, banner, and layout options with detailed
+  configuration examples and guidance.
+---
+
+# Branding & Layout
+
+We offer you to customize the main aspects of your APIToGo site's appearance and behavior.
+
+## Branding
+
+**Title**, **logo** can be configured in under the `site` property:
+
+```tsx title=apitogo.config.tsx
+const config = {
+  site: {
+    title: "My API Documentation",
+    logo: {
+      src: {
+        light: "/path/to/light-logo.png",
+        dark: "/path/to/dark-logo.png",
+      },
+      alt: "Company Logo",
+      href: "/",
+    },
+    // Other options...
+  },
+};
+```
+
+### Available Options
+
+#### Title
+
+Set the title of your site next to the logo in the header:
+
+```tsx title=apitogo.config.tsx
+{
+  site: {
+    title: "My API Documentation",
+  }
+}
+```
+
+#### Logo
+
+Configure the site's logo with different versions for light and dark themes:
+
+```tsx title=apitogo.config.tsx
+{
+  site: {
+    logo: {
+      src: {
+        light: "/light-logo.png",
+        dark: "/dark-logo.png"
+      },
+      alt: "Company Logo",
+      width: "120px", // optional width
+      href: "/", // optional link target (defaults to "/")
+      reloadDocument: true, // optional, defaults to true
+    }
+  }
+}
+```
+
+The `reloadDocument` option controls whether clicking the logo triggers a full page reload (`true`,
+the default) or uses client-side SPA navigation (`false`). A full reload is useful when your landing
+page is served by a different system (e.g. a CMS) outside of APIToGo.
+
+#### Colors & Theme
+
+We allow you to fully customize all colors, borders, etc - read more about it in
+[Colors & Themes](/docs/customization/colors-theme)
+
+## Layout
+
+### Banner
+
+Add a banner message to the top of the page:
+
+```tsx title=apitogo.config.tsx
+{
+  site: {
+    banner: {
+      message: "Welcome to our beta documentation!",
+      color: "info", // "note" | "tip" | "info" | "caution" | "danger" or custom
+      dismissible: true
+    }
+  }
+}
+```
+
+### Footer
+
+The footer configuration has its own dedicated section. See the [Footer Configuration](./footer) for
+details.
+
+## Complete Example
+
+Here's a comprehensive example showing all available page configuration options:
+
+```tsx title=apitogo.config.tsx
+{
+  site: {
+    title: "My API Documentation",
+    logo: {
+      src: {
+        light: "/images/logo-light.svg",
+        dark: "/images/logo-dark.svg"
+      },
+      alt: "Company Logo",
+      width: "100px",
+    },
+    banner: {
+      message: "Welcome to our documentation!",
+      color: "info",
+      dismissible: true
+    },
+  }
+}
+```

package/docs/configuration/slots.mdx

@@ -0,0 +1,125 @@
+---
+title: Slots
+sidebar_icon: between-horizontal-start
+description:
+  Learn how to use slots to inject custom content into predefined locations throughout your APIToGo
+  site.
+---
+
+Slots provide a powerful way to inject custom content into predefined locations throughout APIToGo.
+They allow you to extend the default layout and functionality without modifying the core components.
+
+## Configuration
+
+You can define slots in your `apitogo.config.tsx` file using the `slots` property:
+
+```tsx
+import type { ApitogoConfig } from "@lukoweb/apitogo";
+import { Button } from "@lukoweb/apitogo/ui/Button.js";
+
+const config: ApitogoConfig = {
+  // ... other config
+  slots: {
+    "head-navigation-end": () => (
+      <div className="flex items-center gap-2">
+        <Button variant="ghost" size="icon" asChild>
+          <a href="https://github.com/your-repo">
+            <GithubIcon className="w-4 h-4" />
+          </a>
+        </Button>
+      </div>
+    ),
+    "footer-before": <div>Custom footer content</div>,
+  },
+};
+
+export default config;
+```
+
+## Slot Types
+
+Slots accept either:
+
+- **React components/elements**: JSX elements
+- **Function components**: Functions that return JSX elements and receive routing props
+
+```tsx
+slots: {
+  // JSX element
+  "footer-after": <CustomFooter />,
+
+  // Function with access to routing props
+  "head-navigation-end": ({ navigate, location, searchParams }) => (
+    <Button
+      onClick={() => navigate('/settings')}
+      variant={location.pathname === '/settings' ? 'default' : 'ghost'}
+    >
+      Settings
+    </Button>
+  ),
+}
+```
+
+Functions receive an object with routing properties:
+
+- `location` - Current route location
+- `navigate` - Navigation function
+- `searchParams` - URL search parameters
+- `setSearchParams` - Function to update search parameters
+- `params` - Route parameters
+
+## Type Safety
+
+APIToGo provides full TypeScript support for slot names. All predefined slot names will show up with
+autocomplete when you type them in your configuration.
+
+## Advanced Usage
+
+For more advanced slot usage, including programmatic slot management, dynamic content, and adding
+custom slot names, see the [Slot Component](/docs/components/slot) documentation.
+
+## Examples
+
+### Adding Social Links to Header
+
+```tsx
+slots: {
+  "head-navigation-end": () => (
+    <div className="flex items-center gap-2">
+      <Button variant="ghost" size="icon" asChild>
+        <a href="https://github.com/your-org" target="_blank">
+          <GithubIcon className="w-4 h-4" />
+        </a>
+      </Button>
+      <Button variant="ghost" size="icon" asChild>
+        <a href="https://discord.gg/your-server" target="_blank">
+          <DiscordIcon className="w-4 h-4" />
+        </a>
+      </Button>
+    </div>
+  ),
+}
+```
+
+### Dynamic Content with Routing
+
+```tsx
+slots: {
+  "top-navigation-side": ({ location, navigate }) => (
+    <div className="flex items-center gap-2">
+      <Button
+        variant={location.pathname === '/docs' ? 'default' : 'ghost'}
+        onClick={() => navigate('/docs')}
+      >
+        Documentation
+      </Button>
+      <Button
+        variant={location.pathname === '/api' ? 'default' : 'ghost'}
+        onClick={() => navigate('/api')}
+      >
+        API Reference
+      </Button>
+    </div>
+  ),
+}
+```

package/docs/configuration/vite-config.md

@@ -0,0 +1,18 @@
+---
+title: Vite Config
+sidebar_icon: server-crash
+---
+
+APIToGo is built on top of [Vite](https://vite.dev/) and can be customized using a
+[Vite configuration file](https://vite.dev/config/) if advanced functionality is required.
+
+Not all configurations are supported in APIToGo, but common tasks like adding plugins will generally
+work as expected. Simply create a `vite.config.ts` file in the root of your project and set the
+configuration options as needed.
+
+APIToGo will automatically pick up the configuration file and will use it to augment the built-in
+configuration.
+
+You can find an
+[example project](https://github.com/lukoweb/apitogo-doc-tool/tree/main/examples/with-vite-config)
+on GitHub that demonstrates how to use a custom Vite configuration with APIToGo.

package/docs/custom-plugins.md

@@ -0,0 +1,285 @@
+---
+title: Custom Plugins
+sidebar_icon: list-end
+---
+
+APIToGo is highly extensible. You can create custom plugins to add new functionality to your
+documentation site. This guide will show you how to create and use plugins in your APIToGo
+configuration.
+
+## Plugin Types
+
+All plugins in APIToGo must implement the `ApitogoPlugin` type, which is a union of these plugin
+interfaces:
+
+- **CommonPlugin**: Basic plugin with initialization, head elements, and MDX component customization
+- **ProfileMenuPlugin**: Add custom items to the profile menu
+- **NavigationPlugin**: Define custom routes and sidebar items
+- **ApiIdentityPlugin**: Provide API identities for testing
+- **SearchProviderPlugin**: Implement custom search functionality
+- **EventConsumerPlugin**: Handle custom events
+- **TransformConfigPlugin**: Modify configuration at build-time
+
+## Defining Plugins
+
+You can define plugins in your APIToGo configuration using objects with explicit type declarations:
+
+### Common Plugin Example
+
+```tsx
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const commonPlugin: ApitogoPlugin = {
+  initialize: async (context) => {
+    // Initialization logic
+  },
+  getHead: () => <link rel="stylesheet" href="/custom-styles.css" />,
+  getMdxComponents: () => ({
+    // Custom MDX components
+  }),
+};
+
+const config: ApitogoConfig = {
+  // ... other config
+  plugins: [commonPlugin],
+};
+```
+
+### API Identity Plugin Example
+
+```tsx
+import type { ApitogoPlugin, ApiIdentity } from "@lukoweb/apitogo";
+
+const apiIdentityPlugin: ApitogoPlugin = {
+  getIdentities: async (context) => {
+    return [
+      {
+        label: "Test User",
+        id: "test-user",
+        authorizeRequest: (request: Request) => {
+          request.headers.set("Authorization", "Bearer test-token");
+          return request;
+        },
+      },
+    ] as ApiIdentity[];
+  },
+};
+
+// In your apitogo.config.tsx
+const config: ApitogoConfig = {
+  // ... other config
+  plugins: [apiIdentityPlugin],
+};
+```
+
+## Example Implementations
+
+Here are some common plugin implementations:
+
+### Google Tag Manager
+
+Below is a sample of adding the necessary scripts for GTM, but this could apply to any tag manager
+or tracking script.
+
+```tsx
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const commonPlugin: ApitogoPlugin = {
+  getHead: () => {
+    return (
+      <script>
+        {`
+    (function (w, d, s, l, i) {
+      w[l] = w[l] || [];
+      w[l].push({ "gtm.start": new Date().getTime(), event: "gtm.js" });
+      var f = d.getElementsByTagName(s)[0],
+        j = d.createElement(s),
+        dl = l != "dataLayer" ? "&l=" + l : "";
+      j.async = true;
+      j.src = "https://www.googletagmanager.com/gtm.js?id=" + i + dl;
+      f.parentNode.insertBefore(j, f);
+    })(window, document, "script", "dataLayer", "GTM-<YOUR GTM ID HERE>");`}
+      </script>
+    );
+  },
+};
+```
+
+#### Tracking `page_view` Events
+
+APIToGo is a single page application so typical `page_view` events are not captured by most
+analytics scripts or tag managers. Instead, you must listen to the `location`
+[event](./extending/events.md) with a plugin and log navigation changes in code.
+
+```tsx
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const navigationLoggerPlugin: ApitogoPlugin = {
+  events: {
+    location: ({ from, to }) => {
+      if (!from) return;
+      window.dataLayer.push({
+        event: "page_view",
+        page_path: to.pathname,
+        page_title: document.title,
+        page_location: window.location.href,
+      });
+    },
+  },
+};
+```
+
+If you are using TypeScript, you will also need to add the following type declaration to the file
+this plugin is declared
+
+```ts
+declare global {
+  interface Window {
+    dataLayer: Record<string, any>[];
+  }
+}
+```
+
+### Navigation Plugin
+
+```tsx
+import type { ApitogoPlugin, RouteObject } from "@lukoweb/apitogo";
+
+const navigationPlugin: ApitogoPlugin = {
+  getRoutes: (): RouteObject[] => {
+    return [
+      {
+        path: "/custom",
+        element: <CustomPage />,
+      },
+    ];
+  },
+  getSidebar: async (path: string) => {
+    // Return custom sidebar items
+    return {
+      items: [{ id: "custom", label: "Custom Page" }],
+    };
+  },
+};
+```
+
+### Wrapping Routes with Context or Layout
+
+You can wrap your plugin's routes with a context provider or custom layout using React Router's
+nested route pattern. The parent route renders an `<Outlet />` where child routes will appear.
+
+```tsx
+import { createContext, useContext } from "react";
+import type { ApitogoPlugin, RouteObject } from "@lukoweb/apitogo";
+import { Outlet } from "@lukoweb/apitogo/router";
+
+const MyContext = createContext("value");
+
+const pluginWithContext: ApitogoPlugin = {
+  getRoutes: () => [
+    {
+      element: (
+        <MyContext.Provider value="hello">
+          <Outlet />
+        </MyContext.Provider>
+      ),
+      children: [
+        { path: "/custom", element: <CustomPage /> },
+        { path: "/custom/nested", element: <NestedPage /> },
+      ],
+    },
+  ],
+};
+```
+
+All child routes will have access to `MyContext`. This pattern works for any wrapper including
+layouts, error boundaries, or data providers.
+
+### Dropdown Navigation Plugin
+
+```tsx
+import type { ApitogoPlugin, RouteObject } from "@lukoweb/apitogo";
+import { UserIcon } from "@lukoweb/apitogo/icons";
+
+const AccountPageNavItemPlugin: ApitogoPlugin = {
+  getRoutes: (): RouteObject[] => {
+    return [
+      {
+        path: "/account",
+        element: <Account />, // This is a custom page
+      },
+    ];
+  },
+  getProfileMenuItems: () => {
+    return [
+      {
+        label: "Account",
+        path: "/account",
+        category: "middle",
+        icon: UserIcon,
+      },
+    ];
+  },
+};
+```
+
+### Event Consumer Plugin
+
+```tsx
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const eventConsumerPlugin: ApitogoPlugin = {
+  events: {
+    location: ({ from, to }) => {
+      if (!from) {
+        console.log(`Initial navigation to: ${to.pathname}`);
+      } else {
+        console.log(`Navigation from ${from.pathname} to ${to.pathname}`);
+      }
+    },
+  },
+};
+```
+
+### Transform Config Plugin
+
+The `transformConfig` hook allows plugins to modify the APIToGo configuration at build-time. This is
+useful for dynamically adding navigation items, modifying theme settings, or adjusting any other
+configuration based on external data or conditions.
+
+```tsx
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const transformConfigPlugin: ApitogoPlugin = {
+  transformConfig: ({ config, merge }) => {
+    // Option 1: Use merge helper for deep merging
+    return merge({
+      slots: {
+        "head-navigation-start": () => <a href="/pricing">Pricing</a>,
+      },
+    });
+
+    // Option 2: Manual spread for full control
+    return {
+      ...config,
+      navigation: [
+        ...(config.navigation ?? []),
+        {
+          type: "link",
+          label: "System Status",
+          to: "https://status.example.com",
+          icon: "activity",
+        },
+      ],
+    };
+  },
+};
+```
+
+The `transformConfig` function receives an object with:
+
+- **config**: The current APIToGo configuration object
+- **merge**: A helper function that deep merges a partial config with the current config
+
+The function must return a full configuration object (either via `merge()` or manual spreading), or
+`void` to make no changes. The hook can also be async.