Images ​

An image is a link to an image file[1] that does not have a description part, for example

bash
./img/cat.jpg

If you wish to define a caption for the image (see Captions) and maybe a label for internal cross-references (see Internal Links), make sure that the link is on a line by itself and precede it with ‘CAPTION’ and ‘NAME’ keywords as follows:

orgmode
#+CAPTION: This is the caption for the next figure link (or table)
#+NAME:   fig:SED-HR4049
[[./img/a.jpg]]

Such images can be displayed within the buffer with the following command:

C-c C-x C-v (org-toggle-inline-images) ​

Toggle the inline display of linked images. When called with a prefix argument, also display images that do have a link description. You can ask for inline images to be displayed at startup by configuring the variable org-startup-with-inline-images[2].

By default, Org mode displays inline images according to their actual width, but no wider than fill-column characters.

You can customize the displayed image width using org-image-actual-width variable (globally) or ‘ORG-IMAGE-ACTUAL-WIDTH’ property (subtree-level)[3]. Their value can be the following:

  • (default) Non-nil, use the actual width of images when inlining them. If the actual width is too wide, limit it according to org-image-max-width.

  • When set to a number, use imagemagick (when available) to set the image’s width to this value.

  • When set to a number in a list, try to get the width from any ‘#+ATTR.*’ keyword if it matches a width specification like:

    orgmode
    #+ATTR_HTML: :width 300px

    and fall back on that number if none is found.

  • When set to nil, try to get the width from an ‘#+ATTR.*’ keyword and fall back on the original width or org-image-max-width if none is found.

org-image-max-width limits the maximum displayed image width, but only when the image width is not set explicitly. Possible maximum width can be set to:

  • (default) fill-column, limit width to fill-column number of characters.
  • window, limit width to current window width.
  • integer number, limit width to that specified number of pixels.
  • nil, do not limit the width.

Org mode can left-align, center or right-align the display of inline images. This setting is controlled (globally) by org-image-align. Only standalone images are affected, corresponding to links with no surrounding text in their paragraph except for whitespace. Its value can be the following:

  • (default) The symbol left, which inserts the image where the link appears in the buffer.
  • The symbol center, which will preview links centered in the Emacs window.
  • The symbol right, which will preview links right-aligned in the Emacs window.

Inline image alignment can be specified for each link using the ‘#+ATTR.*’ keyword if it matches an alignment specification like:

orgmode
#+ATTR_HTML: :align center

Org will use the alignment specification from any ‘#+ATTR.*’ keyword, such as ‘#+ATTR_HTML’ or ‘#+ATTR_LATEX’, but ‘#+ATTR_ORG’ (if present) will override the others. For instance, this link

orgmode
#+ATTR_HTML: :align right
#+ATTR_ORG: :align center
[[/path/to/image/file.png]]

will be displayed centered in Emacs but exported right-aligned to HTML.

When ‘#+ATTR_ORG’ is not set, inline image alignment is also read from the ‘:center’ attribute supported by some export backends (like HTML, LaTeX and Beamer.)

Inline images can also be displayed when cycling the folding state. When custom option org-cycle-inline-images-display is set, the visible inline images under subtree will be displayed automatically.

  1. What Emacs considers to be an image depends on image-file-name-extensions and image-file-name-regexps. ↩︎

  2. The variable org-startup-with-inline-images can be set within a buffer with the ‘STARTUP’ options ‘inlineimages’ and ‘noinlineimages’. ↩︎

  3. The width can be customized in Emacs >= 24.1, built with imagemagick support. ↩︎