vitepress-plugin-diagrams 1.2.2 → 1.3.0

package/README.md

@@ -24,6 +24,7 @@ The diagrams are meant to be generated at __DEV time__ because:
 - Clean, semantic HTML output
 - Use can use any editor to create diagrams (for example `VS Code` with `Mermaid` extension)
 - **Import diagrams from external files** using `@file:` syntax
+- **Optional build-time generation** for CI/CD pipelines (diagrams generated during `vitepress build`)
 
 ## Demo
 
@@ -203,6 +204,58 @@ You can customize the `CSS` classes to match your theme.
   - For `positionId`, previous files with the same `diagramType` and `positionId` are removed.
   - Without identifiers, older `[diagramType]-[otherHash].svg` files are removed when content changes.
 
+## Build-Time Generation (Optional)
+
+By default, diagrams are generated at **dev time** (fire-and-forget fetch with a placeholder SVG). For CI/CD pipelines or when you need diagrams to be reliably generated during `vitepress build`, you can use the **build-time generation** mode.
+
+In this mode:
+- Diagram HTTP calls are **deferred** and executed during the Vite build (`generateBundle` hook) or dev server request.
+- The build **fails** if a diagram cannot be generated (e.g., Kroki is unreachable), ensuring broken diagrams are caught early.
+- Already-generated SVGs on disk are reused (not re-fetched).
+
+### Setup
+
+Use `createBuildTimeDiagramsPlugin` instead of `configureDiagramsPlugin`:
+
+```ts
+import { defineConfig } from "vitepress";
+import { createBuildTimeDiagramsPlugin } from "vitepress-plugin-diagrams";
+
+const { configureMarkdown, vitePlugin } = createBuildTimeDiagramsPlugin({
+  diagramsDir: "docs/public/diagrams",
+  publicPath: "/diagrams",
+  // Optional: emit SVGs as build assets at this path
+  diagramsDistDir: "diagrams",
+});
+
+export default defineConfig({
+  markdown: {
+    config: (md) => configureMarkdown(md),
+  },
+  vite: {
+    plugins: [vitePlugin()],
+  },
+});
+```
+
+All standard options (`krokiServerUrl`, `excludedDiagramTypes`, `enableFileImports`, etc.) are supported.
+
+| Additional Option | Type | Default | Description |
+|-------------------|------|---------|-------------|
+| `diagramsDistDir` | `string` | `undefined` | If set, SVG files are emitted as Vite build assets at this path |
+
+### Using with a self-hosted Kroki instance
+
+For reliable CI builds, you can run [Kroki via Docker](https://docs.kroki.io/kroki/setup/use-docker-or-podman/) and point the plugin to it:
+
+```ts
+const { configureMarkdown, vitePlugin } = createBuildTimeDiagramsPlugin({
+  krokiServerUrl: "http://localhost:8000",
+  diagramsDir: "docs/public/diagrams",
+  publicPath: "/diagrams",
+});
+```
+
 ## Note
 
 When updating a diagram, you may see a placeholder image on the browser page. This is normal, because the svg file is loaded asynchronously and may not be displayed immediately. Just refresh the page.

package/package.json

@@ -1,65 +1,66 @@
-{
-  "name": "vitepress-plugin-diagrams",
-  "version": "1.2.2",
-  "description": "VitePress plugin for generating diagrams from text (PlantUML, Mermaid, etc.)",
-  "author": "Ruslan Makarov <ruslan.makarov@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/altrusl/vitepress-plugin-diagrams.git"
-  },
-  "bugs": {
-    "url": "https://github.com/altrusl/vitepress-plugin-diagrams/issues"
-  },
-  "homepage": "https://github.com/altrusl/vitepress-plugin-diagrams",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "keywords": [
-    "vite",
-    "vitepress-plugin",
-    "diagrams",
-    "plantuml",
-    "mermaid"
-  ],
-  "files": [
-    "bin",
-    "dist"
-  ],
-  "bin": "bin/cli.js",
-  "dependencies": {
-    "markdown-it": "^14.1.0",
-    "commander": "^14.0.0"
-  },
-  "devDependencies": {
-    "@sxzz/eslint-config": "^4.6.0",
-    "@types/node": "^22.13.1",
-    "esbuild": "^0.25.5",
-    "eslint": "^9.20.0",
-    "typescript": "^5.7.3",
-    "undici-types": "^7.10.0",
-    "vite": "^6.1.0",
-    "vitepress": "^1.6.3",
-    "vitest": "^3.0.0"
-  },
-  "peerDependencies": {
-    "vite": ">= 4.0.0",
-    "vitepress": ">= 1.0.0"
-  },
-  "scripts": {
-    "build": "vite build && pnpm run build:types",
-    "build:types": "tsc -p tsconfig.types.json",
-    "build:cli": "tsc",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "demo:dev": "pnpm --filter vitepress-diagrams-demo dev",
-    "demo:build": "pnpm --filter vitepress-diagrams-demo build"
-  }
-}
+{
+  "name": "vitepress-plugin-diagrams",
+  "version": "1.3.0",
+  "description": "VitePress plugin for generating diagrams from text (PlantUML, Mermaid, etc.)",
+  "author": "Ruslan Makarov <ruslan.makarov@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/altrusl/vitepress-plugin-diagrams.git"
+  },
+  "bugs": {
+    "url": "https://github.com/altrusl/vitepress-plugin-diagrams/issues"
+  },
+  "homepage": "https://github.com/altrusl/vitepress-plugin-diagrams",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "keywords": [
+    "vite",
+    "vitepress-plugin",
+    "diagrams",
+    "plantuml",
+    "mermaid"
+  ],
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "bin": "bin/cli.js",
+  "scripts": {
+    "build": "vite build && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build:cli": "tsc",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "demo:dev": "pnpm --filter vitepress-diagrams-demo dev",
+    "demo:build": "pnpm --filter vitepress-diagrams-demo build",
+    "publish": "pnpm publish --access public"
+  },
+  "dependencies": {
+    "markdown-it": "^14.1.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@sxzz/eslint-config": "^4.6.0",
+    "@types/node": "^22.13.1",
+    "esbuild": "^0.25.5",
+    "eslint": "^9.20.0",
+    "typescript": "^5.7.3",
+    "undici-types": "^7.10.0",
+    "vite": "^6.1.0",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "vite": ">= 4.0.0",
+    "vitepress": ">= 1.0.0"
+  }
+}