mirror of
https://github.com/keathmilligan/obsidian-paste-reformatter.git
synced 2026-07-22 05:43:44 +00:00
73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# Obsidian Plugin Development Guidelines
|
|
|
|
This is an Obsidian plugin project. Follow these guidelines when working with the codebase.
|
|
|
|
## Reference Documentation
|
|
|
|
- Official guide: https://docs.obsidian.md/Plugins/Getting+started/Build+a+plugin
|
|
- API reference: https://docs.obsidian.md/Reference/TypeScript+API/Plugin
|
|
- TypeScript API: Use `obsidian` module types
|
|
|
|
## Project Structure
|
|
|
|
- `main.ts` - Main plugin entry point (extends `Plugin` class)
|
|
- `manifest.json` - Plugin metadata (id, name, version, minAppVersion)
|
|
- `styles.css` - Plugin styles (optional)
|
|
- `src/` - Additional source files and modules
|
|
|
|
## Best Practices
|
|
|
|
### Security & DOM Manipulation
|
|
- **Never** use `innerHTML` or `outerHTML` (security risk)
|
|
- Use DOM APIs (`createElement`, `appendChild`, etc.) or Obsidian helper functions
|
|
- Sanitize user input before rendering
|
|
- Prefer `createEl()` and `createDiv()` methods from Obsidian API
|
|
|
|
### Styling
|
|
- Avoid assigning styles via JavaScript or inline HTML
|
|
- Move all styles to CSS files for better theme compatibility
|
|
- Use CSS variables for colors and spacing when possible
|
|
- Follow Obsidian's design language
|
|
- Use `app.workspace.containerEl.win` to access the window object for styles
|
|
|
|
### Settings
|
|
- Use the `Setting` API for all settings components
|
|
- Include proper headings and dividers using the Settings API
|
|
- Use sentence case for all UI text and headings
|
|
- Organize settings logically into sections
|
|
- Store settings in a dedicated settings object
|
|
- Call `saveData()` after settings changes
|
|
|
|
### Code Organization
|
|
- Keep main plugin file lean, delegate to separate modules
|
|
- Use TypeScript for better type safety
|
|
- Follow async/await patterns for asynchronous operations
|
|
- Clean up resources in `onunload()` method
|
|
- Use `addCommand()` for command palette integration
|
|
- Use `registerEvent()` for event listeners to ensure cleanup
|
|
|
|
### Plugin Lifecycle
|
|
- `onload()` - Initialize plugin, register events, commands, settings
|
|
- `onunload()` - Clean up resources, remove event listeners
|
|
- Use `this.register()` to register cleanup callbacks
|
|
- Use `this.registerEvent()` for automatic event cleanup
|
|
|
|
### Common Patterns
|
|
- Access app: `this.app`
|
|
- Access vault: `this.app.vault`
|
|
- Access workspace: `this.app.workspace`
|
|
- Read files: `this.app.vault.read(file)`
|
|
- Modify files: `this.app.vault.modify(file, content)`
|
|
- Create notices: `new Notice("message")`
|
|
|
|
### Development Workflow
|
|
- Use `npm run dev` to watch and rebuild on changes
|
|
- Hot reload: Copy built `main.js` to vault's `.obsidian/plugins/` folder
|
|
- Test in actual Obsidian vault for best results
|
|
- Check console for errors: View > Toggle Developer Tools
|
|
|
|
### Performance
|
|
- Avoid blocking the main thread
|
|
- Use debouncing for frequent operations
|
|
- Be mindful of large vault operations
|
|
- Cache expensive computations when appropriate
|