metanorma-plugin-plantuml 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82db5cce760911ac43ad666a3d25e800341ff7b4f591d0905562f2e8bccb99e2
-  data.tar.gz: 170923ac6b7ace25020922e57904417ced9a3ef6d6f311a83be9ce0ab65b281f
+  metadata.gz: 3b3797ddb4db236753261836d74b360e635c58ea3b0eeaa09dfc1c7192dacf78
+  data.tar.gz: 0aba3ecbbc90f15570887ea206fa0a0c19b6d3179a7d9481438fb480df305873
 SHA512:
-  metadata.gz: 1347f4e1aab08371499c23dd2b39dfdc3aa3371f1db258ffa36ad557513a915e30b70e470df5f37d5766df38ca106dc54cbaad146f09cb135dfa1c41cab5e5f7
-  data.tar.gz: 1bb6c111325ab23cbe83f3c1903701740c31573f1baa80760c03f467559c07111b81ab80fc99afbda6de0445e5dab9e1c4cf58f96fb92e24a8552f7e1946a1d6
+  metadata.gz: ed86eced1c2c434f17ce4f3f5307c88f349c30275ad2051ea7c6063feb1d13ca6c64480ea406951221a75ceececd035ffed82519d9dfe169205f55a160996c9b
+  data.tar.gz: 2e1488a69e6c3ff71a88c17778fead0b264ed2b6c8d2a7d8803e04441d0d7f1b4b2cebdd102050e6428500a477a876d6f3cc8cdf9882da007a7bc6900a19cffa

data/Gemfile

@@ -13,9 +13,11 @@ rescue StandardError
 end
 
 gem "byebug"
+gem "canon"
 gem "debug"
 gem "metanorma"
-gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "feature/extract-plantuml"
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc",
+                         branch: "main"
 gem "rake"
 gem "rspec"
 gem "rspec-html-matchers"
@@ -25,4 +27,3 @@ gem "simplecov"
 gem "timecop"
 gem "vcr"
 gem "webmock"
-gem "canon"

data/README.adoc

@@ -65,6 +65,8 @@ the `plantuml` block directive.
 
 === Basic syntax
 
+==== Block style
+
 [source,asciidoc]
 ----
 [plantuml]
@@ -76,6 +78,25 @@ Bob -> Alice: Hi there
 ....
 ----
 
+==== Block macro style
+
+[source,asciidoc]
+----
+plantuml_image::path/to/my-plantuml.puml[]
+----
+
+The file `path/to/my-plantuml.puml` looks like:
+[source,plantuml]
+----
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hi there
+@enduml
+----
+
+`plantuml_image` block macro performs the same function as the `plantuml` block,
+but the PlantUML diagram is defined in a separate file instead of a block.
+
 === Supported diagram types
 
 PlantUML supports various diagram types, each with its own `@start` and `@end` directives:
@@ -183,6 +204,132 @@ Alice -> Bob: Hello
 ....
 ----
 
