Keyboard Macro

The keyboard macro allows to create a reference to a key or key sequence on a keyboard. You can use this macro when you need to communicate to a reader what key or key sequence to press to perform a function.

In order to use the UI macros, you must set the experimental document attribute. Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc language. The requirement to specify the attribute is merely an optimization for the processor. If the specification committee determines that an attribute is still necessary, the name of the attribute will likely change to better reflect that the macros are integral to the language.

Keyboard macro syntax

The keyboard macro uses the short (no target) macro syntax kbd:[key(+key)*]. Each key is displayed as entered in the document. Multiple keys are separated by a plus (e.g., Ctrl+T) or a comma (e.g., Ctrl,T). The plus is preferred.

It’s customary to represent alpha keys in uppercase, though this is not enforced.

If the last key is a backslash (\), it must be followed by a space. Without this space, the processor will not recognize the macro. If one of the keys is a closing square bracket (]), it must be preceded by a backslash. Without the backslash escape, the macro will end prematurely. You can find example of these cases in the example below.

Example 1. Using the keyboard macro syntax
|Shortcut |Purpose

|Toggle fullscreen

|Open a new tab

|New incognito window

|kbd:[\ ]
|Used to escape characters

|Jump to keyword

|kbd:[Ctrl + +]
|Increase zoom

The result of Example 1 is displayed below.

Shortcut Purpose


Toggle fullscreen


Open a new tab


New incognito window


Used to escape characters


Jump to keyword


Increase zoom