puml-for-markdown 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 2.0.0
+
+### Migration from version 1
+
+- Requires Node.js 22 or newer. Upgrade Node.js before installing version 2.
+- CLI failures now exit with a nonzero status so scripts and CI can detect errors.
+- The CLI creates `.puml-cache.json` by default. Add it to `.gitignore`, or use
+  `--no-cache` to disable caching. Refresh with `--no-cache` when remote includes
+  or the rendering server change.
+
+### Features and fixes
+
+- Add local image links, offline check and dry-run modes, persistent caching,
+  and private Polr URL shortening.
+- Support `.plantuml` files, Windows paths, nested ignore rules, and recursive
+  includes with cycle detection.
+- Preserve Markdown formatting and code examples while replacing diagram links.
+- Validate references before editing Markdown and preserve unrelated exported
+  files. Export images atomically with readable permissions.
+- Handle HTTP errors and timeouts, and serialize watch updates.
+- Update dependencies and examples, with automated checks on Linux, macOS,
+  and Windows using Node.js 22 and 24.

package/README.md

@@ -5,7 +5,7 @@ Just run `puml-for-markdown` in any directory where you have markdown files and
 in markdown comments. The best part about this is that it requires no build files, you don't even need to store 
 puml images in your repo. Also the embedded diagrams can link to other diagrams. [PlantUML](https://plantuml.com) files 
 allow you to create diagrams that are defined using a simple and intuitive language. By default the entire directory 
-is recursively searched, automatically ignoring anything in the gitignore file.
+is recursively searched, respecting root and nested `.gitignore` rules, including negation. `.git`, `node_modules`, the output directory, and symbolic links are always skipped. Both `.puml` and `.plantuml` diagram files are supported.
 
 ## Examples
 The following examples are of a project I worked on, **yellow components will link you to another diagram**. Obviously the
@@ -20,7 +20,7 @@ You can easily add an embedded diagram to your markdown. Simply add a link to th
 
 Here's the result. **Try clicking on the yellow blocks.**
 
-[![Diagram Image Link](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->
+[![Diagram Image Link](https://tinyurl.com/2d47useb)](https://tinyurl.com/2d47useb)<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->
 
 ### Link Only
 To render a link to a puml diagram, do the same thing but exclude the `!`
@@ -30,7 +30,7 @@ To render a link to a puml diagram, do the same thing but exclude the `!`
 
 which renders into
 
-[Click to Open Interactive Diagram](https://tinyurl.com/y847en68)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
+[Click to Open Interactive Diagram](https://tinyurl.com/2d47useb)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
 
 ## Goal
 The goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.
@@ -76,6 +76,13 @@ If you want to update the link text or switch it between image and link, just up
 don't need to delete the rendered image or link.
 
 ### Installation
+Requires **Node.js 22 or newer** (Node.js 24 recommended for development).
+
+Version 2 raises the minimum Node.js version to 22. Upgrade Node.js before upgrading
+from version 1. Existing dependencies pinned to `1.x` or `^1.2.1` stay on version 1;
+installing `latest` will select version 2 once it is published. See the
+[release notes](./CHANGELOG.md) for the changes.
+
 `npm i -g puml-for-markdown`
 
 ### Advanced Usage
@@ -86,35 +93,62 @@ For an example of outputted images, checkout [dist_puml/puml](./dist_puml/puml).
 - You can specify the PUML server used to render the diagrams see `--puml-server-url`
 
 ### All CLI Options
-```
+```text
 Usage: puml-for-markdown [options]
 
 An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.
 
 Options:
-  -s, --puml-server-url <url>      This is the base URL used to render diagrams. Defaults to the public plantuml server. (default: "https://www.plantuml.com/plantuml")
+  -s, --puml-server-url <url>      This is the base URL used to render
+                                   diagrams. Defaults to the public plantuml
+                                   server. (default:
+                                   "https://www.plantuml.com/plantuml")
   -x, --root-directory <path>      The path to your project (default: CWD)
-  -r, --hot-reload                 Rerun markdown generator every `interval` seconds, determined by interval option
-  -v, --interval-seconds <number>  If --hot-reload is set, how often should it reload (default: 2)
-  -p, --puml-directory <path>      Path to directory containing puml files which are referenced in markdown files (default: rootDirectory)
-  -m, --markdown-directory <path>  Path to directory containing markdown files referencing puml files (default: rootDirectory)
-  -g, --ignore-gitignore           Don't use .gitignore to skip PUML and MD
-  -i, --gitignore-path <path>      Use this as path to .gitignore file. (default: rootDirectory/.gitignore)
-  -d, --output-images              If set, will output images of diagrams to the dist directory
-  -b, --dist-directory <path>      If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)
-  -f, --image-formats <format>     If --output-images is set, sets the output image format (choices: "png", "svg", "both", default: "png")
-  -t, --turn-off-link-shortening   Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work
+  -r, --hot-reload                 Rerun markdown generator every `interval`
+                                   seconds, determined by interval option
+  -v, --interval-seconds <number>  If --hot-reload is set, how often should it
+                                   reload (default: 2)
+  -p, --puml-directory <path>      Path to directory containing puml files
+                                   which are referenced in markdown files
+                                   (default: rootDirectory)
+  -m, --markdown-directory <path>  Path to directory containing markdown files
+                                   referencing puml files (default:
+                                   rootDirectory)
+  -g, --ignore-gitignore           Don't use .gitignore rules to skip PUML and
+                                   MD
+  -i, --gitignore-path <path>      Use this as path to .gitignore file.
+                                   (default: rootDirectory/.gitignore)
+  -d, --output-images              If set, will output images of diagrams to
+                                   the dist directory
+  -b, --dist-directory <path>      If --output-images is set, path to output
+                                   diagram images (default:
+                                   rootDirectory/dist_puml)
+  -f, --image-formats <format>     If --output-images is set, sets the output
+                                   image format (choices: "png", "svg", "both",
+                                   default: "png")
+  -t, --turn-off-link-shortening   Use the full puml server link instead of the
+                                   tiny url, if your diagrams are too big this
+                                   won't work
+  --local-images                   Link Markdown to exported local images
+                                   (implies --output-images)
+  --interactive-links              Wrap local image previews in an interactive
+                                   renderer link
+  --check                          Check for stale Markdown and images without
+                                   writing or using the network
+  --dry-run                        List planned changes without writing or
+                                   using the network
+  --no-cache                       Disable the persistent diagram and image
+                                   cache
+  -l, --polr-url <url>             Use a private Polr shortener; reads
+                                   POLR_APIKEY from the environment
   -h, --help                       display help for command
 ```
 
 ### Notes
 - Comments within inline or multiline code styling will be ignored
-- Currently doesn't support cyclic graph references, i.e. a diagram can't reference any diagrams which reference back
-to it
+- Cyclic diagram links and recursive local includes fail with an error showing the reference chain.
 - See the [pre-commit hook](./.husky/pre-commit) to see how to add a git hook
-- If you are saving diagram images and have puml files which only define constants or settings
-(i.e. [example](./puml/constants.puml)) you'll see a warning in the console saying it failed to save the image to file
-because these aren't renderable on their own (since there is nothing to render)
+- Image export skips files without an `@start...` directive and files used only as local includes. A Markdown reference or diagram hyperlink makes an included file exportable. Other files must render successfully.
 - Anything inside `inline code` or `code blocks` will be excluded from rendering
 
 ### How It Works
@@ -148,25 +182,140 @@ though.
 ### Other Helpful Links
 * [C4-Puml](https://github.com/plantuml-stdlib/C4-PlantUML): A collection of PlantUML diagrams for use in C4, you'll see me using this in my examples
 
+### Known Issues
+* Seems to be breaking on Windows, see [here](https://github.com/danielyaa5/puml-for-markdown/issues/6). I don't have a
+Windows machine to test on so help here would be appreciated.
+
 ### More Examples
-[![ERD](https://tinyurl.com/ya6qvr7r)](https://tinyurl.com/ya6qvr7r)<!--![ERD](./puml/level_4_erd.puml)-->
+[![ERD](https://tinyurl.com/2amb263t)](https://tinyurl.com/2amb263t)<!--![ERD](./puml/level_4_erd.puml)-->
+
+
+
+[![Container View](https://tinyurl.com/284kg5h5)](https://tinyurl.com/284kg5h5)<!--![Container View](./puml/level_2_container_view.puml)-->
+
+
+
+[![Component View - Label Retrieval Job](https://tinyurl.com/262ys7bk)](https://tinyurl.com/262ys7bk)<!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)-->
+
 
 
+[![Component View - Pipeline Component](https://tinyurl.com/2xlmr44t)](https://tinyurl.com/2xlmr44t)<!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)-->
 
-[![Container View](https://tinyurl.com/yblre3m4)](https://tinyurl.com/yblre3m4)<!--![Container View](./puml/level_2_container_view.puml)-->
 
 
+[![Activity Diagram - Sampler A](https://tinyurl.com/26j5s2fw)](https://tinyurl.com/26j5s2fw)<!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)-->
 
-[![Component View - Label Retrieval Job](https://tinyurl.com/y8egw3wt)](https://tinyurl.com/y8egw3wt)<!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)-->
 
 
+[![Activity Diagram - Sampler B](https://tinyurl.com/2cqvdekn)](https://tinyurl.com/2cqvdekn)<!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)-->
 
-[![Component View - Pipeline Component](https://tinyurl.com/y9j7twkz)](https://tinyurl.com/y9j7twkz)<!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)-->
 
+### Reliability and operational notes
 
+- Fatal errors return a nonzero exit status, suitable for CI. Watch mode logs errors
+  and retries on the next interval; it runs immediately on startup.
+- Local `!include` files are expanded recursively relative to the file containing
+  the directive. Remote, standard-library, and macro-based includes remain for the
+  renderer to evaluate. This is not a complete PlantUML preprocessor: conditional
+  includes and `!include_once` / `!include_many` are not expanded locally.
+- Unrelated Markdown links, fenced/indented code, inline code, and line endings
+  are preserved. Unchanged Markdown files are not rewritten.
+- All Markdown references are checked before documents are written. Image exports
+  complete before Markdown is updated, but an export failure can leave earlier
+  successfully exported images updated; the operation is not a multi-file transaction.
+- Export overwrites the matching generated image files but never clears the output
+  directory. Stale images are retained. Ambiguous output names and symlinks inside
+  the output path are rejected.
+- Renderer and shortener requests time out after 30 seconds. If TinyURL fails,
+  a warning is printed and the direct PlantUML URL is used. Large URLs can still
+  exceed renderer/proxy limits; shortening does not remove the renderer's limit.
+- **Diagram privacy:** encoded diagram URLs contain recoverable source text.
+  The default shortener receives that URL, and the renderer receives the diagram
+  when someone opens it or when images are exported. For private diagrams, use
+  your own renderer with `--puml-server-url` and disable shortening with `-t`.
 
-[![Activity Diagram - Sampler A](https://tinyurl.com/ybp8ju9x)](https://tinyurl.com/ybp8ju9x)<!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)-->
 
+### Local images and offline viewing
+
+```sh
+puml-for-markdown --local-images --image-formats svg
+```
+
+This implies `--output-images` and produces relative Markdown links to files in
+`dist_puml`. For example, `<!--![Diagram](puml/a.puml)-->` becomes
+`![Diagram](dist_puml/puml/a.svg)<!--![Diagram](puml/a.puml)-->`.
+Paths are relative to each Markdown file and URL-encoded, including spaces.
+Both `.puml` and `.plantuml` sources work.
+
+SVG diagrams link to other exported SVG diagrams using relative paths. Open the
+SVG directly in a browser or serve the export folder to navigate between them.
+Markdown hosts may disable links inside embedded SVG images. PNG previews cannot
+contain clickable elements. With `--image-formats both`, Markdown uses SVG.
+
+Add `--interactive-links` to wrap a local preview in a link to the online renderer.
+That renderer link uses separate source with online diagram hyperlinks, while
+exported SVGs retain their local hyperlinks. Local-only mode skips URL shortening.
+Rendering still contacts the configured PlantUML server; use `--puml-server-url`
+with your own renderer when the source must remain private.
+
+### Check or preview changes without modifying files
+
+```sh
+puml-for-markdown --dry-run -t
+puml-for-markdown --check -t
+puml-for-markdown --local-images --image-formats svg --check
+```
+
+Both commands are offline and never write Markdown, images, or cache files.
+`--dry-run` lists planned changes and exits successfully; `--check` exits with 1
+if documentation is stale, otherwise 0. Invalid inputs still exit with 1.
+Neither can be combined with `--hot-reload`.
+
+A check that uses shortened URLs or exported images needs the cache from a prior
+successful generation with the same settings. If it is missing, the check reports
+that generation is needed rather than contacting a shortener or claiming the files
+are current. Direct-URL Markdown checks (`--check -t` without image export) do not
+require a cache. For CI, use that deterministic mode or restore the generation
+cache with the exported images.
+
+### Persistent cache and incremental watch mode
+
+Successful runs save `.puml-cache.json` at the project root. Add it to your
+`.gitignore`: encoded URLs contain recoverable source text, even for private diagrams.
+The cache contains no Polr API key. Renderer/provider settings and a hash of the key
+separate cache entries when configuration changes.
+
+The CLI reuses encodings, shortened URLs, and verified image files. Watch mode
+checks inputs each interval and only rebuilds affected content. Local include
+changes invalidate their parent diagrams; remote diagram links invalidate parents
+when their target URL changes. Local links stay stable when only a child changes.
+Missing or externally modified images are rendered again.
+
+```sh
+puml-for-markdown --hot-reload
+puml-for-markdown --no-cache
+```
+
+`--no-cache` forces regeneration without reading or writing the cache. Use it to
+refresh remote includes, renderer upgrades at the same URL, or expired short links:
+those external changes cannot be detected from local file content. Failed shortening
+attempts are not cached, allowing the next run to retry. Stale generated images are
+retained; the CLI never clears the destination directory.
+
+### Private Polr URL shortening
+
+```sh
+# Set POLR_APIKEY in your shell or CI secret environment first.
+puml-for-markdown --puml-server-url https://uml.example.com/plantuml \
+  --polr-url https://short.example.com
+```
 
+This adapts the provider idea from [PR #8](https://github.com/danielyaa5/puml-for-markdown/pull/8)
+by @mzagar. The implementation uses the [Polr v2 API](https://docs.polrproject.org/en/latest/developer-guide/api/):
+POST `/api/v2/action/shorten`, with URL-encoded `url`, `key`, and `response_type`
+fields. JSON and plain-text responses are accepted and validated. Credentials are
+never written into generated links or the cache. A failed Polr request falls back
+to the direct renderer URL, never TinyURL. `--polr-url` cannot be combined with `-t`.
 
-[![Activity Diagram - Sampler B](https://tinyurl.com/ya3cqxkv)](https://tinyurl.com/ya3cqxkv)<!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)-->
+To avoid a shortener entirely, use your own renderer with `-t`. This is also the
+simplest setup for private diagrams when URLs are short enough for your renderer.

package/bin/index.js

@@ -13,6 +13,7 @@ const run = require(path.resolve(__dirname, '../index.js'))
 // =============
 
 new Command()
+  .name('puml-for-markdown')
   .description('An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.')
   .option(
     '-s, --puml-server-url <url>',
@@ -45,7 +46,7 @@ new Command()
   )
   .option(
     '-g, --ignore-gitignore',
-    "Don't use .gitignore to skip PUML and MD. Will automatically be true if no gitignore is found",
+    "Don't use .gitignore rules to skip PUML and MD",
   )
   .addOption(new Option(
       '-i, --gitignore-path <path>',
@@ -70,6 +71,12 @@ new Command()
     '-t, --turn-off-link-shortening',
     "Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work",
   )
+  .option('--local-images', 'Link Markdown to exported local images (implies --output-images)')
+  .option('--interactive-links', 'Wrap local image previews in an interactive renderer link')
+  .option('--check', 'Check for stale Markdown and images without writing or using the network')
+  .option('--dry-run', 'List planned changes without writing or using the network')
+  .option('--no-cache', 'Disable the persistent diagram and image cache')
+  .option('-l, --polr-url <url>', 'Use a private Polr shortener; reads POLR_APIKEY from the environment')
   .action(opts => {
       const useDefaultGitignorePath = !opts.gitignorePath
 
@@ -81,14 +88,16 @@ new Command()
       opts.respectGitignore = !opts.ignoreGitignore
       opts.imageFormats = opts.imageFormats === 'both' ? ['png', 'svg'] : [opts.imageFormats]
 
-      // If a gitignore path wasn't specified, don't try and parse it
+      // A missing root ignore file must not disable nested .gitignore files.
       if (useDefaultGitignorePath && !fs.existsSync(opts.gitignorePath)) {
-          opts.respectGitignore = false
+          opts.gitignorePath = undefined
       }
 
-      return run(opts).catch((e) => {
-          console.error('FATAL EXCEPTION')
-          console.error(e)
+      return run(opts).then(result => {
+          if (opts.check && result.stale) process.exitCode = 1
+      }).catch((e) => {
+          console.error(`ERROR: ${e.message}`)
+          process.exitCode = 1
       })
   })
   .parse(process.argv)