+==== Document-level includedirs configuration
+
+When using `!include` or `!includesub` in your PlantUML diagrams, you can set
+the default include directories (separated by semicolons) by
+`plantuml-includedirs` to search for files for all PlantUML diagrams in your
+document:
+
+[source,asciidoc]
+----
+:plantuml-includedirs: path/to/plantuml/include-1;path/to/plantuml/include-2
+
+[plantuml]
+....
+@startuml
+!include sequences.puml!1
+@enduml
+....
+
+[plantuml]
+....
+@startuml
+!include components.puml!FRONTEND
+!include components.puml!BACKEND
+
+WebApp --> APIGateway
+MobileApp --> APIGateway
+APIGateway --> DB
+@enduml
+....
+
+[plantuml]
+....
+@startuml
+title this contains only B and D
+!includesub subpart.puml!BASIC
+@enduml
+....
+----
+
+This plugin will search the include directories specified by
+`includedirs` options (i.e. `path/to/plantuml/include-1` and
+`path/to/plantuml/include-2`) for the files referenced in `!include` or
+`!includesub` directives (i.e. `sequences.puml`, `components.puml` and
+`subpart.puml`).
+
+You can also use `plantuml_image` to include external PlantUML files as images:
+
+[source,asciidoc]
+----
+:plantuml-includedirs: path/to/plantuml/include-1;path/to/plantuml/include-2
+
+plantuml_image::path/to/my-plantuml-1.puml[]
+
+plantuml_image::path/to/my-plantuml-2.puml[]
+----
+
+The file `path/to/my-plantuml-1.puml` looks like:
+[source,plantuml]
+----
+@startuml
+!include sequences.puml!1
+@enduml
+----
+
+The file `path/to/my-plantuml-2.puml` looks like:
+[source,plantuml]
+----
+@startuml
+!include components.puml!FRONTEND
+!include components.puml!BACKEND
+
+WebApp --> APIGateway
+MobileApp --> APIGateway
+APIGateway --> DB
+@enduml
+----
+
+When using `plantuml_image`, the path of the directory of the PlantUML file will
+also be added into the `includedirs`. (i.e. `path/to` will be added to
+`includedirs`)
+
+==== Block-level includedirs configuration
+
+When using `!include` or `!includesub` in your PlantUML diagrams, you can set
+the default include directories (separated by semicolons) by `includedirs` in
+block-level to search for files for the PlantUML diagram defined in your block:
+
+[source,asciidoc]
+----
+[plantuml,includedirs="path/to/plantuml/include-1"]
+....
+@startuml
+!include sequences.puml!1
+@enduml
+....
+
+[plantuml,includedirs="path/to/plantuml/include-2"]
+....
+@startuml
+!include components.puml!FRONTEND
+!include components.puml!BACKEND
+
+WebApp --> APIGateway
+MobileApp --> APIGateway
+APIGateway --> DB
+@enduml
+....
+----
+
+This plugin will search `sequences.puml` in `path/to/plantuml/include-1` and
+`components.puml` in `path/to/plantuml/include-2`.
+
+The block-level `includedirs` configuration can be used together with the
+document-level configuration to provide more granular control over include
+paths.  You can set multiple paths by separating them with semicolons.
+
+You can also use `plantuml_image` to set `includedirs` option to include
+external PlantUML files:
+
+[source,asciidoc]
+----
+plantuml_image::path/to/my-plantuml-1.puml[includedirs=path/to/plantuml/include-1]
+
+plantuml_image::path/to/my-plantuml-2.puml[includedirs=path/to/plantuml/include-2]
+----
+
 === Image attributes
 
 Standard AsciiDoc image attributes are supported:
@@ -272,7 +419,7 @@ Metanorma integration and PlantUML execution:
 ----
 Metanorma Document
       ↓
-BlockProcessor ← (processes [plantuml] blocks)
+BlockProcessor ← (processes [plantuml] blocks) or ImageBlockMacroProcessor ← (processes plantuml_image::{path}[{options}] macros)
       ↓
 Backend ← (Metanorma integration, paths, validation)
       ↓
@@ -284,6 +431,9 @@ PlantUML JAR ← (diagram generation)
 `BlockProcessor`:: Processes `[plantuml]` blocks in Metanorma documents and
 integrates with the Metanorma rendering pipeline.
 
+`ImageBlockMacroProcessor`:: Processes `plantuml_image::{path}[{options}]` macros
+in Metanorma documents and integrates with the Metanorma rendering pipeline.
+
 `Backend`:: Handles Metanorma-specific logic including document paths, PlantUML
 source validation, filename extraction, and attribute mapping.
 

data/Rakefile

@@ -10,7 +10,7 @@ task default: [
 ]
 
 def uri_open(url)
-  require 'open-uri'
+  require "open-uri"
   URI.parse(url).open
 end
 
@@ -29,7 +29,7 @@ file "data/plantuml.jar" do |file|
 end
 
 desc "Download PlantUML JAR file"
-task :download_jar => "data/plantuml.jar"
+task download_jar: "data/plantuml.jar"
 
 desc "Clean downloaded JAR file"
 task :clean_jar do

data/lib/metanorma/plugin/plantuml/backend.rb

@@ -14,31 +14,38 @@ module Metanorma
       class Backend
         class << self
           def plantuml_installed?
-            unless Wrapper.available?
-              raise "PlantUML not installed"
-            end
+            return true if plantuml_available?
+
+            raise "PlantUML not installed"
           end
 
           def plantuml_available?
             Wrapper.available?
           end
 
-          def generate_file(parent, reader, format_override = nil)
+          def generate_file( # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+            parent, reader, format_override: nil, options: {}
+          )
             ldir, imagesdir, fmt = generate_file_prep(parent)
             fmt = format_override if format_override
-            plantuml_content = prep_source(reader)
+            plantuml_content = prep_source(parent, reader)
 
             # Extract filename from PlantUML source if specified
+            filename = generate_unique_filename(fmt)
             extracted_filename = extract_plantuml_filename(plantuml_content)
 
