ZenStack Markdown Plugin

ZenStack Markdown Plugin is a standard plugin of ZenStack to generate markdown from the ZModel schema with Mermaid ERD diagram.

Do you know the Mermaid's official SaaS product, MermaidChart, is powered by ZenStack？😉

Example

Post
User

Post

erDiagram
"Post" {
  String id PK
  DateTime createdAt
  DateTime updatedAt
  String title
  Boolean published
  String authorId FK
}
"Post" }o--|| "User": author

The author of the post can perform all operations on their posts.
Any authenticated user can read published posts.

User

erDiagram
"User" {
  String id PK
  String name  "?"
  String email
  DateTime emailVerified  "?"
  String password
  String image  "?"
}
"User" ||--o{ "Post": posts

Anyone can create and read user profiles.
Only the user themselves can update or delete their own profile.

Setup

npm i -D zenstack-markdown

add the plugin in your ZModel schema file

plugin zenstackmd {
    provider = 'zenstack-markdown'
}

You could generate more meaningful doc using AI
Simply set one of the below API key of AI provider in the .env:

OPENAI_API_KEY

ANTHROPIC_API_KEY

XAI_API_KEY

then run zenstack generate

npx zenstack generate

you will see the schema.md generated in the same folder of your ZModel schema file.

Options

Name	Type	Description	Required	Default
output	String	Output file path (relative to the path of ZModel)	No	schema.md
disabled	Boolean	Whether to run this plugin	No	false

example:

plugin zenstackmd {
    provider = 'zenstack-markdown'
    output = 'docs/schema.md'
    disabled = true
}

You can also disable it using env variable

DISABLE_ZENSTACK_MD=true

Local Development

Install

npm install

Build

npm run build

After build, the plugin will be generated in dist folder. Then you can use it in your existing ZModel schema by setting the provider this dist folder

plugin zenstackmd {
    provider = '.../zenstack-markdown/dist'
}

provider could either by the absolute path or relative path to the running zenstack module.

Run Sample

simply run npm run dev to see a more complicated result schema.md generated from schema.zmodel

Show Mermaid Diagrams in Markdown

GitHub

Supported by default
VSCode

Install this extension Markdown Preview Mermaid Support
Other Unsupported Places

Install the mermaid-cli:
```
npm install -g @mermaid-js/mermaid-cli
```
Transform the markdown file with mermaid diagrams
```
mmdc -i schema.md -o schema-svg.md
```
The mermaid-cli will find the mermaid diagrams, create SVG files from them and refer to those in the markdown output.