Zudoku

https://zudoku.dev/docs/
Admin
Zudoku is a framework and CLI tool for building modern, customizable API documentation and developer...
Tokens:76,766
Snippets:1,051
Trust Score:8.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Vercel CLI Configuration Prompt

Source: https://zudoku.dev/docs/deploy/vercel

Example output from the Vercel CLI during project setup showing default framework detection settings.

```ansi
No framework detected. Default Project Settings:
- Build Command: `npm run vercel-build` or `npm run build`
- Development Command: None
- Install Command: `yarn install`, `pnpm install`, `npm install`, or `bun install`
- Output Directory: `public` if it exists, or `.`
? Want to modify these settings? (y/N)
```

--------------------------------

### JSON, YAML, and TOML examples

Source: https://zudoku.dev/docs/components/syntax-highlight

Examples for common configuration file formats.

```json
{
  "name": "zudoku",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}
```

```yaml
name: zudoku
version: 1.0.0
scripts:
  dev: vite
  build: vite build
```

```toml
[package]
name = "zudoku"
version = "1.0.0"

[dependencies]
react = "^19.0.0"
```

--------------------------------

### PHP example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of a PHP class with constructor property promotion.

```php
<?php
class User {
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly string $email
    ) {}

    public function getDisplayName(): string {
        return ucfirst($this->name);
    }
}
```

--------------------------------

### Markdown and MDX examples

Source: https://zudoku.dev/docs/components/syntax-highlight

Examples for documentation and component-based markdown.

```markdown
# Hello World

This is **bold** and _italic_ text.

- Item 1
- Item 2

[Link to Zudoku](https://zudoku.dev)
```

```mdx
import { Button } from "./Button";

# Welcome to MDX

<Button onClick={() => alert("Hello!")}>Click me</Button>
```

--------------------------------

### Shell and ANSI terminal examples

Source: https://zudoku.dev/docs/components/syntax-highlight

Examples for command-line scripts and terminal output.

```bash
#!/bin/bash

# Install and build
npm install

if [ "$NODE_ENV" = "production" ]; then
  npm run build
else
  npm run dev
fi
```

```ansi
$ pnpm run build

> zudoku@1.0.0 build

[36mvite v7.0.5 [32mbuilding for production...[0m
[32m✓ 34 modules transformed.
[90mdist/[39m[32mindex.html                 [0m[90m0.46 kB[0m [33m│ gzip:  0.30 kB[0m
[90mdist/[39m[36massets/index-4sK2hL.css   [0m[90m24.67 kB[0m [33m│ gzip:  4.72 kB[0m
[90mdist/[39m[35massets/index-B1tPwS.js   [0m[90m143.18 kB[0m [33m│ gzip: 46.13 kB[0m
[34m✓ built in 1.23s
```

--------------------------------

### Complete Site Configuration Example

Source: https://zudoku.dev/docs/configuration/site

A comprehensive example demonstrating multiple site configuration options combined.

```tsx
{
  site: {
    title: "My API Documentation",
    logo: {
      src: {
        light: "/images/logo-light.svg",
        dark: "/images/logo-dark.svg"
      },
      alt: "Company Logo",
      width: "100px",
    },
    notFoundPage: <NotFound />,
    banner: {
      message: "Welcome to our documentation!",
      color: "info",
      dismissible: true
    },
  }
}
```

--------------------------------

### C# example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of an asynchronous C# service class.

```csharp
using System;
using System.Linq;

public class UserService {
    private readonly List<User> _users = new();

    public async Task<User?> GetUserAsync(int id) {
        await Task.Delay(100);
        return _users.FirstOrDefault(u => u.Id == id);
    }
}
```

--------------------------------

### Install build-time dependencies

Source: https://zudoku.dev/docs/guides/mermaid

Install the necessary packages for build-time Mermaid rendering.

```bash
npm install rehype-mermaid
npm install -D playwright
npx playwright install
```

--------------------------------

### Rust example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of using a HashMap in Rust.

```rust
use std::collections::HashMap;

fn main() {
    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Red"), 50);

    println!("Team scores: {:?}", scores);
}
```

--------------------------------

### Install Vercel CLI

Source: https://zudoku.dev/docs/deploy/vercel

Global installation of the Vercel CLI via npm.

```bash
npm i -g vercel
```

--------------------------------

### Ruby example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of a simple Ruby class.

```ruby
class TodoList
  attr_reader :name, :items

  def initialize(name)
    @name = name
    @items = []
  end

  def add_item(description)
    @items << { description: description, completed: false }
  end
end
```

--------------------------------

### Complete Frontmatter Example

Source: https://zudoku.dev/docs/markdown/frontmatter

Demonstrates multiple configuration properties applied to a single document.

```md
---
title: Advanced Configuration Guide
description: Learn how to configure advanced features in Zudoku
category: Configuration
sidebar_label: Advanced Config
sidebar_icon: settings
toc: true
disable_pager: false
draft: false
---

This page content follows the frontmatter...
```

--------------------------------

### TypeScript, JavaScript, and TSX examples

Source: https://zudoku.dev/docs/components/syntax-highlight

Examples for common web development languages.

```typescript
interface User {
  name: string;
  age: number;
}

const greet = (user: User): string => `Hello, ${user.name}!`;
```

```javascript
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

console.log(fibonacci(10));
```

```tsx
export const App = () => {
  return <div>Hello, World!</div>;
};
```

--------------------------------

