zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/zudoku/guides/mermaid.mdx

@@ -0,0 +1,70 @@
+---
+title: Mermaid Diagrams
+sidebar_icon: chart-network
+---
+
+Dev Portal supports rendering [Mermaid diagrams](https://mermaid.js.org/) in two ways:
+
+| Approach                        | Pros                                                                  | Cons                                                        |
+| ------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
+| **Build-Time** (rehype-mermaid) | • Faster page loads<br/>• No client-side JS needed<br/>• SEO friendly | • Requires playwright<br/>• Slower builds<br/>• Static only |
+| **Client-Side** (`<Mermaid />`) | • Fast builds<br/>• Can be dynamic<br/>• No build dependencies        | • Requires client-side JS<br/>• Slight render delay         |
+
+## Client-Side Rendering
+
+For the [`<Mermaid />` component](/dev-portal/zudoku/components/mermaid), install the peer dependency:
+
+```bash
+npm install mermaid
+```
+
+Then use in your MDX files (no import needed):
+
+```tsx
+<Mermaid
+  chart={`graph TD;
+    A-->B;
+    A-->C;`}
+/>
+```
+
+Outside of MDX, import from `zudoku/mermaid`:
+
+```tsx
+import { Mermaid } from "zudoku/mermaid";
+```
+
+See the [Mermaid component documentation](/dev-portal/zudoku/components/mermaid) for full details.
+
+## Build-Time Rendering
+
+<Stepper>
+
+1. Install dependencies:
+
+   ```bash
+   npm install rehype-mermaid
+   npm install -D playwright
+   npx playwright install
+   ```
+
+1. Add to `zudoku.build.ts`:
+
+   ```tsx title="zudoku.build.ts"
+   import rehypeMermaid from "rehype-mermaid";
+
+   export default {
+     rehypePlugins: (plugins) => [[rehypeMermaid, { strategy: "inline-svg" }], ...plugins],
+   };
+   ```
+
+1. Use in markdown with code blocks:
+
+   ````mdx
+   ```mermaid
+   graph TD;
+       A-->B;
+   ```
+   ````
+
+</Stepper>

package/docs/dev-portal/zudoku/guides/navigation-migration.md

@@ -0,0 +1,87 @@
+---
+title: Navigation Migration
+navigation_icon: arrow-right-left
+---
+
+This guide explains how to migrate existing configurations that used `topNavigation`, `sidebar` and
+`customPages` to the new unified `navigation` configuration introduced in vNEXT.
+
+## Overview
+
+Navigation is now configured through a single `navigation` array. Items at the root level become top
+navigation tabs, while nested categories automatically form the sidebar. Custom pages are added
+using the `custom-page` item type.
+
+## Before and After
+
+```tsx title="Before"
+const config: ZudokuConfig = {
+  topNavigation: [
+    { id: "docs", label: "Docs" },
+    { id: "api", label: "API" },
+  ],
+  sidebar: {
+    docs: [{ type: "doc", id: "introduction" }],
+  },
+  customPages: [{ path: "/playground", render: Playground, prose: false }],
+  apis: {
+    type: "file",
+    input: "./openapi.json",
+    navigationId: "api",
+  },
+};
+```
+
+```tsx title="After"
+const config: ZudokuConfig = {
+  navigation: [
+    {
+      type: "category",
+      label: "Docs",
+      items: ["introduction"],
+    },
+    {
+      type: "custom-page",
+      path: "/playground",
+      element: <Playground />,
+    },
+    {
+      type: "link",
+      to: "/api",
+      label: "API",
+    },
+  ],
+  apis: [
+    {
+      path: "/api",
+      type: "file",
+      input: "./openapi.json",
+    },
+  ],
+};
+```
+
+## Migration steps
+
+<Stepper>
+
+1. **Create a `navigation` array**
+
+   Move all items from `topNavigation` and your sidebar into a new `navigation` array.
+
+1. **Convert custom pages**
+
+   Replace entries in `customPages` with `type: "custom-page"` items inside `navigation`.
+
+1. **Update plugin configs**
+
+   Replace all uses of `navigationId` with `path` in plugin options like `apis` or `catalogs`.
+   Navigation items of type `link` should use the `to` property to reference the path of the API or
+   catalog.
+
+1. **Reference plugin paths in navigation**
+
+   Items produced by plugins are not added automatically. Add links or categories in your
+   `navigation` so users can access them.
+
+</Stepper>

package/docs/dev-portal/zudoku/guides/navigation-rules.mdx

@@ -0,0 +1,197 @@
+---
+title: Navigation Rules
+sidebar_icon: list-tree
+---
+
+import { LayersPlusIcon, PencilIcon, SortAscIcon, ArrowUpDownIcon, TrashIcon } from "zudoku/icons";
+
+Plugins like the OpenAPI plugin generate sidebar navigation automatically. Navigation rules let you
+customize that generated sidebar without changing the source. You can:
+
+- <LayersPlusIcon className="inline-block size-3.5 me-1" /> **Insert** items at a specific position
+- <PencilIcon className="inline-block size-3.5 me-1" /> **Modify** items
+- <SortAscIcon className="inline-block size-3.5 me-1" /> **Sort** items with a custom comparator
+- <ArrowUpDownIcon className="inline-block size-3.5 me-1" /> **Move** items to a different position
+- <TrashIcon className="inline-block size-3.5 me-1" /> **Remove** items
+
+## Setup
+
+Add a `navigationRules` array to your `zudoku.config.tsx`:
+
+```tsx
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  apis: [{ type: "file", input: "./api.json", path: "api-shipments" }],
+  navigation: [{ type: "link", label: "Shipments", to: "/api-shipments" }],
+  navigationRules: [
+    // rules go here
+  ],
+};
+```
+
+## Inserting docs
+
+Use `type: "insert"` to add items before or after a matched sidebar item. The `match` string uses
+the tab label as the first segment and navigates into the sidebar tree.
+
+```tsx
+navigationRules: [
+  {
+    type: "insert",
+    match: "Shipments/0",
+    position: "before",
+    items: [
+      {
+        type: "doc",
+        file: "api-shipments/getting-started",
+        icon: "plane-takeoff",
+      },
+    ],
+  },
+],
+```
+
+This inserts a "Getting Started" doc before the first item in the Shipments sidebar.
+
+![Inserting a doc before the first sidebar item](./navigation-rules/insert-doc.png)
+
+The MDX file lives at `pages/api-shipments/getting-started.mdx` (under your configured docs
+directory, matching the API's base path).
+
+## Adding links
+
+You can insert external or internal links the same way:
+
+```tsx
+{
+  type: "insert",
+  match: "Shipments/-1",
+  position: "after",
+  items: [
+    {
+      type: "link",
+      label: "System Status",
+      to: "/status",
+      icon: "satellite",
+    },
+  ],
+}
+```
+
+The `-1` index targets the last item, and `position: "after"` places the link at the very end of the
+sidebar.
+
+![Inserting a link after the last sidebar item](./navigation-rules/insert-doc-end.png)
+
+## Modifying items
+
+Use `type: "modify"` to change properties of existing sidebar items like their icon, label, or
+collapsed state:
+
+```tsx
+{
+  type: "modify",
+  match: "Shipments/Shipment Management",
+  set: { icon: "box", collapsed: true },
+}
+```
+
+![Modifying a sidebar item's icon](./navigation-rules/modify-item.png)
+
+## Removing items
+
+`type: "remove"` hides items from the sidebar. This is rarely needed since it's usually better to
+fix the underlying source, but can be useful as a quick workaround:
+
+```tsx
+{
+  type: "remove",
+  match: "Shipments/Deprecated Endpoint",
+}
+```
+
+## Sorting items
+
+Use `type: "sort"` to reorder children of a category alphabetically or with any custom comparator:
+
+```tsx
+{
+  type: "sort",
+  match: "Shipments",
+  by: (a, b) => a.label.localeCompare(b.label),
+}
+```
+
+The `by` function receives two navigation items and works like a standard `Array.sort` comparator.
+
+## Moving items
+
+Use `type: "move"` to relocate an existing item to a different position in the sidebar:
+
+```tsx
+{
+  type: "move",
+  match: "Shipments/Track a Shipment",
+  to: "Shipments/0",
+  position: "before",
+}
+```
+
+This moves "Track a Shipment" to the top of the Shipments category. You can also move items between
+different levels, for example from inside a category to the root level.
+
+## Rule order
+
+Rules are applied sequentially, so order matters. For example, sorting first and then inserting
+places the new item at an exact position in the already-sorted list. Inserting first and then
+sorting will sort the new item along with everything else.
+
+## Complete example
+
+This is the configuration used in the Cosmo Cargo demo shown above:
+
+```tsx
+navigationRules: [
+  {
+    type: "sort",
+    match: "Shipments",
+    by: (a, b) => a.label.localeCompare(b.label),
+  },
+  {
+    type: "insert",
+    match: "Shipments/Shipment",
+    position: "before",
+    items: [
+      {
+        type: "doc",
+        file: "api-shipments/getting-started",
+        icon: "plane-takeoff",
+      },
+    ],
+  },
+  {
+    type: "insert",
+    match: "Shipments/-1",
+    position: "after",
+    items: [
+      {
+        type: "link",
+        label: "System Status",
+        to: "/status",
+        icon: "satellite",
+      },
+    ],
+  },
+  {
+    type: "modify",
+    match: "Shipments/1",
+    set: { icon: "box" },
+  },
+],
+```
+
+## Match syntax reference
+
+For the full match syntax including label matching, index selectors, and nested paths, see the
+[Navigation Rules reference](/dev-portal/zudoku/configuration/navigation#navigation-rules).

package/docs/dev-portal/zudoku/guides/processors.mdx

@@ -0,0 +1,234 @@
+---
+sidebar_icon: cpu
+---
+
+# Schema Processors
+
+Schema processors are functions that transform your OpenAPI schemas before they are used in the
+documentation. They are defined in your `zudoku.build.ts` file and can be used to modify schemas in
+various ways.
+
+:::tip
+
+For information on how to configure processors in your project, see the
+[Build Configuration](../configuration/build-configuration) guide.
+
+:::
+
+## Built-in Processors
+
+Dev Portal provides several built-in processors that you can use to transform your schemas:
+
+### `removeExtensions`
+
+Removes OpenAPI extensions (`x-` prefixed properties) from your schema:
+
+```ts
+import { removeExtensions } from "zudoku/processors/removeExtensions";
+import type { ZudokuBuildConfig } from "zudoku";
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [
+    // Remove all x- prefixed properties
+    removeExtensions(),
+
+    // Remove specific extensions
+    removeExtensions({
+      keys: ["x-internal", "x-deprecated"],
+    }),
+
+    // Remove extensions based on a custom filter
+    removeExtensions({
+      shouldRemove: (key) => key.startsWith("x-zuplo"),
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+### `removeParameters`
+
+Removes parameters from your schema:
+
+```ts
+import { removeParameters } from "zudoku/processors/removeParameters";
+import type { ZudokuBuildConfig } from "zudoku";
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [
+    // Remove parameters by name
+    removeParameters({
+      names: ["apiKey", "secret"],
+    }),
+
+    // Remove parameters by location
+    removeParameters({
+      in: ["header", "query"],
+    }),
+
+    // Remove parameters based on a custom filter
+    removeParameters({
+      shouldRemove: ({ parameter }) => parameter["x-internal"],
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+### `removePaths`
+
+Removes paths or operations from your schema:
+
+```ts
+import { removePaths } from "zudoku/processors/removePaths";
+import type { ZudokuBuildConfig } from "zudoku";
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [
+    // Remove entire paths
+    removePaths({
+      paths: {
+        "/internal": true,
+        "/admin": ["get", "post"],
+      },
+    }),
+
+    // Remove paths based on a custom filter
+    removePaths({
+      shouldRemove: ({ path, method, operation }) => operation["x-internal"],
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+:::info
+
+If you are missing a processor that you think should be built-in, please don't hesitate to
+[open an issue on GitHub](https://github.com/zuplo/zudoku/issues/new).
+
+:::
+
+## Custom Processors
+
+You can also create your own processors. Here's a simple example that adds a description to all
+operations:
+
+```ts
+import type { ZudokuBuildConfig } from "zudoku";
+
+async function addDescriptionProcessor({ schema }) {
+  if (!schema.paths) return schema;
+
+  // Add a description to all operations
+  Object.values(schema.paths).forEach((path) => {
+    Object.values(path).forEach((operation) => {
+      if (typeof operation === "object") {
+        operation.description = "This is a public API endpoint";
+      }
+    });
+  });
+
+  return schema;
+}
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [addDescriptionProcessor],
+};
+
+export default buildConfig;
+```
+
+### Adding Server URLs
+
+```ts
+import type { ZudokuBuildConfig } from "zudoku";
+
+async function addServerUrl({ schema }) {
+  return {
+    ...schema,
+    servers: [{ url: "https://api.example.com" }],
+  };
+}
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [addServerUrl],
+};
+
+export default buildConfig;
+```
+
+## Using Query Parameters to Split Schemas
+
+You can use the same OpenAPI file multiple times with different processing by appending query
+parameters to the file input string. These parameters are passed to your processors via the `params`
+argument, allowing you to filter or transform the schema differently for each variant.
+
+This is useful when you have a single schema containing multiple API versions or groups that you
+want to split into separate pages.
+
+Plain strings work out of the box. Version paths and dropdown labels are auto-generated from the
+query parameter values. For more control, use the object form with explicit `path` and `label`.
+
+```ts title=zudoku.config.ts
+const config = {
+  apis: {
+    type: "file",
+    input: [
+      // Object form: explicit path and label
+      {
+        input: "openapi.json?prefix=/v2",
+        path: "latest",
+        label: "Latest (v2)",
+      },
+      // Object form: explicit path, label auto-generated from params
+      {
+        input: "openapi.json?prefix=/v1.1",
+        path: "v1.1",
+      },
+      // Plain string: both path and label auto-generated from params
+      "openapi.json?prefix=/v1",
+    ],
+    path: "/api",
+  },
+};
+```
+
+```ts title=zudoku.build.ts
+import type { ZudokuBuildConfig } from "zudoku";
+
+const buildConfig: ZudokuBuildConfig = {
+  processors: [
+    ({ schema, params }) => {
+      const prefix = params.prefix;
+      if (!prefix) return schema;
+
+      return {
+        ...schema,
+        paths: Object.fromEntries(
+          Object.entries(schema.paths ?? {}).filter(([path]) => path.startsWith(prefix)),
+        ),
+      };
+    },
+  ],
+};
+
+export default buildConfig;
+```
+
+Each version tab will show only the endpoints matching that prefix. The query parameters are
+arbitrary key-value pairs that you define and consume in your processors.
+
+When schema download is enabled, param variants serve the processed (filtered) schema rather than
+the original file.
+
+## Best Practices
+
+- **Handle missing properties**: Check for the existence of properties before accessing them
+- **Return the schema**: Always return the transformed schema, even if no changes were made
+- **Use async/await**: Processors can be async functions, which is useful for more complex
+  transformations
+- **Chain processors**: Processors are executed in order, so you can chain multiple transformations

package/docs/dev-portal/zudoku/guides/static-files.md

@@ -0,0 +1,55 @@
+---
+title: Static Files
+sidebar_icon: folder-open
+description:
+  Learn how to serve and reference static files like images and PDFs in your Dev Portal documentation
+  using the public directory.
+---
+
+Dev Portal makes it easy to serve static files like images, PDFs, or any other assets alongside your
+documentation. Any files placed in the `public` directory will be served at the root path `/` during
+dev, and copied to the root of the dist directory as-is.
+
+Note that you should always reference `public` assets using root absolute path - for example,
+`public/icon.png` should be referenced in source code as `/icon.png`.
+
+## Usage
+
+1. Create a `public` directory in your project root if it doesn't exist already
+2. Place any static files in this directory
+3. Reference these files in your documentation using the root path `/`
+
+## Example
+
+If you have the following structure:
+
+```
+your-project/
+├── public/
+│   ├── images/
+│   │   └── diagram.png
+│   └── documents/
+│       └── api-spec.pdf
+└── ...
+```
+
+You can reference these files using markdown like this:
+
+```md
+![API Architecture](/dev-portal/zudoku/images/diagram.png)
+```
+
+If you want users to download a file like a PDF, you can use an anchor tag like this:
+
+```html
+<a href="/documents/api-spec.pdf" download="/documents/api-spec.pdf">Download API specification</a>
+```
+
+## Relative paths
+
+If you want to reference a file that is in the same directory as the current file, you can also use
+a relative path:
+
+```md title="page.mdx"
+![API Architecture](./image.png)
+```