How to add images to the README#

The contents of the README.md file may be presented in various places:

  • Project homepage on GitHub

  • Project documentation (if using Sphinx build)

  • PyPI (if publishing there)

This places some limitations on including relative content as PyPI is only provided with the content directly in README.md and not the surrounding resources.

Additionally the Sphinx build uses the docs directory as the root of the build meaning that included content is relative to that path.

A reference link in Markdown syntax can be used to allow images to be included such that a fixed image URL is used in the README.md itself which can be overridden to a relative URL for the Sphinx build. This satisfies the three use cases above.

Example of Markdown reference link:

![Image alt text][reference]

with the reference defined (potentially elsewhere) as:

[reference]: https://mydomain.com/myimage.png

Example: Image Reference#

This example shows how to include an image (local to the repository) in the README.md such that it will render in all three places mentioned above.

In the README.md a reference image link is placed at the location the image should be rendered:

![my example image][blueapi]

at the bottom of the README.md, link to a raw.githubusercontent.com URL. This is placed below a comment:

<!-- README only content. Anything below this line won't be included in index.md -->

[blueapi]: https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png

The absolute URL is used to allow PyPI to render the image. If PyPI is not required a relative URL can be used which will work for GitHub rendering.

The README.md content is included in the Sphinx build (for example index.md) but will stop when it reaches the comment:

```{include} ../README.md
:end-before: <!-- README only content
```

After this include block the reference can be redefined to point to the local image, relative to the root of the Spinx build:

[blueapi]: images/blueapi.png

This ensures that a frozen version of the image at the time the docs are built is used for the documentation rather than an image on a branch.

Note that if using a raw.githubusercontent.com URL pointing to an image on a branch, e.g:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png

it is possible that the image will be removed or change over time. This would affect the content displayed on PyPI, even for releases already made.

To mitigate this it may be desired to point to fixed versions of such assets, via a commit hash or a tag URL. For example an image at a specific tag:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/0.4.0/docs/images/blueapi.png

or an image at a specific commit:

https://raw.githubusercontent.com/DiamondLightSource/blueapi/7bbc94e0d61da2a4ce4de6a1285c4cc0e4ba67f2/docs/images/blueapi.png

This may incur a prohibitive maintenance cost, in constantly updating references when releases are made, so use of these fixed images is left as a per-project decision.