mirror of
https://github.com/tailormade-eu/obsidian-task-export-plugin.git
synced 2026-07-22 06:41:42 +00:00
Add README and requirements documentation for task export plugin
This commit is contained in:
Raoul Jacobs
commit
1ad834e2ca
3 changed files with 989 additions and 0 deletions
363
README.md
Normal file
363
README.md
Normal file
|
|
@ -0,0 +1,363 @@
|
|||
# obsidian-task-export-plugin
|
||||
|
||||
Automatically export outstanding tasks from your Obsidian vault to CSV for ManicTime integration.
|
||||
|
||||
## Description
|
||||
|
||||
An Obsidian plugin that monitors your customer project files and automatically exports outstanding tasks to CSV format. Integrates seamlessly into your Obsidian workflow with command palette support, automatic file watching, and configurable export options.
|
||||
|
||||
## Features
|
||||
|
||||
- 🎨 **Command Palette Integration** - Export tasks with keyboard shortcuts
|
||||
- 🔄 **Automatic Export** - Watch for file changes and auto-export
|
||||
- ⚙️ **Settings Panel** - Fully configurable export behavior
|
||||
- 🎯 **Ribbon Icon** - Quick access from sidebar
|
||||
- 📊 **Status Bar** - Shows last export time
|
||||
- 🔔 **Notifications** - Success/error feedback
|
||||
- 🚀 **Debounced Updates** - Efficient file watching
|
||||
- 📁 **Selective Monitoring** - Only watches relevant folders
|
||||
- ⚡ **High Performance** - Async processing, file caching
|
||||
|
||||
## Installation
|
||||
|
||||
### From Obsidian Community Plugins
|
||||
|
||||
> Plugin not yet published to community store
|
||||
|
||||
1. Open Obsidian Settings
|
||||
2. Navigate to Community Plugins
|
||||
3. Search for "Task Export Tool"
|
||||
4. Click Install and Enable
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Download the latest release from [GitHub Releases](https://github.com/tailormade-eu/obsidian-task-export-plugin/releases)
|
||||
2. Extract `main.js`, `manifest.json`, and `styles.css` to:
|
||||
```
|
||||
VaultFolder/.obsidian/plugins/task-export-plugin/
|
||||
```
|
||||
3. Reload Obsidian
|
||||
4. Enable plugin in Settings → Community Plugins
|
||||
|
||||
### Development Build
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/tailormade-eu/obsidian-task-export-plugin.git
|
||||
cd obsidian-task-export-plugin
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build plugin
|
||||
npm run build
|
||||
|
||||
# For development with auto-reload
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Install and enable the plugin
|
||||
2. Open Settings → Task Export Tool
|
||||
3. Configure "Customers Folder" path (default: `Customers`)
|
||||
4. Press `Ctrl/Cmd + P` → "Export Outstanding Tasks"
|
||||
5. Find `outstanding_tasks.csv` in your vault root
|
||||
|
||||
## Usage
|
||||
|
||||
### Manual Export
|
||||
|
||||
**Via Command Palette:**
|
||||
1. Press `Ctrl/Cmd + P`
|
||||
2. Type "Export Outstanding Tasks"
|
||||
3. Press Enter
|
||||
4. Notification shows export success
|
||||
|
||||
**Via Ribbon Icon:**
|
||||
- Click the export icon (📊) in left sidebar
|
||||
|
||||
### Automatic Export
|
||||
|
||||
1. Open Settings → Task Export Tool
|
||||
2. Enable "Auto Export"
|
||||
3. Choose trigger: "On Save" or "On File Change"
|
||||
4. Edit any `.md` file in Customers folder
|
||||
5. CSV automatically updates in background
|
||||
|
||||
### Status Bar
|
||||
|
||||
View last export time and status in bottom status bar:
|
||||
- ✅ "Last export: 2 minutes ago" (success)
|
||||
- ⚠️ "Export failed" (error - click for details)
|
||||
|
||||
## Settings
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Setting | Description | Default | Type |
|
||||
|---------|-------------|---------|------|
|
||||
| **Output Path** | CSV file location (relative to vault) | `outstanding_tasks.csv` | Text |
|
||||
| **Customers Folder** | Root folder with customer files | `Customers` | Text |
|
||||
| **Auto Export** | Enable automatic export | `false` | Toggle |
|
||||
| **Export on Save** | Trigger on file save | `true` | Toggle |
|
||||
| **Export on Modify** | Trigger on any modification | `false` | Toggle |
|
||||
| **Show Notifications** | Display export notifications | `true` | Toggle |
|
||||
| **Debounce Delay** | Wait time after changes (seconds) | `3` | Number |
|
||||
|
||||
### Accessing Settings
|
||||
|
||||
Settings → Plugin Options → Task Export Tool
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description | Default Hotkey |
|
||||
|---------|-------------|----------------|
|
||||
| **Export Outstanding Tasks** | Manually trigger export | None |
|
||||
| **Toggle Auto-Export** | Enable/disable automatic export | None |
|
||||
| **Open Export Settings** | Jump to plugin settings | None |
|
||||
|
||||
### Custom Hotkeys
|
||||
|
||||
Assign hotkeys via: Settings → Hotkeys → Search "Task Export"
|
||||
|
||||
## Input Format
|
||||
|
||||
### Vault Structure
|
||||
|
||||
```
|
||||
YourVault/
|
||||
├── Customers/ ← Configured folder
|
||||
│ ├── Customer A/
|
||||
│ │ ├── Project 1.md
|
||||
│ │ └── Project 2.md
|
||||
│ └── Customer B/
|
||||
│ └── SubFolder/
|
||||
│ └── Project X.md
|
||||
├── outstanding_tasks.csv ← Output file
|
||||
└── .obsidian/
|
||||
└── plugins/
|
||||
└── task-export-plugin/
|
||||
```
|
||||
|
||||
### Markdown Task Format
|
||||
|
||||
Standard Markdown task checkboxes:
|
||||
|
||||
```markdown
|
||||
## Section
|
||||
|
||||
- [ ] Outstanding task
|
||||
- [x] Completed task (ignored)
|
||||
- [ ] Task with sub-items
|
||||
- [ ] Sub-task (nested)
|
||||
|
||||
### Subsection
|
||||
|
||||
- [ ] Another task
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
CSV with dynamic columns:
|
||||
|
||||
```csv
|
||||
CustomerName,ProjectName,Header1,Header2,Header3,Task
|
||||
Customer A,Project 1,Section,Outstanding task
|
||||
Customer A,Project 1,Section,Task with sub-items
|
||||
Customer A,Project 1,Section,Sub-task (nested)
|
||||
Customer A,Project 1,Section,Subsection,Another task
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- TypeScript
|
||||
- Obsidian Plugin API
|
||||
- Rollup (bundling)
|
||||
- Node.js (development)
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
obsidian-task-export-plugin/
|
||||
├── src/
|
||||
│ ├── main.ts # Plugin entry point
|
||||
│ ├── settings.ts # Settings interface
|
||||
│ ├── exporter.ts # Export logic
|
||||
│ ├── parser.ts # Markdown parsing
|
||||
│ ├── csv-writer.ts # CSV generation
|
||||
│ └── file-watcher.ts # File monitoring
|
||||
├── manifest.json # Plugin metadata
|
||||
├── package.json # Dependencies
|
||||
├── tsconfig.json # TypeScript config
|
||||
├── rollup.config.js # Build config
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Key APIs Used
|
||||
|
||||
- `app.vault.getMarkdownFiles()` - File enumeration
|
||||
- `app.vault.read(file)` - File reading
|
||||
- `app.vault.adapter.write()` - CSV writing
|
||||
- `app.workspace.on('file-modified')` - File watching
|
||||
- `addCommand()` - Command registration
|
||||
- `addSettingTab()` - Settings UI
|
||||
- `addRibbonIcon()` - Sidebar icon
|
||||
- `addStatusBarItem()` - Status bar
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- **File Caching**: Only re-parse modified files
|
||||
- **Debouncing**: Waits for changes to settle (configurable delay)
|
||||
- **Async Processing**: Non-blocking file operations
|
||||
- **Selective Watching**: Only monitors Customers folder
|
||||
- **Incremental Updates**: Smart change detection
|
||||
|
||||
### Expected Performance
|
||||
|
||||
- Initial scan of 100 files: < 2 seconds
|
||||
- Auto-export after file change: < 500ms
|
||||
- Memory footprint: < 10MB
|
||||
- CPU usage: Minimal (idle when no changes)
|
||||
|
||||
## Development
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# Development build with watch mode
|
||||
npm run dev
|
||||
|
||||
# Production build (minified)
|
||||
npm run build
|
||||
|
||||
# Type checking
|
||||
npm run check
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Run tests with coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Hot Reload
|
||||
|
||||
Install [Hot Reload Plugin](https://github.com/pjeby/hot-reload) for automatic plugin reload during development.
|
||||
|
||||
### Debugging
|
||||
|
||||
1. Open Developer Tools: `Ctrl/Cmd + Shift + I`
|
||||
2. Check Console tab for logs
|
||||
3. Use `console.log()` in code
|
||||
4. Set breakpoints in Sources tab
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin Not Loading
|
||||
|
||||
1. Check console for errors: `Ctrl/Cmd + Shift + I`
|
||||
2. Verify files in `.obsidian/plugins/task-export-plugin/`:
|
||||
- `main.js`
|
||||
- `manifest.json`
|
||||
- `styles.css` (optional)
|
||||
3. Check Obsidian version compatibility in `manifest.json`
|
||||
4. Disable and re-enable plugin
|
||||
|
||||
### Auto-Export Not Working
|
||||
|
||||
1. Verify "Auto Export" is enabled in settings
|
||||
2. Check "Customers Folder" path is correct
|
||||
3. Ensure files are `.md` format
|
||||
4. Check console for errors
|
||||
5. Try manual export first
|
||||
|
||||
### CSV Not Generated
|
||||
|
||||
1. Verify output path is writable
|
||||
2. Check at least one unchecked task exists
|
||||
3. Look for error notifications
|
||||
4. Check console for detailed errors
|
||||
5. Try different output location
|
||||
|
||||
### Performance Issues
|
||||
|
||||
1. Disable "Export on Modify" (use "On Save" instead)
|
||||
2. Increase "Debounce Delay" in settings
|
||||
3. Check file cache is working (look for "Using cached" in console with verbose logging)
|
||||
4. Reduce number of files in Customers folder
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [x] Basic task extraction
|
||||
- [x] Command palette integration
|
||||
- [x] Auto-export on file changes
|
||||
- [x] Settings panel
|
||||
- [ ] Export templates
|
||||
- [ ] Multiple output formats (JSON, XML)
|
||||
- [ ] Task filtering (by date, tags)
|
||||
- [ ] Statistics dashboard
|
||||
- [ ] Direct ManicTime API integration
|
||||
- [ ] Custom task patterns
|
||||
- [ ] Scheduled exports
|
||||
- [ ] Export history
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome!
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
||||
3. Make your changes
|
||||
4. Add tests for new functionality
|
||||
5. Commit changes: `git commit -m 'Add amazing feature'`
|
||||
6. Push to branch: `git push origin feature/amazing-feature`
|
||||
7. Open a Pull Request
|
||||
|
||||
### Code Style
|
||||
|
||||
- Use TypeScript strict mode
|
||||
- Follow Obsidian plugin conventions
|
||||
- Add JSDoc comments for public APIs
|
||||
- Keep methods focused and testable
|
||||
- Write tests for new features
|
||||
|
||||
## Related Projects
|
||||
|
||||
- **[markdown-task-export](https://github.com/tailormade-eu/markdown-task-export)** - C# console application version
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See [LICENSE](LICENSE) file for details
|
||||
|
||||
## Support
|
||||
|
||||
- 🐛 **Report Bugs**: [GitHub Issues](https://github.com/tailormade-eu/obsidian-task-export-plugin/issues)
|
||||
- 💬 **Discussions**: [GitHub Discussions](https://github.com/tailormade-eu/obsidian-task-export-plugin/discussions)
|
||||
- 📖 **Documentation**: [Wiki](https://github.com/tailormade-eu/obsidian-task-export-plugin/wiki)
|
||||
- ⭐ **Star** the repo if you find it useful!
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Built with the [Obsidian Plugin Developer Guide](https://docs.obsidian.md/)
|
||||
- Inspired by the need for better task tracking integration
|
||||
- Thanks to the Obsidian community
|
||||
|
||||
## Author
|
||||
|
||||
Created for personal use in managing customer project tasks with time tracking integration.
|
||||
146
docs/COPILOT-PROMPT.md
Normal file
146
docs/COPILOT-PROMPT.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# Task Export Tool - Iteration 2 (Obsidian Plugin)
|
||||
|
||||
Create an Obsidian plugin that extracts outstanding tasks from Markdown files and exports them to a CSV file for ManicTime time tracking.
|
||||
|
||||
## Overview
|
||||
|
||||
This iteration builds upon Iteration 1 (C# Console App) by integrating the task export functionality directly into Obsidian as a plugin, providing on-demand and automatic export capabilities.
|
||||
|
||||
## Requirements
|
||||
|
||||
### 1. Plugin Features
|
||||
|
||||
- **Manual Export**: Add a command to the command palette to export tasks on demand
|
||||
- **Automatic Export**: Watch for file changes and automatically regenerate the CSV when markdown files are modified
|
||||
- **Settings Panel**: Allow users to configure:
|
||||
- Output file location
|
||||
- Customers folder path
|
||||
- Enable/disable automatic export
|
||||
- Export trigger options (on save, on file change, manual only)
|
||||
|
||||
### 2. Task Detection (Same as Iteration 1)
|
||||
|
||||
Find all unchecked tasks marked with `- [ ]` (checkbox syntax in markdown)
|
||||
- Ignore completed tasks marked with `- [x]`
|
||||
- Ignore tasks with checkmarks like `✅ 2025-11-11`
|
||||
|
||||
### 3. Hierarchical Structure Parsing (Same as Iteration 1)
|
||||
|
||||
- Extract markdown headers (##, ###, ####) as Header1, Header2, Header3
|
||||
- Associate each task with its parent headers in the hierarchy
|
||||
- Handle nested/indented tasks (sub-bullets under parent tasks)
|
||||
- When a task has sub-tasks (indented bullets), treat the parent task text as an additional header level
|
||||
|
||||
### 4. Customer and Project Name Extraction (Same as Iteration 1)
|
||||
|
||||
- **CustomerName** = the folder name directly under `Customers/` (e.g., "Belgian Recycling Network (BRN)", "I.Deeds", "Cetec")
|
||||
- **ProjectName** = the markdown filename without extension (e.g., "Billit implementation", "Webshop")
|
||||
- Handle nested customer folders (e.g., `Customers/I.Deeds/Cetec/` → Customer: "I.Deeds", look in subfolder for projects)
|
||||
|
||||
### 5. CSV Output Format (Same as Iteration 1)
|
||||
|
||||
- Header row: `CustomerName,ProjectName,Header1,Header2,Header3,Task`
|
||||
- **Only include header columns that have values** (no empty trailing commas)
|
||||
- If Header2 doesn't exist, row should be: `CustomerName,ProjectName,Header1,Task` (skip empty Header2 and Header3 columns)
|
||||
- Handle commas within task text by properly escaping with quotes
|
||||
- Handle quotes within task text by doubling them
|
||||
|
||||
### 6. Output File
|
||||
|
||||
Create `outstanding_tasks.csv` in the configurable location (default: vault root)
|
||||
|
||||
## Plugin-Specific Features
|
||||
|
||||
### Commands
|
||||
|
||||
1. **Export Outstanding Tasks**: Manually trigger task export
|
||||
2. **Toggle Auto-Export**: Enable/disable automatic export on file changes
|
||||
|
||||
### Settings
|
||||
|
||||
```typescript
|
||||
interface TaskExportSettings {
|
||||
outputPath: string; // Path for CSV output
|
||||
customersFolder: string; // Root folder for customer files
|
||||
autoExport: boolean; // Enable automatic export
|
||||
exportOnSave: boolean; // Export when files are saved
|
||||
exportOnModify: boolean; // Export when files are modified
|
||||
showNotifications: boolean; // Show notifications on export
|
||||
}
|
||||
```
|
||||
|
||||
### User Interface
|
||||
|
||||
- Add ribbon icon for quick export
|
||||
- Show status bar item with last export time
|
||||
- Display notice/notification on successful export
|
||||
- Show error notifications if export fails
|
||||
|
||||
### File Watching
|
||||
|
||||
- Monitor the `Customers/` folder for changes
|
||||
- Debounce file changes (wait 2-3 seconds after last change before exporting)
|
||||
- Only trigger export for `.md` files
|
||||
- Handle bulk operations efficiently
|
||||
|
||||
## Technical Details
|
||||
|
||||
- Use **TypeScript** with Obsidian API
|
||||
- Follow Obsidian plugin development best practices
|
||||
- Use `obsidian` module for API access
|
||||
- Properly handle file system operations through Obsidian's API
|
||||
- Implement proper error handling and logging
|
||||
- Add progress indicators for large exports
|
||||
|
||||
## Plugin Structure
|
||||
|
||||
```
|
||||
task-export-plugin/
|
||||
├── main.ts // Plugin entry point
|
||||
├── settings.ts // Settings interface and tab
|
||||
├── export.ts // Core export logic
|
||||
├── parser.ts // Markdown parsing logic
|
||||
├── csv-writer.ts // CSV generation
|
||||
├── manifest.json // Plugin manifest
|
||||
└── styles.css // Optional styling
|
||||
```
|
||||
|
||||
## Example User Workflows
|
||||
|
||||
### Workflow 1: Manual Export
|
||||
1. User opens command palette (Ctrl/Cmd + P)
|
||||
2. Types "Export Outstanding Tasks"
|
||||
3. Plugin scans Customers folder
|
||||
4. CSV is generated and saved
|
||||
5. Notification shows "Exported 49 tasks to outstanding_tasks.csv"
|
||||
|
||||
### Workflow 2: Automatic Export
|
||||
1. User enables auto-export in settings
|
||||
2. User edits a markdown file in Customers folder
|
||||
3. User saves the file
|
||||
4. Plugin automatically regenerates CSV in background
|
||||
5. Status bar updates to show last export time
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Handle missing Customers folder gracefully
|
||||
- Show helpful error messages for invalid file paths
|
||||
- Log errors to console for debugging
|
||||
- Don't block Obsidian if export fails
|
||||
- Validate CSV output before saving
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Cache parsed files to avoid re-parsing unchanged files
|
||||
- Use debouncing for file change events
|
||||
- Process files asynchronously to avoid blocking UI
|
||||
- Consider limiting auto-export to files in Customers folder only
|
||||
|
||||
## Future Enhancements (Iteration 3?)
|
||||
|
||||
- Filter tasks by date range
|
||||
- Support custom task formats beyond `- [ ]`
|
||||
- Export to multiple formats (JSON, XML, etc.)
|
||||
- Integration with ManicTime API for direct import
|
||||
- Task statistics dashboard in Obsidian
|
||||
- Support for task priorities and tags
|
||||
480
docs/REQUIREMENTS.md
Normal file
480
docs/REQUIREMENTS.md
Normal file
|
|
@ -0,0 +1,480 @@
|
|||
# Requirements - Obsidian Plugin
|
||||
|
||||
Automatically export outstanding tasks from Obsidian vault to CSV for ManicTime time tracking.
|
||||
|
||||
## Overview
|
||||
|
||||
An Obsidian plugin that integrates task export functionality directly into Obsidian, providing both on-demand and automatic export capabilities with a native user experience.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### 1. Plugin Integration
|
||||
|
||||
**Obsidian API Integration**
|
||||
- Use Obsidian Plugin API for all file operations
|
||||
- Register as a community plugin (follows Obsidian guidelines)
|
||||
- Compatible with Obsidian desktop (Windows, macOS, Linux)
|
||||
- Minimal performance impact on Obsidian startup/runtime
|
||||
|
||||
**Plugin Lifecycle**
|
||||
- Load settings on plugin activation
|
||||
- Initialize file watchers conditionally (based on settings)
|
||||
- Clean up resources on plugin deactivation
|
||||
- Save settings changes immediately
|
||||
|
||||
### 2. User Interface Components
|
||||
|
||||
**Command Palette Commands**
|
||||
- "Export Outstanding Tasks" - Trigger manual export
|
||||
- "Toggle Auto-Export" - Enable/disable automatic mode
|
||||
- "Open Export Settings" - Jump to settings panel
|
||||
|
||||
**Ribbon Icon**
|
||||
- Add icon to left sidebar for quick export access
|
||||
- Visual feedback on click (spinning/loading state)
|
||||
- Tooltip: "Export Outstanding Tasks"
|
||||
|
||||
**Status Bar Item**
|
||||
- Display last export timestamp: "Last export: 2 minutes ago"
|
||||
- Show export status: ✅ success, ⚠️ error
|
||||
- Clickable to trigger manual export
|
||||
- Hide when plugin is disabled
|
||||
|
||||
**Settings Tab**
|
||||
- Custom settings panel under Settings → Plugin Options
|
||||
- Input fields for all configurable options
|
||||
- Real-time validation of paths
|
||||
- Reset to defaults button
|
||||
|
||||
**Notifications**
|
||||
- Success: "Exported 49 tasks to outstanding_tasks.csv"
|
||||
- Error: "Export failed: [error message]"
|
||||
- Optional (configurable): Show/hide notifications
|
||||
- Duration: 5 seconds (auto-dismiss)
|
||||
|
||||
### 3. Task Detection (Same as Console App)
|
||||
|
||||
**Task Identification**
|
||||
- Find unchecked tasks: `- [ ]`
|
||||
- Ignore completed: `- [x]`, `✅ 2025-11-11`
|
||||
- Support nested/indented tasks
|
||||
- Multi-line task descriptions
|
||||
|
||||
**Parsing Logic**
|
||||
- Use same extraction rules as console app
|
||||
- Extract hierarchical headers (##, ###, ####)
|
||||
- Associate tasks with parent headers
|
||||
- Handle nested task patterns
|
||||
|
||||
### 4. Export Functionality
|
||||
|
||||
**Manual Export**
|
||||
- Triggered by user command
|
||||
- Scans configured Customers folder
|
||||
- Generates CSV immediately
|
||||
- Shows progress for large exports (> 50 files)
|
||||
- Displays notification on completion
|
||||
|
||||
**Automatic Export**
|
||||
- Triggered by file events (save/modify)
|
||||
- Debounced to avoid excessive exports (configurable delay)
|
||||
- Only monitors files in Customers folder
|
||||
- Runs in background (non-blocking)
|
||||
- Updates status bar on completion
|
||||
|
||||
**File Watching**
|
||||
- Monitor Obsidian vault file events:
|
||||
- `file-modified` event
|
||||
- `file-created` event (if new .md files added)
|
||||
- Filter events to only `.md` files in Customers folder
|
||||
- Implement debouncing (default: 3 seconds)
|
||||
- Unsubscribe when auto-export disabled
|
||||
|
||||
### 5. Settings Management
|
||||
|
||||
**Settings Schema**
|
||||
```typescript
|
||||
interface TaskExportSettings {
|
||||
outputPath: string; // CSV output path (relative to vault)
|
||||
customersFolder: string; // Root customer folder path
|
||||
autoExport: boolean; // Enable auto-export
|
||||
exportOnSave: boolean; // Trigger on file save
|
||||
exportOnModify: boolean; // Trigger on file modify
|
||||
showNotifications: boolean; // Show export notifications
|
||||
debounceDelay: number; // Debounce delay in seconds (1-30)
|
||||
}
|
||||
```
|
||||
|
||||
**Default Values**
|
||||
- outputPath: `outstanding_tasks.csv`
|
||||
- customersFolder: `Customers`
|
||||
- autoExport: `false`
|
||||
- exportOnSave: `true`
|
||||
- exportOnModify: `false`
|
||||
- showNotifications: `true`
|
||||
- debounceDelay: `3`
|
||||
|
||||
**Settings Persistence**
|
||||
- Saved to `.obsidian/plugins/task-export-plugin/data.json`
|
||||
- Load on plugin activation
|
||||
- Save immediately on change
|
||||
- Validate on load (use defaults if invalid)
|
||||
|
||||
### 6. CSV Output (Same as Console App)
|
||||
|
||||
**Format**
|
||||
- Header: `CustomerName,ProjectName,Header1,Header2,Header3,Task`
|
||||
- Dynamic columns (no empty trailing commas)
|
||||
- Proper CSV escaping
|
||||
- UTF-8 with BOM
|
||||
|
||||
**File Writing**
|
||||
- Use Obsidian's `vault.adapter.write()` API
|
||||
- Atomic write (write to temp, then rename)
|
||||
- Handle write failures gracefully
|
||||
- Output path relative to vault root
|
||||
|
||||
### 7. Error Handling
|
||||
|
||||
**User-Facing Errors**
|
||||
- Invalid paths (show notification)
|
||||
- Write permissions issues
|
||||
- No tasks found (info notification)
|
||||
- File reading errors (skip file, continue)
|
||||
|
||||
**Developer Errors**
|
||||
- Log to console for debugging
|
||||
- Don't crash Obsidian
|
||||
- Provide detailed error messages
|
||||
- Graceful degradation
|
||||
|
||||
**Error Recovery**
|
||||
- Retry failed operations once
|
||||
- Fall back to manual export if auto-export fails
|
||||
- Clear error state after successful export
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
|
||||
**Target Metrics**
|
||||
- Plugin activation: < 100ms
|
||||
- Manual export (100 files): < 2 seconds
|
||||
- Auto-export after file change: < 500ms
|
||||
- Memory footprint: < 10MB
|
||||
- No noticeable UI lag
|
||||
|
||||
**Optimization Strategies**
|
||||
- Cache parsed file content (invalidate on change)
|
||||
- Async file operations (don't block main thread)
|
||||
- Debounce file change events
|
||||
- Process files in batches if needed
|
||||
- Only watch configured folder
|
||||
|
||||
### Compatibility
|
||||
|
||||
**Obsidian Version**
|
||||
- Minimum: Obsidian 1.0.0
|
||||
- Tested on latest stable release
|
||||
- API compatibility with mobile (future consideration)
|
||||
|
||||
**Operating Systems**
|
||||
- Windows 10/11
|
||||
- macOS 11+
|
||||
- Linux (major distributions)
|
||||
|
||||
**Vault Types**
|
||||
- Local vaults
|
||||
- Synced vaults (Dropbox, OneDrive, etc.)
|
||||
- Git-based vaults
|
||||
|
||||
### Usability
|
||||
|
||||
**User Experience**
|
||||
- Intuitive settings interface
|
||||
- Clear error messages
|
||||
- Helpful tooltips
|
||||
- Keyboard shortcuts (optional)
|
||||
- Minimal clicks to export
|
||||
|
||||
**Documentation**
|
||||
- README with installation instructions
|
||||
- Settings descriptions
|
||||
- Troubleshooting guide
|
||||
- Example use cases
|
||||
|
||||
### Security
|
||||
|
||||
**File Access**
|
||||
- Only read files user has access to
|
||||
- Only write to configured output path
|
||||
- Don't expose sensitive file contents
|
||||
- Validate all user inputs
|
||||
|
||||
**Data Privacy**
|
||||
- No external network requests
|
||||
- No telemetry/analytics
|
||||
- All processing local
|
||||
- No data leaves user's machine
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### Technology Stack
|
||||
|
||||
**Required**
|
||||
- TypeScript 4.0+
|
||||
- Obsidian Plugin API (latest)
|
||||
- Node.js 16+ (development only)
|
||||
- Rollup (bundling)
|
||||
|
||||
**Optional Libraries**
|
||||
- None required (use vanilla TypeScript/Obsidian API)
|
||||
- Consider: `csv-stringify` for robust CSV generation
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
obsidian-task-export-plugin/
|
||||
├── src/
|
||||
│ ├── main.ts # Plugin entry, command registration
|
||||
│ ├── settings.ts # Settings interface and tab
|
||||
│ ├── exporter.ts # Core export logic
|
||||
│ ├── parser.ts # Markdown parsing
|
||||
│ ├── csv-writer.ts # CSV generation
|
||||
│ ├── file-watcher.ts # File monitoring and debouncing
|
||||
│ └── types.ts # TypeScript interfaces
|
||||
├── tests/
|
||||
│ ├── exporter.test.ts
|
||||
│ ├── parser.test.ts
|
||||
│ └── fixtures/ # Test markdown files
|
||||
├── manifest.json # Plugin metadata
|
||||
├── package.json # Dependencies
|
||||
├── tsconfig.json # TypeScript config
|
||||
├── rollup.config.js # Build configuration
|
||||
├── README.md
|
||||
└── LICENSE
|
||||
```
|
||||
|
||||
### Build System
|
||||
|
||||
**Development**
|
||||
```bash
|
||||
npm run dev # Watch mode with source maps
|
||||
```
|
||||
|
||||
**Production**
|
||||
```bash
|
||||
npm run build # Minified build for distribution
|
||||
```
|
||||
|
||||
**Testing**
|
||||
```bash
|
||||
npm test # Run unit tests
|
||||
npm run test:coverage # Generate coverage report
|
||||
```
|
||||
|
||||
### Plugin Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-export-plugin",
|
||||
"name": "Task Export Tool",
|
||||
"version": "1.0.0",
|
||||
"minAppVersion": "1.0.0",
|
||||
"description": "Export outstanding tasks to CSV for time tracking",
|
||||
"author": "Raoul Jacobs",
|
||||
"authorUrl": "https://github.com/tailormade-eu",
|
||||
"isDesktopOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Core Classes
|
||||
|
||||
**TaskExportPlugin (main.ts)**
|
||||
- Extends `Plugin` class
|
||||
- Registers commands, ribbon icon, status bar
|
||||
- Manages file watcher lifecycle
|
||||
- Handles settings loading/saving
|
||||
|
||||
**TaskExportSettings (settings.ts)**
|
||||
- Extends `PluginSettingTab`
|
||||
- Builds settings UI
|
||||
- Validates user inputs
|
||||
- Saves settings on change
|
||||
|
||||
**TaskExporter (exporter.ts)**
|
||||
- Main export orchestration
|
||||
- File enumeration via Obsidian API
|
||||
- Calls parser for each file
|
||||
- Aggregates results
|
||||
- Writes CSV output
|
||||
|
||||
**MarkdownParser (parser.ts)**
|
||||
- Parses markdown content
|
||||
- Extracts headers and tasks
|
||||
- Maintains hierarchical context
|
||||
- Returns structured data
|
||||
|
||||
**CsvWriter (csv-writer.ts)**
|
||||
- Formats data as CSV
|
||||
- Handles escaping
|
||||
- Writes to file via Obsidian API
|
||||
|
||||
**FileWatcher (file-watcher.ts)**
|
||||
- Subscribes to file events
|
||||
- Implements debouncing
|
||||
- Filters relevant files
|
||||
- Triggers exports
|
||||
|
||||
### State Management
|
||||
|
||||
**Plugin State**
|
||||
- Current settings
|
||||
- Last export timestamp
|
||||
- Export in progress flag
|
||||
- Cached file content (optional)
|
||||
|
||||
**No Persistent State Required**
|
||||
- All state derived from vault files
|
||||
- Settings persisted by Obsidian
|
||||
|
||||
### Event Handling
|
||||
|
||||
**File Events**
|
||||
```typescript
|
||||
this.registerEvent(
|
||||
this.app.workspace.on('file-modified', (file) => {
|
||||
if (shouldExport(file)) {
|
||||
debouncedExport();
|
||||
}
|
||||
})
|
||||
);
|
||||
```
|
||||
|
||||
**Command Events**
|
||||
```typescript
|
||||
this.addCommand({
|
||||
id: 'export-tasks',
|
||||
name: 'Export Outstanding Tasks',
|
||||
callback: () => this.exportTasks()
|
||||
});
|
||||
```
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
**Parser Tests**
|
||||
- Task detection patterns
|
||||
- Header hierarchy extraction
|
||||
- Nested task handling
|
||||
- Edge cases (empty files, no tasks)
|
||||
|
||||
**CSV Writer Tests**
|
||||
- Proper escaping (commas, quotes)
|
||||
- Dynamic column generation
|
||||
- UTF-8 encoding
|
||||
|
||||
**Exporter Tests**
|
||||
- Customer/Project name extraction
|
||||
- File enumeration
|
||||
- Error handling
|
||||
|
||||
### Integration Tests
|
||||
|
||||
**Manual Export**
|
||||
- Command execution
|
||||
- Progress indication
|
||||
- Notification display
|
||||
- File writing
|
||||
|
||||
**Auto Export**
|
||||
- File watching activation
|
||||
- Debouncing behavior
|
||||
- Background processing
|
||||
|
||||
### Test Fixtures
|
||||
|
||||
Sample vault structure:
|
||||
```
|
||||
test-vault/
|
||||
├── Customers/
|
||||
│ ├── Customer A/
|
||||
│ │ └── Project 1.md
|
||||
│ └── Customer B/
|
||||
│ └── Project 2.md
|
||||
└── outstanding_tasks.csv
|
||||
```
|
||||
|
||||
Sample markdown files with:
|
||||
- Various task patterns
|
||||
- Different header structures
|
||||
- Special characters
|
||||
- Nested tasks
|
||||
|
||||
## Publishing Requirements
|
||||
|
||||
### Obsidian Community Plugin Submission
|
||||
|
||||
**Required Files**
|
||||
- `manifest.json` - Plugin metadata
|
||||
- `main.js` - Compiled plugin code
|
||||
- `styles.css` - Optional styling
|
||||
- `README.md` - Documentation
|
||||
- `LICENSE` - Open source license (MIT recommended)
|
||||
|
||||
**Review Criteria**
|
||||
- Code quality and security
|
||||
- No external network requests
|
||||
- Proper error handling
|
||||
- Clear documentation
|
||||
- Follows Obsidian guidelines
|
||||
|
||||
**Submission Process**
|
||||
1. Create GitHub repository
|
||||
2. Add plugin to Obsidian community plugins list (PR)
|
||||
3. Wait for review and approval
|
||||
4. Plugin listed in Obsidian's plugin browser
|
||||
|
||||
### Release Process
|
||||
|
||||
**Version Tagging**
|
||||
- Follow semantic versioning: `v1.0.0`
|
||||
- Create GitHub release with:
|
||||
- Release notes
|
||||
- Attached `main.js`, `manifest.json`, `styles.css`
|
||||
|
||||
**Changelog**
|
||||
- Maintain `CHANGELOG.md`
|
||||
- Document breaking changes
|
||||
- List new features and fixes
|
||||
|
||||
## Success Criteria
|
||||
|
||||
The plugin is successful if it:
|
||||
|
||||
1. ✅ Installs and activates without errors
|
||||
2. ✅ Correctly exports all unchecked tasks from test vault
|
||||
3. ✅ Auto-export works reliably with file changes
|
||||
4. ✅ Settings persist across Obsidian restarts
|
||||
5. ✅ No performance impact on Obsidian UI
|
||||
6. ✅ Handles errors gracefully without crashing
|
||||
7. ✅ Compatible with latest Obsidian version
|
||||
8. ✅ CSV validates successfully in ManicTime
|
||||
9. ✅ Has 80%+ code coverage in tests
|
||||
10. ✅ Passes Obsidian plugin review (if submitted)
|
||||
|
||||
## Future Enhancements (Out of Scope for v1)
|
||||
|
||||
- Mobile support (iOS/Android)
|
||||
- Export templates (custom CSV formats)
|
||||
- Multiple output formats (JSON, XML)
|
||||
- Task filtering (by date, tags, priority)
|
||||
- Statistics dashboard
|
||||
- Direct ManicTime API integration
|
||||
- Scheduled exports (daily, weekly)
|
||||
- Export history viewer
|
||||
- Task completion tracking
|
||||
- Custom task patterns (beyond `- [ ]`)
|
||||
Loading…
Reference in a new issue