Setting up plugin settings with Marcus Olsson

Obsidian plugin settings can be made persistent by wiring three pieces together: a typed settings model with defaults, runtime load/save using Obsidian’s data.json storage, and a Settings Tab UI that edits those values. The payoff is straightforward—users can customize behavior (like the “boo” text in a Halloween plugin) and have the change survive restarts instead of being hard-coded.

The tutorial starts with a concrete problem: the “peek into the dark” command and ribbon action currently display a fixed, hard-coded scare message. To let users choose their own scare text, the plugin needs a configurable property and a way to remember it. The first step is defining what’s configurable by creating a settings interface (for example, a single string property such as “spooky text”) and pairing it with defaults. Defaults are handled using a “partial” type so missing fields won’t crash the plugin, and the initial value can safely fall back to something like “boo.”

Next comes the runtime plumbing. Obsidian provides APIs to move settings between disk and memory: load data from the plugin directory’s data.json into the plugin at startup, and save data back when users change values. The tutorial recommends extracting loading into an async loadSettings function that reads from disk, then merging loaded values over the defaults using Object.assign. That merge step matters because it avoids a common mistake: directly assigning defaults by reference can cause updates in the live settings to mutate the default object itself.

Once settings are loaded, the plugin must actually use them. The scare notice is updated to read from settings.spookyText (or the equivalent property), but nothing changes until loadSettings is called during plugin initialization. After that, the command reflects the stored value.

The final—and most user-facing—piece is the Settings Tab. Obsidian’s SettingsTab mechanism lets plugins register a new section under the app’s settings UI. A custom SpookySettingsTab class extends the built-in PluginSettingTab, implements a display method, and receives the plugin and app context via its constructor so it can access the current settings. Inside display, the tab builds UI using HTML container elements and Obsidian’s Setting components, including a text input bound to the current setting value.

To persist edits, the text input’s onChange handler updates the plugin’s in-memory settings and calls a saveSettings method. That method uses Obsidian’s saveData API to write the updated settings object back to data.json. The tutorial closes by showing the resulting data.json structure in the vault (where user-editable settings live), and suggests extending the same pattern with additional setting types and UI controls. Theme development is teased as the next topic after settings.