VSCode Extension

Intelligent markdown task management directly in Visual Studio Code, powered by md2do.

Current version: v0.2.1

Install from Marketplace • Report Issues

What is it?

The md2do VSCode extension brings powerful task management features to your markdown editor:

Task Explorer - Browse all tasks in a hierarchical tree view
Smart Diagnostics - Validation warnings in Problems panel
Hover Tooltips - Rich metadata display on hover
Smart Completion - Auto-complete dates, assignees, tags, priorities
Quick Actions - Toggle, copy, edit, delete tasks with one click

Installation

VSCode Marketplace (Recommended)

Open VSCode
Go to Extensions sidebar (Cmd+Shift+X / Ctrl+Shift+X)
Search for "md2do"
Click Install

Or install directly from the marketplace.

Command Line Install

bash

code --install-extension md2do.md2do-vscode

Manual Install (Alternative)

If you prefer to install manually:

Download the latest .vsix file from GitHub Releases
Open VSCode
Go to Extensions sidebar (Cmd+Shift+X / Ctrl+Shift+X)
Click the ... menu (top-right of Extensions sidebar)
Select "Install from VSIX..."
Choose the downloaded md2do-vscode-X.X.X.vsix file
Reload VSCode when prompted

Updates

Extensions installed from the marketplace auto-update automatically. You can also manually check for updates in the Extensions sidebar.

Uninstall

Go to Extensions sidebar
Find "md2do"
Click gear icon → Uninstall

Features

Browse all tasks across your workspace with powerful organization options:

Grouping Modes:

📁 By File - Default view, grouped by file location
👤 By Assignee - See who has what tasks
📅 By Due Date - Overdue, today, this week, later, no date
⚡ By Priority - Urgent, high, normal, low
🏷️ By Tag - Organized by task tags
📋 Flat List - All tasks in a sorted list without grouping

Filters:

☑️ Show Incomplete Only - Hide completed tasks
⚠️ Show Overdue Only - Focus on overdue tasks
👥 Show Assigned Only - Hide unassigned tasks

Sorting Options:

📅 Sort by Due Date
⚡ Sort by Priority
🔤 Sort Alphabetically
📍 Sort by Line Number

Features:

Shows completion status and counts for each group
Rich tooltips with full task metadata
Click any task to jump to its location
Right-click for quick actions (toggle, edit, delete)
Toolbar buttons for easy access to grouping, filtering, and sorting

Location: Appears in the Explorer sidebar panel

Keyboard Shortcut: Cmd+Shift+E / Ctrl+Shift+E to focus Explorer, then scroll to "md2do Tasks"

⚠️ Smart Diagnostics

md2do validation warnings appear directly in VSCode's Problems panel:

Malformed checkboxes - Detects [-], [X], [*] instead of [ ] or [x]
Formatting issues - Missing spaces after checkbox or before metadata
Missing metadata - Optional warnings for tasks without due dates or completion dates
Duplicate Todoist IDs - Prevents sync conflicts
File read errors - Reports files that couldn't be scanned

Location: View → Problems (Cmd+Shift+M / Ctrl+Shift+M)

Configuration: Respects your .md2do.json warning rules

⌨️ Quick Task Actions

Toggle Completion

Press Cmd+K Enter (Mac) or Ctrl+K Enter (Win/Linux) to toggle task completion:

[ ] → [x] - Marks complete and adds [completed: 2026-01-27]
[x] → [ ] - Marks incomplete and removes completion date

Works on any line with a checkbox when cursor is positioned on that line.

Right-click any task in the Task Explorer:

Toggle Completion - Check/uncheck task (inline button)
Edit Task - Jump to task location in file
Copy as Markdown - Copy task text with all metadata to clipboard
Delete Task - Remove task from file (with confirmation)

💡 Hover Tooltips

Hover over any task line to see rich metadata:

✅ Status - Completed or incomplete
📅 Due Date - Shows date and overdue warning if applicable
👤 Assignee - Who's responsible
⚡ Priority - Urgent, high, normal, or low
🏷️ Tags - All tags on the task
📄 Location - File path and line number

