Obsidian Plugins

https://docs.obsidian.md/plugins/
Admin
Obsidian Plugins is a developer documentation resource for creating and extending plugins for...
Tokens:34,030
Snippets:436
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Plugin Dependencies

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Install the necessary Node.js dependencies for the plugin. This command should be run from within the plugin's directory.

```bash
npm install
```

--------------------------------

### Add React dependencies

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Install React and ReactDOM as project dependencies. This is the first step to enable React in your plugin.

```bash
npm install react react-dom

```

--------------------------------

### Implement Declarative Settings with getSettingDefinitions

Source: https://docs.obsidian.md/plugins/guides/migrate-declarative-settings

Example of a PluginSettingTab using the declarative API to define settings via an array, replacing the imperative display() method.

```typescript
import { App, PluginSettingTab } from 'obsidian';

interface MySettings {
  enabled: boolean;
  mode: 'fast' | 'thorough';
  cacheKey: string;
}

class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  getSettingDefinitions() {
    return [
      {
        name: 'Enable feature',
        desc: 'Turns the feature on or off.',
        control: { type: 'toggle', key: 'enabled' },
      },
      {
        name: 'Mode',
        control: {
          type: 'dropdown',
          key: 'mode',
          defaultValue: 'fast',
          options: { fast: 'Fast', thorough: 'Thorough' },
        },
      },
      {
        name: 'Cache key',
        desc: 'Alphanumeric only.',
        control: {
          type: 'text',
          key: 'cacheKey',
          placeholder: 'default',
          validate: (value: string) =>
            /^[a-z0-9]*$/i.test(value.trim()) ? undefined : 'Use letters and digits only.',
        },
      },
    ];
  }
}
```

--------------------------------

### Compile Plugin with Development Server

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Compile the plugin's source code and start a development server. This command will automatically rebuild the plugin when source files are modified.

```bash
npm run dev
```

--------------------------------

### Imperative PluginSettingTab implementation

Source: https://docs.obsidian.md/plugins/guides/migrate-declarative-settings

The starting point for migration, showing a traditional PluginSettingTab that manually manages DOM elements and state updates within display().

```typescript
import { App, Plugin, PluginSettingTab, Setting } from 'obsidian';

interface MySettings {
  enabled: boolean;
  mode: 'fast' | 'thorough';
  cacheKey: string;
}

class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  display(): void {
    let { containerEl } = this;
    containerEl.empty();

    new Setting(containerEl)
      .setName('Enable feature')
      .setDesc('Turns the feature on or off.')
      .addToggle(toggle => toggle
        .setValue(this.plugin.settings.enabled)
        .onChange(async (value) => {
          this.plugin.settings.enabled = value;
          await this.plugin.saveData(this.plugin.settings);
        }));

    new Setting(containerEl)
      .setName('Mode')
      .addDropdown(dropdown => dropdown
        .addOption('fast', 'Fast')
        .addOption('thorough', 'Thorough')
        .setValue(this.plugin.settings.mode ?? 'fast')
        .onChange(async (value) => {
          this.plugin.settings.mode = value as 'fast' | 'thorough';
          await this.plugin.saveData(this.plugin.settings);
        }));

    new Setting(containerEl)
      .setName('Cache key')
      .setDesc('Alphanumeric only.')
      .addText(text => text
        .setValue(this.plugin.settings.cacheKey)
        .onChange(async (value) => {
          let trimmed = value.trim();
          if (!/^[a-z0-9]*$/i.test(trimmed)) return;
          this.plugin.settings.cacheKey = trimmed;
          await this.plugin.saveData(this.plugin.settings);
        }));
  }
}
```

--------------------------------

### Install Svelte dependencies

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+Svelte+in+your+plugin

Add Svelte and its related build tools to your plugin's development dependencies.

```bash
npm install --save-dev svelte svelte-preprocess esbuild-svelte svelte-check
```

--------------------------------

### Implement an imperative settings page

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Subclass SettingPage to handle dynamic UI rendering and custom logic. This example demonstrates manual DOM creation and integration via a factory function.

```typescript
import { SettingPage, Setting } from 'obsidian';

class StatusPage extends SettingPage {
  constructor(private plugin: MyPlugin) {
    super();
    this.title = 'Status';
  }

  display() {
    this.containerEl.empty();

    let stats = this.plugin.computeStats();
    this.containerEl.createEl('h3', { text: `${stats.totalEntries} entries` });
    this.containerEl.createEl('p', { text: `Last sync: ${stats.lastSync}` });

    new Setting(this.containerEl)
      .setName('Refresh now')
      .addButton((btn) => btn
        .setButtonText('Refresh')
        .onClick(async () => {
          await this.plugin.sync();
          this.display();
        }));
  }
}

// In getSettingDefinitions():
{
  type: 'page',
  name: 'Status',
  page: () => new StatusPage(this.plugin),
}
```

--------------------------------

### Illustrating State Changes

Source: https://docs.obsidian.md/Plugins/Editor/State+management

This example demonstrates how direct string assignments lose previous states, highlighting the need for a history-based approach for undo functionality.

```javascript
let note = '';
note = 'Heading'
note = '# Heading'
note = '## Heading' // How to undo this?
```

--------------------------------

### Create a Svelte component

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+Svelte+in+your+plugin

Define a basic Svelte component with state and props. This example includes a simple counter.

```svelte
<script lang="ts">
  interface Props {
    startCount: number;
  }

  let { 
    startCount
  }: Props = $props();

  let count = $state(startCount);

  export function increment() {
    count += 1;
  }
</script>

<div class="number">
  <span>My number is {count}!</span>
</div>

<style>
  .number {
    color: red;
  }
</style>

```

