@mehdad67/apitogo 0.1.24

package/docs/configuration/docs.md

@@ -0,0 +1,282 @@
+---
+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="apitogo.config.tsx" 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="apitogo.config.tsx"
+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="apitogo.config.tsx"
+// 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="apitogo.config.tsx"
+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="apitogo.config.tsx"
+docs: {
+  defaultOptions: {
+    disablePager: true; // Disable pager by default
+  }
+}
+```
+
+#### `showLastModified`
+
+**Type:** `boolean`  
+**Default:** `false`
+
+Whether to show the last modified date by default.
+
+```tsx title="apitogo.config.tsx"
+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="apitogo.config.tsx"
+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="apitogo.config.tsx"
+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="apitogo.config.tsx"
+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="apitogo.config.tsx"
+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/footer.mdx

@@ -0,0 +1,214 @@
+---
+sidebar_label: Footer
+sidebar_icon: panel-bottom-dashed
+description:
+  Learn how to configure the footer in APIToGo, including columns, social links, copyright notice,
+  and logo. Customize the footer's position and content with slots.
+---
+
+# Footer Configuration
+
+The footer is a customizable component that appears at the bottom of every page in your APIToGo
+site. You can configure various aspects of the footer including its position, columns, social links,
+copyright notice, and logo.
+
+## Basic Configuration
+
+The footer is configured in your `apitogo.config.tsx` file under the `page.footer` property:
+
+```tsx
+const config: ApitogoConfig = {
+  site: {
+    footer: {
+      // Footer configuration goes here
+      position: "center",
+      copyright: `© ${new Date().getFullYear()} YourCompany LLC. All rights reserved.`,
+      // Other options...
+    },
+  },
+  // Other configuration...
+};
+```
+
+## Position
+
+You can control the horizontal alignment of the footer content using the `position` property:
+
+```tsx
+footer: {
+  position: "center"; // default
+  // or
+  position: "start";
+  // or
+  position: "end";
+}
+```
+
+This affects how the content in the footer's main row is positioned horizontally.
+
+## Columns
+
+The footer can include multiple columns of links, each with its own title:
+
+```tsx
+footer: {
+  columns: [
+    {
+      title: "Product",
+      position: "center", // position in grid, optional: start, center, end
+      links: [
+        { label: "Features", href: "/features" },
+        { label: "Pricing", href: "/pricing" },
+        { label: "Documentation", href: "/docs" },
+        { label: "GitHub", href: "https://github.com/org/repo" }, // Auto-detected as external
+      ],
+    },
+    {
+      title: "Company",
+      links: [
+        { label: "About", href: "/about" },
+        { label: "Blog", href: "/blog" },
+        { label: "Contact", href: "/contact" },
+      ],
+    },
+  ];
+}
+```
+
+Each column can have its own positioning with the `position` property, which can be `"start"`,
+`"center"`, or `"end"`. This controls how the column is positioned within the footer grid.
+
+## Social Media Links
+
+You can add social media links to your footer:
+
+```tsx
+footer: {
+  social: [
+    {
+      icon: "github",
+      href: "https://github.com/yourusername",
+    },
+    {
+      icon: "twitter",
+      href: "https://twitter.com/yourhandle",
+      label: "Follow us", // optional label text
+    },
+  ];
+}
+```
+
+The `icon` property currently can be one of the following values:
+
+<div className="[&_ul]:grid [&_ul]:grid-cols-[repeat(3,auto)]">
+
+- `"reddit"`
+- `"discord"`
+- `"github"`
+- `"x"` (Twitter)
+- `"linkedin"`
+- `"facebook"`
+- `"instagram"`
+- `"youtube"`
+- `"tiktok"`
+- `"twitch"`
+- `"pinterest"`
+- `"snapchat"`
+- `"whatsapp"`
+- `"telegram"`
+
+</div>
+
+Or you can provide a custom React component.
+
+## Copyright Notice
+
+Add a copyright notice with the `copyright` property:
+
+```tsx
+footer: {
+  copyright: `© ${new Date().getFullYear()} YourCompany LLC. All rights reserved.`;
+}
+```
+
+## Logo
+
+You can add a logo to your footer:
+
+```tsx
+footer: {
+  logo: {
+    src: {
+      light: "/path/to/light-logo.png",
+      dark: "/path/to/dark-logo.png"
+    },
+    alt: "Company Logo",
+    width: "120px" // optional width
+  }
+}
+```
+
+## Customizing with Slot
+
+APIToGo provides `footer-before` and `footer-after` slots that allow you to insert custom content
+before or after the main footer columns:
+
+```tsx
+// In your apitogo.config.tsx
+slots: {
+  "footer-before": () => (
+    <div>
+      <h3>Custom pre-footer content</h3>
+      <p>This appears before the columns</p>
+    </div>
+  ),
+  "footer-after": () => (
+    <div>
+      <p>Additional footer content</p>
+    </div>
+  )
+}
+```
+
+## Complete Example
+
+Here's a complete example showing all footer options:
+
+```tsx
+footer: {
+  position: "center",
+  columns: [
+    {
+      title: "Product",
+      position: "start",
+      links: [
+        { label: "Features", href: "/features" },
+        { label: "Pricing", href: "/pricing" },
+        { label: "Documentation", href: "/docs" }
+      ]
+    },
+    {
+      title: "Resources",
+      position: "center",
+      links: [
+        { label: "Blog", href: "/blog" },
+        { label: "Support", href: "/support" },
+        { label: "GitHub", href: "https://github.com/yourusername" } // Auto-detected as external
+      ]
+    }
+  ],
+  social: [
+    { icon: "github", href: "https://github.com/yourusername" },
+    { icon: "linkedin", href: "https://linkedin.com/company/yourcompany", label: "LinkedIn" }
+  ],
+  copyright: `© ${new Date().getFullYear()} YourCompany LLC. All rights reserved.`,
+  logo: {
+    src: {
+      light: "/images/logo-light.svg",
+      dark: "/images/logo-dark.svg"
+    },
+    alt: "Company Logo",
+    width: "100px"
+  }
+}
+```

