Pixel Banner is a plugin for Obsidian that allows you to automatically add beautiful banner images to your notes using various images providers APIs, direct URLs, or local images with folder-specific settings supported. Enhance your note-taking experience with visually appealing headers that provide context and improve the overall aesthetics of your notes.
- Seamless integration with Obsidian's interface
- Popular images providers supported such as Pexels, Pixabay, Flickr, and Unsplash, automatically fetch and display banner images based on keywords
- Use direct URLs for custom banner images
- Use local images from your vault
- Use Obsidian internal links to images
- Customize banner appearance globally, per folder, or per note by plugin settings and properties of note
- Banner Image selection modal, local image picker with sort options
- Control select, pin, and refresh banner via commands from command palette and hotkeys
- Adjust vertical position of the banner image
- Set banner height (100-2500 pixels) as well as content start position of note
- Set the banner image display to cover, auto, or contain
- Control banner fade transparency (-1500 to 100)
- Banner image border radius customization
- Set banner gap between banner and the window edges
- Customize inline title color (requires Obsidian's "Show inline title" setting enabled)
- Control Titles and Banners embedded note
- Option to hide Pixel Banner fields at frontmatter (properties) in Reading mode
- Customize frontmatter field names for per note appearance
- Option to display fast select banner icon, open Banner Image selection modal to select local image
- Option to display view banner icon, immersive view full image
- Set default folder path when opening the Banner Image selection modal
- Automatically show release notes after plugin updates
- Option to display pin icon, save banner image from API to local folder
- Option to display refresh icon, get new random image
- Set pinned images folder path to save pinned image for permanent banner
- Clean orphaned images, clean unlinked images in pinned images folder
- Select size and orientation of images when fetch from images providers
- Choose number of images when fetch from images providers
- Set default keywords for fetch when no specific keyword is provided
- Open Obsidian and go to Settings
- Navigate to Community Plugins and disable Safe Mode
- Click on Browse and search for "Pixel Banner"
- Install the plugin and enable it
- Unzip the latest release into your
<vault>/.obsidian/plugins/folder.
- Obtain a free API key from Pexels, Pixabay, Flickr, or Unsplash (requires account to generate API)
- In Obsidian, go to Settings > Pixel Banner > API Settings and enter your API key(s)
- In any note, add a
bannerfield to the frontmatter with keywords for the desired image, a direct URL, a path to a local image, or an Obsidian internal link:
---
banner: blue turtle
---
### Or use a direct URL:
---
banner: https://example.com/image.jpg
---
### Or use a local image:
---
banner: /path/to/local/image.jpg
---
### Or use an Obsidian internal link:
---
banner: [[path/to/internal/image.jpg]]
---
### All settings can be overridden per note:
---
banner: ocean
banner-y: 30
content-start: 90
banner-display: contain
banner-repeat: true
banner-height: 500
banner-fade: -75
banner-radius: 50
banner-title-color: "#FF5733"
---You can customize the frontmatter field names used for each setting, and even define multiple names for each field. For example, if you set the banner field names to "banner, header-image, cover" and the Y-position field names to "banner-y, y-pos", you could use any of these variations in your frontmatter:
---
header-image: sunset
y-pos: 22
---
---
banner-y: 60
y-pos: 60
---
---
header-image: sunset
banner-y: 30
---Field names must follow these rules:
- Only letters, numbers, dashes, and underscores are allowed
- No spaces within field names (spaces after commas are fine)
- Names must be unique across all fields
In the API settings, you can customize:
- API Provider (Pexels/Pixabay/Flickr/Unsplash)
- Test your API keys directly in settings with the "Test API" button
- Get immediate feedback if your API key is valid
- Image size (small, medium, large)
- Image orientation (landscape, portrait, square)
- Number of images to fetch (1-50)
- Show pin/refresh icon
- Default keywords for when no specific keyword is provided
When using random images from images providers, you'll see a pin icon (📌) in the top left corner of the banner. Click this to:
- Save the image to your vault
- Update your note's frontmatter to use the local image
- Never lose that perfect banner image again!
You can configure the save location and manage orphaned pins in settings.
You can set default banner images for entire folders:
- Go to Settings > Pixel Banner
- Open "Folder Images" page
- Click "Add Folder Image Setting"
- Configure the folder settings:
- Folder path
- Enable Image Shuffle option: Randomly select an image from a specified folder each time the note loads
- Y-position (0-100)
- Banner height (100-2500 pixels)
- Fade effect (-1500 to 100)
- Border radius
- Inline title color
- Display mode and repeat settings
- Direct Children Only: Enable this option to apply the banner settings only to the direct children of the specified folder, excluding subfolders.
- Repeat for additional folders as needed
Folder-specific settings will apply to all notes in that folder (and subfolders) that don't have their own banner specified in the frontmatter, unless the "Direct Children Only" option is enabled.
If you enjoy this plugin please consider sending me a tip to support my work 😀
If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.
