Merge pull request #1 from sheldonj/feature/improve-skill-generation

feat: improve SVG diagram embedding and add release automation

Author: sheldonj

.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

CONTRIBUTING.md

@@ -310,23 +310,15 @@ pnpm test -- --update
 
 ### Prerequisites
 
-From the repository root:
-
 ```bash
 pnpm install
 pnpm build
 ```
 
-The plugin package is at `packages/plugins/documentation/`.
-
 ### Build
 
 ```bash
-# Build this package only (run from packages/plugins/documentation/)
 pnpm build
-
-# Build from repo root (builds all packages via Turbo)
-cd /path/to/zenstack && pnpm build
 ```
 
 The build uses `tsup-node` for bundling and `tsc --noEmit` for type checking.
@@ -346,22 +338,80 @@ This plugin was built with strict TDD. When adding features:
 pnpm lint
 ```
 
-Uses the shared `@zenstackhq/eslint-config`.
+Uses `eslint-config-canonical` with project-specific overrides defined in `eslint.config.js`.
 
 ### Preview output
 
-To visually inspect what the plugin generates, point the output at a local directory:
+To visually inspect what the plugin generates:
 
 ```bash
-# In any project with a schema.zmodel:
-plugin documentation {
-    provider = '../path/to/packages/plugins/documentation'
-    output   = './preview-output'
-}
-pnpm exec zenstack generate
+pnpm run build
+npx ts-node scripts/preview.ts
+```
+
+Then browse the generated Markdown files in `preview-output/` or render them with your preferred viewer.
+
+## Commit conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) and [Release Please](https://github.com/googleapis/release-please) for automated versioning and changelog generation.
+
+### Commit message format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
 ```
 
-Then browse the generated Markdown files or render them with your preferred viewer.
+### Types
+
+| Type | Purpose | Version bump |
+|---|---|---|
+| `feat` | New feature or capability | minor (0.x → 0.x+1) |
+| `fix` | Bug fix | patch (0.x.y → 0.x.y+1) |
+| `perf` | Performance improvement | patch |
+| `docs` | Documentation only | none |
+| `test` | Adding or updating tests | none |
+| `refactor` | Code change that neither fixes a bug nor adds a feature | none |
+| `chore` | Maintenance tasks (deps, CI config) | none |
+| `ci` | CI/CD workflow changes | none |
+
+### Breaking changes
+
+Append `!` after the type to indicate a breaking change:
+
+```
+feat!: rename diagramFormat option to svgMode
+```
+
+Or include a `BREAKING CHANGE:` footer:
+
+```
+feat: overhaul diagram rendering pipeline
+
+BREAKING CHANGE: diagramFormat option renamed to svgMode
+```
+
+Breaking changes bump the major version (or minor while pre-1.0).
+
+### Examples
+
+```
+feat: add diagramEmbed option for inline SVG embedding
+fix: use descriptive alt text in SVG image references
+docs: document responsive wrapper behavior
+refactor: extract wrapResponsive helper from processDiagrams
+test: add inline SVG embedding tests
+chore: update dev dependencies
+```
+
+### How it works
+
+1. You merge PRs to `main` using conventional commit messages
+2. Release Please reads the commit history and opens a "Release PR" with a version bump and auto-generated `CHANGELOG.md`
+3. Merging the Release PR creates a GitHub Release, which triggers the npm publish workflow
 
 ## Frequently touched files
 

README.md

