Absolute vs. relative image references in markdown files

[samajammin]

Hey folks! I'm curious if there's any recommendations/best practices around re-using images across markdown files.

The problem:

Currently our codebase stores images related to a markdown file within the directory of the file.

Here's an example of our file structure:

src
├── content
│   ├── about
│   └── developers
|   │   └── tutorials
│   │   │   └── erc20-annotated-code
│   │   │   │   └── index.md
│   │   │   │   └── erc20_interface.png

Then from within the markdown file (index.md), we reference images with a relative path, e.g.

![Illustration of the ERC-20 interface](./erc20_interface.png)

This works perfectly but has gotten complicated once we've added translations of files, in which we mirror the file structure of our English files but nested deeper within our file structure (under a /translations/ directory):

src
├── content
│   ├── about
│   └── developers
|   │   └── tutorials
│   │   │   └── erc20-annotated-code
│   │   │   │   └── index.md
│   │   │   │   └── erc20_interface.png
│   └── translations
|   │   └── es
│   │   │   └── developers
│   │   │   │   └── tutorials
│   │   │   │   │   └── erc20-annotated-code
│   │   │   │   │   │   └── index.md
|   │   └── de
│   │   │   └── developers
│   │   │   │   └── tutorials
│   │   │   │   │   └── erc20-annotated-code
│   │   │   │   │   │   └── index.md

Currently this forces us to update the relative paths to our image files, so e.g. from src/content/translations/es/developers/tutorials/erc20-annotated-code/index.md we have to update the image reference from

![Illustration of the ERC-20 interface](./erc20_interface.png)

to

![Illustration of the ERC-20 interface](../../../../../developers/tutorials/erc20-annotated-code/erc20_interface.png)

Ideal situation for us would be to 1) not have to alter our image references at all & 2) not have to copy images into the translation directories. Is there a recommended approach here?

e.g. is there a way to update all markdown images to reference an absolute vs. relative path? So we could do something like:

![Illustration of the ERC-20 interface](/static/tutorials/erc20_interface.png)

Other avenues we're considering:

1. A script to somehow automatically update the relative paths of image references

2. Re-organizing our translated files to live within the same file structure, e.g.

src
├── content
│   ├── about
│   └── developers
|   │   └── tutorials
│   │   │   └── erc20-annotated-code
│   │   │   │   └── en.md
│   │   │   │   └── es.md
│   │   │   │   └── de.md
│   │   │   │   └── erc20_interface.png

This would require some significant refactoring of other code elsewhere tho 😕

Thanks in advance for your input!

[LekoArts]

Do you use / want to use gatsby-remark-images?

[samajammin]

Hey @LekoArts - thanks for the question! Yes, I should have clarified. We are using gatsby-remark-images. You can view our full config here: https://github.com/ethereum/ethereum-org-website/blob/dev/gatsby-config.js#L137

[LekoArts]

As you can't rewrite the file paths and also can't place it into the static folder as you want to use gatsby-remark-images I guess rethinking the structure is the best option here.

You'll also need to consider that your translations might need different images than the original one, you won't always use the same one. Depending on your requirements having all markdown files in the same folder might be the best option, or each md file and any additional images in their own folder.