@jackdbd/zod-to-doc

Zod to Doc

Inject your Zod schemas into your docs.

About
Installation
Docs
Examples
- Usage as a CLI
  - Car table
- Usage as a library
  - Car tire table
Troubleshooting
Dependencies
License

About

I was looking for a way to keep my documentation updated with my Zod schemas. To my surprise, I couldn't find any tool that would output a string representation of a Zod schema. So I decided to write my own. You can use this tool either as a library or as a CLI.

Installation

npm install --save-dev @jackdbd/zod-to-doc

Docs

Docs generated by TypeDoc

📖 API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Examples

Here are some tables generated using a couple of Zod schemas exported by fixtures/schemas.mjs.

Usage as a CLI

Zod to Doc can be used as a CLI. For example, if you run this command and have the correct placeholder in your document (see this README.md in raw mode):

ztd --module ./fixtures/schemas.mjs \
  --schema car \
  --placeholder car-table \
  --title '#### Car table'

You get this output:

Car table

Key	Default	Description
`manufacturer`	`undefined`	Car manufacturer
`model`	`undefined`	Car model
`tires`	`undefined`	Array of 4 elements
`year`	`undefined`	Year in which the car was manufactured

Usage as a library

Zod to Doc can also be used as a library. For example, the readme.ts file in this repository uses markdownTableFromZodSchema to replace a mustache-style placeholder with this markdown table:

Car tire table

Key	Default	Description
`manufacturer`	`undefined`	Car tire manufacturer
`pressure`	`30`	Car tire pressure in PSI

Troubleshooting

This package uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=ztd:*

Dependencies

Package	Version
ansi-colors	`^4.1.3`
debug	`^4.3.4`
yargs	`^17.7.2`
zod	`^3.23.4`