### JSON Placeholder API example

Source: https://zudoku.dev/docs/components/playground

Demonstrates a simple GET request with custom button text.

```tsx
<OpenPlaygroundButton server="https://jsonplaceholder.typicode.com" url="/photos" method="GET">
  Test Photos Endpoint
</OpenPlaygroundButton>
```

```tsx
<OpenPlaygroundButton server="https://jsonplaceholder.typicode.com" url="/photos" method="GET">
  Test Photos Endpoint
</OpenPlaygroundButton>
```

--------------------------------

### XML Configuration

Source: https://zudoku.dev/docs/components/syntax-highlight

Example XML configuration file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appSettings>
    <add key="ApplicationName" value="Zudoku" />
    <add key="Version" value="1.0.0" />
  </appSettings>
  <modules>
    <module name="Auth" enabled="true" />
    <module name="Logging" enabled="true" />
  </modules>
</configuration>
```

--------------------------------

### Python example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of an asynchronous Python class.

```python
import asyncio
from typing import List, Optional

class DataProcessor:
    def __init__(self, name: str):
        self.name = name

    async def process_items(self, items: List[str]) -> dict:
        results = [await self._process(item) for item in items]
        return {"processed": len(results), "items": results}
```

--------------------------------

### Install Supabase Dependencies

Source: https://zudoku.dev/docs/configuration/authentication-supabase

Install the required Supabase client package for Zudoku.

```bash
npm install @supabase/supabase-js
```

--------------------------------

### Launch development server

Source: https://zudoku.dev/docs

Starts the local development server with hot reloading enabled.

```bash
npm run dev
```

--------------------------------

### Add Dynamic Values to Examples

Source: https://zudoku.dev/docs/guides/transforming-examples

Inject authentication tokens or other dynamic values into example headers.

```tsx
transformExamples: ({ content, auth }) => {
  const apiKey = auth.accessToken;

  return content.map((contentItem) => ({
    ...contentItem,
    example: {
      ...contentItem.example,
      headers: {
        ...contentItem.example.headers,
        Authorization: `Bearer ${apiKey}`,
      },
    },
  }));
};
```

--------------------------------

### Install Mermaid dependency

Source: https://zudoku.dev/docs/components/mermaid

Install the required peer dependency for the Mermaid component.

```bash
npm install mermaid
```

--------------------------------

### Complete navigation configuration

Source: https://zudoku.dev/docs/guides/navigation-rules

A comprehensive example demonstrating multiple sequential navigation rules.

```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" },
  },
],
```

--------------------------------

### GraphQL schema example

Source: https://zudoku.dev/docs/components/syntax-highlight

Example of a GraphQL schema definition.

```graphql
type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
  users: [User!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
}
```

--------------------------------

### Markdown Links and Images Syntax

Source: https://zudoku.dev/docs/components/markdown

Example of link and image syntax.

```markdown
[Link text](https://example.com) ![Alt text](image.jpg)
```

--------------------------------

### Implementing a Sign-in Button

Source: https://zudoku.dev/docs/extending/hooks

Example component demonstrating how to handle authentication states and trigger login/logout actions.

```tsx
import { useAuth } from "zudoku/hooks";
import { Button } from "zudoku/ui/Button.js";

export const AuthButton = () => {
  const { isAuthenticated, isPending, profile, login, logout } = useAuth();

  if (isPending) {
    return <Button disabled>Loading…</Button>;
  }

  if (!isAuthenticated) {
    return <Button onClick={() => login()}>Sign in</Button>;
  }

  return (
    <div className="flex items-center gap-2">
      <span>Hi, {profile?.name ?? profile?.email}</span>
      <Button onClick={() => logout()}>Sign out</Button>
    </div>
  );
};
```

--------------------------------

### Transform Example Data

Source: https://zudoku.dev/docs/guides/transforming-examples

Practical implementation of the transformExamples function to inject dynamic properties like timestamps into example objects.

```tsx
const config: ZudokuConfig = {
  defaults: {
    apis: {
      transformExamples: ({ content, type }) => {
        // Example: Add a timestamp to all examples
        const timestamp = new Date().toISOString();

        return content.map((contentItem) => ({
          ...contentItem,
          example: {
            ...contentItem.example,
            timestamp,
            // You can modify other example properties here
          },
        }));
      },
    },
  },
};
```

--------------------------------

### Complete Footer Configuration

Source: https://zudoku.dev/docs/configuration/footer

A comprehensive example demonstrating all available footer configuration 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"
  }
}
```

--------------------------------

### Install Algolia DocSearch Plugin

Source: https://zudoku.dev/docs/configuration/search

Install the required package for Algolia DocSearch integration.

```bash
npm install @zudoku/plugin-search-algolia
```

--------------------------------

### Markdown Header Syntax

Source: https://zudoku.dev/docs/components/markdown

Example of header levels in markdown.

```markdown
# H1 Header

## H2 Header

### H3 Header
```

--------------------------------

### Button Sizes

Source: https://zudoku.dev/docs/components/button

Examples of different button size configurations.

```tsx
<Button size="default">Default Size</Button>
```

```tsx
<Button size="sm">Small Button</Button>
```

```tsx
<Button size="lg">Large Button</Button>
```

```tsx
<Button size="xl">Extra Large</Button>
```

```tsx
<Button size="icon">
  <PopcornIcon size={16} />
</Button>
```

--------------------------------

### Zuplo Echo API example

Source: https://zudoku.dev/docs/components/playground

Demonstrates testing a POST endpoint with headers, path parameters, query parameters, and a JSON body.

```tsx
<OpenPlaygroundButton
  server="https://echo.zuplo.io/"
  url="/hello-world/{name}"
  headers={[{ name: "X-Zudoku-Playground", defaultValue: "Hello World" }]}
  pathParams={[{ name: "name", defaultValue: "John" }]}
  queryParams={[
    { name: "age", defaultValue: "30" },
    { name: "city", defaultValue: "New York" },
  ]}
  body={JSON.stringify({ message: "Hello World" })}
  method="POST"
/>
```

```tsx
<OpenPlaygroundButton
  server="https://echo.zuplo.io/"
  url="/hello-world/{name}"
  headers={[
    {
      name: "X-Zudoku-Playground",
      defaultValue: "Hello World",
    },
  ]}
  pathParams={[{ name: "name", defaultValue: "John" }]}
  queryParams={[
    { name: "age", defaultValue: "30" },
    { name: "city", defaultValue: "New York" },
  ]}
  body={JSON.stringify({ message: "Hello World" })}
  method="POST"
/>
```

--------------------------------

### Example implementation with ClientOnly

Source: https://zudoku.dev/docs/components/client-only

Demonstrates integrating ClientOnly within a functional component to handle browser-specific logic.

```tsx
function MyComponent() {
  return (
    <div>
      <h1>This renders on both server and client</h1>
      <ClientOnly fallback={<Spinner />}>
        <ComponentThatUsesWindowObject />
      </ClientOnly>
    </div>
  );
}
```

--------------------------------

### Format Example Data

Source: https://zudoku.dev/docs/guides/transforming-examples

Apply custom formatting to dates and numeric values within example content.

```tsx
transformExamples: ({ content }) => {
  return content.map((contentItem) => ({
    ...contentItem,
    example: {
      ...contentItem.example,
      // Format dates in a specific way
      createdAt: new Date(contentItem.example.createdAt).toLocaleDateString(),
      // Format numbers with specific precision
      amount: Number(contentItem.example.amount).toFixed(2),
    },
  }));
};
```

--------------------------------

### Configure Okta OIDC in zudoku.config.ts

Source: https://zudoku.dev/docs/configuration/authentication-openid

Example configuration for integrating Okta as an identity provider.

```typescript
{
  authentication: {
    type: "openid",
    clientId: "<your-okta-client-id>",
    issuer: "https://your-tenant.okta.com/oauth2/default",
    scopes: ["openid", "profile", "email"],
  },
}
```

--------------------------------

### Badge Usage Example

Source: https://zudoku.dev/docs/components/badge

Demonstrates how to group multiple badges together.

```tsx
<Badge variant="default">New</Badge>
<Badge variant="secondary">Main</Badge>
<Badge variant="muted">10</Badge>
```

--------------------------------

### Common Navigation Patterns

Source: https://zudoku.dev/docs/components/link

Implementation examples for navigation menus, breadcrumbs, dynamic lists, and conditional rendering.

```tsx
function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/docs">Documentation</Link>
      <Link to="/api">API Reference</Link>
      <Link to="/blog">Blog</Link>
    </nav>
  );
}
```

```tsx
function Breadcrumbs({ path }) {
  return (
    <div className="breadcrumbs">
      <Link to="/">Home</Link>
      <span>/</span>
      <Link to="/docs">Docs</Link>
      <span>/</span>
      <span>{path}</span>
    </div>
  );
}
```

```tsx
function DocsList({ docs }) {
  return (
    <ul>
      {docs.map((doc) => (
        <li key={doc.id}>
          <Link to={`/docs/${doc.slug}`}>{doc.title}</Link>
        </li>
      ))}
    </ul>
  );
}
```

```tsx
function ConditionalLink({ to, disabled, children }) {
  if (disabled) {
    return <span className="disabled-link">{children}</span>;
  }

  return <Link to={to}>{children}</Link>;
}
```

--------------------------------

### Markdown Table Syntax

Source: https://zudoku.dev/docs/components/markdown

Example of table structure in markdown.

```markdown
| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |
```

--------------------------------

### Markdown List Syntax

Source: https://zudoku.dev/docs/components/markdown

Examples of unordered and ordered lists with nesting.

```markdown
- Unordered list item
- Another item
  - Nested item

1. Ordered list item
2. Another numbered item
```

--------------------------------

### Implement API Identity Plugin

Source: https://zudoku.dev/docs/concepts/auth-provider-api-identities

Configuration example for adding an API identity plugin to the Zudoku configuration.

```typescript
import { createApiIdentityPlugin } from "zudoku/plugins";

export default {
  authentication: {
    type: "auth0",
    domain: "my-domain.auth0.com",
    clientId: "my-client-id",
  },
  plugins: [
    createApiIdentityPlugin({
      getIdentities: async (context) => [
        {
          id: "api-key-one",
          label: "My API Key",
          authorizeRequest: (request) => {
            // We get the access token from the
            // authentication provider (Auth0) and add it to the request headers
            return context.authentication?.signRequest(request);
          },
        },
      ],
    }),
  ],
};
```

--------------------------------

### Configure MCP server in OpenAPI

Source: https://zudoku.dev/docs/guides/mcp-servers

Example of defining an MCP server within the OpenAPI paths object using the x-mcp-server extension.

```json
{
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/mcp/docs": {
      "post": {
        "x-mcp-server": { "name": "docs-mcp" },
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}
```

--------------------------------

### Markdown Emphasis Syntax

Source: https://zudoku.dev/docs/components/markdown

Examples of italic, bold, and strikethrough formatting.

```markdown
_italic_ or *italic*
**bold** or __bold__
**_bold italic_**
~~strikethrough~~
```

--------------------------------

### Rocket Callout

Source: https://zudoku.dev/docs/components/callout

Display a rocket callout for getting started guides.

```tsx
<Callout type="rocket" title="Getting started">
  Spin up your first project in minutes.
</Callout>
```

--------------------------------

### Example llms.txt output format

Source: https://zudoku.dev/docs/configuration/llms

The generated llms.txt file structure includes a title, description, instructions, and a list of documentation links.

```markdown
# Acme API

> Build and operate integrations with the Acme API.

Use these docs when creating or debugging an Acme integration. Start with the quickstart, then
consult the API reference for request and response schemas.

## Documentation

- [Quickstart](/docs/quickstart.md): Get started with Zudoku
- [Writing](/docs/writing.md): A guide to writing documentation
```

--------------------------------

### Configure category links

Source: https://zudoku.dev/docs/configuration/navigation

Examples of different ways to make a category label clickable.

```tsx
{
  type: "category",
  label: "Configuration",
  link: "docs/configuration/overview",
  items: [
    "docs/configuration/navigation",
    "docs/configuration/site",
  ],
}
```

```tsx
{
  type: "category",
  label: "Documentation",
  link: {
    type: "doc",
    file: "home.md",
    path: "/",
  },
  items: [
    "guides/getting-started",
    "guides/advanced",
  ],
}
```

```tsx
{
  type: "category",
  label: "API Reference",
  link: {
    type: "link",
    to: "/api",
  },
  items: [
    "guides/authentication",
    "guides/rate-limits",
  ],
}
```

--------------------------------

### Configure Keycloak OIDC in zudoku.config.ts

Source: https://zudoku.dev/docs/configuration/authentication-openid

Example configuration for integrating Keycloak using the realm issuer URL.

```typescript
{
  authentication: {
    type: "openid",
    clientId: "zudoku",
    issuer: "https://keycloak.example.com/realms/<your-realm>",
  },
}
```

--------------------------------

### Create a Zudoku project

Source: https://zudoku.dev/docs

Initializes a new project using the Zudoku CLI interactive prompts.

```bash
npm create zudoku@latest
```

--------------------------------

### Implement Custom API Key Management Service

Source: https://zudoku.dev/docs/guides/managing-api-keys-and-identities

Example implementation of the ApiKeyService interface for managing consumers and keys in custom storage.

```typescript
const config = {
  // ...
  apiKeys: {
    enabled: true,

    // Retrieve all API consumers and their keys
    getConsumers: async (context) => {
      // Implement fetching consumers from your storage
      // Each consumer can have multiple API keys
      return consumers;
    },

    // Create a new API key for a consumer
    createKey: async ({ apiKey, context, auth }) => {
      const newKey: ApiKey = {
        id: crypto.randomUUID(),
        key: `key-${crypto.randomUUID()}`,
        description: apiKey.description,
        createdOn: new Date().toISOString(),
        expiresOn: apiKey.expiresOn,
      };
      // Save the new key to your storage
      // Associate it with the current user/consumer
    },

    // Delete an API key
    deleteKey: async (consumerId, keyId, context) => {
      // Remove the key from the consumer's keys in your storage
    },

    // Regenerate an API key
    rollKey: async (consumerId, context) => {
      // Update the key value for the consumer while maintaining metadata
    },

    // Update consumer information
    updateConsumer: async (consumer, context) => {
      // Update the consumer's label or other metadata
    },

    // Get API usage statistics (optional)
    getUsage: async (apiKeys, context) => {
      // Fetch usage data for the provided API keys
    },
  },
};
```

--------------------------------

### Build the documentation site

Source: https://zudoku.dev/docs/deploy/cloudflare-pages

Generates the static files required for deployment in the dist folder.

```bash
npm run build
```

--------------------------------

### Link Path Types

Source: https://zudoku.dev/docs/components/link

Examples of relative, absolute, query parameter, and hash-based linking.

```tsx
// Relative to current route
<Link to="../parent-page">Up one level</Link>

// Relative to path
<Link to="./sibling-page" relative="path">
  Sibling page
</Link>
```

```tsx
<Link to="/absolute/path">Absolute Path</Link>
```

```tsx
<Link to="/search?q=react&type=docs">Search Results</Link>
```

```tsx
<Link to="/docs/api#authentication">Authentication Section</Link>
```

--------------------------------

### Advanced Link Functionality

Source: https://zudoku.dev/docs/components/link

Examples of custom styling, programmatic navigation, and confirmation dialogs.

```tsx
<Link to="/important-page" className="text-blue-600 hover:text-blue-800 underline">
  Important Page
</Link>
```

```tsx
import { useNavigate } from "react-router";

function MyComponent() {
  const navigate = useNavigate();

  const handleClick = () => {
    // Perform some logic
    navigate("/next-page");
  };

  return (
    <div>
      <Link to="/direct-link">Direct Link</Link>
      <button onClick={handleClick}>Programmatic Navigation</button>
    </div>
  );
}
```

```tsx
function DeleteLink({ itemId }) {
  const handleClick = (e) => {
    if (!confirm("Are you sure you want to delete this item?")) {
      e.preventDefault();
    }
  };

  return (
    <Link to={`/items/${itemId}/delete`} onClick={handleClick} className="text-red-600">
      Delete Item
    </Link>
  );
}
```

--------------------------------

### Input types

Source: https://zudoku.dev/docs/components/input

Examples of different input types including text, email, password, and number.

```tsx
<Input type="text" placeholder="Text input" />
```

```tsx
<Input type="email" placeholder="Email input" />
```

```tsx
<Input type="password" placeholder="Password input" />
```

```tsx
<Input type="number" placeholder="Number input" />
```

--------------------------------

### Configure transformExamples in zudoku.config.tsx

Source: https://zudoku.dev/docs/guides/transforming-examples

Define the transformExamples hook within the Zudoku configuration object to intercept and modify example content.

```tsx
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  // ... other config options ...
  defaults: {
    apis: {
      transformExamples: (options) => {
        // Transform the content here
        return options.content;
      },
    },
  },
};
```

--------------------------------

### Usage example for Slot components

Source: https://zudoku.dev/docs/components/slot

Demonstrates rendering a target and injecting content within a custom page component.

```tsx
function MyCustomPage() {
  return (
    <div>
      <h1>My Page</h1>

      {/* Render slot content here */}
      <Slot.Target name="custom-page-header" />

      {/* Inject content into a slot */}
      <Slot.Source name="custom-page-header">
        <div className="bg-blue-100 p-4 rounded">Custom header content</div>
      </Slot.Source>

      <p>Page content here...</p>
    </div>
  );
}
```

--------------------------------

### Create a custom page file

Source: https://zudoku.dev/docs/guides/custom-pages

Initialize a new component file in the project's source directory.

```bash
touch src/MyCustomPage.tsx
```

--------------------------------

### Match syntax examples

Source: https://zudoku.dev/docs/configuration/navigation

The match property uses slash-separated segments to target specific items in the navigation tree.

```json
match: "Users/Get User";      // by label
match: "Users/0";             // first item
match: "Users/-1";            // last item
match: "Users/Advanced/0";   // mixed nesting
```

--------------------------------

### Basic Link Usage

Source: https://zudoku.dev/docs/components/link

Examples of standard link configurations including internal navigation, state passing, history replacement, and full page reloads.

```tsx
<Link to="/docs/getting-started">Get Started</Link>
```

```tsx
<Link to="/profile" state={{ from: "header" }}>
  Profile
</Link>
```

```tsx
<Link to="/login" replace>
  Login
</Link>
```

```tsx
<Link to="/docs" reloadDocument>
  Full Page Reload
</Link>
```

--------------------------------

### Initialize Vercel Project

Source: https://zudoku.dev/docs/deploy/vercel

Command to initialize a new Vercel project in the current directory.

```bash
vercel
```

--------------------------------

### Install Sentry dependency

Source: https://zudoku.dev/docs/configuration/sentry

Install the required @sentry/react package via npm.

```bash
npm install --save @sentry/react
```

--------------------------------

### Use navigation shorthands

Source: https://zudoku.dev/docs/configuration/navigation

Referencing documents as strings for a more concise configuration.

```json
{
  "navigation": [
    {
      "type": "category",
      "label": "Documentation",
      "icon": "book",
      "items": [
        "documentation/introduction",
        "documentation/getting-started",
        "documentation/installation"
      ]
    },
    {
      "type": "link",
      "to": "/api",
      "label": "API Reference",
      "icon": "code"
    }
  ]
}
```

--------------------------------

### Navigate to project directory

Source: https://zudoku.dev/docs

Changes the current working directory to the newly created project folder.

```bash
cd your-project-name
```

--------------------------------

### Import SyntaxHighlight component

Source: https://zudoku.dev/docs/components/syntax-highlight

Import the component from the Zudoku UI library.

```tsx
import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight";
```

--------------------------------

### GET /posts

Source: https://zudoku.dev/docs/api-placeholder/~endpoints

Retrieve a list of all posts.

```APIDOC
## GET /posts

### Description
Retrieve a list of all posts.

### Method
GET

### Endpoint
https://jsonplaceholder.typicode.com/posts

### Response
#### Success Response (200)
- **id** (integer) - The post ID
- **userId** (integer) - The ID of the user who created the post
- **title** (string) - The title of the post
- **body** (string) - The content of the post

#### Response Example
[
  {
    "id": 0,
    "userId": 0,
    "title": "title",
    "body": "body"
  }
]
```

--------------------------------

### Define Project Structure

Source: https://zudoku.dev/docs/configuration/build-configuration

Shows the required location for the zudoku.build.ts file in the project root.

```bash
your-project/
├── zudoku.config.ts
├── zudoku.build.ts    # <-- Add this file
└── ...
```

--------------------------------

### Create a new Pages project

Source: https://zudoku.dev/docs/deploy/cloudflare-pages

Initializes a new project configuration for Cloudflare Pages via Wrangler.

```bash
npx wrangler pages project create
```

--------------------------------

### Button Variants

Source: https://zudoku.dev/docs/components/button

Examples of different button visual variants.

```tsx
<Button variant="default">Default Button</Button>
```

```tsx
<Button variant="destructive">Delete</Button>
```

```tsx
<Button variant="outline">Outline Button</Button>
```

```tsx
<Button variant="secondary">Secondary</Button>
```

```tsx
<Button variant="ghost">Ghost Button</Button>
```

```tsx
<Button variant="link">Link Button</Button>
```

--------------------------------

### GET /posts/{id}

Source: https://zudoku.dev/docs/api-placeholder/~endpoints

Retrieve a specific post by its ID.

```APIDOC
## GET /posts/{id}

### Description
Retrieve a specific post by its ID.

### Method
GET

### Endpoint
https://jsonplaceholder.typicode.com/posts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - Post ID

### Response
#### Success Response (200)
- **id** (integer) - The post ID
- **userId** (integer) - The ID of the user who created the post
- **title** (string) - The title of the post
- **body** (string) - The content of the post

#### Response Example
{
  "id": 0,
  "userId": 0,
  "title": "title",
  "body": "body"
}
```

--------------------------------

### Define a navigation category

Source: https://zudoku.dev/docs/configuration/navigation

Example of a category structure with a nested link.

```json
{
  "type": "category",
  "label": "Getting Started",
  "collapsible": true, // optional
  "collapsed": false, // optional
  "items": [
    {
      "type": "link",
      "label": "Support",
      "to": "https://support.example.com"
    }
  ]
}
```

--------------------------------

### Import BrowserWindow component

Source: https://zudoku.dev/docs/components/browser-window

Import the component from the zudoku library.

```tsx
import { BrowserWindow } from "zudoku/components";
```

--------------------------------

### Enable Markdown Publishing

Source: https://zudoku.dev/docs/configuration/docs

Toggle the generation of .md files for documentation pages during the build process.

```tsx
docs: {
  publishMarkdown: true,
}
```

--------------------------------

### Enable MCP with Boolean Shorthand

Source: https://zudoku.dev/docs/openapi-extensions/x-mcp-server

Set x-mcp-server to true to enable the MCP UI using the operation's summary as the server name.

```yaml
paths:
  /mcp:
    post:
      summary: My MCP Server
      x-mcp-server: true
      responses:
        "200":
          description: MCP response
```

--------------------------------

### Badge Variants

Source: https://zudoku.dev/docs/components/badge

Examples of different Badge variants available for use.

```tsx
<Badge variant="default">Default</Badge>
```

```tsx
<Badge variant="secondary">Secondary</Badge>
```

```tsx
<Badge variant="muted">Muted</Badge>
```

```tsx
<Badge variant="destructive">Destructive</Badge>
```

```tsx
<Badge variant="outline">Outline</Badge>
```

--------------------------------

### Create Profiles Table and Trigger

Source: https://zudoku.dev/docs/configuration/authentication-supabase

SQL schema for a profiles table and a trigger function to automatically create a record when a new user signs up.

```sql
CREATE TABLE profiles (
  id UUID REFERENCES auth.users ON DELETE CASCADE,
  username TEXT UNIQUE,
  bio TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  PRIMARY KEY (id)
);

-- Create trigger to automatically create profile on user signup
CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO public.profiles (id)
  VALUES (new.id);
  RETURN new;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();
```

--------------------------------

### GET /posts/{id}/comments

Source: https://zudoku.dev/docs/api-placeholder/~endpoints

Retrieve all comments for a specific post.

```APIDOC
## GET /posts/{id}/comments

### Description
Retrieve all comments for a specific post.

### Method
GET

### Endpoint
https://jsonplaceholder.typicode.com/posts/{id}/comments

### Parameters
#### Path Parameters
- **id** (integer) - Required - Post ID

### Response
#### Success Response (200)
- **id** (integer) - The comment ID
- **postId** (integer) - The ID of the post this comment belongs to
- **name** (string) - The name of the commenter
- **email** (string) - The email of the commenter
- **body** (string) - The content of the comment

#### Response Example
[
  {
    "id": 0,
    "postId": 0,
    "name": "name",
    "email": "test@example.com",
    "body": "body"
  }
]
```

--------------------------------

### Shell Commands in Stepper

Source: https://zudoku.dev/docs/components/stepper

Example of shell commands used within a step.

```sh
pnpm build
pnpm test
pnpm deploy --prod
```

--------------------------------

### Configure file-based versioning

Source: https://zudoku.dev/docs/configuration/api-reference

Provide an array of file paths to automatically generate versioned documentation. Metadata is extracted at build time.

```ts
const config = {
  apis: {
    type: "file",
    input: [
      // Order of the array determines the order of the versions
      "./openapi-v2.json",
      "./openapi-v1.json",
    ],
    path: "/api",
  },
};
```

--------------------------------

### Markdown Code Block Syntax

Source: https://zudoku.dev/docs/components/markdown

Example of a code block with syntax highlighting.

```markdown
```javascript
// Code block with syntax highlighting
function hello() {
  console.log("Hello, world!");
}
```
```

--------------------------------

### Enable API Catalog

Source: https://zudoku.dev/docs/configuration/api-catalog

Define the catalog path and label in the Zudoku configuration file.

```ts
const config = {
  // ...
  catalogs: {
    path: "/catalog",
    label: "API Catalog",
  },
  // ...
};
```

--------------------------------

### Component Integration and Accessibility

Source: https://zudoku.dev/docs/components/link

Examples of integrating Link with other components and ensuring accessibility.

```tsx
<Button asChild variant="outline">
  <Link to="/action">Perform Action</Link>
</Button>
```

```tsx
<Link to="/help" aria-label="Get help and support">
  Help
</Link>
```

--------------------------------

### Import LandingPage

Source: https://zudoku.dev/docs/components/landing-page

Import the component from the Zudoku library.

```tsx
import { LandingPage } from "zudoku/components";
```

--------------------------------

### Organize Documentation Files

Source: https://zudoku.dev/docs/writing

Structure your documentation using logical directories within the pages folder.

```text
pages/
├── getting-started/
│   ├── installation.md
│   └── quick-start.md
├── guides/
│   ├── authentication.md
│   └── deployment.md
└── api/
    └── reference.md
```

--------------------------------

### Implement Schema Processor

Source: https://zudoku.dev/docs/configuration/build-configuration

Example of a processor function that modifies OpenAPI schema operations.

```ts
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) {
        operation.description = "This is a public API endpoint";
      }
    });
  });

  return schema;
}

export default {
  processors: [addDescriptionProcessor],
};
```

--------------------------------

### Type-safe slot usage

Source: https://zudoku.dev/docs/components/slot

Example of using predefined slot names with autocomplete support.

```tsx
// These will show autocomplete for available slot names
<Slot.Target name="head-navigation-end" />
<Slot.Source name="footer-before">Content</Slot.Source>
```

--------------------------------

### Syntax Highlighting Configuration

Source: https://zudoku.dev/docs/markdown/code-blocks

Configuring themes and additional languages in zudoku.config.tsx.

```tsx
import { defaultLanguages, type ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  // ...
  syntaxHighlighting: {
    themes: {
      light: "vitesse-light",
      dark: "vitesse-dark",
    },
    // Extend default languages with additional ones
    // Aliases like "lisp" are resolved automatically
    languages: [...defaultLanguages, "rust", "ruby", "php", "powershell"],
  },
};
```

--------------------------------

### Markdown Inline Code Syntax

Source: https://zudoku.dev/docs/components/markdown

Example of inline code formatting using backticks.

```markdown
Inline `code` with backticks
```

--------------------------------

### Set a root landing page

Source: https://zudoku.dev/docs/guides/redirects

Redirects visitors from the portal root to a specific documentation page.

```ts
redirects: [{ from: "/", to: "/docs/introduction" }];
```

--------------------------------

### Gating Content with useAuth

Source: https://zudoku.dev/docs/extending/hooks

Example component that restricts access to children based on authentication status.

```tsx
import { useAuth } from "zudoku/hooks";

export const PremiumContent = ({ children }: { children: React.ReactNode }) => {
  const { isAuthenticated, isPending, login } = useAuth();

  if (isPending) return null;

  if (!isAuthenticated) {
    return (
      <button type="button" onClick={() => login({ redirectTo: window.location.href })}>
        Sign in to view this content
      </button>
    );
  }

  return <>{children}</>;
};
```

--------------------------------

### Define Navigation Items

Source: https://zudoku.dev/docs/configuration/overview

Set up the top bar and sidebar navigation using categories and links.

```ts
{
  // ...
  "navigation": [
    { "type": "category", "label": "Docs", "items": ["introduction"] },
    { "type": "link", "to": "api", "label": "API Reference" }
  ]
  // ...
}
```

--------------------------------

### Define a Custom Component

Source: https://zudoku.dev/docs/markdown/mdx

Example of a basic React component to be used within MDX files.

```tsx
export default function MyCustomComponent() {
  return <div>My Custom Component</div>;
}
```

--------------------------------

### Warning Alert Example

Source: https://zudoku.dev/docs/components/alert

Customized alert using utility classes to represent a warning state.

```tsx
<Alert className="border-yellow-200 bg-yellow-50 text-yellow-800 dark:border-yellow-800 dark:bg-yellow-950 dark:text-yellow-400">
  <AlertTitle>Warning!</AlertTitle>
  <AlertDescription>This action cannot be undone. Please proceed with caution.</AlertDescription>
</Alert>
```

--------------------------------

### Compare Navigation Configurations

Source: https://zudoku.dev/docs/guides/navigation-migration

Shows the transition from legacy topNavigation, sidebar, and customPages properties to the unified navigation array.

```tsx
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
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",
    },
  ],
};
```

--------------------------------

### Success Alert Example

Source: https://zudoku.dev/docs/components/alert

Customized alert using utility classes to represent a success state.

```tsx
<Alert className="border-green-200 bg-green-50 text-green-800 dark:border-green-800 dark:bg-green-950 dark:text-green-400">
  <CheckCircle2Icon className="h-4 w-4" />
  <AlertTitle>Success!</AlertTitle>
  <AlertDescription>Your changes have been saved successfully.</AlertDescription>
</Alert>
```

--------------------------------

### Project Directory Structure for Static Assets

Source: https://zudoku.dev/docs/deploy/zuplo

Place static files such as images and PDFs in the public directory to serve them at the root path.

```text
your-project/
├── public/
│   ├── images/
│   │   └── diagram.png
│   └── documents/
│       └── api-spec.pdf
└── ...
```

--------------------------------

### Use JWT Claims in Transformations

Source: https://zudoku.dev/docs/guides/transforming-examples

Extract and utilize user-specific claims from a JWT to customize example data.

```tsx
transformExamples: async ({ content, auth, context }) => {
  const token = await context.authentication.getAccessToken();

  // Decode the JWT (this is a simple example - in production you might want to use a proper JWT library)
  const [, payload] = token.split(".");
  const decodedPayload = JSON.parse(atob(payload));

  return content.map((contentItem) => ({
    ...contentItem,
    example: {
      ...contentItem.example,
      // Add user-specific data from the JWT
      userId: decodedPayload.sub,
      organizationId: decodedPayload.org_id,
      // You can add any other claims from the JWT
      role: decodedPayload.role,
    },
  }));
};
```

--------------------------------

### Basic OpenPlaygroundButton usage

Source: https://zudoku.dev/docs/components/playground

The component is available in MDX files without requiring explicit imports.

```tsx
<OpenPlaygroundButton {...props} />
```

--------------------------------

### File tree structure

Source: https://zudoku.dev/docs/configuration/docs

Visual representation of how file paths map to URL routes in Zudoku.

```text
pages/
├── introduction.md         → /introduction
├── quickstart.mdx          → /quickstart
├── guides/
│   ├── getting-started.md  → /guides/getting-started
│   └── advanced.md         → /guides/advanced
└── api/
    └── reference.md        → /api/reference
```

--------------------------------

### Add Social Links to Header

Source: https://zudoku.dev/docs/configuration/slots

Example of injecting multiple social media links into the navigation header.

```tsx
slots: {
  "head-navigation-end": () => (
    <div className="flex items-center gap-2">
      <Button variant="ghost" size="icon" asChild>
        <a href="https://github.com/your-org" target="_blank">
          <GithubIcon className="w-4 h-4" />
        </a>
      </Button>
      <Button variant="ghost" size="icon" asChild>
        <a href="https://discord.gg/your-server" target="_blank">
          <DiscordIcon className="w-4 h-4" />
        </a>
      </Button>
    </div>
  ),
}
```

--------------------------------

### Configure Basic Build Settings

Source: https://zudoku.dev/docs/configuration/build-configuration

Defines the structure for a basic build configuration file using ZudokuBuildConfig.

```ts
import type { ZudokuBuildConfig } from "zudoku";

const buildConfig: ZudokuBuildConfig = {
  processors: [
    async ({ schema }) => {
      // Transform your schema here
      return schema;
    },
  ],
  remarkPlugins: [],
  rehypePlugins: [],
};

export default buildConfig;
```

--------------------------------

### SidecarBox with code block

Source: https://zudoku.dev/docs/components/sidecar-box

Example of using p-0 on the body to allow a SyntaxHighlight component to fill the container.

```tsx
<SidecarBox.Root className="not-prose max-w-sm">
  <SidecarBox.Head className="text-xs font-medium">Example response</SidecarBox.Head>
  <SidecarBox.Body className="p-0">
    <SyntaxHighlight
      embedded
      language="json"
      className="rounded-none text-xs"
      code={`{
  "id": "usr_123",
  "name": "Ada Lovelace",
  "active": true
}`}
    />
  </SidecarBox.Body>
  <SidecarBox.Footer className="text-muted-foreground text-xs">200 OK</SidecarBox.Footer>
</SidecarBox.Root>
```

```tsx
<SidecarBox.Root>
  <SidecarBox.Head className="text-xs font-medium">Example response</SidecarBox.Head>
  <SidecarBox.Body className="p-0">
    <SyntaxHighlight
      embedded
      language="json"
      className="rounded-none text-xs"
      code={`{
  "id": "usr_123",
  "name": "Ada Lovelace",
  "active": true
}`}
    />
  </SidecarBox.Body>
  <SidecarBox.Footer className="text-muted-foreground text-xs">200 OK</SidecarBox.Footer>
</SidecarBox.Root>
```

--------------------------------

### Configure LLM documentation generation in zudoku.config.tsx

Source: https://zudoku.dev/docs/configuration/docs

Define settings for generating llms.txt and llms-full.txt files to assist LLM integration.

```tsx
docs: {
  llms: {
    llmsTxt: true,        // Generate llms.txt summary file
    llmsTxtFull: true,    // Generate llms-full.txt with complete content
    includeProtected: false,
    title: "Acme API",
    description: "Build and operate integrations with the Acme API.",
    instructions:
      "Use these docs when creating or debugging an Acme integration. Start with the quickstart, then use the API reference for request and response schemas."
  }
}
```

--------------------------------

### SidecarBox with status badge

Source: https://zudoku.dev/docs/components/sidecar-box

Example of a SidecarBox containing a header with a status badge and an embedded code block.

```tsx
<SidecarBox.Root className="not-prose max-w-sm">
  <SidecarBox.Head className="text-xs flex justify-between items-center">
    <span className="font-medium">GET /users/{`{id}`}</span>
    <Badge variant="muted">200</Badge>
  </SidecarBox.Head>
  <SidecarBox.Body className="p-0">
    <SyntaxHighlight
      embedded
      language="bash"
      className="rounded-none text-xs"
      code={`curl https://api.example.com/users/usr_123 \\
  -H "Authorization: Bearer $TOKEN"`}
    />
  </SidecarBox.Body>
</SidecarBox.Root>
```

```tsx
<SidecarBox.Root>
  <SidecarBox.Head className="text-xs flex justify-between items-center">
    <span className="font-medium">GET /users/{id}</span>
    <Badge variant="muted">200</Badge>
  </SidecarBox.Head>
  <SidecarBox.Body className="p-0">
    <SyntaxHighlight embedded language="bash" className="rounded-none text-xs" code={curlExample} />
  </SidecarBox.Body>
</SidecarBox.Root>
```
Tokens:
Raw