zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/zudoku/markdown/frontmatter.md

@@ -0,0 +1,172 @@
+---
+sidebar_icon: scissors-line-dashed
+title: Frontmatter
+description:
+  Learn how to use YAML frontmatter in Dev Portal markdown files to customize page titles, descriptions,
+  navigation, and other document properties.
+---
+
+Frontmatter is metadata written in [YAML](https://yaml.org/) format at the beginning of markdown
+files, enclosed between triple dashes (`---`). It allows you to configure various aspects of your
+pages without affecting the visible content.
+
+In Zudoku, frontmatter enables you to customize page titles, descriptions, navigation settings, and
+other document properties. Here are all the supported properties:
+
+## Properties
+
+### `title`
+
+Sets the page title that appears in the browser tab and as the document title.
+
+```md
+---
+title: My Page Title
+---
+```
+
+### `description`
+
+Provides a description for the page, which can be used for SEO and content summaries.
+
+```md
+---
+description: This page explains how to use Zudoku's markdown features.
+---
+```
+
+### `category`
+
+Assigns the page to a specific category for organizational purposes. This will be shown above the
+main heading of the document.
+
+```md
+---
+category: Getting Started
+---
+```
+
+### `navigation_label`
+
+_Deprecated (`sidebar_label`)_
+
+Sets a custom label for the page in the sidebar navigation, allowing you to use a shorter or
+different title than the main page title.
+
+```md
+---
+title: My Very Long Documentation Page Title
+navigation_label: Short Title
+---
+```
+
+### `navigation_icon`
+
+_Deprecated (`sidebar_icon`)_
+
+Specifies a [Lucide icon](https://lucide.dev/icons) to display next to the page in the sidebar
+navigation.
+
+```md
+---
+navigation_icon: compass
+---
+```
+
+### `navigation_display`
+
+Specifies the display property of the navigation item. See the
+[Navigation guide](/dev-portal/zudoku/configuration/navigation#display-control)
+
+```md
+---
+navigation_display: auth
+---
+```
+
+### `toc`
+
+Controls whether the table of contents is displayed for the page. Set to `false` to hide the table
+of contents.
+
+```md
+---
+toc: false
+---
+```
+
+### `disable_pager`
+
+Controls whether the previous/next page navigation is displayed at the bottom of the page. Set to
+`true` to disable it.
+
+```md
+---
+disable_pager: true
+---
+```
+
+### `draft`
+
+Marks a document as a draft. Draft documents are only visible when running in development mode and
+are excluded from production builds. This is useful for working on content that isn't ready to be
+published.
+
+```md
+---
+draft: true
+---
+```
+
+:::info
+
+When `draft: true` is set:
+
+- The document will be visible when running `zudoku dev`
+- The document will be excluded from builds created with `zudoku build`
+- The document won't appear in the navigation or be accessible via URL in production
+
+:::
+
+### `lastModifiedTime`
+
+The last modified timestamp for the page. This property is automatically set by Dev Portal during the
+build process based on the Git commit history. You generally should not set this manually.
+
+If you need to override the automatically detected date, you can set it explicitly:
+
+```md
+---
+lastModifiedTime: 2025-11-20T10:30:00.000Z
+---
+```
+
+::if{mode=opensource}
+
+:::info
+
+For accurate last modified dates in deployment environments, ensure full Git history is available
+during builds. See the [Vercel deployment guide](/dev-portal/zudoku/deploy/vercel#accurate-last-modified-dates)
+for configuration details.
+
+:::
+
+::
+
+## Complete Example
+
+Here's an example showing multiple frontmatter properties used together:
+
+```md title=documentation.md
+---
+title: Advanced Configuration Guide
+description: Learn how to configure advanced features in Dev Portal category: Configuration
+navigation_label: Advanced Config
+navigation_icon: settings
+toc: true
+disable_pager: false
+draft: false
+---
+
+This page content follows the frontmatter...
+```

package/docs/dev-portal/zudoku/markdown/mdx.md

@@ -0,0 +1,68 @@
+---
+title: MDX
+sidebar_icon: notebook-pen
+description:
+  Learn how to use MDX in Dev Portal to create rich documentation pages with markdown and custom React
+  components.
+---
+
+Dev Portal supports MDX files for creating rich content pages. MDX is a markdown format that allows you
+to include JSX components in your markdown files.
+
+## Getting Started
+
+To use MDX in your documentation, simply create files with the `.mdx` extension instead of `.md`.
+These files work exactly like regular markdown files but with all MDX features unlocked - you can
+write normal markdown content and add JSX components whenever needed.
+
+```
+docs/
+├── my-page.md      # Regular markdown
+├── my-mdx-page.mdx # MDX with JSX support
+```
+
+## Custom Components
+
+Dev Portal supports the use of custom components in your MDX files. This allows you to create reusable
+components that can be used across multiple pages.
+
+You can create a custom component in your project and reference it in the
+[Dev Portal Configuration](./overview.md) file.
+
+For example, create the `<MyCustomComponent />` component in a file called `MyCustomComponent.tsx`
+in the `src` directory at the root of your project.
+
+```tsx
+export default function MyCustomComponent() {
+  return <div>My Custom Component</div>;
+}
+```
+
+In [Dev Portal Configuration](./overview.md) you will need to import the component and add it to the
+`customComponents` option in the configuration.
+
+```ts title=zudoku.config.ts
+import MyCustomComponent from "./src/MyCustomComponent";
+
+const config: ZudokuConfig = {
+  // ...
+  mdx: {
+    components: {
+      MyCustomComponent,
+    },
+  },
+  // ...
+};
+
+export default config;
+```
+
+## JSX in Headings
+
+JSX components in headings render in both the sidebar navigation and table of contents:
+
+```mdx
+# My Page <Badge>New</Badge>
+```
+
+Components must be registered via [`mdx.components`](#custom-components) to work in headings.

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

@@ -0,0 +1,275 @@
+---
+title: Markdown
+navigation_icon: align-left
+description:
+  Comprehensive guide to using Markdown and MDX in Zudoku, including formatting, frontmatter, syntax
+  highlighting, tables, lists, task lists, collapsible sections, and advanced documentation
+  features.
+---
+
+Dev Portal supports
+[GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+(GFM) with additional features for creating rich documentation.
+
+## Basic Formatting
+
+### Headers
+
+Use `#` to create headers. The number of `#` symbols determines the header level:
+
+```md
+# H1 Header
+
+## H2 Header
+
+### H3 Header
+
+#### H4 Header
+
+##### H5 Header
+
+###### H6 Header
+```
+
+### Text Formatting
+
+<!-- prettier-ignore -->
+```mdx
+**Bold text**
+_Italic text_
+~~Strikethrough text~~
+`Inline code`
+```
+
+**Bold text**  
+_Italic text_  
+~~Strikethrough text~~  
+`Inline code`
+
+### Lists
+
+**Unordered lists:**
+
+```md
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+```
+
+**Ordered lists:**
+
+```md
+1. First item
+2. Second item
+   1. Nested item
+   2. Another nested item
+```
+
+<details>
+<summary>See list examples</summary>
+
+**Unordered list:**
+
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+
+**Ordered list:**
+
+1. First item
+2. Second item
+   1. Nested item
+   2. Another nested item
+
+</details>
+
+### Links and Images
+
+```md
+[Link text](https://example.com)
+
+![Image alt text](image.jpg)
+```
+
+<details>
+<summary>See link and image examples</summary>
+
+[Link text](https://example.com)
+
+![Image alt text](https://images.unsplash.com/photo-1588083066783-8828e623bad7?q=75&w=400&auto=format&fit=crop)
+
+</details>
+
+### Tables
+
+```md
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+<details>
+<summary>See table example</summary>
+
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+
+</details>
+
+### Blockquotes
+
+```md
+> This is a blockquote
+>
+> It can span multiple lines
+```
+
+<details>
+<summary>See blockquote example</summary>
+
+> This is a blockquote
+>
+> It can span multiple lines
+
+</details>
+
+## Frontmatter
+
+Frontmatter allows you to configure page metadata using YAML at the beginning of your markdown
+files:
+
+```md
+---
+title: My Page Title
+description: Page description for SEO
+navigation_icon: book
+category: Getting Started
+---
+
+Your markdown content starts here...
+```
+
+Common frontmatter properties include `title`, `description`, `sidebar_icon`, and `category`. For a
+complete list of supported properties, see the [Frontmatter documentation](./frontmatter).
+
+## MDX Support
+
+Dev Portal supports [MDX](./mdx), allowing you to use JSX components within your markdown:
+
+```mdx title=my-page.mdx
+import MyCustomComponent from "./MyCustomComponent";
+
+# Regular Markdown
+
+This is regular markdown content.
+
+<MyCustomComponent prop="value" />
+
+You can mix markdown and JSX seamlessly.
+```
+
+MDX enables you to create interactive documentation with custom React components. Learn more in the
+[MDX documentation](./mdx).
+
+## Syntax Highlighting
+
+Dev Portal uses [Shiki](https://shiki.style/) for syntax highlighting in code blocks:
+
+````md
+```javascript
+function greet(name) {
+  console.log(`Hello, ${name}!`);
+}
+```
+````
+
+**Advanced features:**
+
+- Line highlighting: `{1,3-5}`
+- Word highlighting: `/keyword/`
+- Line numbers: `showLineNumbers`
+- Titles: `title="filename.js"`
+
+````
+```tsx {4-5} /useState/ title="Counter.tsx" showLineNumbers
+import { useState } from "react";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+````
+
+<details>
+<summary>See advanced features example</summary>
+
+```tsx {4-5} /useState/ title="Counter.tsx" showLineNumbers
+import { useState } from "react";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+</details>
+
+For complete syntax highlighting documentation, see [Code Blocks](./code-blocks).
+
+## Additional Features
+
+Dev Portal also supports:
+
+- [Admonitions](./admonitions) - Callout boxes for notes, warnings, and tips
+- Task lists with checkboxes
+- Automatic link detection
+
+### Task Lists
+
+```md
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+<details>
+<summary>See task list example</summary>
+
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+
+</details>
+
+### Collapsible Sections
+
+You can create collapsible content using HTML `<details>` and `<summary>` tags:
+
+```html
+<details>
+  <summary>Click to expand</summary>
+
+  This content is hidden by default and can be expanded by clicking the summary. You can include any
+  markdown content here: - Lists - **Bold text** - Code blocks - Images
+</details>
+```
+
+<details>
+<summary>Click to expand</summary>
+
+This content is hidden by default and can be expanded by clicking the summary.
+
+You can include any markdown content here:
+
+- Lists
+- **Bold text**
+- Code blocks
+- Images
+
+</details>

package/docs/dev-portal/zudoku/plugins.md

@@ -0,0 +1,5 @@
+---
+title: Dev Portal Plugins
+---
+
+Dev Portal can be extended using plugins.

package/docs/dev-portal/zudoku/writing.mdx

@@ -0,0 +1,72 @@
+---
+title: Writing
+sidebar_icon: book-open-text
+description: A guide to writing documentation in Dev Portal using Markdown and MDX.
+---
+
+Get started with creating rich documentation in Dev Portal using Markdown and MDX. This guide covers the
+essentials to help you begin documenting your project.
+
+## Quick Start
+
+1. **Create a markdown file** in your `pages` directory
+2. **Add frontmatter** with title and metadata
+3. **Configure navigation** to make it discoverable
+4. **Write content** using Markdown or MDX
+
+### Basic Document Structure
+
+```md
+---
+title: My Document
+sidebar_icon: file-text
+---
+
+Your content goes here using standard Markdown syntax.
+```
+
+## Adding to Navigation
+
+To make your documentation discoverable, add it to the navigation configuration. Documents are
+referenced by their file path:
+
+```ts title="zudoku.config.ts"
+const config = {
+  navigation: [
+    {
+      type: "doc",
+      file: "my-document",
+      label: "My Document",
+    },
+  ],
+};
+```
+
+Learn more about configuring navigation at
+[Navigation → Documents](/dev-portal/zudoku/configuration/navigation#type-doc).
+
+## File Organization
+
+Organize your documentation files in logical directories:
+
+```
+pages/
+├── getting-started/
+│   ├── installation.md
+│   └── quick-start.md
+├── guides/
+│   ├── authentication.md
+│   └── deployment.md
+└── api/
+    └── reference.md
+```
+
+## What's Next?
+
+Explore the detailed guides to enhance your documentation:
+
+- **[Markdown Overview](/dev-portal/zudoku/markdown/overview)** - Complete markdown syntax reference
+- **[Frontmatter](/dev-portal/zudoku/markdown/frontmatter)** - Document metadata and configuration
+- **[MDX](/dev-portal/zudoku/markdown/mdx)** - Interactive components in markdown
+- **[Admonitions](/dev-portal/zudoku/markdown/admonitions)** - Callouts and alerts
+- **[Code Blocks](/dev-portal/zudoku/markdown/code-blocks)** - Syntax highlighting and features

package/docs/errors/bad-request.mdx

@@ -0,0 +1,39 @@
+---
+title: Bad Request (BAD_REQUEST)
+---
+
+The request was invalid. The response body typically contains specific error
+details explaining what went wrong.
+
+## Common causes
+
+- **Malformed JSON body** - The request body contains invalid JSON, such as
+  missing commas, unclosed brackets, or trailing commas.
+- **Missing required fields** - The request is missing one or more fields that
+  the API expects.
+- **Invalid Content-Type header** - The `Content-Type` header does not match the
+  format of the request body. For example, sending JSON without setting
+  `Content-Type: application/json`.
+- **Invalid parameter types** - A field value does not match the expected type,
+  such as sending a string where a number is required.
+
+## How to debug
+
+1. Check the response body for specific error messages. Zuplo returns detailed
+   error information that identifies the exact issue.
+2. Validate the request body using a JSON linter or validator before sending.
+3. Verify that all required headers are present and correctly formatted.
+4. Compare the request against the API documentation to ensure all required
+   fields are included with the correct types.
+
+:::tip
+
+Use a tool like `curl -v` or an API client such as Postman to inspect the full
+request and response, including headers and body.
+
+:::
+
+## Related errors
+
+If the request body fails JSON Schema validation, see
+[Schema Validation Failed](./schema-validation-failed.mdx) for more details.

package/docs/errors/build-error.mdx

@@ -0,0 +1,45 @@
+---
+title: Build Error (BUILD_ERROR)
+---
+
+There was an error building your project. The gateway returns this error when
+the project fails to compile during deployment.
+
+## Common causes
+
+- **TypeScript errors** - Type mismatches, missing type definitions, or invalid
+  TypeScript syntax prevent the project from compiling.
+- **Missing imports** - A module or package referenced in the code is not
+  installed or does not exist.
+- **Invalid route configuration** - The `routes.oas.json` file contains syntax
+  errors or references policies or handlers that do not exist.
+- **Incompatible dependencies** - A package dependency has version conflicts or
+  is not compatible with the Zuplo runtime.
+
+## How to access build logs
+
+1. Open the Zuplo portal and navigate to the project.
+2. Check the deployment logs for detailed error messages and stack traces.
+3. For local development, run the build locally to see the full error output.
+
+## How to fix
+
+1. Read the error message carefully. Build errors typically include the file
+   name, line number, and a description of the issue.
+2. Fix any TypeScript compilation errors by checking types and imports.
+3. Verify that all referenced modules are listed in `package.json` and properly
+   installed.
+4. Validate the `routes.oas.json` file to ensure all handler and policy
+   references are correct.
+
+:::tip
+
+Run builds locally before deploying to catch errors early. See
+[Local Development](../articles/local-development.mdx) for setup instructions.
+
+:::
+
+## Related resources
+
+- [Local Development](../articles/local-development.mdx)
+- [Local Development Troubleshooting](../articles/local-development-troubleshooting.mdx)

package/docs/errors/fatal-project-error.mdx

@@ -0,0 +1,39 @@
+---
+title: Zuplo Fatal Project Error (FATAL_PROJECT_ERROR)
+---
+
+There was a fatal error loading your Zuplo project. This error indicates a
+critical failure that prevents the project from starting.
+
+## Common causes
+
+- **Corrupted deployment** - The deployment artifacts are invalid or incomplete.
+- **Critical configuration errors** - The project configuration contains errors
+  that prevent the runtime from initializing.
+- **Infrastructure issues** - A temporary platform issue may prevent the project
+  from loading.
+
+## Recovery steps
+
+1. Check the deployment logs in the Zuplo portal for specific error details.
+2. Try redeploying the project. This resolves issues caused by transient
+   infrastructure problems.
+3. Review recent changes to the project configuration, routes, or code for
+   anything that could cause a fatal error.
+4. Roll back to a previous working deployment if available.
+
+:::caution
+
+This error affects all routes in the project. No requests can be processed until
+the issue is resolved.
+
+:::
+
+## When to contact support
+
+Contact [Zuplo support](../articles/support.mdx) if:
+
+- Redeploying does not resolve the error.
+- No recent changes were made to the project.
+- The error persists across multiple deployment attempts.
+- The deployment logs do not contain actionable error information.