@mehdad67/apitogo 0.1.24

package/docs/customization/colors-theme.mdx

@@ -0,0 +1,276 @@
+---
+sidebar_icon: paintbrush
+title: Colors & Theme
+description:
+  Customize your APIToGo site's colors and theme with flexible options, including light/dark modes,
+  custom CSS, and shadcn registry integration.
+---
+
+APIToGo provides flexible theming options allowing you to customize colors, import themes from
+[shadcn registries](https://ui.shadcn.com/docs/registry), and add custom CSS. You can create
+cohesive light and dark mode experiences that match your brand.
+
+:::tip
+
+Try out the interactive [Theme Playground](/docs/theme-playground) to experiment with colors and see
+real-time previews of your theme changes.
+
+:::
+
+The theme system is built on [shadcn/ui theming](https://ui.shadcn.com/docs/theming) and
+[Tailwind v4](https://tailwindcss.com), giving us a great foundation to build upon:
+
+- **CSS variables** match `shadcn/ui` conventions
+- **Tailwind v4** CSS variable system for modern styling
+- **Theme editors** like [tweakcn](https://tweakcn.com/) work out of the box
+- **Shadcn registries** are supported
+
+## Custom Colors
+
+You can manually define colors for both light and dark modes, either by extending the
+[default theme](#default-theme) or creating a completely custom theme. Colors can be specified as
+hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by
+[Tailwind CSS](https://tailwindcss.com):
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    light: {
+      background: "#ffffff",
+      foreground: "#020817",
+      card: "#ffffff",
+      cardForeground: "#020817",
+      popover: "#ffffff",
+      popoverForeground: "#020817",
+      primary: "#0284c7",
+      primaryForeground: "#ffffff",
+      secondary: "#f1f5f9",
+      secondaryForeground: "#020817",
+      muted: "#f1f5f9",
+      mutedForeground: "#64748b",
+      accent: "#f1f5f9",
+      accentForeground: "#020817",
+      destructive: "#ef4444",
+      destructiveForeground: "#ffffff",
+      border: "#e2e8f0",
+      input: "#e2e8f0",
+      ring: "#0284c7",
+      radius: "0.5rem",
+    },
+    dark: {
+      background: "#020817",
+      foreground: "#f8fafc",
+      card: "#020817",
+      cardForeground: "#f8fafc",
+      popover: "#020817",
+      popoverForeground: "#f8fafc",
+      primary: "#0ea5e9",
+      primaryForeground: "#f8fafc",
+      secondary: "#1e293b",
+      secondaryForeground: "#f8fafc",
+      muted: "#1e293b",
+      mutedForeground: "#94a3b8",
+      accent: "#1e293b",
+      accentForeground: "#f8fafc",
+      destructive: "#ef4444",
+      destructiveForeground: "#f8fafc",
+      border: "#1e293b",
+      input: "#1e293b",
+      ring: "#0ea5e9",
+      radius: "0.5rem",
+    },
+  },
+};
+```
+
+## Available Theme Variables
+
+| Variable                | Description                           |
+| ----------------------- | ------------------------------------- |
+| `background`            | Main background color                 |
+| `foreground`            | Main text color                       |
+| `card`                  | Card background color                 |
+| `cardForeground`        | Card text color                       |
+| `popover`               | Popover background color              |
+| `popoverForeground`     | Popover text color                    |
+| `primary`               | Primary action color                  |
+| `primaryForeground`     | Text color on primary backgrounds     |
+| `secondary`             | Secondary action color                |
+| `secondaryForeground`   | Text color on secondary backgrounds   |
+| `muted`                 | Muted/subtle background color         |
+| `mutedForeground`       | Text color for muted elements         |
+| `accent`                | Accent color for highlights           |
+| `accentForeground`      | Text color on accent backgrounds      |
+| `destructive`           | Color for destructive actions         |
+| `destructiveForeground` | Text color on destructive backgrounds |
+| `border`                | Border color                          |
+| `input`                 | Input field border color              |
+| `ring`                  | Focus ring color                      |
+| `radius`                | Border radius value                   |
+
+:::note
+
+While shadcn/ui defines additional theme variables, APIToGo currently uses only these core
+variables.
+
+:::
+
+## shadcn Registry Integration
+
+The easiest way to customize your theme is by using a Shadcn registry theme. For example you can use
+the great [tweakcn](https://tweakcn.com/) visual theme editor.
+
+### Using tweakcn Themes
+
+<Stepper>
+
+1. Visit [tweakcn.com](https://tweakcn.com/) to select a preset or customize your theme visually
+
+   <Framed align="start">![](./tweakcn0.webp)</Framed>
+   <Framed align="start">![](./tweakcn1.webp)</Framed>
+
+1. Copy the registry URL from the "Copy" section
+
+   <Framed align="start">![](./tweakcn2.webp)</Framed>
+
+1. Add it to your configuration:
+   ```ts title=apitogo.config.ts
+   const config = {
+     theme: {
+       registryUrl: "https://tweakcn.com/r/themes/northern-lights.json",
+     },
+   };
+   ```
+1. The theme will then be automatically imported with all color variables, fonts, and styling
+   configured for you 🚀
+
+   <Framed align="start">![](/tweakcn-northlight.png)</Framed>
+
+</Stepper>
+
+You can still override specific values if needed:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    registryUrl: "https://tweakcn.com/api/registry/theme/xyz123",
+    // Override specific colors
+    light: {
+      primary: "#0066cc",
+    },
+    dark: {
+      primary: "#3399ff",
+    },
+  },
+};
+```
+
+Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    customCss: `
+      /* Copied CSS code */
+    `,
+  },
+};
+```
+
+## Custom CSS
+
+For advanced styling, you can add custom CSS either as a string or structured object:
+
+:::note
+
+Changes to `customCss` require restarting the development server to take effect.
+
+:::
+
+### CSS String
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    customCss: `
+      .custom {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      }
+    `,
+  },
+};
+```
+
+### CSS Object
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    customCss: {
+      ".custom": {
+        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+      },
+    },
+  },
+};
+```
+
+## Default Theme
+
+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
+const config = {
+  theme: {
+    noDefaultTheme: true,
+    // Your custom theme configuration
+  },
+};
+```
+
+When `noDefaultTheme` is set to `true`, no default colors or styling will be applied, giving you
+complete control over your theme. Changing this requires to restart the development server.
+
+## Complete Example
+
+Here's a comprehensive example combining multiple theming approaches:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    // Import base theme from registry
+    registryUrl: "https://tweakcn.com/api/registry/theme/modern-blue",
+
+    // Override specific colors
+    light: {
+      primary: "#0066cc",
+      accent: "#f0f9ff",
+    },
+    dark: {
+      primary: "#3399ff",
+      accent: "#0c1b2e",
+    },
+
+    // Custom fonts
+    fonts: {
+      sans: "Inter",
+      mono: "JetBrains Mono",
+    },
+
+    // Additional custom styling
+    customCss: {
+      ".hero-section": {
+        background: "var(--primary)",
+        color: "var(--primary-foreground)",
+        padding: "2rem",
+        "border-radius": "var(--radius)",
+      },
+    },
+  },
+};
+```
+
+This configuration imports a base theme, customizes colors for both light and dark modes, sets
+fonts, and adds custom component styling.

package/docs/customization/fonts.md

@@ -0,0 +1,110 @@
+---
+sidebar_icon: baseline
+title: Font & Typography
+sidebar_label: Font & Typography
+description:
+  Learn how to customize fonts and typography in APIToGo using predefined Google Fonts, custom font
+  URLs, or local fonts for sans, serif, and monospace text.
+---
+
+APIToGo allows you to customize fonts for text (`sans`), serif content (`serif`), and code (`mono`).
+You can use predefined Google Fonts, external sources, or local fonts.
+
+## Predefined Google Fonts
+
+The easiest way to use fonts is with predefined Google Fonts. Simply specify the font name as a
+string:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: "Inter",
+      serif: "Merriweather",
+      mono: "JetBrains Mono",
+    },
+  },
+};
+```
+
+### Available Google Fonts
+
+The following fonts are available as predefined options:
+
+**Sans Serif:** Inter, Roboto, Open Sans, Poppins, Montserrat, Outfit, Plus Jakarta Sans, DM Sans,
+IBM Plex Sans, Geist, Oxanium, Space Grotesk
+
+**Serif:** Architects Daughter, Merriweather, Playfair Display, Lora, Source Serif Pro, Libre
+Baskerville
+
+**Monospace:** JetBrains Mono, Fira Code, Source Code Pro, IBM Plex Mono, Roboto Mono, Space Mono,
+Geist Mono
+
+## Custom Font URLs
+
+For more control or to use fonts not in the predefined list, you can specify a custom font URL:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: {
+        url: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap",
+        fontFamily: "Roboto, sans-serif",
+      },
+      mono: {
+        url: "https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap",
+        fontFamily: "Roboto Mono, monospace",
+      },
+    },
+  },
+};
+```
+
+## Local Fonts
+
+To use local fonts, add them to the `public` folder and create a `fonts.css` file:
+
+```css
+@font-face {
+  font-family: "CustomFont";
+  font-style: normal;
+  font-weight: 400;
+  src: url("/custom-font-400.woff2") format("woff2");
+}
+```
+
+Then reference the local CSS file:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: {
+        url: "/fonts.css",
+        fontFamily: "CustomFont, sans-serif",
+      },
+    },
+  },
+};
+```
+
+## Mixed Configuration
+
+You can mix predefined fonts with custom fonts:
+
+```ts title=apitogo.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: "Inter", // Predefined Google Font
+      serif: {
+        // Custom font
+        url: "/custom-serif.css",
+        fontFamily: "CustomSerif, serif",
+      },
+      mono: "Fira Code", // Predefined Google Font
+    },
+  },
+};
+```

