zod-schema2md

Generate beautiful markdown documentation from your Zod schemas automatically

zod-schema2md analyzes your Zod schemas and generates clean markdown tables with:

• Field names and types
• Validation rules (min, max, regex, enums)
• Required/optional indicators
• Nested object support
• Array schemas with nested objects

Installation

npm install -D zod-schema2md
# or
yarn add -D zod-schema2md
# or
pnpm add -D zod-schema2md

Quick Start

1. Create a config file

npx zod-schema2md init

This creates zod-schema2md.config.ts:

import { defineConfig } from 'zod-schema2md';
import { UserSchema, ProductSchema } from './schemas';

export default defineConfig({
  schemas: [
    { name: 'User', schema: UserSchema },
    { name: 'Product', schema: ProductSchema },
  ],
  outputDir: './docs/schemas',
});

2. Generate documentation

npx zod-schema2md

That's it! Your markdown docs are ready in ./docs/schemas/.

Usage

CLI

# Generate with default config
npx zod-schema2md

# Generate with custom config
npx zod-schema2md generate -c path/to/config.ts

# Override output directory
npx zod-schema2md generate -o ./custom-output

# Initialize config file
npx zod-schema2md init

Programmatic API

import { ZodSchemaExporter } from 'zod-schema2md';
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(50),
  age: z.number().min(18).optional(),
  role: z.enum(['admin', 'user', 'guest']),
});

const exporter = new ZodSchemaExporter('./docs');

exporter.registerSchema('User', UserSchema);
exporter.exportAllSchemas();

In package.json scripts

{
  "scripts": {
    "docs:generate": "zod-schema2md",
    "docs:watch": "nodemon --watch src/schemas --exec zod-schema2md"
  }
}

Example Output

Given this schema:

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(50),
  age: z.number().min(18).optional(),
  role: z.enum(['admin', 'user', 'guest']),
  metadata: z.object({
    createdAt: z.date(),
    updatedAt: z.date(),
  }),
});

Generates:

index	type	min	max	enum	regex	remark
id	string				^[0-9a-f]{8}-[0-9a-f]{4}-...	required
email	string				^[^\s@]+@[^\s@]+\.[^\s@]+$	required
name	string	2	50			required
age	number	18
role	enum			admin, user, guest		required
metadata	object					required
createdAt	Date					required
updatedAt	Date					required

Features

• All Zod types supported (string, number, boolean, date, enum, arrays, objects, etc.)
• Validation rules extracted (min, max, length, regex, enums)
• Nested objects with proper indentation
• Array schemas with object items
• Optional/required field detection
• Multiple schemas in one run
• Auto-generated index file
• TypeScript-first with full type safety
• Zero config needed (with sensible defaults)
• Supports both Zod v3 and v4

Configuration Options

interface ZodSchema2MdConfig {
  schemas: Array<{
    name: string;        // Display name for the schema
    schema: any;         // The Zod schema
  }>;
  outputDir?: string;    // Output directory (default: './schema-export')
  format?: 'markdown';   // Output format (only markdown for now)
}

Real-World Example

// zod-schema2md.config.ts
import { defineConfig } from 'zod-schema2md';
import {
  LoginSchema,
  RegisterSchema,
  UserUpdateSchema,
  ProductSchema,
  OrderSchema,
} from './src/schemas';

export default defineConfig({
  schemas: [
    // Auth schemas
    { name: 'LoginSchema', schema: LoginSchema },
    { name: 'RegisterSchema', schema: RegisterSchema },
    { name: 'UserUpdateSchema', schema: UserUpdateSchema },
    
    // Business schemas
    { name: 'ProductSchema', schema: ProductSchema },
    { name: 'OrderSchema', schema: OrderSchema },
  ],
  outputDir: './docs/api-schemas',
});

Then run:

npm run docs:generate

Tips

1. Keep schemas in sync: Add schema generation to your CI/CD pipeline
2. Version your docs: Commit the generated markdown to git
3. Automate: Use nodemon or similar to regenerate on schema changes
4. Link in README: Point your API consumers to the generated docs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Yehonatan Moravia