--------------------------------

### Initialize Plugin with Empty onload - TypeScript

Source: https://docs.obsidian.md/plugins/guides/bases-view

Start with a minimal plugin structure by removing unnecessary code and leaving only the onload function.

```typescript
export default class MyPlugin extends Plugin {
  async onload() {
  }
}
```

--------------------------------

### CSS Fallback Example for RTL Support

Source: https://docs.obsidian.md/Plugins/User+interface/Right-to-left

Use `@supports` to conditionally apply styles for newer CSS features like `:dir()`. This prevents older Obsidian versions from breaking. Split rules into fallback and modern versions.

```css
.supported,
.unsupported {
  /* this won't run */
}

.supported {
  /* this will run */
}

.unsupported {
  /* this won't run */
}

@supports selector(:dir(*)) {
  /* will run if :dir() is supported */
}
```

--------------------------------

### Importing Moment.js in Obsidian Plugin

Source: https://docs.obsidian.md/Plugins/Events

Import the Moment.js library directly from the Obsidian API for date and time manipulation. No external installation is required.

```typescript
import { moment } from 'obsidian';
```

--------------------------------

### Dispatching a Transaction to the Editor View

Source: https://docs.obsidian.md/Plugins/Editor/State+management

This example demonstrates how to dispatch a transaction to the editor view, grouping multiple state changes into a single undoable operation. This is useful for features like surrounding selected text with quotes.

```javascript
view.dispatch({
  changes: [
    { from: selectionStart, insert: `"` },
    { from: selectionEnd, insert: `"` }
  ]
});

```

--------------------------------

### Add React type definitions

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Install the development type definitions for React to enable type checking and autocompletion in your TypeScript project.

```bash
npm install --save-dev @types/react @types/react-dom

```

--------------------------------

### Initialize a Setting Tab Container

Source: https://docs.obsidian.md/Plugins/User+interface/HTML+elements

This snippet shows how to get the container element for a plugin's settings tab. This container is an `HTMLElement` that can be used to create custom UI elements.

```typescript
import { App, PluginSettingTab } from 'obsidian';

class ExampleSettingTab extends PluginSettingTab {
  plugin: ExamplePlugin;

  constructor(app: App, plugin: ExamplePlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  display(): void {
    // highlight-next-line
    let { containerEl } = this;

    // ...
  }
}

```

--------------------------------

### Get All Files

Source: https://docs.obsidian.md/Plugins/Vault

Retrieves all files within the vault, regardless of their type. Use this when you need to process all documents, not just Markdown.

```APIDOC
## Get All Files

### Description
Retrieves all files within the vault, regardless of their type. Use this when you need to process all documents, not just Markdown.

### Method
`app.vault.getFiles()`

### Returns
- `TFile[]`: An array of TFile objects representing all files in the vault.
```

--------------------------------

### Recording State Changes with ChangeSpec

Source: https://docs.obsidian.md/Plugins/Editor/State+management

This TypeScript example shows how to record state changes using `ChangeSpec` to build a history that supports undo operations.

```typescript
const changes: ChangeSpec[] = [];

changes.push({ from: 0, insert: 'Heading' });
changes.push({ from: 0, insert: '# ' });
changes.push({ from: 0, insert: '#' });
```

--------------------------------

### Define Custom CSS Styles for Elements

Source: https://docs.obsidian.md/Plugins/User+interface/HTML+elements

Provides example CSS rules for styling HTML elements within an Obsidian plugin. These styles can be added to a `styles.css` file in the plugin's root directory.

```css
.book {
  border: 1px solid var(--background-modifier-border);
  padding: 10px;
}

.book__title {
  font-weight: 600;
}

.book__author {
  color: var(--text-muted);
}

```

--------------------------------

### Handle Custom Markdown Code Blocks with registerMarkdownCodeBlockProcessor

Source: https://docs.obsidian.md/Plugins/Editor/Markdown+post+processing

Register a processor for specific code block languages (e.g., 'csv') to render them dynamically. This example parses CSV data into an HTML table.

```typescript
import {
  Plugin
} from 'obsidian';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.registerMarkdownCodeBlockProcessor('csv', (source, el, ctx) => {
      const rows = source.split('\n').filter((row) => row.length > 0);

      const table = el.createEl('table');
      const body = table.createEl('tbody');

      for (let i = 0; i < rows.length; i++) {
        const cols = rows[i].split(',');

        const row = body.createEl('tr');

        for (let j = 0; j < cols.length; j++) {
          row.createEl('td', { text: cols[j] });
        }
      }
    });
  }
}
```

--------------------------------

### Add Configuration Options to Bases View - TypeScript

Source: https://docs.obsidian.md/plugins/guides/bases-view

Enhance a custom Bases view by adding configuration options. This example demonstrates how to include a text input for a 'Property separator' in the view's settings menu, with a default value.

```typescript
export default class MyPlugin extends Plugin {
  async onload() {
    // Tell Obsidian about the new view type that this plugin provides.
    this.registerBasesView(ExampleViewType, {
      name: "Example",
      icon: 'lucide-graduation-cap',
      factory: (controller, containerEl) => {
        new MyBasesView(controller, containerEl)
      },
      options: () => ([
        {
          // The type of option. 'text' is a text input.
          type: 'text',
          // The name displayed in the settings menu.
          displayName: 'Property separator',
          // The value saved to the view settings.
          key: 'separator',
          // The default value for this option.
          default: ' - ',
        },
        // ...
    ]),
    });
  }
}
```

--------------------------------

### Updating Status Bar with Interval Timer

Source: https://docs.obsidian.md/Plugins/Events

Use `window.setInterval()` with `registerInterval()` to repeatedly call a function. This example updates the status bar every second with the current time.

```typescript
import { moment, Plugin } from 'obsidian';

