Obsidian Developer Docs

https://docs.obsidian.md/
Admin
Obsidian Developer Docs provides resources and guides for building plugins and themes to extend the...
Tokens:268,944
Snippets:4,052
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Frontmatter YAML Example

Source: https://docs.obsidian.md/Reference/TypeScript+API/CachedMetadata/frontmatter

An example of YAML frontmatter configuration.

```yaml
aliases: "CachedMetadata.frontmatter"
cssclasses: hide-title
```

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

### Install plugin dependencies

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

Install the necessary project dependencies using npm.

```bash
npm install
```

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

### BasesConfigFile properties configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesConfigFile/properties

Example of setting properties in the configuration file.

```yaml
aliases: "BasesConfigFile.properties"
cssclasses: hide-title
```

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

### Vault.process usage example

Source: https://docs.obsidian.md/Reference/TypeScript+API/Vault/process

An example showing how to use Vault.process to replace text within a file.

```typescript
app.vault.process(file, (data) => {
 return data.replace('Hello', 'World');
});
```

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

### Instruction Frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/Instruction

Example of the frontmatter configuration for an Instruction page.

```yaml
aliases: "Instruction"
cssclasses: hide-title
```

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

### Install React type definitions

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

Add the necessary TypeScript type definitions for React development.

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

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

### Command.callback usage example

Source: https://docs.obsidian.md/Reference/TypeScript+API/Command/callback

An example of adding a command with a callback that logs a message to the console.

```typescript
this.addCommand({
  id: 'print-greeting-to-console',
  name: 'Print greeting to console',
  callback: () => {
    console.log('Hey, you!');
  },
});
```

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

### parseFrontMatterTags frontmatter example

Source: https://docs.obsidian.md/Reference/TypeScript+API/parseFrontMatterTags

Example of frontmatter configuration for the parseFrontMatterTags function.

```yaml
aliases: "parseFrontMatterTags"
cssclasses: hide-title
```

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

### Implement dual support for settings

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

This example shows how to include both getSettingDefinitions() for Obsidian 1.13.0+ and the legacy display() method for older versions within a PluginSettingTab class.

```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
  }
}
```

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

### Install React dependencies

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

Add React and React DOM to your plugin dependencies.

```bash
npm install react react-dom
```

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

### Imperative PluginSettingTab display() implementation

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

The starting point for migration, showing a standard PluginSettingTab using the imperative display() method to manually construct settings UI.

```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);
        }));
  }
}
```

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

### FrontMatterCache YAML configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/FrontMatterCache

Example of frontmatter configuration for the FrontMatterCache page.

```yaml
aliases: "FrontMatterCache"
cssclasses: hide-title
```

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

### SubpathResult.start

Source: https://docs.obsidian.md/Reference/TypeScript+API/SubpathResult/start

The start property defines the starting location of the subpath result.

```APIDOC
## SubpathResult.start

### Description
The start property indicates the starting location (Loc) of the subpath result.

### Signature
`start: Loc;`
```

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

### Plugin.onUserEnable()

Source: https://docs.obsidian.md/Reference/TypeScript+API/Plugin/onUserEnable

This method is called when the user enables the plugin. It is the appropriate place to perform initial setup, such as registering custom views or engaging with the user interface.

```APIDOC
## Plugin.onUserEnable()

### Description
Perform any initial setup code. The user has explicitly interacted with the plugin so it is safe to engage with the user. If your plugin registers a custom view, you can open it here.

### Signature
`onUserEnable(): void;`

### Returns
- **void**
```

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

### Install Svelte dependencies

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

Install the required Svelte packages as development dependencies.

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

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

### Single fundingUrl

Source: https://docs.obsidian.md/Reference/Manifest

Example of providing a single funding URL as a string.

```json
{
  "fundingUrl": "https://buymeacoffee.com"
}
```

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

### Frontmatter aliases example

Source: https://docs.obsidian.md/Reference/TypeScript+API/parseFrontMatterAliases

An example of frontmatter containing an aliases field.

```yaml
aliases: "parseFrontMatterAliases"
cssclasses: hide-title
```

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

### Implement declarative settings with getSettingDefinitions

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

Example of a PluginSettingTab implementation using the declarative API. The display() method is removed, and settings are defined via an array returned by getSettingDefinitions().

```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.',
        },
      },
    ];
  }
}
```

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

### Example usage of processFrontMatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/FileManager/processFrontMatter

Demonstrates how to use the callback function to add or delete keys within the frontmatter object.

```typescript
app.fileManager.processFrontMatter(file, (frontmatter) => {
    frontmatter['key1'] = value;
    delete frontmatter['key2'];
});
```

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

### Multiple fundingUrl

Source: https://docs.obsidian.md/Reference/Manifest

Example of providing multiple funding URLs as an object.

```json
{
  "fundingUrl": {
    "Buy Me a Coffee": "https://buymeacoffee.com",
    "GitHub Sponsor": "https://github.com/sponsors",
    "Patreon": "https://www.patreon.com/"
  }
}
```

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

### Import and apply Google Fonts

Source: https://docs.obsidian.md/Reference/CSS+variables/Publish/Site+fonts

