README file from
GithubList Callouts, Improved
Create customized callouts in any list or highlighted text in Obsidian.
[!NOTE] This project is a fork of obsidian-list-callouts by @mgmeyers, who deserves all the credit for the original plugin and its design. Unfortunately that project has seen no activity since September 2024 and appears to be abandoned by the author.
This fork picks up maintenance and feature development so the plugin keeps working with current versions of Obsidian.
Typing a configurable character at the beginning of a list item turns the item into a highlighted callout:
The characters can be replaced with icons:
An item whose text runs onto further lines is one callout: the band covers every line of the item, in the editor as in reading view, nested items included:
Characters, icons, and colors are all configurable, and you can add your own callouts:
A callout's color paints both its marker and its background. If the marker is hard to read against a faint background, switch Default marker color to Custom marker color and pick a color for the marker alone. The background keeps the callout's color, and the marker color also applies to that callout's highlights:
A callout line shows two markers by default: the list's own bullet or number, then the callout's. Turn on Hide bullets and numbers in the settings tab and the callout marker stands in for the bullet, the way a checkbox does. A checkbox stays, since it can be clicked, and plain list items keep their bullets:
The previews in the settings tab follow the toggle, so each callout shows how it will look:
By default a callout colors its own list item only. Turn on Color nested items and the items nested under it take its color too, all the way down. A nested item that starts a callout of its own colors the items under it instead, and the items under a plain item stay plain:
Callouts are drawn in Live Preview and reading view. Source mode shows the raw markdown, - & Important and so on, with the callout character there to see and edit: no marker or icon stands in for it. The band behind the line and a highlight's color are kept, and the character is tinted in the callout's color, so a callout is still told apart at a glance in either mode:
Callout padding and background intensity can be adjusted with the Style Settings plugin.
Highlights
The same callout triggers work inside Obsidian's ==highlight== syntax. Start a highlight with a callout trigger and a space ==* Highlighted text==, and it takes that callout's color, led by the character, or by the icon if one is set:
A highlight that runs across a line break is colored as one in both the editor and reading view, including a list item's continuation line. Highlights inside callout blocks and tables work too:
A callout highlight's text keeps the normal text color, the same as a list callout's. Under a theme that gives highlighted text a color of its own, a plain highlight takes the theme's color and a callout highlight does not:
A highlight in one of Obsidian's colors (1.14 and later, ==🔴* Highlighted text==) that starts with a callout trigger is a callout too, in Live Preview and reading view, and takes the callout's color rather than its own. Source mode leaves it as Obsidian draws it, in the highlight's color.
Tag callouts
A callout can be triggered by a tag instead of a character: set a callout's character to a whole tag, such as #meal, and turn on Tag callouts at the top of the settings tab. Any list item with that tag anywhere on its first line then takes the callout, so a day's log can read - 12:30 #meal Lunch. If the callout has an icon, the icon replaces the tag; without one, the tag stays as Obsidian draws it and still links to its search. In Live Preview the tag comes back while the cursor is on it, so it can be edited.
- A nested tag takes its parent's callout unless it has one of its own:
#work/meetinguses the#workcallout. - Tags match whatever their case, as in Obsidian.
- If an item has more than one tag with a callout, the first one wins. A callout character at the start of the item wins over any tag.
- A
#tagin inline code or outside a list is left alone, and so is one on a line the item wraps onto. - Remove callout removes the tag that made the item a callout. Next callout and Previous callout work on the start of the item, as they do for characters.
- Hide bullets and numbers leaves an item colored by a tag its bullet, since the icon sits where the tag is rather than where the bullet was.
With the setting off, a tag callout only counts at the start of an item, like any other callout character.
This follows List Callouts Tags, without replacing character callouts: both kinds can be used side by side.
From Callout Manager
With Callout Manager enabled, the settings tab offers an Import from Callout Manager button. It adds a tag callout for each callout Callout Manager lists, with the color and icon it shows for it, so - #definition matches > [!definition]. That includes the callouts your theme and CSS snippets define, not only the ones made in Callout Manager. Obsidian's built-in callouts, the tags you already have a callout for, and ids that can't be tags (such as 2024) are left out, and the button lists what it will add before it adds anything.
The import is a copy: a callout changed in Callout Manager afterwards isn't updated here. A callout with different colors for light and dark mode comes over in the color it has in the current mode.
Managing callouts
Callouts are defined in one list. A new vault starts with the seven shown above, and any of them can be edited, reordered by dragging, or deleted, built-in ones included.
Reset to defaults, at the bottom of the settings tab, restores the original seven. It replaces everything currently configured, so added callouts and edits to the built-in ones are lost. It asks for confirmation first and can't be undone.
The order matters: it is the order the cycling commands below step through.
Commands
Each command can be given a hotkey from Settings → Hotkeys. All three act on every line a selection touches, skipping lines that aren't list items, and one undo reverts them all.
| Command | What it does |
|---|---|
| Next callout / Previous callout | Steps the line through the callout list in the order the settings tab shows. A plain list item is part of the cycle: stepping off either end leaves a plain list item, so overshooting wraps around instead of stranding the line, and the two directions are exact inverses. |
| Remove callout | Strips the callout character from the current line, leaving the list item behind. |
Support for custom icons
Any SVG in your vault's .obsidian/icons folder is registered as an icon and appears in the picker alongside the ones Obsidian ships. A file named My Fancy Icon.svg gets the icon name my-fancy-icon.
This is the same folder Iconize uses, so a vault already keeping icons there needs no changes.
An icon drawn in a single color, such as the black of most icon downloads, takes the callout's color (or its marker color) the way Obsidian's own icons do. An icon in two or more colors, or with a gradient, keeps its own.
Icons are read once Obsidian has finished starting up, so restart Obsidian or toggle the plugin after adding files. A name that an Obsidian icon already uses is skipped rather than replaced, and a file that is not usable SVG is skipped with a note in the console.
Migrating from List Callouts
This fork uses a new plugin id, so Obsidian treats it as a separate plugin and your existing List Callouts settings won't carry over on their own.
If the original plugin's settings are still in your vault, the settings tab offers an Import from List Callouts button that copies them over.
Once migrated, disable or delete the old plugin.
Development
See docs/DEVELOPMENT.md for building the plugin and docs/TESTING.md for running the test suite.
License
If this plugin is useful to you, please consider buying me a coffee.