Obsidian Developer Documentation

For technical support, feedback, or community interaction, you can use the following channels:

• Discord: Join the #plugin-dev and #theme-dev channels.
• Obsidian Forum: Use the Developers & API section for technical discussions and the Share & showcase section to show your work.

A State Field is an editor extension used to manage custom editor state. It does not store state directly; instead, it manages it by taking the current state, applying any pending State Effects within a transaction, and returning a new state.

State fields are useful for maintaining data that is not part of the document text itself, such as calculator values, UI states, or custom metadata that needs to persist across editor updates.

As of Obsidian 1.6, --bold-modifier is the recommended way to adjust the weight of bolded text. Unlike setting a fixed weight, the modifier value stacks on top of existing font weights. This allows for hierarchical bolding (e.g., making text inside a heading even heavier).

Recommended values for --bold-modifier are between 100 and 300.

/* Example: Adjusting how much extra weight bold text gets */
:root {
  --bold-modifier: 200;
}

Obsidian exposes abstracted variables for core design tokens. Use these to ensure consistent spacing, typography, and color application across your custom UI or plugin elements. Key categories include:

• Colors: Theming colors and semantic color roles.
• Spacing: Standardized margins, paddings, and gaps.
• Typography: Font sizes, weights, and families.
• Borders & Radiuses: Standardized border widths and corner rounding.
• Icons: Variables for icon sets used in the UI.

A SettingDefinitionPage is a navigable entry on a parent tab. Use them to prevent parent tabs from becoming too long. Pages can be nested, but names must be unique among siblings at the same depth.

Declarative pages are defined by an items array. Obsidian renders the UI automatically based on the definitions provided.

{
  type: 'page',
  name: 'Advanced',
  desc: 'Power-user options.',
  items: [
    { name: 'Debug logging', control: { type: 'toggle', key: 'debug' } },
    { name: 'Verbose errors', control: { type: 'toggle', key: 'verbose' } },
    {
      type: 'group',
      heading: 'Cache',
      items: [
        { name: 'Cache size (MB)', control: { type: 'slider', key: 'cacheMb', min: 1, max: 500, step: 1 } },
        { name: 'Clear cache', action: () => this.plugin.clearCache() },
      ],
    },
  ],
}

The Workspace class is the central authority for managing the Obsidian application's layout, including sidebars (ribbons), splits, and leaves (individual views). It extends Events, allowing you to listen to workspace-wide lifecycle events.

Key Concepts

• Leaves: The individual view containers (e.g., a file editor, a search view, or a canvas).
• Splits: Containers that hold leaves or other splits (e.g., rootSplit, leftSplit, rightSplit).
• Layout Readiness: Because the layout is initialized asynchronously, you should use onLayoutReady() instead of checking layoutReady directly to ensure the UI is stable before interacting with it.

The Tasks class is used to manage and track a collection of asynchronous operations (tasks). It allows you to add individual callbacks or Promises to a queue and provides a way to wait for all registered tasks to complete. This is useful for coordinating multiple asynchronous actions within a plugin or script.

// Example conceptual usage of the Tasks class
const tasks = new Tasks();

// Add a callback-based task
tasks.add(() => {
  console.log("Task completed");
});

// Add a Promise-based task
tasks.addPromise(fetch('https://api.example.com'));

// Wait for all tasks to finish
await tasks.promise();

To style the application shell (the 'window chrome'), use variables related to the window's structural components:

• Ribbon & Status bar: The sidebars and bottom bars.
• Scrollbar: Customizing the appearance of scrollbars.
• Workspace & Window frame: The main workspace area and the outer window frame.
• Divider: The lines separating different panes.

The id property is a required string for plugins. It must follow these constraints:

• Use only lowercase letters and hyphens.
• It cannot end with the word plugin.
• It cannot contain the word obsidian.

Important for local development: The id must match the plugin's folder name. If they do not match, certain methods like onExternalSettingsChange will not be triggered.

The navigation property (inherited from View) determines how the view interacts with the Obsidian workspace navigation model.

• Set navigation to false: For static views that do not change the active file or context (e.g., a File Explorer, a Calendar, or a static dashboard).
• Set navigation to true: For views that open a file or can be navigated away from (e.g., a Markdown editor, a Kanban board, or a PDF viewer).