Docutils: Does rst2html copy images?

Question

Does rst2html copy image directories and image paths?

I tried rst2odt and it copies the images. I failed to reach the same for rst2html.

It's crazy. It is a tool for documentation and yet I am searching for hours to find a definitive answer to such a central question.

Where do you expect them to be copied? rST documents don't include images, only links, so I wouldn't expect HTML documents to contain them either. — Nikolaj Š., May 18 '23 at 11:36
I wouldn't call _rst2html_ "a tool for documentation" either. It's a quick converter. For a full-fledged documentation tool, take a look at [Sphinx](https://www.sphinx-doc.org/en/master/) — Nikolaj Š., May 18 '23 at 11:38

score 0 · Answer 1 · answered Jul 24 '19 at 18:10

The reStructuredText markup language includes the image directive, as do documentation generators built on reStructuredText such as Sphinx. How the image is included in the output depends on the output format.

For example, the rst2odt program does not copy image directories or image paths, it copies the actual images into the ODT file. ODT files are just ZIP files with a particular structure, so you can unzip the ODT file and see the images in Pictures/.

By contrast, the rst2html program does not store images directly in the HTML file as this is not typical of HTML. Instead, it generates an img tag that points to the image. For example, this markup:

.. image:: example.png

will produce this HTML:

<img alt="example.png" src="example.png" />

The path example.png is an example of a path relative to the source file, but there are other options for img tags.

If you want to embed the images directly into the HTML file as e.g. data URLs, you will need to do something else, such as:

Manually convert the image to Base64, use it to make an HTML img tag with the data URL, and include it in the reStructuredText using the raw directive.

For example, this markup:

.. raw:: html

    <img alt="red square" src="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAQMAAABKLAcXAAAAA1BMVEX/AAAZ4gk3AAAAFElEQVQ4 y2NgGAWjYBSMglFATwAABXgAASlxufwAAAAASUVORK5CYII=" />

will produce this HTML:

<img alt="red square" src="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAQMAAABKLAcXAAAAA1BMVEX/AAAZ4gk3AAAAFElEQVQ4 y2NgGAWjYBSMglFATwAABXgAASlxufwAAAAASUVORK5CYII=" />

which will produce this image:

Use a tool such as SingleFile, inliner, or webpage2html to post-process the generated HTML.

Note there are limitations on data URLs, including browser-dependent size restrictions.

score 0 · Answer 2 · answered May 12 '23 at 11:03

Since Docutils 0.18, the "html5 writer" supports several ways of image handling.

You can embed images in the HTML output with rst2html5 --image-loading=embed INFILE > OUTFILE.html or set the "image-loading" option in a configuration file (cf. https://docutils.sourceforge.io/docs/user/config.html#image-loading)

Docutils: Does rst2html copy images?

2 Answers2