Update images.md

docs/syntax/images.md

@@ -1,29 +1,35 @@
 # Images
 
-Images include screenshots, inline images, icons, and more. Syntax for images is like the syntax for links, with two differences:
+Images include screenshots, inline images, icons, and more. Syntax for images is like the syntax for links, with the following differences:
+
 1. instead of link text, you provide an image description
 2. an image description starts with `![` not just `[`
+3. there are restrictions on the scope of image paths
+
+:::{note}
+This type of relative path may fail to render when you run a local build, thus it's generally preferable to use an absolute path, for example: `/solutions/images/observability-apm-app-landing.png`.
 
-Images can be referenced from the top-level `_static` dir or a local image dir.
+Irrespective of whether you use relative or absolute paths, if you reference an image that exists in a folder that is higher in the tree than the `toc.yml` file, it is at risk of being broken if the assembler rehomes this subtree and causes a warning in the build.
+:::
 
 ## Block-level images
 
 ```markdown
-![APM](img/apm.png)
+![APM](/syntax/img/apm.png)
 ```
 
-![APM](img/apm.png)
+![APM](/syntax/img/apm.png)
 
 Or, use the `image` directive.
 
 ```markdown
-:::{image} img/observability.png
+:::{image} /syntax/img/observability.png
 :alt: Elasticsearch
 :width: 250px
 :::
 ```
 
-:::{image} img/observability.png
+:::{image} /syntax/img/observability.png
 :alt: Elasticsearch
 :width: 250px
 :::
@@ -33,36 +39,36 @@ Or, use the `image` directive.
 Screenshots are images displayed with a box-shadow. Define a screenshot by adding the `:screenshot:` attribute to a block-level image directive.
 
 ```markdown
-:::{image} img/apm.png
+:::{image} /syntax/img/apm.png
 :screenshot:
 :::
 ```
 
-:::{image} img/apm.png
+:::{image} /syntax/img/apm.png
 :screenshot:
 :::
 
 ## Inline images
 
 ```markdown
-Here is the same image used inline ![Elasticsearch](img/observability.png "elasticsearch =50%x50%")
+Here is the same image used inline ![Elasticsearch](/syntax/img/observability.png "elasticsearch =50%x50%")
 ```
 
-Here is the same image used inline ![Elasticsearch](img/observability.png "elasticsearch =50%x50%")
+Here is the same image used inline ![Elasticsearch](/syntax/img/observability.png "elasticsearch =50%x50%")
 
 
 ### Inline image titles
 
 Titles are optional making this the minimal syntax required
 
 ```markdown
-![Elasticsearch](img/observability.png)
+![Elasticsearch](/syntax/img/observability.png)
 ```
 
 Including a title can be done by supplying it as an optional argument.
 
 ```markdown
-![Elasticsearch](img/observability.png "elasticsearch")
+![Elasticsearch](/syntax/img/observability.png "elasticsearch")
 ```
 
 ### Inline image sizing
@@ -73,35 +79,35 @@ This is done to maintain maximum compatibility with markdown parsers
 and previewers. 
 
 ```markdown
-![alt](img.png "title =WxH")
-![alt](img.png "title =W")
+![alt](/syntax/img/apm.png "title =WxH")
+![alt](/syntax/img/apm.png "title =W")
 ```
 
 `W` and `H` can be either an absolute number in pixels or a number followed by `%` to indicate relative sizing.
 
 If `H` is omitted `W` is used as the height as well.
 
 ```markdown
-![alt](img.png "title =250x330")
-![alt](img.png "title =50%x40%")
-![alt](img.png "title =50%")
+![alt](/syntax/img/apm.png "title =250x330")
+![alt](/syntax/img/apm.png "title =50%x40%")
+![alt](/syntax/img/apm.png "title =50%")
 ```
 
 
 
 ### SVG 
 
 ```markdown
-![Elasticsearch](img/alerts.svg)
+![Elasticsearch](/syntax/img/alerts.svg)
 ```
-![Elasticsearch](img/alerts.svg)
+![Elasticsearch](/syntax/img/alerts.svg)
 
 ### GIF
 
 ```markdown
-![Elasticsearch](img/timeslider.gif)
+![Elasticsearch](/syntax/img/timeslider.gif)
 ```
-![Elasticsearch](img/timeslider.gif)
+![Elasticsearch](/syntax/img/timeslider.gif)
 
 
 ## Asciidoc syntax
@@ -113,4 +119,4 @@ image::images/metrics-alert-filters-and-group.png[Metric threshold filter and gr
 
 ```asciidoc
 image::images/synthetics-get-started-projects.png[]
-```
+```