Skip to content

Problems linking to images #1134

Closed
@colleenmcginnis

Description

@colleenmcginnis

Describe the bug

I'm not sure if this is a bug or not, but when using absolute links to reference images in the style of absolute links used for internal links, the final URL that ends up in the HTML doesn't take the path_prefix into consideration.

Also, the plain Markdown syntax for images seems to behave differently than the custom directive (:::{image}).

I tried three different URL formats with both the plain Markdown syntax and the custom directive: relative links, absolute links based on file path, and absolute links based on the final URL path. Here are the results:

Relative link

Syntax

<!-- Plain markdown -->
![Buildkite pipeline view showing a few test failures](images/settings-read-only-badge.png)

<!-- Custom directive -->
:::{image} images/settings-read-only-badge.png
:alt: Buildkite pipeline view showing a few test failures
:::

Rendered result

Image

Logs

No warnings/errors.

Absolute link (file-based)

Syntax

<!-- Plain markdown -->
![Buildkite pipeline view showing a few test failures](/reference/images/settings-read-only-badge.png)

<!-- Custom directive -->
:::{image} /reference/images/settings-read-only-badge.png
:alt: Buildkite pipeline view showing a few test failures
:::

Rendered result

Image

Logs

No warnings/errors.

Absolute link (url-based)

Syntax

<!-- Plain markdown -->
![Buildkite pipeline view showing a few test failures](/reference/kibana/images/settings-read-only-badge.png)

<!-- Custom directive -->
:::{image} /reference/kibana/images/settings-read-only-badge.png
:alt: Buildkite pipeline view showing a few test failures
:::

Rendered result

Image

Logs

Error: `/reference/kibana/images/settings-read-only-badge.png` does not exist. resolved to `/GitHub/docs-builder/.artifacts/checkouts/next/kibana/docs/reference/kibana/images/settings-read-only-badge.png
    ┌─[/GitHub/docs-builder/.artifacts/checkouts/next/kibana/docs/reference/index.md]
    │
    │
    └─
 
Error: `/reference/kibana/images/settings-read-only-badge.png` does not exist. resolved to `/GitHub/docs-builder/.artifacts/checkouts/next/kibana/docs/reference/kibana/images/settings-read-only-badge.png
    ┌─[/GitHub/docs-builder/.artifacts/checkouts/next/kibana/docs/reference/index.md]
    │
 38 │ ![Buildkite pipeline view showing a few test failures](/reference/kibana/images/settings-read-only-badge.png)
    · ─────────────────────────────────────────────────────                                                        
    ·                                                                                                               
    │
    └─

Expected behavior

I would expect:

  • Plain Markdown and custom directive to behave the same with regard to image links.
  • To be able to use the same pattern used for internal absolute links for image links.

Steps to reproduce

  1. Build docs-builder and docs-assembler locally.
  2. Clone all repos.
  3. Manually edit .artifacts/checkouts/next/kibana/docs/reference/index.md to add:
    ## Relative link
    
    ![Buildkite pipeline view showing a few test failures](images/settings-read-only-badge.png)
    
    :::{image} images/settings-read-only-badge.png
    :alt: Buildkite pipeline view showing a few test failures
    :::
    
    ## Absolute link (file-based)
    
    ![Buildkite pipeline view showing a few test failures](/reference/images/settings-read-only-badge.png)
    
    :::{image} /reference/images/settings-read-only-badge.png
    :alt: Buildkite pipeline view showing a few test failures
    :::
    
    ## Absolute link (url-based)
    
    ![Buildkite pipeline view showing a few test failures](/reference/kibana/images/settings-read-only-badge.png)
    
    :::{image} /reference/kibana/images/settings-read-only-badge.png
    :alt: Buildkite pipeline view showing a few test failures
    :::
  4. Build all.
  5. Run the site locally and open in a browser.

Tooling

  • docs-builder
  • migration tooling
  • I'm not sure

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions