Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jackdbd/zod-to-doc

Inject your Zod schemas into your docs
https://github.com/jackdbd/zod-to-doc

docs readme schemas zod

Last synced: 7 days ago
JSON representation

Inject your Zod schemas into your docs

Host: GitHub
URL: https://github.com/jackdbd/zod-to-doc
Owner: jackdbd
License: mit
Created: 2024-02-02T15:09:04.000Z (11 months ago)
Default Branch: main
Last Pushed: 2024-03-17T00:02:42.000Z (9 months ago)
Last Synced: 2024-04-14T07:40:01.319Z (8 months ago)
Topics: docs, readme, schemas, zod
Language: JavaScript
Homepage: https://jackdbd.github.io/zod-to-doc/
Size: 513 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

        # Zod to Doc

[![npm package badge](https://badge.fury.io/js/@jackdbd%2Fzod-to-doc.svg)](https://badge.fury.io/js/@jackdbd%2Fzod-to-doc)

[![install size](https://packagephobia.com/badge?p=@jackdbd/zod-to-doc)](https://packagephobia.com/result?p=@jackdbd/zod-to-doc)

[![CI](https://github.com/jackdbd/zod-to-doc/actions/workflows/ci.yaml/badge.svg)](https://github.com/jackdbd/zod-to-doc/actions/workflows/ci.yaml)

[![CodeCov badge](https://codecov.io/gh/jackdbd/zod-to-doc/graph/badge.svg?token=9jddzo5Dt3)](https://codecov.io/gh/jackdbd/zod-to-doc)

[![CodeFactor badge](https://www.codefactor.io/repository/github/jackdbd/zod-to-doc/badge)](https://www.codefactor.io/repository/github/jackdbd/zod-to-doc)

[![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/zod-to-doc)](https://socket.dev/npm/package/@jackdbd/zod-to-doc)

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)

Inject your [Zod](https://github.com/colinhacks/zod) schemas into your docs.

- [About](#about)

- [Installation](#installation)

- [Docs](#docs)

- [Examples](#examples)

  - [Usage as a CLI](#usage-as-a-cli)

    - [Car table](#car-table)

  - [Usage as a library](#usage-as-a-library)

    - [Car tire table](#car-tire-table)

- [Troubleshooting](#troubleshooting)

- [Dependencies](#dependencies)

- [License](#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

```sh

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

```

## Docs

[Docs generated by TypeDoc](https://jackdbd.github.io/zod-to-doc/index.html)

> 📖 **API Docs**

>

> This project uses [API Extractor](https://api-extractor.com/) and [api-documenter markdown](https://api-extractor.com/pages/commands/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](https://api-extractor.com/pages/setup/generating_docs/) if you want to know more*.

## Examples

Here are some tables generated using a couple of Zod schemas exported by [fixtures/schemas.mjs](https://github.com/jackdbd/zod-to-doc/blob/main/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):

```sh

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](https://github.com/jackdbd/zod-to-doc/blob/main/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](https://github.com/debug-js/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:

```sh

# print all logging statements

export DEBUG=ztd:*

```

## Dependencies

| Package | Version |

|---|---|

| [ansi-colors](https://www.npmjs.com/package/ansi-colors) | `^4.1.3` |

| [debug](https://www.npmjs.com/package/debug) | `^4.3.4` |

| [yargs](https://www.npmjs.com/package/yargs) | `^17.7.2` |

| [zod](https://www.npmjs.com/package/zod) | `^3.23.4` |

## License

© 2024 [Giacomo Debidda](https://www.giacomodebidda.com/) // [MIT License](https://spdx.org/licenses/MIT.html)