Bases Kanban Companion

Route project notes to status-based folders alongside Obsidian's built-in Bases Kanban view. Keep To do, Doing, and Review in one folder, and move Done to an archive folder without changing your board layout.

An independent community plugin, not an official Obsidian product. It does not add a Kanban view or replace Bases.

Features

• Map each project's statuses to folders. Multiple statuses can share a folder.
• Configure project and status property names.
• Exclude folders, including their descendants.
• Create tasks with project metadata and an initial status in a configured folder.
• Create issues from Markdown templates and allocate per-project identifiers.
• Reorder cards with a numeric property, respecting leading native sort options.
• Define custom text-value sorting, including labels in your own language.
• Open embedded Kanban boards in a new tab.
• Optionally display compact cards with horizontal property blocks.
• Review pending moves before applying rules to existing notes.
• Import settings from Project Task Router version 2 without rewriting note properties.

All processing is local. No accounts, network requests, telemetry, or extra runtime dependencies.

Requirements and installation

Supports desktop Obsidian 1.14.4 or newer. Card dragging, custom value sort setup, compact layout, and embedded open buttons are enabled only on the tested 1.14.4 build; routing and issue creation are separate. Mobile is not enabled until it has been tested. Enable the Bases core plugin to use the official Kanban view. Routing also works when you edit a note's status directly.

To install manually:

1. Download main.js, manifest.json, and styles.css from the latest GitHub release, or build from source with the commands below.
2. Back up your vault and test in a disposable vault first.
3. Create .obsidian/plugins/bases-kanban-companion/ in that vault.
4. Copy the three downloaded files (or the built files from release/) into it.
5. Reload Obsidian and enable Bases Kanban Companion in Community plugins.

No rules are installed by default, and no startup scan moves existing notes.

Quick start

Open Settings → Bases Kanban Companion.

1. Keep the default properties: project and status.
2. Add a project named EXAMPLE and set its new-task folder to Tasks/Active.
3. Add the following statuses, in this order:

4. Save. Saving settings does not move existing notes.
5. Run Bases Kanban Companion: Create project issue from the command palette.
6. Open the example Base, which groups cards by status and includes both folders.
7. Move the card to Done. Its status changes, and the plugin moves the same note to Tasks/Archive. Move it back to Doing to restore it to Tasks/Active.

You can also import example-settings.json in the settings screen, review the draft, and save.

A task contains properties like these:

---
project: EXAMPLE
status: To do
issue_id: EXAMPLE-1
---

The new-task command fills those properties automatically. The first configured status is the initial status. Native Bases New buttons are separate: this plugin does not intercept them or control their creation folder. Add matching properties to notes created that way.

Routing scope and safety

• Only Markdown notes are eligible. .base files and attachments are not moved.
• Project and status values must match exactly. Note type values do not restrict routing.
• The note's current folder must be the project's new-task folder or one of its destination folders. Managed subfolders are not implicitly included.
• Excluded folders and their descendants cannot be sources or destinations. Add your template folder here if it overlaps a managed folder.
• Paths must be vault-relative and non-hidden. Root, absolute, traversal, and hidden-folder paths are rejected.
• Existing destination files are never intentionally overwritten; conflicts are skipped with a notice. Obsidian or the filesystem may also reject a rename, for example due to case-insensitive filename collisions.
• Moves use Obsidian's FileManager, respecting its link-update setting.
• Unknown statuses and disabled or unconfigured projects are ignored.
• Startup does not reconcile existing notes. After startup, matching metadata edits or file renames trigger routing, even if the edit did not change the status itself.
• Existing notes can be moved through Review pending moves, which lists source and destination paths before applying.

This is not a backup or a move-history system. To undo a routed move, change the status to one mapped to the previous folder, or move the note manually. Back up your vault before enabling automation.

Board filters

Include every relevant folder in your Base filter, including archive destinations. Otherwise, moved cards disappear from that view even though the notes still exist. The plugin never edits your .base files automatically.

If you only need columns for physical folders, Bases itself supports moving cards between file.folder columns. This plugin is useful when status columns and physical folders differ. See the official folder-column announcement and Bases Kanban help.

Migrating from Project Task Router

See migration instructions. Keep a copy of your old settings and disable the old plugin before enabling equivalent rules here. Do not run both routers on the same notes.

Upgrading to 1.1.0

The Type property and Required type value settings have been removed. Routing now uses project, status, and managed folders, regardless of a note's type. Review managed folders and exclusions before upgrading if you used that restriction. Existing note properties and Base filters are not rewritten; a type filter in your Base still applies. Compact layout is off by default; an existing saved compact-layout preference is retained. See the 1.1.0 release notes.

Kanban features

Open an embedded Kanban board

