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
- Setting OPENAI_API_KEY of OpenAI in .env
- Or setting XAI_API_KEY by obtaining a free Grok API Key from https://x.ai

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.