metanorma-plugin-plantuml 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07e9ee8fdf5e99900198be1e8ea51dd948957c62475694b0b40660fd25bff4d2
-  data.tar.gz: c6b49a7ec9b20d96e45c6600f2a368c3b5df542e6ee3bcc3f75ed17dd7d929bc
+  metadata.gz: c7c85595e30e3155c473b4f44936209c3f95c8ab5cf29d55a2368bad6584c136
+  data.tar.gz: d7e58a9934d9995c9b36c3b86dc543a7c633d0c31fab5dd543707b7f347207c8
 SHA512:
-  metadata.gz: f9903747e63488c1af15f954441acbdaaa17c715935b1d0d390d515173f5e052df6defc0828de335e6491e019c69b9fa915365850a91a91155e5d68e3ee60376
-  data.tar.gz: 73e6bac1cfc02b057d52eb39913bfb833f0b70237fb8d00323424ef17a6b5ea302baf57faae486dda1779f0254035a4b449e0abb9648c21ceb18e30a39234778
+  metadata.gz: '05039945787b1a1d65f8a37193db39346f2d42ac820dff54d70724fbb09bdbe2808a9ca20477a78e78b1357f65de337c289a075feabf27c9e3ae92264e671865'
+  data.tar.gz: 1cff1673fbed5b3e00a6e05d7642cccce29e6d5f5d2cd62500860fddf089a8fc7046a2c49df41b422804b03eb762bd0bb6ac21d67e8763e6d38583f29df4e0ed

data/.github/workflows/rake.yml

@@ -10,6 +10,6 @@ on:
 
 jobs:
   rake:
-    uses: metanorma/ci/.github/workflows/plantuml-rake.yml@main
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
     secrets:
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/Gemfile

@@ -17,7 +17,7 @@ gem "canon"
 gem "debug"
 gem "metanorma"
 gem "metanorma-standoc", github: "metanorma/metanorma-standoc",
-                         branch: "feature/extract-plantuml"
+                         branch: "main"
 gem "rake"
 gem "rspec"
 gem "rspec-html-matchers"

data/README.adoc

@@ -4,7 +4,7 @@ image:https://github.com/metanorma/metanorma-plugin-plantuml/workflows/rake/badg
 
 == Purpose
 
-This is a Metanorma plugin to enable usage of PlantUML diagrams in Metanorma
+This Metanorma plugin enables the usage of PlantUML diagrams in Metanorma
 documents.
 
 It provides a Ruby API that wraps a bundled PlantUML JAR file.
@@ -59,12 +59,134 @@ $ gem install metanorma-plugin-plantuml
 
 == Usage
 
+=== General
+
 This plugin enables PlantUML diagram generation in Metanorma documents through
-the `plantuml` block directive.
+multiple methods, including:
+
+* Block syntax using `[plantuml]` blocks
+* Command syntax using `plantuml_image::{path}[{options}]`
+
+Both syntaxes support various diagram types, output formats, and image
+attributes, as well as PlantUML's `include!` and `includesub!` directives for
+modular diagrams.
+
+The effect of both syntaxes is the same: they generate and embed PlantUML diagrams
+as images in the output document.
+
+However, there are important differences in using them with external files, as
+it is described in the various options.
+
+The difference lies in how the PlantUML source is provided:
+
+* In the block syntax, the PlantUML source is defined directly within the
+document, and hence generated by PlantUML without a specific file context.
+
+* In the command syntax, the PlantUML source is read from an external file,
+which provides a file context for the PlantUML source.
+
+Generally, the command syntax is more suitable for referencing external PlantUML
+files.
+
+
+=== Command syntax for external diagrams
+
+PlantUML diagrams can be directly referenced from external files using the
+`plantuml_image::{path}[{options}]` command.
+
+Syntax:
+
+[source,asciidoc]
+----
+plantuml_image::{plantuml-source.puml}[{options}]
+----
+
+Where,
+
+`{plantuml-source.puml}`:: Path to the PlantUML source file, relative to the
+path of the current file.
+
+`{options}`:: (Optional) Comma-separated list of options to customize diagram
+generation.
+
+.Specifying an external PlantUML diagram using the `plantuml_image` command without options
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::foo/bar.puml[]
+----
+
+The file `foo/bar.puml` looks like:
+
+[source,plantuml]
+----
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hi there
+@enduml
+----
+====
+
+.Specifying an external PlantUML diagram using the `plantuml_image` command with options
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::foo/bar.puml[format=svg]
+----
+
+The file `foo/bar.puml` is the same as above.
+The `format=svg` option specifies the output format as SVG.
+====
+
 
 
-=== Basic syntax
+=== Block syntax for inline diagrams
+
+PlantUML diagrams can be defined directly within your Metanorma document using
+`[plantuml]` blocks.
+
+Syntax:
 
