mikro-orm-markdown 0.1.0-alpha.4 → 0.1.0-alpha.5

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0-alpha.5] - 2026-06-29
+
+### Added
+
+- `--mermaid-layout <layout>` and `--mermaid-theme <theme>` CLI options to inject Mermaid YAML frontmatter into each `erDiagram` fence
+- `mermaid` option in the programmatic API (`generateMarkdown({ mermaid: { layout, theme } })`) with the same effect
+- `MermaidLayout`, `MermaidTheme`, and `MermaidRenderOptions` types exported from the public API
+- When neither option is set, output is identical to previous versions — no frontmatter is emitted
+
 ## [0.1.0-alpha.4] - 2026-06-29
 
 ### Fixed

package/README.ko.md

@@ -79,6 +79,8 @@ npm run erd
 | `-d, --description <string>` | —           | 제목 아래에 표시할 설명 문단 (선택)                                   |
 | `--tsconfig <path>`    | —                 | `.ts` config 로드 시 사용할 `tsconfig.json`; 기본값은 config 파일 근처의 가장 가까운 파일 |
 | `--src <paths...>`     | —                 | 원본 TypeScript 엔티티 소스 경로/glob; MikroORM이 컴파일된 JavaScript에서 엔티티를 discovery할 때만 필요 |
