From f6a127b14459f6a32f4eeecbd3791756eea0bfa6 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 10 Apr 2025 15:05:12 -0700 Subject: [PATCH 01/10] Update images.md Relates to https://github.com/elastic/docs-content/issues/1079 --- docs/syntax/images.md | 49 ++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index 6a9346592..a996bddb6 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -1,29 +1,34 @@ # 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. image paths must be specified as absolute paths -Images can be referenced from the top-level `_static` dir or a local image dir. +:::{note} +If you reference an image using a relative path, it must be relative to the `toc.yml` or `docset.yml` rather than relative to the page that uses it. +This typically fails to render when you run a local build, thus it's preferrable to use an absolute path, for example: `/solutions/images/observability-apm-app-landing.png`. +::: ## 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,22 +38,22 @@ 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 @@ -56,13 +61,13 @@ Here is the same image used inline ![Elasticsearch](img/observability.png "elast 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,8 +78,8 @@ 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. @@ -82,9 +87,9 @@ and previewers. 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%") ``` @@ -92,16 +97,16 @@ If `H` is omitted `W` is used as the height as well. ### 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 +118,4 @@ image::images/metrics-alert-filters-and-group.png[Metric threshold filter and gr ```asciidoc image::images/synthetics-get-started-projects.png[] -``` \ No newline at end of file +``` From 08f1e69b02283a5f2d604f1e240b2578f78338a3 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 16:39:59 -0700 Subject: [PATCH 02/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index a996bddb6..2ea7b1123 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -4,7 +4,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is 1. instead of link text, you provide an image description 2. an image description starts with `![` not just `[` -3. image paths must be specified as absolute paths +3. there are restrictions on the scope of image paths :::{note} If you reference an image using a relative path, it must be relative to the `toc.yml` or `docset.yml` rather than relative to the page that uses it. From 1e7731216095dc9d691d9705899a012ea370d4d8 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 16:43:45 -0700 Subject: [PATCH 03/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index 2ea7b1123..b36331f3d 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -7,7 +7,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is 3. there are restrictions on the scope of image paths :::{note} -If you reference an image using a relative path, it must be relative to the `toc.yml` or `docset.yml` rather than relative to the page that uses it. +If a page uses a relative image path, it must be relative to the `toc.yml` or `docset.yml` that includes the page rather than relative to the page itself. This typically fails to render when you run a local build, thus it's preferrable to use an absolute path, for example: `/solutions/images/observability-apm-app-landing.png`. ::: From 077c0d27f0d0f0cf6278a2bbc595690a76086581 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 16:45:52 -0700 Subject: [PATCH 04/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index b36331f3d..da38ca800 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -8,7 +8,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is :::{note} If a page uses a relative image path, it must be relative to the `toc.yml` or `docset.yml` that includes the page rather than relative to the page itself. -This typically fails to render when you run a local build, thus it's preferrable to use an absolute path, for example: `/solutions/images/observability-apm-app-landing.png`. +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`. ::: ## Block-level images From 836ed296a13625771c0454cee1ca8008b6e53102 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 16:50:59 -0700 Subject: [PATCH 05/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index da38ca800..d4336bc5c 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -9,6 +9,8 @@ Images include screenshots, inline images, icons, and more. Syntax for images is :::{note} If a page uses a relative image path, it must be relative to the `toc.yml` or `docset.yml` that includes the page rather than relative to the page itself. 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`. + +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 From b31cd8efa06fd7d7fc1c8e6971707b2b59fdb952 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 17:47:07 -0700 Subject: [PATCH 06/10] Update docs/syntax/images.md --- docs/syntax/images.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index d4336bc5c..8ba263934 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -7,7 +7,6 @@ Images include screenshots, inline images, icons, and more. Syntax for images is 3. there are restrictions on the scope of image paths :::{note} -If a page uses a relative image path, it must be relative to the `toc.yml` or `docset.yml` that includes the page rather than relative to the page itself. 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`. 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. From ff5db98a5c824e0aa1c9a9979dc4fb5b93b25964 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 17:47:42 -0700 Subject: [PATCH 07/10] Update docs/syntax/images.md --- docs/syntax/images.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index 8ba263934..bd1c2fb9e 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -7,7 +7,6 @@ Images include screenshots, inline images, icons, and more. Syntax for images is 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`. 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. ::: From 52187a34f5f0a1a71125784b675aea23f48fc4dc Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 17:51:01 -0700 Subject: [PATCH 08/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index bd1c2fb9e..81b670869 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -8,7 +8,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is :::{note} -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. +When a page is referenced in a `toc.yml` file or a `docset.yml` file and you reference an image that exists outside the tree represented in that `.yml` file, it will fail to render and will generate warnings. ::: ## Block-level images From 8b573226b9216882af1c2d95f9a8124819c51274 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Fri, 11 Apr 2025 17:53:25 -0700 Subject: [PATCH 09/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index 81b670869..50de4d5da 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -8,7 +8,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is :::{note} -When a page is referenced in a `toc.yml` file or a `docset.yml` file and you reference an image that exists outside the tree represented in that `.yml` file, it will fail to render and will generate warnings. +If a page uses an image that exists outside the folder that contains the `toc.yml` file or `docset.yml` file that contains that page, the image will fail to render and will generate warnings. ::: ## Block-level images From 80e15f2b6865287bb422b457dfdbde05f28112bb Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 14 Apr 2025 07:57:40 -0700 Subject: [PATCH 10/10] Update docs/syntax/images.md --- docs/syntax/images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/images.md b/docs/syntax/images.md index 50de4d5da..3893ad4d4 100644 --- a/docs/syntax/images.md +++ b/docs/syntax/images.md @@ -8,7 +8,7 @@ Images include screenshots, inline images, icons, and more. Syntax for images is :::{note} -If a page uses an image that exists outside the folder that contains the `toc.yml` file or `docset.yml` file that contains that page, the image will fail to render and will generate warnings. +If a page uses an image that exists outside the folder that contains the `toc.yml` file or `docset.yml` file that contains that page, the image will fail to render and will generate warnings. Likewise, if a snippet in a [file inclusion](/syntax/file_inclusion.md) includes an image and is used in pages that exist in different `toc.yml`, the images will break. ::: ## Block-level images