Obsidian Plugin Development Guidelines

Follow these comprehensive guidelines derived from the official Obsidian ESLint plugin rules, submission requirements, and best practices.

Getting Started

Quick Start Tool

For new plugin projects, an interactive boilerplate generator is available:

• Script:

  tools/create-plugin.js

  in the skill repository
• Command: Invoke

  create-plugin

  using your agent's method (

  /create-plugin

  ,

  $create-plugin

  , or

  @create-plugin

  )
• Generates minimal, best-practice boilerplate with no sample code
• Detects existing projects and only adds missing files

Recommend the boilerplate generator when users ask how to create a new plugin, want to start a new project, or need help setting up the basic structure.

Rules Reference (eslint-plugin-obsidianmd v0.2.3)

Submission & Naming

.?!)

Memory & Lifecycle

registerEvent()

MarkdownRenderer

detachLeavesOfType()

onunload

Type Safety

instanceof

any

var

.instanceOf(T)

instanceof

UI/UX

recommendedWithLocalesEn

.setHeading()

API Best Practices

Vault.modify()

Vault.process()

Vault.modify()

FileManager.trashFile()

Vault.trash()

Vault.delete()

Vault.getAbstractFileByPath()

Vault.getFiles().find()

normalizePath()

.obsidian

Platform

navigator.platform

userAgent

requestUrl()

fetch()

onload

onunload

console.log

onload

onunload

AbstractInputSuggest

TextInputSuggest

minAppVersion

Popout Window Compatibility

activeDocument

activeWindow

document

window

activeWindow.setTimeout()

setInterval()

setTimeout()

setInterval()

Event Handling

evt.defaultPrevented

evt.preventDefault()

Styling

styles.css

no-forbidden-elements

<link>

<style>

Accessibility (MANDATORY)

data-tooltip-position

:focus-visible

Security & Compatibility

createDiv()

createSpan()

createEl()

innerHTML

outerHTML

document.createElement

Code Quality

Object.assign({}, defaults, overrides)

object-assign

Object.assign(defaultsVar, other)

validate-license

Detailed Guidelines

For comprehensive information on specific topics, see the reference files:

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 (TypeScript, JSON locale, TS/JS locale modules)

• recommendedWithLocalesEn

  config for locale file checks
• Command naming conventions (no "command", no plugin name, no plugin ID)
• 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
• Additional resources and important notes

ESLint Setup Guide

• Complete ESLint config for community scanner compliance
• Why

  typescript-eslint

  recommendedTypeChecked is required
• Common violations and fixes (floating promises, require imports, etc.)
• Popout window compatibility rules (new in v0.2.3)

Plugin Submission Validation Workflow

Before submitting a plugin, follow this sequence:

1. Run ESLint —

   npx eslint .

   using

   eslint-plugin-obsidianmd

   ; fix all errors (warnings are informational)
2. Validate manifest — Confirm

   id

   ,

   name

   ,

   description

   ,

   version

   , and

   minAppVersion

   meet naming and formatting rules (rules 1–5)
3. Check LICENSE — Copyright holder must not be "Dynalist Inc." and the year must be current
4. Test on mobile — Verify no regex lookbehind, no

   fetch()

   , and touch targets ≥ 44×44px (skip only if plugin is declared desktop-only)
5. Keyboard accessibility audit — Tab through all interactive elements; confirm focus indicators and ARIA labels are present
6. Submit — Open a PR to the community plugins repository with the updated

   manifest.json

   and

   community-plugins.json

   entry

If ESLint reports new errors after fixing, re-run from step 1.

When Reviewing/Writing Code

Use this checklist for code review and implementation:

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

When helping with Obsidian plugin development, proactively apply these rules and suggest improvements based on these guidelines. Refer to the detailed reference files for comprehensive information on specific topics.