Obsidian Corkboard

Scrivener-style corkboard for Obsidian. Each folder gets a single index.corkboard file that renders the folder's markdown notes as index cards arranged in a flowing grid.

繁體中文：README_zh_TW.md

What it gives you

• Each card represents one .md file in the folder.
• Cards show the file's title, an author-written synopsis (separate from the file body), a status label, and an optional colour.
• Drag to reorder, multi-select with Cmd/Shift, drag-and-drop reorder.
• Right-click context menus on cards (write synopsis to file, change status / colour, remove from corkboard, add file back, …) and on the empty area (new card, add existing file).
• Auto-sync with the file system: creating, renaming, deleting, or moving .md files in the folder is reflected in the corkboard immediately, even when the corkboard view is closed.
• Per-corkboard card width / height, persisted with the document.
• Customisable status labels (default: Todo / Draft / Revision / Done).
• Read-only banner with Show raw / Reset when the corkboard JSON is corrupt — the plugin never silently overwrites a damaged file.

Desktop only.

Install

While the plugin isn't on the community plugin list yet, install manually:

1. Build it locally (see Development below) or download the release artifacts (main.js, manifest.json, styles.css).
2. Copy the three files to <your vault>/.obsidian/plugins/corkboard/.
3. In Obsidian → Settings → Community plugins → enable Corkboard.

Quick start

The fastest path to a working corkboard:

1. Right-click a folder in the file explorer → Create corkboard.
2. Or use the command palette: Corkboard: Create for current folder (creates one for the folder containing the active note).

Either entry point creates an index.corkboard file in that folder pre-populated with one card per existing .md file. The corkboard opens in a new tab.

How to use it

Creating cards

Action	Result
Right-click empty area → New card	Creates a new Untitled-N.md file in the folder and adds a card
Right-click empty area → Add existing file…	Fuzzy-search a folder file that isn't on the board yet, add it as a card
Create an .md directly in the file explorer	Auto-syncs as a new card at the end

Editing a card

• Click synopsis area → type → click out (or focus another card) to commit. Esc to cancel.
• Double-click the title → inline rename. Enter / blur commits; Esc cancels. The underlying file is renamed via Obsidian's fileManager.renameFile, so backlinks update.
• Right-click a card for status, colour, "Write synopsis to file", "Remove from corkboard", "Rebind…".

Selection & navigation

Gesture	Result
Click a card	Select (blue outline)
Cmd/Ctrl-click	Add or remove from selection
Shift-click	Range-select from the previous anchor
Click empty area	Clear selection
Double-click a card body	Open the underlying .md in a new tab

Reorder

Drag any card and release on top of another to reorder. The new order is persisted in index.corkboard.

Card menu, with multi-select

If you right-click a card while multiple cards are selected, the menu applies to all selected cards — so you can change status / colour in batch, or remove several cards at once.

File system sync

If you create / rename / delete / move a .md file via the file explorer (or another tool, while Obsidian is open), the corkboard catches up:

• Created → new card appended.
• Renamed → card title updates; synopsis / status / colour preserved.
• Deleted → card is removed.
• Moved across folders → removed from the old folder's corkboard, added to the new folder's corkboard.

If the plugin was disabled when a file was deleted, the orphaned card is shown dimmed with a red ⚠ badge. Right-click → Remove from corkboard to clean up.

Settings

Settings → Community plugins → Corkboard → cog icon. The settings tab lets you rename the four status labels (the underlying status ids stay stable, so existing cards still display).

Data model

Each corkboard is a JSON file at <folder>/index.corkboard:

{
  "version": 1,
  "cardWidth": 280,
  "cardHeight": 180,
  "cards": [
    {
      "path": "novel/ch01-opening.md",
      "synopsis": "Protagonist meets the antagonist.",
      "status": "draft",
      "color": "blue"
    }
  ]
}

title is derived from path (no separate field). Synopsis lives in the JSON; you can also push it into the file via right-click → Write synopsis to file (insert as the first paragraph, after frontmatter).

Known limits in v0.1.0

• Rebind to another file… is a stub (shows a Notice).
• The drag drop indicator is functional but visually minimal.
• Sub-folders are ignored; the corkboard only shows md files in the same folder as the index.corkboard.
• No undo/redo within the view.
• Mobile is not supported (isDesktopOnly: true).

Development

Stack: TypeScript, esbuild, Preact (automatic JSX runtime), Vitest + jsdom + @testing-library/preact for tests.

npm install
npm run dev      # esbuild watch mode
npm run build    # type-check + production bundle
npm run test     # run unit + component tests
npm run lint     # eslint with obsidianmd plugin rules

Source layout:

src/
  main.ts                       # plugin lifecycle, registrations
  constants.ts, types.ts
  data/
    corkboardDocument.ts        # parse / serialize / mutations
    schema.ts                   # runtime validator (v1)
    initialData.ts              # build a fresh document from a folder's md files
  state/
    controller.ts               # CorkboardController + VaultGateway interface
    selectionStore.ts, dragStore.ts
  sync/
    vaultSync.ts                # vault events ↔ controller registry
    pathResolver.ts, synopsisInjector.ts
  view/
    CorkboardView.tsx           # TextFileView + Preact mount + corrupt-JSON banner
    components/
      CorkboardApp.tsx, CardGrid.tsx, Card.tsx, SynopsisEditor.tsx,
      Toolbar.tsx, ContextMenus.ts, AddCardModal.ts, DragLayer.tsx
  settings/
    settings.ts, settingsTab.ts
  utils/
    debounce.ts, filename.ts

The design spec and implementation plan live in docs/superpowers/. The manual integration test plan is docs/superpowers/test-plan.md.

License

0BSD (matches the original Obsidian sample plugin scaffold this is built from).