On desktop Obsidian 1.14.4, external .base Kanban embeds in Markdown notes show Open on the left above the native toolbar, away from Live Preview's top-right code-edit action. Click to open the same Base in a new tab; an explicit view fragment in the embed link is retained. Works in Live Preview and reading mode. Standalone Bases, other layouts, and inline base code blocks do not receive the button. There is no project-specific path or setting.

This feature observes the existing embed DOM, rather than replacing the official Kanban view or adding another layout. Other app versions are disabled until their DOM has been verified. Link resolution and opening use public Obsidian APIs, including source-note context for relative links and nested note embeds. Buttons and observers are removed on unload or when leaves/views change. Buttons are hidden in print. No notes, Base configuration, sort options, or plugin settings are written by this feature.

Compact card layout

When enabled, Kanban card titles remain above a responsive row of property blocks. Each block keeps its label above its value; additional blocks wrap when the card is narrow. Settings → Card layout → Compact card layout is optional and off by default, including when importing older settings. Toggling it saves and applies immediately, without Save or a plugin reload. Other settings remain drafts until Save; this toggle does not save their pending edits. One toggle controls both horizontal property blocks and compact height. Turning it off restores the official vertical property layout and card height immediately; notes and sorting remain unchanged.

Property block width sets the minimum width of each block (3–10rem, default 5rem) and also saves and applies immediately. Lower it when blocks wrap onto an extra row in narrow columns, for example when a column's scrollbar takes up width. Card height still fits one label row and one value row, so every card in a view keeps the same height.

When enabled on desktop Obsidian 1.14.4, the plugin measures the rendered property rows and adjusts the official view's sizing placeholders to their total height. Cards share one compact height per view; resizing or changing displayed properties recalculates it. The native renderer still calculates card positions, scroll height and drag targets. Titles stay single-line and cover-image height remains native. No note, sort or Base configuration is written. Other Base layouts and note Properties are unchanged. This uses version-guarded internal DOM, not a public variable-height API. Observers and all layout/sizing overrides are removed when disabled or on unload. Other versions retain the official layout until their DOM has been verified.

Create issues from templates

Create project issue offers Choose template and Clear. Set an optional Template folder in plugin settings; its Markdown files and subfolders are searchable by full path. Blank searches all visible Markdown notes. Without a selection, creation keeps the built-in task layout. Native Bases New is not intercepted.

The new note copies the template's properties and body. The selected project, first configured status, and explicitly selected dropdown values override template properties. Leave a dropdown at Use template value / not set to keep its template value. Other properties, including type, remain unchanged. The source template is never edited. Frontmatter is reserialized, so YAML comments and formatting may change.

Plain templates support {{title}}, {{date}}, {{time}}, and Moment formats such as {{date:YYYY/MM/DD}} in body text and string property values. Defaults are YYYY-MM-DD and HH:mm, independent of the core Templates settings. Unknown variables remain literal. Templater scripts (<% … %>) are rejected, not executed. Invalid frontmatter, stale templates, settings changes, and existing target files abort creation. The Templates core plugin is not required.

Project issue identifiers

New issues created through Create project issue receive issue_id: PROJECT-1, then PROJECT-2, independently per project. Filenames remain the entered title. The generated ID overrides any template ID. Existing cards are not backfilled; native Bases New does not allocate an ID.

Project names saved through settings must contain English letters only and are normalized to uppercase (example → EXAMPLE). Digits, spaces and punctuation are rejected. Legacy names are preserved on load, not silently renamed. They cannot create new identifiers until corrected. Case-normalization saves are blocked while existing notes still use the previous name; update those project values first. Routing retains its exact-match behavior. issue_id is reserved and cannot be used as a routing, ordering or custom-value property.

Last reserved numbers are stored in plugin data.json as issueCounters, separate from card order. Creation and settings writes run in one queue. A reservation is persisted before the note is created; failure can leave a gap. Deleting a note or project, restarting, and saving/importing an older settings draft do not lower the stored counters. A fresh scan of all visible Markdown notes also considers existing IDs, including archived notes and templates; omit IDs from templates to avoid reserving unnecessary numbers. Moving notes does not change their IDs.

This is a single-app allocator, not a distributed sequence service. Simultaneous creation on synchronized devices is not guaranteed unique. Create issues on one device, then sync. Keep backups of data.json: losing counters and deleting the corresponding notes removes the history needed to prevent reuse. Do not manually edit counters or identifiers. No startup scan changes existing notes.

Manual card ordering (experimental)

Enable the opt-in Experimental card ordering setting to reorder cards. It keeps the official Kanban view and uses guarded, undocumented drag information from desktop Obsidian 1.14.4. Other versions are disabled for this feature; normal folder routing is separate.

Enable it in settings, and include the configured numeric property (order by default) with ascending direction in the official Sort menu. Manage sort options and their precedence there; dragging does not rewrite your sort list or add a separate priority mode.

