Generate markdown doc from ZModel schema file of ZenStack with Mermaid ERD
npm install zenstack-markdownZenStack 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?😉
``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.
`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.
`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.
| 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
`bash`
npm install
`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.
simply run npm run dev to see a more complicated result schema.md generated from schema.zmodel
- 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.