diff --git a/README.md b/README.md index 05a29be..57ffcdb 100644 --- a/README.md +++ b/README.md @@ -1,149 +1,89 @@ # Note Status for Obsidian +[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white)](https://paypal.me/aleixsoler) [![GitHub release](https://img.shields.io/github/v/release/devonthesofa/obsidian-note-status)](https://github.com/devonthesofa/obsidian-note-status/releases) [![Build Status](https://img.shields.io/github/actions/workflow/status/devonthesofa/obsidian-note-status/release.yml)](https://github.com/devonthesofa/obsidian-note-status/actions) [![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?logo=obsidian&color=%23483699&label=downloads&query=%24%5B%22note-status%22%5D.downloads&url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2Fmaster%2Fcommunity-plugin-stats.json)](https://obsidian.md/plugins?id=note-status) [![GitHub License](https://img.shields.io/github/license/devonthesofa/obsidian-note-status)](https://github.com/devonthesofa/obsidian-note-status/blob/master/LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/devonthesofa/obsidian-note-status)](https://github.com/devonthesofa/obsidian-note-status/stargazers) -Track the status of your notes with a powerful, customizable status management system. Mark notes as active, completed, on hold, or create your own custom workflows. +Track the lifecycle of every file with statuses you control. Works on Markdown and non-Markdown, shows badges in the status bar and explorer, and adds commands, dashboards, and quick actions to keep notes moving. -![Status assignment workflow demonstration](images/status-assignment-demo.png) +## Contents -_Alt: Demonstration of assigning status to a note using the toolbar dropdown_ +- [Feature Guide](docs/features.md): what the plugin can do across commands, UI surfaces, and workflows. +- [Settings Reference](docs/settings.md): every option, grouped like the in-app settings. -## 🎯 Features +## Quick start -- **πŸ“‹ Status Assignment** - Mark notes with workflow statuses (active, completed, on hold, etc.) -- **🎯 Multi-Status Support** - Assign multiple statuses per note -- **πŸ“ File Explorer Icons** - Visual indicators next to filenames with configurable positioning -- **🧭 Status Bar Integration** - View current status at bottom of editor -- **⬇️ Toolbar Dropdown** - Change statuses quickly from editor toolbar -- **πŸ“Š Status Dashboard** - Vault overview with statistics and quick actions -- **πŸ“ˆ Grouped View** - Browse notes organized by status with search and filtering -- **⚑ Batch Operations** - Update multiple files simultaneously -- **🎨 Custom Statuses** - Create your own statuses with icons, colors, and descriptions -- **🏷️ Template Scoping** - Organize statuses by note templates -- **πŸš€ Performance Optimized** - Works with large vaults (40k+ notes tested) +1. Open Settings β†’ Note Status. +2. Expand **Templates & Statuses** and keep a built-in template or add your own/custom-only set. +3. Pick where to see/change status: **Status Bar** or **Editor Toolbar**. +4. Set a status from the badge or run `Change current note status`. +5. Watch file explorer icons update; hover for the overview popup or click to change again. +6. If enabled, open the **Status Dashboard** or **Grouped Status View** from the ribbon/commands. -![File explorer with status icons](images/file-explorer-status-icons.png) +## Key features -_Alt: File explorer showing multiple notes with different status icons positioned next to note names and the tooltip with status overview_ +- Status picker everywhere: status bar badge, editor toolbar, explorer context menus, commands. +- Multi-status or single-status workflows; quick-status commands for hotkeys. +- File explorer icons with configurable placement, frames, and visual treatments (row tint, underline, dot, border). +- Status bar badges with accent/filled/dot styles and icon/text options; template names can auto-show on conflicts. +- Dashboards and grouped views (gated by experimental toggles and vault size limit) for vault-wide visibility and quick actions. +- Built-in templates (Colorful, Minimal, Academic, Project) plus full custom templates and standalone custom statuses. +- Works with YAML frontmatter and non-Markdown via a synced JSON store; frontmatter mappings let you write to multiple keys. -![Status dashboard with vault statistics](images/status-dashboard-overview1.png) +## Data model -_Alt: Status dashboard showing current note information, vault statistics with total notes and coverage percentages_ -![Status dashboard with vault statistics](images/status-dashboard-overview2.png) +- **Markdown**: statuses live under the tag prefix (default `obsidian-note-status`). Map templates/statuses to extra YAML keys and optionally also write to the default. +- **Non-Markdown**: stored in `.obsidian/plugins/obsidian-note-status/non-markdown-statuses.json`, kept in sync on rename/delete. +- **Single vs multi**: multiple statuses by default; single-status mode can store as list (`status: [draft]`) or string (`status: draft`) for compatibility. -_Alt: Status distribution chart showing different statuses with colored bars and note counts for each status type_ -![Status dashboard with vault statistics](images/status-dashboard-overview3.png) +## Screenshots (add yours) -_Alt: Quick actions panel with organized sections for views, current note operations, clipboard actions, and tools_ +- Status assignment workflow: ![Status assignment workflow demonstration](images/status-assignment-demo.png) +- File explorer with status icons and hover overview: ![File explorer with status icons](images/file-explorer-status-icons.png) +- Status dashboard: ![Status dashboard with vault statistics](images/status-dashboard-overview1.png) ![Status dashboard with vault statistics](images/status-dashboard-overview2.png) ![Status dashboard with vault statistics](images/status-dashboard-overview3.png) +- Grouped status view: ![Grouped status view with filtering](images/grouped-status-filtering.png) +- Custom statuses editor: ![Custom statuses](images/custom-status-change.png) -## πŸ’» Technology Stack +## Installation -Built with modern web technologies for performance and reliability: +### Community Plugin Store (recommended) -- **TypeScript** - Type-safe development -- **React** - Modern UI framework -- **esbuild** - Fast bundling and development -- **Obsidian API** - Deep vault integration +1. Obsidian β†’ Settings β†’ Community plugins. +2. Disable Safe mode β†’ Browse β†’ search β€œNote Status”. +3. Install and enable. -## πŸ“¦ Installation +### Manual -### Community Plugin Store (Recommended) +1. Download the latest release from [GitHub Releases](https://github.com/devonthesofa/obsidian-note-status/releases). +2. Extract `main.js`, `manifest.json`, and `styles.css` to `.obsidian/plugins/note-status/`. +3. Enable in Community plugins settings. -1. Open Obsidian β†’ Settings β†’ Community plugins -2. Disable Safe mode β†’ Browse β†’ Search "Note Status" -3. Install and Enable +## Example workflows -### Manual Installation - -1. Download latest release from [GitHub Releases](https://github.com/devonthesofa/obsidian-note-status/releases) -2. Extract `main.js`, `manifest.json`, and `styles.css` to `.obsidian/plugins/note-status/` -3. Enable in Community plugins settings - -## πŸš€ How to Use - -### Quick Start - -1. **Assign Status**: - - 1. Click the "No status" in toolbar - - ![Status toolbar](images/no-status-toolbar.png) - - _Alt: Editor toolbar showing "No status" button for status assignment_ - - 2. β†’ Select a status - -2. **View in Explorer**: Status icons appear next to note names - - ![File explorer item](images/file-explorer-item.png) - - _Alt: Single file explorer item showing a note with status icon positioned next to the filename_ - -3. **Browse by Status or open the Dashboard**: Open from left sidebar - - ![Open status view](images/open-view-buttons.png) - - _Alt: Left sidebar showing ribbon buttons for opening grouped status view and status dashboard_ - -4. **Batch Update**: Select multiple files β†’ Right-click β†’ Change status - - ![Multiple status context](images/change-multiple-statuses.png) - - _Alt: Context menu appearing when right-clicking multiple selected files, showing "Change note status" option_ - -### Example Workflows - -**Personal Knowledge Management** +**Personal knowledge** ``` πŸ’‘ idea β†’ πŸ“ draft β†’ ✏️ editing β†’ βœ… completed β†’ πŸ“¦ archived ``` -**Project Management** +**Project delivery** ``` πŸ“‹ backlog β†’ 🚦 ready β†’ πŸ‘¨β€πŸ’» inDevelopment β†’ πŸ§ͺ testing β†’ πŸš€ live ``` -**Academic Research** +**Academic** ``` πŸ” research β†’ πŸ“‘ outline β†’ ✏️ draft β†’ πŸ”¬ review β†’ πŸ“š final ``` -![Grouped status view with filtering](images/grouped-status-filtering.png) +## Data format -_Alt: Grouped status view showing notes organized by status with template filtering and search functionality_ - -### Custom Statuses - -Create your own workflow: - -1. **Settings** β†’ Note Status β†’ Custom Statuses -2. **Add Status** β†’ Configure name, icon, color, description -3. **Reorder** using arrow controls -4. **Use** in your notes - -Example custom status: - -``` -Name: urgent -Icon: πŸ”₯ -Color: #FF0000 -Description: Requires immediate attention -``` - -![Custom statuses](images/custom-status-change.png) - -_Alt: Status selection modal showing custom and template statuses with icons, names, and selection interface_ - -## πŸ“‹ Data Format - -Statuses are stored in YAML frontmatter: +Statuses in YAML: ```yaml --- @@ -153,46 +93,15 @@ obsidian-note-status: --- ``` -Works with: +Works with Dataview, Templater, QuickAdd, and search. Non-Markdown uses the JSON store noted above. -- **Dataview queries** -- **Templater scripts** -- **QuickAdd macros** -- **Global search** +## API / contributing / support -Non-Markdown files (PDF, Canvas, images, etc.) can't host YAML frontmatter. Their statuses live in a lightweight JSON file under `.obsidian/plugins/obsidian-note-status/non-markdown-statuses.json`, and every command/view in the plugin reads from that store transparently. External tools such as Dataview or Templater still only see Markdown/frontmatter data, so keep using Markdown files if you need those integrations. +- Developer docs & API: see the [wiki](https://github.com/devonthesofa/obsidian-note-status/wiki). +- Issues & feature requests: [GitHub Issues](https://github.com/devonthesofa/obsidian-note-status/issues) / [Discussions](https://github.com/devonthesofa/obsidian-note-status/discussions). +- Contributions welcome: fork, follow dev setup in the wiki, open a PR. -## πŸ› οΈ API Reference - -For developers building integrations or contributing: - -πŸ“š **[Developer Documentation](https://github.com/devonthesofa/obsidian-note-status/wiki)** - -Includes: - -- Architecture overview -- Development setup -- API reference -- Contributing guide - -## 🀝 Contributing - -We welcome contributions! - -1. **Check** [GitHub Issues](https://github.com/devonthesofa/obsidian-note-status/issues) for bugs/features -2. **Fork** the repository -3. **Follow** [Development Setup](https://github.com/devonthesofa/obsidian-note-status/wiki/πŸ”§-Development-Setup) -4. **Submit** pull request - -## πŸ› Support - -- **πŸ“– Documentation**: [Complete Wiki](https://github.com/devonthesofa/obsidian-note-status/wiki) -- **🐞 Bug Reports**: [GitHub Issues](https://github.com/devonthesofa/obsidian-note-status/issues) -- **πŸ’‘ Feature Requests**: [GitHub Discussions](https://github.com/devonthesofa/obsidian-note-status/discussions) - -## ❀️ Support Development - -If you find this plugin useful: +## Support the project [![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white)](https://paypal.me/aleixsoler) @@ -200,4 +109,4 @@ If you find this plugin useful: --- -**License**: MIT | **Author**: [Aleix Soler](https://aleixsoler.com) +**License**: MIT Β· **Author**: [Aleix Soler](https://aleixsoler.com) diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..0256a42 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,81 @@ +# Feature Guide + +## Status editing & selection + +- Open the picker from the status bar badge, editor toolbar button, file explorer context menu, or the `Change current note status` command. The same modal handles single files, multi-select batches, and folder runs. +- Browse by template tabs (All, per template, Custom), search, and use full keyboard navigation (arrows/Tab + Enter/Backspace/Escape). Current statuses appear as removable chips; single-status mode keeps only one value. +- Works on Markdown and non-Markdown; resolves every relevant frontmatter key (default tag and any mappings) before writing. +- Clipboard helpers: `Copy current note status` and `Paste status to current note` mirror what you see in the picker. + +## Bulk changes & context menus + +- Right-click one or many files β†’ `Change note status` to batch-apply statuses. +- Right-click a folder β†’ `Apply note status to folder`; enable recursion in settings if you want nested folders included. +- The modal shows how many files will change before you confirm. + +## Status surfaces + +**Status bar** + +- Clickable badges; hide entirely or auto-hide when empty. Keep a β€œNo status” badge with custom text/icon/color if you prefer. +- Template names can be hidden, auto-shown only on conflicts, or always shown. +- Badge visuals: accent stripe, solid fill, or dot; content can be icon+text, icon only, text only, or empty accent. + +**Editor toolbar** + +- Optional badge in the editor header. Place it left, right-before actions, or right, and choose whether it shows for all editors or only the active one. +- Uses the same unknown-status icon/color you configure elsewhere. + +**File explorer** + +- Status icons appear next to file names. Choose placement (filename left, filename right, absolute right), add a frame or keep it frameless, and pick whether icons use status colors or the theme. +- Extra cues per option: color filename, tint the row, add a left border, append a dot, underline the filename. Unknowns can be hidden. +- Hover an icon to open the Status Overview popup listing every frontmatter key with statuses, highlighting the default tag. + +**Status overview popup** + +- Lightweight popup used by explorer/status icons; lists statuses per key and labels the default tag. Respects the enable/disable toggle. + +## Dashboards and views (experimental) + +**Status Dashboard** + +- Ribbon icon/command (gated by Experimental Features + Dashboard toggles and the vault size limit). Shows the active note (path, modified time, statuses per tag), vault totals, and a status distribution chart. Clicking a bar runs a search for that status. +- Quick Actions panel: open grouped view, find unassigned notes, change/cycle/clear status, copy/paste status, search by status, toggle multi-status mode, and run Quick Status Commands. + +**Grouped Status View** + +- Ribbon icon/command (same gating and vault limit). Groups notes by frontmatter key, then by status (template badges shown when relevant). +- Filters: quick search, filter by note name substring, and filter by template id. Groups are collapsible and support β€œload more” for large sets. Clicking a note opens it in a new leaf. + +## Templates & custom statuses + +- Built-in templates: Colorful (idea β†’ draft β†’ inProgress β†’ editing β†’ pending β†’ onHold β†’ needsUpdate β†’ completed β†’ archived), Minimal (todo β†’ inProgress β†’ review β†’ done), Academic (research β†’ outline β†’ draft β†’ review β†’ revision β†’ final β†’ published), Project (planning β†’ backlog β†’ ready β†’ inDevelopment β†’ testing β†’ review β†’ approved β†’ live). +- Build your own templates (name, description, ordered statuses with emoji/Lucide + color). New templates auto-enable; you can edit/delete or reset built-ins anytime. +- Custom statuses live outside templates; create, reorder, delete them, or run in β€œCustom only” mode to hide template statuses entirely. +- Unknown status handling is configurable (icon/Lucide icon, color, and whether unknowns show in explorer/status bar). + +## Commands & keyboard shortcuts + +- Change current note status (opens picker). +- Cycle through statuses (single-status mode only). +- Clear status. +- Copy/Paste status (clipboard). +- Toggle multiple statuses mode. +- Search notes by current status (opens Global Search with queries for every configured frontmatter key). +- Open grouped status view (requires toggle). +- Quick Status Commands: select statuses in settings to auto-register `Set status to ...` commands you can bind to hotkeys. + +## Data & compatibility + +- Frontmatter key prefix defaults to `obsidian-note-status`; change it per vault. Map templates/statuses to extra YAML keys, and optionally also write mapped tags to the default key. +- Single-status mode can store the value as a list (`status: [in-progress]`) or plain string (`status: in-progress`) for compatibility with plugins that expect strings. +- Non-Markdown files store statuses in `.obsidian/plugins/obsidian-note-status/non-markdown-statuses.json`. Rename/delete events stay in sync automatically. +- Strict status validation removes unknown statuses when you edit a file’s statusesβ€”use with caution if you expect ad-hoc values. + +## Screenshot ideas (add later) + +- Status picker modal with template tabs and search. +- File explorer with icons/row coloring and the hover overview popup. +- Status bar badge styles (accent/filled/dot) with and without template names. +- Dashboard and Grouped Status View with filters. diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 0000000..cfa119d --- /dev/null +++ b/docs/settings.md @@ -0,0 +1,126 @@ +## Settings Reference + +All settings are grouped the same way you see them in the plugin. Each section lists what it controls and when to tweak it. + +--- + +## Templates & Statuses + +### Status templates + +- Enable/disable built-in templates or build your own (name, description, ordered statuses with emoji/Lucide + color). +- Auto-enables new templates; you can reset built-ins anytime. +- Good for shared workflows: research pipelines, task boards, project phases. + +### Use only custom statuses + +- Hides all template statuses so only your standalone statuses appear. +- Handy for very small personal vocabularies (e.g., `idea`, `draft`, `done`). + +### Custom statuses + +- Create standalone statuses, reorder, delete. +- Useful for special-purpose tags like `needsReviewByJohn` or `instagramPostReady`. + +--- + +## Quick Actions + +### Quick Status Commands + +- Registers `Set status to ...` commands you can bind to hotkeys. +- Best when you want fast keyboard-driven changes; shines in single-status mode. + +--- + +## Status Bar + +### Visibility and behavior + +- Show status icon in status bar; optionally hide when no status is set. +- Show status overview popup on hover for a quick per-key breakdown. +- Show template names next to status: never / auto on conflicts (default) / always. + +### Badge visuals + +- Badge style: accent stripe / filled / dot. +- Badge content: icon + text / icon only / text only / empty accent. + +### No-status display + +- Custom text for empty state. +- Show icon when no status. +- Show text when no status. + +--- + +## Editor Toolbar + +### Toolbar button + +- Show/hide the status button in the editor header. +- Position: left / right-before-actions / right. +- Show for: all notes / active note only. + +--- + +## File Explorer + +### Icons and placement + +- Show status icons in file explorer. +- Icon position: filename left / filename right / absolute right. +- Hide icon when status is unknown. + +### Visual treatments (per-option) + +- Color filename text. +- Color entire row. +- Left border. +- Status dot. +- Underline filename. + +### Icon styling + +- Status icon frame: never / always. +- Status icon color: use status colors / inherit theme colors. + +--- + +## Unknown / No-Status Appearance + +### Fallback visuals + +- Icon for unknown status (emoji or Lucide). +- Color for unknown status (used across status bar/explorer fallbacks). + +--- + +## Behavior & Storage + +### Status model + +- Enable multiple statuses (default) or force single-status mode. +- Single-status format when multiple is off: list (`status: [draft]`) or string (`status: draft`). + +### Write targets + +- Apply status recursively to subfolders (folder context menu option). +- Status tag prefix (frontmatter key, default `obsidian-note-status`). +- Frontmatter mappings: map templates or statuses to additional YAML keys; optional β€œwrite mapped tags to default” to keep both in sync. +- Strict status validation: removes unknown statuses on edit (use in controlled vocabularies). + +### Safeguards + +- Vault size limit: disables dashboard and grouped view beyond the threshold. + +--- + +## Experimental Features + +### Toggles + +- Enable experimental features (master gate). +- Enable status dashboard. +- Enable grouped status view. +- Dashboard/grouped view respect the vault size limit.