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.
Example: Logo#
A logo may also be added to the README.md
.
Given that the README.md
layout has not been drastically changed from the
template, the following HTML image style code may be placed at the very top of
README.md
:
<img src="https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi-logo.svg"
style="background: none" width="120px" height="120px" align="right">
The width and height may be adjusted to suit the particular project logo.