diff --git a/docs/config.rst b/docs/config.rst
index dc21610..a929d2d 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -50,6 +50,19 @@ img_dir
For reading image file command (e.g. png and svg), read from this directory instead
+img_missing:
+ default: ``:warn``
+
+ Log a warning if an image file is missing. This option is only consulted if the following are true:
+
+ * If the ``file`` specified for an input image (e.g. :doc:`/dsl/png` or :doc:`/dsl/svg`) does not exist,
+ * AND a ``placeholder`` image does not exist
+
+ Other options:
+ * ``error`` - raise a ``RuntimeError`` and halt the entire build.
+ * ``silent`` - do nothing, log nothing, and act as if the ``file`` was ``nil``
+
+
warn_ellipsize
default: true
diff --git a/docs/dsl/png.rst b/docs/dsl/png.rst
index ece1bee..ed26d67 100644
--- a/docs/dsl/png.rst
+++ b/docs/dsl/png.rst
@@ -33,13 +33,24 @@ blend
default: ``:none``
the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators.
- The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
+ The possibilties include: :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
mask
default: ``nil``
Accepts a color (see :doc:`/colors`). If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.
+placeholder
+ default: ``nil``
+
+ if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+ No warning is thrown when a placeholder is used.
+
+ If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
+
+ Examples of how to use placeholders are below.
+
.. include:: /args/transform.rst
.. include:: /args/range.rst
@@ -47,3 +58,27 @@ mask
Examples
--------
+
+These examples live here: https://github.com/andymeneely/squib/tree/dev/samples/images
+
+.. literalinclude:: ../../samples/images/_images.rb
+ :linenos:
+
+.. raw:: html
+
+ 
+
+.. literalinclude:: ../../samples/images/_placeholders.rb
+ :linenos:
+
+First placeholder expected output.
+
+.. raw:: html
+
+ 
+
+Second placeholder expected output.
+
+.. raw:: html
+
+ 
\ No newline at end of file
diff --git a/docs/dsl/svg.rst b/docs/dsl/svg.rst
index a4ab9a4..f206058 100644
--- a/docs/dsl/svg.rst
+++ b/docs/dsl/svg.rst
@@ -17,6 +17,8 @@ file
file(s) to read in. As in :doc:`/arrays`, if this a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. If any of them are nil or '', nothing is done for that card.
+ By default, if ``file`` is not found, a warning is logged. This behavior can be configured in :doc:`/config`
+
.. include:: /args/xy.rst
data
@@ -65,6 +67,16 @@ mask
For implementation reasons, your vector image will be rasterized when mask is applied. If you use this with, say, PDF, the images will be embedded as rasters, not vectors.
+placeholder
+ default: ``nil``
+
+ if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+ No warning is thrown when a placeholder is used.
+
+ If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
+
+ Examples of how to use placeholders are below.
crop_x
default: ``0``
@@ -117,3 +129,27 @@ flip_vertical
Examples
--------
+
+These examples live here: https://github.com/andymeneely/squib/tree/dev/samples/images
+
+.. literalinclude:: ../../samples/images/_images.rb
+ :linenos:
+
+.. raw:: html
+
+
+
+.. literalinclude:: ../../samples/images/_placeholders.rb
+ :linenos:
+
+First placeholder expected output.
+
+.. raw:: html
+
+
+
+Second placeholder expected output.
+
+.. raw:: html
+
+
\ No newline at end of file
diff --git a/docs/dsl/text.rst b/docs/dsl/text.rst
index 241e972..83aa293 100644
--- a/docs/dsl/text.rst
+++ b/docs/dsl/text.rst
@@ -278,6 +278,14 @@ blend
the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators.
The possibilties include :none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity. String versions of these options are accepted too.
+placeholder
+ default: ``nil``
+
+ if ``file`` does not exist, but the file pointed to by this string does, then draw this image instead.
+
+ No warning is thrown when a placeholder is used.
+
+ If this is non-nil, but the placeholder file does not exist, then a warning is thrown and no image is drawn.
mask
default: ``nil``
diff --git a/samples/images/.gitignore b/samples/images/.gitignore
index e87ecce..432eb21 100644
--- a/samples/images/.gitignore
+++ b/samples/images/.gitignore
@@ -1,8 +1,8 @@
-*.png
+!*_expected.png
!ball.png
!grit.png
!sprites.png
!with-alpha.png
-!_images_00_expected.png
!shiny-purse.png
!angler-fish.png
+*.png
diff --git a/samples/images/_placeholders.rb b/samples/images/_placeholders.rb
index 99c90d7..10d1f5c 100644
--- a/samples/images/_placeholders.rb
+++ b/samples/images/_placeholders.rb
@@ -24,6 +24,12 @@ Squib::Deck.new(width: 100, height: 100, cards: 4) do
files = %w(angler-fish.png does-not-exist.png does-not-exist.png does-not-exist.png)
placeholders = %w(grit.png does-not-exist.png grit.png )
png file: files, placeholder: placeholders
+
+ # text embeds can have placeholders too
+ text(str: 'A', color: :red) do |embed|
+ embed.png key: 'A', file: files, placeholder: placeholders, width: 30, height: 30
+ end
+
save_sheet columns: 1, prefix: 'multi_placeholder_sheet_'
end