Example of importing a Google Font and applying it to the body text using the --font-text-theme variable in publish.css.

```css
/* @import must always be at the top of your publish.css file */
@import url('https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap');

body {
  --font-text-theme: 'Poppins';
}
```

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

### debounce usage example

Source: https://docs.obsidian.md/Reference/TypeScript+API/debounce

An example showing how to create a debounced function and how the resetTimer parameter affects execution.

```typescript
const debounced = debounce((text: string) => {
    console.log(text);
}, 1000, true);
debounced('Hello world'); // this will not be printed
await sleep(500);
debounced('World, hello'); // this will be printed to the console.
```

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

### Define manifest.json version requirements

Source: https://docs.obsidian.md/Reference/Versions

Example manifest.json showing a plugin version and its minimum required Obsidian app version.

```json
{
  // ...

  "version": "1.0.0",
  "minAppVersion": "1.2.0"
}
```

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

### MarkdownFileInfo YAML Frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/MarkdownFileInfo

Example of the frontmatter configuration for the MarkdownFileInfo page.

```yaml
aliases: "MarkdownFileInfo"
cssclasses: hide-title
```

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

### SuggestModal.setInstructions()

Source: https://docs.obsidian.md/Reference/TypeScript+API/SuggestModal/setInstructions

Sets the instructions to be displayed in the SuggestModal.

```APIDOC
## SuggestModal.setInstructions()

### Description
Sets the instructions to be displayed in the SuggestModal. This method takes an array of Instruction objects to guide the user interaction.

### Signature
`setInstructions(instructions: Instruction[]): void;`

### Parameters
- **instructions** (Instruction[]) - Required - An array of instruction objects to display.
```

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

### Use async/await for asynchronous operations

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

This example demonstrates the preferred pattern of using async/await for cleaner, more readable asynchronous code.

```typescript
async function AsyncTest(): Promise<string | null> {
  try {
    let res = await requestUrl('https://example.com');
    let text = await r.text;
    return text;
  }
  catch (e) {
    console.log(e);
    return null;
  }
}
```

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

### Define CSS variables in publish.css

Source: https://docs.obsidian.md/Themes/Obsidian+Publish+themes/Build+a+Publish+theme

Example of setting layout variables and theme-specific color overrides within the publish.css file.

```css
.published-container {
  --page-width: 800px;
  --page-side-padding: 48px;
  
  /* ... CSS variables for Publish that do not change when light or dark mode is enabled. They sometimes link to color variables in .theme-light or .theme-dark */
}

.theme-light {
  --background-primary: #ebf2ff;
  --h1-color: #000000;
 
  /* ... CSS color variables for when light mode is enabled */
}
.theme-dark {
  --background-primary: #1f2a3f;
  --h1-color: #ffffff;
  
  /* ... CSS color variables for when dark mode is enabled */
}
```

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

### Define versions.json fallback mapping

Source: https://docs.obsidian.md/Reference/Versions

Example versions.json mapping plugin versions to the minimum Obsidian app version they support.

```json
{
  "0.1.0": "1.0.0",
  "0.12.0": "1.1.0",
}
```

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

### Community directory frontmatter configuration

Source: https://docs.obsidian.md/community-directory/set-up-and-claim

The YAML frontmatter used to define metadata for the community directory setup documentation.

```yaml
aliases:
  - Get started with the community directory
  - Getting started with the community directory
  - Sign in to the community directory
  - Directory setup
description: Sign in to the Obsidian Community directory, set up your community profile, and claim your plugins and themes.
permalink: community-directory/set-up-and-claim
publish: true
```

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

### ExamplePlugin settings persistence

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

Demonstrates how to define, load, and save plugin settings to disk using the Obsidian Plugin API.

```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);
  }
}
```

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

### LinkValue.parseFromString usage example

Source: https://docs.obsidian.md/Reference/TypeScript+API/LinkValue/parseFromString

A basic example of using parseFromString with a wikilink string.

```typescript
parseFromString("[[Welcome|Example Link]]")
```

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

### Create and show a custom Menu

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

Demonstrates how to instantiate a Menu, add items with titles, icons, and click handlers, and display it at the location of a mouse event.

```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);
    });
  }
}
```

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

### WorkspaceWindowInitData.x frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceWindowInitData/x

Frontmatter configuration for the WorkspaceWindowInitData.x documentation page.

```yaml
aliases: "WorkspaceWindowInitData.x"
cssclasses: hide-title
```

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

### Create the plugins directory

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

Navigate to your vault directory and create the .obsidian/plugins folder to store your plugin files.

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

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

### DateValue.parseFromString usage examples

Source: https://docs.obsidian.md/Reference/TypeScript+API/DateValue/parseFromString

Examples of valid ISO 8601 strings that can be parsed using the parseFromString method.

```typescript
parseFromString("2025-12-31") parseFromString("2025-12-31T23:59") parseFromString("2025-12-31T23:59:59") parseFromString("2025-12-31T23:59:59Z-07")
```

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

### Mermaid diagram code block example

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

An example of a standard Mermaid diagram code block used in Obsidian.

