obsidian-dev-rules

Obsidian Dev Rules

Obsidian is extended two ways: plugins (TypeScript against the Obsidian API) and themes/snippets (CSS). This skill mirrors the official developer docs at https://docs.obsidian.md so you can build and review Obsidian plugins/themes without re-fetching. The API ships as the obsidian npm package; the canonical starting point is the obsidian-sample-plugin.

When to use this skill

• Building, debugging, or reviewing an Obsidian plugin (lifecycle, commands, settings, UI, views).
• Reading/writing notes via the Vault API; manipulating the active note via the Editor API.
• Subscribing to events, registering Markdown post-processors / code-block processors, or CodeMirror 6 editor extensions.
• Building a theme (CSS variables, theme.css, manifest) or snippets.
• Releasing/submitting a plugin or theme to the community directory.

Reference index — load the file you need

File	Covers
references/plugin-basics.md	Project setup, manifest.json, Plugin lifecycle (onload/onunload), resource registration & cleanup, events, dev workflow / hot reload, debugging
references/vault-and-editor.md	Vault API (read/cachedRead/create/modify/process/delete, TFile/TFolder, adapter, normalizePath), Editor API, Markdown post-processing & code-block processors, CodeMirror 6 editor extensions
references/ui.md	Commands (callback variants, hotkeys), Settings (PluginSettingTab, load/saveData, Setting controls), Modals (Modal/SuggestModal/FuzzySuggestModal), Views (ItemView, registerView, workspace leaves), ribbon/status bar
references/themes-and-release.md	Themes (CSS variables, theme.css/manifest, body classes, snippets), submitting plugins & themes, developer policies & guidelines

Cheat sheet

import { Plugin, Notice, MarkdownView, TFile, normalizePath } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    await this.loadSettings();
    this.addRibbonIcon('dice', 'Greet', () => new Notice('Hello!'));
    this.addCommand({ id: 'do-x', name: 'Do X', callback: () => {/* ... */} });
    this.addSettingTab(new MySettingTab(this.app, this));
    // Auto-cleaned on unload — always register through these:
    this.registerEvent(this.app.vault.on('modify', (f) => {/* ... */}));
    this.registerInterval(window.setInterval(() => {/* ... */}, 1000));
    this.registerDomEvent(document, 'click', () => {/* ... */});
  }
  onunload() { /* release anything NOT registered via register*/ }
}

// Vault: prefer process() over read()+modify(); use cachedRead() for display only.
const file = this.app.vault.getFileByPath('Notes/x.md');
await this.app.vault.process(file, (data) => data.replace('foo', 'bar'));
// Editor of the active note (preserves cursor/selection):
const view = this.app.workspace.getActiveViewOfType(MarkdownView);
view?.editor.replaceSelection(view.editor.getSelection().toUpperCase());

Plugin files: manifest.json + main.js (+ optional styles.css) in <vault>/.obsidian/plugins/<id>/. Theme files: manifest.json + theme.css in <vault>/.obsidian/themes/<name>/.

Hard rules

• Use this.app, never the global app (global exists for debugging only and may be removed).
• Register everything that needs teardown via registerEvent / registerInterval / registerDomEvent / addCommand / registerView / registerMarkdownPostProcessor — Obsidian auto-cleans those on unload. Manually release anything else in onunload(). Leaked listeners/ intervals degrade Obsidian after the plugin is disabled.
• Never use innerHTML / outerHTML / insertAdjacentHTML with dynamic content — build DOM with createEl() / createDiv() / createSpan().
• Prefer the Vault API over the Adapter API; use getFileByPath() (not iterate-all); always normalizePath() user-supplied paths. Use process() (atomic) instead of sequential read()+modify() to avoid data loss; cachedRead() only when you won't write it back.
• For the active note, edit via the Editor interface, not Vault.modify — it preserves the cursor and selection.
• Don't store references to view instances; Obsidian may recreate them — fetch with getLeavesOfType() / getActiveViewOfType().
• Don't set default hotkeys for distributed plugins (OS-dependent, conflict-prone). UI text is sentence case. Use CSS classes + Obsidian CSS variables, not hardcoded inline styles.
• manifest.json required fields: id, name, version (semver x.y.z), minAppVersion, description, author, isDesktopOnly. id must not contain "obsidian"; name is Basic-Latin, no emoji/punctuation except hyphens.
• Release: GitHub release whose tag equals the manifest version, with main.js, manifest.json, and optional styles.css attached as individual binary assets (not zipped).
• Use async/await (not Promise chains); const/let (not var).