+[source,asciidoc]
+----
+[plantuml]
+....
+{PlantUML diagram source here}
+....
+----
+
+Where,
+
+`[plantuml]`:: Specifies that the block contains PlantUML source code.
+
+`....`:: Delimiters that indicate the start and end of the PlantUML source code.
+
+`{PlantUML diagram source here}`:: The actual PlantUML diagram definition using
+PlantUML syntax.
+
+
+The block can be used with or without options.
+
+Syntax with options:
+
+[source,asciidoc]
+----
+[plantuml,{options}]
+....
+{PlantUML diagram source here}
+....
+----
+
+Where,
+
+`{options}`:: Comma-separated list of options to customize diagram generation.
+
+
+.Specifying a simple PlantUML diagram in the `[plantuml]` block
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml]
@@ -75,10 +197,14 @@ Bob -> Alice: Hi there
 @enduml
 ....
 ----
+====
+
+
 
 === Supported diagram types
 
-PlantUML supports various diagram types, each with its own `@start` and `@end` directives:
+PlantUML, and therefore this plugin, supports various diagram types, each with
+its own `@start` and `@end` directives:
 
 `@startuml` / `@enduml`:: UML diagrams (sequence, class, activity, etc.)
 `@startmindmap` / `@endmindmap`:: Mind map diagrams
@@ -129,12 +255,40 @@ Bob --> Alice: Authentication Response
 ----
 ====
 
+
 === Format options
 
 ==== Single format specification
 
-Specify the output format using the `format` attribute:
+The output format is specified using the `format` option, which can be applied
+in both block and command syntaxes.
+
+Block syntax:
+
+[source,adoc]
+----
+[plantuml,format={format}]
+----
+
+Command syntax:
+
+[source,adoc]
+----
+plantuml_image::{path}[format={format}]
+----
+
+Where `{format}` can be one of the following:
+
+`png`:: (default) Portable Network Graphics
+`svg`:: Scalable Vector Graphics
+`pdf`:: Portable Document Format
+`txt`:: ASCII art text output
+`eps`:: Encapsulated PostScript
+
 
+.Block syntax with format option
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,format=svg]
@@ -144,19 +298,47 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
 
-Supported formats:
+.Command syntax with format option
+[example]
+====
+[source,asciidoc]
+----
+plantuml_image::path/to/my-plantuml.puml[format=svg]
+----
+====
 
-`png`:: (default) Portable Network Graphics
-`svg`:: Scalable Vector Graphics
-`pdf`:: Portable Document Format
-`txt`:: ASCII art text output
-`eps`:: Encapsulated PostScript
 
 ==== Multiple format generation
 
-Generate multiple formats simultaneously using the `formats` attribute:
+It is possible to generate multiple output formats simultaneously by specifying
+the `formats` option, which accepts a comma-separated list of formats.
+
+While Metanorma does not currently support embedding multiple images for a single
+diagram, generating multiple formats can be useful for documentation or other
+purposes.
 
+Block syntax:
+
+[source,adoc]
+----
+[plantuml,formats="{format1},{format2},..."]
+----
+
+Command syntax:
+
+[source,adoc]
+----
+plantuml_image::{path}[formats="{format1},{format2},..."]
+----
+
+Where `{format1}`, `{format2}`, etc. can be any of the supported formats listed
+above.
+
+.Block syntax with multiple formats
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml,formats="png,svg,pdf"]
@@ -166,11 +348,26 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
+
 
 ==== Document-level format configuration
 
-Set the default format for all PlantUML diagrams in your document:
+The default format for all PlantUML diagrams in a document can be set using the
+`plantuml-image-format` document attribute.
+
+Syntax:
+
+[source,asciidoc]
+----
+:plantuml-image-format: {format}
+----
+
+Where `{format}` can be any of the supported formats listed above.
 
+.Document with document-level format configuration
+[example]
+====
 [source,asciidoc]
 ----
 :plantuml-image-format: svg
@@ -182,22 +379,246 @@ Alice -> Bob: Hello
 @enduml
 ....
 ----
+====
 