```markdown
```mermaid
flowchart LR
    Start --> Stop
```
```

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

### EditorRange.from

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorRange/from

The from property defines the starting EditorPosition of an EditorRange.

```APIDOC
## EditorRange.from

### Description
The `from` property specifies the starting position of the range within the editor.

### Signature
`from: EditorPosition;`
```

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

### WorkspaceWindow.win frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceWindow/win

Frontmatter configuration for the WorkspaceWindow.win documentation page.

```yaml
aliases: "WorkspaceWindow.win"
cssclasses: hide-title
```

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

### EditorRangeOrCaret.from

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorRangeOrCaret/from

The from property defines the starting position of the range or caret.

```APIDOC
## EditorRangeOrCaret.from

### Description
The `from` property specifies the starting `EditorPosition` for an `EditorRangeOrCaret` object.

### Signature
`from: EditorPosition;`
```

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

### ObjectValue.get aliases and cssclasses

Source: https://docs.obsidian.md/Reference/TypeScript+API/ObjectValue/get

Frontmatter configuration for the ObjectValue.get documentation page.

```yaml
aliases: "ObjectValue.get"
cssclasses: hide-title
```

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

### FileSystemAdapter.mkdir(path: string)

Source: https://docs.obsidian.md/Reference/TypeScript+API/FileSystemAdapter/mkdir

Creates a new directory at the provided path.

```APIDOC
## FileSystemAdapter.mkdir

### Description
Creates a new directory at the specified path.

### Signature
`static mkdir(path: string): Promise<void>;`

### Parameters
- **path** (string) - The path where the directory should be created.

### Returns
- **Promise<void>** - A promise that resolves when the directory has been created.
```

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

### Define ExamplePluginSettings interface

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

Define the settings structure and include it as a member variable in the plugin class.

```typescript
interface ExamplePluginSettings {
  sampleValue: string;
}

export default class ExamplePlugin extends Plugin {
  settings: ExamplePluginSettings;

  // ...
}
```

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

### Workspace.on('editor-menu') alias configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('editor-menu')

Frontmatter configuration for the Workspace.on('editor-menu') documentation page.

```yaml
aliases: "Workspace.on('editor-menu')"
cssclasses: hide-title
```

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

### Clone the sample theme

Source: https://docs.obsidian.md/Themes/App+themes/Build+a+theme

Clone the Obsidian sample theme repository into your local themes directory using Git.

```bash
git clone https://github.com/obsidianmd/obsidian-sample-theme.git "Sample Theme"
```

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

### Clone the sample plugin

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

Use Git to clone the obsidian-sample-plugin repository into your plugins directory.

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

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

### EditorSuggestTriggerInfo.start

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorSuggestTriggerInfo/start

The start property represents the EditorPosition where the triggering text begins.

```APIDOC
## EditorSuggestTriggerInfo.start

### Description
The start position of the triggering text. This is used to position the popover.

### Signature
`start: EditorPosition;`
```

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

### MarkdownSectionInformation YAML frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/MarkdownSectionInformation

Example of YAML frontmatter configuration for a Markdown file.

```yaml
aliases: "MarkdownSectionInformation"
cssclasses: hide-title
```

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

### SubpathResult.start property signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/SubpathResult/start

The signature of the start property within the SubpathResult interface.

```typescript
start: Loc;
```

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

### WorkspaceContainer.win page aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceContainer/win

Frontmatter configuration for the WorkspaceContainer.win documentation page.

```yaml
aliases: "WorkspaceContainer.win"
cssclasses: hide-title
```

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

### EditorSelection.anchor

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorSelection/anchor

The anchor property defines the starting point of a selection within the editor.

```APIDOC
## EditorSelection.anchor

### Description
The `anchor` property specifies the starting position of a selection in the editor. It is defined as an `EditorPosition` object.

### Signature
`anchor: EditorPosition;`
```

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

### Navigate to plugin directory

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

Change the current working directory to the plugin folder.

```bash
cd obsidian-sample-plugin
```

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

### EditorSelectionOrCaret.anchor

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorSelectionOrCaret/anchor

The anchor property defines the starting point of a selection or the position of the caret in the editor.

```APIDOC
## EditorSelectionOrCaret.anchor

### Description
The anchor property specifies the starting position of a selection or the current caret position within the editor.

### Signature
`anchor: EditorPosition;`
```

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

### CapacitorAdapter.mkdir(normalizedPath: string)

Source: https://docs.obsidian.md/Reference/TypeScript+API/CapacitorAdapter/mkdir

Creates a directory at the provided normalized path.

```APIDOC
## CapacitorAdapter.mkdir(normalizedPath: string)

### Description
Creates a directory at the specified path.

### Signature
`mkdir(normalizedPath: string): Promise<void>;`

### Parameters
- **normalizedPath** (string) - The path where the directory should be created.

### Returns
- **Promise<void>** - A promise that resolves when the directory has been created.
```

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

### MarkdownEditView.get() Signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/MarkdownEditView/get

The signature for the get() method, which returns a string representing the editor content.

```typescript
get(): string;
```

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

### Orphaned Component Pitfall

