Frontmatter Icons

An Obsidian plugin that reads emoji values from Markdown frontmatter and displays them beside the corresponding file or folder in the File Explorer. Icons are stored with notes, so moving a note or folder does not leave a path-keyed icon behind.

Properties

The default property names are file_icon and folder_icon. Each value must contain 1 to 3 emoji. Spaces between emoji are allowed, but mixed text and values with more than 3 emoji are invalid:

folder_icon: "🫐"
file_icon: "👟"

Invalid non-empty values display as ? with an exclamation marker and a tooltip explaining the allowed format. The frontmatter is left unchanged so you can correct the value there.

folder_icon applies to the folder that directly contains the Markdown note. Any Markdown note in that folder can declare it.

file_icon applies to the Markdown note containing the property. A note can set both properties: one icon for itself and one for its containing folder.

Settings

Open Frontmatter Icons in Obsidian's plugin settings to configure:

• File icon property: Frontmatter property used for note icons. Defaults to file_icon.
• Folder icon property: Frontmatter property used for folder icons. Defaults to folder_icon.
• Folder icon search order: Choose alphabetical (A to Z) or reverse alphabetical (Z to A) when multiple notes in a folder declare folder_icon.
• Global folder icons: Set an icon for a vault-relative folder path. These override a folder_icon property and do not require a Markdown note. Add or remove entries in settings.
• Show conflict marker: Show or hide the exclamation mark and tooltip when multiple icons are declared. Invalid-value warnings remain visible when conflict markers are hidden.

Conflicts

If multiple notes in a folder declare folder_icon, the configured search order determines which note supplies the folder icon. Duplicate declarations of the same property in one note also count as a conflict; the first declaration supplies the icon. Conflict markers are enabled by default.

API and dashboards

Scripts can access the plugin through app.plugins.plugins["frontmatter-icons"]. The API accepts vault-relative paths:

• getFileIcon(path) returns the icon set on that note.
• getFolderIcon(path) returns the icon set on that folder.
• getIcon(path) returns the note icon, falling back to the nearest ancestor folder icon.

Each method returns an empty string when no valid icon is available. In a DataviewJS block, use getIcon to show icons in a dashboard table:

const icons = app.plugins.plugins["frontmatter-icons"];

dv.table(
    ["Icon", "Project"],
    dv.pages('"Projects"')
        .map(page => [icons?.getIcon(page.file.path) ?? "", page.file.link])
);

Install for testing

1. Copy this folder into <vault>/.obsidian/plugins/frontmatter-icons/.
2. Enable Frontmatter Icons in Obsidian's Community plugins settings.
3. Add folder_icon or file_icon to a Markdown note and inspect that folder or note in the File Explorer.