Banner Images

Banner Images for Obsidian

Display banner images at the top of your notes using frontmatter fields.

Features

• Frontmatter-driven -- Add a single field to your note's frontmatter and a banner image appears at the top
• Multiple image sources -- Use vault-relative paths, wikilink-style paths ([[image.png]]), or external URLs
• Customizable height -- Set banner height globally or per-note via frontmatter
• Opacity control -- Adjust banner transparency globally or per-note
• Vertical positioning -- Control which part of the image is shown (top, center, bottom, or percentage)
• Fit modes -- Choose how the image fills the banner: cover (default), fit to height, or fit to width
• Gradient transparency -- Smooth fade from full opacity at the top to your chosen opacity at the bottom
• Command palette -- Insert banner frontmatter into any note via the command palette
• Works in all views -- Renders in both Reading View and Live Preview/Source mode
• Mobile support -- Full-width banners on mobile devices

Installation

Obsidian Community Plugin

This plugin is available in the official Obsidian community plugin directory. Install it from Settings > Community plugins > Browse and search for "Banner Images" or "Banner Images by saltyfireball".

Usage

Quick Start

1. Enable the plugin in settings
2. Add banner_image to your note's frontmatter manually, or use the command palette (Ctrl/Cmd+P) and run Banner Images: Insert banner frontmatter to insert all available fields automatically:

---
banner_image: path/to/your/image.png
---

The command will add only missing banner fields if frontmatter already exists.

Frontmatter Fields

Examples

Basic banner:

---
banner_image: attachments/header.jpg
---

Full customization:

---
banner_image: attachments/landscape.png
banner_height: 300
banner_opacity: 0.7
banner_offset: 30%
banner_gradient: true
banner_fit: fit_width
---

Using a URL:

---
banner_image: https://example.com/image.jpg
banner_height: 250
---

Using wikilink syntax:

---
banner_image: "[[my-banner.png]]"
---

Fit Modes

The banner_fit field controls how the image is sized within the banner area:

• none (default) -- The image covers the entire banner area. Parts of the image may be cropped to fill the space.
• fit_height -- The image scales so its full height is visible within banner_height. The image is centered horizontally, and the sides may be cropped if the image is wider than the banner area.
• fit_width -- The image scales so its full width matches the banner width. Resizing the window effectively zooms in or out. The top/bottom may be cropped based on banner_offset.

Supported Image Formats

• Vault-relative paths: attachments/banner.png
• Wikilink-style paths: [[image.png]]
• External URLs: https://example.com/image.png
• All common image formats: PNG, JPG, GIF, WebP, SVG

Settings

Access settings via Obsidian Settings > Banner Images:

• Enable banner images -- Master toggle for the feature
• Default height -- Default banner height in pixels (used when banner_height is not set in frontmatter)
• Default opacity -- Default transparency level (used when banner_opacity is not set)
• Gradient transparency -- Enable gradient fade by default
• Default vertical position -- Default image positioning (used when banner_offset is not set)
• Default fit mode -- Default image fit behavior (used when banner_fit is not set)

Compatibility

This plugin uses the banner_image frontmatter key by default. For compatibility with other banner plugins, it also reads the backdrop and banner fields.

Cross-Plugin API

This plugin exposes its default settings so that other plugins (such as export tools) can read the user's configured defaults. The API is accessible via the standard Obsidian plugin registry pattern:

// Access from another plugin
const bannerPlugin = (app as any).plugins?.plugins?.["banner-images"];
const defaults = bannerPlugin?.api?.getDefaults();

The getDefaults() method returns an object with the current default settings:

If the banner-images plugin is not installed or not enabled, callers should provide their own fallback defaults. Always use optional chaining when accessing the API.

License

This plugin is released under the MIT License.