mirror of
https://github.com/devonthesofa/obsidian-note-status.git
synced 2026-07-22 05:45:04 +00:00
chore: improved readme and docs
This commit is contained in:
Aleix Soler
parent
063a4aac01
commit
87d865de3b
3 changed files with 259 additions and 143 deletions
195
README.md
195
README.md
|
|
@ -1,149 +1,89 @@
|
|||
# Note Status for Obsidian
|
||||
|
||||
[](https://paypal.me/aleixsoler)
|
||||
[](https://github.com/devonthesofa/obsidian-note-status/releases)
|
||||
[](https://github.com/devonthesofa/obsidian-note-status/actions)
|
||||
[](https://obsidian.md/plugins?id=note-status)
|
||||
[](https://github.com/devonthesofa/obsidian-note-status/blob/master/LICENSE)
|
||||
[](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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
## Data model
|
||||
|
||||
_Alt: Status dashboard showing current note information, vault statistics with total notes and coverage percentages_
|
||||
|
||||
- **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_
|
||||
|
||||
## Screenshots (add yours)
|
||||
|
||||
_Alt: Quick actions panel with organized sections for views, current note operations, clipboard actions, and tools_
|
||||
- Status assignment workflow: 
|
||||
- File explorer with status icons and hover overview: 
|
||||
- Status dashboard:   
|
||||
- Grouped status view: 
|
||||
- Custom statuses editor: 
|
||||
|
||||
## 💻 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
|
||||
|
||||
|
||||
|
||||
_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
|
||||
|
||||
|
||||
|
||||
_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
|
||||
|
||||
|
||||
|
||||
_Alt: Left sidebar showing ribbon buttons for opening grouped status view and status dashboard_
|
||||
|
||||
4. **Batch Update**: Select multiple files → Right-click → Change status
|
||||
|
||||
|
||||
|
||||
_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
|
||||
```
|
||||
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
|
||||
|
||||
_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
|
||||
|
||||
[](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)
|
||||
|
|
|
|||
81
docs/features.md
Normal file
81
docs/features.md
Normal file
|
|
@ -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.
|
||||
126
docs/settings.md
Normal file
126
docs/settings.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue