MarkBoard

A local-first, browser-based Kanban board that stores tasks in plain Markdown.

MarkBoard is designed for people who want the UX of a visual board while keeping full ownership of their data as regular .md files.

Why MarkBoard

• Local-first by default: no backend required.
• Markdown-native: board data remains human-readable and git-friendly.
• Portable storage options:
  • File System Access API (direct local directory/file writes in supported browsers)
  • OPFS fallback (sandboxed browser storage)
• Fast editing flow with debounced persistence.
• Type-safe codebase with Vue 3 + TypeScript.

Current Status

This repository is an application prototype with core board, storage, and sync flows implemented.

Implemented in code today:

• Board load and save lifecycle
• Markdown parse + serialize pipeline
• FSA storage provider
• OPFS storage provider
• Debounced sync manager with retry support
• Basic Kanban interactions and theme/accessibility toggles

Planned/iterative areas (from the technical design direction):

• Expanded AI-assisted workflows
• Additional accessibility refinements
• PWA/offline packaging and advanced export/import pathways

Tech Stack

• Vue 3
• Pinia
• TypeScript
• Vite
• Tailwind CSS v4 alpha
• Headless UI (Vue)
• vuedraggable
• unified + remark + gray-matter
• idb-keyval
• Vitest + ESLint + Prettier + Husky + lint-staged

Project Structure

src/
  core/
    parser.ts           # Markdown -> Board and Board -> Markdown
    types.ts            # Core domain types
    storage/
      index.ts          # Storage interface and error model
      fsa.ts            # File System Access provider
      opfs.ts           # OPFS provider
      sync.ts           # Debounced write/sync manager
  ui/
    components/         # Kanban UI and dashboard components
    stores/
      boardStore.ts     # Pinia board state and mutations
    styles/
      main.css
  App.vue
  main.ts

How It Works

1. User action updates Pinia board state.
2. Sync manager enqueues a debounced save.
3. Active storage provider serializes board data to Markdown.
4. Data is written to:
   • local file via FSA, or
   • sandboxed OPFS file.

Markdown acts as the durable board format.

Requirements

• Node.js 18+
• npm 9+ (or compatible npm with lockfile support)

Quick Start

npm install
npm run dev

By default, the dev server runs on:

• http://localhost:5000

Available Scripts

• npm run dev - Start Vite dev server (strict port 5000)
• npm run build - Type check and production build
• npm run preview - Preview production build
• npm run test - Run tests once (Vitest)
• npm run test:watch - Run tests in watch mode
• npm run lint - Lint TypeScript and Vue files
• npm run format - Format TS/Vue/CSS/MD under src

Browser Notes

Storage behavior depends on browser capabilities:

• Chromium-based browsers: best experience with File System Access API.
• Other browsers: OPFS storage mode is used when available.

If directory permissions are revoked or require re-authorization, the app prompts the user to grant access again.

Data Format

MarkBoard persists board state in Markdown with frontmatter and task metadata comments.

High-level mapping:

• ## Column Name -> board column
• - [ ] Task / - [x] Task -> card completion state
• HTML comment JSON -> structured metadata for a card

Testing and Quality

• Unit tests: Vitest (examples in src/core/*.spec.ts and src/core/storage/*.spec.ts)
• Linting: ESLint with Vue + TypeScript configs
• Formatting: Prettier
• Pre-commit checks: Husky + lint-staged

Build for Production

npm run build
npm run preview

Build output is generated in dist/.

Publish Checklist

Before making the project public:

1. Verify tests and lint pass:
   • npm run test
   • npm run lint
2. Ensure no sensitive data is committed:
   • no local board content samples with private data
   • no credentials in code or config
3. Confirm .gitignore excludes generated and local-only files.
4. Validate README accuracy against current functionality.
5. Create a tagged release after a green build.

Contributing

Contributions are welcome. Suggested flow:

1. Fork and create a feature branch.
2. Keep changes focused and tested.
3. Run lint + tests before opening a PR.
4. Describe behavior changes and migration impact in the PR.

License

This project is licensed under the MIT License.

See LICENSE for details.