export default class ExamplePlugin extends Plugin {
  statusBar: HTMLElement;

  async onload() {
    this.statusBar = this.addStatusBarItem();

    this.updateStatusBar();

    this.registerInterval(
      window.setInterval(() => this.updateStatusBar(), 1000)
    );
  }

  updateStatusBar() {
    this.statusBar.setText(moment().format('H:mm:ss'));
  }
}
```

--------------------------------

### Register vault event listener after layout is ready

Source: https://docs.obsidian.md/plugins/guides/load-time

To avoid issues with Obsidian's vault initialization, register vault event listeners within an `onLayoutReady` callback. This ensures the workspace is fully initialized before the listener starts reacting to events.

```typescript
class MyPlugin extends Plugin {
    onload(app: App) {
	    super(app);
        this.registerEvent(this.app.vault.on('create', this.onCreate, this));
    }

	onCreate() {
	    if (!this.app.workspace.layoutReady) {
	      // Workspace is still loading, do nothing
	      return;
	    }
		// ...
	}
}
```

```typescript
class MyPlugin extends Plugin {
    onload(app: App) {
	    super(app);
	    this.app.workspace.onLayoutReady(() => {
	        this.registerEvent(this.app.vault.on('create', this.onCreate, this));
	    });
    }

	onCreate() {
		// ...
	}
}
```

--------------------------------

### Use App context in a React component

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Demonstrates how to use the `useApp` custom hook within a React component to access the Obsidian `App` object, for example, to get the vault name.

```typescript
import { useApp } from './hooks';

export const ReactView = () => {
  const { vault } = useApp();

  return <h4>{vault.getName()}</h4>;
};

```

--------------------------------

### Implement persistent plugin settings

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Demonstrates the structure for defining, loading, and saving plugin settings to disk.

```typescript
import { Plugin } from 'obsidian';
import { ExampleSettingTab } from './settings';

interface ExamplePluginSettings {
  sampleValue: string;
}

const DEFAULT_SETTINGS: Partial<ExamplePluginSettings> = {
  sampleValue: 'Lorem ipsum',
};

export default class ExamplePlugin extends Plugin {
  settings: ExamplePluginSettings;