Source: https://docs.obsidian.md/plugins/guides/lifecycle-management

An example of a memory leak caused by creating a component that is never unloaded.

```typescript
import { Component, ItemView, MarkdownRenderer } from 'obsidian';

class MyView extends ItemView {
	onload() {		
		// Bad: tempComponent is never unloaded!
		const tempComponent = new Component();
		MarkdownRenderer.render(this.app, "## Some Markdown", this.containerEl, "", tempComponent);
		tempComponent.load();
	}
}
```

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

### Command.hotkeys frontmatter aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/Command/hotkeys

Frontmatter configuration for the Command.hotkeys documentation page.

```yaml
aliases: "Command.hotkeys"
cssclasses: hide-title
```

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

### KeymapInfo.key frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/KeymapInfo/key

Frontmatter configuration for the KeymapInfo.key documentation page.

```yaml
aliases: "KeymapInfo.key"
cssclasses: hide-title
```

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

### ListValue.get() method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/ListValue/get

The signature for the get method, which takes a numeric index and returns a Value.

```typescript
get(index: number): Value;
```

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

### Component.load()

Source: https://docs.obsidian.md/Reference/TypeScript+API/Component/load

Initializes the component and its child components.

```APIDOC
## Component.load()

### Description
Loads this component and its children.

### Signature
`load(): void;`

### Returns
- **void** - This method does not return a value.
```

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

### Workspace.on('quick-preview') signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('quick-preview')

The signature for the on('quick-preview') event listener.

```typescript
on(name: 'quick-preview', callback: (file: TFile, data: string) => any, ctx?: any): EventRef;
```

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

### Vault.getResourcePath(file: TFile): string

Source: https://docs.obsidian.md/Reference/TypeScript+API/Vault/getResourcePath

Returns a URI for the browser engine to use, for example to embed an image.

```APIDOC
## Vault.getResourcePath()

### Description
Returns a URI for the browser engine to use, for example to embed an image.

### Signature
`getResourcePath(file: TFile): string;`

### Parameters
- **file** (TFile) - Required - The file to retrieve the resource path for.

### Returns
- **string** - The URI string for the browser engine.
```

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

### WorkspaceWindowInitData Frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceWindowInitData

The frontmatter configuration for the WorkspaceWindowInitData documentation page.

```yaml
aliases: "WorkspaceWindowInitData"
cssclasses: hide-title
```

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

### DataAdapter.getResourcePath(normalizedPath: string): string

Source: https://docs.obsidian.md/Reference/TypeScript+API/DataAdapter/getResourcePath

Returns a URI for the browser engine to use, for example to embed an image.

```APIDOC
## DataAdapter.getResourcePath()

### Description
Returns a URI for the browser engine to use, for example to embed an image.

### Signature
`getResourcePath(normalizedPath: string): string;`

### Parameters
- **normalizedPath** (string) - Required - Path to file/folder, use normalizePath() to normalize beforehand.

### Returns
- **string** - The URI for the browser engine.
```

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

### Registering a Command with editorCallback

Source: https://docs.obsidian.md/Reference/TypeScript+API/Command/editorCallback

An example of adding a command that utilizes editorCallback to access the current editor selection.

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

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

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

### WorkspaceWindow.doc frontmatter aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceWindow/doc

Frontmatter configuration for the WorkspaceWindow.doc page.

```yaml
aliases: "WorkspaceWindow.doc"
cssclasses: hide-title
```

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

### Loc.offset property signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/Loc/offset

The signature for the offset property, which is a number representing the character count from the file start.

```typescript
offset: number;
```

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

### BasesView.createFileForView()

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesView/createFileForView

Displays the new note menu for a file, optionally accepting a filename and a callback to modify the note's frontmatter.

```APIDOC
## BasesView.createFileForView()

### Description
Displays the new note menu for a file with the provided filename and optionally a function to modify the frontmatter.

### Signature
`createFileForView(baseFileName?: string, frontmatterProcessor?: (frontmatter: any) => void): Promise<void>;`

### Parameters
- **baseFileName** (string) - Optional - The name of the file to be created.
- **frontmatterProcessor** ((frontmatter: any) => void) - Optional - A callback function used to modify the frontmatter of the new note.

### Returns
- **Promise<void>** - A promise that resolves when the operation is complete.
```

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

### EditorRange interface

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorRange

The EditorRange interface represents a selection or range in the editor, defined by its start and end positions.

```APIDOC
## EditorRange

### Description
Represents a range within the editor, defined by a start and end position.

### Properties
- **from** (EditorPosition) - The starting position of the range.
- **to** (EditorPosition) - The ending position of the range.
```

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

### BasesViewConfig.get method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesViewConfig/get

The signature for the get method, which takes a string key and returns an unknown type.

```typescript
get(key: string): unknown;
```

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

### BasesConfigFileView.summaries configuration metadata

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesConfigFileView/summaries

Metadata defining the aliases and CSS classes for the BasesConfigFileView.summaries documentation page.

```yaml
aliases: "BasesConfigFileView.summaries"
cssclasses: hide-title
```

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

### TypeScript change history array

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

