add extended converter example that looks for images in multiple dirs

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/pdf-converter-multiple-imagesdirs.rb b/docs/modules/extend/examples/pdf-converter-multiple-imagesdirs.rb
new file mode 100644
index 00000000..29747feb
--- /dev/null
+++ b/docs/modules/extend/examples/pdf-converter-multiple-imagesdirs.rb
@@ -0,0 +1,19 @@
+class PDFConverterMultipleImagesdirs < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def resolve_image_path node, image_path, image_format, relative_to = true
+    if relative_to == true
+      unless File.file? image_path
+        docdir = (doc = node.document).attr 'docdir'
+        %w(imagesdir imagesdir2).each do |attr_name|
+          imagesdir = (doc.attr attr_name) || ''
+          abs_imagesdir = File.absolute_path imagesdir, docdir
+          next unless File.file? (File.absolute_path image_path, abs_imagesdir)
+          relative_to = abs_imagesdir
+          break
+        end
+      end
+    end
+    super
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index ffcf19e2..19743373 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -255,6 +255,19 @@ image:
   indent: [0.5in, 0]
 ----
 
+== Look for images in multiple dirs
+
+By default, an AsciiDoc converter only supports resolving images from a single location, the value of the `imagesdir` attribute.
+You can use an extended converter to have Asciidoctor PDF look in multiple locations until it finds the image.
+
+.Extended converter that resolve images from multiple locations
+[,ruby]
+----
+include::example$pdf-converter-multiple-imagesdirs.rb[]
+----
+
+If you need the converter to support more than two locations, update the list of attribute names in the extended converter.
+
 == Language label on code block
 
 The built-in HTML converter inserts a source language label in the upper right corner of the code block, which appears on hover.