package/docs/deploy/apache-nginx.md

@@ -0,0 +1,41 @@
+---
+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/apitogo.md

@@ -0,0 +1,139 @@
+---
+title: APIToGo
+zuplo: false
+---
+
+[APIToGo](https://app.apitogo.com) gives you a managed way to publish your API documentation without
+having to maintain your own hosting setup.
+
+## Before you deploy
+
+Before publishing, make sure your documentation works locally:
+
+```bash
+npm run dev
+```
+
+## Deploy with APIToGo
+
+To publish your docs with APIToGo:
+
+1. Sign in to [app.apitogo.com](https://app.apitogo.com)
+2. Create a new project or open an existing one
+3. Navigate to Project settings and copy the deployment token
+4. Run the following command:
+
+```bash
+apitogo deploy --deployment-token=<TOKEN> --env=<environment-name>
+```
+
+The `--env` value is the **environment name** your deploy server uses. It must match what is
+configured for your project (see the APIToGo dashboard / deploy API).
+
+Common patterns:
+
+- **`production`** — main live site (default when `--env` is omitted)
+- **Named non-production environments** — any label your backend accepts, for example `staging`,
+  `dev`, or `preview`
+- **Multiple preview slots** — separate previews such as `preview-a` and `preview-b` when your
+  `/deploy` endpoint supports them:
+
+```bash
+apitogo deploy --deployment-token=<TOKEN> --env=preview-a
+apitogo deploy --deployment-token=<TOKEN> --env=preview-b
+```
+
+If you do not provide `--env`, APIToGo deploys to `production` by default:
+
+```bash
+apitogo deploy --deployment-token=<TOKEN>
+```
+
+### JSON-only mode (`--json-only`)
+
+Use `--json-only` when you want **machine-readable output** from the whole command (for example
+piping to `jq` in CI).
+
+- **Standard output** is a **single JSON value**: on success, the parsed deploy API response (the
+  same payload the server returns with `?jsonOnly=true`). On failure (including build errors),
+  stdout is `{"error":"..."}` and the process exits with a non-zero code.
+- The CLI **suppresses** normal build and progress logs so they do not mix with that JSON.
+- The deploy request still includes `?jsonOnly=true` on the endpoint.
+
+```bash
+apitogo deploy --deployment-token=<TOKEN> --json-only
+```
+
+Combine with `--env` as usual (including named previews such as `preview-a`):
+
+```bash
+apitogo deploy --deployment-token=<TOKEN> --env=preview --json-only
+apitogo deploy --deployment-token=<TOKEN> --env=preview-a --json-only
+```
+
+## Deploy with GitHub Actions
+
+You can automate deploys from GitHub so every merge to `main` updates production and every pull
+request gets a **preview** URL.
+
+### 1. Generate the workflow
+
+From your documentation project root (the folder that contains `apitogo.config` and `package.json`),
+run:
+
+```bash
+apitogo configure-github-workflow
+```
+
+This creates `.github/workflows/apitogo-deploy.yml` with two jobs:
+
+- **Preview** — runs on pull requests targeting `main`. It deploys to an environment named like
+  `preview-pr-<number>` and exposes the preview URL on the GitHub Actions run.
+- **Production** — runs on pushes to `main`. It deploys with the default production environment.
+
+If the file already exists, pass `--force` to overwrite it.
+
+### 2. Add your deployment token as a GitHub secret
+
+1. In [APIToGo](https://app.apitogo.com), open your project and copy the **deployment token** from
+   project settings (the same token you use with `apitogo deploy`).
+2. On GitHub, open your repository → **Settings** → **Secrets and variables** → **Actions**.
+3. Create a new repository secret named **`APITOGO_TOKEN`** and paste the token.
+
+The generated workflow reads that secret as `${{ secrets.APITOGO_TOKEN }}`.
+
+### 3. Optional: GitHub environments
+
+The workflow references **`preview`** and **`production`**
+[environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment).
+If you use environment protection rules, create matching environments in the repo settings and
+attach reviewers or branch filters as needed. If you do not use environments, the jobs still run;
+you can simplify the workflow later to drop `environment:` blocks.
+
+### 4. Commit and ship
+
+Add the new workflow to version control, commit, and push:
+
+```bash
+git add .github/workflows/apitogo-deploy.yml
+git commit -m "Add APIToGo GitHub Actions deploy workflow"
+git push
+```
+
+After that, pushes and pull requests against `main` trigger deploys automatically. You can also run
+the workflow manually from the **Actions** tab (**workflow_dispatch**).
+
+## What to verify after deployment
+
+After your site is live, check the following:
+
+- Navigation load correctly
+- Static assets such as images and logos resolve correctly
+- OpenAPI references and API playground features load as expected
+- Any custom domain or redirects are working properly
+
+## Open APIToGo
+
+To get started, sign in here:
+
+- [APIToGo Dashboard](https://app.apitogo.com)

package/docs/deploy/cloudflare-pages.md

@@ -0,0 +1,75 @@
+---
+title: Cloudflare Pages
+zuplo: false
+---
+
+[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

@@ -0,0 +1,18 @@
+---
+title: Upload/FTP
+zuplo: false
+---
+
+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.