Accept user input using commands and ribbon actions with Marcus Olsson

TL;DR

Register ribbon actions inside `onload` to add clickable icons to Obsidian’s left ribbon with a hover title and callback.

Briefing Cornell Notes

Briefing

Obsidian plugin developers can give users direct control by wiring plugin behavior into two core interaction points: ribbon actions and commands. Ribbon actions add a clickable icon to Obsidian’s left-side ribbon, making it easy to trigger a small task on demand—like the Halloween “boo” example—without building a full interface. Commands, by contrast, integrate with Obsidian’s command palette (Command-P on macOS) and can optionally support hotkeys, conditional availability, and editor-only execution.

The session starts from a minimal plugin setup and moves into user-driven features. A ribbon action is registered inside the plugin’s `onload` function. The icon comes from Obsidian’s Lucide icon library (`lucide.dev`), where developers pick an icon ID (for example, an “eye” icon) and provide a title shown on hover plus a callback that runs when the user clicks. After reloading, the new ribbon icon appears in the side menu; clicking it triggers the callback and produces the intended effect.

Next comes commands, which are central to how Obsidian users discover and run functionality. Commands appear in the command palette and can be bound to keyboard shortcuts. The session then demonstrates a conditional command using a `checkCallback` instead of a normal callback. The check callback runs twice: first with a “checking” flag set to true to determine whether the command should be available, and then with the flag set to false to actually execute the action. In the Halloween example, the command only becomes available after a time threshold (checking the current hour and returning true only after 7–11 p.m., depending on the demo). This pattern generalizes to other prerequisites—like verifying configuration or credentials—so commands don’t show up when they can’t succeed.

Finally, the session introduces an editor callback, which restricts a command to run only when the user is actively editing. Instead of manually locating the editor and markdown view, the callback receives them as parameters, enabling direct manipulation of the open note. The “decorate” command demonstrates this by reading the entire note contents, using a regular expression to find lines that start with `#` (headings), appending a pumpkin string to each match, and writing the updated text back via `setValue`. When the command is run outside the editor, it won’t execute; inside the editor, it updates the document immediately.

By the end, the takeaway is clear: ribbon actions are lightweight click-to-run entry points, commands integrate with Obsidian’s palette and hotkeys, conditional commands control availability through a two-phase check, and editor callbacks provide safe, direct access to the active note. Modals are mentioned as a next step for richer user input, but they’re reserved for a later session.

Cornell Notes

Obsidian plugins can accept user input by registering ribbon actions and commands inside `onload`. Ribbon actions add a clickable icon to the left ribbon; selecting an icon from Lucide and wiring a callback lets users trigger plugin behavior instantly. Commands appear in the command palette and can support hotkeys, but they can also be made conditional via `checkCallback`, which runs twice—once to decide availability and once to execute. For document edits, an editor callback runs only when the user is in the editor and receives the editor and markdown view, enabling direct text transformations like regex-based updates to headings. These patterns help plugins stay discoverable while preventing actions from running in the wrong context.

How does a ribbon action get added to an Obsidian plugin, and what does the user experience look like?

A ribbon action is registered in the plugin’s `onload` function. Developers supply an icon (chosen from Obsidian’s Lucide icon set at `lucide.dev`), a hover title, and a callback function. After reloading, the icon appears in Obsidian’s left-side ribbon; clicking it runs the callback (the demo uses a Halloween “boo” callback that spooks the user).

What’s the practical difference between a normal command callback and a conditional command using `checkCallback`?

A normal command callback runs when the command is invoked. A conditional command uses `checkCallback`, which runs twice: first with a “checking” flag set to true so the plugin can decide whether the command should be shown/available, then again with the flag set to false to perform the action. The demo checks the current hour and returns true only after a chosen time threshold (e.g., after 7 p.m.), so the command appears only when it’s “past dark.”

Why does `checkCallback` run twice, and how should the callback behave in each phase?

The first run (checking mode) should determine whether the command can run right now—returning true if conditions are met, false otherwise. The second run (execution mode) should carry out the actual action. In the demo, the callback checks the hour and then uses the `checking` parameter to decide whether to only validate availability or to run the “boo” action.

How does an editor callback change what a command can do?

An editor callback restricts execution to times when the user is actively editing. It receives the editor instance and the markdown view as parameters, so the plugin can read and update the current note without manually fetching those objects. The demo’s “decorate” command reads the note contents, uses a regex to find lines starting with `#`, appends a pumpkin to each match, and writes the updated text back with `setValue`.

What text-editing workflow is demonstrated for transforming a note using the editor callback?

The command workflow is: (1) get the entire note contents from the editor, (2) run a regular expression to match specific lines (headings beginning with `#`), (3) build a replacement string that appends a pumpkin to each match, and (4) update the editor content using `setValue` with the modified text. The result is immediate visual changes to the open note when the command runs inside the editor.

Review Questions

When registering a ribbon action, which three parameters are needed to make the icon clickable (icon, title, callback), and where are they provided?
In a conditional command, what does the `checking` flag indicate on the first vs second invocation of `checkCallback`?
How does an editor callback ensure the command only runs when the user is editing, and what two objects does it provide to the callback?

Key Points

1
Register ribbon actions inside `onload` to add clickable icons to Obsidian’s left ribbon with a hover title and callback.
2
Use Lucide icon IDs from `lucide.dev` to supply the ribbon action icon parameter.
3
Commands surface in the command palette and can optionally support hotkeys for faster user access.
4
Conditional commands use `checkCallback`, which runs twice—first to decide availability (checking=true) and then to execute (checking=false).
5
Conditional logic can gate commands based on runtime conditions like time of day or configuration readiness (e.g., credentials).
6
Editor callbacks provide direct access to the editor and markdown view and only run when the user is inside the editor context.
7
Use regex-based transformations plus `setValue` to update note contents safely from an editor callback.

Highlights

Ribbon actions are the quickest way to add a user-triggered button: icon + hover title + callback, registered in `onload`.

`checkCallback` runs twice, enabling commands to appear only when conditions are met and to execute only in the valid phase.

Editor callbacks hand over the editor and markdown view directly, making it straightforward to rewrite note text (e.g., append pumpkins to heading lines).

Topics

Ribbon Actions
Commands
Conditional Commands
Editor Callbacks
Lucide Icons