Kan Sync

Sync your Obsidian checklists with Kan.bn kanban boards — view boards in a sidebar, push note checklists as cards, and pull execution status back into your notes.

Kan.bn is the open-source alternative to Trello. This plugin turns any Obsidian note with checkboxes into a live kanban board and keeps the two in sync — without ever duplicating your board data locally.

Table of Contents

• Features
• How It Works
• Installation
• Configuration
• Commands
• Complete usage guide
• Sync Conventions
• Disclosures
• Data & Privacy
• API Endpoints Used
• Troubleshooting
• Limitations
• Roadmap
• Changelog
• Development
• License

Features

• Full Kan API coverage (v0.7.x) — board filters/templates/archive, card editing, workspace admin, invites, permissions, webhook management, Trello/GitHub import; slug resolve, named checklists, label colour sync.
• Sidebar board view with drag & drop — browse any Kan board inside Obsidian; drag cards between lists or reorder within a list. Filter by due date, label, or member.
• Push checklists to Kan — headings become lists; unchecked items become cards.
• Pull board status into notes — status table + auto-check completed items; optionally enrich lines with due dates, #tags, and @mentions from Kan.
• Rename-safe sync (ID markers) — hidden %%kan:ID%% comments so rewording updates the same card.
• Due dates — 📅 2026-08-14 or @due(2026-08-14); clearing the date on a note clears the card due date on push.
• #tags → labels — auto-created with deterministic colours; retro-label existing cards; optional remove when deletes are enabled.
• @mentions → assignees — matched by workspace member name or email prefix; set on card create.
• Card descriptions — indented text under an item (not a sub-checkbox) syncs to the card description.
• Sub-items → card checklists — two-way completion; optional delete of removed sub-items.
• Attachments — attach a file or the active note to a synced card.
• Card detail modal — edit title/description/due, toggle labels/members, checklist CRUD, attachments, activity, inline comments.
• Multi-workspace switcher — switch workspaces from the board view header.
• Board & list rename — renaming the note / kan_board or a heading can rename the Kan board / list on push.
• Optional deletes — opt-in removal of cards, labels, members, and checklist items that disappear from the note.
• Duplicate / delete card commands — from the cursor line (delete requires optional deletes).
• Workspace search, comments, done-item → Done list, auto-sync pull, self-hosted base URL.

How It Works

Your boards live on Kan's servers — the plugin is a live API bridge, not a local database.

┌─────────────────────┐         REST API          ┌──────────────┐
│  Obsidian (vault)   │ ◄───────────────────────► │   Kan.bn     │
│                     │                           │              │
│  Notes = the PLAN   │  Push: checklist → cards  │ Boards = the │
│  (what needs doing) │  Pull: status + meta → ☑  │  EXECUTION   │
│                     │  View: live board render  │ (progress)   │
└─────────────────────┘                           └──────────────┘

Nothing runs in the background except optional auto-pull. Push and pull only run when you invoke a command (or auto-sync tick).

Installation

Community plugins (recommended)

1. Settings → Community plugins → turn off Restricted mode if prompted
2. Browse / search for Kan Sync
3. Install and enable

Also listed at community.obsidian.md.

Manual

1. Download the latest release from GitHub Releases (manifest.json, main.js, styles.css)
2. Copy them into:

   <your-vault>/.obsidian/plugins/kan-sync/
   ├── manifest.json
   ├── main.js
   └── styles.css
   

3. Reload Obsidian (Ctrl/Cmd + R) and enable Kan Sync under Community plugins

Via BRAT

1. Install the BRAT plugin
2. Add https://github.com/x-o-r-r-o/Kan-Sync as a beta plugin
3. Enable Kan Sync in Community plugins

Configuration

Open Settings → Kan Sync.

Connection

Push (note → Kan)

Pull (Kan → note)

Board view header (not in Settings) also remembers board type (regular / template), archived visibility, and due-date filter.

Settings → Kan Sync also has an admin section (account, workspace CRUD, invites, roles/permissions, webhooks, integrations/imports, labels). Open it via Kan Sync: Open Kan Sync settings (admin).

Commands

All via Command Palette (Ctrl/Cmd + P):

