Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions source/guides/making-a-pypi-friendly-readme.rst
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,41 @@ provide both the file path and content type explicitly:
The referenced README should remain in the project source tree so the build
backend can read it when producing package metadata.


Adding images
-------------

To display an image in your project's description on PyPI, use a publicly
accessible HTTPS URL pointing directly to the image. For an image hosted in a
source repository, use the raw file URL rather than the repository's page for
the file.

.. tab:: Markdown

In :file:`README.md`, use Markdown image syntax:

.. code-block:: markdown

![Screenshot of the application](https://example.com/screenshot.png)

.. tab:: reStructuredText

In :file:`README.rst`, use the reStructuredText ``image`` directive:

.. code-block:: rst

.. image:: https://example.com/screenshot.png
:alt: Screenshot of the application

Relative paths such as ``docs/screenshot.png`` may work on your repository's
website, but will not work on PyPI. PyPI does not serve image files from your
uploaded source distribution or wheel for use in the project description.

The same approach works for logos, badges, and animated GIFs. ``data:`` URLs and
embedded video players are not supported; link to externally hosted videos
instead.


Validating reStructuredText markup
----------------------------------

Expand Down
Loading