7 files changed, 21 insertions, 5 deletions
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 3f157a95..c9625afd 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -11,6 +11,7 @@ Enhancements::
 
 * allow page background image to be specified per layout using `+{page-layout}+` attribute reference in path (#1739)
 * allow page margin for rotated page to be configured independently using `page-margin-rotated` theme key or `pdf-page-margin-rotated` document attribute (#1719)
+* set `docimagesdir` attribute when attribute substitutions are applied to value from theme (#2278)
 * start page numbering and running content on empty verso page before first chapter of prepress book if `start-at` value is 0 (#2252)
 * don't force page break after TOC with automatic placement in article if `title-page` attribute is set and value of `toc-break-after` theme key is `auto` (#1768)
 * add `--theme` option to CLI as shorthand for `-a pdf-theme` (#2250)
diff --git a/docs/modules/theme/pages/apply-theme.adoc b/docs/modules/theme/pages/apply-theme.adoc
index 2cdb4fab..967ea94c 100644
--- a/docs/modules/theme/pages/apply-theme.adoc
+++ b/docs/modules/theme/pages/apply-theme.adoc
@@ -66,7 +66,7 @@ For now, it's recommended that you specify absolute paths to future-proof your c
 
  $ asciidoctor-pdf --theme /path/to/resources/themes/basic-theme.yml -a pdf-fontsdir=/path/to/resources/fonts doc.adoc
 
-Alternately, you can prefix image paths in the theme using the `+{docdir}+` attribute reference.
+Alternately, you can prefix image paths in the theme using the `+{docdir}+` or `+{docimagesdir}+` attribute references.
 
 == Using Maven and Gradle
 
diff --git a/docs/modules/theme/pages/images.adoc b/docs/modules/theme/pages/images.adoc
index 2dec6a08..6c4fecad 100644
--- a/docs/modules/theme/pages/images.adoc
+++ b/docs/modules/theme/pages/images.adoc
@@ -48,12 +48,12 @@ title-page:
 
 The target of the inline image macro can be a path relative to the `pdf-themesdir` attribute (default), an absolute path, or a data URI.
 If `pdf-theme` is a path that ends in `.yml`, and `pdf-themesdir` is not set, then the images are resolved relative to the directory of the path specified by `pdf-theme`.
-If you want to reference an image relative to the document you're converting, then prefix the target with the `\{docdir}` attribute reference.
+If you want to reference an image relative to the document you're converting, then prefix the target with the `\{docdir}` or `\{docimagesdir}` attribute references, which both resolve to an absolute path.
 
 [,yaml]
 ----
 title-page:
-  background-image: image:{docdir}/images/title-cover.png[]
+  background-image: image:{docimagesdir}/title-cover.png[]
 ----
 
 === Per page layout
diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb
index 42e9e774..a7b1c232 100644
--- a/lib/asciidoctor/pdf/converter.rb
+++ b/lib/asciidoctor/pdf/converter.rb
@@ -2770,6 +2770,7 @@ module Asciidoctor
         if (imagesdir = opts[:imagesdir])
           imagesdir_to_restore = doc.attr 'imagesdir'
           doc.set_attr 'imagesdir', imagesdir
+          remove_docimagesdir = doc.set_attr 'docimagesdir', (::File.absolute_path imagesdir_to_restore.to_s, (doc.attr 'docdir', '')), false
         end
         if (page_layout = opts[:page_layout])
           page_layout_to_restore = doc.attr 'page-layout'
@@ -2783,7 +2784,10 @@ module Asciidoctor
         value = value.gsub '\{', '{' if escaped_attr_ref
         doc.set_attr 'attribute-missing', attribute_missing unless attribute_missing == 'skip'
         page_layout_to_restore ? (doc.set_attr 'page-layout', page_layout_to_restore) : (doc.remove_attr 'page-layout') if page_layout
-        imagesdir_to_restore ? (doc.set_attr 'imagesdir', imagesdir_to_restore) : (doc.remove_attr 'imagesdir') if imagesdir
+        if imagesdir
+          imagesdir_to_restore ? (doc.set_attr 'imagesdir', imagesdir_to_restore) : (doc.remove_attr 'imagesdir')
+          doc.remove_attr 'docimagesdir' if remove_docimagesdir
+        end
         value
       end
 
diff --git a/spec/fixtures/images/tux.png b/spec/fixtures/images/tux.png
new file mode 100644
index 00000000..d846bf2d
--- /dev/null
+++ b/spec/fixtures/images/tux.png
diff --git a/spec/page_spec.rb b/spec/page_spec.rb
index 53da7c9f..2d3e70bf 100644
--- a/spec/page_spec.rb
+++ b/spec/page_spec.rb
@@ -1096,7 +1096,7 @@ describe 'Asciidoctor::PDF::Converter - Page' do
       (expect to_file).to visually_match 'page-background-color-and-image.pdf'
     end
 
-    it 'should resolve attribute reference in image path in theme', visual: true do
+    it 'should resolve docdir attribute reference in image path in theme', visual: true do
       pdf_theme = {
         page_background_color: 'F9F9F9',
         page_background_image: 'image:{docdir}/tux.png[fit=none,pdfwidth=50%]',
@@ -1106,6 +1106,16 @@ describe 'Asciidoctor::PDF::Converter - Page' do
       (expect to_file).to visually_match 'page-background-color-and-image.pdf'
     end
 
+    it 'should resolve docimagesdir attribute reference in image path in theme', visual: true do
+      pdf_theme = {
+        page_background_color: 'F9F9F9',
+        page_background_image: 'image:{docimagesdir}/tux.png[fit=none,pdfwidth=50%]',
+      }
+      to_file = to_pdf_file '{blank}', 'page-background-color-and-image-relative-to-docdir.pdf', pdf_theme: pdf_theme, attribute_overrides: { 'docdir' => fixtures_dir, 'imagesdir' => 'images' }
+
+      (expect to_file).to visually_match 'page-background-color-and-image.pdf'
+    end
+
     it 'should only substitute attributes in image path in theme', visual: true do
       pdf_theme = {
         page_background_color: 'F9F9F9',
diff --git a/spec/running_content_spec.rb b/spec/running_content_spec.rb
index c39ac540..32c06dc1 100644
--- a/spec/running_content_spec.rb
+++ b/spec/running_content_spec.rb
@@ -3193,6 +3193,7 @@ describe 'Asciidoctor::PDF::Converter - Running Content' do
 
       doc = to_pdf 'body', pdf_theme: pdf_theme, enable_footer: true, to_file: (pdf_io = StringIO.new), attributes: {}, analyze: :document
       (expect doc.attr? 'imagesdir').to be_falsy
+      (expect doc.attr? 'docimagesdir').to be_falsy
       pdf = PDF::Reader.new pdf_io
       (expect (pdf.page 1).text).to include fixtures_dir
     end