BuJo is an extension that adds syntax highlighting for Bullet Journal items (e.g., tasks) in Markdown. It works by parsing the text written in Markdown files for specific patterns and highlighting the matches. At its core, BuJo uses the VS Code API for injecting language grammars (i.e., see VS Code documentation for more details).
BuJo provides highlighting for the standard Bullet Journal symbols (i.e., see Carroll, 2018). It also provides an way to select and colorize markdown table lines, as well as tasks in tables (i.e., see below).
For each Bullet Journal entry, you can highlight four different tokens. Take, for example, the Bullet Journal entry below:
[x] Write BuJo readme file.
BuJo uses the notation [
]
to indicate that the text that follows
is a Bullet Journal entry. The x
inside [
]
represents the symbol
that describes the type of Bullet Journal entry. The text that follows
(i.e., Write BuJo readme file.
) represents the content of the entry.
Aside from the notation, symbol, and text, you may also use a
modifier. For example, you can use the !
modifier after [x]
to
indicate a sense of priority:
[x] ! Write BuJo readme file.
Below is a list with the supported Bullet Journal symbols:
- [ ] Represents a task.
- [x] Represents a completed task.
- [>] Represents a task migrated forward.
- [>] Represents a task migrated backward.
- [/] Represents a task in progress.
- [-] Represents a dropped task.
- [o] Represents an event.
- Represents a note. Nothing special about it.
With the BuJo colors suggested below and the default Dark+ theme, the entries above are highlighted as follows:
Note that the notation brackets []
can be colored such that they are not
visible, but will still present (e.g., [x]
). This might be useful if one wants
to make the notation brackets transparent to keep the entry clean and emphasize
the content. For instance:
BuJo supports three Bullet Journal modifiers:
! indicates, e.g., priority, inspiration, etc.
? indicates, e.g., waiting for someone or something, unclear, etc.
* indicates, e.g., something special about the entry, etc.
These modifiers can be combined with any of the supported Bullet Journal symbols. For example:
BuJo can easily be extended to support an arbitrary number of characters (i.e., including combinations of characters) as modifiers.
BuJo entries can also contain wiki links or blockquote IDs (e.g., see Dendron or Foam for an awesome way to turn VS Code into a full-fledge personal knowledge management and productivity system) as below.
- [ ] Represents a task | [[wiki.link]]
- [ ] Represents a task ^dzywxpxd9fvg
- [ ] Represents a task | [[wiki.link]] ^dzywxpxd9fvg
The lines above will be parsed in such a way that the wiki link and the block quote IDs at the end of the line are omitted.
BuJo also exposes scopes for targeting and highlighting grids in markdown
tables (i.e., the :---:
, :---
, or ---:
for horizontal grid, and the |
for vertical grid). A separate scope is also provided for highlighting the :
in an horizontal grid. The following picture demonstrates the tokens
highlighting:
With the default colors suggested below the table grid can be faded way to be less obtrusive:
BuJo also provides support for highlighting tasks in markdown tables, as well as well as time records:
Similarly, it also supports time blocking highlighting:
See the section Exposed TextMate scopes for a list of all exposed scopes that can be targeted and highlighted.
BuJo comes with default colors for the TextMate scopes it exposes. These
colors and styles are chosen to work well with the default Dark+ theme.
However, they can be customized via the editor.tokenColorCustomizations
setting in VS Code below.
{
// Other VS Code settings.
"editor.tokenColorCustomizations": {
// Override only for the `Default Dark+` theme.
"[Default Dark+]": {
"textMateRules": [
// The scopes for which we want to provide custom colors.
]
}
}
}
For example, to colorize the notation brackets [
and ]
for a task [x]
, you
can use:
{
// Other VS Code settings.
"editor.tokenColorCustomizations": {
// Override only for the `Default Dark+` theme.
"[*Dark*]": {
"textMateRules": [
{
"scope": "bujo.task.completed.notation",
"settings": {
"foreground": "#FFB6C1",
"fontStyle": "bold underline"
}
}
]
}
}
}
When the theme Default Dark+
is used, the above override will result in a
completed task with bolded, underlined, and pink notation:
See the section Exposed TextMate scopes below for a complete overview
of the scopes that can be customized via the editor.tokenColorCustomizations"
setting.
Below are the TextMate scopes targeted in the VS Code settings for color customizations.
bujo.task.open.notation
: targets the left[
and the right]
brackets only when they contain a space in-betweenbujo.task.open.symbol
: targets the space between the notation brackets[
and]
bujo.task.open.modifier
: targets any supported modifier that follows after[ ]
bujo.task.open.text
: targets the text that follows[ ]
without a modifier, e.g.,[ ]
This is targeted.
bujo.task.open.text.modifier
: targets the text that follows[ ]
with a modifier, e.g.,[ ] !
This is targeted.
bujo.task.completed.notation
: targets the left[
and the right]
brackets only when they containx
in-betweenbujo.task.completed.symbol
: targets the symbolx
between the notation brackets[
and]
bujo.task.completed.modifier
: targets any supported modifier that follows after[x]
bujo.task.completed.text
: targets the text that follows[x]
without a modifier, e.g.,[x]
This is targeted.
bujo.task.completed.text.modifier
: targets the text that follows[x]
with a modifier, e.g.,[x] !
This is targeted.
bujo.task.in.progress.notation
: targets the left[
and the right]
brackets only when they contain/
in-betweenbujo.task.in.progress.symbol
: targets the symbol/
between the notation brackets[
and]
bujo.task.in.progress.modifier
: targets any supported modifier that follows after[/]
bujo.task.in.progress.text
: targets the text that follows[/]
without a modifier, e.g.,[/]
This is targeted.
bujo.task.in.progress.text.modifier
: targets the text that follows[/]
with a modifier, e.g.,[/] !
This is targeted.
bujo.task.migrated.forward.notation
: targets the left[
and the right]
brackets only when they contain>
in-betweenbujo.task.migrated.forward.symbol
: targets the symbol>
between the notation brackets[
and]
bujo.task.migrated.forward.modifier
: targets any supported modifier that follows after[>]
bujo.task.migrated.forward.text
: targets the text that follows[>]
without a modifier, e.g.,[>]
This is targeted.
bujo.task.migrated.forward.text.modifier
: targets the text that follows[>]
with a modifier, e.g.,[>] !
This is targeted.
bujo.task.migrated.forward.notation
: targets the left[
and the right]
brackets only when they contain<
in-betweenbujo.task.migrated.forward.symbol
: targets the symbol<
between the notation brackets[
and]
bujo.task.migrated.forward.modifier
: targets any supported modifier that follows after[<]
bujo.task.migrated.forward.text
: targets the text that follows[<]
without a modifier, e.g.,[<]
This is targeted.
bujo.task.migrated.forward.text.modifier
: targets the text that follows[<]
with a modifier, e.g.,[<] !
This is targeted.
bujo.task.dropped.notation
: targets the left[
and the right]
brackets only when they contain-
in-betweenbujo.task.dropped.symbol
: targets the symbol-
between the notation brackets[
and]
bujo.task.dropped.modifier
: targets any supported modifier that follows after[-]
bujo.task.dropped.text
: targets the text that follows[-]
without a modifier, e.g.,[-]
This is targeted.
bujo.task.dropped.text.modifier
: targets the text that follows[-]
with a modifier, e.g.,[-] !
This is targeted.
bujo.task.event.notation
: targets the left[
and the right]
brackets only when they containo
in-betweenbujo.task.event.symbol
: targets the symbolo
between the notation brackets[
and]
bujo.task.event.modifier
: targets any supported modifier that follows after[o]
bujo.task.event.text
: targets the text that follows[o]
without a modifier, e.g.,[o]
This is targeted.
bujo.task.event.text.modifier
: targets the text that follows[o]
with a modifier, e.g.,[o] !
This is targeted.
bujo.grid.horizontal
: targets the:---:
,:---
, or---:
horizontal grids in tablesbujo.grid.colon
: targets the:
in horizontal gridsbujo.grid.vertical
: target the|
vertical grids in tables
bujo.todo.start.hour
: targets, e.g.,08
in08:10-09:20
inside a table rowbujo.todo.start.colon
: targets, e.g., the:
after08
in08:10-09:20
inside a table rowbujo.todo.start.minute
: targets, e.g.,10
in08:10-09:20
inside a table rowbujo.todo.separator
: targets, e.g.,-
in08:10-09:20
inside a table rowbujo.todo.end.hour
: targets, e.g.,09
in08:10-09:20
inside a table rowbujo.todo.end.colon
: targets, e.g., the:
after09
in08:10-09:20
inside a table rowbujo.todo.end.minute
: targets, e.g.,20
in08:10-09:20
inside a table rowbujo.todo.total
: targets the total time spent, e.g.,98m
in a table row
bujo.timeblock.revision.time.parenthesis.open
: targets, e.g.,(
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.revision.time.hour
: targets, e.g.,07
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.revision.time.colon
: targets, e.g.,:
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.revision.time.minute
: targets, e.g.,40
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.revision.time.parenthesis.close
: targets, e.g.,)
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.revision.text
: targets, e.g.,(Revision #1)
in| (07:40) | (Revision #1) |
inside a table rowbujo.timeblock.chunk.title
: targets, e.g.,Deep work (#1)
in| 08:00-10:00 | Deep work (#1) |
in a table rowbujo.timeblock.chunk.note
: targets, e.g.,- Random meeting
in| | - Random meeting |
in a table row
In case you experience issues, the regular expressions used for capturing the scopes above can be consulted at:
See the CHANGELOG file.
Foam is licensed under the MIT license.
- Carroll, R. (2018). The bullet journal method: Track the past, order the present, design the future. Penguin.