Obsidian Plugin Development Guidelines

Getting Started

Quick Start Tool

• Script:

  tools/create-plugin.js

  in the skill repository
• Slash command:

  /create-plugin

  for guided setup
• Generates minimal, best-practice boilerplate with no sample code
• Detects existing projects and only adds missing files
• All generated code follows these guidelines automatically

When to Suggest the Tool

• Ask "how do I create a new Obsidian plugin?"
• Want to start a new plugin project
• Need help setting up the basic structure
• Want to ensure they start with best practices

Core Principles

1. Memory Safety: Prevent memory leaks through proper resource management
2. Type Safety: Use proper type narrowing and avoid unsafe casts
3. API Best Practices: Follow Obsidian's recommended patterns
4. User Experience: Maintain consistency in UI/UX across plugins
5. Platform Compatibility: Ensure cross-platform support (including iOS)
6. Accessibility: Make all features keyboard and screen reader accessible

Quick Reference

Top 27 Most Critical Rules

1. Plugin ID: no "obsidian", can't end with "plugin" - Validation bot enforced
2. Plugin name: no "Obsidian", can't end with "Plugin" - Validation bot enforced
3. Plugin name: can't start with "Obsi" or end with "dian" - Validation bot enforced
4. Description: no "Obsidian", "This plugin", etc. - Validation bot enforced
5. Description must end with

   .?!)

   punctuation - Validation bot enforced

registerEvent()

instanceof

.setHeading()

Vault.process()

normalizePath()

Platform

requestUrl()

fetch()

:focus-visible

innerHTML

outerHTML

Detailed Guidelines

Memory Management & Lifecycle

• Using

  registerEvent()

  ,

  addCommand()

  ,

  registerDomEvent()

  ,

  registerInterval()

• Avoiding view references in plugin
• Not using plugin as component
• Proper leaf cleanup

Type Safety

• Using

  instanceof

  instead of type casting
• Avoiding

  any

  type
• Using

  const

  and

  let

  over

  var

UI/UX Standards

• Sentence case enforcement
• Command naming conventions
• Settings and configuration best practices

File & Vault Operations

• View access patterns
• Editor vs Vault API
• Atomic file operations
• File management
• Path handling

CSS Styling Best Practices

• Avoiding inline styles
• Using Obsidian CSS variables
• Scoping plugin styles
• Theme support
• Spacing and layout

Accessibility (A11y)

• Keyboard navigation (MANDATORY)
• ARIA labels and roles (MANDATORY)
• Tooltips and accessibility
• Focus management (MANDATORY)
• Focus visible styles (MANDATORY)
• Screen reader support (MANDATORY)
• Mobile and touch accessibility (MANDATORY)
• Accessibility checklist

Code Quality & Best Practices

• Removing sample code
• Security best practices
• Platform compatibility
• API usage best practices
• Async/await patterns
• DOM helpers

Plugin Submission Requirements

• Repository structure
• Submission process
• Semantic versioning
• Testing checklist

Essential Do's and Don'ts

Do's ✅

• Use

  registerEvent()

  ,

  addCommand()

  ,

  registerDomEvent()

  ,

  registerInterval()

• Return views/components directly (don't store unnecessarily)

• Use

  instanceof

  for type checking (not type casting)
• Use specific types or

  unknown

  instead of

  any

• Use

  const

  and

  let

  (not

  var

  )

• Use

  this.app

  (not global

  app

  )
• Use Editor API for active file edits
• Use

  Vault.process()

  for background file modifications
• Use

  FileManager.processFrontMatter()

  for YAML
• Use

  fileManager.trashFile()

  for deletions
• Use

  normalizePath()

  for user-defined paths
• Use

  Platform

  API for OS detection
• Use

  AbstractInputSuggest

  for autocomplete
• Use direct file lookups (not vault iteration)
• Use

  requestUrl()

  instead of

  fetch()

  for network requests

• Use sentence case for all UI text
• Use

  .setHeading()

  for settings headings
• Use Obsidian DOM helpers (

  createDiv()

  ,

  createSpan()

  ,

  createEl()

  )
• Use

  window.setTimeout/setInterval

  with

  number

  type

• Move all styles to CSS
• Use Obsidian CSS variables for all styling
• Scope CSS to plugin containers
• Support both light and dark themes via CSS variables
• Follow Obsidian's 4px spacing grid

• Make all interactive elements keyboard accessible
• Provide ARIA labels for icon buttons
• Define clear focus indicators using

  :focus-visible

• Use

  data-tooltip-position

  for tooltips
• Ensure minimum touch target size (44×44px)
• Manage focus properly in modals
• Test with keyboard navigation

• Use async/await (not Promise chains)
• Remove all sample/template code
• Test on mobile (if not desktop-only)
• Follow semantic versioning
• Minimize console logging (no console.log in onload/onunload in production)

Don'ts ❌

• Don't store view references in plugin properties
• Don't pass plugin as component to MarkdownRenderer
• Don't detach leaves in

  onunload()

• Don't cast to TFile/TFolder (use

  instanceof

  )
