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 keyboard macro, you must set the experimental document attribute. Although this attribute is named experimental, the keyboard macro is considered a stable feature of the AsciiDoc language. The requirement to specify the attribute is merely an optimization for the processor.

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 proceeded 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

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab

|kbd:[Ctrl+Shift+N]
|New incognito window

|kbd:[\ ]
|Used to escape characters

|kbd:[Ctrl+\]]
|Jump to keyword

|kbd:[Ctrl + +]
|Increase zoom
|===

The result of Example 1 is displayed below.

Shortcut Purpose

F11

Toggle fullscreen

Ctrl+T

Open a new tab

Ctrl+Shift+N

New incognito window

\

Used to escape characters

Ctrl+]

Jump to keyword

Ctrl++

Increase zoom