Skip to content

Latest commit

 

History

History
206 lines (147 loc) · 6.47 KB

index-structure.md

File metadata and controls

206 lines (147 loc) · 6.47 KB
Raw

Index Structure

Here is a sample index file (.kanbn/index.md):

---
optionName: optionValue
---

# Project Name

Project description...

## Column 1

- [task-1](tasks/task-1.md)

## Column 2

- [task-2](tasks/task-2.md)
- [task-3](tasks/task-3.md)

The index file can optionally begin with YAML front-matter containing project options.

There should be a single level-1 heading at the top of the markdown body containing the project name.

The project description should appear below the title. The description can be of any length and can contain markdown, however it must not contain any headings.

Below the description there should be one or more level-2 headings. The 'Options' name is reserved for project options.

All level-2 headings (except for 'Options') will be treated as columns. Columns should only contain a list of links to task markdown files.

Project options

The 'Options' heading should be followed by a code block containing YAML. The 'yaml' info-string is not required, but might help with syntax highlighting in some editors.

Project options will be merged with YAML front-matter if any is present.

Note: when the index is saved, all project options will be placed into YAML front-matter. The 'Options' heading is still supported for backwards-compatibility.

hiddenColumns:
  - Archive
startedColumns:
  - In Progress
completedColumns:
  - Done
sprints:
  - start: date
    name: name
    description: ""
defaultTaskWorkload: 2
taskWorkloadTags:
  Nothing: 0
  Tiny: 1
  Small: 2
  Medium: 3
  Large: 5
  Huge: 8
columnSorting:
  Archive:
    - field: name
      filter: ""
      order: ascending
taskTemplate: ""
dateFormat: ""
views:
  - name: My view 1
    columns:
      "Column 1":
        - hidden: false
          filters:
            name: /test/
            workload:
              - 1
              - 5
          sorters:
            - field: name
              filter: ""
              order: ascending
    lanes:
      - name: "Lane 1"
        filter:
          - field: name
            filter: ""
customFields:
  - name: 'myCustomField'
    type: 'date'
{customFieldName}Columns:
  - {Column name}

hiddenColumns

A list of column names. These columns will be hidden from the kanbn board.

startedColumns

A list of column names. When a task is created in or dragged into one of these columns, the task's started date will be set to the current time, unless the task already has a 'started' date.

completedColumns

A list of column names. When a task is created in or dragged into one of these columns, the task's completed date will be set to the current time. If the task already has a completed date, this date will be updated.

sprints

A list of sprints. Each sprint will have start, name and description properties.

Run kanbn sprint --help for more information.

defaultTaskWorkload

The default workload amount for tasks. When a task has no workload tags applied to it, this value will be used instead.

taskWorkloadTags

An associative array of tag names and workload values. If these tags are added to a task, their values will be used to calculate the task workload. Multiple workload tags can be added to a task, in which case their values will be summed.

columnSorting

An associative array of column names and sorters. Each column can have an array of sorters, where each sorter should have field, filter and order properties.

The filter property can be used to transform values before sorting.

Run kanbn sort --help for more information.

taskTemplate

A template literal used for rendering tasks on the kanbn board. The following variables can be interpolated into the string:

name
description
created
updated
started
completed
due
tags
subTasks
relations
overdue
dueDelta
dueMessage
column
workload
progress
{...customFields}

The default task template is ^+^_${overdue ? '^R' : ''}${name}^: ${created ? ('\\n^-^/' + created) : ''}.

This string can contain markup sequences. See terminal-kit for markup reference.

Note: custom fields can also be interpolated into the task template, but only if they are defined in customFields (see below).

dateFormat

The date format to use for dates on the kanbn board and burndown chart views. See dateformat for date format reference.

views

An array of views that can be used to customize how the kanbn board is displayed.

Each view should have a name property (run kanbn board --view "name" to specify which view to use), a list of columns and a list of lanes.

Each column can be hidden, filtered or sorted. Each lane has a list of filters.

customFields

An array of custom metadata fields, where each field should have name and type properties. Adding a custom field to this list allows you to reference the field when adding, updating, searching and sorting tasks.

Run kanbn add --help, kanbn edit --help, kanbn find --help and kanbn sort --help for more information.

Valid types are:

  • boolean
  • date
  • number
  • string

Additionally, if a custom field has type date, the custom field can have a string property called updateDate. See the {customFieldName}Columns section for information on how this property is used.

{customFieldName}Columns

A list of column names. {customFieldName} should be the name of a custom field with type date (see the customFields section above for more information).

When a task is created in or dragged into one of these columns, the matching custom field in the task can be set to the current time.

If the custom field has updateDate set to once, the field will only be updated if it doesn't already have a value.

If the custom field has updateDate set to always, the field will be updated every time the task is moved into a linked column.

Here's an example of how this could be used:

  • Assume we have added a column called Testing
  • In index.md (or kanbn.json / kanbn.yml if using a separate configuration file), we have: 
    customFields:
  - name: testedAt
    type: date
    updateDate: once
testedAtColumns:
  - Testing
  • When a task is moved into the Testing column and the task doesn't already have a testedAt value in its metadata, this value will be automatically populated with the current date/time.