Usage

Three directives are provided by the extension.

Images

reStructuredText

.. imgur:: 611EovQ
    :alt: Example image

MyST Markdown

```{imgur} 611EovQ
:alt: Example image
```

.. imgur::

Equivalent to the built in image directive. Display an Imgur image in the document the same way a regular image is displayed.

align/alt/height/width/scale/target: Same as the image directive.

:ext:: Override the image file extension (useful for gifs). Can be implicitly set with .. imgur:: 7WTPx0v.gif, otherwise the default extension is automatically used (can be changed with imgur_default_ext in conf.py).

Note

Implicitly setting the extension implies imgur:fullsize unless you set imgur:size.

:size:: Override the image size character (e.g. s, b, t, m, l, h). Can be implicitly set with .. imgur:: 611EovQs, otherwise the default character is automatically used (can be changed with imgur_default_size in conf.py).

:fullsize: (flag)

Use the full size image URL instead of using smaller thumbnails. The example below will link to https://i.imgur.com/abcd123.jpg instead of https://i.imgur.com/abcd123h.jpg:

.. imgur:: abcd123
    :fullsize:

:img_src_format:: Override the image URL formatter used for the output. Otherwise the default formatter is used (can be changed with imgur_img_src_format in conf.py). Valid substitutions are %(id)s, %(size)s, and %(ext)s.

:notarget: (flag): When set the image won’t automatically link to the full size image on Imgur. To override use the built in image :target: option.

Figures

Just like the .. imgur:: directive, imgur-figure is synonymous with the built in figure directive. The same options are also available.

https://i.imgur.com/611EovQh.jpg — Put your caption here.

reStructuredText

.. imgur-figure:: 611EovQ

    Put your caption here.

MyST Markdown

```{imgur-figure} 611EovQ

Put your caption here.
```

Albums

To embed albums use the imgur-embed directive, which relies on Imgur’s official embed unit.

Loading...

reStructuredText

.. imgur-embed:: a/hWyW0

MyST Markdown

```{imgur-embed} a/hWyW0
```

.. imgur-embed::

Besides imgur-embed:hide_post_details the other options are mainly for sphinxext-opengraph compatibility.

:hide_post_details:: Hide titles and descriptions in all album embeds when set to True. Same as checking the Hide Title checkbox in the native Imgur embed unit.

Note

There’s currently a bug where if you have two embed units on the same page, with just one of them with this option, both embeds will shrink in vertical size causing the embed with titles and descriptions enabled to appear cut off.

:og_imgur_id:: Without this option Imgur album embeds will be ignored by sphinxext-opengraph (an embedded image works fine). Specify an image ID (typically one of the images in your album) so it shows up when posting your sphinx document link on Slack/Facebook/Discord/etc.

:alt:: Passed to og:image:alt, similar to the built in image :alt: option.

:ext:: Override the file extension used in sphinxext-opengraph, similar to imgur:ext.

:size:: Override the image size character for sphinxext-opengraph. Similar to imgur:size.

:fullsize: (flag): Use the full size image URL instead of using smaller thumbnails for sphinxext-opengraph. Similar to imgur:fullsize.

:img_src_format:: Override the image URL formatter for sphinxext-opengraph. Similar to imgur:img_src_format.

Configuration

Set defaults for the extension in your conf.py file:

imgur_default_ext

Default: jpg

Default file extension for images. When a document uses .. imgur:: abcd123 the output will contain https://i.imgur.com/abcd123h.jpg. This can be overridden implicitly in the directive by using .. imgur:: abcd123.gif or with the imgur:ext option.

imgur_default_size

Default: h

Default image size to use in documents. To save visitors’ bandwidth, when a document uses .. imgur:: abcd123 the output will contain https://i.imgur.com/abcd123h.jpg. This can be overridden implicitly in the directive by using .. imgur:: abcd123s (for a small thumbnail) or with the imgur:size option, or disabled all together with the imgur:fullsize option. Current valid choices are s, b, t, m, l, and h.

imgur_img_src_format

Default: https://i.imgur.com/%(id)s%(size)s.%(ext)s

Image URL formatter used for the output. Valid substitutions are %(id)s, %(size)s, and %(ext)s. This can be overridden in documents with the imgur:img_src_format option.

imgur_target_format

Default: https://imgur.com/%(id)s

URL formatter used for image links. Valid substitutions are %(id)s, %(size)s, and %(ext)s. This can be disabled in documents with the imgur:notarget option, and overridden with the built in image :target: option.

imgur_hide_post_details

Default: False

Hide titles and descriptions in all album embeds when set to True. Same as checking the Hide Title checkbox in the native Imgur embed unit. This can be set in documents on a per embed basis with the imgur-embed:hide_post_details option.