Usage
Three directives are provided by the extension.
Images
.. imgur:: 611EovQ
:alt: Example image
```{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 withimgur_default_ext
inconf.py
).Note
Implicitly setting the extension implies
imgur:fullsize
unless you setimgur: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 withimgur_default_size
inconf.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 ofhttps://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
inconf.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.
.. imgur-figure:: 611EovQ
Put your caption here.
```{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...
.. imgur-embed:: a/hWyW0
```{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 containhttps://i.imgur.com/abcd123h.jpg
. This can be overridden implicitly in the directive by using.. imgur:: abcd123.gif
or with theimgur: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 containhttps://i.imgur.com/abcd123h.jpg
. This can be overridden implicitly in the directive by using.. imgur:: abcd123s
(for a small thumbnail) or with theimgur:size
option, or disabled all together with theimgur:fullsize
option. Current valid choices ares
,b
,t
,m
,l
, andh
.
- 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 theimgur: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 theimgur: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 theimgur-embed:hide_post_details
option.