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

$3

``mermaid
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.

$3

`mermaid
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

`bash
npm i -D zenstack-markdown
`

add the plugin in your ZModel schema file

`ts
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
> - PERPLEXITY_API_KEY
> - XAI_API_KEY
> - GOOGLE_GENERATIVE_AI_API_KEY

then
run zenstack generate

`bash
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:

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

You can also disable it using env variable

`bash
DISABLE_ZENSTACK_MD=true
`

Local Development

$3

`bash
npm install
`

$3

`bash
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

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

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

$3

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:

`bash
npm install -g @mermaid-js/mermaid-cli
`

Transform the markdown file with mermaid diagrams

`bash
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.