  async onload() {
    await this.loadSettings();

    this.addSettingTab(new ExampleSettingTab(this.app, this));
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}
```

--------------------------------

### Using Obsidian API for Pop-Out Window Compatibility

Source: https://docs.obsidian.md/plugins/guides/pop-out-windows

Illustrates the correct way to append elements and perform instance checks in pop-out windows using Obsidian's provided APIs like `activeDocument`, `element.doc`, and `element.instanceOf()`.

```typescript
let myElement: HTMLElement = ...;

// Bad: myElement would be added to the currently focused document, which is not necessarily the one you want
activeDocument.body.appendChild(myElement);
// Good: This will append myElement to the same window as someElement
someElement.doc.body.appendChild(myElement);

// This will work correctly in pop-out windows
if (myElement.instanceOf(HTMLElement)) {

}

element.on('click', '.my-css-class', (event) => {
    // This will work correctly in pop-out windows
    if (event.instanceOf(MouseEvent)) {

    }
}

```

--------------------------------

### Get Active Editor

Source: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Access the editor of the active note using app.workspace.activeEditor?.editor. This provides a safe way to get the editor instance, returning undefined if no active editor is available.

```typescript
const editor = this.app.workspace.activeEditor?.editor;

if (editor) {
    // ...
}
```

--------------------------------

### Implement a Settings List

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use the 'list' type for collections that require adding, removing, or reordering entries.

```javascript
{
  type: 'list',
  heading: 'Watched folders',
  emptyState: 'No folders being watched yet.',
  addItem: {
    name: 'Add folder',
    action: () => this.openAddFolderModal(),
  },
  onReorder: async (oldIndex, newIndex) => {
    let folders = this.plugin.settings.folders;
    let [moved] = folders.splice(oldIndex, 1);
    folders.splice(newIndex, 0, moved);
    await this.plugin.saveData(this.plugin.settings);
  },
  onDelete: async (idx) => {
    this.plugin.settings.folders.splice(idx, 1);
    await this.plugin.saveData(this.plugin.settings);
    this.update();
  },
  items: this.plugin.settings.folders.map((path) => ({
    name: path,
    searchable: false,
  })),
}
```

--------------------------------

### Get Markdown Files

Source: https://docs.obsidian.md/Plugins/Vault

Retrieves all Markdown files within the vault. This is useful for operations that specifically target Markdown documents.

```APIDOC
## Get Markdown Files

### Description
Retrieves all Markdown files within the vault. This is useful for operations that specifically target Markdown documents.

### Method
`app.vault.getMarkdownFiles()`

### Returns
- `TFile[]`: An array of TFile objects representing the Markdown files.
```

--------------------------------

### Create a basic View Plugin

Source: https://docs.obsidian.md/Plugins/Editor/View+plugins

Implement a class extending PluginValue and use ViewPlugin.fromClass() to create a view plugin. The constructor initializes the plugin, update() handles changes, and destroy() cleans up resources.

```typescript
import {
  ViewUpdate,
  PluginValue,
  EditorView,
  ViewPlugin,
} from '@codemirror/view';

class ExamplePlugin implements PluginValue {
  constructor(view: EditorView) {
    // ...
  }

  update(update: ViewUpdate) {
    // ...
  }

  destroy() {
    // ...
  }
}

export const examplePlugin = ViewPlugin.fromClass(ExamplePlugin);

```

--------------------------------

### Clone Sample Plugin

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Clone the sample Obsidian plugin from its GitHub repository into the plugins directory. Remember to use the URL of your own repository if you've created a fork.

```bash
git clone https://github.com/obsidianmd/obsidian-sample-plugin.git
```

--------------------------------

### Import Notice and Plugin

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Import the necessary classes from the Obsidian API. `Notice` is used for displaying temporary messages to the user.

```typescript
import { Notice, Plugin } from 'obsidian';
```

--------------------------------

### Implement Dual Support for Settings

Source: https://docs.obsidian.md/plugins/guides/migrate-declarative-settings

Maintain both getSettingDefinitions() for newer Obsidian versions and display() for legacy versions to ensure consistent settings across all user environments.

```typescript
import { App, PluginSettingTab, Setting } from 'obsidian';

interface MySettings {
  enabled: boolean;
  mode: 'fast' | 'thorough';
  cacheKey: string;
}

class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  // 1.13.0+: Obsidian calls this and skips display().
  // Controls auto-bind to this.plugin.settings[key].
  getSettingDefinitions() {
    return [
      {
        name: 'Enable feature',
        desc: 'Turns the feature on or off.',
        control: { type: 'toggle', key: 'enabled' },
      },
      {
        name: 'Mode',
        control: {
          type: 'dropdown',
          key: 'mode',
          defaultValue: 'fast',
          options: { fast: 'Fast', thorough: 'Thorough' },
        },
      },
      {
        name: 'Cache key',
        desc: 'Alphanumeric only.',
        control: {
          type: 'text',
          key: 'cacheKey',
          placeholder: 'default',
          validate: (value: string) =>
            /^[a-z0-9]*$/i.test(value.trim()) ? undefined : 'Use letters and digits only.',
        },
      },
    ];
  }

  // < 1.13.0: Obsidian calls this. Keep your original imperative implementation.
  display(): void {
    let { containerEl } = this;
    containerEl.empty();

    new Setting(containerEl)
      .setName('Enable feature')
      .setDesc('Turns the feature on or off.')
      .addToggle(toggle => toggle
        .setValue(this.plugin.settings.enabled)
        .onChange(async (value) => {
          this.plugin.settings.enabled = value;
          await this.plugin.saveData(this.plugin.settings);
        }));

    // …mode and cacheKey settings unchanged from Before
  }
}
```

--------------------------------

### Plugin Lifecycle with Console Logging

Source: https://docs.obsidian.md/Plugins/Getting+started/Anatomy+of+a+plugin

Demonstrates how to add console logs to the onload and onunload methods to monitor plugin lifecycle events.

```typescript
import { Plugin } from 'obsidian';

export default class ExamplePlugin extends Plugin {
  async onload() {
    console.log('loading plugin')
  }
  async onunload() {
    console.log('unloading plugin')
  }
}
```

--------------------------------

### Get Active Markdown View

Source: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Use getActiveViewOfType(MarkdownView) to safely access the active Markdown view. It returns null if the active view is not a MarkdownView or if there is no active view.

```typescript
const view = this.app.workspace.getActiveViewOfType(MarkdownView);

// getActiveViewOfType will return null if the active view is null, or if it's not a MarkdownView.
if (view) {
  // ...
}
```

--------------------------------

### Mount a Svelte component in an Obsidian ItemView

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+Svelte+in+your+plugin

Demonstrates how to mount a Svelte component into an Obsidian ItemView's content element and interact with its methods.

```typescript
import { ItemView, WorkspaceLeaf } from 'obsidian';

// Import the Counter Svelte component and the `mount` and `unmount` methods.
import Counter from './Counter.svelte';
import { mount, unmount } from 'svelte';

export const VIEW_TYPE_EXAMPLE = 'example-view';

export class ExampleView extends ItemView {
  // A variable to hold on to the Counter instance mounted in this ItemView.
  counter: ReturnType<typeof Counter> | undefined;

  constructor(leaf: WorkspaceLeaf) {
    super(leaf);
  }

  getViewType() {
    return VIEW_TYPE_EXAMPLE;
  }

  getDisplayText() {
    return 'Example view';
  }

  async onOpen() {
    // Attach the Svelte component to the ItemViews content element and provide the needed props.
    this.counter = mount(Counter, {
      target: this.contentEl,
      props: {
        startCount: 5,
      }
    });

    // Since the component instance is typed, the exported `increment` method is known to TypeScript.
    this.counter.increment();
  }

  async onClose() {
    if (this.counter) {
      // Remove the Counter from the ItemView.
      unmount(this.counter);
    }
  }
}

```

--------------------------------

### Implement nested settings with dot-notation

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use path-walking helper functions to support nested JSON structures in settings. This approach requires manual implementation of path resolution and object creation.

```typescript
interface MySettings {
  editor: { fontSize: number; tabSize: number };
  sync: { enabled: boolean; interval: number };
}

function getPath(obj: Record<string, unknown>, path: string): unknown {
  let cursor: unknown = obj;
  for (let part of path.split('.')) {
    if (cursor === null || typeof cursor !== 'object') return undefined;
    cursor = (cursor as Record<string, unknown>)[part];
  }
  return cursor;
}

function setPath(obj: Record<string, unknown>, path: string, value: unknown): void {
  let parts = path.split('.');
  let last = parts.pop()!;
  let cursor: Record<string, unknown> = obj;
  for (let part of parts) {
    let next = cursor[part];
    if (next === null || typeof next !== 'object') {
      next = {};
      cursor[part] = next;
    }
    cursor = next as Record<string, unknown>;
  }
  cursor[last] = value;
}

class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

