Skip to content

Update images.md #1090

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Update images.md #1090

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f6a127b
Update images.md
lcawl Apr 10, 2025
08f1e69
Update docs/syntax/images.md
lcawl Apr 11, 2025
1e77312
Update docs/syntax/images.md
lcawl Apr 11, 2025
077c0d2
Update docs/syntax/images.md
lcawl Apr 11, 2025
836ed29
Update docs/syntax/images.md
lcawl Apr 11, 2025
b31cd8e
Update docs/syntax/images.md
lcawl Apr 12, 2025
ff5db98
Update docs/syntax/images.md
lcawl Apr 12, 2025
52187a3
Update docs/syntax/images.md
lcawl Apr 12, 2025
8b57322
Update docs/syntax/images.md
lcawl Apr 12, 2025
80e15f2
Update docs/syntax/images.md
lcawl Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 27 additions & 22 deletions docs/syntax/images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It can be a relative path but it can not go relative beyond the toc.

e.g

/images/
  - other.png
/solutions/
   /images/
      - observability-apm-app-landing.png`
   /page/
      - index.md
   toc.yml

../images/observability-apm-app-landing.png from index.md is fine because that lives in the same subtree as the toc.yml the page lives in.

../../images/other.png lives outside the toc.yml subtree so is at risk of being broken if the assembler rehomes this subtree.

`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, i've taken another go at the explanation since i think this might confuse folks

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
:::
Expand All @@ -33,36 +38,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
Expand All @@ -73,35 +78,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
Expand All @@ -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[]
```
```
Loading