Kanban.md is a modern VSCode extension that brings the power of Kanban boards directly into your Markdown workflow. Manage tasks, track progress, and organize projects using plain Markdown files with a beautiful, interactive drag-and-drop interface.

Built with modern technologies (React 19, TypeScript 5.9, Vite 7) and designed to respect your VSCode theme, Kanban.md seamlessly integrates with your development environment.

Note: This project is inspired by holooooo/markdown-kanban. It has been completely refactored with modern technologies and architectural patterns to provide enhanced performance and maintainability.

• 📋 Markdown-First Approach: Your data lives in .kanban.md files - no databases, no proprietary formats
• 🔄 Real-Time Bidirectional Sync: Changes in the Kanban view instantly update the Markdown file and vice versa
• 🎨 Theme-Aware UI: Automatically adapts to your VSCode theme (Dracula, One Dark Pro, etc.)
• ⚡ Smooth Drag & Drop: Built with @dnd-kit for fluid, responsive interactions
• 🗂️ Sidebar Integration: Dedicated Activity Bar icon with TreeView showing all kanban boards in your workspace

• Priority Levels: Three levels displayed as colored left border on cards (Trello-style)
  • High: red border
  • Medium: yellow border
  • Low: green border
• Workload Tracking: Four intensity levels with diamond icons
  • Easy (◇), Normal (◈), Hard (◆), Extreme (◆◆)
• Editable Task Modal: Click any task to open a modal where you can:
  • Click badges to cycle through priority/workload values
  • Add, remove, and edit subtasks inline
  • Edit description with save-on-blur
  • Set due dates with date picker
  • Unsaved changes indicator (●) shown in header
• Step-by-Step Tasks: Checkbox-based subtasks using - [ ] step format
• Tag System: Multiple tagging formats supported:
  • Inline: #tag1 #tag2
  • Array: [tag1, tag2, tag3]
• Due Dates: Track deadlines with due:YYYY-MM-DD
• Task Descriptions: Multi-line descriptions with Markdown code block support
• Expand/Collapse: Tasks collapsed by default for clean view

• Archive Support: Move completed columns to archive state
• Column Management: Hide/show, reorder columns via drag & drop
• Tag Filtering: Filter tasks by one or multiple tags (comma-separated)
• Multiple Sort Options: Sort by name, due date, priority, workload
• File Switcher: Toggle automatic file switching behavior
• Quick Board Creation: One-click creation with pre-filled templates
• Auto-Refresh: Sidebar updates when .kanban.md files change
• Configurable Task Format: Choose between header (###) or list (-) format

• Modern Architecture:
  • React 19 with functional components and hooks
  • Zustand for centralized state management
  • TypeScript 5.9 with strict mode
  • Vite 7 for lightning-fast builds
  • TailwindCSS 3 for utility-first styling
• Flicker-Free Drag & Drop:
  • Fingerprint-based content comparison (NormalizedDocument pattern)
  • Promise queue for serialized save operations
  • Optimistic UI updates with backend sync protection
  • Deferred save pattern - changes saved when modal closes
• Performance Optimizations:
  • Memoized components (React.memo) to prevent unnecessary re-renders
  • Single HTML build per panel lifecycle
  • Ref-based state tracking for message handlers
• Collision Detection: Smart closestCorners algorithm for accurate drop targeting
• Cross-Column Preview: Real-time visual feedback when dragging tasks between columns

1. Open VSCode
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)
3. Search for "Markdown Kanban"
4. Click Install

code --install-extension kanban-md-0.1.3.vsix

• VSCode: 1.74.0 or higher
• Node.js: 22+ (for development)

Option A: From Sidebar (Recommended)

1. Click the Kanban icon in the Activity Bar (left sidebar)
2. Click the ➕ New Kanban Board button
3. Enter a name (e.g., sprint-planning)
4. Board opens automatically with example tasks

Option B: Manual Creation

Create a file with .kanban.md extension:

# Project Sprint

## To Do

### Design User Interface
#design #ui #frontend
**Priority:** High
**Workload:** Hard
**Due:** 2024-12-01

Design user login and registration pages, including:
- Responsive layout design
- Brand color application
- User experience optimization

- [ ] Create wireframes
- [ ] Design mockups
- [ ] Get stakeholder approval

### Write API Documentation
#documentation #backend
**Priority:** Medium
**Workload:** Normal

Write complete REST API documentation using OpenAPI 3.0 specification.

## In Progress

### Implement Authentication
#security #backend
**Priority:** High
**Workload:** Extreme

- [x] Setup JWT tokens
- [ ] Add OAuth providers
- [ ] Write security tests

## Done

### Project Setup
#setup
**Priority:** Low
**Workload:** Easy

Initial repository setup complete!

Choose any method:

• Method 1: Click a board in the sidebar
• Method 2: Right-click .kanban.md file → "Kanban"
• Method 3: Command Palette (Ctrl/Cmd+Shift+P) → "Markdown Kanban: Kanban"

Moving Tasks

• Drag any task card to another column
• Changes save automatically to the Markdown file

Filtering & Sorting

• Enter tags in the filter box: design,urgent
• Use sort dropdown: Name, Due Date, Priority, Workload
• Click "Clear Filters" to reset

Task Operations

• Expand: Click task to view full details
• Edit: Click "Edit" button on task card
• Delete: Click "Delete" button
• Add: Click "+ Add Task" at column bottom

Column Operations

• Hide: Click eye icon on column title
• Reorder: Drag column header to new position
• Archive: Mark columns as archived

Modern Structured Format (Recommended)

### Task Title
- tags: [tag1, tag2, tag3]
- priority: high
- workload: Hard
- due: 2024-12-31
- defaultExpanded: true
- steps:
    - [x] Step 1
    - [ ] Step 2
  ```md
  Detailed description with **Markdown** support.
  Can include code blocks, lists, etc.

**Classic Inline Format** (Also Supported)

```markdown
### Task Title
#tag1 #tag2
**Priority:** High
**Workload:** Hard
**Due:** 2024-12-31

Task description here

- [ ] Step 1
- [x] Step 2

Access via File > Preferences > Settings → Search "Markdown Kanban"

Choose task format in Markdown files:

• "title" (default): Tasks use ### Header format
• "list": Tasks use - List item format

{
  "markdown-kanban.taskHeader": "title"
}

node --version  # Should be 22+
npm --version

# Clone repository
git clone https://github.com/wguilherme/kanban.md.git
cd kanban.md

# Install dependencies
npm install

# Build extension + webview
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Type checking
npm run check-types

# Linting
npm run lint

# Run tests
npm test

markdown-kanban/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── kanbanWebviewPanel.ts     # Webview lifecycle manager
│   ├── webview/                  # React application
│   │   ├── App.tsx               # Main React app
│   │   ├── components/
│   │   │   ├── KanbanBoard/      # Board + drag-drop components
│   │   │   ├── TaskModal.tsx     # Task detail modal
│   │   │   └── atoms/            # Atomic design: Button, Badge, etc.
│   │   ├── stores/               # Zustand state management
│   │   │   └── kanbanStore.ts    # Centralized board state
│   │   ├── hooks/                # Custom React hooks
│   │   └── types/                # TypeScript definitions
├── dist/                         # Build output
│   ├── extension.js              # Bundled extension
│   └── webview/                  # Bundled React app
├── vite.config.ts                # Vite config for extension
├── vite.webview.config.ts        # Vite config for webview
├── tailwind.config.js            # TailwindCSS with VSCode theme vars
└── tsconfig.json                 # TypeScript configuration

This project uses Vite 7 with dual configurations:

• Extension: Node.js SSR build (vite.config.ts)
• Webview: Browser SPA build (vite.webview.config.ts)

We welcome contributions! Whether it's bug reports, feature requests, or pull requests, your input helps make Markdown Kanban better.

1. Fork the repository

   gh repo fork wguilherme/kanban.md

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Write clean, typed TypeScript code
   • Follow the Atomic Design pattern for components
   • Add tests if applicable
   • Update documentation

4. Test thoroughly

   npm run check-types
   npm run lint
   npm run build
   # Manual testing in VSCode

5. Commit with clear messages

   git commit -m "feat: add task duplication feature"

6. Push and create PR

   git push origin feature/amazing-feature
   gh pr create

• Code Style: Follow existing patterns, use TypeScript strict mode
• Commit Messages: Use Conventional Commits
  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • refactor: Code refactoring
  • chore: Build/tooling changes
• Testing: Ensure no regressions before submitting
• Documentation: Update README/CHANGELOG for user-facing changes

• Use React DevTools for debugging webview components
• Check Output > Markdown Kanban for extension logs
• Test with multiple VSCode themes to ensure UI compatibility
• Verify .kanban.md file sync works bidirectionally

• 📱 Mobile/responsive improvements
• 🎨 Additional theme customization options
• 🔍 Advanced search/filter capabilities
• 📊 Task analytics and reporting
• 🌐 i18n/localization support
• 🧪 Test coverage expansion
• 📝 Documentation improvements

Found a bug? Please open an issue with:

• VSCode version: Help > About
• Extension version: Check extensions panel
• OS: Windows/macOS/Linux + version
• Steps to reproduce: Detailed repro steps
• Expected vs actual behavior
• Screenshots/GIFs: If applicable
• Sample .kanban.md file: If relevant

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Marketplace: VSCode Marketplace

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with VSCode Extension API
• Drag & drop powered by @dnd-kit
• UI components follow Atomic Design principles
• Special thanks to all contributors