Images¶
Support for including images is provided by Sphinx, with docutils (for reStructuredText) and myst-parser (for Markdown).
Image directive¶
To display an image using the MyST-parser extension you can use the standard Markdown syntax. To display an image using reStructuredText you only need to use the image directive. In both cases, the styling of Nefertiti places the image aligned to the left, and adjust the size when the width is larger than the width of the container.
A sample image¶
An example of the simplest way to insert an image:
.. image:: img/great_sphinx_of_giza.jpeg
Image dimensions¶
To adapt images’ size you can provide either the width or height and the other dimension will adapt to keep the aspect ratio. Alternatively you can pass the scale argument followed by an integer from 0 to 100 representing the percentage with respect to the width of the main documentation area.
Tip
It is not recommend to use width or height in combination with scale, as the resulting image does not maintain the original aspect ratio.
Setting image’s width¶
The following example adds an image at half of its width, and display it aligned to the center. The width dimension can be expressed in the following units: em, ex, px, in, cm, mm, pt, pc, %.
```{image} img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:alt: Watercolour painting by Mong kyaw sing marma
:width: 75%
:align: center
```
.. image:: img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:width: 75%
:align: center
Setting image’s height¶
The following example displays an image centered and with a height of 350px. The original height dimension is 600px. The height dimension can be expressed in the following units: em, ex, px, in, cm, mm, pt, pc, but not in percentage.
```{image} img/landscape-nature-trees-house-sunset-painting.jpg
:height: 500px
:align: center
```
.. image:: img/landscape-nature-trees-house-sunset-painting.jpg
:height: 500px
:align: center
Image alignment¶
In the previous section we have seen how to center the image. When the image is centered, it acts as a block and text can not surround the image. However when images are given an :align: left or :align: right attribute, text can surround the image.
Image left aligned¶
The following example in Markdown and reStructuredText inserts an image left aligned with enough text to surround the image.
```{image} img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:alt: Watercolour painting by Mong kyaw sing marma
:width: 50%
:align: left
```
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis
erat, iaculis non nibh nec, suscipit convallis ante. Fusce ullamcorper
magna semper libero laoreet, sed faucibus ligula venenatis. Nunc justo
leo, faucibus at turpis eget, dapibus pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat, in
vehicula dui congue vitae. Cras fringilla faucibus faucibus. Phasellus
vitae efficitur arcu. Sed mollis elementum nisl, ac mattis ex feugiat
vitae. Donec augue lectus, viverra molestie mi nec, volutpat auctor
purus. Duis viverra, ante quis lobortis fermentum, lectus tortor
fermentum justo, a finibus lectus ipsum a leo.
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis erat, iaculis non nibh nec, suscipit convallis ante. Fusce ullamcorper magna semper libero laoreet, sed faucibus ligula venenatis. Nunc justo leo, faucibus at turpis eget, dapibus pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat, in vehicula dui congue vitae. Cras fringilla faucibus faucibus. Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi nec, volutpat auctor purus. Duis viverra, ante quis lobortis fermentum, lectus tortor fermentum justo, a finibus lectus ipsum a leo.
.. image:: img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:width: 50%
:align: left
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis
erat, iaculis non nibh nec, suscipit convallis ante. Fusce
ullamcorper magna semper libero laoreet, sed faucibus ligula
venenatis. Nunc justo leo, faucibus at turpis eget, dapibus
pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat,
in vehicula dui congue vitae. Cras fringilla faucibus faucibus.
Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac
mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi
nec, volutpat auctor purus. Duis viverra, ante quis lobortis
fermentum, lectus tortor fermentum justo, a finibus lectus ipsum a
leo.
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis erat, iaculis non nibh nec, suscipit convallis ante. Fusce ullamcorper magna semper libero laoreet, sed faucibus ligula venenatis. Nunc justo leo, faucibus at turpis eget, dapibus pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat, in vehicula dui congue vitae. Cras fringilla faucibus faucibus. Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi nec, volutpat auctor purus. Duis viverra, ante quis lobortis fermentum, lectus tortor fermentum justo, a finibus lectus ipsum a leo.
Image right aligned¶
The following example in Markdown and reStructuredText inserts an image right aligned with enough text to surround the image.
```{image} img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:alt: Watercolour painting by Mong kyaw sing marma
:width: 50%
:align: right
```
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis
erat, iaculis non nibh nec, suscipit convallis ante. Fusce
ullamcorper magna semper libero laoreet, sed faucibus ligula
venenatis. Nunc justo leo, faucibus at turpis eget, dapibus
pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat,
in vehicula dui congue vitae. Cras fringilla faucibus faucibus.
Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac
mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi
nec, volutpat auctor purus. Duis viverra, ante quis lobortis
fermentum, lectus tortor fermentum justo, a finibus lectus ipsum
a leo.
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis erat, iaculis non nibh nec, suscipit convallis ante. Fusce ullamcorper magna semper libero laoreet, sed faucibus ligula venenatis. Nunc justo leo, faucibus at turpis eget, dapibus pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat, in vehicula dui congue vitae. Cras fringilla faucibus faucibus. Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi nec, volutpat auctor purus. Duis viverra, ante quis lobortis fermentum, lectus tortor fermentum justo, a finibus lectus ipsum a leo.
.. image:: img/Watercolour_by_Mong_kyaw_sing_marma.jpg
:width: 50%
:align: right
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis
erat, iaculis non nibh nec, suscipit convallis ante. Fusce
ullamcorper magna semper libero laoreet, sed faucibus ligula
venenatis. Nunc justo leo, faucibus at turpis eget, dapibus
pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat,
in vehicula dui congue vitae. Cras fringilla faucibus faucibus.
Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac
mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi
nec, volutpat auctor purus. Duis viverra, ante quis lobortis
fermentum, lectus tortor fermentum justo, a finibus lectus ipsum
a leo.
Nunc accumsan enim ac rutrum dignissim. In sed erat urna. In turpis erat, iaculis non nibh nec, suscipit convallis ante. Fusce ullamcorper magna semper libero laoreet, sed faucibus ligula venenatis. Nunc justo leo, faucibus at turpis eget, dapibus pharetra tortor.
Morbi commodo ut quam eget ultricies. Nam porta condimentum erat, in vehicula dui congue vitae. Cras fringilla faucibus faucibus. Phasellus vitae efficitur arcu. Sed mollis elementum nisl, ac mattis ex feugiat vitae. Donec augue lectus, viverra molestie mi nec, volutpat auctor purus. Duis viverra, ante quis lobortis fermentum, lectus tortor fermentum justo, a finibus lectus ipsum a leo.