{"_id":"@akashacms/diagram-maker","name":"@akashacms/diagram-maker","dist-tags":{"latest":"0.9.0"},"versions":{"0.9.0":{"name":"@akashacms/diagram-maker","version":"0.9.0","description":"Process PlantUML diagrams into SVG, PNG, as well as AkashaCMS integration","bin":{"diagram-maker":"dist/cli.js"},"main":"dist/index.js","types":"dist/index.js","type":"module","scripts":{"build":"npx tsc","watch":"npx tsc -w","dopublish":"npm publish --access public"},"repository":{"type":"git","url":"git+https://github.com/akashacms/plugins-diagrams.git"},"keywords":["PlantUML","Markdown","Static Content Management System","AkashaCMS"],"author":{"name":"David Herron","email":"david@davidherron.com"},"license":"ISC","bugs":{"url":"https://github.com/akashacms/plugins-diagrams/issues"},"homepage":"https://github.com/akashacms/plugins-diagrams#readme","dependencies":{"commander":"^13.0.0","html-entities":"^2.5.2"},"devDependencies":{"@types/node":"^22.10.7","typescript":"^5.7.3"},"peerDependencies":{"akasharender":"^0.9.1"},"_id":"@akashacms/diagram-maker@0.9.0","gitHead":"092eb1b8d9f295d313cf982b75d061bba5b335c6","_nodeVersion":"23.6.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-9fUaURYoIgl2+knx9UI+UBQxkvbvvZ30WZ3erSeepqCeBdLtl2iPS4/EuZM1+/LwkpfcAc9saHZuR4Adp9MBqA==","shasum":"7faba305f07e20bbe87cbe628b35b55d238465a7","tarball":"https://registry.npmjs.org/@akashacms/diagram-maker/-/diagram-maker-0.9.0.tgz","fileCount":11,"unpackedSize":11891678,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBo65uuwO0pYYwI+wBL3wHR+avztQ0suCica8ZQvGiRUAiBHt7+BL5aHgvxrTlDom2c6n1tvblgOuEDl/awox33i3Q=="}]},"_npmUser":{"name":"reikiman","email":"david@davidherron.com"},"directories":{},"maintainers":[{"name":"reikiman","email":"david@davidherron.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/diagram-maker_0.9.0_1737641136194_0.9394352144048641"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-23T14:05:36.055Z","0.9.0":"2025-01-23T14:05:36.657Z","modified":"2025-01-23T14:05:37.010Z"},"maintainers":[{"name":"reikiman","email":"david@davidherron.com"}],"description":"Process PlantUML diagrams into SVG, PNG, as well as AkashaCMS integration","homepage":"https://github.com/akashacms/plugins-diagrams#readme","keywords":["PlantUML","Markdown","Static Content Management System","AkashaCMS"],"repository":{"type":"git","url":"git+https://github.com/akashacms/plugins-diagrams.git"},"author":{"name":"David Herron","email":"david@davidherron.com"},"bugs":{"url":"https://github.com/akashacms/plugins-diagrams/issues"},"license":"ISC","readme":"# @akashacms/diagram-maker\n\nProcess PlantUML diagrams and either convert into an output file, or embed as HTML in a document.\n\nDiagrams are rendered locally using a copy of `plantuml.jar`, specifically the version released under the MIT license.  By using the JAR file, you are not reliant on an external server.\n\n**NOTE**: This package requires the Java runtime to be installed on your machine and in your path.  You can test this by running `java --help` at the command line.\n\n**NOTE**: It was intended that this package also support Mermaid and KaTeX.  Those who are interested (or not) should see [the issue queue entry](https://github.com/akashacms/plugins-diagrams/issues/7) for this task.\n\n## INSTALL\n\nIn an AkashaCMS project directory:\n\n```shell\n$ npm install @akashacms/diagram-makers --save\n```\n\n## Configuration\n\nIn the AkashaCMS configuration file add this:\n\n```js\n// CJS modules - would require import() - untested\n// In Node.js 24, require(ESM MODULE) is supposed to work\n// Something like this:\nconst DiagramsPlugin = await import('@akashacms/plugins-diagrams');\n// ESM modules\nimport { DiagramsPlugin } from '@akashacms/plugins-diagrams';\n\n/// In the section where plugins are being added:\n\nconfig.use(DiagramsPlugin);\n```\n\n## Usage - CLI -- PlantUML\n\nThe package includes a CLI tool with the following synopsis:\n\n```shell\nUsage: npx document-maker plantuml [options]\n\nRender PlantUML files\n\nOptions:\n  --input-file <inputFN...>  Path for document to render\n  --output-file <outputFN>   Path for rendered document\n  --charset <charset>        To use a specific character set. Default: UTF-8\n  --darkmode                 To use dark mode for diagrams\n  --debugsvek                To generate intermediate svek files\n  --filename <fileNm>        \"example.puml\" To override %filename% variable\n  --nbthread <nThreads>      To use (N) threads for processing.\n                             Use \"auto\" for 4 threads.\n  --nometadata               To NOT export metadata in PNG/SVG generated files\n  --output-dir <outDir>      To generate images in the specified directory\n  --teps                     To generate images using EPS format\n  --thtml                    To generate HTML file for class diagram\n  --tlatex                   To generate images using LaTeX/Tikz format\n  --tpdf                     To generate images using PDF format\n  --tpng                     To generate images using PNG format (default)\n  --tscxml                   To generate SCXML file for state diagram\n  --tsvg                     To generate images using SVG format\n  --ttxt                     To generate images with ASCII art\n  --tutxt                    To generate images with ASCII art\n                             using Unicode characters\n  --tvdx                     To generate images using VDX format\n  --txmi                     To generate XMI file for class diagram\n  --verbose                  To have log information\n  -h, --help                 display help for command\n```\n\nMost of these options correspond directly to the CLI arguments for `plantuml.jar` as listed on the PlantUML website.\n\nOne mode is a single input file, and a single output file:\n\n```shell\n$ npx diagram-maker plantuml \\\n      --input-file flight.puml \\\n      --output-file flight.png  \\\n      --tpng\n```\n\nThis converts the PlantUML diagram in the named file into a PNG.\n\nThe `--input-file` parameter can be used multiple times.  In that case, the parameters are treated as the `[file/dir] [file/dir] [file/dir]` parameters for `plantuml.jar`.  The `--output-file` parameter, if given, is ignored in this case.  You may use the `--output-dir` parameter to affect where the files land.\n\n```shell\n$ npx diagram-maker plantuml \\\n    --input-file file1.puml --input-file dir/with/diagrams \\\n    --output-dir out\n    --tpng\n```\n\nThis will search for PlantUML documents in the named files or directories, generating PNG files, with the files landing in a directory hierarchy under the `out` directory.\n\n<!-- ## USAGE - CLI - Mermaid -->\n<!-- ## USAGE - CLI - KaTeX -->\n\n## API - PlantUML\n\nThe `diagram-maker` package exports an API providing similar functionality.\n\n```js\nimport { doPlantUMLOptions, doPlantUMLLocal } from 'diagram-maker';\n\nawait doPlantUMLLocal({\n  inputBody: `\n    @startuml\n    ... diagram\n    @enduml\n    `,\n  outputFN: '/path/to/destination/diagram.png',\n  tpng: true\n} as doPlantUMLOptions);\n```\n\nThis converts an inline diagram into a PNG file at the named filesystem location.  The structure of the _options_ parameter is described by `doPlantUMLOptions`.\n\nThe `inputFNs` is an array treated similarly to the `--input-file` parameter for the CLI.\n\nThere are three modes for treating inputs and outputs:\n\n* No `inputFNs`, in which case `inputBody` is output to the `outputFN` which is required.\n* One entry in the `inputFNs` which is output to the `outputFN` which is required.\n* Multiple entries in the `inputFNs`, and the output location is influenced by `outputDir`.\n\n## Usage - AkashaCMS project\n\nThe `diagram-makers` package includes an AkashaCMS plugin.\n\nSetup, configuration:\n\n```js\nimport { DiagramsPlugin } from 'diagram-makers';\n\nconfig.use(DiagramsPlugin);\n```\n\n### PlantUML diagrams in AkashaCMS projects\n\nIn a document the `<diagrams-plantuml>` is used for rendering a single PlantUML diagram into either PNG or SVG.\n\nThe PlantUML document can be used inline\n\n```html\n<diagrams-plantuml output-file=\"./flight.png\" tpng>\n@startuml\nstart\n\nif (Graphviz installed?) then (yes)\n  :process all \n  diagrams;\nelse (no)\n  :process only \n  __sequence__ and __activity__ diagrams;\nendif\n\nstop\n@enduml\n</diagrams-plantuml>\n```\n\nThe diagram is rendered into the AkashaCMS `renderDestination` directory hierarchy to a location relative to the document being rendered.\n\nEither the `tpng` or `tsvg` property (not attribute) is used to indicate the output format.\n\nThe diagram can also be in the filesystem:\n\n\n```html\n<diagrams-plantuml\n    input-file=\"./img/flight.puml\"\n    output-file=\"./img/flight.png\"\n    tpng/>\n<diagrams-plantuml\n    input-file=\"/path/to/diagrams/flight.puml\"\n    output-file=\"./img/flight.png\"\n    tpng/>\n```\n\nThe `input-file` path must be a virtual path within either an `assets` or `documents` directory.\n\nIf the `input-file` is an absolute pathname, it is relative to the root of the virtual filespace of the AkashaCMS project configuration.  A relative pathname is relative to the file being rendered.\n\n## Hat Tip\n\nThis package was inspired by https://www.npmjs.com/package/plantuml\n","readmeFilename":"README.md"}