Syntax Highlighting

When enabled, BuJo parses the text written in Markdown files for specific regex patterns. These patterns are exposed as TextMate scopes to form a language grammar that can be used for syntax highlighting. At its core, BuJo uses the VS Code API for injecting a language grammar (i.e., see VS Code documentation for more details). This section of the guide provides information about the anatomy of a BuJo entry, as well as other components that are supported for syntax highlighting.

BuJo Entries

For each Bullet Journal entry, you can highlight four different tokens. Take, for example, the Bullet Journal entry below that constitutes a completed task:

- [x] Write BuJo readme file.

Notation

BuJo uses the notation [ ] to indicate that the text that follows is a Bullet Journal entry. The x in [x] represents the symbol that describes the type of Bullet Journal entry. The text that follows (i.e., Write BuJo readme file.) represents the entry's content.

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.

Symbols

Below is a list with the supported Bullet Journal symbols (i.e., more can be added upon request):

- [ ] 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 default colors and the Default Dark+ theme, the entries above are highlighted as follows:

The notation brackets [ and ] can be colored such that they are not visible, but will still remain present in the editor (e.g., [x]). This can be useful if one wants to make the notation brackets transparent to keep the entry clean and emphasize the content. For example:

Modifiers

BuJo also supports three Bullet Journal modifiers:

• ! - may indicate priority, inspiration, etc.
• ? - may indicate waiting for someone or something, unclear, etc.
• * - may indicate 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 upon request to support an arbitrary number of characters (i.e., including combinations of characters) as modifiers. BuJo provides flexibility for where a supported modifier can be placed. For example, all of the following are correctly identified and parsed as valid entries, as can be seen in the image below:

- [ ] ! Represents a task
- [ ]! Represents a task
- [ ] !Represents a task
- [ ]!Represents a task

Complex Entries

BuJo also provides syntax highlighting support for multiple entries on the same line separated by a pipe (i.e., |) character:

- [ ] Task one | [ ] ! Task two | [x] Task three
- [<] Task one | [-] ! Task two | [>] Task three

Experimental

The support for multiple BuJo entries on the line is experimental and may change in the future.

Metadata

BuJo entries may also contain inline metadata stored after the | character. For example, entries can contain wiki links or blockquote IDs (e.g., as used by Dendron and Foam):

- [ ] Represents a task | [[wiki.link]]
- [ ] Represents a task ^dzywxd9fvg
- [ ] Represents a task | [[wiki.link]] ^dzywxd9fvg

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.

Markdown Tables

BuJo also exposes scopes for targeting and highlighting grids in markdown tables (i.e., the :---:, :---, or ---: for horizontal grids, and the | for vertical grids). A separate scope is also provided for highlighting the : in in horizontal grids. The following screenshot shows the tokens that can highlighted:

With the default colors (i.e., and the Default Dark+ theme) the table grid can be faded way to be less obtrusive:

Time Tracking

BuJo also provides support for highlighting tasks in markdown tables, as well as well as associated time records (i.e., hh:mm-hh:mm):

Note. See section Time Tracking for how to easily add entries to the time tracking table and track the time spent on tasks.

Time Blocking

Similarly, BuJo it also supports time blocking syntax highlighting, based on the methodology discussed in Newport (2016).

Custom Colors

BuJo comes with default colors and styles 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.

Upon typing "editor.tokenColorCustomizations" you can trigger VS Code's intellisense which will automatically pre-fill the textMateRules array with the default colors provided by BuJo.

{
    // 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 brackets:

TIP

Check out the TextMate Scopes Reference for the complete list of tokens that can be targeted and colorized.