image¶
Image directive inserts image block to the text.
Image syntax¶
Basically, you need only to specify a file to display in the image:: directive argument (please note the space after ::). Without options, image:: directive displays image as-is, i.e. in original size.
1.. image:: /img/banana.png
Setting image width¶
To change displayed image width, use :width: option. Modifying the width, also changes its height to keep the image’s width : height aspect ratio.
You can enter desired value either as length unit (e.g., px, em), or as percentage of available width (e.g, 50%).
1.. image:: /img/rocket.png
2 :width: 50%
Note
For example, in the HTML output the file is not actually resized. New dimensions are modified just in the browser by applying CSS style like width: 50%;.
Setting image height¶
To change displayed image height, use :height: option. Modifying the height, also changes its width to keep the image’s width : height aspect ratio.
You must enter desired value as length unit (e.g., px, em). Values without a unit (e.g., 50) are px for HTML output (e.g., 50px).
1.. image:: /img/pumpkin.png
2 :height: 250px
Caution
Specifying percentages causes a warning similar to the following error:
WARNING: Error in "image" directive: invalid option value: (option: "height"; value: '50%') not a positive measure of one of the following units: "em" "ex" "px" "in" "cm" "mm" "pt" "pc" "".
Don’t maintain aspect ration¶
If you specify either width or height, image will maintain its aspect ration. To turn it off, set both the :width: and :height: manually.
1.. image:: /img/banana.png
2 :width: 150px
3 :height: 250px
Scaling images¶
Instead of setting width, height, or both, you might want to scale the image based on its original dimensions.
For example, the image rocket.png has 1272x920 pixels. Setting :scale: 25% will set its width to 318px and height to 230px.
1.. image:: /img/rocket.png
2 :scale: 25%
Image alignment¶
With :align: option the image will float and have the text flow (wrap) around it. Possible values are left, right, and center.
1.. image:: /img/small-banana.png
2
3Dolor occaecat tempor nostrud enim velit laborum anim. Ut veniam fugiat consectetur ea. Fugiat commodo elit reprehenderit non pariatur officia velit dolore consectetur minim irure ad ex.
4
5.. image:: /img/small-banana.png
6 :align: left
7
8Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa. Sit culpa deserunt cupidatat reprehenderit ex voluptate excepteur consectetur do. Proident est veniam occaecat reprehenderit occaecat Lorem eu. Sunt ad nisi velit tempor proident nulla exercitation voluptate exercitation.
9
10.. image:: /img/small-banana.png
11 :align: right
12
13Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Aliqua duis laboris minim nisi occaecat tempor dolor et consectetur voluptate. Nulla nostrud fugiat occaecat nostrud qui labore duis nisi aute. Sint pariatur qui incididunt minim.
14
15.. image:: /img/small-banana.png
16 :align: center
17
18Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor.Deserunt nisi quis amet veniam mollit adipisicing adipisicing fugiat ad dolor.
Dolor occaecat tempor nostrud enim velit laborum anim. Ut veniam fugiat consectetur ea. Fugiat commodo elit reprehenderit non pariatur officia velit dolore consectetur minim irure ad ex.
Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa. Sit culpa deserunt cupidatat reprehenderit ex voluptate excepteur consectetur do. Proident est veniam occaecat reprehenderit occaecat Lorem eu. Sunt ad nisi velit tempor proident nulla exercitation voluptate exercitation.
Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Aliqua duis laboris minim nisi occaecat tempor dolor et consectetur voluptate. Nulla nostrud fugiat occaecat nostrud qui labore duis nisi aute. Sint pariatur qui incididunt minim.
Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor.Deserunt nisi quis amet veniam mollit adipisicing adipisicing fugiat ad dolor.
Caution
The exact behavior and appearance depends on output format and theme. For example, in the most HTML themes, the center value center the image but don’t float (wrap).
Image as external link¶
With :target: option, you transform an image into the link to an external URL.
1.. image:: /img/pumpkin.png
2 :width: 50%
3 :target: https://en.wikipedia.org/wiki/Pumpkin
Resized image without a link to the original file¶
Maybe you have noticed that images resized with :width:, :height:, or :scale: are links to the original image file. This is normally useful. If you want to turn it off, add :class: no-scaled-link option to the image:: directive.
1.. image:: /img/cupcake.png
2 :width: 25%
3
4.. image:: /img/cupcake.png
5 :width: 25%
6 :class: no-scaled-link
Important
Scaled image link feature is added by Sphinx and not supported in pure Docutils. It is enabled by default. To turn it off completely, set html_scaled_image_link option to False in your conf.py.