From 20184c8c2faee4d89ac26bbff27272c8723dac74 Mon Sep 17 00:00:00 2001 From: Aleix Soler Date: Sun, 25 May 2025 17:23:23 +0200 Subject: [PATCH] feat: wiki --- README.md | 6 +- wiki/Architecture Overview.md | 364 +--------------------------------- wiki/Configuration Guide.md | 137 +++---------- wiki/Development Setup.md | 150 ++++++++++++++ wiki/Frontmatter Format.md | 115 +++++++++++ wiki/Home Page.md | 66 +----- wiki/Performance Tuning.md | 86 ++++++++ wiki/Quick Start Guide.md | 53 ++--- wiki/User Manual.md | 184 +---------------- 9 files changed, 423 insertions(+), 738 deletions(-) create mode 100644 wiki/Development Setup.md create mode 100644 wiki/Frontmatter Format.md create mode 100644 wiki/Performance Tuning.md diff --git a/README.md b/README.md index 2059cc0..47e13d2 100644 --- a/README.md +++ b/README.md @@ -60,16 +60,16 @@ Track the status of your notes with a powerful, customizable status management s - **[[Quick Start Guide|๐Ÿ“š Quick Start Guide]]** - Get running in 5 minutes - **[[User Manual|๐Ÿ“– User Manual]]** - Complete feature documentation - **[[Configuration Guide|โš™๏ธ Configuration Guide]]** - Settings and customization -- **[[๐Ÿš€ Performance Tuning]]** - Optimize for large vaults +- **[[Performance Tuning|๐Ÿš€ Performance Tuning]]** - Optimize for large vaults ### For Developers - **[[Architecture Overview|๐Ÿ—๏ธ Architecture Overview]]** - Plugin structure and design -- **[[๐Ÿ”ง Development Setup]]** - Contributing guide +- **[[Development Setup|๐Ÿ”ง Development Setup]]** - Contributing guide ### Reference -- **[๐Ÿ“ Frontmatter Format](../../wiki/Frontmatter-Format)** - Technical specification +- **[[Frontmatter Format|๐Ÿ“ Frontmatter Format]]** - Technical specification ## Data Format diff --git a/wiki/Architecture Overview.md b/wiki/Architecture Overview.md index 1692a2d..5fcbfb8 100644 --- a/wiki/Architecture Overview.md +++ b/wiki/Architecture Overview.md @@ -16,222 +16,8 @@ note-status/ โ””โ”€โ”€ styles/ # Modular CSS architecture ``` -### Design Principles - -1. **Separation of Concerns**: Clear boundaries between UI, business logic, and data -2. **Service-Based Architecture**: Core functionality in injectable services -3. **Component Modularity**: Reusable UI components with clear interfaces -4. **Event-Driven Communication**: Loose coupling via custom events -5. **Performance-First**: Optimized for large vaults (40k+ notes tested) - ## Core Services -### StatusService (`services/status-service.ts`) - -**Purpose**: Central hub for all status-related operations -**Key Responsibilities**: - -- Status CRUD operations on files -- Template and custom status management -- Frontmatter parsing and manipulation -- Batch operation handling -- Status validation and normalization - **Design Patterns**: -- **Strategy Pattern**: Different status modification operations (set, add, remove, toggle) -- **Observer Pattern**: Dispatches status change events -- **Template Method**: Standardized status modification workflow - -### StyleService (`services/style-service.ts`) - -**Purpose**: Dynamic CSS generation and theme management -**Key Responsibilities**: - -- Generate CSS rules for custom status colors -- Manage theme compatibility -- Handle dynamic style updates -- CSS injection and cleanup - **CSS Generation Pattern**: - -```css -.status-{statusName} { - color: {statusColor} !important; -} -``` - -## Component Architecture - -### Component Hierarchy - -``` -StatusDropdown (DropdownManager) -โ”œโ”€โ”€ DropdownUI -โ”‚ โ”œโ”€โ”€ DropdownRender -โ”‚ โ”œโ”€โ”€ DropdownPosition -โ”‚ โ””โ”€โ”€ DropdownEvents -โ”œโ”€โ”€ StatusBar (StatusBarController) -โ”‚ โ””โ”€โ”€ StatusBarView -โ”œโ”€โ”€ StatusPane (StatusPaneViewController) -โ”‚ โ””โ”€โ”€ StatusPaneView -โ””โ”€โ”€ ToolbarButton -``` - -### StatusDropdown System - -**Architecture**: Manager โ†’ UI โ†’ Renderer pattern -**DropdownManager** (`components/status-dropdown/dropdown-manager.ts`): - -- High-level dropdown operations -- File and status management -- Event handling coordination - **DropdownUI** (`components/status-dropdown/dropdown-ui.ts`): -- Core UI component management -- DOM manipulation -- Event listener setup/cleanup - **DropdownRender** (`components/status-dropdown/dropdown-render.ts`): - -- Pure rendering functions -- DOM element creation -- Content population - -### StatusBar System - -**Architecture**: Controller โ†’ View pattern - -**StatusBarController**: - -- Business logic and state management -- Settings updates and re-rendering -- Integration with status service - -**StatusBarView**: - -- Pure UI rendering -- DOM manipulation -- No business logic - -### StatusPane System - -**Architecture**: MVC pattern - -**StatusPaneViewController** (Controller): - -- Obsidian view lifecycle management -- User interaction handling -- Data fetching and state management - -**StatusPaneView** (View): - -- Pure rendering functions -- DOM element creation -- No state management - -## Integration Architecture - -### Obsidian API Integration - -#### Workspace Integration (`integrations/workspace/`) - -```typescript -class WorkspaceIntegration { - registerWorkspaceEvents(): void { - this.app.workspace.on("file-open", this.handleFileOpen); - this.app.workspace.on( - "active-leaf-change", - this.handleActiveLeafChange, - ); - this.app.workspace.on("layout-change", this.handleLayoutChange); - } -} -``` - -**Integration Points**: - -- File open events โ†’ Status propagation -- Active leaf changes โ†’ Toolbar updates -- Layout changes โ†’ UI refresh - -#### File Explorer Integration (`integrations/explorer/`) - -**Challenge**: File explorer uses private Obsidian APIs **Solution**: Defensive programming with fallbacks - -```typescript -interface FileExplorerView extends View { - fileItems: Record< - string, - { - el?: HTMLElement; - file?: TFile; - titleEl?: HTMLElement; - selfEl?: HTMLElement; - } - >; -} -``` - -**Performance Optimizations**: - -- Debounced batch updates -- DOM mutation batching -- Memory-efficient icon management - -#### Metadata Cache Integration (`integrations/metadata-cache/`) - -```typescript -class MetadataIntegration { - registerMetadataEvents(): void { - this.app.metadataCache.on("changed", this.handleMetadataChanged); - this.app.metadataCache.on("resolved", this.handleMetadataResolved); - } -} -``` - -**Event Flow**: - -1. File frontmatter changes -2. Metadata cache fires 'changed' event -3. Plugin updates UI components -4. Status change event propagated - -### Event System - -#### Custom Event Architecture - -```typescript -// Event dispatch pattern -window.dispatchEvent(new CustomEvent('note-status:status-changed', { - detail: { statuses: string[], file: string } -})); - -// Event listening pattern -window.addEventListener('note-status:status-changed', this.boundHandler); -``` - -**Event Types**: - -- `note-status:status-changed` - Status updates -- `note-status:update-pane` - Pane refresh requests -- `note-status:settings-changed` - Configuration updates - -#### Event Flow Diagram - -``` -User Action โ†’ Component โ†’ Service โ†’ Event Dispatch โ†’ UI Updates - โ†“ โ†“ โ†“ โ†“ โ†“ -Click Status โ†’ Dropdown โ†’ StatusService โ†’ Custom Event โ†’ All Components -``` - -## Data Flow Architecture - -### State Management - -**Philosophy**: Services as single source of truth, components as views - -``` -Settings (Plugin) โ†โ†’ StatusService โ†โ†’ Components - โ†“ - File System (Frontmatter) -``` - ### Status Change Flow 1. **User Interaction** โ†’ Component captures intent @@ -240,34 +26,6 @@ Settings (Plugin) โ†โ†’ StatusService โ†โ†’ Components 4. **StatusService** โ†’ Dispatches status-changed event 5. **All Components** โ†’ Update their displays -### Performance Optimization Strategies - -#### Large Vault Handling - -**Problem**: 40k+ notes can cause UI lag **Solutions**: - -- Pagination in status pane (configurable page size) -- Debounced file explorer updates -- Optional exclusion of unknown status files -- Lazy loading of status groups - -#### Memory Management - -**Strategies**: - -- Event listener cleanup on plugin unload -- DOM element cleanup in component destroy methods -- Weak references where applicable -- Batch DOM updates to prevent layout thrashing - -#### File System Optimization - -**Techniques**: - -- Batch frontmatter updates -- Debounced metadata cache operations -- Intelligent file filtering before DOM updates - ## CSS Architecture ### Modular CSS Structure @@ -299,119 +57,9 @@ styles/ ### Build Process -**Development**: CSS files watched and bundled automatically **Production**: Minified and optimized CSS output **Hot Reload**: CSS changes reflected immediately in development - -## Plugin Lifecycle - -### Initialization Sequence - -```typescript -async onload() { - await this.loadSettings(); // 1. Load saved configuration - this.initializeServices(); // 2. Create service instances - this.registerViews(); // 3. Register Obsidian views - this.initializeUI(); // 4. Create UI components - this.initializeIntegrations(); // 5. Setup integrations - this.setupCustomEvents(); // 6. Event system setup -} -``` - -### Cleanup Sequence - -```typescript -onunload() { - // Event listeners cleanup - window.removeEventListener('note-status:status-changed', this.boundHandler); - - // Integration cleanup - this.explorerIntegration?.unload(); - this.workspaceIntegration?.unload(); - - // Service cleanup - this.styleService?.unload(); - - // UI cleanup - this.statusBar?.unload(); - this.statusDropdown?.unload(); -} -``` - -## Error Handling Strategy - -### Defensive Programming - -```typescript -// File explorer integration with fallbacks -try { - const fileExplorer = this.findFileExplorerView(); - if (fileExplorer?.fileItems) { - this.updateIcons(fileExplorer); - } else { - this.scheduleRetry(); - } -} catch (error) { - console.error("Note Status: Explorer integration failed", error); - this.fallbackToBasicMode(); -} -``` - -### Error Recovery - -- Graceful degradation when Obsidian APIs change -- Automatic retry mechanisms for transient failures -- User-visible error messages for critical failures -- Comprehensive logging for debugging - -## Extension Points - -### Custom Status Templates - -```typescript -interface StatusTemplate { - id: string; - name: string; - description: string; - statuses: Status[]; -} -``` - -### Plugin API (Future) - -```typescript -// Planned extension API -interface NoteStatusAPI { - registerStatusTemplate(template: StatusTemplate): void; - getFileStatuses(file: TFile): string[]; - setFileStatuses(file: TFile, statuses: string[]): Promise; -} -``` - -### CSS Customization Points - -- Status color overrides -- Component layout modifications -- Animation customization -- Theme integration hooks - -## Testing Strategy - -### Test Categories - -1. **Unit Tests**: Service logic and utilities -2. **Integration Tests**: Obsidian API interactions -3. **Performance Tests**: Large vault scenarios -4. **Manual Tests**: UI interactions and workflows - -### Test Utilities - -```typescript -// Mock file creation for testing -createMockFile(path: string, frontmatter: any): TFile - -// Status service testing helpers -setMockStatuses(file: TFile, statuses: string[]): void -assertStatusEquals(file: TFile, expected: string[]): void -``` +**Development**: CSS files watched and bundled automatically +**Production**: Minified and optimized CSS output +**Hot Reload**: CSS changes reflected immediately in development ## Security Considerations @@ -421,12 +69,6 @@ assertStatusEquals(file: TFile, expected: string[]): void - Status name validation (prevent injection) - File path sanitization -### Permission Model - -- Read-only access to Obsidian settings -- Write access only to note frontmatter -- No network requests or external dependencies - ### Privacy - All data stored locally in vault diff --git a/wiki/Configuration Guide.md b/wiki/Configuration Guide.md index 3d4a86f..0c2b115 100644 --- a/wiki/Configuration Guide.md +++ b/wiki/Configuration Guide.md @@ -19,7 +19,7 @@ Controls which predefined status sets are available. โ˜ Project management (8 development statuses) ``` -**Impact**: Enabled templates add their statuses to dropdown and quick commands. +**Impact**: Enabled templates add their statuses to dropdown. #### Template Details @@ -41,7 +41,7 @@ Controls which predefined status sets are available. ``` ๐Ÿ“Œ todo (#F44336) - Needs attention -โš™๏ธ inProgress (#2196F3) - Currently working +โš™๏ธ inProgress (#2196F3) - Currently working ๐Ÿ‘€ review (#9C27B0) - Needs review โœ“ done (#4CAF50) - Completed ``` @@ -51,7 +51,7 @@ Controls which predefined status sets are available. ``` ๐Ÿ” research (#2196F3) - Information gathering ๐Ÿ“‘ outline (#9E9E9E) - Structure planning -โœ๏ธ draft (#FFC107) - Writing phase +โœ๏ธ draft (#FFC107) - Writing phase ๐Ÿ”ฌ review (#9C27B0) - Peer review stage ๐Ÿ“ revision (#FF5722) - Revisions needed ๐Ÿ“š final (#4CAF50) - Final version @@ -61,16 +61,18 @@ Controls which predefined status sets are available. **Project Management** - Development workflow: ``` -๐Ÿ—“๏ธ planning (#9E9E9E) - Planning phase -๐Ÿ“‹ backlog (#E0E0E0) - Backlog items -๐Ÿšฆ ready (#8BC34A) - Ready to start +๐Ÿ—“๏ธ planning (#9E9E9E) - Planning phase +๐Ÿ“‹ backlog (#E0E0E0) - Backlog items +๐Ÿšฆ ready (#8BC34A) - Ready to start ๐Ÿ‘จโ€๐Ÿ’ป inDevelopment (#2196F3) - Development phase -๐Ÿงช testing (#9C27B0) - Testing phase -๐Ÿ‘๏ธ review (#FFC107) - Code review -๐Ÿ‘ approved (#4CAF50) - Approved -๐Ÿš€ live (#3F51B5) - Production/live +๐Ÿงช testing (#9C27B0) - Testing phase +๐Ÿ‘๏ธ review (#FFC107) - Code review +๐Ÿ‘ approved (#4CAF50) - Approved +๐Ÿš€ live (#3F51B5) - Production/live ``` +![File Explorer Screenshot](images/status-templates.png) + ### User Interface Settings #### Status Bar Configuration @@ -119,11 +121,9 @@ Controls which predefined status sets are available. **When Enabled**: - Clicking status toggles it on/off -- Notes can have combinations like ["active", "inProgress"] +- Notes can have combinations like ("active", "inProgress",....) - Status bar shows all assigned statuses - -**When Disabled**: - + **When Disabled**: - Clicking status replaces current status - Notes have single status only - Simpler workflow for basic usage @@ -141,11 +141,14 @@ Status tag prefix: "obsidian-note-status" ```yaml # Default --- -obsidian-note-status: ["active"] +obsidian-note-status: + - active --- # Custom prefix --- -project-status: ["inProgress", "testing"] +project-status: + - inProgress + - testing --- ``` @@ -190,7 +193,7 @@ Description: [optional tooltip text] - Must be unique across all statuses - Case-sensitive -- No spaces (use camelCase: `inProgress`) +- No spaces - Used in frontmatter and commands **Icon Field**: @@ -288,43 +291,6 @@ Ctrl+Shift+S โ†’ Change status of current note ## Advanced Configuration -### CSS Customization - -#### Status Colors - -Plugin generates CSS variables for each status: - -```css -.status-active { - color: var(--text-success) !important; -} -.status-completed { - color: var(--text-accent) !important; -} -``` - -#### Custom CSS Overrides - -Add to `snippets/note-status-custom.css`: - -```css -/* Larger status icons */ -.note-status-icon { - font-size: 18px !important; -} - -/* Custom status colors */ -.status-urgent { - color: #ff0000 !important; - font-weight: bold !important; -} - -/* Hide status bar completely */ -.note-status-bar { - display: none !important; -} -``` - ### Performance Tuning #### Large Vault Settings (5000+ notes) @@ -344,69 +310,16 @@ Items per page: 50 (reduce from default 100) ### Import/Export Configuration +WIP + #### Export Settings -```javascript -// Console command to export settings -console.log( - JSON.stringify(app.plugins.plugins["note-status"].settings, null, 2), -); -``` +WIP #### Import Process -1. **Copy exported JSON** -2. **Settings โ†’ Note Status โ†’ Import button** (if available) -3. **Or manually edit `data.json` in plugin folder** +WIP #### Migration Between Vaults -```json -{ - "customStatuses": [...], - "enabledTemplates": [...], - "statusColors": {...}, - "quickStatusCommands": [...] -} -``` - -### Team/Shared Configuration - -#### Standardized Setup - -```json -{ - "enabledTemplates": ["project"], - "useCustomStatusesOnly": false, - "strictStatuses": true, - "useMultipleStatuses": true, - "quickStatusCommands": ["inDevelopment", "review", "approved"] -} -``` - -#### Deployment Strategy - -1. **Configure on template vault** -2. **Export settings JSON** -3. **Import on team member vaults** -4. **Document workflow in team wiki** - -### Troubleshooting Configuration - -#### Settings Not Persisting - -- Check file permissions on `.obsidian` folder -- Verify Obsidian has write access -- Restart Obsidian after major changes - -#### Performance Issues - -- Disable file explorer icons temporarily -- Reduce pagination size -- Enable unknown status exclusion - -#### Status Colors Not Showing - -- Check CSS snippet conflicts -- Verify color format in custom statuses -- Clear Obsidian cache and restart +WIP diff --git a/wiki/Development Setup.md b/wiki/Development Setup.md new file mode 100644 index 0000000..1d53360 --- /dev/null +++ b/wiki/Development Setup.md @@ -0,0 +1,150 @@ +# Development Setup + +Get the plugin running locally for development. + +## Prerequisites + +- Node.js 16+ +- npm or yarn +- Git +- Obsidian installed + +## Quick Start + +```bash +# Clone and setup +git clone https://github.com/devonthesofa/obsidian-note-status.git +cd obsidian-note-status +npm install + +# Development mode (hot reload) +npm run dev + +# Build for production +npm run build +``` + +## Development Workflow + +### 1. Link to Test Vault + +```bash +# Symlink to your test vault +ln -s /path/to/obsidian-note-status /path/to/vault/.obsidian/plugins/note-status + +# Windows +mklink /D "C:\Vault\.obsidian\plugins\note-status" "C:\Dev\obsidian-note-status" +``` + +### 2. Enable Plugin + +1. Open Obsidian +2. Settings โ†’ Community plugins โ†’ Disable Safe Mode +3. Enable "Note Status" + +### 3. Hot Reload + +Development mode watches for changes: + +- TypeScript changes โ†’ Auto rebuild +- CSS changes โ†’ Instant update +- Full reload: Ctrl+R in Obsidian + +## Common Development Tasks + +### Add New Status Template + +```typescript +// constants/status-templates.ts +export const PREDEFINED_TEMPLATES: StatusTemplate[] = [ + { + id: "new-workflow", + name: "New Workflow", + description: "Description", + statuses: [{ name: "status1", icon: "๐Ÿ”ฅ", color: "#FF0000" }], + }, +]; +``` + +### Add New Command + +```typescript +// integrations/commands/command-integration.ts +this.plugin.addCommand({ + id: "new-command", + name: "New Command", + callback: () => { + // Implementation + }, +}); +``` + +### Add New Setting + +```typescript +// 1. Update interface in models/types.ts +export interface NoteStatusSettings { + newSetting: boolean; +} + +// 2. Add default in constants/defaults.ts +export const DEFAULT_SETTINGS: NoteStatusSettings = { + newSetting: false, +}; + +// 3. Add UI in integrations/settings/settings-ui.ts +new Setting(containerEl) + .setName("New Setting") + .addToggle((toggle) => + toggle + .setValue(settings.newSetting) + .onChange((value) => + this.callbacks.onSettingChange("newSetting", value), + ), + ); +``` + +## Build & Release + +### Production Build + +```bash +npm run build +# Creates: main.js, manifest.json, styles.css +``` + +### Version Bump + +```bash +npm version patch # or minor/major +# Updates: package.json, manifest.json, versions.json +``` + +### Release Process + +1. Create git tag: `git tag 1.0.13` +2. Push tag: `git push origin 1.0.13` +3. GitHub Actions creates draft release +4. Edit release notes and publish + +### Obsidian DevTools + +- Ctrl+Shift+I โ†’ Console +- Check for plugin errors +- Monitor performance tab + +## Code Style + +- TypeScript strict mode +- Use `const` by default +- Explicit return types +- Handle null/undefined +- Clean up in unload() + +## Contributing + +1. Fork repository +2. Create feature branch +3. Follow existing patterns +4. Test with large vault +5. Submit PR with description diff --git a/wiki/Frontmatter Format.md b/wiki/Frontmatter Format.md new file mode 100644 index 0000000..1a10998 --- /dev/null +++ b/wiki/Frontmatter Format.md @@ -0,0 +1,115 @@ +# Frontmatter Format + +Technical specification for Note Status metadata storage. + +## Format Overview + +Status metadata is stored in YAML frontmatter using a configurable tag prefix. + +```yaml +--- +obsidian-note-status: + - active +--- +``` + +## Specification + +### Field Name + +- **Default**: `obsidian-note-status` +- **Type**: String or Array +- **Configurable**: Yes, via `tagPrefix` setting + +### Value Types + +#### Single Status (Array) + +```yaml +--- +obsidian-note-status: + - active +--- +``` + +#### Multiple Statuses (Array) + +```yaml +--- +obsidian-note-status: + - active + - hello + - world +--- +``` + +## Valid Status Values + +### Default Statuses + +- `unknown` - No status assigned +- Template Statuses: Any status defined in enabled templates + - Must match exact name (case-sensitive) + - Icon and color stored separately +- Custom Statuses: User-defined statuses + - Any string value allowed + - No spaces + - Case-sensitive matching + +## Validation + +With `strictStatuses: true`: + +- Only defined statuses allowed +- Unknown statuses removed on save +- Case-sensitive matching + +## Custom Tag Prefix + +### Configuration + +```javascript +settings.tagPrefix = "project-status"; +``` + +### Result + +```yaml +--- +project-status: + - inDevelopment + - testing +--- +``` + +## Integration Examples + +### Dataview Query + +```dataview +TABLE obsidian-note-status as Status +FROM "" +WHERE contains(obsidian-note-status, "active") +``` + +### Templater + +```yaml +--- +obsidian-note-status: ["<% tp.system.prompt("Status?") %>"] +--- +``` + +### QuickAdd + +```yaml +--- +obsidian-note-status: ["{{VALUE:active,onHold,completed}}"] +--- +``` + +### Reserved Values + +- `unknown` - System reserved +- Empty string - Converted to unknown +- `null`/`undefined` - Treated as unknown diff --git a/wiki/Home Page.md b/wiki/Home Page.md index 622bb33..758d41f 100644 --- a/wiki/Home Page.md +++ b/wiki/Home Page.md @@ -6,46 +6,15 @@ Welcome to the comprehensive documentation for the Note Status plugin for Obsidi ### For Users -- **[Quick Start Guide](https://claude.ai/chat/Quick-Start-Guide)** - Get up and running in 5 minutes -- **[User Manual](https://claude.ai/chat/User-Manual)** - Complete feature documentation -- **[Configuration Guide](https://claude.ai/chat/Configuration-Guide)** - Settings and customization -- **[Performance Tuning](https://claude.ai/chat/Performance-Tuning)** - Optimize for large vaults -- **[Troubleshooting](https://claude.ai/chat/Troubleshooting)** - Common issues and solutions -- **[FAQ](https://claude.ai/chat/FAQ)** - Frequently asked questions +- **[[Quick Start Guide|๐Ÿ“š Quick Start Guide]]** - Get running in 5 minutes +- **[[User Manual|๐Ÿ“– User Manual]]** - Complete feature documentation +- **[[Configuration Guide|โš™๏ธ Configuration Guide]]** - Settings and customization +- **[[Performance Tuning|๐Ÿš€ Performance Tuning]]** - Optimize for large vaults ### For Developers -- **[Architecture Overview](https://claude.ai/chat/Architecture-Overview)** - Plugin structure and design -- **[API Reference](https://claude.ai/chat/API-Reference)** - Core services and interfaces -- **[Development Setup](https://claude.ai/chat/Development-Setup)** - Contributing to the project -- **[Custom Extensions](https://claude.ai/chat/Custom-Extensions)** - Building on top of the plugin -- **[Testing Guide](https://claude.ai/chat/Testing-Guide)** - Testing strategies and tools - -### Reference - -- **[Status Templates](https://claude.ai/chat/Status-Templates)** - Predefined and custom templates -- **[CSS Customization](https://claude.ai/chat/CSS-Customization)** - Styling and theming -- **[Command Reference](https://claude.ai/chat/Command-Reference)** - All available commands -- **[Frontmatter Format](https://claude.ai/chat/Frontmatter-Format)** - Technical specification -- **[Migration Guide](https://claude.ai/chat/Migration-Guide)** - Upgrading between versions - -## ๐Ÿš€ Quick Links - -| Task | Documentation | -| ---------------------- | ----------------------------------------------------------------------------- | -| Install and setup | [Quick Start Guide](https://claude.ai/chat/Quick-Start-Guide) | -| Change note status | [Basic Usage](https://claude.ai/chat/User-Manual#basic-usage) | -| Batch update files | [Batch Operations](https://claude.ai/chat/User-Manual#batch-operations) | -| Create custom statuses | [Custom Statuses](https://claude.ai/chat/Configuration-Guide#custom-statuses) | -| Improve performance | [Performance Tuning](https://claude.ai/chat/Performance-Tuning) | -| Plugin not working | [Troubleshooting](https://claude.ai/chat/Troubleshooting) | - -## ๐Ÿ”ง Plugin Information - -- **Current Version**: 1.0.12 -- **Minimum Obsidian**: 0.15.0 -- **Repository**: [GitHub](https://github.com/devonthesofa/obsidian-note-status) -- **License**: MIT +- **[[Architecture Overview|๐Ÿ—๏ธ Architecture Overview]]** - Plugin structure and design +- **[[Development Setup|๐Ÿ”ง Development Setup]]** - Contributing guide ## ๐Ÿ“ˆ Features Overview @@ -95,31 +64,14 @@ Welcome to the comprehensive documentation for the Note Status plugin for Obsidi - Manage video script statuses - Organize creative project stages -## ๐Ÿ”„ Recent Updates - -### Version 1.0.12 - -- Performance improvements for large vaults -- Enhanced pagination in status pane -- Better error handling and stability - -### Upcoming Features - -- Canvas integration -- Graph view status display -- Enhanced batch operations modal -- Mobile optimization - ## ๐Ÿ’ก Getting Help -1. **Check the [FAQ](https://claude.ai/chat/FAQ)** for common questions -2. **Search the [Troubleshooting](https://claude.ai/chat/Troubleshooting)** guide -3. **Review [GitHub Issues](https://github.com/devonthesofa/obsidian-note-status/issues)** -4. **Create a new issue** with detailed information +1. **Review [GitHub Issues](https://github.com/devonthesofa/obsidian-note-status/issues)** +2. **Create a new issue** with detailed information ## ๐Ÿค Contributing -We welcome contributions! See the [Development Setup](https://claude.ai/chat/Development-Setup) guide to get started. +We welcome contributions! See the [[Development Setup]] guide to get started. - **Report bugs** via GitHub Issues - **Suggest features** in GitHub Discussions diff --git a/wiki/Performance Tuning.md b/wiki/Performance Tuning.md new file mode 100644 index 0000000..6c86122 --- /dev/null +++ b/wiki/Performance Tuning.md @@ -0,0 +1,86 @@ +# Performance Tuning + +Optimize Note Status for large vaults (tested up to 40k notes). + +## Quick Wins + +### Essential Settings for 5k+ Notes + +``` +โœ… Exclude unassigned notes from status pane +โœ… Hide unknown status in file explorer +Pagination: 50-100 items per page +``` + +### Disable Heavy Features + +``` +โ˜ Show status icons in file explorer (if slow) +โ˜ Auto-hide status bar (reduces DOM updates) +``` + +## Minimal Performance Config + +```json +{ + "showStatusIconsInExplorer": false, + "excludeUnknownStatus": true, + "hideUnknownStatusInExplorer": true, + "compactView": true, + "enabledTemplates": ["minimal"] +} +``` + +## Troubleshooting Lag + +### Status Pane Slow + +1. Enable compact view +2. Close unused status groups + +### File Explorer Sluggish + +1. Disable status icons temporarily +2. Restart Obsidian +3. Check for conflicting plugins + +### Dropdown Delay + +Normal behavior - uses debouncing. If excessive: + +- Check console for errors +- Disable strict validation +- Reduce custom statuses count + +## Advanced Optimization + +### Browser DevTools Analysis + +``` +1. Ctrl+Shift+I โ†’ Performance tab +2. Record while opening status pane +3. Look for: + - Long tasks > 50ms + - Excessive DOM operations + - Memory leaks +``` + +## Known Limitations + +### File Explorer Integration + +- Uses private Obsidian APIs +- May break with updates +- Fallback: Disable icons + +### Metadata Cache + +- Triggers on every frontmatter change +- Batched with 100ms debounce +- Can't be optimized further + +### DOM Mutations + +- File explorer recreates elements +- Status pane uses virtual scrolling +- Limit: ~10k visible items diff --git a/wiki/Quick Start Guide.md b/wiki/Quick Start Guide.md index de35419..732d529 100644 --- a/wiki/Quick Start Guide.md +++ b/wiki/Quick Start Guide.md @@ -14,17 +14,23 @@ Get the Note Status plugin working in under 5 minutes. ### Method 2: Manual Installation 1. Download latest release from [GitHub](https://github.com/devonthesofa/obsidian-note-status/releases) -2. Extract to `.obsidian/plugins/note-status/` -3. Enable in Community plugins +2. Extract the following files into your Obsidian vault under `.obsidian/plugins/note-status/`: + - `main.js` + - `manifest.json` + - `styles.css` +3. In Obsidian, go to **Settings โ†’ Community plugins** and enable **Note Status**. ## First Status Assignment ### Using the Toolbar 1. Open any note -2. Click the `โ“` icon in the toolbar +2. Click the `โ“` icon in the toolbar: + - ![Status From Toolbar Screenshot](images/status-from-toolbar.png) 3. Select a status (e.g., "active") -4. Status appears in status bar and file explorer +4. Status appears in status bar and file explorer: + - ![Status Bar Screenshot](images/status-bar.png) + - ![File Explorer Screenshot](images/file-explorer.png) ### Using Commands @@ -46,7 +52,6 @@ Access via Settings โ†’ Note Status: ## Status Templates Enable a template for instant statuses: - **Recommended for beginners: "Minimal workflow"** - `todo` ๐Ÿ“Œ @@ -68,16 +73,18 @@ Enable a template for instant statuses: - Click status icon in left sidebar - See all notes grouped by status - Click any note to open + ![Status Pane Screenshot](images/status-pane.png) ### File Explorer - Status icons appear next to file names - Right-click files to change status -- Select multiple files for batch updates +- Select multiple files for batch updates - ![Status Pane Screenshot](images/batch-updates.png) + ![File Explorer Screenshot](images/file-explorer.png) ## Performance Setup (Large Vaults) -If you have 1000+ notes: +If you have 1000+ notes, set the settings: ``` โœ… Exclude unassigned notes from status pane @@ -90,7 +97,8 @@ The plugin stores statuses in YAML frontmatter: ```yaml --- -obsidian-note-status: ["active"] +obsidian-note-status: + - active --- ``` @@ -98,34 +106,17 @@ Multiple statuses: ```yaml --- -obsidian-note-status: ["active", "inProgress"] +obsidian-note-status: + - idea + - HelloWorld --- ``` ## Next Steps -- **[User Manual](https://claude.ai/chat/User-Manual)** - Complete feature guide -- **[Configuration Guide](https://claude.ai/chat/Configuration-Guide)** - Custom statuses and templates -- **[Performance Tuning](https://claude.ai/chat/Performance-Tuning)** - Optimize for your vault size - -## Common First-Time Issues - -### Status not showing - -- Check that Community plugins are enabled -- Verify the file has `.md` extension -- Look for frontmatter in source mode - -### Performance slow - -- Enable "Exclude unassigned notes" in settings -- Disable file explorer icons temporarily - -### Can't find dropdown - -- Look for `โ“` icon in toolbar (right side) -- Try right-clicking in file explorer -- Use Command Palette: "Change status" +- **[[User Manual]]** - Complete feature guide +- **[[Configuration Guide]]** - Custom statuses and templates +- **[[Performance Tuning]]** - Optimize for your vault size ## Quick Reference diff --git a/wiki/User Manual.md b/wiki/User Manual.md index 958ad21..62d0851 100644 --- a/wiki/User Manual.md +++ b/wiki/User Manual.md @@ -17,7 +17,9 @@ Statuses are stored in YAML frontmatter: ```yaml --- -obsidian-note-status: ["active", "inProgress"] +obsidian-note-status: + - idea + - HelloWorld --- ``` @@ -51,11 +53,15 @@ obsidian-note-status: ["active", "inProgress"] ### 4. File Explorer Integration -**Visual**: Status icons next to file names **Interaction**: Right-click for context menu **Multi-select**: Select multiple files for batch operations +**Visual**: Status icons next to file names +**Interaction**: Right-click for context menu +**Multi-select**: Select multiple files for batch operations ### 5. Status Pane -**Location**: Left sidebar **Access**: Ribbon icon or Command Palette **Features**: +**Location**: Left sidebar +**Access**: Ribbon icon or Command Palette +**Features**: - Notes grouped by status - Search functionality @@ -187,107 +193,7 @@ All commands available via Command Palette: - `Toggle multiple statuses mode` - Enable/disable multi-status - `Search notes by current status` - Global search -## Configuration Options - -### Display Settings - -- **Show status bar**: Toggle status bar visibility -- **Auto-hide status bar**: Hide when status is unknown -- **Show status icons in file explorer**: File tree integration -- **Hide unknown status in file explorer**: Clean up display -- **Default to compact view**: Status pane display mode - -### Performance Settings - -- **Exclude unassigned notes**: Skip unknown status files (recommended for large vaults) -- **Items per page**: Pagination size for status groups - -### Behavior Settings - -- **Enable multiple statuses**: Allow multiple statuses per note -- **Status tag prefix**: YAML frontmatter key (default: `obsidian-note-status`) -- **Strict status validation**: Only allow defined statuses - -## Templates System - -### Predefined Templates - -#### Colorful Workflow - -Complete workflow with descriptive icons: - -- `idea` ๐Ÿ’ก - Initial concepts -- `draft` ๐Ÿ“ - First draft stage -- `inProgress` ๐Ÿ”ง - Active work -- `editing` ๐Ÿ–Š๏ธ - Review and editing -- `pending` โณ - Waiting for input -- `onHold` โธ - Temporarily paused -- `needsUpdate` ๐Ÿ”„ - Requires revision -- `completed` โœ… - Finished work -- `archived` ๐Ÿ“ฆ - Long-term storage - -#### Minimal Workflow - -Essential statuses only: - -- `todo` ๐Ÿ“Œ - Needs attention -- `inProgress` โš™๏ธ - Currently working -- `review` ๐Ÿ‘€ - Needs review -- `done` โœ“ - Completed - -#### Academic Research - -Research-focused workflow: - -- `research` ๐Ÿ” - Information gathering -- `outline` ๐Ÿ“‘ - Structure planning -- `draft` โœ๏ธ - Writing phase -- `review` ๐Ÿ”ฌ - Peer review -- `revision` ๐Ÿ“ - Revisions needed -- `final` ๐Ÿ“š - Final version -- `published` ๐ŸŽ“ - Published work - -#### Project Management - -Development-oriented workflow: - -- `planning` ๐Ÿ—“๏ธ - Planning phase -- `backlog` ๐Ÿ“‹ - Backlog items -- `ready` ๐Ÿšฆ - Ready to start -- `inDevelopment` ๐Ÿ‘จโ€๐Ÿ’ป - Development phase -- `testing` ๐Ÿงช - Testing phase -- `review` ๐Ÿ‘๏ธ - Code review -- `approved` ๐Ÿ‘ - Approved -- `live` ๐Ÿš€ - Production - -### Custom Statuses - -Create your own statuses: - -1. **Settings โ†’ Custom statuses** -2. **Click "Add Status"** -3. **Configure**: - - Name: Unique identifier - - Icon: Emoji or symbol - - Color: Visual theme color - - Description: Tooltip text - -**Validation Rules**: - -- Names must be unique -- Icons recommended (fallback: โ“) -- Colors use CSS format (#hex, var(), etc.) - -## Search and Organization - -### Status Pane Search - -- **Real-time filtering** by filename -- **Case-insensitive** matching -- **Preserves grouping** by status -- **Clears with X button** - -### Global Search Integration +## Global Search Integration Use Obsidian's global search with status queries: @@ -296,12 +202,6 @@ Use Obsidian's global search with status queries: [obsidian-note-status:"inProgress" OR "review"] ``` -### File Organization - -- **Status-based folders**: Manually organize -- **Smart collections**: Use search operators -- **Tag combinations**: Mix with regular tags - ## Keyboard Shortcuts ### Default Shortcuts @@ -318,67 +218,3 @@ None assigned by default - customize in Obsidian settings. ### Quick Status Commands Configure in settings to enable hotkeys for frequently used statuses. - -## Integration Points - -### File System - -- **Frontmatter storage**: Industry standard YAML -- **Cross-platform**: Works with any markdown editor -- **Git-friendly**: Text-based, version controllable - -### Obsidian Features - -- **Global search**: Status-based queries -- **Templates**: Include status in note templates -- **Dataview**: Query notes by status -- **Graph view**: Future integration planned - -### External Tools - -- **Export capabilities**: JSON configuration export -- **Backup strategies**: Include in vault backups -- **Migration**: Frontmatter-based for portability - -## Troubleshooting - -### Common Issues - -#### Status not showing - -1. Verify file has `.md` extension -2. Check frontmatter format in source mode -3. Ensure plugin is enabled - -#### Performance slow with large vault - -1. Enable "Exclude unassigned notes" -2. Reduce pagination size -3. Hide unknown status in explorer - -#### Dropdown not appearing - -1. Check for toolbar button (โ“ icon) -2. Try right-click context menu -3. Use Command Palette fallback - -#### Multiple statuses not working - -1. Enable in settings -2. Check strict validation setting -3. Verify status exists in templates - -### Performance Optimization - -#### Large Vault Tips (5000+ notes) - -- Enable exclusion of unknown status -- Use pagination in status pane -- Disable explorer icons if needed -- Regular cleanup of unused statuses - -#### Memory Management - -- Plugin automatically cleans up -- Restart Obsidian if memory grows -- Report persistent issues on GitHub