package/docs/configuration/llms.md

@@ -0,0 +1,90 @@
+---
+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="apitogo.config.tsx"
+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/make-config.mdx

@@ -0,0 +1,90 @@
+---
+title: Make config (CLI)
+navigation_label: Make config
+sidebar_icon: file-cog
+description:
+  Scaffold package.json and tsconfig when missing, optionally wire OpenAPI, then refresh navigation
+  and redirects from your Markdown pages while preserving other config options.
+---
+
+The **`apitogo make-config`** command can **bootstrap a minimal project** (new `package.json` and
+`tsconfig.json` when missing, **`npm install`** then **`npm run dev`**), **add an `apis` block**
+when it finds an OpenAPI spec and your config has none yet, and **regenerate `navigation` and
+`redirects`** from your `pages/` tree. Other existing settings (such as **`site`** or **`theme`**)
+stay as you left them unless you are creating files for the first time.
+
+## What it does
+
+1. **Ensures you can run npm scripts** — If there is no **`package.json`**, it creates one with
+   **`apitogo dev`**, **`apitogo build`**, **`apitogo preview`**, and adds **`react`**,
+   **`react-dom`**, and **`@lukoweb/apitogo`** if missing. If **`tsconfig.json`** is missing, it
+   adds a minimal TypeScript config that includes your config file and **`pages/`**. After a new
+   `package.json` is created, run **`npm install`** (or pnpm/yarn), then **`npm run dev`**.
+2. **Wires OpenAPI when possible** — If it finds an OpenAPI file (for example
+   **`apis/openapi.json`** or **`openapi.json`** at the project root) and your config has no
+   **`apis`** entry yet, it adds an **`apis`** block pointing at that file. Existing **`apis`**
+   settings are not overwritten.
+3. **Finds or creates a config file** — It looks for an existing `apitogo.config.*` or
+   `apitogo.config.*` file in the project root. If **none** exists, it creates
+   **`apitogo.config.tsx`** with **`docs.files`** for your pages glob, optional **`apis`** when a
+   spec was found, plus empty **`navigation`** and **`redirects`**, then fills nav and redirects
+   from disk.
+4. **Rebuilds `navigation`** — Builds a tree from `.md` / `.mdx` files under your pages directory,
+   including nested folders as categories, and adds the usual Documentation category plus API link
+   block used by the generator.
+5. **Sets `redirects`** — Adds a root redirect from `/` to the first page (after a stable sort that
+   prefers paths like `introduction` and `getting-started` when present).
+
+Other config you already had—**`site`**, **`theme`**, plugins, authentication, etc.—is **left
+unchanged**. The command replaces only the **values** of the **`navigation`** and **`redirects`**
+arrays. If **`apis`** was already set, it is not modified.
+
+## Usage
+
+Run from your project root (where the config and `package.json` live):
+
+```bash
+apitogo make-config
+```
+
+### Options
+
+| Option              | Description                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `--pages-dir <dir>` | Folder to scan for `.md` / `.mdx` files (default: `pages`). Paths in `navigation` are derived from this tree. |
+| `--dir <path>`      | Project root (default: current directory). Useful in monorepos or scripts.                                    |
+
+Examples:
+
+```bash
+apitogo make-config --pages-dir content
+apitogo make-config --dir ./my-docs-site
+```
+
+## Requirements
+
+- **`navigation` and `redirects` must be array literals** in the config (e.g.
+  `navigation: [ ... ]`). If your navigation is computed from variables or imported from another
+  module, `make-config` cannot update it safely—maintain those by hand or switch to generated arrays
+  when you want this workflow.
+- If your file has **`navigation`** but no **`redirects`**, the command inserts `redirects: []`
+  before updating. If **both** are missing, it inserts empty arrays after
+  `const config: ApitogoConfig = {`.
+
+## Relationship to navigation
+
+The **`navigation`** array structure and item types (`link`, `category`, doc paths as strings, and
+so on) are the same as when you [configure navigation by hand](./navigation.md). The CLI only
+**generates** that structure from your files; it does not add new concepts.
+
+## When not to use it
+
+- You need a **fully custom** navigation order or labels per page that the generator would
+  overwrite. Run the command once to get a baseline, then edit—or maintain navigation manually.
+- You use **only** OpenAPI-driven sidebars and no Markdown docs tree; there may be nothing useful to
+  scan under `pages/`.
+
+## See also
+
+- [Navigation](./navigation.md) — Navigation item types, icons, and rules
+- [Documentation (pages)](./docs.md) — How file paths map to URLs