  constructor(app: App, plugin: MyPlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  getControlValue(key: string): unknown {
    return getPath(this.plugin.settings, key);
  }

  async setControlValue(key: string, value: unknown): Promise<void> {
    setPath(this.plugin.settings, key, value);
    await this.plugin.saveData(this.plugin.settings);
  }

  getSettingDefinitions() {
    return [
      {
        type: 'group',
        heading: 'Editor',
        items: [
          { name: 'Font size', control: { type: 'number', key: 'editor.fontSize', min: 8, max: 32 } },
          { name: 'Tab size', control: { type: 'number', key: 'editor.tabSize', min: 1, max: 8 } },
        ],
      },
      {
        type: 'group',
        heading: 'Sync',
        items: [
          { name: 'Enable sync', control: { type: 'toggle', key: 'sync.enabled' } },
          {
            name: 'Interval (seconds)',
            visible: () => this.plugin.settings.sync.enabled,
            control: { type: 'number', key: 'sync.interval', min: 5 },
          },
        ],
      },
    ];
  }
}
```

--------------------------------

### Use DOM API or Obsidian helpers

Source: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Prefer using Obsidian's helper functions like `createEl()`, `createDiv()`, and `createSpan()` or the standard DOM API for creating and manipulating HTML elements to ensure security and consistency.

```typescript
let containerElement = document.querySelector('.my-container');
// DO THIS
let div = containerElement.createDiv({
  cls: 'my-class'
});
div.createEl('b', { text: 'Your name is: ' });
div.createSpan({ text: name });
```

--------------------------------

### Create headings using `setHeading()`

Source: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Use the `Setting` class's `setHeading()` method to create consistent and properly styled headings within your plugin's settings UI, rather than using raw HTML heading elements.

```typescript
new Setting(containerEl).setName('your heading title').setHeading();
```

--------------------------------

### Handle user input in a Modal

Source: https://docs.obsidian.md/Plugins/User+interface/Modals

Use the Setting class to add input fields and buttons, passing data back via a callback.

```typescript
import { App, Modal, Setting } from 'obsidian';

export class ExampleModal extends Modal {
  constructor(app: App, onSubmit: (result: string) => void) {
    super(app);
	this.setTitle('What\'s your name?');

	let name = '';
    new Setting(this.contentEl)
      .setName('Name')
      .addText((text) =>
        text.onChange((value) => {
          name = value;
        }));

    new Setting(this.contentEl)
      .addButton((btn) =>
        btn
          .setButtonText('Submit')
          .setCta()
          .onClick(() => {
            this.close();
            onSubmit(name);
          }));
  }
}
```

```typescript
new ExampleModal(this.app, (result) => {
  new Notice(`Hello, ${result}!`);
}).open();
```

--------------------------------

### Implement legacy imperative settings tab

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use this approach for plugins with a minAppVersion below 1.13.0 by overriding the display() method.

```typescript
import ExamplePlugin from './main';
import { App, PluginSettingTab, Setting } from 'obsidian';

export class ExampleSettingTab extends PluginSettingTab {
  plugin: ExamplePlugin;

  constructor(app: App, plugin: ExamplePlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  display(): void {
    let { containerEl } = this;

    containerEl.empty();

    new Setting(containerEl)
      .setName('Default value')
      .addText((text) =>
        text
          .setPlaceholder('Lorem ipsum')
          .setValue(this.plugin.settings.sampleValue)
          .onChange(async (value) => {
            this.plugin.settings.sampleValue = value;
            await this.plugin.saveSettings();
          })
      );
  }
}
```

--------------------------------

### Create Styled HTML Elements with CSS Classes

Source: https://docs.obsidian.md/Plugins/User+interface/HTML+elements

Illustrates how to apply CSS classes to newly created HTML elements using the `cls` property in `createEl()`. This allows for custom styling defined in a CSS file.

```typescript
const book = containerEl.createEl('div', { cls: 'book' });
book.createEl('div', { text: 'How to Take Smart Notes', cls: 'book__title' });
book.createEl('small', { text: 'Sönke Ahrens', cls: 'book__author' });

```

--------------------------------

### Mount React component using createRoot

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Mount a React component to an HTML element, typically `this.contentEl`, using `createRoot` from `react-dom/client`. Ensure to import necessary modules from React and Obsidian.

```typescript
import { StrictMode } from 'react';
import { ItemView, WorkspaceLeaf } from 'obsidian';
import { Root, createRoot } from 'react-dom/client';
import { ReactView } from './ReactView';

const VIEW_TYPE_EXAMPLE = 'example-view';

class ExampleView extends ItemView {
	root: Root | null = null;

	constructor(leaf: WorkspaceLeaf) {
		super(leaf);
	}

	getViewType() {
		return VIEW_TYPE_EXAMPLE;
	}

	getDisplayText() {
		return 'Example view';
	}

	async onOpen() {
		this.root = createRoot(this.contentEl);
		this.root.render(
			<StrictMode>
				<ReactView />,
			</StrictMode>,
		);
	}

