Adding captions to images in your Obsidian notes can significantly enhance clarity and context, especially when working with visual information. While Obsidian doesn’t natively offer image captions, the “Image Caption” plugin provides a seamless solution. This guide will show you how to use this plugin to effectively caption your photos in Obsidian, making your notes more informative and visually appealing.
Effortlessly Add Captions to Images in Obsidian
The Obsidian Image Caption plugin is designed to be intuitive and straightforward. Once installed, it allows you to add captions to both internally embedded images and externally linked images with ease. Let’s explore how to use it for different types of image embeds.
Captioning Internal Image Embeds
For images stored within your Obsidian vault, adding a caption is as simple as using the pipe symbol (|) followed by your caption text within the image embed syntax.
![[your-image.png|Your descriptive caption here]]For example, if you have an image named “mountain_view.jpg” and you want to add the caption “Stunning mountain vista at sunrise,” your markdown would look like this:
![[mountain_view.jpg|Stunning mountain vista at sunrise]]
Obsidian Image Caption example
This will display your image with the caption “Stunning mountain vista at sunrise” appearing directly below it, providing immediate context to your visual content.
Captioning External Image Embeds
When embedding images from external websites, you can utilize the alt text field to serve as your image caption. This method also allows the Obsidian Image Caption plugin to recognize and display it as a proper caption.
For instance, to caption an external image with the URL https://example.com/cityscape.png with the caption “Night cityscape with vibrant lights,” you would use:
This approach ensures that even images linked from external sources are clearly captioned within your Obsidian notes.
Resizing Images with Captions
The Obsidian Image Caption plugin retains Obsidian’s native image resizing capabilities. You can resize both internally and externally embedded images, even when captions are included. To resize, you typically use the <width>x<height> format after the pipe (|) for internal images. When using captions, ensure you correctly delimit the caption text as per your plugin settings.
Here’s how resizing works with internal embeds:
![[my_image.png|50x50]] ![[another_image.png|autox200]]To resize and caption simultaneously, and assuming " is set as your caption delimiter in the plugin settings, you might use:
![[image_name.png|50x50 "Concise caption here"]]For external images, resizing and captioning, using the same " delimiter example:
Remember to configure your caption delimiter in the plugin’s settings for this to function correctly.
Customizing Caption Appearance in Obsidian
The Obsidian Image Caption plugin offers several customization options to tailor the appearance and behavior of your image captions. These settings can be found in the plugin’s settings tab within Obsidian.
Caption Label
The “Label” setting allows you to prepend a consistent text label to all your captions. This is useful for automatically numbering figures or adding a prefix like “Fig.” For automatic numbering, use ‘#’ in this field. To output a literal ‘#’, escape it with a backslash ‘#’. Similarly, backslashes themselves need to be escaped as ‘\’.
Custom CSS for Captions
If you want to further refine the visual style of your captions, the “CSS” setting lets you apply custom CSS styling. Captions are indexed starting from 1 using the data-image-caption-index attribute, allowing for sequential styling based on figure number.
Caption Delimiter
The “Delimiter” setting is crucial for defining how the plugin identifies caption text, especially when resizing is also used. You can set a single character delimiter (e.g., ") to enclose your captions, or define a start and end delimiter set separated by a comma (e.g., {,}). If no delimiter is set, the entire text following the image path (and size, if present) will be treated as the caption. Whitespace around delimiters is automatically trimmed.
Render Captions as HTML
Enabling the “Caption as HTML” option allows your captions to be rendered as HTML instead of plain text. This provides greater flexibility for formatting captions with HTML elements directly within your markdown.
Troubleshooting Common Caption Issues
Captions Not Appearing: A common reason for captions not showing up is that the image needs to be re-rendered after adding or modifying the caption. Try making a minor change to the caption text (even adding and removing a space) and see if the caption then appears. If this resolves the issue, you can revert the text back to your intended caption. If problems persist, consider reporting it as an issue to the plugin developers.
Pandoc Compatibility: While the plugin enhances Obsidian’s display, full compatibility with Pandoc for exporting is still under development. Be aware that caption rendering might differ when exporting your notes using Pandoc. For external embeds, the plugin’s behavior aligns with Pandoc’s implicit_figures extension, which uses alt text as captions for images alone in a paragraph. However, Pandoc might not recognize resizing parameters applied through the plugin.
Known Limitations
Occasional Missing Captions: In some instances, captions might not render correctly, which is a known issue being addressed in ongoing development.
Partial Pandoc Export Compatibility: As noted, full Pandoc compatibility is still in progress, and exported documents might not perfectly replicate the captioned images as seen in Obsidian.
By following this guide, you can effectively use the Obsidian Image Caption plugin to add informative and styled captions to your images, significantly improving the clarity and context of your visual notes within Obsidian.
