148 lines
7.1 KiB
Markdown
148 lines
7.1 KiB
Markdown
# Obsidian GUI Tasks — Requirements
|
|
|
|
## Overview
|
|
|
|
An Obsidian plugin that provides a more traditional task management GUI for designated markdown files within a vault. Task files are rendered in a custom view rather than the default markdown editor, and all changes are persisted back to the underlying markdown. The plugin supports both desktop and mobile Obsidian.
|
|
|
|
---
|
|
|
|
## 1. Task Files
|
|
|
|
### 1.1 Detection
|
|
|
|
- A **task file** is any markdown file whose vault path matches a user-configured regex pattern.
|
|
- Default pattern: all `.md` files inside the top-level `Tasks/` folder (e.g., `^Tasks\/.*\.md$`).
|
|
- When a task file is opened in Obsidian, the plugin automatically renders it in the custom task view instead of the default markdown editor.
|
|
|
|
### 1.2 Structure
|
|
|
|
- Task files consist of markdown checklist items (`- [ ] …` / `- [x] …`) and optional header content.
|
|
- Any non-checklist lines **before the first checklist item** are treated as **header text**: they are not parsed as tasks, not shown in the UI, and are preserved verbatim when the file is written back.
|
|
- Any non-checklist lines immediately following a checklist item are treated as **notes** for that item.
|
|
- Notes are separated from their parent task in the file by a blank line.
|
|
- The ordering of checklist items in the file reflects the display order in the UI.
|
|
- Completed items remain in the file until the user marks them as done, at which point they are moved to the current Daily Note (see §5).
|
|
|
|
### 1.3 Inbox File
|
|
|
|
- One task file is designated as the **Inbox** — the default destination when opened via the command palette.
|
|
- The Inbox file path is configured in plugin settings.
|
|
- Default: `Tasks/Inbox.md`.
|
|
|
|
---
|
|
|
|
## 2. Task View UI
|
|
|
|
### 2.1 Source Mode
|
|
|
|
- The task view header contains an **"Edit source"** action button (code icon).
|
|
- Clicking it switches the current leaf to Obsidian's standard markdown editor in source mode, bypassing the normal intercept that redirects task files to the task view.
|
|
- To return to task view, use the tab's **"Open as… > YAOTP Task View"** context menu option, or close and reopen the file.
|
|
|
|
### 2.2 Layout
|
|
|
|
- The custom view replaces the standard markdown editor for task files.
|
|
- Each checklist item is displayed as a task row containing:
|
|
- A clickable **checkbox** on the left.
|
|
- The **task text**, which wraps to multiple lines as needed.
|
|
- Notes are **not** shown inline; they are accessible via the task editor (§3).
|
|
- The view does not render raw markdown syntax.
|
|
|
|
### 2.3 Reordering
|
|
|
|
- Task rows can be reordered by dragging and dropping within the view.
|
|
- On mobile, reordering is triggered by a long-press on the drag handle, followed by dragging.
|
|
- Reordering the UI immediately reorders the corresponding checklist items in the markdown file.
|
|
- Notes travel with their parent task during reordering.
|
|
|
|
### 2.4 File Switcher
|
|
|
|
- A header bar or sidebar control lets the user quickly switch between:
|
|
- The Inbox file.
|
|
- Any other task file in the vault (matched by the configured regex).
|
|
- The switcher also provides a **"New task file"** action that:
|
|
- Prompts for a file name.
|
|
- Creates the file in the configured tasks folder (or a location derived from the regex).
|
|
- Opens the new file in the task view.
|
|
|
|
### 2.5 Adding a Task
|
|
|
|
- The first row of every task list is a persistent **add-task row** that looks identical to a regular task row.
|
|
- The add-task row contains:
|
|
- A **drag handle** (visually present but disabled — not interactive).
|
|
- A **checkbox** (visually present but disabled — not interactive).
|
|
- A single-line **text input** with placeholder text `Enter new task…`.
|
|
- Typing into the input and pressing **Enter** creates a new task with that text, no notes, and inserts it at the top of the task list (immediately below the add-task row).
|
|
- The new task is immediately persisted to the markdown file.
|
|
- The add-task row is always visible, even when the list is empty.
|
|
|
|
### 2.6 Completing a Task
|
|
|
|
- Clicking a task's checkbox marks it as complete.
|
|
- The task (and its notes) is removed from the current task file.
|
|
- The task is appended to the **`#### Tasks`** section at the bottom of the current Daily Note (see §5).
|
|
- If the `#### Tasks` section does not exist in the Daily Note, it is created.
|
|
|
|
---
|
|
|
|
## 3. Task Editor
|
|
|
|
- Clicking the **text** of a task opens an editor modal.
|
|
- The editor provides:
|
|
- A single **multiline text area** with the task title on the first line, a blank line, then the notes. The blank line separator is always present when notes exist; if the user removes it or writes notes without it, a blank line is inserted automatically on save.
|
|
- A **file selector** (dropdown or fuzzy-search picker) to move the task to a different task file. Selecting a different file removes the task from the current file and appends it to the bottom of the selected file.
|
|
- A **Delete** button that, after a confirmation prompt, permanently removes the task from the file.
|
|
- Changes are saved back to the markdown file on confirm/close.
|
|
- The **"+ New list"** button opens a modal prompting for a file name and creates the file in the configured tasks folder.
|
|
|
|
---
|
|
|
|
## 4. Markdown Persistence
|
|
|
|
- The markdown file is the source of truth.
|
|
- All UI actions (reorder, complete, edit) must produce a corresponding update to the file via the Obsidian Vault API.
|
|
- If a task file is modified externally (e.g., edited in another pane or by a sync tool), the task view refreshes to reflect the new state.
|
|
- Checklist format written back to disk:
|
|
```
|
|
- [ ] Task title
|
|
|
|
notes line 1
|
|
notes line 2
|
|
|
|
- [ ] Next task
|
|
```
|
|
Notes are separated from the checklist item above by one blank line and followed by one blank line before the next checklist item. Completed items use `- [x] …`.
|
|
|
|
---
|
|
|
|
## 5. Daily Note Integration
|
|
|
|
- The plugin relies on Obsidian's Daily Notes core plugin (or compatible community plugin) to locate the current daily note.
|
|
- When a task is completed, the plugin:
|
|
1. Finds or creates today's daily note.
|
|
2. Looks for a `#### Tasks` heading at the bottom of the file.
|
|
3. Appends the completed task and its notes under that heading, using the same format as the task file (task line, blank line, notes, blank line).
|
|
4. If the task has no notes, only the task line is appended.
|
|
- If the Daily Notes plugin is not enabled, the plugin displays a warning and does not move the task.
|
|
|
|
---
|
|
|
|
## 6. Plugin Settings
|
|
|
|
| Setting | Description | Default |
|
|
|---|---|---|
|
|
| **Inbox file path** | Vault-relative path to the Inbox task file | `Tasks/Inbox.md` |
|
|
| **Task file regex** | Regex matched against vault-relative file paths to identify task files | `^Tasks\/.*\.md$` |
|
|
| **Task file folder** | Vault-relative folder where new task lists are created via the "New list" button; leave empty for the vault root | `Tasks` |
|
|
| **Daily note date format** | Date format string used to locate the daily note (should match Daily Notes plugin setting) | `YYYY-MM-DD` |
|
|
| **Daily note folder** | Folder where daily notes are stored (should match Daily Notes plugin setting) | *(empty — vault root)* |
|
|
|
|
---
|
|
|
|
## 7. Out of Scope (v1)
|
|
|
|
- Due dates, priorities, or labels on tasks.
|
|
- Subtasks / nested checklists.
|
|
- Task search or filtering.
|
|
- Sync with external task services (Todoist, Things, etc.).
|