Obsidian Plugin Development Guidelines

Code Quality

Detailed Guidelines

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

Memory Management & Lifecycle

• Using registerEvent(), addCommand(), registerDomEvent(), registerInterval()
• registerDomEvent() vs manual addEventListener (and the activeDocument drift bug)
• 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
• Declarative settings API (1.13+): migration paths, control types, pitfalls

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
• Avoiding !important (use specificity or CSS variables)
• Avoiding :has selector (toggle classes from TypeScript instead)
• 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
• Deprecated/replaceable packages (e.g., builtin-modules → node:module)

Plugin Submission Requirements

• Repository structure
• Submission process
• Semantic versioning
• Testing checklist
• Additional resources and important notes

Community Plugin Scanner

• What the scanner runs (ESLint rule sets + checks beyond ESLint)
• Scorecard system (Health, Review, Disclosures, improvement tips)
• Version-stamped — the single file to update as the scanner evolves

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

Plugin Submission Validation Workflow

Before submitting a plugin, follow this sequence:

1. Run ESLint — npx eslint . using eslint-plugin-obsidianmd; fix all errors AND warnings (warnings affect your Scorecard)
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. Create GitHub Release — Tag must match manifest.json version; attach main.js, manifest.json, and styles.css (optional)
7. Submit via community.obsidian.md — Sign in, link GitHub account, navigate to Plugins → New plugin, enter repository URL, review Developer policies, and submit

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

Scorecard System

Published plugins receive a Scorecard visible on community.obsidian.md. The Scorecard affects user trust and discoverability — a poor score deters users from installing.

Key points:

• Aim for 90%+ overall score
• Fix ALL ESLint warnings, not just errors — warnings are publicly visible
• Use typescript-eslint/recommendedTypeChecked for type-aware checks
• Add GitHub artifact attestation to releases

See Community Plugin Scanner for full details on scanner checks, Health metrics, Review checks, common warnings, and improvement tips.

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?
13. Settings: Using declarative getSettingDefinitions() on 1.13+? All saved data co-located in plugin.settings?

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

Declarative Settings (1.13+)

// ✅ CORRECT — getSettingDefinitions() replaces display() on 1.13+
getSettingDefinitions() {
  return [
    {
      name: 'Mode',
      control: {
        type: 'dropdown',
        key: 'mode',
        defaultValue: 'fast',
        options: { fast: 'Fast', thorough: 'Thorough' },
      },
    },
  ];
}

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.