zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/zudoku/configuration/overview.md

@@ -0,0 +1,380 @@
+---
+title: Configuration File
+sidebar_icon: file-json-2
+description:
+  Learn how to configure your Dev Portal documentation site using the configuration file. Covers file
+  formats, options, examples, and best practices.
+---
+
+Dev Portal uses a single file for configuration. It controls the structure, metadata, style, plugins,
+and routing for your documentation.
+
+You can find the file in the root directory of your project. It will start with `zudoku.config`. The
+file can be in either JavaScript or TypeScript format and use a `.js`, `.mjs`, `.jsx`, `.ts`, or
+`.tsx` file extension:
+
+- `zudoku.config.ts`
+- `zudoku.config.tsx`
+- `zudoku.config.js`
+- `zudoku.config.jsx`
+- `zudoku.config.mjs`
+
+When you create a project, a default configuration file is generated for you. This file is a good
+starting point and can be customized to suit your needs.
+
+:::note{title="Security Consideration"}
+
+The Dev Portal configuration file runs on both client and server at runtime. Avoid including secrets
+directly in your config as they may be exposed to the client.
+
+:::
+
+## Example
+
+Below is an example of the default Dev Portal configuration. You can edit this configuration to suit
+your own needs.
+
+```ts title=zudoku.config.ts
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  navigation: [
+    {
+      type: "category",
+      label: "Documentation",
+      items: ["introduction", "example"],
+    },
+    { type: "link", to: "api", label: "API Reference" },
+  ],
+  redirects: [{ from: "/", to: "/docs/introduction" }],
+  apis: {
+    type: "file",
+    input: "./apis/openapi.yaml",
+    path: "/api",
+  },
+  docs: {
+    files: "/pages/**/*.{md,mdx}",
+  },
+};
+
+export default config;
+```
+
+## Configuration options
+
+### `apis`
+
+There are multiple options for referencing your OpenAPI document. The example below uses a URL to an
+OpenAPI document, but you can also use a local file path. For full details on the options available,
+see the [API Reference](./api-reference.md).
+
+```ts
+{
+  // ...
+  "apis": {
+    "type": "url",
+    "input": "https://rickandmorty.zuplo.io/openapi.json",
+    "path": "/api"
+  }
+  // ...
+}
+```
+
+### `site`
+
+Controls global page attributes across the site, including logos and the site title.
+
+**Example:**
+
+```ts
+{
+  // ...
+  "site": {
+    "title": "Our Documentation",
+    "logo": {
+      "src": {
+        "light": "/logos/zudoku-light.svg",
+        "dark": "/logos/zudoku-dark.svg"
+      },
+      "width": "99px"
+    }
+  }
+  // ...
+}
+```
+
+### `navigation`
+
+Defines navigation for both the top bar and the sidebar. Items can be categories, links or custom
+pages.
+
+```ts
+{
+  // ...
+  "navigation": [
+    { "type": "category", "label": "Docs", "items": ["introduction"] },
+    { "type": "link", "to": "api", "label": "API Reference" }
+  ]
+  // ...
+}
+```
+
+### `theme`
+
+Allows you to control the dark and light themes that persist across each MDX page, and the API
+reference.
+
+You can customize your theme as much as you want using
+[ShadCDN UI theme variables](https://ui.shadcn.com/docs/theming#list-of-variables). In the example
+below only the `primary` and `primaryForeground` variables are used but you can add any additional
+variables from ShadCDN UI that you would like to change.
+
+**Tip**: Use the
+[ShadCDN UI Theme Generator](https://zippystarter.com/tools/shadcn-ui-theme-generator) to create a
+great looking theme based off your primary color.
+
+**Example:**
+
+```ts
+{
+  // ...
+  "theme": {
+    "light": {
+      "primary": "316 100% 50%",
+      "primaryForeground": "360 100% 100%"
+    },
+    "dark": {
+      "primary": "316 100% 50%",
+      "primaryForeground": "360 100% 100%"
+    }
+  }
+  // ...
+}
+```
+
+### `metadata`
+
+Controls the site metadata for your documentation. All possible options are outlined in the example
+below.
+
+**Example:**
+
+```ts
+{
+  // ...
+  "metadata": {
+    "title": "Example Website Title",
+    "description": "This is an example description for the website.",
+    "logo": "https://example.com/logo.png",
+    "favicon": "https://example.com/favicon.ico",
+    "generator": "Website Generator 1.0",
+    "applicationName": "Example App",
+    "referrer": "no-referrer",
+    "keywords": ["example", "website", "metadata", "SEO"],
+    "authors": ["John Doe", "Jane Smith"],
+    "creator": "John Doe",
+    "publisher": "Example Publisher Inc."
+  }
+  // ...
+}
+```
+
+### `docs`
+
+Configures where your non API reference documentation can be found in your folder structure. The
+default is shown in the example below and you don't need to change it unless you want a different
+structure in place, or to have it match an existing structure that you already have.
+
+**Example:**
+
+```ts
+{
+  // ...
+  "docs": {
+    "files": "/pages/**/*.{md,mdx}"
+  }
+  // ...
+}
+```
+
+### `sitemap`
+
+Controls the sitemap for your documentation. All possible options are outlined in the example below.
+
+```ts
+{
+  // ...
+  "sitemap": {
+    // The base url for your site
+    // Required
+    "siteUrl": "https://example.com",
+    // The change frequency for the pages
+    // Defaults to daily
+    "changefreq": "daily",
+    // The priority for the pages
+    // Defaults to 0.7
+    "priority": 0.7,
+    // The output directory for the sitemap
+    // Defaults to undefined
+    "outDir": "sitemaps/",
+    // Whether to include the last modified date
+    // Defaults to true
+    "autoLastmod": true,
+    // The pages to exclude from the sitemap
+    // Can also be a function that returns an array of paths
+    // () => Promise<string[]>
+    "exclude": ["/404", "/private/page"]
+  }
+  // ...
+}
+```
+
+### `redirects`
+
+Implements any page redirects you want to use. This gives you control over the resource names in the
+URL.
+
+**Example:**
+
+```ts
+{
+  // ...
+  "redirects": [
+    { "from": "/", "to": "/documentation/introduction" },
+    { "from": "/documentation", "to": "/documentation/introduction" }
+  ]
+  // ...
+}
+```
+
+### `port`
+
+The port on which the development server will run. Defaults to `3000`. This option can also be
+passed to the CLI as `--port' (which takes precedence).
+
+```ts
+{
+  "port": 9001
+}
+```
+
+If the port is already in use, the next available port will be used.
+
+### `basePath`
+
+Sets the base path for your documentation site. This is useful when you want to host your
+documentation under a specific path.
+
+```ts
+{
+  basePath: "/docs",
+  // A page defined as `/intro` would result in: https://example.com/docs/intro
+}
+```
+
+### `canonicalUrlOrigin`
+
+Sets the canonical [origin URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin) for
+your documentation site. This is used for SEO purposes and helps search engines understand the
+preferred version of a page.
+
+```ts
+{
+  basePath: '/docs',
+  canonicalUrlOrigin: "https://example.com",
+  // visiting the page `/intro` would result in:
+  // https://example.com/docs/intro
+}
+```
+
+This is the resulting HTML that will be added to the `<head>` of your pages:
+
+```html
+<link rel="canonical" href="https://example.com/docs/intro" />
+```
+
+### `cdnUrl`
+
+Configures the CDN URL for your documentation site's assets. You can provide either a string for a
+single CDN URL or an object to specify different URLs for base and media assets.
+
+```ts
+// Single CDN URL
+{
+  cdnUrl: "https://cdn.example.com"
+}
+
+// Separate URLs for base and media assets
+{
+  cdnUrl: {
+    base: "https://cdn.example.com",
+    media: "https://media.example.com"
+  }
+}
+```
+
+### `https`
+
+Enables HTTPS for the dev server. `key` and `cert` are required and `ca` is optional.
+
+```ts
+{
+  "https": {
+    "key": "/path/to/key.pem",
+    "cert": "/path/to/cert.pem",
+    "ca": "/path/to/ca.pem"
+  }
+}
+```
+
+### `enableStatusPages`
+
+Enables static generation of status pages for your site. This results in several files (404.html,
+500.html, etc.) being generated in the `dist` directory. This is useful as many hosting providers
+will serve these files automatically when a user visits a non-existent page or encounters an error.
+
+This option is enabled by default, but you can disable it if you don't need these pages.
+
+```ts
+{
+  enableStatusPages: false;
+}
+```
+
+## Multiple Files
+
+The configuration file is a standard JavaScript or TypeScript file, so you can split it into
+multiple files if you prefer. This can be useful if you have a large configuration or want to keep
+your code organized.
+
+For example, if you wanted to move your navigation configuration to a separate file, you could
+create a new file called `navigation.ts` and export the navigation configuration from there.
+
+```ts
+// navigation.ts
+import type { Navigation } from "zudoku";
+
+export const navigation: Navigation = [
+  {
+    type: "category",
+    label: "Documentation",
+    items: ["example", "other-example"],
+  },
+];
+```
+
+Then you can import the navigation configuration into your main configuration file.
+
+```ts title=zudoku.config.ts
+// zudoku.config.ts
+import type { ZudokuConfig } from "zudoku";
+import { navigation } from "./navigation";
+
+const config = {
+  // ...
+  navigation,
+  // ...
+};
+
+export default config;
+```

package/docs/dev-portal/zudoku/configuration/protected-routes.md

@@ -0,0 +1,149 @@
+---
+title: Protected Routes
+sidebar_icon: squares-subtract
+description:
+  Learn how to protect specific routes in your documentation using authentication, including simple
+  array patterns, advanced authorization with reason codes, and custom callback functions.
+---
+
+You can protect specific routes in your documentation by adding the `protectedRoutes` property to
+your [Dev Portal configuration](./overview.md). This requires [authentication](./authentication.md) to
+be configured. The property supports two formats: a simple array of path patterns, or an advanced
+object format with custom authorization logic.
+
+:::note{title="Client-side protection only"}
+
+`protectedRoutes` are client-side only. Do not rely on `protectedRoutes` to hide sensitive
+information.
+
+We are working on an additional offering that secures this data server-side.
+
+:::
+
+## Array Format
+
+The simplest way to protect routes is to provide an array of path patterns. Users must be
+authenticated to access these routes.
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  protectedRoutes: [
+    "/admin/*",     // Protect all routes under /admin
+    "/settings",    // Protect the settings page
+    "/api/*",       // Protect all API-related routes
+    "/private/:id"  // Protect dynamic routes with parameters
+  ],
+  // ...
+}
+```
+
+When a user tries to access a protected route, a login dialog will appear prompting them to sign in
+or register. After logging in, they are automatically redirected back to the route they were trying
+to access.
+
+## Object Format
+
+For more complex authorization logic, you can provide a record mapping route patterns to custom
+callback functions:
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  protectedRoutes: {
+    // Only allow authenticated users with admin role
+    "/admin/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.role === "admin",
+
+    // Check if user has enterprise access
+    "/api/enterprise/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.subscription === "enterprise",
+
+    // Allow access to beta features based on user attributes
+    "/beta/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.betaAccess === true,
+  },
+  // ...
+}
+```
+
+### Callback Parameters
+
+The callback function receives an object with:
+
+- `auth` - The current authentication state, including `isAuthenticated`, `isPending`, `profile`,
+  and more
+- `context` - The Dev Portal context providing access to configuration and utilities
+- `reasonCode` - An object containing the reason code constants `UNAUTHORIZED` and `FORBIDDEN` (see
+  [Reason Codes](#reason-codes))
+
+### Return Values
+
+The callback can return a `boolean` or a reason code string:
+
+| Return value              | Behavior                                          |
+| ------------------------- | ------------------------------------------------- |
+| `true`                    | Allow access to the route                         |
+| `false`                   | Treated as `UNAUTHORIZED` - prompts login         |
+| `reasonCode.UNAUTHORIZED` | Show a login dialog prompting the user to sign in |
+| `reasonCode.FORBIDDEN`    | Show a 403 "Access Denied" page                   |
+
+## Reason Codes
+
+Reason codes allow you to distinguish between users who need to sign in and users who are signed in
+but lack permission. This is useful for building role-based or attribute-based access control.
+
+- **`UNAUTHORIZED`** - The user is not authenticated. A login dialog is shown, and navigation to the
+  route is blocked until the user signs in.
+- **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
+  page is displayed instead of the route content.
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  protectedRoutes: {
+    // Members-only page: unauthenticated users see a login prompt
+    "/only-members": ({ auth, reasonCode }) =>
+      auth.isAuthenticated ? true : reasonCode.UNAUTHORIZED,
+
+    // VIP page: unauthenticated users see a login prompt,
+    // authenticated users without permission see "Access Denied"
+    "/vip-lounge": ({ auth, reasonCode }) =>
+      !auth.isAuthenticated
+        ? reasonCode.UNAUTHORIZED
+        : auth.profile?.email?.endsWith("@example.com")
+          ? true
+          : reasonCode.FORBIDDEN,
+  },
+  // ...
+}
+```
+
+## Navigation Blocking
+
+When a user navigates to a route that returns `false` or `UNAUTHORIZED`, navigation is intercepted
+before the page changes. The user stays on the current page while a login dialog is displayed. If
+the user cancels, they remain on the current page. If they log in successfully, navigation
+automatically proceeds to the protected route.
+
+Routes that return `FORBIDDEN` do not block navigation — the user navigates to the route and sees
+the "Access Denied" page.
+
+## Path Patterns
+
+The path patterns follow the same syntax as [React Router](https://reactrouter.com):
+
+- `:param` matches a URL segment up to the next `/`, `?`, or `#`
+- `*` matches zero or more characters up to the next `/`, `?`, or `#`
+- `/*` matches all characters after the pattern
+
+For example:
+
+- `/users/:id` matches `/users/123` or `/users/abc`
+- `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
+- `/settings` matches only the exact path `/settings`
+
+## Next Steps
+
+- Learn about [authentication providers](./authentication.md#authentication-providers) supported by
+  Dev Portal - Configure [user data](./authentication.md#user-data) display

package/docs/dev-portal/zudoku/configuration/search.md

@@ -0,0 +1,169 @@
+---
+title: Search
+sidebar_icon: search-code
+description:
+  Learn how to configure and customize search functionality in Zudoku, including setup instructions
+  for Pagefind and Inkeep providers, result transformation, and ranking options.
+---
+
+Dev Portal offers search functionality that enhances user experience by enabling content discovery
+across your site. When configured, a search bar will appear in the header, allowing users to quickly
+find relevant information on any page.
+
+We currently support three search providers:
+
+- [Pagefind](https://pagefind.app/)
+- [Algolia DocSearch](https://docsearch.algolia.com/)
+- [Inkeep](https://inkeep.com/)
+
+## Pagefind
+
+[Pagefind](https://pagefind.app/) is a lightweight, static search library that can be used to add
+search to your Dev Portal site without any external services.
+
+To enable pagefind search, configure the `search` option in your configuration:
+
+```typescript
+{
+  search: {
+    type: "pagefind",
+    // Optional: Maximum number of sub results per page
+    maxSubResults: 3,
+    // Optional: Configure search result ranking (defaults shown below)
+    ranking: {
+      termFrequency: 0.8,
+      pageLength: 0.6,
+      termSimilarity: 1.2,
+      termSaturation: 1.2,
+    },
+  }
+}
+```
+
+### Transforming/Filtering Search Results
+
+You can transform or filter search results using the `transformResults` option. This function
+receives the search result along with the current auth state and context, allowing you to:
+
+- Filter results based on user permissions
+- Modify result content
+- Add custom results
+
+The type of `result` is the same as
+[the type returned by Pagefind's search API](https://github.com/Pagefind/pagefind/blob/03552d041d9533b09563f6c50466b25d394ece64/pagefind_web_js/types/index.d.ts#L123-L160).
+
+```typescript
+{
+  search: {
+    type: "pagefind",
+    transformResults: ({ result, auth, context }) => {
+      // Return false to filter out the result
+      if (!auth.isAuthenticated) return false;
+
+      // Return true or undefined to keep the original result
+      if (result.url.includes("/private/")) return true;
+
+      // Return a modified result
+      return {
+        ...result,
+        title: `${result.title} (${context.meta.title})`
+      };
+    }
+  }
+}
+```
+
+For more information about how Pagefind's ranking system works and how to customize it for your
+content, see the [Pagefind ranking documentation](https://pagefind.app/docs/ranking/).
+
+## Algolia DocSearch
+
+[Algolia DocSearch](https://docsearch.algolia.com/) is a free search solution for open-source
+documentation sites. You can apply for the free DocSearch program or use your own Algolia account.
+
+:::note
+
+Algolia DocSearch is provided as a separate plugin package (`@zudoku/plugin-search-algolia`). We are
+experimenting with external plugin packages as a distribution model for new integrations.
+
+:::
+
+### Installation
+
+```bash
+npm install @zudoku/plugin-search-algolia
+```
+
+### Configuration
+
+Import the plugin and add it to the `plugins` array in your Dev Portal configuration:
+
+```typescript
+import { algoliaSearchPlugin } from "@zudoku/plugin-search-algolia";
+
+const config = {
+  plugins: [
+    algoliaSearchPlugin({
+      appId: "YOUR_APP_ID",
+      apiKey: "YOUR_SEARCH_API_KEY",
+      indices: ["YOUR_INDEX_NAME"],
+    }),
+  ],
+};
+```
+
+You can get your credentials by [applying for DocSearch](https://docsearch.algolia.com/apply/) or
+creating an index through the [Algolia dashboard](https://www.algolia.com/dashboard).
+
+Any additional [DocSearch options](https://docsearch.algolia.com/docs/api/) can be passed alongside
+the required fields.
+
+## Inkeep
+
+[Inkeep](https://inkeep.com/) is an AI-powered search and chat platform that can index your
+documentation and provide intelligent search capabilities to your users.
+
+### Setting up Inkeep Integration
+
+Before you can use Inkeep search in your Dev Portal site, you need to set up an Inkeep integration and
+have your site indexed. Here's how to get started:
+
+#### 1. Create an Inkeep Account
+
+1. Go to [Inkeep](https://inkeep.com/) and sign up for an account
+2. Navigate to the [Inkeep Portal](https://portal.inkeep.com/)
+
+#### 2. Set up Site Indexing
+
+1. In the Inkeep Portal, create a new project or integration
+2. Configure your site URL so Inkeep can crawl and index your documentation
+3. Ensure your Dev Portal site is deployed and publicly accessible for indexing
+4. Wait for Inkeep to crawl and index your site content (this may take some time)
+
+#### 3. Get Your Integration Credentials
+
+To add Inkeep search to your site you will need to copy some variables from your
+[Inkeep account setting](https://portal.inkeep.com/):
+
+- API Key
+- Integration ID
+- Organization ID
+
+#### 4. Configure Dev Portal 
+Once you have your credentials and your site is indexed, you can configure the `search` option in
+your [Dev Portal Configuration](./overview.md):
+
+```typescript
+{
+  // ...
+  search: {
+    type: "inkeep",
+    apiKey: "<your-api-key>",
+    integrationId: "<your-integration-id>",
+    organizationId: "<your-organization-id>",
+    primaryBrandColor: "#26D6FF",
+    organizationDisplayName: "Your Organization Name",
+  }
+  // ...
+}
+```