Obsidian Sample Plugin Plus

This is a sample plugin for Obsidian with AI-assisted development tools and best practices.

This project uses TypeScript to provide type checking and documentation. The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does.

This sample plugin demonstrates some of the basic functionality the plugin API can do:

• Adds a ribbon icon, which shows a Notice when clicked.
• Adds a command "Open modal (simple)" which opens a Modal.
• Adds a plugin setting tab to the settings page.

What Makes This Plus Version Different?

This template includes additional tools and documentation to improve your development experience:

AI-Assisted Development System

This template uses the OpenSkills system with skills available via npm package.

Setup:

# 1. Install dependencies (includes obsidian-dev-skills)
pnpm install

# 2. Initialize localized skill set (.agent/skills/)
pnpm obsidian-dev-skills

# 3. Set up reference materials (symlinks to core Obsidian repos)
.\scripts\setup-ref-links.bat  # Windows  
# or  [header-9](#header-9)
bash scripts/setup-ref-links.sh  # macOS/Linux

What's included:

• AGENTS.md - OpenSkills entry point for AI agent guidance
• .agent/skills/ folder - Symlinks to centralized skills repository
• Plugin development skills - TypeScript, API patterns, lifecycle management
• Operations skills - Build, release, and maintenance workflows
• Technical references - API docs, manifest rules, file formats
• Project-specific skills - Your custom patterns and conventions

Benefits:

• Single source of truth for development knowledge
• Automatic updates when skills are improved
• Consistent guidance across all your projects
• Specialized knowledge for plugin vs theme development
• Helps AI assistants understand your project structure and coding conventions
• Provides quick reference guides and common task examples

Reference Materials System (.ref folder)

• Symlinks to Obsidian repositories - Easy access to API docs, sample code, and examples
• Centralized storage - All projects share the same reference repos (no duplication)
• 6 core Obsidian projects - API definitions, documentation, sample plugins, ESLint rules
• Project-specific references - Add your own plugin/theme references as needed

ESLint 9 with Obsidian Rules

• Exact parity with Review Bot - Uses the same obsidianmd.configs.recommended configuration
• Automatic migration - Upgrades from ESLint 8 to ESLint 9 automatically
• Smart detection - Handles main.ts in root or src/ folder automatically
• Catches common issues - Command naming, style manipulation, deprecated APIs, and more

See also: obsidian-sample-theme-plus - The companion theme template with similar enhancements.

Recommended Tools and Plugins for Plugin Development

These tools can significantly improve your plugin development workflow:

Hot Reload Plugins

Hot Reload - Automatically reload your plugin when code changes. Dramatically speeds up development by eliminating manual reloads.

Hot Reload Mobile - Mobile-compatible version of Hot Reload for testing on mobile devices.

Improve Code Quality with ESLint

ESLint is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.

• This project already has ESLint preconfigured, you can invoke a check by running pnpm lint
• Together with a custom ESLint plugin for Obsidian specific code guidelines

Quick Start

For New Plugins (Using This as a Template)

1. Use this template - Click "Use this template" on GitHub or clone this repo
2. Install dependencies: pnpm install
3. Initialize skills: pnpm obsidian-dev-skills
4. Optional: Setup reference materials (recommended):
   • Windows: scripts\setup-ref-links.bat
   • macOS/Linux: ./scripts/setup-ref-links.sh
5. Optional: Setup ESLint (recommended):

   node scripts/setup-eslint.mjs
   pnpm install
   pnpm lint
   

6. Start developing: pnpm dev

For Existing Plugins (Upgrading to This System)

You can add these enhancements to your existing plugin:

1. Copy these folders/files to your plugin:

   • AGENTS.md → Your plugin root
   • .agents/ folder → Your plugin root
   • scripts/ folder → Your plugin root

2. Initialize skills:

   • Run pnpm obsidian-dev-skills to seed the .agent/skills/ folder and automatically generate AGENTS.md.

3. Setup reference materials:

   • Windows: scripts\setup-ref-links.bat
   • macOS/Linux: ./scripts/setup-ref-links.sh
   • This creates symlinks to Obsidian reference repos in .ref/ folder