An example of tracking state changes in an array of ChangeSpec objects to maintain a history.

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

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

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

### SubpathResult interface

Source: https://docs.obsidian.md/Reference/TypeScript+API/SubpathResult

The SubpathResult interface represents the result of resolving a subpath, containing the start and optional end locations.

```APIDOC
## SubpathResult

### Description
The `SubpathResult` interface defines the range of a subpath within a file or document.

### Properties
- **start** (`Loc`) - The starting location of the subpath.
- **end** (`Loc | null`) - The ending location of the subpath, if applicable.
```

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

### WorkspaceWindowInitData Interface

Source: https://docs.obsidian.md/Reference/TypeScript+API/WorkspaceWindowInitData

The WorkspaceWindowInitData interface provides configuration for the initial dimensions and screen position of a workspace window.

```APIDOC
## WorkspaceWindowInitData

### Description
Defines the initialization data for a workspace window, allowing specification of window size and screen coordinates.

### Properties
- **size** ({ width: number; height: number; }) - Optional - The suggested dimensions for the window.
- **x** (number) - Optional - The horizontal screen coordinate.
- **y** (number) - Optional - The vertical screen coordinate.
```

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

### ObjectValue.get method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/ObjectValue/get

The TypeScript signature for the get method, which accepts a string key and returns a Value or null.

```typescript
get(key: string): Value | null;
```

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

### PluginManifest.description frontmatter aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/PluginManifest/description

Frontmatter configuration for the PluginManifest.description documentation page.

```yaml
aliases: "PluginManifest.description"
cssclasses: hide-title
```

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

### BasesFileOption.placeholder frontmatter configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesFileOption/placeholder

Frontmatter configuration for the placeholder property.

```yaml
aliases: "BasesFileOption.placeholder"
cssclasses: hide-title
```

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

### BasesSliderOption.step frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesSliderOption/step

The frontmatter configuration for the BasesSliderOption.step documentation page.

```yaml
aliases: "BasesSliderOption.step"
cssclasses: hide-title
```

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

### BasesPropertyOption.type aliases and cssclasses

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesPropertyOption/type

Frontmatter configuration for the BasesPropertyOption.type documentation page.

```yaml
aliases: "BasesPropertyOption.type"
cssclasses: hide-title
```

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

### FileSystemAdapter.mkdir method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/FileSystemAdapter/mkdir

The static method signature for creating a directory.

```typescript
static mkdir(path: string): Promise<void>;
```

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

### BasesView.allProperties frontmatter configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesView/allProperties

Frontmatter configuration for the allProperties page.

```yaml
aliases: "BasesView.allProperties"
cssclasses: hide-title
```

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

### Assigning a new Scope to a view

Source: https://docs.obsidian.md/Reference/TypeScript+API/View/scope

Example of initializing a new Scope for a view using the application's scope as a parent.

```typescript
this.scope = new Scope(this.app.scope);
```

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

### BasesEntry.file frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesEntry/file

Frontmatter configuration for the BasesEntry.file documentation page.

```yaml
aliases: "BasesEntry.file"
cssclasses: hide-title
```

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

### Avoid Promise chains in TypeScript

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

This example demonstrates the discouraged pattern of using .then() and .catch() chains for asynchronous operations.

```typescript
function test(): Promise<string | null> {
  return requestUrl('https://example.com')
    .then(res => res.text
    .catch(e => {
      console.log(e);
      return null;
    });
}
```

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

### Dispatching a transaction

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

An example of grouping multiple changes into a single transaction using view.dispatch to ensure they are treated as one operation.

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

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

### Setting.components frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/Setting/components

Frontmatter configuration for the Setting.components documentation page.

```yaml
aliases: "Setting.components"
cssclasses: hide-title
```

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

### Setting Components API

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

A collection of imperative UI components for building settings interfaces in Obsidian.

```APIDOC
## Setting Components

### Description
These components are used within the `display()` method of a settings tab to render interactive elements.

### Usage
All components are initialized via `new Setting(containerEl)`.

### Components

#### Headings
`new Setting(containerEl).setName('Title').setHeading();`

#### Search with Suggestions
`new Setting(containerEl).setName('Search').addSearch((search) => { ... });`

#### Moment Format
`new Setting(containerEl).addMomentFormat((momentFormat) => { ... });`

#### Buttons
`new Setting(containerEl).addButton((button) => { ... });`

#### Extra Button
`new Setting(containerEl).addExtraButton((button) => { ... });`

#### Progress Bar
`new Setting(containerEl).addProgressBar((bar) => bar.setValue(50));`
```

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

### Manual window resize listener cleanup

Source: https://docs.obsidian.md/plugins/guides/lifecycle-management

This example shows a more responsible approach by manually removing the event listener in the onunload method.

```typescript
// Better: but more tedious and error-prone.
class MyPlugin extends Plugin {
	onResize() {
		console.debug("Window resized!");
	}

	onload() {
		window.addEventListener("resize", this.onResize);
	}

	onunload() {
		window.removeEventListener("resize", this.onResize);
	}
}
```

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

### Embed a GIF as a background image