Usage: Simply hover your mouse over a task line

⚡ Smart Completion

Auto-complete for task metadata as you type:

Date Completion

Trigger: Type [due: or [completed: and press Space

Suggestions:

today → Today's date
tomorrow → Tomorrow's date
monday, tuesday, etc. → Next occurrence of that weekday
next week → 7 days from today
next month → 30 days from today

Example:

markdown

- [ ] Review PR [due: t|]

Type t and select today → - [ ] Review PR [due: 2026-01-27]

Assignee Completion

Trigger: Type @ followed by a character

Suggestions:

Configured assignees from md2do.defaultAssignees setting
Learned assignees from existing tasks in workspace
Sorted alphabetically

Example:

markdown

- [ ] Fix bug @a|

Type @a and select alice → - [ ] Fix bug @alice

Tag Completion

Trigger: Type # followed by a character

Suggestions:

All tags found in workspace tasks
Sorted by frequency (most common first)

Example:

markdown

- [ ] Update docs #b|

Type #b and select backend → - [ ] Update docs #backend

Priority Completion

Trigger: Type ! after a space

Suggestions:

! → Normal priority
!! → High priority
!!! → Urgent priority

Example:

markdown

- [ ] Critical bug !|

Type ! and select !!! → - [ ] Critical bug !!!

🔍 CodeLens Inline Actions

Actionable links appear above each task for quick access:

✅ Mark Complete / ⬜ Mark Incomplete - Toggle task completion with one click
📅 Due Date Info - Shows due date with countdown or overdue warnings
🔴/🟠/🟡 Priority - Visual priority indicators
🔄 Synced - Todoist sync status
🗑️ Delete - Quick delete action

Usage: CodeLens links appear directly above each task line in your markdown files

Example:

markdown

Due in 3 days • Priority: High • Delete

- [ ] Review PR [due: 2026-01-30] @alice !! #review

Click any CodeLens link to perform the action instantly without opening menus.

📊 Interactive Dashboard

Visual overview of all incomplete tasks with smart grouping:

Task Statistics - Total, complete, incomplete, overdue, and due today counts
By Assignee - See who has what tasks assigned
By Due Date - Overdue, today, this week, later, no date
By Priority - Urgent, high, normal, low
Click to Drill Down - Click any group to see detailed task list with sorting options
Navigate to Tasks - Click tasks to jump to file location
Auto-refresh - Updates automatically when you edit markdown files

Open with: Cmd+Shift+P → md2do: Open Dashboard

Features:

Clean, visual interface for task management
Interactive drill-down from groups to individual tasks
Sort tasks by due date, priority, alphabetical, or line number
One-click navigation to task locations
Real-time updates as you edit files

📊 Status Bar Integration

See task overview at a glance in the status bar:

Total task count - Shows number of tasks in workspace
Overdue warnings - Highlights overdue task count in red
Click to refresh - Manually rescan all tasks

Location: Bottom-right of VSCode window

Task Format

md2do supports rich metadata in your markdown tasks:

markdown

- [ ] Basic task
- [ ] Task with due date [due: 2026-02-01]
- [ ] Urgent task [due: tomorrow] !!!
- [ ] Assigned task @alice #bug
- [x] Completed task [completed: 2026-01-27]
- [ ] Full metadata task [due: 2026-02-15] @bob #feature #urgent !! [todoist: 123456]

See Task Format for complete syntax reference.

Keyboard Shortcuts

Command	Shortcut (Mac)	Shortcut (Win/Linux)	Description
Toggle Task Completion	`Cmd+K Enter`	`Ctrl+K Enter`	Toggle `[ ]` ↔ `[x]`
Open Explorer	`Cmd+Shift+E`	`Ctrl+Shift+E`	View Task Explorer
Open Problems	`Cmd+Shift+M`	`Ctrl+Shift+M`	View Diagnostics
Command Palette	`Cmd+Shift+P`	`Ctrl+Shift+P`	Access md2do commands

Commands

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and search for:

Dashboard:

md2do: Open Dashboard - Open interactive task dashboard

Task Actions:

md2do: Toggle Task Completion - Toggle task at cursor
md2do: Refresh Tasks - Refresh all tasks and diagnostics

Grouping:

md2do: Group by File - Group tasks by file
md2do: Group by Assignee - Group tasks by assignee
md2do: Group by Due Date - Group tasks by due date
md2do: Group by Priority - Group tasks by priority
md2do: Group by Tag - Group tasks by tag
md2do: Flat List (No Grouping) - Show all tasks in a flat list

Filters:

md2do: Toggle: Show Incomplete Only - Show/hide completed tasks
md2do: Toggle: Show Overdue Only - Show/hide non-overdue tasks
md2do: Toggle: Show Assigned Only - Show/hide unassigned tasks

Sorting:

md2do: Sort by Due Date - Sort tasks by due date
md2do: Sort by Priority - Sort tasks by priority
md2do: Sort Alphabetically - Sort tasks alphabetically
md2do: Sort by Line Number - Sort tasks by line number

Tip: Use the toolbar buttons in the Task Explorer for quick access to grouping, filtering, and sorting options!

Extension Settings

Configure md2do through VSCode settings (Cmd+, / Ctrl+,):

json

{
  // Enable/disable automatic workspace scanning
  "md2do.autoScan": true,

  // Show validation warnings in Problems panel
  "md2do.warnings.enabled": true,

  // Default assignees for auto-completion
  "md2do.defaultAssignees": ["@alice", "@bob", "@charlie"]
}

Settings Reference

`md2do.autoScan`

Type: boolean
Default: true
Description: Automatically scan workspace for tasks on startup and file changes

`md2do.warnings.enabled`

Type: boolean
Default: true
Description: Show md2do validation warnings in Problems panel

`md2do.defaultAssignees`

Type: string[]
Default: []
Description: List of default assignees for auto-completion (e.g., ["@alice", "@bob"])

Configuration File

Create a .md2do.json file in your workspace root to customize behavior:

json

{
  "markdown": {
    "pattern": "**/*.md",
    "exclude": ["node_modules/**", ".git/**", "dist/**"]
  },
  "warnings": {
    "enabled": true,
    "rules": {
      "unsupported-bullet": "warn",
      "malformed-checkbox": "warn",
      "missing-space-after": "warn",
      "missing-space-before": "warn",
      "relative-date-no-context": "warn",
      "missing-due-date": "off",
      "missing-completed-date": "off",
      "duplicate-todoist-id": "error",
      "file-read-error": "error"
    }
  }
}

See Configuration Guide for full options.

Common Configurations

Strict Validation

Require due dates and completion dates:

json

{
  "warnings": {
    "rules": {
      "missing-due-date": "warn",
      "missing-completed-date": "warn"
    }
  }
}

Minimal Warnings

Only show critical errors:

json

{
  "warnings": {
    "rules": {
      "unsupported-bullet": "off",
      "missing-space-after": "off",
      "missing-space-before": "off",
      "duplicate-todoist-id": "error",
      "file-read-error": "error"
    }
  }
}

Custom File Patterns

Scan only specific directories:

json

{
  "markdown": {
    "pattern": "{docs,notes,tasks}/**/*.md",
    "exclude": ["archive/**"]
  }
}

Example Workflows

Daily Task Review

Open VSCode in your workspace
View Task Explorer in sidebar
See all tasks grouped by file
Click overdue tasks to jump to location
Toggle completion with Cmd+K Enter

Creating New Tasks

Open any markdown file
Type - [ ] to start a task
Add description
Type [due: and press Space
Select date from auto-complete
Type @ and select assignee
Type # and select tags
Add priority with !, !!, or !!!

Fixing Validation Issues

Open Problems panel (Cmd+Shift+M)
See all validation warnings
Click warning to jump to location
Fix the issue (e.g., change [-] to [ ])
Warning disappears automatically

Team Task Management

Configure default assignees in settings
Create tasks with assignee auto-completion
Use tags for categorization (#bug, #feature, etc.)
Filter tasks in CLI: md2do list --assignee alice
Sync selected tasks to Todoist

Combining with CLI

The VSCode extension works seamlessly with the md2do CLI:

bash

# List all tasks in VSCode workspace
md2do list

# Filter by assignee (from VSCode auto-completion)
md2do list --assignee @alice

# Show statistics
md2do stats --group-by priority

# Sync to Todoist
md2do todoist sync

See CLI Reference for full command documentation.

Troubleshooting

Tasks not appearing in Explorer

Problem: Task Explorer is empty but you have tasks in markdown files

Solutions:

Check file patterns in .md2do.json - ensure your markdown files match the pattern
Refresh tasks manually: Command Palette → "md2do: Refresh Tasks"
Check VSCode settings: ensure md2do.autoScan is true
Verify task format: must be - [ ] or - [x] (GitHub-style checkboxes)

Diagnostics not showing

Problem: No warnings appear in Problems panel

Solutions:

Check VSCode setting: md2do.warnings.enabled should be true
Check .md2do.json warning rules: ensure rules aren't all set to "off"
Verify file format: warnings only appear for detected issues
Open Problems panel: Cmd+Shift+M / Ctrl+Shift+M

Auto-completion not working

Problem: Date/assignee/tag completion doesn't trigger

Solutions:

Ensure you're on a task line starting with - [ ] or - [x]
For dates: type [due: or [completed: followed by Space
For assignees: type @ followed by a character
For tags: type # followed by a character
For priorities: type ! after a space character

Keyboard shortcut conflicts

Problem: Cmd+K Enter doesn't toggle task completion

Solutions:

Check for keyboard shortcut conflicts: VSCode → Preferences → Keyboard Shortcuts
Search for "md2do.toggleComplete"
Reassign to a different shortcut if needed
Alternative: Use Command Palette → "md2do: Toggle Task Completion"

Performance with large workspaces

Problem: Extension is slow with thousands of markdown files

Solutions:

Exclude large directories in .md2do.json:

json

{
  "markdown": {
    "exclude": ["node_modules/**", "vendor/**", "archive/**"]
  }
}

Use specific file patterns instead of **/*.md:

json

{
  "markdown": {
    "pattern": "tasks/**/*.md"
  }
}

Disable auto-scan and refresh manually: set md2do.autoScan to false

Roadmap

Phase 1 (v0.1.0) ✅ Complete

✅ Task Explorer sidebar
✅ Diagnostics integration
✅ Toggle completion command
✅ Hover tooltips
✅ Context menu actions
✅ Smart auto-completion

Phase 2 (v0.2.0) ✅ Complete

✅ CodeLens inline actions (toggle, due date info, priority, sync status, delete)
✅ Advanced Task Explorer with filtering and sorting
✅ Grouping modes (file, assignee, due date, priority, tag, flat)
✅ Filter toggles (incomplete only, overdue only, assigned only)
✅ Sort options (due date, priority, alphabetical, line number)

Phase 3 (v0.2.0+) 🚧 In Progress

✅ Dashboard webview with task visualization and statistics
✅ Interactive drill-down with grouping and sorting
🔄 Todoist bidirectional sync from within VSCode (planned)
🔄 Bulk operations (mark multiple tasks complete) (planned)
🔄 Task dependencies visualization (planned)
🔄 Task time tracking integration (planned)

See Roadmap for the full project roadmap.

@md2do/cli - Command-line interface
@md2do/core - Core task parsing and scanning
@md2do/mcp - Model Context Protocol server for AI integration

Contributing

Found a bug or have a feature request? Open an issue.

Development Setup

Clone the repository:

bash

git clone https://github.com/TeamNickHart/md2do.git
cd md2do

Install dependencies:
bash
```
pnpm install
```
Build the extension:
bash
```
pnpm --filter md2do-vscode build
```
Open in VSCode:
bash
```
code packages/vscode
```
Press F5 to launch Extension Development Host
Test your changes in the new VSCode window

See Contributing Guide for full development workflow.

Privacy & Security

Everything runs locally:

No data sent to external servers
No internet connection required
Tasks never leave your machine
Extension only reads/writes markdown files you explicitly open

Your markdown files remain private and secure.

Requirements

Visual Studio Code 1.85.0 or higher
Markdown files with task checkboxes (GitHub-flavored Markdown format)

Resources

GitHub Repository - Source code and issues
GitHub Releases - Download .vsix files
Task Format Guide - Learn the task syntax
Configuration Guide - Customize behavior
Examples - More usage patterns

Next Steps

Getting Started - Set up md2do CLI
Task Format - Learn the task syntax
Configuration - Customize your setup
MCP Integration - Connect to AI assistants
Todoist Integration - Sync with Todoist

VSCode Extension ​

What is it? ​

Installation ​

VSCode Marketplace (Recommended) ​

Command Line Install ​

Manual Install (Alternative) ​

Updates ​

Uninstall ​

Features ​

📋 Task Explorer Sidebar ​

⚠️ Smart Diagnostics ​

⌨️ Quick Task Actions ​

Toggle Completion ​

Tree View Context Menu ​

💡 Hover Tooltips ​

⚡ Smart Completion ​

Date Completion ​

Assignee Completion ​

Tag Completion ​

Priority Completion ​

🔍 CodeLens Inline Actions ​

📊 Interactive Dashboard ​

📊 Status Bar Integration ​

Task Format ​

Keyboard Shortcuts ​

Commands ​

Extension Settings ​

Settings Reference ​

md2do.autoScan ​

md2do.warnings.enabled ​

md2do.defaultAssignees ​

Configuration File ​

Common Configurations ​

Strict Validation ​

Minimal Warnings ​

Custom File Patterns ​

Example Workflows ​

Daily Task Review ​

Creating New Tasks ​

Fixing Validation Issues ​

Team Task Management ​

Combining with CLI ​

Troubleshooting ​

Tasks not appearing in Explorer ​

Diagnostics not showing ​

Auto-completion not working ​

Keyboard shortcut conflicts ​

Performance with large workspaces ​

Roadmap ​

Phase 1 (v0.1.0) ✅ Complete ​

Phase 2 (v0.2.0) ✅ Complete ​

Phase 3 (v0.2.0+) 🚧 In Progress ​

Related Packages ​

Contributing ​

Development Setup ​

Privacy & Security ​

Requirements ​

Resources ​

Next Steps ​

License ​

VSCode Extension

What is it?

Installation

VSCode Marketplace (Recommended)

Command Line Install

Manual Install (Alternative)

Updates

Uninstall

Features

📋 Task Explorer Sidebar

⚠️ Smart Diagnostics

⌨️ Quick Task Actions

Toggle Completion

Tree View Context Menu

💡 Hover Tooltips

⚡ Smart Completion

Date Completion

Assignee Completion

Tag Completion

Priority Completion

🔍 CodeLens Inline Actions

📊 Interactive Dashboard

📊 Status Bar Integration

Task Format

Keyboard Shortcuts

Commands

Extension Settings

Settings Reference

`md2do.autoScan`

`md2do.warnings.enabled`

`md2do.defaultAssignees`

Configuration File

Common Configurations

Strict Validation

Minimal Warnings

Custom File Patterns

Example Workflows

Daily Task Review

Creating New Tasks

Fixing Validation Issues

Team Task Management

Combining with CLI

Troubleshooting

Tasks not appearing in Explorer

Diagnostics not showing

Auto-completion not working

Keyboard shortcut conflicts

Performance with large workspaces

Roadmap

Phase 1 (v0.1.0) ✅ Complete

Phase 2 (v0.2.0) ✅ Complete

Phase 3 (v0.2.0+) 🚧 In Progress

Related Packages

Contributing

Development Setup

Privacy & Security

Requirements

Resources

Next Steps

License