Complete usage guide

1. Connect once

1. Install and enable Kan Sync.
2. Open Settings → Kan Sync.
3. Paste your API key from kan.bn/settings.
4. Click Detect next to Workspace (or paste a workspace public ID).
5. Leave Base URL as default unless you self-host.

2. Write a plan note

Use normal Markdown checklists. Headings (##–####) become Kan lists.

---
kan_board: Product Launch
---

## Phase 1 — Foundation
- [ ] Lock the launch date 📅 2026-07-20 #P0 @alex
  Confirm with leadership and freeze the calendar.
  - [ ] Draft announcement
  - [ ] Book venue
- [ ] Finalize positioning & core message #P1
- [x] Already done item

## Phase 2 — Assets
- [ ] Ad creatives batch 1 @due(2026-07-27) #marketing

Frontmatter

Line syntax

3. Push

1. Open the note.
2. Run Kan Sync: Push active note's checklist to Kan.
3. The plugin finds or creates the board, ensures lists, creates/updates cards, and appends %%kan:ID%% markers.
4. Open Kan Sync: Open board view to see the live board; drag cards to move them in Kan.

4. Work in Kan

Move cards, add labels/members/due dates in Kan (web or self-hosted). Collaborators can edit the board while your note remains the plan source.

5. Pull

1. Run Kan Sync: Pull Kan board status into active note.
2. Items whose cards sit in a Done list get checked off.
3. With pull options on, each linked line is enriched with 📅, #tags, and @mentions from the card.
4. A ## Kan Board Status table is written/updated at the bottom (or your custom heading).

6. Full sync

Kan Sync: Full sync active note (push + pull) — push plan changes, then pull execution state.

7. Descriptions and named checklists

- [ ] Ship docs #P1
  Audience: new self-hosters.
  Include Docker Compose and MinIO notes.
  ### Writing
  - [ ] Outline
  - [ ] Screenshots
  ### Review
  - [ ] Peer review

On push, the card description becomes:

From Obsidian: path/to/note.md

Audience: new self-hosters.
Include Docker Compose and MinIO notes.

Indented ### headings under a card create named Kan checklists; sub-item renames and order are pushed when titles change or items move.

8. Board and list rename

• Change kan_board (or rename the note if you rely on the basename) → next push renames the Kan board when Rename board to match note is on.
• Rename a ## heading whose cards already have markers → next push renames that Kan list when Rename lists to match headings is on.

9. Optional deletes (off by default)

Enable Allow deletes on push, then on the next push:

• Tags removed from a line → labels removed from the card
• @mentions removed → members removed
• Sub-checkboxes removed → checklist items deleted
• Entire synced items removed from the note → cards whose description starts with From Obsidian: <this note path> are deleted

You can also run Delete linked card (cursor line) with the cursor on a marked item.

10. Comments, attachments, duplicate

• Cursor on a marked line → Comment on linked card
• Attach a file / Attach active note
• Duplicate linked card creates a copy in the same list

11. Auto-sync

Set Auto-sync interval to e.g. 15. Only notes with kan_board in frontmatter auto-pull while active. Pushes stay manual so half-written plans are not pushed.

12. Self-hosted Kan

Set Base URL to your instance’s API root (usually ending in /api/v1). Everything else is the same.

Sync Conventions

• Dedupe key = ID marker when present; title (case-insensitive, formatting-stripped) as fallback. With markers on, rewording an item renames its card on next push.
• No deletions by default. Enable Allow deletes on push to remove cards/labels/members/subtasks that disappear from the note.
• One board per note. Use headings for phases, or multiple notes each with kan_board / kan_board_id.
• Labels attach at creation and via retro-label. Adding a #tag to an already-synced item labels the card on next push when Retro-label is on.
• Clearing a due date in the note clears dueDate on the card on push.
• Pull enrichment rewrites due/#tags/@mentions on linked lines from Kan (title text is preserved; meta is rebuilt).
• Vault owns the plan; Kan owns execution — avoid editing the same field on both sides in the same sync cycle.

Disclosures

This section covers items the community scorecard surfaces, per Obsidian developer policies. Also see SECURITY.md.

Account required

A Kan.bn account (or an account on your self-hosted Kan instance) and an API key are required for the plugin to function. There is no separate Kan Sync account.

Payment

No payment is required for this plugin. Kan.bn or your self-hosted host may have their own plans; this plugin has no in-app purchases.

Network use

All remote HTTP uses Obsidian’s requestUrl() API (three call sites in main.js):

1. Kan REST API — GET/POST/PUT/PATCH/DELETE to your configured Base URL (default https://kan.bn/api/v1) with your API key in the Authorization header. Used for boards, lists, cards, labels, members, search, comments, checklists, webhooks admin, imports, etc. Base URL must be https:// (or http://localhost for local self-host). Path IDs are URL-encoded; credentials in the Base URL are rejected.
2. Presigned attachment upload — PUT of file bytes to a short-lived https URL returned by Kan (typically S3-compatible object storage). The upload request does not include your API key. Non-https schemes are rejected.
3. Attachment download — GET of an attachment https URL when saving into the vault. Filenames are sanitized (no path traversal); downloads are capped at 50 MB.

No other remote hosts are contacted by default. Changing Base URL (self-hosted) redirects all Kan API traffic to that host. Optional Open authorization URL for Trello/GitHub import opens a browser tab only for validated https:// URLs returned by Kan.

Optional auto-sync pull (off by default) schedules a silent pull for the active note when kan_board frontmatter is set. It uses a one-shot timer only while the interval setting is > 0 — not a permanent background poller.

Clipboard access

The plugin writes invite links / codes to the system clipboard when you use Copy workspace invite link (and the matching Settings button). The clipboard is never read.

Vault access

Reads and writes Markdown notes via the Obsidian vault API (vault.read / vault.modify, frontmatter helpers). Does not access files outside the vault.

Telemetry

No analytics, crash reporters, or third-party telemetry. Traffic is only to your Kan API base and Kan-issued upload/download URLs.

Webhooks

Settings can create/update/test/delete Kan webhook endpoints. Obsidian cannot receive inbound HTTP; live event→vault sync needs an external relay.

Data & Privacy

If you sync your vault (Obsidian Sync, iCloud, git), data.json — including your API key — syncs with it. Add it to .gitignore for public repos.

API Endpoints Used

Core sync and board-view paths (not every admin/import route). The plugin client wraps the full Kan REST surface used by Settings admin, card modal CRUD, webhooks, and imports — see docs.kan.bn/api-reference.

Troubleshooting

Errors also go to the developer console (Ctrl/Cmd + Shift + I).

Limitations

• Without Allow deletes, sync is additive for labels, members, and completion (removing in the note never removes in Kan).
• Auto-sync pulls only; pushes stay manual.
• Card detail modal supports editing title, description, due date, labels, members, checklists, comments, and attachments; list membership and board-wide structure still change mainly via the board view, note push, or Kan’s web UI.
• Pull card descriptions is off by default; when on, Kan description body overwrites indented note text under linked items (subtasks preserved).
• Inbound Kan webhooks cannot be received inside Obsidian — Settings only manages webhook endpoints on Kan.
• @mention matching needs workspace name or email prefix; unmatched mentions are logged, never guessed.
• Pull enrichment rebuilds meta tokens; keep important wording in the title portion of the line.
• Sub-item renames without ID markers use title + positional matching; large checklist reshuffles can mis-pair items.

Roadmap

• Card↔item ID mapping — v0.2.0
• Self-hosted base URL, drag & drop, due dates, #tags, auto-sync — v0.2.0
• Retro-label, reordering, sub-items, search, comments, done-move — v0.3.0
• Two-way subtasks, attachments — v0.4.0
• Members, card modal, multi-workspace — v0.5.0
• Community plugin store — v0.5.2
• Description sync, richer pull, clear due, optional deletes, board/list rename — v0.6.0
• Full Kan API coverage (board filters/templates, card modal CRUD, workspace admin, webhooks manage, imports) — v0.7.0
• Slug resolve, named checklists, subtask rename/reorder, label colour sync, admin command wiring — v0.7.1
• Scorecard disclosures / CONTRIBUTING / auto-sync timer hygiene — v0.7.2
• Card order on push, optional pull descriptions, admin field fill-ins — v0.7.3
• Security hardening (URL allowlists, path encoding, filename/CSS sanitization) — v0.7.4

New ideas welcome via GitHub issues.

Changelog

0.7.4

• Security — validate Base URL / external URLs (https only, block javascript:/data:/credentials); encode path IDs; sanitize attachment filenames (path traversal); validate CSS colours; escape Markdown table cells; redact Bearer tokens in error text; safe window.open for OAuth; webhook/image URL checks

0.7.3

• Card order on push — sets each card’s index to match checklist order within its list
• Pull card descriptions (optional, off by default) — rewrites indented description text under linked items from Kan; keeps sub-checkboxes and named ### checklists
• Admin forms — workspace showEmailsToMembers, webhook update secret, user image URL

0.7.2

• Scorecard hygiene — add CONTRIBUTING.md and SECURITY.md
• Disclosures — document the three requestUrl call sites, clipboard write (invite links), optional auto-sync, no payment/telemetry
• Auto-sync — replace permanent setInterval with a one-shot timer only while the interval setting is enabled (avoids setInterval+network heuristic)

0.7.1

• Slug-based board resolve — stores/uses kan_board_slug + kan_workspace_slug (and Settings workspace slug) on push/pull
• Named checklists — indented ### Name under a card item maps to a Kan checklist of that name
• Subtask rename & reorder — push updates checklist item titles and indices (positional match when titles change)
• Label name/colour sync — existing #tags update Kan label casing and deterministic colour on push
• Open Kan Sync settings (admin) command; stats, invite lookup, get workspace/label, role/member permission inspect in Settings
• Workspace slug setting (auto-filled by Detect when available)

0.7.0

• Full Kan API coverage — client wraps all documented REST operations
• Board view: due/label/member filters, regular/template/archived lists, board actions (favorite, archive, visibility, slug, move, delete, templates), list drag-reorder and delete
• Card modal: edit title/description/due, toggle labels/members, checklist CRUD (rename/delete/reorder items), comment edit/delete, activity pagination, attachment delete + save to vault, duplicate options
• Push: new card position (start/end), list reorder to heading order, optional empty-list delete, kan_template_id / kan_labels frontmatter
• Settings admin: account/health, workspace CRUD, invites, members/roles/permissions, webhooks (manage only), Trello/GitHub import, label update/delete, danger-zone delete workspace
• Commands: test connection, import Trello/GitHub, invite/copy invite link, archive/favorite board, create from / save as template
• Note: Obsidian cannot receive inbound webhooks; webhook UI is for managing endpoints only

0.6.0

• Description sync — indented text under a checklist item becomes the card description
• Richer pull — optional sync of due dates, #tags, and @mentions from Kan onto note lines
• Clear due date — removing 📅 / @due() from a note clears the card due date on push
• Members on create — assignees sent in the create-card call
• Optional deletes — opt-in removal of cards, labels, members, and checklist items
• Board & list rename — rename Kan board/list from note / heading changes; kan_board_id frontmatter
• Duplicate / delete card commands
• README: Sync Conventions fixed; complete usage guide

0.5.2

• Documented network/account disclosures
• GitHub artifact attestations for release assets
• Community plugin store submission completed

0.5.1

• Remove "Obsidian" from manifest description (review requirement)
• MIT license file aligned with README

0.5.0

• @mention member sync; card detail modal; multi-workspace switcher
• Assignee names on board cards; versions.json

0.4.0

• Two-way sub-item completion; file/note attachments; attachment badges

0.3.0

• Sub-items, retro-labeling, done-move, comments, search, in-list reorder

0.2.0

• Drag & drop, ID markers, due dates, #tags, full sync, auto-sync, base URL

0.1.1

• Fix workspace detection response shape

0.1.0

• Initial release: board view, push, pull

Development

Plain JavaScript, no build step — main.js is the plugin.

1. Edit main.js
2. Reload Obsidian (or use Hot Reload)
3. node --check main.js for a quick syntax gate

PRs and issues welcome.

License

MIT © x-o-r-r-o

Kan.bn itself is AGPL-3.0 — this plugin is an independent API client and is not affiliated with the Kan team.