# List Callouts, Improved

Create customized callouts in any list or highlighted text in Obsidian.

> [!NOTE]
> **This project is a fork of [obsidian-list-callouts](https://github.com/mgmeyers/obsidian-list-callouts) by [@mgmeyers](https://github.com/mgmeyers)**, who deserves all the credit for the original plugin and its design. Unfortunately that project has seen no activity since [September 2024](https://github.com/mgmeyers/obsidian-list-callouts/releases/tag/1.2.9) 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:

![A note with each built-in callout character applied to a list item, shown in light and dark mode](screenshots/callout-characters.png)

The characters can be replaced with icons:

![The same note with each callout character replaced by an icon, shown in light and dark mode](screenshots/callout-icons.png)

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:

![Three list items, two of them running onto further lines and one of those nested, each painted as a single band covering all of its lines, shown in light and dark mode](screenshots/callout-multiline.png)

Characters, icons, and colors are all configurable, and you can add your own callouts:

![The plugin settings tab with the icon picker open and a tooltip naming the hovered icon, in light and dark mode](screenshots/settings-icon-picker.png)

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's settings row with the marker color dropdown on "Custom marker color", its preview showing a dark amber star on the callout's yellow background, and the marker color picker open below the second swatch, in light and dark mode](screenshots/settings-marker-color-picker.png)

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:

![Six list items with the setting on: a star callout above a plain bullet item, a question-mark callout above a plain numbered item, and a warning callout keeping its checkbox above a plain task, shown in light and dark mode](screenshots/callout-hidden-bullets.png)

The previews in the settings tab follow the toggle, so each callout shows how it will look:

![The settings tab with Hide bullets and numbers turned on: every callout's preview line shows its marker in place of the bullet, in light and dark mode](screenshots/settings-hidden-bullets.png)

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:

![Three lists with the setting on: a star callout whose nested items and their children share its yellow, a question-mark callout whose first nested item is a red warning callout with its own child in red while the next nested item is orange again, and a plain item whose nested item is plain, shown in light and dark mode](screenshots/callout-nested-items.png)

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:

![The same four callouts twice: in Live Preview, each led by its icon, and below it in source mode, each led by its raw character in the callout's color on the same band, shown in light and dark mode](screenshots/callout-source-mode.png)

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 paragraph with several inline highlights, each in a different callout color, rendered twice: led by the callout characters above, and by the callouts' icons below, each shown in light and dark mode](screenshots/highlights.png)

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 paragraph, a list, a callout block and a table, each holding highlights in different callout colors, two of them running across a line break, shown in light and dark mode](screenshots/highlight-multiline.png)

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 paragraph with a plain highlight in a theme's own text color, and below it a list callout with a callout highlight inside, both in the normal text color, shown in light and dark mode](screenshots/highlight-foreground.png)

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 day's log in which each timed entry is colored by a tag somewhere in it: exercise in green with a dumbbell, meals in orange with a fork and knife, work in blue with a briefcase whether tagged #work or #work/meeting, and an errand in purple still showing its #errand tag, shown in light and dark mode](screenshots/callout-tags.png)

- A nested tag takes its parent's callout unless it has one of its own: `#work/meeting` uses the `#work` callout.
- 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 `#tag` in 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](https://github.com/kltsv/obsidian-list-callouts-tags), without replacing character callouts: both kinds can be used side by side.

## 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.

![The plugin's settings tab in full: the tag callouts toggle, the highlight toggles, then the seven built-in callouts each with a preview, character, icon, color and marker color, and the reset at the bottom, shown in light and dark mode](screenshots/settings.png)

**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](https://github.com/FlorianWoelki/obsidian-iconize) uses, so a vault already keeping icons there needs no changes.

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](https://github.com/mgmeyers/obsidian-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.

![The Import from List Callouts row at the top of the settings tab, shown in light and dark mode](screenshots/settings-import.png)

Once migrated, disable or delete the old plugin.

## Development

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for building the plugin and [docs/TESTING.md](docs/TESTING.md) for running the test suite.

## License

[GPL-3.0](LICENSE.md)

If this plugin is useful to you, please consider [buying me a coffee](https://buymeacoffee.com/danyim).