4. Setup ESLint (recommended):

   node scripts/setup-eslint.mjs
   pnpm install
   pnpm lint
   

   What the setup script does automatically:

   • Updates package.json with ESLint 9 dependencies and lint scripts
   • Creates/updates eslint.config.mjs (ESLint 9 flat config)
   • Updates esbuild.config.mjs (fixes builtinModules import, adds entry point detection, ensures output to root)
   • Creates scripts/lint-wrapper.mjs (adds helpful success messages)
   • Removes legacy .eslintrc files if present

   Note: The script will update your existing esbuild.config.mjs and eslint.config.mjs files, but it preserves your custom configuration where possible. Review the changes after running the script.

   Important: Don't copy package.json from this template - it contains template-specific values. The setup script will update your existing package.json with only the necessary ESLint dependencies and scripts.

First Time Developing Plugins?

• Check if someone already developed a plugin for what you want!
• Make a copy of this repo as a template with the "Use this template" button
• Clone your repo to a local development folder
• Install NodeJS (v16+), then run pnpm install
• Run pnpm dev to compile your plugin (builds to main.js in root)
• For releases, run pnpm build which creates main.js in root
• Reload Obsidian to load the new version of your plugin
• Enable plugin in settings window

How to Use

Basic Development

• Clone this repo
• Make sure your NodeJS is at least v16 (node --version)
• pnpm install to install dependencies (or npm install - it will automatically proxy to pnpm)
• Development: pnpm dev - Builds to main.js in root with watch mode
• Production: pnpm build - Builds to main.js in root (one-time build)

Note: This project uses pnpm, but npm install, npm run build, npm run dev, and npm run lint will also work for backwards compatibility. The npm install command automatically proxies to pnpm install via a preinstall hook.

Using the AI System

• Bootstrapping with AI: Before providing instructions to your AI agent, visit the prompts/ folder. Copy the starter-prompt.md, fill in your project details, and provide it to your agent to perfectly initialize the development environment.
• Initialize Skills: Run pnpm obsidian-dev-skills to populate or update the .agent/skills/ folder with the latest localized knowledge and automatically update AGENTS.md.
• Read AGENTS.md for project-specific instructions
• Use npx openskills read <skill-name> to load specialized knowledge
• Check .agent/skills/*/references/ for deep technical guides

Using ESLint

• Check for issues: pnpm lint (shows helpful success message when passing)
• Auto-fix issues: pnpm lint:fix

The lint commands use scripts/lint-wrapper.mjs which adds helpful success messages. This file is automatically created/updated when you run node scripts/setup-eslint.mjs.

Releasing New Releases

• Update your manifest.json with your new version number and minimum Obsidian version
• Update your versions.json file with "new-plugin-version": "minimum-obsidian-version"
• Build for production: Run pnpm build
  • Creates main.js in the root directory (compiled from TypeScript)
• Create new GitHub release using your new version number as the "Tag version" (no v prefix)
• Upload these files to the release:
  • main.js (from root)
  • manifest.json (from root)
  • styles.css (from root, if present)
• Publish the release

Tip: You can simplify the version bump process by running pnpm version patch, pnpm version minor or pnpm version major after updating minAppVersion manually in manifest.json.

Adding Your Plugin to the Community Plugin List

• Check the plugin guidelines
• Publish an initial version
• Make sure you have a README.md file in the root of your repo
• Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin

Manually Installing the Plugin

• Copy over main.js, manifest.json, and styles.css (if present) from the root directory to your vault VaultFolder/.obsidian/plugins/your-plugin-id/

Funding URL

You can include funding URLs in your manifest.json file:

{
    "fundingUrl": "https://buymeacoffee.com"
}

Or for multiple URLs:

{
    "fundingUrl": {
        "Buy Me a Coffee": "https://buymeacoffee.com",
        "GitHub Sponsor": "https://github.com/sponsors"
    }
}

Troubleshooting

Upgrade Issues

If you're upgrading an existing plugin and encounter issues:

1. ESLint errors after setup: Run pnpm install to ensure all dependencies are installed
2. Build errors: Check that esbuild.config.mjs was updated correctly (the setup script should handle this automatically)
3. Entry point not found: The setup script adds entry point detection - verify esbuild.config.mjs has the detection logic for both src/main.ts and main.ts
4. Package.json conflicts: Don't copy package.json from the template - the setup script updates your existing one with only the necessary additions

Common Issues

• .ref folder is empty: Run the setup script (scripts\setup-ref-links.bat or .sh)
• Linting fails: Make sure you ran pnpm install after running the ESLint setup script
• Build fails: Check that esbuild.config.mjs exists and has the correct entry point detection

API Documentation

See https://docs.obsidian.md