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 (pending)

This plugin has been submitted for review to the Obsidian community plugin directory. Once approved, you will be able to install it directly from Settings > Community plugins > Browse by searching for "Banner Images".

Using BRAT

You can install this plugin right now using the BRAT plugin:

1. Install BRAT from Settings > Community plugins > Browse (search for "BRAT" by TfTHacker)

2. Open the BRAT settings

3. Under the Beta plugins section, click Add beta plugin

   

4. In the overlay, enter this plugin's repository: https://github.com/saltyfireball/obsidian-banner-images (or just saltyfireball/obsidian-banner-images)

   

5. Leave the version set to latest

   

6. Click Add plugin

Manual

1. Download the latest release from the Releases page
2. Copy main.js, manifest.json, and styles.css into your vault's .obsidian/plugins/banner-images/ directory
3. Enable the plugin in Settings > Community plugins

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

Field	Type	Default	Description
banner_image	string	--	Path to image file (required). Also accepts backdrop or banner as field names
banner_height	number	200	Height of the banner in pixels
banner_opacity	number	1	Opacity from 0 (transparent) to 1 (fully visible)
banner_offset	string/number	center	Vertical position: top, center, bottom, or a percentage like 20%
banner_gradient	boolean	false	When true, fades from full opacity at top to selected opacity at bottom
banner_fit	string	none	Image fit mode: none (cover), fit_height, or fit_width

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:

Property	Type	Description
height	number	Default banner height in pixels
opacity	number	Default opacity (0 to 1)
offset	string	Default vertical position (e.g. "center", "30%")
gradient	boolean	Whether gradient transparency is enabled by default
fit	string	Default fit mode ("none", "fit_height", or "fit_width")

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.