	async onClose() {
		this.root?.unmount();
	}
}

```

--------------------------------

### Registering a File Creation Event

Source: https://docs.obsidian.md/Plugins/Events

Subscribe to file creation events using `app.vault.on('create')`. Ensure event handlers are detached when the plugin unloads by using `registerEvent()`.

```typescript
import { Plugin } from 'obsidian';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.registerEvent(this.app.vault.on('create', () => {
      console.log('a new file has entered the arena')
    }));
  }
}
```

--------------------------------

### Implement a custom render callback

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use a render callback for settings requiring custom UI or side effects. Ensure manual saving of settings as this method does not auto-save.

```javascript
{
  name: 'Enable feature X',
  render: (setting) => {
    setting.addToggle((toggle) => toggle
      .setValue(this.plugin.settings.featureX)
      .onChange(async (value) => {
        this.plugin.settings.featureX = value;
        this.plugin.applyFeatureX();
        await this.plugin.saveData(this.plugin.settings);
      }));
  },
}
```

--------------------------------

### Open a Modal

Source: https://docs.obsidian.md/Plugins/User+interface/Modals

Instantiate the modal class and call the open method within a plugin command.

```typescript
import { Plugin } from 'obsidian';
import { ExampleModal } from './modal';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: 'display-modal',
      name: 'Display modal',
      callback: () => {
        new ExampleModal(this.app).open();
      },
    });
  }
}
```

--------------------------------

### Add Ribbon Icon and Action

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Add a custom icon to the Obsidian ribbon. When clicked, this icon will display a 'Hello, world!' notice to the user.

```typescript
this.addRibbonIcon('dice', 'Greet', () => {
  new Notice('Hello, world!');
});
```

--------------------------------

### Create a Heading in Settings

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Adds a heading to a setting container.

```typescript
new Setting(containerEl).setName('Defaults').setHeading();
```

--------------------------------

### Create GitHub Actions Release Workflow

Source: https://docs.obsidian.md/Plugins/Releasing/Release+your+plugin+with+GitHub+Actions

This YAML file defines a GitHub Actions workflow that triggers on tag pushes. It checks out the code, sets up Node.js, builds the plugin, and creates a draft GitHub release with the built assets.

```yaml
name: Release Obsidian plugin

on:
  push:
    tags:
      - "*"

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v3

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18.x"

      - name: Build plugin
        run: |
          npm install
          npm run build

      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          tag="${GITHUB_REF#refs/tags/}"

          gh release create "$tag" \
            --title="$tag" \
            --draft \
            main.js manifest.json styles.css

```

--------------------------------

### Create a basic Modal

Source: https://docs.obsidian.md/Plugins/User+interface/Modals

Define a class extending Modal to display information to the user.

```typescript
import { App, Modal } from 'obsidian';

export class ExampleModal extends Modal {
  constructor(app: App) {
    super(app);
	this.setContent('Look at me, I\'m a modal! 👀')
  }
}
```

--------------------------------

### Import Svelte build tools in esbuild.config.mjs

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+Svelte+in+your+plugin

Add necessary imports for esbuild-svelte and svelte-preprocess to your esbuild configuration file.

```javascript
import esbuildSvelte from 'esbuild-svelte';
import { sveltePreprocess } from 'svelte-preprocess';

```

--------------------------------

### Implement a SuggestModal

Source: https://docs.obsidian.md/Plugins/User+interface/Modals

Extend SuggestModal to provide a searchable list of items with custom rendering.

```typescript
import { App, Notice, SuggestModal } from 'obsidian';

interface Book {
  title: string;
  author: string;
}

const ALL_BOOKS = [
  {
    title: 'How to Take Smart Notes',
    author: 'Sönke Ahrens',
  },
  {
    title: 'Thinking, Fast and Slow',
    author: 'Daniel Kahneman',
  },
  {
    title: 'Deep Work',
    author: 'Cal Newport',
  },
];

export class ExampleModal extends SuggestModal<Book> {
  // Returns all available suggestions.
  getSuggestions(query: string): Book[] {
    return ALL_BOOKS.filter((book) =>
      book.title.toLowerCase().includes(query.toLowerCase())
    );
  }

  // Renders each suggestion item.
  renderSuggestion(book: Book, el: HTMLElement) {
    el.createEl('div', { text: book.title });
    el.createEl('small', { text: book.author });
  }

  // Perform action on the selected suggestion.
  onChooseSuggestion(book: Book, evt: MouseEvent | KeyboardEvent) {
    new Notice(`Selected ${book.title}`);
  }
}
```

--------------------------------

### Create React App context

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Create a React Context to provide the Obsidian `App` object globally to your React components. This avoids prop drilling.

```typescript
import { createContext } from 'react';
import { App } from 'obsidian';

export const AppContext = createContext<App | undefined>(undefined);

```

--------------------------------

### Define a declarative settings page

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use a configuration object to define page structure, including groups and various control types. This approach enables automatic rendering and integration with global settings search.

```javascript
{
  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() },
      ],
    },
  ],
}
```

--------------------------------

### Create Nested HTML Elements

Source: https://docs.obsidian.md/Plugins/User+interface/HTML+elements

Shows how to create a `<div>` element and then add nested `<div>` and `<small>` elements within it, assigning text content to each.

```typescript
const book = containerEl.createEl('div');
book.createEl('div', { text: 'How to Take Smart Notes' });
book.createEl('small', { text: 'Sönke Ahrens' });

