#image #rustdoc #documentation #base64 #img

build docima

Generate images at build time & embed them in the Rust documentation

7 releases (breaking)

0.9.1 Aug 22, 2021
0.8.1-builddep Aug 22, 2021

#194 in Build Utils

24 downloads per month
Used in docima


388 lines


Generate images at build time for embedding in the Rust documentation.

Crate API Lines Of Code


The current API is going to evolve a lot while the major version number is 0.


  1. First configure your build script to generate the images in the desired path. They will be encoded as pngbase64 and saved as HTML tags. E.g.:
    .attr("title", "My image")
    .attr("id", "image-01")
    .attr("style", "display: block; margin:auto;")
    .wrapper_attr("style", "background-color:red; padding:3px;")
  1. Include your image in the Rust documentation by using the doc attribute and the include_str macro.
#[doc = include_str!("../images/my_image.html") ]
  1. Generate the docs:
cargo doc --open


There are several features that allows to customize the defaults.


By default all images will always be generated even when the target file already exists. By using this feature you can avoid generation in case the file exists.

Note that you can always override the default by using the overwrite method.


By enabling this feature images will only be generated when the following doc feature is also used.

This can be very useful in case you need to always overwrite the generated files but don't want to generate the images when normally compiling the source code.


Use this feature manually, in conjunction to build_when_doc.

You'll have to customize your setup using the the following example as a model:

Add to Cargo.toml:

doc = ["docima/doc"]

docima = { version = "*", features = ["build_when_doc"] }

Then the images will only be generated when you use this feature, like this:

doc --features=doc

For greater convenience you can create a new alias in .cargo/config.toml:

docdoc = "doc --features=doc"

More info

You can refer to the crate documentation and the source code for more complete information and practical examples.

Similar crates


~23K SLoC