Advanced Configuration

Kanbn will search for a JSON or YAML configuration file in the root of the directory where it is initialised. The configuration file should be called kanbn.json or kanbn.yml.

If such a file is found, then project options (which are normally saved as YAML front matter in the index file) will instead be saved into this file.

If any project options are added to the index file, then the next time Kanbn writes to the index the options will be moved into the configuration file.

Note: in future, it might be possible to split project options between the index and configuration files, but for now configuration must be saved inside only one of these files.

This applies to the main board. In a workspace with several boards, a secondary board's own options always live in that board file's front matter, and a board-local operation never writes to the configuration file.

Note: Kanbn rewrites whichever file holds the project options every time it saves them (kanbn add, kanbn move, kanbn sort --save, kanbn validate --save, and so on). The YAML is regenerated, so formatting and comments in that file are not preserved.

Configuring default locations#

By default, Kanbn will store everything inside the .kanbn directory inside your workspace. The index file will be called index.md and tasks will be stored inside .kanbn/tasks/.

However, these paths can be configured by adding the following optional fields to your kanbn.json / kanbn.yml file:

{
  "mainFolder": "custom-kanbn-folder",
  "indexFile": "custom-index.md",
  "taskFolder": "custom-task-folder",
  "archiveFolder": "custom-archive-folder"
}

mainFolder: custom-kanbn-folder
indexFile: custom-index.md
taskFolder: custom-task-folder
archiveFolder: custom-archive-folder

Note: these options must go inside the configuration file in the root of your workspace. If they're added to the index file they will have no effect.

mainFolder#

This will rename the main folder where everything is stored. By default this is .kanbn.

indexFile#

This will rename the index file. By default this is index.md. It is relative to the main folder.

taskFolder#

This will rename the folder where tasks are stored. By default this is tasks. It is relative to the main folder.

archiveFolder#

This will rename the archive folder where archived tasks are stored. By default this is archive. It is relative to the main folder.

Multiple boards#

Two more workspace-scoped options control multiple boards: defaultBoard names the board that commands target when -b isn't given, and boards controls discovery, display order and per-board options.

defaultBoard: design
boards:
  exclude:
    - notes.md
  order:
    - index
    - design
  design:
    hiddenColumns:
      - Ideas

Contributors#

contributors is workspace-scoped too: an optional list of the people who work on this workspace, used to canonicalise assigned and comment author values and to answer "who is the current user?".

contributors:
  - gordon
  - name: dave
    email: dave@example.com
    aliases:
      - Dave Smith

It is advisory — nothing is ever validated against it. See Contributors.

Actions#

actions is a list of rules that fire when a task changes — "when this enters In Progress, assign it to me and tag it active". Unlike contributors it is board-scoped: declared in a configuration file it applies to every board, and declared in a board's front matter it applies to that board alone.

actions:
  - name: start-work
    on: task.moved
    when:
      toColumn: In Progress
    then:
      - assign: '@me'
      - addTag: active

Rules are declarative — Kanbn never executes anything a workspace supplies — and nothing a rule writes can fire another rule. --no-actions on any mutating command, or KANBN_NO_ACTIONS=1, steps around a rule that is misbehaving. actionsFile moves a long rule set out of front matter and into a file of its own. See Actions.

Note that indexFile also sets the main board's slug: with indexFile: board.md, the main board's slug is board, and main / default still resolve to it.

Where a configuration file exists, everything in it is inherited by every board — it is workspace-level by construction, so a board-scoped option declared there is a deliberate statement about all boards. Where there is no configuration file, the workspace options live in the main board's front matter, and only the workspace-scoped ones propagate; startedColumns, views and the rest stay with the main board.