Zudoku Framework Guide

Build beautiful API documentation sites and developer portals with Zudoku. This skill teaches you how to find current documentation and configure Zudoku projects.

Prerequisites

Before writing any Zudoku code, check if the package is installed:

ls node_modules/zudoku/

• If package exists: Use embedded docs first (most reliable)
• If no package: Install first or use remote docs

Documentation lookup guide

Quick Reference

Priority order for writing code

1. Embedded docs first (if package installed)

   Look up current types and config options in node_modules. Example:

   grep -r "ZudokuConfig" node_modules/zudoku/dist/
   

   • Why: Matches your EXACT installed version
   • Most reliable source of truth
   • More information: references/embedded-docs.md

2. Source code second (if package installed)

   If you can’t find what you need in the types, look directly at the source code:

   # Check type definitions
   cat node_modules/zudoku/dist/config.d.ts
   

   • Why: Ultimate source of truth if docs are missing or unclear
   • More information: references/embedded-docs.md

3. Remote docs third (if package not installed)

   Fetch the latest docs from the Zudoku website:

   https://zudoku.dev/llms.txt
   

   • Why: Latest published docs (may be ahead of installed version)
   • Use when: Package not installed or exploring new features
   • More information: references/remote-docs.md

Core concepts

Configuration

Zudoku uses a single configuration file (zudoku.config.ts or .tsx, .js, .mjs, .jsx) that controls structure, metadata, style, plugins, and routing.

import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  navigation: [
    { type: "category", label: "Documentation", items: ["introduction"] },
    { type: "link", to: "api", label: "API Reference" },
  ],
  apis: {
    type: "file",
    input: "./apis/openapi.yaml",
    path: "/api",
  },
  docs: {
    files: "/pages/**/*.{md,mdx}",
  },
};

export default config;

Key components

• Navigation: Top bar and sidebar structure (categories, links, custom pages)
• APIs: OpenAPI/Swagger specification integration for interactive API reference
• Docs: Markdown/MDX documentation pages with frontmatter
• Theme: Full color customization with light/dark mode (ShadCN UI variables)
• Plugins: Extensible architecture for search, auth, analytics, and more
• Authentication: Support for Auth0, Clerk, Supabase, Azure AD, Firebase, PingFederate

Content authoring

Zudoku supports GitHub Flavored Markdown and MDX (JSX in Markdown). Features include:

• Frontmatter for page metadata (title, description, sidebar icon)
• Code blocks with syntax highlighting, line numbers, and titles
• Admonitions/callouts (note, tip, caution, danger)
• 28+ built-in UI components (buttons, cards, dialogs, etc.)
• Interactive API playground component
• Mermaid diagrams

Plugin system

Zudoku is extensible with plugin types:

• CommonPlugin: Head elements, MDX components, initialization
• NavigationPlugin: Custom routes and sidebar items
• ApiIdentityPlugin: API authentication contexts
• SearchProviderPlugin: Custom search implementation
• EventConsumerPlugin: React to application events

Deployment

Zudoku supports deployment to:

• Zuplo (native)
• Vercel
• Cloudflare Pages
• GitHub Pages
• Apache/Nginx servers

Build with npm run build → outputs to /dist.

Critical requirements

Node.js version

Zudoku requires Node.js 22.7.0+ (or 20.19+).

Config file security

The config file runs on both client and server at runtime. Never include secrets directly in zudoku.config.ts — they will be exposed to the client.

When you see errors

Common signs of issues:

• Build failures or Vite errors
• Config type errors
• Missing module errors
• OpenAPI spec parsing errors

What to do:

1. Check references/common-errors.md
2. Verify current API in embedded docs
3. Check the Zudoku config type definitions

Development workflow

Always verify before writing code:

1. Check package installed

   ls node_modules/zudoku/
   

2. Look up current API
   • If installed → Use embedded docs references/embedded-docs.md
   • If not → Use remote docs references/remote-docs.md

3. Write code based on current docs

4. Test locally

   npm run dev  # http://localhost:3000
   

Resources

• Setup: references/create-zudoku.md
• Embedded docs lookup: references/embedded-docs.md - Start here if package is installed
• Remote docs lookup: references/remote-docs.md
• Common errors: references/common-errors.md
• Migrations: references/migration-guide.md