+            if extracted_filename
+              filename = "#{extracted_filename}.#{fmt}"
+            end
+
             absolute_path, relative_path = path_prep(ldir, imagesdir)
-            filename = extracted_filename ? "#{extracted_filename}.#{fmt}" : generate_unique_filename(fmt)
             output_file = File.join(absolute_path, filename)
 
             result = Wrapper.generate(
               plantuml_content,
               format: fmt,
-              output_file: output_file
+              output_file: output_file,
+              includedirs: options[:includedirs],
             )
 
             unless result[:success]
@@ -48,10 +55,12 @@ module Metanorma
             File.join(relative_path, filename)
           end
 
-          def generate_multiple_files(parent, reader, formats, attrs)
+          def generate_multiple_files(
+            parent, reader, formats, attrs, options: {}
+          )
             # Generate files for each format
             filenames = formats.map do |format|
-              generate_file(parent, reader, format)
+              generate_file(parent, reader, format, options: options)
             end
 
             # Return data for BlockProcessor to create image block
@@ -68,28 +77,44 @@ module Metanorma
           def generate_file_prep(parent)
             ldir = localdir(parent)
             imagesdir = parent.document.attr("imagesdir")
-            fmt = parent.document.attr("plantuml-image-format")&.strip&.downcase || "png"
+            fmt = parent.document
+              .attr("plantuml-image-format")&.strip&.downcase ||
+              Wrapper::DEFAULT_FORMAT
             [ldir, imagesdir, fmt]
           end
 
           def localdir(parent)
             ret = Utils.localdir(parent.document)
-            File.writable?(ret) or
-              raise "Destination directory #{ret} not writable for PlantUML!"
-            ret
+            return ret if File.writable?(ret)
+
+            raise "Destination directory #{ret} not writable for PlantUML!"
           end
 
           def path_prep(localdir, imagesdir)
             path = Pathname.new(File.join(localdir, "_plantuml_images"))
             sourcepath = imagesdir ? File.join(localdir, imagesdir) : localdir
             path.mkpath
-            File.writable?(path) or
+
+            unless File.writable?(path)
               raise "Destination path #{path} not writable for PlantUML!"
-            [path, Pathname.new(path).relative_path_from(Pathname.new(sourcepath)).to_s]
+            end
+
+            [
+              path,
+              Pathname.new(path)
+                .relative_path_from(Pathname.new(sourcepath)).to_s,
+            ]
           end
 
-          def prep_source(reader)
-            src = reader.source
+          def prep_source(parent, reader) # rubocop:disable Metrics/MethodLength
+            src = if reader.respond_to?(:source)
+                    # get content from BlockProcessor
+                    reader.source
+                  else
+                    # get content from ImageBlockMacroProcessor
+                    docdir = parent.document.attributes["docdir"]
+                    File.read(File.join(docdir, reader))
+                  end
 
             # Validate that we have matching start/end pairs
             validate_plantuml_delimiters(src)
@@ -106,8 +131,9 @@ module Metanorma
 
           private
 
-          def validate_plantuml_delimiters(src)
-            # Find @start... pattern (case insensitive, support all PlantUML diagram types)
+          def validate_plantuml_delimiters(src) # rubocop:disable Metrics/MethodLength
+            # Find @start... pattern
+            # (case insensitive, support all PlantUML diagram types)
             start_match = src.match(/^@start(\w+)/i)
             unless start_match
               raise "PlantUML content must start with @start... directive!"
@@ -117,14 +143,16 @@ module Metanorma
             end_pattern = "@end#{diagram_type}"
 
             # Look for matching @end... directive (case insensitive)
