zod2md

Generate Markdown docs from Zod schemas.

Setup

Install the zod2md package (optional):

npm install --save-dev zod2md

Run the CLI. The following arguments are required:

• entry - path to file which exports Zod schemas,
• title - heading text for Markdown document,
• output - path where output Markdown file will be generated.

npx zod2md --entry src/schemas.ts --title "Models reference" --output docs/models.md

Configuration

Although most arguments may be provided directly to the CLI, it may be more convenient to use a configuration file.

For example, create the following zod2md.config.ts and then you can simply run npx zod2md:

import type { Config } from 'zod2md';

const config: Config = {
  entry: 'src/schemas.ts',
  title: 'Models reference',
  output: 'docs/models.md',
};

export default config;

CLI arguments take precedence over configuration file values.

CLI arguments

| Option | Type | Required | Description | | :--------------- | :--------------- | :------: | :------------------------------------------------------------------ | | -e, --entry | string[] (*) | yes | Entry point(s), i.e. paths to modules with Zod schema exports | | -t, --title | string | yes | Heading text for Markdown document | | -o, --output | string | yes | Output file path where Markdown document will be generared | | --tsconfig | string | no | Path to tsconfig.json to be used when importing entry point(s) | | -f, --format | 'esm' \| 'cjs' | no | Module type to assume when importing entry point(s) | | -c, --config | string | no | Path to configuration file (default is zod2md.config.{ts,mjs,js}) | | -h, --help | boolean | no | Display CLI help and exit |

(*) Use --entry PATH_1 --entry PATH_2 to provide multiple paths.

Configuration file reference

| Property | Type | Required | Description | | :-------------- | :---------------------------------------------------- | :------: | :----------------------------------------------------------------------------------------- | | entry | string \| string[] | yes | Entry point(s), i.e. paths to modules with Zod schema exports | | tsconfig | string | no | Path to tsconfig.json to be used when importing entry point(s) | | format | 'esm' \| 'cjs' | no | Module type to assume when importing entry point(s) | | title | string | yes | Heading text for Markdown document | | transformName | (name: string \| undefined, path: string) => string | no | Custom function for convert exported variable name and file path to display title (*) |

(*) Default is to strip Schema-suffix and convert to PascalCase (e.g. userSchema becomes User). In case of a default export, the file path is used.

Programmatic usage

It's also possible to import the core zod2md function to generate the Markdown string in your own code:

import { zod2md } from 'zod2md';

const markdown = await zod2md({
  entry: 'src/schemas.ts',
  title: 'Models reference',
});

Examples

A few examples of inputs and outputs are provided (used in E2E tests):

| Example | Source files | Generated docs | | :----------------------------------------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | | Prettier config file | e2e/fixtures/prettier | e2e/__snapshots__/prettier-example.md | | Commitlint config object | e2e/fixtures/commitlint | e2e/__snapshots__/commitlint-example.md | | User REST API | e2e/fixtures/user-rest-api | e2e/__snapshots__/user-rest-api-example.md |

Contributing

• Install dependencies with npm install.
• Run unit tests with npm test (uses Vitest).
• Run E2E tests with npm run e2e (uses Vitest and Verdaccio).
• Build library with npm run build (uses tsup).
• Release new version with npm run release (uses release-it).