Overview
ThePlugin class is the abstract base class that all Obsidian plugins must extend. It provides the foundation for plugin lifecycle management, UI integration, and access to the Obsidian API through the app property. The Plugin class extends Component, inheriting all component lifecycle methods.
Available since: v0.9.7
Constructor
The main App instance providing access to the Obsidian API.
The plugin manifest containing metadata like id, name, version, etc.
Properties
Reference to the main App instance, providing access to all Obsidian APIs.Since: v0.9.7
The plugin’s manifest containing metadata such as id, name, version, author, and description.Since: v0.9.7
Lifecycle Methods
onload()
Called when the plugin is loaded. Override this method to initialize your plugin, register commands, add ribbon icons, and set up event handlers. Returns:Promise<void> | void
Since: v0.9.7
onUserEnable()
Called when the user explicitly enables the plugin for the first time. Use this for initial setup that requires user interaction, such as opening a custom view or showing a welcome message. Returns:void
Since: v1.7.2
onExternalSettingsChange()
Called when thedata.json file is modified externally (e.g., by a sync service). Implement this to reload settings when they change outside of Obsidian.
Returns: any
Since: v1.5.7
UI Methods
addRibbonIcon()
Adds an icon to the left ribbon bar.The icon name to display. See Icon documentation for available icons.
The tooltip text shown when hovering over the icon.
The callback function executed when the icon is clicked.
HTMLElement - The created ribbon icon element.
Since: v0.9.7
addStatusBarItem()
Adds a status bar item to the bottom of the app. Not available on mobile devices. Returns:HTMLElement - The status bar element to populate with content.
Since: v0.9.7
Command Registration
addCommand()
Registers a command globally. Commands appear in the command palette and can be assigned hotkeys. The command id and name are automatically prefixed with your plugin’s id and name.The command configuration object containing id, name, callback, and optional properties.
Command - The registered command object.
Since: v0.9.7
removeCommand()
Manually removes a command. Only needed if your plugin registers commands dynamically.The ID of the command to remove (without the plugin prefix).
void
Since: v1.7.2
Settings
addSettingTab()
Registers a settings tab that appears in the settings panel.The settings tab instance to register.
void
Since: v0.9.7
loadData()
Loads settings data fromdata.json in the plugin folder.
Returns: Promise<any> - The parsed data from the file, or null if the file doesn’t exist.
Since: v0.9.7
saveData()
Writes settings data todata.json in the plugin folder.
The data object to serialize and save. Must be JSON-serializable.
Promise<void>
Since: v0.9.7
View Registration
registerView()
Registers a custom view type with the workspace.A unique identifier for this view type.
A factory function that creates view instances:
(leaf: WorkspaceLeaf) => Viewvoid
Since: v0.9.7
registerExtensions()
Registers file extensions to be handled by a specific view type.Array of file extensions (without the dot).
The view type that should handle these extensions.
void
Since: v0.9.7
Editor Extensions
registerEditorExtension()
Registers a CodeMirror 6 extension. To dynamically reconfigure extensions, pass an array that can be modified, then callWorkspace.updateOptions() to apply changes.
A CodeMirror 6 Extension or array of Extensions.
void
Since: v0.12.8
registerEditorSuggest()
Registers an EditorSuggest that provides live autocomplete suggestions while typing.The editor suggest instance to register.
void
Since: v0.12.7
Markdown Processing
registerMarkdownPostProcessor()
Registers a post processor to transform rendered markdown in reading mode.The post processor function:
(el: HTMLElement, ctx: MarkdownPostProcessorContext) => Promise<any> | voidOptional sort order to control when this processor runs relative to others.
MarkdownPostProcessor - The registered post processor.
Since: v0.9.7
registerMarkdownCodeBlockProcessor()
Registers a handler for fenced code blocks with a specific language. The<pre><code> wrapper is automatically removed, and a <div> is provided for custom rendering.
The language identifier for the code block (e.g., ‘mermaid’, ‘dataview’).
handler
(source: string, el: HTMLElement, ctx: MarkdownPostProcessorContext) => Promise<any> | void
required
Function that receives the code block source, container element, and context.
Optional sort order for execution priority.
MarkdownPostProcessor - The registered processor.
Since: v0.9.7
Protocol Handlers
registerObsidianProtocolHandler()
Registers a handler forobsidian:// URLs.
The action identifier (e.g., ‘open’ for
obsidian://open).Callback that receives the parsed URL parameters:
(params: ObsidianProtocolData) => anyvoid
Since: v0.11.0
CLI Integration
registerCliHandler()
Registers a CLI command handler. Command IDs must be globally unique.The command ID (use format
<plugin-id> or <plugin-id>:<action>).Description shown in help and autocomplete.
Command line flags configuration, or null if no flags needed.
The handler function to process CLI invocations.
void
Since: v1.12.2
Complete Example
Related Types
App- Main application interfaceComponent- Base class for lifecycle management (parent class of Plugin)PluginManifest- Plugin metadata interfaceCommand- Command registration interfaceViewCreator- Type alias for view factory functions:(leaf: WorkspaceLeaf) => ViewIconName- Type alias for icon identifiers (string)