MH Banners & Icons

MH Banners & Icons is an Obsidian plugin for adding configurable banners, icons, date and time information, and text overlays to notes. Visuals can be controlled through frontmatter, reusable templates, and ordered conditional rules.

Features

• Render banners from vault files, wikilinks, URLs, or CSS colors.
• Render icons from emoji, Lucide icon names, vault files, URLs, or short text.
• Display configurable date and time overlays using the shared MH API formats.
• Display manual text, note names, frontmatter properties, or rotating phrases from another note.
• Create reusable templates for banner, icon, date/time, and text presentation.
• Apply templates and content sources through ordered rules based on folders, paths, names, tags, and frontmatter.
• Choose normal, sticky, or background banner modes.
• Limit rendering to reading mode, editing mode, or both.
• Configure image positioning, content offsets, opacity, blur, darkening, desaturation, borders, shadows, and animations.
• Configure timed or note-based refresh behavior for random phrases.
• Use English or Brazilian Portuguese interfaces.
• Share suggesters, condition controls, formatting, and visual components with MH API.

Installation

Requirements

MH API is an operational dependency and must be installed and enabled before MH Banners & Icons.

MH Banners & Icons	Required MH API
1.0.0	1.0.0
1.1.0 or newer	1.1.0 or newer

The plugin stops loading and displays a native Obsidian notice when MH API is unavailable or incompatible.

Install With BRAT

1. Install and enable the compatible version of MH API.

2. Install and enable BRAT from Obsidian's Community plugins.

3. Open the command palette and run BRAT: Plugins: Add a beta plugin for testing.

4. Enter this repository URL:

   https://github.com/heide-oficial/mh-banners-and-icons
   

5. Select the latest release and add the plugin.

6. Open Settings > Community plugins and enable MH Banners & Icons.

BRAT installs main.js and manifest.json from the selected GitHub Release and handles subsequent updates.

Install Manually

1. Install and enable the compatible version of MH API.

2. Download mh-banners-and-icons-v<version>.7z from the matching GitHub Release.

3. Extract the mh-banners-and-icons folder into your vault's plugin directory:

   <vault>/.obsidian/plugins/
   

4. Confirm that these runtime files exist:

   <vault>/.obsidian/plugins/mh-banners-and-icons/main.js
   <vault>/.obsidian/plugins/mh-banners-and-icons/manifest.json
   

5. Restart Obsidian or reload community plugins.

6. Open Settings > Community plugins and enable MH Banners & Icons.

Do not copy or distribute data.json. It contains vault-specific plugin settings.

Development Guide

Prerequisites

• Node.js and npm.
• A local Obsidian development vault.
• A compatible MH API build installed and enabled in that vault.

Prepare The Project

1. Clone the repository:

   git clone https://github.com/heide-oficial/mh-banners-and-icons.git
   cd mh-banners-and-icons
   

2. Install dependencies:

   npm install
   

3. Run the project checks:

   npm run typecheck
   npm test
   npm run build
   

The production bundle is generated at dist/main.js.

Install A Development Build

Create <vault>/.obsidian/plugins/mh-banners-and-icons/ and copy:

• dist/main.js as main.js;
• manifest.json.

Then reload community plugins in Obsidian. Source code belongs in src/; generated bundles should not be edited manually.

Project Structure

• src/main.ts: plugin lifecycle, settings loading, and Obsidian event registration.
• src/mhApi.ts: typed MH API boundary, capability checks, and minimum-version validation.
• src/integration/: shared dependency error presentation.
• src/renderer/: banner, icon, text, date/time, animation, and scroll rendering.
• src/services/: effective settings, phrase selection, cache, scheduling, and date/time helpers.
• src/settings/: defaults, normalization, migrations, and the settings tab.
• src/ui/: plugin-specific adapters built on MH API components.
• src/i18n/ and locales/: bundled translations and locale access.
• src/styles/: runtime CSS injection.
• tests/: unit and visual validation fixtures.

Credits

Created and maintained by Matheus Heidemann (heide-oficial).

License

Copyright (C) 2026 Matheus Heidemann.

This project is licensed under the GNU General Public License v3.0 or later.