From 5460bde4321c937ce7c3b4f27643a60dcca037a5 Mon Sep 17 00:00:00 2001 From: Michael M Slusarz Date: Mon, 10 Nov 2025 14:32:09 -0700 Subject: [PATCH] plantuml: Generate images manually so we are serving static data Unfortunately, all the VitePress PlantUML plugins either display the data by sending to a remote server (plantuml.com), or require Java and the PlantUML JAR to be installed locally. To keep installation and development of the documentation straightforward, for now require that PlantUML graphics be generated manually. This shouldn't be needed to be done often - and the process to generate is easy if Docker is available. --- .github/actions/spelling/expect.txt | 4 ++ assets/plantuml/README.md | 30 +++++++++ .../plantuml/submission_flow.puml | 0 docs/core/config/images/submission_flow.svg | 1 + docs/core/config/submission.md | 2 +- lib/markdown.js | 2 - package-lock.json | 63 ------------------- package.json | 1 - 8 files changed, 36 insertions(+), 67 deletions(-) create mode 100644 assets/plantuml/README.md rename docs/core/config/include/submission_flow.inc => assets/plantuml/submission_flow.puml (100%) create mode 100644 docs/core/config/images/submission_flow.svg diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index 0cfb20ebf..2ad17e9ee 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -605,6 +605,7 @@ pidof pids Piljk pki +plantuml popafter postconf postfixadmin @@ -631,6 +632,7 @@ proctitle proofpoint proxymap pubout +puml putscript pvo pwcheck @@ -825,6 +827,7 @@ toolarge transitioning Troost tscript +tsvg TTLs tuxfamily typedef @@ -838,6 +841,7 @@ UIDPLUS uids uidv uidvalidity +UML unaccessed unaliased unauth diff --git a/assets/plantuml/README.md b/assets/plantuml/README.md new file mode 100644 index 000000000..de954ee6b --- /dev/null +++ b/assets/plantuml/README.md @@ -0,0 +1,30 @@ +# PlantUML Data + +This directory contains PlantUML files that are used to create diagrams for +the documentation. + +## Docker + +[PlantUML](https://plantuml.com/) files are converted to SVG by using a Java +program. + +It is easiest to run the program by using a pre-configured Docker container. + +The output command is as follows: + +``` +docker run --rm -v /path/to/your/puml/files:/data \ + -v /path/to/your/output/directory:/output plantuml/plantuml \ + -tsvg /data/your_diagram.puml \ + -o /output +``` + +For example, if running from this directory to convert foo.puml, and storing +the SVG file in the "docs/core/images" directory (so it can be referenced via +Markdown from within VitePress), run: + +``` +mkdir -p ../../docs/core/images +docker run --rm -v ./:/data -v ../../docs/core/images:/output \ + plantuml/plantuml -tsvg /data/foo.puml -o /output +``` diff --git a/docs/core/config/include/submission_flow.inc b/assets/plantuml/submission_flow.puml similarity index 100% rename from docs/core/config/include/submission_flow.inc rename to assets/plantuml/submission_flow.puml diff --git a/docs/core/config/images/submission_flow.svg b/docs/core/config/images/submission_flow.svg new file mode 100644 index 000000000..5a5a04fa9 --- /dev/null +++ b/docs/core/config/images/submission_flow.svg @@ -0,0 +1 @@ +DOVECOTsubmission-login(Handles TLS & Auth)Dovecot Authsubmission(Validates SMTP; proxies mail)Mail StorageMUA (Mail Client)Backend MTA(e.g., Postfix/Exim)Remote DeliveryConnect (SMTP: Port 465/587)(Optional) Handles BURLRelays message (SMTP) \ No newline at end of file diff --git a/docs/core/config/submission.md b/docs/core/config/submission.md index f8d226557..ec6637016 100644 --- a/docs/core/config/submission.md +++ b/docs/core/config/submission.md @@ -84,7 +84,7 @@ service: ## Flow Diagram - +![Submission Flow Diagram](/docs/core/config/images/submission_flow.svg) ## Configuration diff --git a/lib/markdown.js b/lib/markdown.js index 1601c343a..ac98a2c9d 100644 --- a/lib/markdown.js +++ b/lib/markdown.js @@ -1,7 +1,6 @@ import containerPlugin from 'markdown-it-container' import fg from 'fast-glob' import deflistPlugin from 'markdown-it-deflist' -import { plantuml } from "@mdit/plugin-plantuml"; import path from 'path' import { createMarkdownRenderer } from 'vitepress' import { dovecotSetting, frontmatterIter, loadData } from './utility.js' @@ -18,7 +17,6 @@ export function dovecotMdExtend(md) { }) md.use(deflistPlugin) md.use(dovecot_markdown) - md.use(plantuml) return md } diff --git a/package-lock.json b/package-lock.json index cc0624191..dc9e419a9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,7 +6,6 @@ "": { "name": "dovecot-ce-documentation", "devDependencies": { - "@mdit/plugin-plantuml": "^0.22.3", "@sindresorhus/slugify": "^2.2.1", "camelcase": "^8.0.0", "commander": "^13.1.0", @@ -818,68 +817,6 @@ "dev": true, "license": "MIT" }, - "node_modules/@mdit/helper": { - "version": "0.22.1", - "resolved": "https://registry.npmjs.org/@mdit/helper/-/helper-0.22.1.tgz", - "integrity": "sha512-lDpajcdAk84aYCNAM/Mi3djw38DJq7ocLw5VOSMu/u2YKX3/OD37a6Qb59in8Uyp4SiAbQoSHa8px6hgHEpB5g==", - "dev": true, - "license": "MIT", - "dependencies": { - "@types/markdown-it": "^14.1.2" - }, - "engines": { - "node": ">= 18" - }, - "peerDependencies": { - "markdown-it": "^14.1.0" - }, - "peerDependenciesMeta": { - "markdown-it": { - "optional": true - } - } - }, - "node_modules/@mdit/plugin-plantuml": { - "version": "0.22.3", - "resolved": "https://registry.npmjs.org/@mdit/plugin-plantuml/-/plugin-plantuml-0.22.3.tgz", - "integrity": "sha512-vnMTNO8HsXGQq8DIux+4Y082M/IkT+ICEZhe0EIXgKfbCORa7jQiw1mCKX4L+okqntglOkM5ItvfSdyCbrqidQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "@mdit/plugin-uml": "0.22.2", - "@types/markdown-it": "^14.1.2" - }, - "peerDependencies": { - "markdown-it": "^14.1.0" - }, - "peerDependenciesMeta": { - "markdown-it": { - "optional": true - } - } - }, - "node_modules/@mdit/plugin-uml": { - "version": "0.22.2", - "resolved": "https://registry.npmjs.org/@mdit/plugin-uml/-/plugin-uml-0.22.2.tgz", - "integrity": "sha512-pe1p527i66rKThIxz6yOrBILyl1E+jZtDexuUHnNKAKEgXx+f10eCENLN7+9L59K2pbARj3PtdxDC0fs+e2DqA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@mdit/helper": "0.22.1", - "@types/markdown-it": "^14.1.2" - }, - "engines": { - "node": ">= 18" - }, - "peerDependencies": { - "markdown-it": "^14.1.0" - }, - "peerDependenciesMeta": { - "markdown-it": { - "optional": true - } - } - }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", diff --git a/package.json b/package.json index 67949f3f7..4792a0830 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,6 @@ { "name": "dovecot-ce-documentation", "devDependencies": { - "@mdit/plugin-plantuml": "^0.22.3", "@sindresorhus/slugify": "^2.2.1", "camelcase": "^8.0.0", "commander": "^13.1.0",