-=== Image attributes
+=== Using `!include` and `!includesub`
+
+==== General
+
+PlantUML supports modular diagram definitions using the `!include` and
+`!includesub` directives to include external PlantUML files or specific parts of
+them.
+
+PlantUML is able to resolve relative paths in these directives based on the context
+of the PlantUML source.
+
+This is where the behavior differs between the block syntax and the command
+syntax:
+
+* In the block syntax, as the PlantUML source is defined inline within the
+document, there is no associated file path for the PlantUML source. The
+consequence is that PlantUML cannot resolve relative paths in `!include` or
+`!includesub` directives, as there is no associated file path. In order to
+resolve includes, you must specify the `includedirs` option to provide
+directories to search for included files.
+
+* In the command syntax, the PlantUML source is read from an external file. This
+means that relative paths in `!include` or `!includesub` directives are resolved
+relative to the location of the PlantUML source file. The `includedirs` option
+is not needed for resolving includes, but can still be used to add additional
+directories to search.
+
+
+==== Setting `includedirs`
 
-Standard AsciiDoc image attributes are supported:
+PlantUML allows you to specify include directories using the `includedirs`
+option. This option can be set at both the document level and the block level,
+through the option of the same name.
+
+There are two ways to set `includedirs`:
+
+* Document-level configuration using the `plantuml-includedirs` document attribute
+
+* The `includedirs` option in the `[plantuml]` block or `plantuml_image` command
+
+Note that when using the `plantuml_image` command, the directory that contains
+the specified PlantUML file will be automatically added as one of the
+`includedirs` directories. This means that any relative includes in the PlantUML
+file will be resolved relative to the file's location, even if `includedirs` is
+not explicitly set.
+
+
+==== Document-level `plantuml-includedirs` attribute
+
+It is possible to set default include directories (separated by semicolons) for
+all PlantUML diagrams in a document using the `plantuml-includedirs` document
+attribute.
+
+This is useful when a document contains multiple PlantUML diagrams that share
+common include files stored in specific directories, e.g. style definitions.
+
+The directories specified in this attribute will be used as the default include
+paths for all PlantUML diagrams in the document, including for both `[plantuml]`
+blocks and `plantuml_image` commands.
+
+NOTE: When using the `plantuml_image` command, the directory that contains the
+specified PlantUML file will always be automatically added as one of the
+`includedirs` directories.
+
+Syntax:
 
 [source,asciidoc]
 ----
-[plantuml,id=my-diagram,title="My Sequence Diagram",width=600,height=400]
+:plantuml-includedirs: {path1};{path2};...
+----
+
+.Resolving PlantUML includes with document-level `includedirs` attribute
+[example]
+====
+[source,asciidoc]
+----
+:plantuml-includedirs: path/to/plantuml/include-1;path/to/plantuml/include-2
+
+[plantuml]
 ....
 @startuml