-            unless src.match(/#{Regexp.escape(end_pattern)}\s*$/mi)
-              raise "@start#{diagram_type} without matching #{end_pattern} in PlantUML!"
+            unless /#{Regexp.escape(end_pattern)}\s*$/mi.match?(src)
+              raise "@start#{diagram_type} without matching #{end_pattern} " \
+                    "in PlantUML!"
             end
           end
 
           def extract_plantuml_filename(plantuml_content)
             # Extract filename from any @start... line if specified
-            # Only match when filename is on the same line as @start... (no newlines)
+            # Only match when filename is on the same line as @start...
+            # (no newlines)
             lines = plantuml_content.lines
             first_line = lines.first&.strip
             return nil unless first_line
@@ -142,11 +170,12 @@ module Metanorma
           def sanitize_filename(filename)
             # Remove quotes and sanitize for filesystem
             filename = filename.gsub(/^["']|["']$/, "")
-            # Replace any non-alphanumeric characters (except dash, underscore, dot) with underscore
+            # Replace any non-alphanumeric characters
+            # (except dash, underscore, dot) with underscore
             filename.gsub(/[^\w\-.]/, "_")
-                    .gsub(/\.{2,}/, "_")  # Replace multiple dots with underscore
-                    .gsub(/_{2,}/, "_")   # Replace multiple underscores with single
-                    .gsub(/^[_\-\.]+|[_\-\.]+$/, "")  # Remove leading/trailing special chars
+              .gsub(/\.{2,}/, "_")  # Replace multiple dots with underscore
+              .gsub(/_{2,}/, "_")   # Replace multiple underscores with single
+              .gsub(/^[_\-.]+|[_\-.]+$/, "") # Remove leading/trailing chars
           end
 
           def generate_unique_filename(format)

data/lib/metanorma/plugin/plantuml/block_processor.rb

@@ -1,30 +1,17 @@
 # frozen_string_literal: true
 
-require "asciidoctor"
-require "asciidoctor/extensions"
-require_relative "backend"
-
 module Metanorma
   module Plugin
     module Plantuml
       # PlantUML block processor for Asciidoctor
       class BlockProcessor < ::Asciidoctor::Extensions::BlockProcessor
+        include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
         use_dsl
         named :plantuml
         on_context :literal
         parse_content_as :raw
 
-        def abort(parent, reader, attrs, msg)
-          warn msg
-          attrs["language"] = "plantuml"
-          create_listing_block(
-            parent,
-            reader.source,
-            (attrs.reject { |k, _v| k.to_s.match?(/^\d+$/) })
-          )
-        end
-
-        def process(parent, reader, attrs)
+        def process(parent, reader, attrs) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           # Check for document-level disable flag
           if parent.document.attr("plantuml-disabled")
             return abort(parent, reader, attrs, "PlantUML processing disabled")
@@ -37,44 +24,25 @@ module Metanorma
 
           # Parse format specifications
           formats = parse_formats(attrs, parent.document)
+          options = parse_options(parent, reader, attrs)
 
-          if formats.length == 1
-            # Single format - original behavior
-            filename = Backend.generate_file(parent, reader, formats.first)
-            through_attrs = Backend.generate_attrs attrs
-            through_attrs["target"] = filename
-            create_image_block parent, through_attrs
-          else
-            # Multiple formats - generate multiple files
-            through_attrs = Backend.generate_multiple_files(parent, reader, formats, attrs)
-            create_image_block parent, through_attrs
-          end
+          process_image_block(parent, reader, attrs, formats, options)
         rescue StandardError => e
           abort(parent, reader, attrs, e.message)
         end
 
         private
 
-        def parse_formats(attrs, document)
-          # Check for formats attribute (multiple formats)
-          if attrs["formats"]
-            formats = attrs["formats"].split(",").map(&:strip).map(&:downcase)
-            return formats.select { |f| valid_format?(f) }
-          end
-
-          # Check for format attribute (single format override)
-          if attrs["format"]
-            format = attrs["format"].strip.downcase
-            return [format] if valid_format?(format)
-          end
+        def parse_options(parent, _reader, attrs)
+          options = {}
 
-          # Fall back to document attribute or default
-          default_format = document.attr("plantuml-image-format")&.strip&.downcase || "png"
-          [default_format]
-        end
+          # Parse include directory
+          options[:includedirs] = parse_doc_includedirs(parent.document)
+          options[:includedirs] = add_attrs_to_includedirs(
+            parent.document, attrs, options[:includedirs]
+          )
 
-        def valid_format?(format)
-          %w[png svg pdf txt eps].include?(format)
+          options
         end
       end
     end

data/lib/metanorma/plugin/plantuml/block_processor_base.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+require_relative "backend"
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      module BlockProcessorBase
+        def abort(parent, reader, attrs, msg)
+          warn msg
+          attrs["language"] = "plantuml"
+          create_listing_block(
+            parent,
+            reader.respond_to?(:source) ? reader.source : reader,
+            attrs.reject { |k, _v| k.to_s.match?(/^\d+$/) },
+          )
+        end
+
+        private
+
+        def parse_doc_includedirs(document)
+          docdir = document.attributes["docdir"]
+          includedirs = document.attr("plantuml-includedirs")&.split(";") || []
+
+          includedirs.map! do |includedir|
+            if Pathname.new(includedir).relative?
+              Pathname.new(docdir).join(includedir).to_s
+            else
+              includedir
+            end
+          end
+
+          includedirs.compact.uniq
+        end
+
+        def parse_formats(attrs, document) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+          # Check for formats attribute (multiple formats)
+          if attrs["formats"]
+            formats = attrs["formats"].split(",").map(&:strip).map(&:downcase)
+            return formats.select { |f| valid_format?(f) }
+          end
+
+          # Check for format attribute (single format override)
+          if attrs["format"]
+            format = attrs["format"].strip.downcase
+            return [format] if valid_format?(format)
+          end
+
+          # Fall back to document attribute or default
+          default_format = document
+            .attr("plantuml-image-format")&.strip&.downcase ||
+            Wrapper::DEFAULT_FORMAT
+
+          [default_format]
+        end
+
+        def valid_format?(format)
+          Wrapper::SUPPORTED_FORMATS.include?(format)
+        end
+
+        def add_attrs_to_includedirs(document, attrs, includedirs)
+          docdir = document.attributes["docdir"]
+          attrs_includedirs = attrs["includedirs"]&.split(";") || []
+
+          attrs_includedirs.each do |attrs_includedir|
+            includedirs << if Pathname.new(attrs_includedir).relative?
+                             Pathname.new(docdir).join(attrs_includedir).to_s
+                           else
+                             attrs_includedir
+                           end
+          end
+
+          includedirs.compact.uniq
+        end
+
+        def process_image_block(parent, reader, attrs, formats, options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          if formats.length == 1
+            # Single format - original behavior
+            filename = Backend.generate_file(
+              parent, reader, format_override: formats.first, options: options
+            )
+            through_attrs = Backend.generate_attrs(attrs)
+            through_attrs["target"] = filename
+          else
+            # Multiple formats - generate multiple files
+            through_attrs = Backend
+              .generate_multiple_files(
+                parent, reader, formats, attrs, options: options
+              )
+          end
+
+          create_image_block parent, through_attrs
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/config.rb

@@ -17,7 +17,7 @@ module Metanorma
           options = [
             "-Xss5m",
             "-Xmx#{memory_limit}",
-            "-Djava.awt.headless=true"
+            "-Djava.awt.headless=true",
           ]
 
           if RbConfig::CONFIG["host_os"].match?(/darwin|mac os/)

data/lib/metanorma/plugin/plantuml/errors.rb

@@ -12,16 +12,21 @@ module Metanorma
 
       class JarNotFoundError < PlantumlError
         def initialize(jar_path = nil)
-          message = jar_path ?
-            "PlantUML JAR file not found at: #{jar_path}" :
-            "PlantUML JAR file not found"
+          message = if jar_path
+                      "PlantUML JAR file not found at: #{jar_path}"
+                    else
+                      "PlantUML JAR file not found"
+                    end
           super(message)
         end
       end
 
       class JavaNotFoundError < PlantumlError
         def initialize
-          super("Java runtime not found. Please ensure Java is installed and available in PATH")
+          super(
+            "Java runtime not found. Please ensure Java is installed and " \
+            "available in PATH",
+          )
         end
       end
 
@@ -34,7 +39,10 @@ module Metanorma
 
       class InvalidFormatError < PlantumlError
         def initialize(format, available_formats)
-          super("Invalid format '#{format}'. Available formats: #{available_formats.join(', ')}")
+          super(
+            "Invalid format '#{format}'. Available formats: " \
+            "#{available_formats.join(', ')}",
+          )
         end
       end
     end

data/lib/metanorma/plugin/plantuml/image_block_macro_processor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      # PlantUML block processor for Asciidoctor
+      class ImageBlockMacroProcessor < ::Asciidoctor::Extensions::BlockMacroProcessor
+        include ::Metanorma::Plugin::Plantuml::BlockProcessorBase
+        use_dsl
+        named :plantuml_image
+
+        def process(parent, reader, attrs) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          # Check for document-level disable flag
+          if parent.document.attr("plantuml-disabled")
+            return abort(parent, reader, attrs, "PlantUML processing disabled")
+          end
+
+          # Check PlantUML availability explicitly
+          unless Backend.plantuml_available?
+            return abort(parent, reader, attrs, "PlantUML not installed")
+          end
+
+          # Parse format specifications
+          formats = parse_formats(attrs, parent.document)
+          options = parse_options(parent, reader, attrs)
+
+          process_image_block(parent, reader, attrs, formats, options)
+        rescue StandardError => e
+          abort(parent, reader, attrs, e.message)
+        end
+
+        private
+
+        def add_image_path_to_includedirs(document, image_path, includedirs)
+          docdir = document.attributes["docdir"]
+          includedirs << File.dirname(File.join(docdir, image_path))
+          includedirs.compact.uniq
+        end
+
+        def parse_options(parent, reader, attrs)
+          options = {}
+
+          # Parse include directory
+          options[:includedirs] = parse_doc_includedirs(parent.document)
+          options[:includedirs] = add_attrs_to_includedirs(
+            parent.document, attrs, options[:includedirs]
+          )
+          options[:includedirs] = add_image_path_to_includedirs(
+            parent.document, reader, options[:includedirs]
+          )
+
+          options
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/plantuml/utils.rb

@@ -13,14 +13,6 @@ module Metanorma
               document.attributes["docdir"] ||
               File.dirname(document.attributes["docfile"] || ".")
           end
-
-          def relative_file_path(document, file_path)
-            return file_path if Pathname.new(file_path).absolute?
-
-            docdir = document.attributes["docdir"] || Dir.pwd
-            File.expand_path(file_path, docdir)
-          end
-
         end
       end
     end

data/lib/metanorma/plugin/plantuml/version.rb

@@ -1,8 +1,8 @@
 module Metanorma
   module Plugin
     module Plantuml
-      VERSION = "1.0.0"
-      PLANTUML_JAR_VERSION = "1.2025.4"
+      VERSION = "1.0.2".freeze
+      PLANTUML_JAR_VERSION = "1.2025.4".freeze
     end
   end
 end

data/lib/metanorma/plugin/plantuml/wrapper.rb

@@ -12,11 +12,14 @@ module Metanorma
   module Plugin
     module Plantuml
       class Wrapper
-        PLANTUML_JAR_NAME = "plantuml.jar"
-        PLANTUML_JAR_PATH = File.join(File.dirname(__FILE__), "..", "..", "..", "..", "data", PLANTUML_JAR_NAME)
+        PLANTUML_JAR_NAME = "plantuml.jar".freeze
+        PLANTUML_JAR_PATH = File.join(
+          File.dirname(__FILE__), "..", "..", "..",
+          "..", "data", PLANTUML_JAR_NAME
+        )
 
         SUPPORTED_FORMATS = %w[png svg pdf txt eps].freeze
-        DEFAULT_FORMAT = "png"
+        DEFAULT_FORMAT = "png".freeze
 
         class << self
           def jvm_options
@@ -29,11 +32,19 @@ module Metanorma
             options
           end
 
-          def generate(content, format: DEFAULT_FORMAT, output_file: nil, base64: false, **options)
+          def generate( # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            content,
+            format: DEFAULT_FORMAT,
+            output_file: nil,
+            base64: false, **options
+          )
             validate_format!(format)
             ensure_jar_available!
             ensure_java_available!
 
+            include_files = get_include_files(content, options)
+            options[:include_files] = include_files unless include_files.empty?
+
             result = if output_file
                        generate_to_file(content, format, output_file, options)
                      elsif base64
@@ -47,27 +58,48 @@ module Metanorma
             { success: false, error: e }
           end
 
-          def generate_from_file(input_file, format: DEFAULT_FORMAT, output_file: nil, base64: false, **options)
+          def get_include_files(content, _options) # rubocop:disable Metrics/MethodLength
+            include_files = []
+            content.each_line do |line|
+              case line
+              when /(!include|!includesub)\s(.+){1}/
+                found_file = $2.split("!").first
+
+                # skip web links and standard libraries
+                if found_file.start_with?("<", "http")
+                  found_file = nil
+                end
+
+                include_files << found_file
+              end
+            end
+            include_files.compact.uniq
+          end
+
+          def generate_from_file(
+            input_file, format: DEFAULT_FORMAT,
+            output_file: nil, base64: false, **options
+          )
             unless File.exist?(input_file)
               raise GenerationError.new("Input file not found: #{input_file}")
             end
 
             content = File.read(input_file)
-            generate(content, format: format, output_file: output_file, base64: base64, **options)
+            generate(content, format: format, output_file: output_file,
+                              base64: base64, **options)
           end
 
           def version
             return nil unless available?
 
-            cmd = [configuration.java_path, *jvm_options, "-jar", PLANTUML_JAR_PATH, "-version"]
-            output, error, status = Open3.capture3(*cmd)
+            cmd = [configuration.java_path, *jvm_options, "-jar",
+                   PLANTUML_JAR_PATH, "-version"]
+            output, _, status = Open3.capture3(*cmd)
 
             if status.success?
               # Extract version from output
               version_match = output.match(/PlantUML version ([\d.]+)/)
               version_match ? version_match[1] : PLANTUML_JAR_VERSION
-            else
-              nil
             end
           rescue StandardError
             nil
@@ -75,6 +107,7 @@ module Metanorma
 
           def available?
             return false if ENV["PLANTUML_DISABLED"] == "true"
+
             File.exist?(PLANTUML_JAR_PATH) && java_available?
           end
 
@@ -122,23 +155,28 @@ module Metanorma
             execute_plantuml(content, format, output_file, options)
 
             unless File.exist?(output_file)
-              raise GenerationError.new("Output file was not created: #{output_file}")
+              raise GenerationError.new(
+                "Output file was not created: #{output_file}",
+              )
             end
 
             { output_path: File.expand_path(output_file) }
           end
 
-          def generate_to_base64(content, format, options)
-            Tempfile.create(['plantuml_output', ".#{format}"]) do |temp_file|
+          def generate_to_base64(content, format, options) # rubocop:disable Metrics/MethodLength
+            Tempfile.create(["plantuml_output", ".#{format}"]) do |temp_file|
               temp_file.close
 
               execute_plantuml(content, format, temp_file.path, options)
 
               unless File.exist?(temp_file.path)
-                raise GenerationError.new("Temporary output file was not created")
+                raise GenerationError.new(
+                  "Temporary output file was not created",
+                )
               end
 
-              encoded_content = Base64.strict_encode64(File.read(temp_file.path))
+              encoded_content = Base64
+                .strict_encode64(File.read(temp_file.path))
               { base64: encoded_content }
             end
           end
@@ -151,45 +189,92 @@ module Metanorma
             generate_to_file(content, format, output_file, options)
           end
 
-          def execute_plantuml(content, format, output_file, options)
-            Tempfile.create(['plantuml_input', '.puml']) do |input_file|
-              input_file.write(content)
-              input_file.close
+          def execute_plantuml(content, format, output_file, options) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+            # PlantUML generates output files based on filename specified in
+            # @start... line
+            # We need to use a temp directory and then move the file
+            Dir.mktmpdir do |temp_dir| # rubocop:disable Metrics/BlockLength
+              # create input file
+              File.open("#{temp_dir}/plantuml_input.puml", "w") do |f|
+                f.write(content)
+              end
 
-              # PlantUML generates output files based on filename specified in @start... line
-              # We need to use a temp directory and then move the file
-              Dir.mktmpdir do |temp_dir|
-                cmd = build_command(input_file.path, format, temp_dir, options)
+              # Handle include files
+              if options[:include_files] && !options[:include_files].empty?
+                if options[:includedirs].empty?
+                  # raise error when include files are found but includedirs
+                  # is nil
+                  raise PlantumlError.new(
+                    "includedirs is required when include files are specified",
+                  )
+                end
 
-                output, error, status = Open3.capture3(*cmd)
+                options[:include_files].each do |include_file|
+                  # find local include file in includedirs
+                  found_include_file = nil
+                  options[:includedirs].each do |includedir|
+                    include_file_path = File.join(includedir, include_file)
+                    if File.exist?(include_file_path)
+                      found_include_file = include_file_path
+                      break
+                    end
+                  end
 
-                unless status.success?
-                  error_message = error.empty? ? "Unknown PlantUML error" : error.strip
-                  raise GenerationError.new(error_message, error)
-                end
+                  if found_include_file
+                    # create include file in temp directory
+                    temp_include_file = File.join(temp_dir, include_file)
+                    FileUtils.mkdir_p(File.dirname(temp_include_file))
 
-                # Find the generated file and move it to the desired location
-                if output_file
-                  generated_file = find_generated_file(temp_dir, content, format)
-                  if generated_file && File.exist?(generated_file)
-                    FileUtils.mv(generated_file, output_file)
-                  else
-                    # Debug: List what files were actually generated
-                    generated_files = Dir.glob(File.join(temp_dir, "*"))
-                    error_msg = "Generated file not found in temp directory. "
-                    error_msg += "Expected: #{generated_file}. "
-                    error_msg += "Found files: #{generated_files.map { |f| File.basename(f) }.join(', ')}"
-                    raise GenerationError.new(error_msg)
+                    File.open(temp_include_file, "w") do |f|
+                      f.write(File.read(found_include_file))
+                    end
                   end
                 end
+              end
 
-                output
+              cmd = build_command(
+                "#{temp_dir}/plantuml_input.puml",
+                format,
+                temp_dir,
+                options,
+              )
+
+              output, error, status = Open3.capture3(*cmd)
+
+              unless status.success?
+                error_message = if error.empty?
+                                  "Unknown PlantUML error"
+                                else
+                                  error.strip
+                                end
+                raise GenerationError.new(error_message, error)
               end
+
+              # Find the generated file and move it to the desired location
+              if output_file
+                generated_file = find_generated_file(temp_dir, content,
+                                                     format)
+                if generated_file && File.exist?(generated_file)
+                  FileUtils.mv(generated_file, output_file)
+                else
+                  # Debug: List what files were actually generated
+                  generated_files = Dir.glob(File.join(temp_dir, "*"))
+                  error_msg = "Generated file not found in temp directory. "
+                  error_msg += "Expected: #{generated_file}. "
+                  error_msg += "Found files: #{generated_files.map do |f|
+                    File.basename(f)
+                  end.join(', ')}"
+                  raise GenerationError.new(error_msg)
+                end
+              end
+
+              output
             end
           end
 
-          def find_generated_file(temp_dir, content, format)
-            # PlantUML generates files based on the filename specified in @start... line
+          def find_generated_file(temp_dir, content, format) # rubocop:disable Metrics/MethodLength
+            # PlantUML generates files based on the filename specified in
+            # @start... line
             extension = format.to_s.downcase
 
             # First, try to extract filename from PlantUML content
@@ -197,17 +282,19 @@ module Metanorma
 
             if plantuml_filename
               # Look for file with PlantUML-specified name
-              generated_file = File.join(temp_dir, "#{plantuml_filename}.#{extension}")
+              generated_file = File.join(temp_dir,
+                                         "#{plantuml_filename}.#{extension}")
               return generated_file if File.exist?(generated_file)
             end
 
-            # Fallback: scan directory for any generated files with correct extension
+            # Fallback: scan directory for any generated files with
+            # the correct extension
             Dir.glob(File.join(temp_dir, "*.#{extension}")).first
           end
 
           def extract_plantuml_filename_from_content(content)
             # Extract the raw filename from @start... line (don't sanitize)
-            match = content.match(/^@start\w+\s+(.+)$/mi)
+            match = content.match(/^@start\w+\s+(.{1,999})$/mi)
             return nil unless match
 
             filename = match[1].strip.split("\n").first&.strip
@@ -217,7 +304,7 @@ module Metanorma
             filename.gsub(/^["']|["']$/, "")
           end
 
-          def build_command(input_file, format, output_dir, options)
+          def build_command(input_file, format, output_dir, _options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
             cmd = [
               configuration.java_path,
               *jvm_options,
@@ -225,17 +312,9 @@ module Metanorma
             ]
 
             # Add format-specific options
-            case format.to_s.downcase
-            when "png"
-              cmd << "-tpng"
-            when "svg"
-              cmd << "-tsvg"
-            when "pdf"
-              cmd << "-tpdf"
-            when "txt"
-              cmd << "-ttxt"
-            when "eps"
-              cmd << "-teps"
+            format_str = format.to_s.downcase
+            if SUPPORTED_FORMATS.include?(format_str)
+              cmd << "-t#{format_str}"
             end
 
             # Add output directory option

data/lib/metanorma-plugin-plantuml.rb

@@ -1,4 +1,3 @@
-
 module Metanorma
   module Plugin
     module Plantuml
@@ -12,4 +11,6 @@ require "metanorma/plugin/plantuml/config"
 require "metanorma/plugin/plantuml/wrapper"
 require "metanorma/plugin/plantuml/utils"
 require "metanorma/plugin/plantuml/backend"
+require "metanorma/plugin/plantuml/block_processor_base"
 require "metanorma/plugin/plantuml/block_processor"
+require "metanorma/plugin/plantuml/image_block_macro_processor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-plantuml
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-26 00:00:00.000000000 Z
+date: 2025-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -58,8 +58,10 @@ files:
 - lib/metanorma-plugin-plantuml.rb
 - lib/metanorma/plugin/plantuml/backend.rb
 - lib/metanorma/plugin/plantuml/block_processor.rb
+- lib/metanorma/plugin/plantuml/block_processor_base.rb
 - lib/metanorma/plugin/plantuml/config.rb
 - lib/metanorma/plugin/plantuml/errors.rb
+- lib/metanorma/plugin/plantuml/image_block_macro_processor.rb
 - lib/metanorma/plugin/plantuml/utils.rb
 - lib/metanorma/plugin/plantuml/version.rb
 - lib/metanorma/plugin/plantuml/wrapper.rb