• order first: reorder freely within a status column, regardless of priority.
• priority then order: reorder only cards with the same priority.
• priority, assignee, then order: both values must match.
• Sort options after order do not restrict dragging.
• No order in Sort: custom card reordering is inactive.

Only order values change. Each same-column drop numbers the entire displayed column from 1 at the top to N at the bottom, initializing missing ranks and closing gaps. Numbers do not restart per priority. Cards outside the moved bucket stay in their displayed positions, but their numbers may change. Switching to order-only sorting follows this last saved display order, not an older manual order hidden by priority sorting. Descending order is rejected with an instruction to choose ascending; the plugin does not change your Sort menu. Same-position drops also fix missing or non-sequential ranks, including a single-card column. An already-numbered same-position drop writes nothing. Startup, sort changes and cross-column moves do not renumber notes. Undo last card reorder restores the last update in the current plugin session, provided those fields have not changed since then.

Card ordering supports up to 200 cards per column without a search or result limit. Arbitrary formulas, file modification time, and file size before order are not supported because their values may change when order is saved. Only the unchanged generated formulas described below are accepted. Multi-file writes are not atomic: completed writes are restored on failure where no later edit conflicts; any incomplete recovery is reported. Back up before testing.

Custom text-value ordering

Configure Custom value sorting for existing text properties, such as priority. Enter one label per line in display order, e.g. High, Medium, Low. Set Sort option name to the label you want in the official Sort menu, e.g. Priority: High → Medium → Low. This names the generated sort, not the actual note property. An empty name keeps the current board label or generates a default. The automatic guidance under each rule tells you to select that name in the official Kanban Sort menu and put order with ascending direction below it. It also shows the configured value order and explains same-value dragging. There is no editable Description field; help is generated in settings and the Apply confirmation, not stored as a user-written description or task property.

Labels remain ordinary note properties, not a global enum; existing notes are never assigned or renamed automatically. The plugin’s Create project issue dialog offers those labels as optional dropdown choices. Native Bases New and Obsidian’s property editor are not replaced or restricted.

1. Save the rule in settings.
2. In the official Kanban Sort menu, include that text property and order.
3. Click Apply saved rules to a Base, or run Apply custom value sorting to Base, choose a .base file and confirm.
4. The selected Base gets a numeric formula sort before the matching text sort. With ascending formula sort, labels follow the configured order; unlisted and empty values sort last. The text sort keeps unlisted labels separate.
5. Same-column dragging changes only order within identical leading values. Further sorts before order (e.g. assignee) still constrain dragging.

Change label order by editing the settings list, saving, and reapplying to the Base. The same Save → Apply flow updates the option name without changing the generated formula or sort positions. A removed secondary text sort is not restored on reapplication. Keep it if you need unlisted labels separated; using only the generated formula and order is sufficient for the listed values. A stale or manually edited formula blocks constrained dragging rather than guessing its meaning. Reapplication preserves native sort precedence/directions, other views and filters, and refuses to overwrite an edited formula. The explicit setup rewrites that selected Base’s YAML, so comments/formatting may change. No startup scan edits Bases or task notes. Generated formulas remain usable by Bases when the companion is disabled. Remove their sort rows in the official menu to return to ordinary text sorting; removing a settings rule alone does not remove an already-applied Base sort.

Development

Node.js 22 or newer is recommended for development. Node.js is not required by the plugin at runtime.

npm ci
npm run check

This runs unit and integration tests, bundles src/main.cjs into main.js, and prepares release/ with only the three installable assets. Tests and build scripts use Node.js; the runtime bundle imports only obsidian. Card ordering also reads internal drag structures as described above.

• src/core.cjs: configuration, migration, note matching, and task metadata.
• src/router.cjs: serialized moves, conflicts, and stale-state checks.
• src/card-order.cjs: rank updates, leading-sort constraints, recovery, and the version-guarded native drag adapter.
• src/value-sort.cjs: explicit Base setup and safe custom label-to-rank formulas.
• src/task-template.cjs: template filtering, property merging, and plain variable rendering.
• src/issue-id.cjs: per-project issue numbers and monotonic counter merging.
• src/kanban-tracker.cjs: version-guarded discovery of official Kanban views, shared by the open buttons and compact layout.
• src/render-scheduler.cjs: frame-deferred refreshes with a limit on repeated DOM changes.
• src/embedded-board.cjs: open buttons for official Kanban embeds.
• src/card-layout.cjs: compact shared card sizing using native Kanban measurements.
• src/main.cjs: Obsidian lifecycle, commands, and settings UI.
• test/: routing, settings, and plugin-lifecycle tests.

For release preparation and remaining verification, see the release checklist.

License

MIT. Copyright © 2026 wjsyuwls.