@@ -142,6 +142,7 @@ plugin documentation {
     generateErd            = true
     erdTheme               = 'github-light'
     diagramFormat          = 'svg'
+    diagramEmbed           = 'inline'
 }
 ```
 
@@ -160,6 +161,7 @@ plugin documentation {
 | `erdFormat` | `"svg"`, `"mmd"`, or `"both"` | `"both"` | Which ERD output format(s) to produce |
 | `erdTheme` | `string` | default | [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) theme name for SVG rendering |
 | `diagramFormat` | `"mermaid"`, `"svg"`, or `"both"` | `"mermaid"` | How per-page Mermaid diagrams are rendered (see [Per-Page SVG Diagrams](#per-page-svg-diagrams)) |
+| `diagramEmbed` | `"file"` or `"inline"` | `"file"` | Whether SVGs are written as companion files or embedded directly in the markdown (see [Per-Page SVG Diagrams](#per-page-svg-diagrams)) |
 
 ## ERD SVG Export
 
@@ -188,7 +190,7 @@ See all 15 themes rendered against the showcase schema in the [theme gallery](./
 
 ## Per-Page SVG Diagrams
 
-By default, diagrams on model, view, enum, type, procedure, and relationship pages are rendered as inline Mermaid code blocks. Set `diagramFormat` to render them as SVG images instead:
+By default, diagrams on model, view, enum, type, procedure, relationship, and SKILL pages are rendered as inline Mermaid code blocks. Set `diagramFormat` to render them as SVG images instead:
 
 ```prisma
 plugin documentation {
@@ -199,13 +201,40 @@ plugin documentation {
 }
 ```
 
+### Diagram format
+
 | Value | Behavior |
 |---|---|
 | `"mermaid"` | Inline ` ```mermaid ` code blocks (default, requires a Mermaid-capable viewer) |
-| `"svg"` | SVG content embedded directly in the markdown — works everywhere, including Notion, plain Markdown viewers, and GitHub |
-| `"both"` | Embedded SVG with the Mermaid source in a collapsible `<details>` block |
+| `"svg"` | Companion `.svg` files referenced via `![Entity diagram](./Entity-diagram.svg)` — works everywhere |
+| `"both"` | SVG image reference with the Mermaid source in a collapsible `<details>` block |
+
+### Embed mode
+
+Control whether SVGs are written as separate files or embedded directly in the markdown:
+
+```prisma
+plugin documentation {
+    provider      = 'zenstack-docs-plugin'
+    output        = './docs/schema'
+    diagramFormat = 'svg'
+    diagramEmbed  = 'inline'
+}
+```
+
+| Value | Behavior |
+|---|---|
+| `"file"` | SVG written as companion files next to each `.md` page (default) |
+| `"inline"` | Raw `<svg>` XML embedded directly in the markdown — fully self-contained, no separate files |
+
+The `diagramEmbed` option only takes effect when `diagramFormat` is `"svg"` or `"both"`.
+
+### Additional features
+
+- **Descriptive alt text** — image references use the entity name (e.g. `![User diagram]`) for accessibility and hover tooltips
+- **Responsive wrapper** — all SVG outputs (file references and inline) are wrapped in `<div style="max-width:100%;overflow-x:auto">` so large diagrams scroll horizontally instead of overflowing the page
 
-When set to `"svg"` or `"both"`, the rendered SVG is embedded inline in each `.md` page — no separate files needed. The `erdTheme` option applies to all per-page SVGs as well as the standalone ERD.
+The `erdTheme` option applies to all per-page SVGs as well as the standalone ERD.
 
 ## Enriching Your Documentation
 

eslint.config.js

@@ -37,6 +37,19 @@ export default tseslint.config(
     },
   },
   {
-    ignores: ['dist/', 'preview-output/', 'zenstack/'],
+    files: ['package.json'],
+    rules: {
+      // types must precede default in exports conditions for TypeScript resolution
+      'jsonc/sort-keys': 'off',
+    },
+  },
+  {
+    ignores: [
+      'dist/',
+      'preview-output/',
+      'zenstack/',
+      'release-please-config.json',
+      '.release-please-manifest.json',
+    ],
   },
 );

release-please-config.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "docs", "section": "Documentation", "hidden": true },
+        { "type": "chore", "section": "Miscellaneous", "hidden": true },
+        { "type": "test", "section": "Tests", "hidden": true },
+        { "type": "ci", "section": "CI", "hidden": true },
+        { "type": "refactor", "section": "Refactoring", "hidden": true }
+      ]
+    }
+  }
+}