```

--------------------------------

### Implement Settings Persistence

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use loadData and saveData to handle settings storage, with helper methods for easier access.

```typescript
export default class ExamplePlugin extends Plugin {

  // ...

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}
```

```typescript
async onload() {
  await this.loadSettings();

  // ...
}
```

--------------------------------

### render(setting: Setting)

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

A callback function used to define custom UI components within a setting row. It is used when simple bindings are insufficient.

```APIDOC
## render(setting: Setting)

### Description
Defines custom UI elements for a setting row. Use this for side effects, custom controls, or complex UI logic. Note that manual saving via `this.plugin.saveData()` is required within this callback.

### Parameters
- **setting** (Setting) - The setting object instance to which the custom UI is attached.

### Cleanup
If the callback initializes resources that outlive the DOM (e.g., `ResizeObserver`, `setInterval`), return a cleanup function. This function is invoked by Obsidian before the row is removed.
```

--------------------------------

### Create Git Tag for Release

Source: https://docs.obsidian.md/Plugins/Releasing/Release+your+plugin+with+GitHub+Actions

Create an annotated Git tag for a new release, ensuring the tag name matches the version in `manifest.json`. Push the tag to the remote repository to trigger the GitHub Actions workflow.

```bash
git tag -a 1.0.1 -m "1.0.1"
git push origin 1.0.1

```

--------------------------------

### Emulate Mobile Device on Desktop

Source: https://docs.obsidian.md/Plugins/Getting+started/Mobile+development

Enable mobile emulation in Obsidian Developer Tools to test your plugin on a simulated mobile environment. Disable it to return to the desktop view.

```javascript
this.app.emulateMobile(true);
```

```javascript
this.app.emulateMobile(false);
```

```javascript
this.app.emulateMobile(!this.app.isMobile);
```

--------------------------------

### Implement Search with Suggestions

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Integrates a searchable input field using the AbstractInputSuggest class.

```typescript
new Setting(containerEl)
  .setName('Search')
  .addSearch((search) => {
    search.setValue(this.plugin.settings.icon)
      .setPlaceholder('Search for an icon')
      .onChange(async (value) => {
        this.plugin.settings.icon = value;
        await this.plugin.saveSettings();
      });
    new IconSuggest(this.plugin.app, search.inputEl);
  });
```

--------------------------------

### Open Context Menu at Mouse Event - TypeScript

Source: https://docs.obsidian.md/Plugins/User+interface/Context+menus

Use `Menu.showAtMouseEvent()` to display a custom context menu at the user's click location. Ensure the `Menu` class is imported from 'obsidian'.

```typescript
import { Menu, Notice, Plugin } from 'obsidian';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.addRibbonIcon('dice', 'Open menu', (event) => {
      const menu = new Menu();

      menu.addItem((item) =>
        item
          .setTitle('Copy')
          .setIcon('documents')
          .onClick(() => {
            new Notice('Copied');
          })
      );

      menu.addItem((item) =>
        item
          .setTitle('Paste')
          .setIcon('paste')
          .onClick(() => {
            new Notice('Pasted');
          })
      );

      menu.showAtMouseEvent(event);
    });
  }
}
```

--------------------------------

### Avoid Top-Level Headings in Settings

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Do not include a plugin-name heading at the top of the settings tab as the sidebar already provides this context.

```javascript
// ❌ Don't
return [
  { type: 'group', heading: 'My Plugin', items: [/* … */] },
];

// ✅ Do
return [
  { name: 'Foo', control: { type: 'toggle', key: 'foo' } },
  { name: 'Bar', control: { type: 'toggle', key: 'bar' } },
];
```

--------------------------------

### List all Markdown files in a Vault

Source: https://docs.obsidian.md/Plugins/Vault

Recursively prints the paths of all Markdown files in the vault. Use `getFiles()` to list all file types.

```typescript
const files = this.app.vault.getMarkdownFiles()

for (let i = 0; i < files.length; i++) {
  console.log(files[i].path);
}
```

--------------------------------

### Avoid Iterating Files: Use Vault Methods

Source: https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines

Instead of iterating through all files, use Vault.getFileByPath, Vault.getFolderByPath, or Vault.getAbstractFileByPath for efficient file retrieval. This is crucial for performance with large vaults.

```typescript
this.app.vault.getFiles().find(file => file.path === filePath);
```

```typescript
const filePath = 'folder/file.md';
// if you want to get a file
const file = this.app.vault.getFileByPath(filePath);
```

```typescript
const folderPath = 'folder';
// or if you want to get a folder
const folder = this.app.vault.getFolderByPath(folderPath);
```

```typescript
const abstractFile = this.app.vault.getAbstractFileByPath(filePath);

if (file instanceof TFile) {
	// it's a file
}
if (file instanceof TFolder) {
	// it's a folder
}
```

--------------------------------

### Define a Setting Group

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use a SettingDefinitionGroup to organize related settings under a shared heading and layout.

```javascript
{
  type: 'group',
  heading: 'Advanced',
  items: [
    { name: 'Debug logging', control: { type: 'toggle', key: 'debug' } },
    { name: 'Cache size (MB)', control: { type: 'number', key: 'cacheMb', min: 1 } },
  ],
}
```

--------------------------------

### Navigate to Obsidian Plugins Directory

Source: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin

Change directory to the .obsidian/plugins folder within your vault. This is where Obsidian looks for community plugins.

```bash
cd path/to/vault
mkdir .obsidian/plugins
cd .obsidian/plugins
```

--------------------------------

### SettingList

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Defines a list of items that can be added, removed, or reordered by the user.

```APIDOC
## SettingList

