Thanks for the library

[davesagraf]

Hey @matejchalk!

First of all, thanks for this library!
I liked both the idea, the structure, the code and the documentation in the README.
However, after trying to make it work with my Zod schemas for quite some time, I finally had to try something else, which somehow led me to making a much simpler (utility, rather than a proper library) version of such a tool.

Nevertheless, since my tool is very similar to yours in what it's trying to make and, more importantly, your tool has inspired me to even try to make something like that, I referenced your project and yourself in my version zod2markdown repo.

Would really appreciate any feedback (there's a long way ahead and a lot of improvements due, if I wish to make something useful out of it).

Well, anyways.

Thanks again!

[matejchalk]

Hi, glad you like the library 🙂 Sorry to hear you couldn't make it work for you. I'm curious what problems you ran in to specifically, as this feedback could be very useful 🤔

I've looked at your code, and I see that you made some simplifications.

• The main difference I see is that you're running it for a single Zod schema, which enables you to reduce complexity in the implementation. When building zod2md, I had a more complex use case in mind where many inter-linked schemas are exported, so the resulting Markdown document is a complete API reference with internal links (hence the "model or ref" distinction in the source code). We use it this way on another tool I work on (example output here). But I've heard from a few users now (e.g. in Programatically run this without using an entry file #13) who don't need this advanced usage, and I admit the library isn't as easy to use as it could be for these simpler use cases like converting a single Zod schema to a Markdown string. This is something I'd like to improve.
• Another difference is that your CLI is using a dynamic import() to load the schema, which restricts input files to JavaScript. It's common to use Zod with TypeScript, so I think many users would miss support for .ts files. I'm currently using bundle-require library for this purpose (jiti could also be a viable alternative).
• Regarding code structure, I like that you've split individual Zod types into their own files. It's more modular and easier to extend this way 👍 This is something I've been planning to improve in my own code, actually.
• The main criticism I have of zod2markdown is that it doesn't have any automated tests yet 😕

Regarding the future of zod2md, I'm hoping to find some time soon to do a large refactor that would modularize the code better and make the library more flexible for different use cases (incl. simpler for simple use cases).

[davesagraf]

Hi @matejchalk! Wow, thank you for your feedback!

I appreciate a lot that you dedicated time, went through and reviewed my overall project, the code and the structure, and also made some useful comparisons.

I definitely agree with your points about the differences of using single schema vs. multiple schemas, and also the possibility to use CLI with TypeScript.

But you're also absolutely right, though, I actually deliberately made a much simpler version because I just needed to export the many schemas used at my workplace to a Markdown documentation for other teams reference, while the code (the origin of schemas) could remain the source of truth.

I also would like to find and dedicate some time to make those improvements in the future, although I don't see when that moment might be yet.

That's why I mentioned somewhere, that my implementation is rather a limited use case utility, than a fully functional library, but that's actually one of the first (if not the first) of my attempts in the FOSS world 🙂

So yeah, hopefully I'll get there some day 😅

Considering your question about the issues I faced, here are some of the difficulties I ran into.

1. Entry point (finding the required schema).

Maybe, that was due to the fact that I have a rather complex structure in the project where I was trying to use zod2md, and/or, maybe, because those Zod schemas were defined in the core part of the repo, which is then shared across 2 backends via symlinks, but anyway, after running this:

npx zod2md --entry src/backend/core/config/baseConfigSchema.ts --title "Config envs reference" --output ../Desktop/config_envs_doc.md

The first error I ran into was this:

npx zod2md --entry src/backend/core/config/baseConfigSchema.ts --title "Config envs reference" --output ../Desktop/config_envs_doc.md
Failed to load entry point Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'zod' imported from /Users/dave/my_monorepo/src/backend/core/config/baseConfigSchema.bundled_vt9hs2rtsdc.mjs

2. Empty resulting Markdown file.

After realising the possible causes for the first issue, I created a separate NodeJS project, where I defined (copied from my original my_monorepo project) all the Zod schemas I initially wanted to export to Markdown format in the src/schemas directory, then added zod2md as one of the dependencies of the project.

Then, for example, considering I have this UserSchema in src/schemas/user/userSchema.ts :

import { z } from "zod";
import { userExtraSchema } from "./userExtraSchema";

export const userSchema = z.object({
    fullName: z.string().describe('Name of the User'),
    email: z.string().email().describe('Email of the User'),
    login: z.string().min(3).max(30).describe('Login/username of the User'),
    password: z.string().min(8).max(50).describe('Password of the User')
})

.merge(userExtraSchema)

.partial() // make all fields partial

export type UserSchema = z.infer<typeof userSchema>;

And the related UserExtraSchema in src/schemas/user/userExtraSchema.ts :

import { z } from "zod";

export const userExtraSchema = z.object({
    age: z.number().describe('Age of the user').optional(),
    address: z.string().describe('Address of the User').optional()
})

export type UserExtraSchema = z.infer<typeof userExtraSchema>;

After running this from the root of the project:

npx zod2md --entry src/schemas/user/userSchema.ts --title "User reference" --output ../Desktop/user_doc.md

I got this as the output:

# User reference

I tried this both with "zod": "^3.24.4" and "zod": "^3.22.4" (as I saw that you have "zod": "^3.22.4" in the package.json of zod2md)

Also, I thought that the reason for this might be my main userSchema adding another schema or schemas with the merge() method and/or making fields optional with the partial() method.

But I got the same results even with the userSchema like this:

import { z } from "zod";

export const userSchema = z.object({
    fullName: z.string().describe('Name of the User'),
    email: z.string().email().describe('Email of the User'),
    login: z.string().min(3).max(30).describe('Login/username of the User'),
    password: z.string().min(8).max(50).describe('Password of the User')
})

export type UserSchema = z.infer<typeof userSchema>;

I even thought that maybe the definition and exporting of the custom inferred type could be the reason, so I tried the most simple version:

import { z } from "zod";

export const userSchema = z.object({
    fullName: z.string().describe('Name of the User'),
    email: z.string().email().describe('Email of the User'),
    login: z.string().min(3).max(30).describe('Login/username of the User'),
    password: z.string().min(8).max(50).describe('Password of the User')
})

But I still got the empty Markdown file with only the title.

Even though, for all these 3 versions, each time I got this output in the terminal:

npx zod2md --entry src/schemas/user/userSchema.ts --title "User reference" --output ../Desktop/user_doc.md
🚀 Generated Markdown docs in ../Desktop/user_doc.md

Anyway, thanks a lot again both for your library and for your feedback! 🙂