Generate Markdown docs from Zod schemas.
Install the zod2md package (optional):
npm install --save-dev zod2mdRun 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.mdAlthough 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.
| 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.
| 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.
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',
});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 |
- 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).