Search code examples
pythongithubrestructuredtextpypi

How do you link to images from your docs folder in your README.rst?

I'm struggling to find a way to use images in my README.rst that will show up both on github and PyPI.

Currently I'm using the following markup:

.. image:: https://github.com/thebjorn/pydeps/blob/master/docs/_static/pydeps.svg

which looks great on github (https://github.com/thebjorn/pydeps), but show up as broken links on PyPI (https://pypi.org/project/pydeps/1.6.0/).

Is this possible, or do I need to host these images somewhere else?

Solution

  • You need to use raw.githubusercontent.com instead of github.com:

    .. image:: https://github.com/thebjorn/pydeps/blob/master/docs/_static/pydeps-pylib.svg

    will render correctly only on Github itself, while

    .. image:: https://raw.githubusercontent.com/thebjorn/pydeps/master/docs/_static/pydeps-pylib.svg?sanitize=true

    will render on any website.

    First attempt (broken & removed)

    Second attempt:

    1. replaces the URLs correctly (also removing the blob part in paths - my bad!),
    2. appends ?sanitize=true to each URL being replaced.
    $ sed -i '' 's,.. image:: https://github.com/\(.*\)/blob/\(.*\).svg,.. image:: https://raw.githubusercontent.com/\1/\2.svg?sanitize=true,g' README.rst

    Testing it on Github and on TestPyPI, both looking good.

    Alternative: Using RawGit

    Another possibility would be using RawGit, although the downside is this being a third-party service, so when it's down, the images are not rendered, although available. Nevertheless, for completeness:

    $ sed -i '' 's,.. image:: https://github.com/\(.*\)/blob/\(.*\)$,.. image:: https://cdn.rawgit.com/\1/\2,g' README.rst