obsidian-plugin

# Obsidian Plugin Development

Build production-ready Obsidian plugins using the [obsidian-sample-plugin-plus](https://github.com/davidvkimball/obsidian-sample-plugin-plus) template.

## Quick Start: New Plugin

### 1. Create from Template

```bash
# Clone the template (or use GitHub's "Use this template" button)
gh repo create my-plugin --template davidvkimball/obsidian-sample-plugin-plus --public --clone
cd my-plugin

# Or clone directly
git clone https://github.com/davidvkimball/obsidian-sample-plugin-plus.git my-plugin
cd my-plugin
rm -rf .git && git init
```

### 2. Configure Plugin Identity

Update these files with your plugin's info:

**manifest.json:**
```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.0.1",
  "minAppVersion": "1.5.0",
  "description": "What your plugin does",
  "author": "Your Name",
  "authorUrl": "https://yoursite.com",
  "isDesktopOnly": false
}
```

**package.json:** Update `name`, `description`, `author`, `license`.

**README.md:** Replace template content with your plugin's documentation.

### 3. Initialize Development Environment

```bash
pnpm install
pnpm obsidian-dev-skills          # Initialize AI skills
./scripts/setup-ref-links.sh      # Unix
# or: scripts\setup-ref-links.bat  # Windows
```

### 4. Clean Boilerplate

In `src/main.ts`:
- Remove sample ribbon icon, status bar, commands, modal, and DOM event
- Keep the settings tab if needed, or remove it
- Rename `MyPlugin` class to your plugin name

Delete `styles.css` if your plugin doesn't need custom styles.

## Development Workflow

### Build & Test

```bash
pnpm dev      # Watch mode — rebuilds on changes
pnpm build    # Production build
pnpm lint     # Check for issues
pnpm lint:fix # Auto-fix issues
pnpm test     # Run unit tests
```

### Install in Obsidian

Copy build output to your vault:
```bash
# Unix
cp main.js manifest.json styles.css ~/.obsidian/plugins/my-plugin/

# Or create a symlink for development
ln -s $(pwd) ~/.obsidian/plugins/my-plugin
```

Enable the plugin in Obsidian Settings → Community Plugins.

Use [Hot Reload](https://github.com/pjeby/hot-reload) plugin for automatic reloading during development.

## Plugin Architecture

### Entry Point (`src/main.ts`)

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

export default class MyPlugin extends Plugin {
  settings: MyPluginSettings;

  async onload() {
    await this.loadSettings();
    // Register commands, ribbons, events, views
  }

  onunload() {
    // Cleanup: remove event listeners, views, DOM elements
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}
```

### Settings Pattern

See [references/settings.md](references/settings.md) for the complete settings UI pattern.

### Common Patterns

See [references/patterns.md](references/patterns.md) for:
- Commands (simple, editor, check callbacks)
- Ribbon icons
- Modals
- Events and lifecycle
- File operations
- Editor manipulation

## Constraints

- **No auto-git**: Never run `git commit` or `git push` without explicit approval
- **No eslint-disable**: Fix lint issues properly, don't suppress them
- **No `any` types**: Use proper TypeScript types
- **Sentence case**: UI text uses sentence case (ESLint may false-positive on this — ignore if so)

## Release Checklist

1. Update version in `manifest.json` and `package.json`
2. Update `versions.json` with `"version": "minAppVersion"`
3. Run `pnpm build` — zero errors
4. Run `pnpm lint` — zero issues
5. Create GitHub release with tag matching version (no `v` prefix)
6. Upload: `main.js`, `manifest.json`, `styles.css` (if used)

## References

- [Settings UI](references/settings.md) — Complete settings tab implementation
- [Common Patterns](references/patterns.md) — Commands, modals, events, file operations
- [Obsidian API Docs](https://docs.obsidian.md) — Official documentation