Obsidian API

Obsidian is organized into several major modules that you interact with through the App instance (accessible via this.app inside your plugin):

• App: The global object that owns all other modules.
• Vault: Provides access to interact with files and folders within the vault.
• Workspace: Provides access to interact with panes on the screen.
• MetadataCache: Contains cached metadata for markdown files, including headings, links, embeds, tags, and blocks.

To start developing an Obsidian plugin, use the official sample plugin template as a foundation. This provides a working structure for a plugin that extends the Plugin class.

Template: https://github.com/obsidianmd/obsidian-sample-plugin

The main.js file is the main entry point of your plugin. It must follow these requirements:

1. Imports:
   • Import the Obsidian API using require('obsidian').
   • Import NodeJS or Electron APIs using require('fs') or require('electron') if isDesktopOnly is true.
2. Export: You must export a default class that extends the Plugin class.
3. Bundling: You must bundle all external dependencies into this single file using a JavaScript bundler like Rollup or Webpack.

To prevent memory leaks and ensure your plugin cleans up after itself, use the built-in registration methods instead of standard JavaScript listeners. These methods ensure that handlers are automatically detached when your plugin unloads.

App and Workspace Events

Use this.registerEvent for events from interfaces like App or Workspace:

this.registerEvent(app.on('event-name', callback));

DOM Events

Use this.registerDomEvent for DOM events on elements that persist on the page after your plugin unloads (e.g., window or document):

this.registerDomEvent(element, 'click', callback);

Intervals

Use this.registerInterval instead of setInterval:

this.registerInterval(setInterval(callback, 1000));

By inheriting from the Plugin class, you gain access to several methods to integrate your plugin into the Obsidian interface:

• this.addRibbonIcon: Add an icon to the left ribbon.
• this.addStatusBarItem: Add an element to the bottom status bar.
• this.addCommand: Add a global command (can include a default hotkey).
• this.addSettingTab: Add a plugin settings tab.
• this.registerView: Register a new kind of view.
• this.loadData / this.saveData: Save and load plugin data.

Every Obsidian plugin must include a manifest.json file in its root directory to define its identity and requirements.

Required and supported fields:

• id: The unique ID of your plugin.
• name: The display name of your plugin.
• author: The plugin author's name.
• version: The version of your plugin.
• minAppVersion: The minimum required Obsidian version for your plugin.
• description: A long description of your plugin.
• isDesktopOnly: Boolean indicating whether your plugin uses NodeJS or Electron APIs.
• authorUrl (optional): A URL to your website.
• fundingUrl (optional): A link for users to donate to support development.