Source: https://docs.obsidian.md/Themes/App+themes/Embed+fonts+and+images+in+your+theme

An example of applying an embedded GIF image to an h1 element using a Base64 data URL.

```css
h1 {
  background-image: url("data:image/gif;base64,R0lGODdhAQADAPABAP////8AACwAAAAAAQADAAACAgxQADs=")
}
```

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

### Creating a Custom Component by Extending Component

Source: https://docs.obsidian.md/plugins/guides/lifecycle-management

Demonstrates how to create a reusable widget that manages its own DOM elements and third-party library lifecycle using onload and onunload.

```typescript
import { Component, MarkdownRenderer } from "obsidian";
import SomeLibrary from "some-library";

class MyWidget extends Component {
	private widget: HTMLElement;
	private lib: SomeLibrary;

	constructor(private app: App) {
		super();
		this.widget = createDiv({ cls: "my-widget" });
	}

	onload() {
		// Render markdown content
		MarkdownRenderer.render(this.app, "## Some Markdown", this.widget, "", this);
		document.body.appendChild(this.widget);

		// Initialize some third-party library
		this.lib = new SomeLibrary();
		this.lib.initialize();

		// Register an event listener
		this.registerDomEvent(window, "resize", () => {
			this.lib.resize(window.innerWidth, window.innerHeight);
		});
	}
	
	doSomething() {
		this.lib.doSomething();
	}

	onunload() {
		// Removes the widget from the DOM and cleans up the library
		this.widget.remove();
		this.lib.destroy();
	}
}
```

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

### Variable assignment state change

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

An example of direct variable assignment where previous states are lost, making undo operations difficult.

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

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

### SearchMatchPart type definition

Source: https://docs.obsidian.md/Reference/TypeScript+API/SearchMatchPart

The SearchMatchPart type is defined as a tuple of two numbers representing the start and end offsets of a text match.

```typescript
export type SearchMatchPart = [number, number];
```

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

### EditorSuggest.setInstructions()

Source: https://docs.obsidian.md/Reference/TypeScript+API/EditorSuggest/setInstructions

Sets the instructions for the editor suggestion interface.

```APIDOC
## EditorSuggest.setInstructions()

### Description
Sets the instructions to be displayed within the EditorSuggest component.

### Signature
`setInstructions(instructions: Instruction[]): void;`

### Parameters
- **instructions** (Instruction[]) - Required - An array of instruction objects to display.
```

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

### BasesConfigFileView.order frontmatter aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesConfigFileView/order

Frontmatter configuration for the BasesConfigFileView.order property.

```yaml
aliases: "BasesConfigFileView.order"
cssclasses: hide-title
```

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

### Accessing the Editor from the active view

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

Demonstrates how to retrieve the editor instance from the active MarkdownView to perform operations like getting the cursor position.

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

// Make sure the user is editing a Markdown file.
if (view) {
	const cursor = view.editor.getCursor();

	// ...
}
```

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

### Workspace.on('window-open')

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('window-open')

Registers a callback function that is executed when a new popout window is opened.

```APIDOC
## Workspace.on('window-open')

### Description
Triggered when a new popout window is created.

### Signature
`on(name: 'window-open', callback: (win: WorkspaceWindow, window: Window) => any, ctx?: any): EventRef;`

### Parameters
- **name** ('window-open') - Required - The event name.
- **callback** ((win: WorkspaceWindow, window: Window) => any) - Required - The function to execute when the event fires.
- **ctx** (any) - Optional - The context to bind to the callback.

### Returns
- **EventRef** - An event reference that can be used to stop listening to the event.
```

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

### Implementing Command.checkCallback

Source: https://docs.obsidian.md/Reference/TypeScript+API/Command/checkCallback

An example of using checkCallback to conditionally execute a command. The checking parameter determines whether the command is being validated for the palette or actually executed.

```typescript
this.addCommand({
  id: 'example-command',
  name: 'Example command',
  checkCallback: (checking: boolean) => {
    const value = getRequiredValue();

    if (value) {
      if (!checking) {
        doCommand(value);
      }
      return true;
    }

    return false;
  }
});
```

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

### Workspace.on('css-change') aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('css-change')

Metadata aliases for the Workspace.on('css-change') method.

```yaml
aliases: "Workspace.on('css-change')"
cssclasses: hide-title
```

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

### CapacitorAdapter.list() method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/CapacitorAdapter/list

The method signature for listing files in the CapacitorAdapter.

```typescript
list(normalizedPath: string): Promise<ListedFiles>;
```

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

### Incorrect window resize listener implementation

Source: https://docs.obsidian.md/plugins/guides/lifecycle-management

This example demonstrates a common pitfall where an event listener is added in onload but never removed, leading to memory leaks.

```typescript
// Bad: the listener is never removed!
class MyPlugin extends Plugin {
	onResize() {
		console.debug("Window resized!");
	}