### Description
Creates a list interface for managing collections of items. Supports drag-and-drop reordering, deletion, and custom add actions.

### Properties
- **type** (string) - Required - Must be 'list'.
- **heading** (string) - Optional - The title displayed for the list.
- **emptyState** (string|DocumentFragment) - Optional - Content shown when the list is empty.
- **addItem** (object) - Optional - Configuration for the add affordance (name, action).
- **onReorder** (function) - Optional - Async callback (oldIndex, newIndex) triggered after reordering.
- **onDelete** (function) - Optional - Async callback (index) triggered when an item is deleted.
- **items** (array) - Required - Array of item objects containing name, searchable, and optional action.
```

--------------------------------

### Register a Basic Command

Source: https://docs.obsidian.md/Plugins/User+interface/Commands

Register a new command by calling `addCommand()` within the plugin's `onload()` method. This command can be invoked from the Command Palette or via a hotkey.

```typescript
import {
  Plugin
} from 'obsidian';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: 'print-greeting-to-console',
      name: 'Print greeting to console',
      callback: () => {
        console.log('Hey, you!');
      },
    });
  }
}
```

--------------------------------

### Register an Editor Command

Source: https://docs.obsidian.md/Plugins/User+interface/Commands

Utilize `editorCallback()` to create commands that require access to the active editor instance. The callback receives the `editor` and `view` as arguments.

```typescript
this.addCommand({
  id: 'example-command',
  name: 'Example command',
  editorCallback: (editor: Editor, view: MarkdownView) => {
    const sel = editor.getSelection()

    console.log(`You have selected: ${sel}`);
  },
})
```

--------------------------------

### Initialize Default Settings

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use Object.assign to merge loaded data with default values, ensuring missing settings are populated.

```typescript
Object.assign({}, DEFAULT_SETTINGS, await this.loadData())
```

```typescript
const DEFAULT_SETTINGS: Partial<ExamplePluginSettings> = {
  sampleValue: 'Lorem ipsum',
};
```

--------------------------------

### Add svelte-check script to package.json

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+Svelte+in+your+plugin

Include a script in your package.json to easily run svelte-check for type checking your Svelte components.

```json
{
  // ...
  "scripts": {
    // ...
    "svelte-check": "svelte-check --tsconfig tsconfig.json"
  }
}

```

--------------------------------

### Define a settings tab class

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Implements a settings tab by extending PluginSettingTab and providing declarative setting definitions.

```typescript
import ExamplePlugin from './main';
import { App, PluginSettingTab } from 'obsidian';

export class ExampleSettingTab extends PluginSettingTab {
  plugin: ExamplePlugin;

  constructor(app: App, plugin: ExamplePlugin) {
    super(app, plugin);
    this.plugin = plugin;
  }

  getSettingDefinitions() {
    return [
      {
        name: 'Default value',
        control: {
          type: 'text',
          key: 'sampleValue',
          placeholder: 'Lorem ipsum',
        },
      },
    ];
  }
}
```

--------------------------------

### Structure Settings with Multiple Sections

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use headings only when there are two or more distinct sections, leaving general settings at the top without a heading.

```javascript
return [
  // General — no heading
  { name: 'Default folder', control: { type: 'folder', key: 'folder' } },
  { name: 'Open on launch', control: { type: 'toggle', key: 'openOnLaunch' } },

  // Subsequent sections get headings
  { type: 'group', heading: 'Appearance', items: [/* … */] },
  { type: 'group', heading: 'Advanced', items: [/* … */] },
];
```

--------------------------------

### Register and Activate Custom View in Plugin

Source: https://docs.obsidian.md/Plugins/User+interface/Views

Register your custom view using registerView() in the plugin's onload method. Add a ribbon icon to activate the view using a custom activateView method.

```typescript
import { Plugin, WorkspaceLeaf } from 'obsidian';
import { ExampleView, VIEW_TYPE_EXAMPLE } from './view';

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.registerView(
      VIEW_TYPE_EXAMPLE,
      (leaf) => new ExampleView(leaf)
    );

    this.addRibbonIcon('dice', 'Activate view', () => {
      this.activateView();
    });
  }

  async onunload() {
  }

  async activateView() {
    const { workspace } = this.app;

    let leaf: WorkspaceLeaf | null = null;
    const leaves = workspace.getLeavesOfType(VIEW_TYPE_EXAMPLE);

    if (leaves.length > 0) {
      // A leaf with our view already exists, use that
      leaf = leaves[0];
    } else {
      // Our view could not be found in the workspace, create a new leaf
      // in the right sidebar for it
      leaf = workspace.getRightLeaf(false);
      await leaf.setViewState({ type: VIEW_TYPE_EXAMPLE, active: true });
    }

    // "Reveal" the leaf in case it is in a collapsed sidebar
    workspace.revealLeaf(leaf);
  }
}

```

--------------------------------

### Define a folder control

Source: https://docs.obsidian.md/Plugins/User+interface/Settings

Use the folder control type to select a directory path.

```javascript
{
  name: 'Output folder',
  control: { type: 'folder', key: 'outputDir', includeRoot: true },
}
```

--------------------------------

### Create a basic React component

Source: https://docs.obsidian.md/Plugins/Getting+started/Use+React+in+your+plugin

Define a simple React functional component that can be imported and used within your plugin.

```typescript
export const ReactView = () => {
  return <h4>Hello, React!</h4>;
};

```
Tokens:
Raw