prisma-markdown turns a Prisma schema into a documented ERD

A generator, not a viewer

prisma-markdown is described as a Prisma markdown documents generator, and it plugs into Prisma through the generator mechanism rather than as a standalone tool. The README lists what it produces in three lines: Mermaid ERD diagrams, descriptions by triple-slash comments, and separations by @namespace comments. That framing matters because it explains what the tool is not. It does not read your database, it does not migrate anything, and it does not render a browsable site. It reads schema.prisma, and writes a Markdown file that you commit, read in a pull request, and render in any Markdown viewer that supports Mermaid. The repository shows the pattern concretely, with schema.prisma and the generated ERD.md sitting side by side at the top level, so you can read the input and the output side by side and see exactly what the transformation does. The project is MIT licensed, the primary language is TypeScript, the default branch is master, and the last push was on 2026-06-09. Releases are v4.0.0 from 2025-11-24, v3.0.1 from 2025-05-17 and v3.0.0 from 2025-05-16, with no GitHub releases beyond those tags.

Setup is three steps and one generator block

Installation is the standard Prisma generator flow. First you install the package as a development dependency.

npm i -D prisma-markdown

Then you add the generator to your schema file, where the provider names the package and the output is the Markdown file you want.

generator markdown {
  provider = "prisma-markdown"
  output   = "./ERD.md"
  title    = "Shopping Mall"
}

Finally you run the generator and the file appears.

npx prisma generate

The title option is worth noticing because it becomes the heading of the generated document, so it is the difference between a file called Shopping Mall and one called Database. The package.json shows the shape of the integration. There is a bin entry mapping prisma-markdown to lib/executable/markdown.js, so the generator can also be invoked directly, and the runtime dependency is @prisma/generator-helper at 7.0.0 or later, with prisma and @prisma/client as peer dependencies at 7.0.0 or later. The version floor is therefore Prisma 7, which is the constraint to check before you add it to an older project.

The comment tags, and what each one controls

The reason this package exists is stated in the README's comment tags section. If your database has over hundreds of models, none of the automatic ERD generators can express them perfectly, and prisma-markdown recommends separating hundreds of models into multiple paginated diagrams. Five tags drive that, and they are applied as triple-slash comments above a model. The @namespace tag puts a model in both the ERD and the markdown content section, and you can assign multiple namespaces to one model; a model with no namespace goes into a section called default. The @erd tag shows the model only at the ERD, and the @describe tag shows it only in the markdown content section, which is the pair that lets you keep a model in the diagram while writing about it elsewhere, or the reverse. The @hidden tag removes the model from both. And @minItems 1 marks a relationship as mandatory, which is the subject of the next section. The sample schema in the README demonstrates all of them together.

Mandatory versus optional relationships

The @minItems 1 tag controls the cardinality notation on the N side of a one-to-many relationship. When you define a 1 to N relationship you can specify whether the N position is mandatory or optional, and to make it mandatory you write the @minItems 1 comment tag. Otherwise the N position is optional and you do nothing. The README contrasts the two forms of the notation, with the tag producing a mandatory relationship marker and no tag producing the optional one, and the sample schema shows a model where one relation carries the tag and a sibling relation does not, with a comment marking the second as optional. The example models are minimal, with empty bodies, because the point is the relation fields and the tag rather than the model contents. This is a small feature but a genuinely useful one, since a plain Prisma relation has no way to express a non-optional list end and a diagram that silently claims every relation is optional misleads exactly the readers the document is for.

Where the generated document lives in your repository

The repository layout shows how this is meant to fit a project. There is a src directory with the generator implementation, a test directory, a prisma.config.ts file, a schema.prisma with the example schema, the generated ERD.md, a vitest.config.mjs, a prettier.config.js and a .pre-commit-config.yaml. The package.json scripts cover the development loop: build compiles with rimraf and tsc, dev does the same in watch mode, test runs ts-node against test/index.ts, and vitest:cov runs the coverage suite. The pre-commit configuration matters more than it looks, because a generator that rewrites a committed file will fail a hook check if someone edits ERD.md by hand or changes the schema without regenerating, and the hook is what keeps the document honest. The package also publishes lib, src and README.md, and the main entry is lib/index.js with typings at lib/index.d.ts, so the generator can also be used as a library rather than only through the Prisma CLI.

Where prisma-markdown is the wrong choice

Three limits. The first is that it is a documentation generator and nothing more, so if your problem is visualising a database interactively, browsing the data, or generating client code, you want a different tool and this one adds nothing. The second is the Prisma 7 floor, which is enforced through the peer dependencies on prisma and @prisma/client at 7.0.0 or later, so a project on an older Prisma cannot adopt it without a major upgrade first, and the generator-helper dependency follows the same line. The third is the human cost of the comment tags. The output quality depends on you writing good triple-slash descriptions and maintaining namespace assignments by hand as the schema grows, and nothing checks that a model has a description or that two namespaces still make sense. The natural alternative is to write the documentation by hand, which is what many small schemas do, and the cost of that is that the diagram drifts from the schema the first time somebody adds a relation and forgets the picture. The other comparison is with other automatic ERD generators, and the README's argument against them is specific: none of them can express hundreds of models well, because a single diagram of that size is unreadable. That is a layout problem, and the @namespace mechanism is the answer to it. So the decision is whether your schema has outgrown a single readable diagram, and if it has not, this tool is more ceremony than the problem deserves.

Editorial conclusion

Adopt prisma-markdown if you keep your Prisma schema in version control and want reviewable documentation of your model relationships generated from the same source of truth. Skip it if a handful of models is all you have, since the generated file adds little there. Before you commit, decide your namespace layout and remember that this is a documentation generator, not a schema migrator, so it never touches your database.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. samchon/prisma-markdown on GitHub