	onload() {
		window.addEventListener("resize", this.onResize);
	}
}
```

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

### DataAdapter.mkdir method signature

Source: https://docs.obsidian.md/Reference/TypeScript+API/DataAdapter/mkdir

The method signature for creating a directory, requiring a normalized path string and returning a promise.

```typescript
mkdir(normalizedPath: string): Promise<void>;
```

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

### OpenViewState Frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/OpenViewState

Frontmatter configuration for the OpenViewState documentation page.

```yaml
aliases: "OpenViewState"
cssclasses: hide-title
```

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

### Workspace.onLayoutReady()

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/onLayoutReady

Registers a callback to be executed when the workspace layout is ready.

```APIDOC
## Workspace.onLayoutReady()

### Description
Runs the callback function right away if layout is already ready, or pushes it to a queue to be called later when layout is ready.

### Signature
`onLayoutReady(callback: () => any): void;`

### Parameters
- **callback** (() => any) - The function to execute when the layout is ready.

### Returns
- **void**
```

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

### Editor.setSelection(anchor: EditorPosition, head?: EditorPosition)

Source: https://docs.obsidian.md/Reference/TypeScript+API/Editor/setSelection

Sets the selection range in the editor. The anchor represents the starting point of the selection, and the optional head represents the end point.

```APIDOC
## Editor.setSelection

### Signature
`abstract setSelection(anchor: EditorPosition, head?: EditorPosition): void;`

### Description
Sets the selection range in the editor. If only the anchor is provided, the selection is collapsed to that position.

### Parameters
- **anchor** (EditorPosition) - Required - The starting position of the selection.
- **head** (EditorPosition) - Optional - The ending position of the selection.

### Returns
- **void**
```

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

### Enable mobile emulation

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

Run this command in the Developer Tools console to enable mobile emulation.

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

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

### ToggleComponent

Source: https://docs.obsidian.md/Reference/TypeScript+API/ToggleComponent

The ToggleComponent class represents a toggle switch UI element. It provides methods to get and set the boolean value, handle change events, and configure the component's state.

```APIDOC
## ToggleComponent

### Description
A UI component for rendering a toggle switch. It extends `ValueComponent<boolean>`.

### Constructor
- `new ToggleComponent(containerEl: HTMLElement)`

### Methods
- `getValue(): boolean` - Returns the current boolean value of the toggle.
- `onChange(callback: (value: boolean) => any): this` - Sets a callback function to be triggered when the toggle state changes.
- `onClick(): void` - Manually triggers the toggle click action.
- `setDisabled(disabled: boolean): this` - Sets the disabled state of the toggle.
- `setTooltip(tooltip: string, options?: TooltipOptions): this` - Sets a tooltip for the toggle component.
- `setValue(on: boolean): this` - Sets the current state of the toggle.
- `then(cb: (value: this) => any): this` - Facilitates method chaining.

### Properties
- `toggleEl` (HTMLElement) - The underlying HTML element for the toggle.
- `disabled` (boolean) - The current disabled state of the component.
```

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

### Create a Heading

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

Adds a heading to the settings container.

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

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

### Instruction.command frontmatter aliases

Source: https://docs.obsidian.md/Reference/TypeScript+API/Instruction/command

Frontmatter configuration for the Instruction.command page.

```yaml
aliases: "Instruction.command"
cssclasses: hide-title
```

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

### TextComponent Class

Source: https://docs.obsidian.md/Reference/TypeScript+API/TextComponent

The TextComponent class allows developers to create and manipulate text input fields. It provides methods to get and set values, handle changes, and toggle the disabled state.

```APIDOC
## TextComponent

### Description
A component representing an HTML input element for text entry.

### Methods
- **getValue()**: Returns the current string value of the input.
- **onChange(callback: (value: string) => any)**: Registers a callback function that triggers whenever the input value changes.
- **setDisabled(disabled: boolean)**: Sets the disabled state of the input element.
- **setPlaceholder(placeholder: string)**: Sets the placeholder text for the input field.
- **setValue(value: string)**: Sets the current value of the input field.
- **then(cb: (component: this) => any)**: Facilitates method chaining.
```

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

### Workspace.on('file-open')

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('file-open')

Registers a callback function that executes whenever the active file changes in the workspace.

```APIDOC
## Workspace.on('file-open')

### Description
Triggered when the active file changes. The file could be in a new leaf, an existing leaf, or an embed.

### Signature
`on(name: 'file-open', callback: (file: TFile | null) => any, ctx?: any): EventRef;`

### Parameters
- **name** ('file-open') - Required - The name of the event.
- **callback** ((file: TFile | null) => any) - Required - The function to execute when the event triggers. Receives the active TFile or null.
- **ctx** (any) - Optional - The context to bind to the callback.

### Returns
- **EventRef** - An event reference that can be used to stop listening to the event.
```

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

### Registering vault event listeners in PluginSettingTab

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

This example demonstrates how to wire up vault event listeners in the constructor of a PluginSettingTab. It uses debounce to prevent excessive re-renders during bursty events and registers events via plugin.registerEvent() for automatic cleanup.

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

export class MySettingTab extends PluginSettingTab {
  plugin: MyPlugin;

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

    let refresh = debounce(() => this.update(), 200, true);
    plugin.registerEvent(this.app.vault.on('create', refresh));
    plugin.registerEvent(this.app.vault.on('delete', refresh));
    plugin.registerEvent(this.app.vault.on('rename', refresh));
  }
}
```

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

