matt/mdtask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial

Browse Source
This commit is contained in:
Matt W
2026-01-05 21:51:59 -05:00
commit 16f0e10198
8 changed files with 1262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
requirements.md Normal file
View File

@ -0,0 +1,64 @@
# mdtask Requirements
mdtask is a single file PHP and Vue.js web application with no external dependencies aside from libraries accessed via CDN.
The script lives in ./scripts/mdtask.php and operates on Markdown files in ../Daily/Inbox.md (referred to as the Inbox) and project-specific markdown files found in ../Tasks/[ProjectName].md (referred to as Project files).
This is a mobile web app - it is laid out for use on a phone screen.
## Task file format
Task markdown files are formatted as follows:
- A "# Inbox" or "# ProjectName" line is at the top of the file.
- Each task is one or more lines separated by a blank line. The first line of a task is the task name. Subsequent lines, if there are any, are task notes. An empty line (with or without white space) or EOF denotes the end of a task.
- An optional line containing "-----" visually separates tasks intended for today vs later. In the UI, this is shown as a thicker line separating the tasks above and below it. Any subsequent instances of "-----" after the first are ignored.
- Each task may begin with a single special character followed by a space that indicates status. An "X " prefix indicates the task is completed. "~ " indicates the task is in progress. "C " indicates the task was cancelled. If none of these are found, the task is active.
## App initialization and default view
When the app starts, it reads ../Daily/Inbox.md and displays the tasks in it. Tasks are listed with the task name. Beneath it, the first line of any notes attached to the task is displayed in smaller text. Tasks are separated by a visual line.
The user can press and drag up or down on a task to move it up or down in the list. When a task is reordered, the underlying task markdown file is saved with the change. The "-----" separator cannot itself be dragged, but tasks can be dragged above or below it.
Clicking a task selects or deselects it, and multiple tasks can be selected.
The following global actions are available as buttons at the bottom of the screen:
- Add: creates and edits a new task. Tasks are added to the top of the file.
- Open: displays a list of markdown files in ../Tasks. Selecting one makes that file the current task file. If Inbox is not the current task file, Inbox appears at the top of this list.
- Tidy: Displays a list of Markdown files found in ../Daily that match the pattern "YYYY-MM-DD DDD.md". When one is selected, certain tasks are moved from the current file to a "#### Tasks" section at the bottom of the selected Daily file. See Tidying Up below for more details.
The following task specific options replace the tray of global options at the bottom of the screen.
- Edit - Opens the task and details in a full screen plain text editing screen with Save and Cancel buttons. This option is grayed out if multiple tasks are selected. All other global commands can act on multiple selected tasks.
- Delete - Removes the task from the list and updates the underlying markdown file.
- Complete - Sets the task status to completed.
- Start - Sets the task status to in progress.
- Cancel - Sets the task status to cancelled.
- Move - Displays a list of the markdown files found in ../Tasks. Selected tasks are moved to the selected markdown tasks file, inserted at the top.
## Avoid over-writing external changes
Task files may be updated by external processes. Before saving a file, the modification date should be checked against the modification date when the file was last read. The app notifies the user if a file modification date has changed since load time to avoid overwriting external changes. When this happens, any changes are discarded and the view is reloaded to show the updated file.
## Tidying up
When the user clicks "Tidy" and selects a Daily markdown page, the following happens:
- All tasks that are Completed (X prefix) or Cancelled (C prefix) are removed from the current task file and appended to the Tasks list in the selected Daily markdown file.
- All tasks that are in progress (~ prefix) are copied to the Daily file rather than moved.
- The task list in the Daily markdown file begins with "#### Tasks". If not found, that heading should be added to the end of the file. Tasks are added to the bottom after that heading.
- If a task is moved that is already in the Daily file, but with a different status indicator, the status of the existing task should be updated with the current status indicator rather than adding it again.
- When checking if a task already exists in the Daily file, use the first line, minus any status indicator. If there are task notes in the Daily file, they should be replaced with the notes from the tasks file.
- The separator line is ignored when tidying and is not copied to the Daily file.
- Active tasks with no prefix are unaffected by the tidying process.
## UI Notes
The separator line is just a bold horizontal line.
Task status should be indicated visually as follows:
- Active: White background
- In progress: Pale yellow background
- Completed: Pale red background
- Cancelled: Pale gray background
Use light blue as an accent color where appropriate.