I would like to insert/embed an image from my local file system into a RhodeCode pull request comment (to aid in providing code feedback). RhodeCode uses a markup syntax/parser called reStructuredText for its comments, which bears some resemblance to Markdown (i.e. both would italicize a word by wrapping it with asterisks). This is the documentation on inserting images using reStructuredText.

I've been able to insert an image from the web using

.. image::  

with success. This presents as the image being displayed in the pull request comment.

Using the documentation I tried .. image:: C:\image.png as well as

.. image:: C:\image.png
   :loading: embed

I also tried wrapping the absolute path to the image in quotation marks and single quotes to no avail. The image failing to embed presents as an empty comment block. The loading and target image options seem to be pertinent to this goal, however the latter seems to be more centric to hyperlinks. Does anyone have any insight into whether this is possible from the local file system or am I limited to having to upload the desired image to a website and then embedding it using the hyperlink?

I would like to insert/embed an image from my local file system into a RhodeCode pull request comment (to aid in providing code feedback). RhodeCode uses a markup syntax/parser called reStructuredText for its comments, which bears some resemblance to Markdown (i.e. both would italicize a word by wrapping it with asterisks). This is the documentation on inserting images using reStructuredText.

I've been able to insert an image from the web using

.. image:: https://www.website/pathToImage 

with success. This presents as the image being displayed in the pull request comment.

Using the documentation I tried .. image:: C:\image.png as well as

.. image:: C:\image.png
   :loading: embed

I also tried wrapping the absolute path to the image in quotation marks and single quotes to no avail. The image failing to embed presents as an empty comment block. The loading and target image options seem to be pertinent to this goal, however the latter seems to be more centric to hyperlinks. Does anyone have any insight into whether this is possible from the local file system or am I limited to having to upload the desired image to a website and then embedding it using the hyperlink?

• image
• restructuredtext
• rhodecode

1 Answer 1

The "image" directive expects the location of the image file as URI. It also accepts a URI-reference -- you may provide "relative" URIs (relative to the base URI of the document), this means you may also leave out the "scheme" part of the URI and provide an absolute or relative POSIX path (with forward slashes). However, there is one caveat: with DOS/windows path syntax, the drive letter may be confused with an URI scheme, so C:/images/my-image.png would be interpreted as /images/my-image.png under the non-existent scheme C.

You may try with file:c:/image.png or /image.png. The "file" scheme is only suited for embedding images or local use. Leave the scheme part for documents intended to be served over the net (make sure to use an URI-reference that works from the location of the generated HTML).

There are some caveats:

Consider when and where the conversion from rST to HTML takes place and where the generated HTML is viewed from. If everything happens on the same local machine, a local file path should work. If the conversion runs on a different machine, it will not be able to access C:\images to embed the image file. If someone looks at the generated HTML via a http(s) connection, an image URI C:/images/image.png, say, would refer to an image file on their machine.

Embedding images in the HTML requires local access at the time of conversion. It is a relatively new feature and may not be supported by RhodeCode.

Docutils (the python package providing a parser and converter for reStructuredText for, e.g. Sphinx-doc and as a standalone application) fixed some issues with image URI handling in the development version. There may be some issues, if RhodeCode uses an older version of the package.

RhodeCode may also be using an alternative reStructuredText parer (pandoc, Text::Restructured, ...) with their own limitations or blocking access of the local file system.

In addition to uploading the image to some accessible URI, it should also be possible (in principle) to convert the image to a data-URI and paste this data-URI into the reStructuredText document. For simple schemata, using a literal block with ASCII art might be a pragmatic workaround.