### BasesViewRegistration.options

Source: https://docs.obsidian.md/Reference/TypeScript+API/BasesViewRegistration/options

The options property is a function that accepts a BasesViewConfig object and returns an array of BasesAllOptions.

```APIDOC
## BasesViewRegistration.options

### Signature
`options?: (config: BasesViewConfig) => BasesAllOptions[];`

### Description
An optional property that defines a function to retrieve view options based on the provided configuration.

### Parameters
- **config** (BasesViewConfig) - Required - The configuration object used to generate the view options.

### Returns
- **BasesAllOptions[]** - An array of options applicable to the view.
```

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

### Workspace.on('url-menu')

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('url-menu')

Registers a callback function to be executed when the context menu is opened for an external URL.

```APIDOC
## Workspace.on('url-menu')

### Description
Triggered when the user opens the context menu on an external URL.

### Signature
`on(name: 'url-menu', callback: (menu: Menu, url: string) => any, ctx?: any): EventRef`

### Parameters
- **name** ('url-menu') - Required - The event name.
- **callback** ((menu: Menu, url: string) => any) - Required - The function to execute when the event is triggered. Receives the Menu object and the URL string.
- **ctx** (any) - Optional - The context in which to execute the callback.

### Returns
- **EventRef** - An event reference that can be used to stop listening to the event.
```

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

### Identify common pitfalls with pop-out window globals

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

Demonstrates code that fails in pop-out windows because it relies on the main window's document or global constructors.

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

// This will always append to the main window
document.body.appendChild(myElement);

// This will actually be false if element is in a pop-out window
if (myElement instanceof HTMLElement) {

}

element.on('click', '.my-css-class', (event) => {
    // This will be false if the event is triggered in a pop-out window
    if (event instanceof MouseEvent) {

    }
}
```

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

### Check layout readiness in onCreate

Source: https://docs.obsidian.md/Plugins/Guides/Optimizing%2Bplugin%2Bload%2Btime

Option A for handling vault creation events by checking if the workspace layout is ready before executing logic.

```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;
	    }
		// ...
	}
}
```

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

### Plugin.loadData()

Source: https://docs.obsidian.md/Reference/TypeScript+API/Plugin/loadData

Loads settings data from the plugin's data.json file on disk.

```APIDOC
## Plugin.loadData()

### Description
Loads settings data from disk. Data is stored in `data.json` in the plugin folder.

### Signature
`loadData(): Promise<any>;`

### Returns
- **Promise<any>** - A promise that resolves with the loaded data.
```

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

### App Page Metadata

Source: https://docs.obsidian.md/Reference/TypeScript+API/App

Frontmatter configuration for the App documentation page.

```yaml
aliases: "App"
cssclasses: hide-title
```

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

### CapacitorAdapter.list()

Source: https://docs.obsidian.md/Reference/TypeScript+API/CapacitorAdapter/list

Retrieves a list of files from the provided normalized path.

```APIDOC
## CapacitorAdapter.list()

### Description
Retrieves a list of files from the specified normalized path.

### Signature
`list(normalizedPath: string): Promise<ListedFiles>`

### Parameters
- **normalizedPath** (string) - The path to list files from.

### Returns
- **Promise<ListedFiles>** - A promise that resolves to the list of files.
```

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

### Workspace.on('files-menu')

Source: https://docs.obsidian.md/Reference/TypeScript+API/Workspace/on('files-menu')

Registers an event listener for the 'files-menu' event, which fires when a context menu is opened for multiple selected files.

```APIDOC
## Workspace.on('files-menu')

### Description
Triggered when the user opens the context menu with multiple files selected in the File Explorer.

### Signature
`on(name: 'files-menu', callback: (menu: Menu, files: TAbstractFile[], source: string, leaf?: WorkspaceLeaf) => any, ctx?: any): EventRef;`

### Parameters
- **name** ('files-menu') - Required - The event name.
- **callback** ((menu: Menu, files: TAbstractFile[], source: string, leaf?: WorkspaceLeaf) => any) - Required - The function to execute when the event is triggered.
- **ctx** (any) - Optional - The context in which to execute the callback.

### Returns
- **EventRef** - An event reference object that can be used to stop listening to the event.
```

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

### Importing moment.js

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

Import the moment library directly from the Obsidian API to handle date and time formatting.

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

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

### Compile plugin source code

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

Run the development build process, which watches for file changes and automatically rebuilds the plugin.

```bash
npm run dev
```

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

### DataAdapter.stat aliases and CSS configuration

Source: https://docs.obsidian.md/Reference/TypeScript+API/DataAdapter/stat

Frontmatter configuration for the DataAdapter.stat documentation page.

```yaml
aliases: "DataAdapter.stat"
cssclasses: hide-title
```

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

### FileSystemAdapter.copy frontmatter

Source: https://docs.obsidian.md/Reference/TypeScript+API/FileSystemAdapter/copy

Frontmatter configuration for the FileSystemAdapter.copy documentation page.

```yaml
aliases: "FileSystemAdapter.copy"
cssclasses: hide-title
```
Tokens:
Raw