• Don't use

  any

  type
• Don't use

  var

• Don't use global

  app

  object
• Don't use

  Vault.modify()

  for active file edits
• Don't hardcode

  .obsidian

  path (use

  vault.configDir

  )
• Don't use

  navigator.platform/userAgent

  (use Platform API)
• Don't iterate vault when direct lookup exists
• Don't use

  fetch()

  (use

  requestUrl()

  instead)

• Don't use Title Case in UI (use sentence case)
• Don't include "command" in command names/IDs
• Don't duplicate plugin ID in command IDs
• Don't set default hotkeys
• Don't create manual HTML headings (use

  .setHeading()

  )
• Don't use "General", "settings", or plugin name in settings headings

• Don't assign styles via JavaScript
• Don't hardcode colors, sizes, or spacing (use CSS variables)
• Don't use broad CSS selectors (scope to plugin)
• Don't manually switch themes (CSS variables adapt automatically)
• Don't create

  <link>

  or

  <style>

  elements (use

  styles.css

  file)

• Don't use

  innerHTML

  /

  outerHTML

  (XSS risk)
• Don't use regex lookbehind (iOS < 16.4 incompatibility)

• Don't create inaccessible interactive elements
• Don't use icon buttons without ARIA labels
• Don't remove focus indicators without alternatives
• Don't make touch targets smaller than 44×44px

• Don't use Promise chains (use async/await)
• Don't use

  document.createElement

  (use Obsidian helpers)
• Don't keep sample class names (MyPlugin, SampleModal, etc.)
• Don't use console.log in onload/onunload (pollutes console in production)

When Reviewing/Writing Code

1. Memory management: Are components and views properly managed?
2. Type safety: Using

   instanceof

   instead of casts?
3. UI text: Is everything in sentence case?
4. Command naming: No redundant words?
5. File operations: Using preferred APIs?
6. Mobile compatibility: No iOS-incompatible features?
7. Sample code: Removed all boilerplate?
8. Manifest: Correct version, valid structure?
9. Accessibility: Keyboard navigation, ARIA labels, focus indicators?
10. Testing: Can you use the plugin without a mouse?
11. Touch targets: Are all interactive elements at least 44×44px?
12. Focus styles: Using

    :focus-visible

    and proper CSS variables?

Common Patterns

Proper Command Registration

// ✅ CORRECT
this.addCommand({
  id: 'insert-timestamp',
  name: 'Insert timestamp',
  editorCallback: (editor: Editor, view: MarkdownView) => {
    editor.replaceSelection(new Date().toISOString());
  }
});

Safe Type Narrowing

// ✅ CORRECT
const file = this.app.vault.getAbstractFileByPath(path);
if (file instanceof TFile) {
  // TypeScript now knows it's a TFile
  await this.app.vault.read(file);
}

Keyboard Accessible Button

// ✅ CORRECT
const button = containerEl.createEl('button', {
  attr: {
    'aria-label': 'Open settings',
    'data-tooltip-position': 'top'
  }
});
button.setText('⚙️');

button.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    performAction();
  }
});

Themed CSS

/* ✅ CORRECT */
.my-plugin-modal {
  background: var(--modal-background);
  color: var(--text-normal);
  padding: var(--size-4-4);
  border-radius: var(--radius-m);
  font-size: var(--font-ui-medium);
}

.my-plugin-button:focus-visible {
  outline: 2px solid var(--interactive-accent);
  outline-offset: 2px;
}

Additional Resources

• ESLint Plugin:

  eslint-plugin-obsidianmd

  (install for automatic checking)
• Obsidian API Docs: https://docs.obsidian.md
• Sample Plugin: https://github.com/obsidianmd/obsidian-sample-plugin
• Community: Obsidian Discord, Forum

Important Notes

• These guidelines are based on

  eslint-plugin-obsidianmd

  which is under active development
• Rules marked as auto-fixable can be automatically corrected with ESLint's

  --fix

  flag
• Accessibility is NOT optional - all interactive elements must be keyboard accessible
• Always test on mobile devices if your plugin is not desktop-only