+| `--mermaid-layout <layout>` | —           | Mermaid 레이아웃 엔진 (`dagre\|elk\|elk.stress`). 생략하면 뷰어 기본값 사용. |
+| `--mermaid-theme <theme>`   | —           | Mermaid 테마 (`default\|neutral\|dark\|forest\|base`). 생략하면 뷰어 기본값 사용. |
 
 > 설명이 길거나 여러 줄이라면 CLI 대신 [프로그래밍 API](#프로그래밍-api)를 사용하세요 — 쉘 인용 부호 제약 없이 문자열을 그대로 전달할 수 있습니다.
 
@@ -392,6 +394,7 @@ await writeFile('./ERD.md', markdown, 'utf-8');
 | `description` | 제목 아래에 표시할 설명 문단입니다. CLI flag와 달리 쉘 quoting 제약 없이 문자열을 그대로 전달할 수 있습니다. |
 | `src` | 원본 TypeScript 엔티티 소스 경로/glob입니다. `orm.entities`가 컴파일된 JavaScript를 discovery할 때만 필요합니다. |
 | `onWarn` | 컴파일된 JavaScript에서 JSDoc을 읽지 못하는 상황 같은 non-fatal warning을 받을 callback입니다. |
+| `mermaid` | Mermaid 렌더링 옵션입니다. 아래 [Mermaid 렌더링 옵션](#mermaid-렌더링-옵션)을 참고하세요. |
 
 MikroORM config를 비동기적으로 만들어야 한다면 직접 resolve한 뒤 결과 options object를 전달하세요:
 
@@ -400,6 +403,56 @@ const ormConfig = await createOrmConfig();
 const markdown = await generateMarkdown({ orm: ormConfig });
 ```
 
+### Mermaid 렌더링 옵션
+
+기본적으로 mikro-orm-markdown은 Mermaid frontmatter config를 출력하지 않습니다. 이렇게 해야 각 Markdown 뷰어의 기본 Mermaid 렌더링 동작이 유지됩니다.
+
+CLI에서 Mermaid 렌더링 옵션을 사용하려면:
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-theme forest
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk --mermaid-theme neutral
+```
+
+프로그래밍 API에서는:
+
+```typescript
+const markdown = await generateMarkdown({
+  orm: ormConfig,
+  mermaid: {
+    layout: 'elk',
+    theme: 'forest',
+  },
+});
+```
+
+layout 또는 theme을 지정하면 각 `erDiagram` 펜스 앞에 YAML frontmatter 블록이 삽입됩니다:
+
+````markdown
+```mermaid
+---
+config:
+  layout: elk
+  theme: forest
+---
+erDiagram
+  ...
+```
+````
+
+**사용 가능한 layout 값:**
+
+| 값 | 설명 |
+| -- | ---- |
+| `dagre` | Mermaid 기본 레이아웃 엔진. |
+| `elk` | 대체 레이아웃 엔진. 엔티티가 많거나 관계선이 복잡한 ERD에서 선 라우팅을 개선할 수 있습니다. |
+| `elk.stress` | ELK stress 레이아웃 변형. Mermaid 버전과 뷰어에 따라 지원 여부가 다릅니다. |
+
+**사용 가능한 theme 값:** `default`, `neutral`, `dark`, `forest`, `base`.
+
+> `elk`와 theme 지원 여부는 뷰어마다 다릅니다. `--mermaid-layout`이나 `--mermaid-theme`을 지정하지 않으면 frontmatter는 출력되지 않습니다.
+
 ## 라이선스
 
 MIT

package/README.md

@@ -79,6 +79,8 @@ npm run erd
 | `-d, --description <string>` | —           | Optional description paragraph shown below the title                            |
 | `--tsconfig <path>`    | —                 | `tsconfig.json` used when loading a `.ts` config; defaults to the nearest one beside the config file |
 | `--src <paths...>`     | —                 | Original TypeScript entity source paths/globs; only needed when MikroORM discovers entities from compiled JavaScript |
+| `--mermaid-layout <layout>` | —            | Mermaid layout engine (`dagre\|elk\|elk.stress`). Omit to use the viewer's default. |
+| `--mermaid-theme <theme>`   | —            | Mermaid theme (`default\|neutral\|dark\|forest\|base`). Omit to use the viewer's default. |
 
 > For a long or multiline description, use the [programmatic API](#programmatic-api) instead — it accepts any string directly, without shell quoting limits.
 
@@ -392,6 +394,7 @@ Programmatic options:
 | `description` | Optional paragraph below the title. Unlike the CLI flag, this can be any string without shell quoting concerns. |
 | `src` | Original TypeScript entity source paths/globs. Only needed when `orm.entities` discovers compiled JavaScript. |
 | `onWarn` | Callback for non-fatal warnings, such as compiled JavaScript JSDoc loss. |
+| `mermaid` | Optional Mermaid rendering options. See [Mermaid rendering options](#mermaid-rendering-options) below. |
 
 If your MikroORM config is asynchronous, resolve it yourself and pass the resulting options object:
 
@@ -400,6 +403,56 @@ const ormConfig = await createOrmConfig();
 const markdown = await generateMarkdown({ orm: ormConfig });
 ```
 
+### Mermaid rendering options
+
+By default, mikro-orm-markdown does not emit Mermaid frontmatter config. This preserves each Markdown viewer's default Mermaid rendering behavior.
+
+You can opt into Mermaid rendering options via the CLI:
+
+```bash
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-theme forest
+mikro-orm-markdown --config ./mikro-orm.config.ts --mermaid-layout elk --mermaid-theme neutral
+```
+
+Or via the programmatic API:
+
+```typescript
+const markdown = await generateMarkdown({
+  orm: ormConfig,
+  mermaid: {
+    layout: 'elk',
+    theme: 'forest',
+  },
+});
+```
+
+When a layout or theme is set, a YAML frontmatter block is prepended to each `erDiagram` fence:
+
+````markdown
+```mermaid
+---
+config:
+  layout: elk
+  theme: forest
+---
+erDiagram
+  ...
+```
+````
+
+**Available layout values:**
+
+| Value | Description |
+| ----- | ----------- |
+| `dagre` | Mermaid's default layered layout. |
+| `elk` | Alternative layout engine; can improve line routing on larger or denser ERDs. |
+| `elk.stress` | ELK stress layout variant. Support varies by Mermaid version and viewer. |
+
+**Available theme values:** `default`, `neutral`, `dark`, `forest`, `base`.
+
+> Viewer support for `elk` and theme values varies. If no `--mermaid-layout` or `--mermaid-theme` is provided, no frontmatter is emitted.
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -281,6 +281,8 @@ function toMarkdownAnchor(value) {
 }
 
 // src/render/mermaid.ts
+var MERMAID_LAYOUTS = ["dagre", "elk", "elk.stress"];
+var MERMAID_THEMES = ["default", "neutral", "dark", "forest", "base"];
 var FORMULA_DUMMY_TABLE = {
   alias: "e0",
   name: "",
@@ -567,8 +569,19 @@ function normalizeType(type) {
   }
   return type;
 }
-function renderErDiagram(model) {
-  const lines = ["erDiagram"];
+function renderErDiagram(model, mermaid) {
+  const lines = [];
+  if (mermaid?.layout !== void 0 || mermaid?.theme !== void 0) {
+    lines.push("---", "config:");
+    if (mermaid.layout !== void 0) {
+      lines.push(`  layout: ${mermaid.layout}`);
+    }
+    if (mermaid.theme !== void 0) {
+      lines.push(`  theme: ${mermaid.theme}`);
+    }
+    lines.push("---");
+  }
+  lines.push("erDiagram");
   for (const entity of model.entities) {
     lines.push(`  ${toMermaidIdentifier(entity.className)} {`);
     for (const col of entity.columns) {
@@ -787,7 +800,7 @@ async function withTsMorphMetadataProvider(options, onWarn) {
 }
 
 // src/render/markdown.ts
-function renderMarkdown(docModel) {
+function renderMarkdown(docModel, mermaid) {
   const sections = [`# ${escapeMarkdownInline(docModel.title)}`];
   if (docModel.description) {
     sections.push(escapeMarkdownParagraph(docModel.description));
@@ -796,7 +809,7 @@ function renderMarkdown(docModel) {
     sections.push(renderTableOfContents(docModel.groups));
   }
   for (const group of docModel.groups) {
-    sections.push(renderGroupSection(group));
+    sections.push(renderGroupSection(group, mermaid));
   }
   return sections.join("\n\n");
 }
@@ -813,14 +826,14 @@ function renderTableOfContents(groups) {
     return `- [${label}](#${toMarkdownAnchor(group.name)})`;
   });
 }
-function renderGroupSection(group) {
+function renderGroupSection(group, mermaid) {
   const parts = [`## ${escapeMarkdownInline(group.name)}`];
   if (group.erdEntities.length > 0) {
     const diagramModel = {
       entities: group.erdEntities.map((e) => e.model),
       relations: group.erdRelations
     };
-    parts.push("```mermaid\n" + renderErDiagram(diagramModel) + "\n```");
+    parts.push("```mermaid\n" + renderErDiagram(diagramModel, mermaid) + "\n```");
   }
   for (const entity of group.textEntities) {
     parts.push(renderEntitySection(entity));
@@ -976,7 +989,7 @@ async function loadEntityMetadataWithTsMorphFallback(originalOrm, effectiveOrm)
   }
 }
 async function generateMarkdown(options) {
-  const { orm, title = "Database Schema", description, src, onWarn } = options;
+  const { orm, title = "Database Schema", description, src, onWarn, mermaid } = options;
   const effectiveOrm = await withTsMorphMetadataProvider(orm, onWarn);
   const { metas, sourcePaths } = await loadEntityMetadataWithTsMorphFallback(orm, effectiveOrm);
   const jsDocResult = loadJsDoc(resolveJsDocSources(sourcePaths, src, onWarn));
@@ -984,7 +997,7 @@ async function generateMarkdown(options) {
     assertExplicitJsDocSourceCoverage(metas, jsDocResult, src, onWarn);
   }
   const docModel = buildDocumentModel(metas, jsDocResult, title, description, onWarn);
-  return renderMarkdown(docModel);
+  return renderMarkdown(docModel, mermaid);
 }
 
 // src/cli.ts
@@ -1099,9 +1112,34 @@ async function writeMarkdownFile(outPath, markdown) {
 ${formatFileSystemError(cause)}`, { cause });
   }
 }
+function parseMermaidOptions(opts) {
+  const { mermaidLayout, mermaidTheme } = opts;
+  if (mermaidLayout !== void 0 && !MERMAID_LAYOUTS.includes(mermaidLayout)) {
+    process.stderr.write(
+      `Error: Invalid --mermaid-layout "${mermaidLayout}". Allowed values: ${MERMAID_LAYOUTS.join(", ")}
+`
+    );
+    process.exit(1);
+  }
+  if (mermaidTheme !== void 0 && !MERMAID_THEMES.includes(mermaidTheme)) {
+    process.stderr.write(
+      `Error: Invalid --mermaid-theme "${mermaidTheme}". Allowed values: ${MERMAID_THEMES.join(", ")}
+`
+    );
+    process.exit(1);
+  }
+  if (mermaidLayout === void 0 && mermaidTheme === void 0) {
+    return void 0;
+  }
+  return {
+    ...mermaidLayout !== void 0 && { layout: mermaidLayout },
+    ...mermaidTheme !== void 0 && { theme: mermaidTheme }
+  };
+}
 async function run(opts) {
   const configPath = path2.resolve(opts.config);
   const outPath = path2.resolve(opts.out);
+  const mermaid = parseMermaidOptions(opts);
   let ormOptions;
   try {
     ormOptions = await loadOrmOptions(configPath, opts.tsconfig);
@@ -1120,6 +1158,7 @@ ${err instanceof Error ? err.message : String(err)}
       title: opts.title,
       ...opts.description !== void 0 && { description: opts.description },
       ...opts.src !== void 0 && { src: opts.src },
+      ...mermaid !== void 0 && { mermaid },
       onWarn: (message) => void process.stderr.write(`Warning: ${message}
 `)
     });
@@ -1144,7 +1183,7 @@ var program = new import_commander.Command().name("mikro-orm-markdown").descript
 ).option(
   "--src <paths...>",
   "Source .ts file globs to read JSDoc from when entities run from compiled .js (comments are stripped at build time)"
-).action(run);
+).option("--mermaid-layout <layout>", `Mermaid layout engine injected as frontmatter (${MERMAID_LAYOUTS.join("|")})`).option("--mermaid-theme <theme>", `Mermaid theme injected as frontmatter (${MERMAID_THEMES.join("|")})`).action(run);
 function isDirectCliExecution() {
   const entryPoint = process.argv[1];
   if (entryPoint === void 0) {