-Alice -> Bob: Hello
+!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
+....
+----
+
+These `[plantuml]` blocks use `!include` and `!includesub` directives to include
+external PlantUML files. PlantUML will search the include directories specified
+by `includedirs` options to find `sequences.puml`, `components.puml` and
+`subpart.puml`, at:
+
+* `path/to/plantuml/include-1`
+* `path/to/plantuml/include-2`
+====
+
+
+.Resolving PlantUML includes in `plantuml_image` command with document-level `includedirs` attribute
+[example]
+====
+[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[]
+----
+
+With `path/to/my-plantuml-1.puml` as:
+
+[source,plantuml]
+----
+@startuml
+!include sequences.puml!1
+@enduml
+----
+
+With `path/to/my-plantuml-2.puml` as:
+
+[source,plantuml]
+----
+@startuml
+!include components.puml!FRONTEND
+!include components.puml!BACKEND
+
+WebApp --> APIGateway
+MobileApp --> APIGateway
+APIGateway --> DB
 @enduml
+----
+
+In using the `plantuml_image` command, the directory containing each PlantUML file
+(`path/to` in this case) is automatically added to the `includedirs`.
+
+Thus in rendering `path/to/my-plantuml-1.puml`, PlantUML will search for
+`sequences.puml` in both `path/to` and the directories specified by the
+`plantuml-includedirs` attribute.
+
+Similarly, in rendering `path/to/my-plantuml-2.puml`, PlantUML will search for
+`components.puml` in both `path/to` and the directories specified by the
+`plantuml-includedirs` attribute.
+====
+
+
+==== Diagram-level `includedirs` option
+
+The `includedirs` option can be used to specify include directories (separated
+by semicolons) for both `[plantuml]` blocks and the `plantuml_image` command.
+
+This option applies only to a single diagram in the document without affecting
+others.
+
+The diagram-level `includedirs` configuration can be used together with the
+document-level configuration to provide more granular control over include
+paths, where it is considered to have higher precedence than the document-level
+configuration.
+
+Syntax:
+
+[source,asciidoc]
+----
+[plantuml,includedirs="{path1};{path2};..."]
+----
+
+Where,
+
+`{path1}`, `{path2}`, etc.:: paths to directories containing PlantUML files to
+be included, delimited by semicolons.
+
+
+.Resolving PlantUML includes using diagram-level `includedirs` in `[plantuml]` blocks
+[example]
+====
+[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`.
+====
+
+
+.Resolving PlantUML includes using diagram-level `includedirs` with `plantuml_image` command
+[example]
+====
+[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
+
+The block and command syntaxes both support standard AsciiDoc image attributes
+to customize the appearance and behavior of the generated PlantUML diagrams.
 
-Supported attributes:
+Supported attributes are as follows:
 
 `id`:: Element identifier
 `title`:: Image title/caption
@@ -208,34 +629,124 @@ Supported attributes:
 `float`:: Float positioning
 `role`:: CSS class/role
 
+
+Block syntax:
+
+[source,asciidoc]
+----
+[plantuml,{image-attributes}]
+....
+{PlantUML diagram source here}
+....
+----
+
+Command syntax:
+
+[source,asciidoc]
+----
+plantuml_image::{path}[{image-attributes}]
+----
+
+Where,
+
+`{image-attributes}`:: Comma-separated list of AsciiDoc image attributes in
+`key=value` format.
+
+
+.Specifying image attributes in `[plantuml]` block
+[example]
+====
+[source,asciidoc]
+----
+[plantuml,id=my-diagram,title="My Sequence Diagram",width=600,height=400]
+....
+@startuml
+Alice -> Bob: Hello
+@enduml
+....
+----
+====
+
+
 === Filename specification
 
-Specify custom filenames within the PlantUML source:
+PlantUML supports specifying custom filenames for generated diagrams using the
+`@start{type} [filename]` directive, where `{type}` is the diagram type (e.g.,
+`uml`, `mindmap`, etc.) and `filename` is the desired name for the output
+file.
+
+This feature is not well documented in official PlantUML documentation, but is
+described at:
+
+* PlantUML Language Reference Guide, 4.7, where `@startuml PERT` is used
+* https://forum.plantuml.net/19896/name-conventions-for-%40startuml-filename[PlantUML Forum: Name conventions for @startuml filename]
+* https://forum.plantuml.net/5483/please-specify-filename-%40startuml-extension-automatically[PlantUML Forum: Please specify filename @startuml extension automatically]
+
+When a custom filename is specified, PlantUML generates the output file using
+the specified filename and the appropriate file extension based on the diagram
+type.
+
+This custom filename feature is supported in both block and command syntaxes.
+
+Syntax:
+
+[source,asciidoc]
+----
+[plantuml]
+....
+@startuml {custom-filename}
+{PlantUML diagram source here}
+@enduml
+....
+----
+
+Where,
 
+`{custom-filename}`:: Desired name for the generated diagram file, without
+file extension.
+
+.Specifying a custom filename in `[plantuml]` block
+[example]
+====
 [source,asciidoc]
 ----
 [plantuml]
 ....
-@startuml my-custom-name
+@startuml AliceToBob
 Alice -> Bob: Hello
 @enduml
 ....
 ----
 
-This generates `my-custom-name.png` (or specified format) instead of an
-auto-generated filename.
+This generates `AliceToBob.png` (which is the default format since none was
+specified) instead of an auto-generated filename. This file is then embedded in
+the output document using the specified filename.
+====
+
 
 
-=== Configuration options
+=== Disable PlantUML processing
 
-==== Disable PlantUML processing
+It is possible to disable PlantUML processing either document-wide or via an
+environment variable.
 
-Disable PlantUML processing document-wide:
+When disabled, PlantUML blocks are rendered as code listings instead of
+diagrams.
+
+The `:plantuml-disabled:` document attribute can be used to disable PlantUML
+processing for a specific document.
+
+Syntax:
 
 [source,asciidoc]
 ----
 :plantuml-disabled:
+----
 
+[example]
+====
+[source,asciidoc]
+----
 [plantuml]
 ....
 @startuml
@@ -244,22 +755,36 @@ Alice -> Bob: Hello
 ....
 ----
 
-When disabled, PlantUML blocks are rendered as code listings instead of diagrams.
+This renders the PlantUML block as a code listing instead of a diagram.
+====
 
-==== Environment variable
+The same effect can be achieved using by setting the `PLANTUML_DISABLED`
+environment variable to `true`.
 
-Disable PlantUML processing via environment variable:
+Syntax:
 
+[source,console]
+----
+$ PLANTUML_DISABLED=true metanorma ...
+----
+
+[example]
+====
 [source,console]
 ----
 $ PLANTUML_DISABLED=true metanorma document.adoc
 ----
+====
+
 
 === File organization
 
-Generated PlantUML images are stored in the `_plantuml_images/` directory
-relative to your document location. This directory is automatically created if
-it doesn't exist.
+Generated PlantUML images are stored in a `_plantuml_images/` directory
+relative to the document location (the document root, if it is made of multiple
+files).
+
+This directory is automatically created if it doesn't exist.
+
 
 == Development
 
@@ -270,20 +795,24 @@ Metanorma integration and PlantUML execution:
 
 [source]
 ----
-Metanorma Document
-      ↓
-BlockProcessor ← (processes [plantuml] blocks)
-      ↓
-Backend ← (Metanorma integration, paths, validation)
-      ↓
-Wrapper ← (Java/JAR execution, file I/O)
-      ↓
-PlantUML JAR ← (diagram generation)
+  Metanorma Document
+          ↓
+    BlockProcessor ← (processes `[plantuml]` blocks)
+and ImageBlockMacroProcessor ← (processes `plantuml_image::` commands)
+          ↓
+      Backend ← (Metanorma integration, paths, validation)
+          ↓
+      Wrapper ← (Java/JAR execution, file I/O)
+          ↓
+    PlantUML JAR ← (diagram generation)
 ----
 
 `BlockProcessor`:: Processes `[plantuml]` blocks in Metanorma documents and
 integrates with the Metanorma rendering pipeline.
 
+`ImageBlockMacroProcessor`:: Processes `plantuml_image::{path}[{options}]` commands
+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/lib/metanorma/plugin/plantuml/backend.rb

@@ -14,19 +14,21 @@ 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) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          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)
@@ -43,6 +45,7 @@ module Metanorma
               plantuml_content,
               format: fmt,
               output_file: output_file,
+              includedirs: options[:includedirs],
             )
 
             unless result[:success]
@@ -52,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
@@ -72,8 +77,9 @@ 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
 
@@ -100,8 +106,15 @@ module Metanorma
             ]
           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)

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

@@ -1,29 +1,16 @@
 # frozen_string_literal: true
 
-require "asciidoctor"
-require "asciidoctor/extensions"
-require_relative "backend"
-
 module Metanorma
   module Plugin
     module Plantuml
-      # PlantUML block processor for Asciidoctor
+      # PlantUML block processor
       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) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           # Check for document-level disable flag
           if parent.document.attr("plantuml-disabled")
@@ -37,45 +24,24 @@ 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
-          else
-            # Multiple formats - generate multiple files
-            through_attrs = Backend
-              .generate_multiple_files(parent, reader, formats, attrs)
-          end
-          create_image_block parent, through_attrs
+          process_image_block(parent, reader, attrs, formats, options)
         rescue StandardError => e
           abort(parent, reader, attrs, e.message)
         end
 
         private
 
-        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
+        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] = add_attrs_to_includedirs(
+            parent.document, attrs, parse_doc_includedirs(parent.document)
+          )
 
-        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/image_block_macro_processor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Plugin
+    module Plantuml
+      # PlantUML block processor
+      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/version.rb

@@ -1,7 +1,7 @@
 module Metanorma
   module Plugin
     module Plantuml
-      VERSION = "1.0.1".freeze
+      VERSION = "1.0.3".freeze
       PLANTUML_JAR_VERSION = "1.2025.4".freeze
     end
   end

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

@@ -32,7 +32,7 @@ module Metanorma
             options
           end
 
-          def generate( # rubocop:disable Metrics/MethodLength
+          def generate( # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             content,
             format: DEFAULT_FORMAT,
             output_file: nil,
@@ -42,6 +42,9 @@ module Metanorma
             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
@@ -55,6 +58,24 @@ module Metanorma
             { success: false, error: e }
           end
 
+          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
@@ -169,47 +190,85 @@ module Metanorma
           end
 
           def execute_plantuml(content, format, output_file, options) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
-            Tempfile.create(["plantuml_input", ".puml"]) do |input_file| # rubocop:disable Metrics/BlockLength
-              input_file.write(content)
-              input_file.close
-
-              # 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
-                cmd = build_command(input_file.path, 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)
+            # 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
+
+              # 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
 
-                # 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)
+                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
+
+                  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))
+
+                    File.open(temp_include_file, "w") do |f|
+                      f.write(File.read(found_include_file))
+                    end
                   end
                 end
+              end
+
+              cmd = build_command(
+                "#{temp_dir}/plantuml_input.puml",
+                format,
+                temp_dir,
+                options,
+              )
 
-                output
+              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
 

data/lib/metanorma-plugin-plantuml.rb

@@ -11,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.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-28 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