@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/custom-plugins.md

@@ -1,285 +0,0 @@
----
-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 site config
-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.

package/docs/deploy/apache-nginx.md

@@ -1,41 +0,0 @@
----
-title: Apache & Nginx
----
-
-APIToGo generates static HTML files for each page during build. Your server must be configured to
-serve these files correctly.
-
-## Apache
-
-Create a `.htaccess` file in your document root (alongside `index.html`):
-
-```apache
-RewriteEngine On
-
-RewriteCond %{REQUEST_FILENAME} !-f
-RewriteCond %{REQUEST_FILENAME}.html -f
-RewriteRule ^(.*)$ $1.html [L]
-
-RewriteCond %{REQUEST_FILENAME} !-f
-RewriteCond %{REQUEST_FILENAME} !-d
-RewriteRule ^ index.html [L]
-```
-
-Requires `mod_rewrite` enabled and `AllowOverride All` in your Apache configuration.
-
-## Nginx
-
-Add a `try_files` directive to your server block:
-
-```nginx
-server {
-    listen 80;
-    server_name example.com;
-    root /var/www/html;
-    index index.html;
-
-    location / {
-        try_files $uri $uri.html $uri/ /index.html;
-    }
-}
-```

package/docs/deploy/cloudflare-pages.md

@@ -1,74 +0,0 @@
----
-title: Cloudflare Pages
----
-
-[Pages](https://developers.cloudflare.com/pages) is a low configuration way of publishing your
-documentation.
-
-## Prerequisites
-
-To publish your site to Cloudflare Pages you will need:
-
-- A Cloudflare account
-
-Optionally, you may also need:
-
-- A GitHub or GitLab account (optional)
-
-## Deploying to Pages
-
-Cloudflare offers three different ways to create Pages sites.
-
-1. Using the [Cloudflare CLI](https://developers.cloudflare.com/pages/get-started/c3/)
-2. Directly uploading the files using
-   [drag and drop](https://developers.cloudflare.com/pages/get-started/direct-upload/#drag-and-drop),
-   or their
-   [Wrangler CLI](https://developers.cloudflare.com/pages/get-started/direct-upload/#wrangler-cli)
-3. Integration with
-   [GitHub or GitLab](https://developers.cloudflare.com/pages/get-started/git-integration/)
-
-It's up to you which approach you choose but the fastest approach is to use the Wrangler CLI.
-
-## Deploy using Wrangler
-
-Wrangler makes light work of deploying to Cloudflare Pages, but first you need to get your files in
-order.
-
-Build the static version of your documentation site by running:
-
-```bash
-npm run build
-```
-
-This will generate a new folder called `dist` that contains all the files that you need to deploy.
-
-Next, if you don't already have one, create a new Pages project:
-
-```bash
-npx wrangler pages project create
-```
-
-Finally, deploy the files to the new project:
-
-```bash
-npx wrangler pages deploy ./dist
-```
-
-Within a few seconds the site will be live and viewable at `<your-project-name>.pages.dev`.
-
-## Accurate Last Modified Dates
-
-If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,
-APIToGo automatically tracks the last modified date of your documentation pages using Git history.
-However, Cloudflare Pages performs shallow clones by default, which can result in inaccurate "Last
-Modified" dates for pages that haven't been updated recently.
-
-To ensure accurate last modified dates when using Git integration with Cloudflare Pages, modify your
-build command to fetch the full history before building:
-
-```bash
-git fetch --unshallow && npm run build
-```
-
-This command converts the shallow clone to a full clone before running your build, ensuring all
-pages show their correct last modified dates.

package/docs/deploy/direct-upload.md

@@ -1,17 +0,0 @@
----
-title: Upload/FTP
----
-
-APIToGo can produce a build of static HTML, JavaScript and CSS files that you can deploy directly to
-your own server.
-
-## Build locally
-
-To prepare the files you need to upload to your server, you will need to use the build command.
-
-```bash
-npm run build
-```
-
-Once complete, you will see a new `dist` folder in the root of your project that includes the files
-you need to upload.

package/docs/deploy/github-pages.md

@@ -1,49 +0,0 @@
----
-title: GitHub Pages
----
-
-[GitHub Pages](https://pages.github.com/) is a great way to publish your documentation, especially
-if you are using GitHub for source control.
-
-## Prerequisites
-
-To publish your site to GitHub Pages you will need:
-
-- A GitHub account
-
-## Deploying to GitHub Pages
-
-Use the
-[GitHub Actions Workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow).
-
-You might need to configure the `basePath` in your site config.ts depending on how your site is
-hosted. For instance, if your site is available at username.github.io/your-repo/ you would set the
-`basePath` to `/your-repo`.
-
-```typescript
-import type { ApitogoConfig } from "@lukoweb/apitogo";
-
-const config: ApitogoConfig = {
-  basePath: "/your-repo",
-  //...
-};
-```
-
-## Accurate Last Modified Dates
-
-If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,
-APIToGo automatically tracks the last modified date of your documentation pages using Git history.
-However, GitHub Actions performs shallow clones by default, which can result in inaccurate "Last
-Modified" dates for pages that haven't been updated recently.
-
-To ensure accurate last modified dates, configure the `actions/checkout` step to fetch the full
-history:
-
-```yaml
-- uses: actions/checkout@v4
-  with:
-    fetch-depth: 0 # Fetch all history for all branches and tags
-```
-
-For more details, see the
-[actions/checkout documentation](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches).

package/docs/deploy/vercel.md

@@ -1,101 +0,0 @@
----
-title: Vercel
----
-
-[Vercel](https://vercel.com) offers multiple ways to deploy to its service, including via GitHub,
-and their CLI. You can read more about them in their
-[Deployments Overview](https://vercel.com/docs/deployments/overview).
-
-## Prerequisites
-
-To deploy to Vercel you will need:
-
-- A Vercel account (free)
-- A GitHub account (if deploying via GitHub)
-- The Vercel CLI
-
-Deploying your APIToGo powered documentation using the Vercel CLI is what we will cover in this
-guide.
-
-## Install the CLI
-
-To get started you need to install the CLI:
-
-```bash
-npm i -g vercel
-```
-
-## Setup a new project
-
-Next, set up a new Vercel project in the root of your docs:
-
-```bash
-vercel
-```
-
-This command will set up everything that is needed to deploy your documentation to Vercel.
-
-It will ask some specific questions including the project name and where the code is located. You
-can answer however you like for these.
-
-When you get to this step:
-
-```ansi
-No framework detected. Default Project Settings:
-- Build Command: `npm run vercel-build` or `npm run build`
-- Development Command: None
-- Install Command: `yarn install`, `pnpm install`, `npm install`, or `bun install`
-- Output Directory: `public` if it exists, or `.`
-? Want to modify these settings? (y/N)
-```
-
-Answer _Yes_ and select to modify the Output Directory.
-
-By default Vercel looks for a directory named `public`, but the APIToGo build will be found in
-`dist`. Set the output directory like this:
-
-```ansi
-? What's your Output Directory? dist
-```
-
-After this is complete, your site will build and Vercel will respond with the URL for you to test
-it.
-
-:::tip{title="Clean URLs"}
-
-You will almost certainly want to enable clean URLs for your site. This will remove the `.html`
-extension from your URLs. You can do this by adding a `cleanUrls` property to your `vercel.json`
-file. See the
-[Vercel Configuration](https://vercel.com/docs/projects/project-configuration#cleanurls) for more
-information.
-
-:::
-
-:::caution{title="Redirects"}
-
-If you have redirects in `apitogo.config.json`, you may also need matching entries in `vercel.json`.
-See the [Vercel Configuration](https://vercel.com/docs/projects/project-configuration#redirects) for
-more information.
-
-This is a current limitation. See [#115](https://github.com/lukoweb/apitogo-doc-tool/issues/151).
-
-:::
-
-## Accurate Last Modified Dates
-
-If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,
-APIToGo automatically tracks the last modified date of your documentation pages using Git history.
-However, Vercel performs shallow clones by default (only fetching the last 10 commits), which can
-result in inaccurate "Last Modified" dates for pages that haven't been updated recently.
-
-To ensure accurate last modified dates, add the `VERCEL_DEEP_CLONE` environment variable to your
-Vercel project:
-
-1. Go to your project settings in Vercel
-2. Navigate to "Environment Variables"
-3. Add a new variable: `VERCEL_DEEP_CLONE=true`
-4. Save and redeploy your site
-
-This will enable full Git history during builds, ensuring all pages show their correct last modified
-dates. The impact on build time is minimal (typically 5-20 seconds on the first build), and
-subsequent builds benefit from caching.

package/docs/extending/events.md

@@ -1,124 +0,0 @@
----
-title: Events
-sidebar_icon: shuffle
----
-
-APIToGo provides an events system that allows plugins to react to various application events. This
-system enables you to build dynamic features that respond to user interactions and application state
-changes.
-
-## Available Events
-
-Currently, APIToGo supports the following events:
-
-### location
-
-```typescript
-type LocationEvent = (e: { from?: Location; to: Location }) => void;
-```
-
-Emitted when the user navigates to a different route. Provides both the previous (`from`) and
-current (`to`)
-[Location objects](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) from
-react-router.
-
-Note that the `from` location will be undefined on the initial page load.
-
-## Consuming Events in Plugins
-
-To consume events in your plugin, you can implement the events property in your plugin. This is
-useful for performing actions like sending analytics events or anything else that's not directly
-related to the UI.
-
-```typescript
-import type { ApitogoPlugin } from "@lukoweb/apitogo";
-
-const navigationLoggerPlugin: ApitogoPlugin = {
-  events: {
-    location: ({ from, to }) => {
-      if (!from) {
-        console.log(`Initial navigation to: ${to.pathname}`);
-      } else {
-        console.log(`User navigated from: ${from.pathname} to: ${to.pathname}`);
-      }
-    },
-  },
-};
-```
-
-### Example in APIToGo Config
-
-In your your site config, you can define the events like this:
-
-```typescript
-export default {
-  plugins: [
-    {
-      events: {
-        location: ({ from, to }) => {
-          if (!from) return;
-
-          // E.g. send an analytics event
-          sendAnalyticsEvent({
-            from: from.pathname,
-            to: to.pathname,
-          });
-        },
-      },
-    },
-  ],
-};
-```
-
-## Using Events in Components
-
-APIToGo provides a convenient `useEvent` hook to subscribe to events in your React components. The
-hook can be used in three different ways:
-
-### 1. Getting the Latest Event Data
-
-If you just want to access the latest event data without a callback:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  const locationEvent = useEvent("location");
-  return <div>Current path: {locationEvent?.to.pathname}</div>;
-}
-```
-
-### 2. Using Event Data in a Component
-
-If you want to transform the event data, return a value from the callback:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  const pathname = useEvent("location", ({ to }) => to.pathname);
-  return <div>Current path: {pathname}</div>;
-}
-```
-
-### 3. Using a Callback for Side Effects
-
-If you just want to perform side effects when the event occurs:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  useEvent("location", ({ from, to }) => {
-    if (from) {
-      console.log(`Navigation: ${from.pathname} → ${to.pathname}`);
-    }
-    // No return value needed for side effects
-  });
-
-  return <div>My Component</div>;
-}
-```
-
-The `useEvent` hook automatically handles subscription and cleanup in the React lifecycle, making it
-easy to work with events in your components.