vscode-kanban

Install
How to use
Customization
- CSS
Support and contribute
Related projects
- vscode-helpers

Launch VS Code Quick Open (Ctrl + P), paste the following command, and press enter:

ext install vscode-kanban

Or search for things like vscode-kanban in your editor.

How to use [↑]

How to execute [↑]

Press F1 and enter one of the following commands:

Name	Description	command
`Kanban: Open Board ...`	Opens a kanban board of a workspace (folder).	`extension.kanban.openBoard`

Settings [↑]

Open (or create) your settings.json in your .vscode subfolder of your workspace or edit the global settings (File >> Preferences >> Settings).

Add a kanban section:

{
    "kanban": {
        "openOnStartup": true
    }
}

Name	Description
`cleanupExports`	Remove existing export files, before regenerate them. Default: `(true)`
`exportOnSave`	Export cards to external Markdown files on save or not. Default: `(false)`
`exportPath`	The custom path where export files, like cards, should be stored. Relative paths will be mapped to the `.vscode` subfolder of the underlying workspace. Default: `.vscode` subfolder of the underlying workspace.
`globals`	Custom data, which can be used inside the extension, like event scripts.
`maxExportNameLength`	The maximum size of the name of an export file. Default: `48`
`noScmUser`	Do not detect username via source control manager like Git. Default: `(false)`
`noSystemUser`	Do not detect username of operating system. Default: `(false)`
`noTimeTrackingIfIdle`	Do not show 'track time' button, if a card is stored in 'Todo' or 'Done'. Default: `(false)`
`openOnStartup`	Opens a board, after a workspace (folder) has been loaded. Default: `(false)`
`trackTime`	Settings for time tracking feature. Default: `(false)`

Markdown support [↑]

Card descriptions can be formatted with Markdown, which is parsed by Showndown library.

The extension uses the following settings:

{
    "completeHTMLDocument": false,
    "encodeEmails": true,
    "ghCodeBlocks": true,
    "ghCompatibleHeaderId": true,
    "headerLevelStart": 3,
    "openLinksInNewWindow": true,
    "simpleLineBreaks": true,
    "simplifiedAutoLink": true,
    "strikethrough": true,
    "tables": true,
    "tasklists": true
}

Code blocks are parsed by highlight.js and all provided languages are included and supported.

Handle events [↑]

For handling events, you can create a Node.js JavaScript file, called vscode-kanban.js, inside your .vscode subfolder of your workspace and start with the following skeleton (s. EventScriptModule interface):

// all 'args' parameters are based on
// 'EventScriptFunctionArguments' interface
// 
// s. https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html

// use any Node.js 7 API, s. https://nodejs.org/
const fs = require('fs');
// use VSCode API, s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
const vscode = require('vscode');

// [OPTIONAL]
// 
// Is raised after a CARD has been CREATED.
exports.onCardCreated = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardcreatedeventdata.html

    // access a module of that extension
    // s. https://github.com/mkloubert/vscode-kanban/blob/master/package.json
    const FSExtra = args.require('fs-extra');

    // write own data to
    // 'tag' property of a card (args.tag)
    // 
    // also works in:
    // - onCardMoved()
    // - onCardUpdated()
    await args.setTag( 'Any JSON serializable data.' );    
};

// [OPTIONAL]
// 
// Is raised after a CARD has been DELETED.
exports.onCardDeleted = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.carddeletedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a CARD has been MOVED.
exports.onCardMoved = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardmovedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a CARD has been UPDATED.
exports.onCardUpdated = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.cardupdatedeventdata.html
};

// [OPTIONAL]
// 
// Is raised after a column has been cleared.
exports.onColumnCleared = async (args) => {
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.columnclearedeventdata.html
};

// [OPTIONAL]
// 
// Is raised when an user clicks on a card's 'Track Time' button.
// This requires global extension / workspace setting 'canTrackTime' to be set to (true).
exports.onTrackTime = async (args) => {
    // args => https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.tracktimeeventarguments.html
};


// [OPTIONAL]
// 
// Generic fallback function, if a function is not defined for an event.
exports.onEvent = async (args) => {
    // args.name => name of the event
    // args.data => object with event data  
};

Time tracking [↑]

Simple time tracking [↑]

Set the value of trackTime inside your .vscode/settings.json to (true):

{
    "kanban": {
        "trackTime": true
    }
}

This will run a simple workflow, which writes all required data to the tag property of the underlying card (s. .vscode/vscode-kanban.json).

Toggl [↑]

To use the build-in Toggl integration, you have to setup your personal API token, which can you find in your profile settings:

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "<YOUR-API-TOKEN>"
        }
    }
}

If you do not want (or if you not able) to save the token in the settings, you can define the path to a text file, which contains it.

For example, create a text file inside your home directory, like toggl.txt, and write the token there. After that, you must define the path of the text file in the settings (.vscode/settings.json):

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "toggl.txt"
        }
    }
}

You also can define an absolute path, like D:/toggl/api-token.txt or /home/mkloubert/toggl-api-token.txt.

For the case, your board belongs to a specific Toggl project and you know its ID, you can define it explicitly:

{
    "kanban": {
        "trackTime": {
            "type": "toggl",
            "token": "<API-TOKEN>",

            "project": 123
        }
    }
}

Custom time tracking [↑]

For handling 'track time' events, you can create or edit a Node.js JavaScript file, called vscode-kanban.js, inside your .vscode subfolder of your workspace and add the following function:

exports.onTrackTime = async (args) => {
    // args => https://mkloubert.github.io/vscode-kanban/interfaces/_workspaces_.eventscriptfunctionarguments.html
    // args.data => s. https://mkloubert.github.io/vscode-kanban/interfaces/_boards_.tracktimeeventarguments.html

    // use any Node.js 7 API, s. https://nodejs.org/
    const fs = require('fs');

    // use VSCode API, s. https://code.visualstudio.com/docs/extensionAPI/vscode-api
    const vscode = require('vscode');

    // access a module of that extension
    // s. https://github.com/mkloubert/vscode-kanban/blob/master/package.json
    const moment = args.require('moment');

    // options from the settings, s. below
    const OPTS = args.options;


    // start implement your workflow here
};

You also have to update the extension settings:

{
    "kanban": {
        "trackTime": {
            "type": "script",
            "options": {
                "MK": 239.79,
                "TM": "5979"
            }
        }
    }
}

Customization [↑]

CSS [↑]

If you want to style your board, you can create a file, called vscode-kanban.css, inside your .vscode sub folder of the underlying workspace or your home directory.

Have a look at the files board.css and style.css to get an idea of the CSS classes, that are used.

Support and contribute [↑]

If you like the extension, you can support the project by sending a donation via PayPal to me.

To contribute, you can open an issue and/or fork this repository.

To work with the code:

clone this repository
create and change to a new branch, like git checkout -b my_new_feature
run npm install from your project folder
open that project folder in Visual Studio Code
now you can edit and debug there
commit your changes to your new branch and sync it with your forked GitHub repo
make a pull request

The complete API documentation can be found here.

Related projects [↑]

vscode-helpers [↑]

vscode-helpers is a NPM module, which you can use in your own VSCode extension and contains a lot of helpful classes and functions.

davetheunissen/vscode-kanban