Colourised brackets

A line with several levels of nested brackets is hard to scan: every (, [ and { looks the same. The brackets attribute colours each bracket by how deep it is nested, cycling through three colours. A reader can then follow a pair by its colour.

Readers see

const title = document.title;
const slug = encodeURIComponent(
  kebab(trim(title.toLowerCase()))
);

You write

```js brackets
const title = document.title;
const slug = encodeURIComponent(
  kebab(trim(title.toLowerCase()))
);
```

The colour cycles every three levels, so the outermost call and the innermost call share a colour. Hover over a bracket to outline it and its partner, so you can tell the two pairs apart even when their colour repeats.

Syntax

Syntax	Where
brackets	Code block fence line
brackets=false	Code block fence line

Examples

Brackets inside a string

Brackets inside a string stay the normal string colour:

Output

const pattern = "(group)";

Source

```js brackets
const pattern = "(group)";
```

Behaviour

• Colours:
  • (), [] and {} cycle through three colours by nesting depth.
  • Brackets inside a string or a comment keep the normal syntax colour, so they do not compete with the real structure of the code.
  • A bracket with no partner, such as one from an incomplete example, keeps its normal colour.
• Matching pairs:
  • Hovering over a bracket outlines it and its matching partner with a solid line. The pair then stands out by shape, not only by colour.
  • Readers who use caret browsing (F7 in most browsers) get the same outline when the caret is on a bracket.
• Without JavaScript:
  • The colours work without JavaScript. The outline needs JavaScript, and does nothing without it.

Options

brackets

Colours matching brackets by nesting depth. Set it to false to turn the feature off.

Type

false | object

Default

On

brackets.languages

Languages that get colourised brackets in every block.

Type

string[]

Default

[]

A site that writes a lot of deeply nested JavaScript or JSON can turn colourised brackets on for those languages by default:

astro.config.mjs

codeblocks({
  brackets: { languages: ['js', 'json'] },
});

Each name also covers the other names of its language, so js also turns on the colours in javascript and mjs blocks.

To turn the colours off for one block of those languages, add brackets=false to its fence line. The fence line is the first line of the code block, with the language.

ConfigurationLearn how to set options for the whole site, or for a single code block.

Limitations

• On a short line with only one level of nesting, the colours add little. Use the attribute for lines that are hard to scan, or turn it on for a whole language with brackets.languages when it is usually dense.
• The plugin finds strings and comments with the comment syntax of the block’s language, not a full parser. A language with unusual string syntax can colour a bracket that is inside a string.

Related

• Focus: blur everything except the lines with the brackets you are explaining.
• Comment notation: the comment syntax map that colourised brackets reads to skip comments.