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 |

License

© 2024 Giacomo Debidda // MIT License