44. User Interface Macros

We are looking for feedback on these macros before setting them in stone. If you have suggestions, we want to hear from you!

You must set the experimental attribute to enable the UI macros.

44.1. Keyboard shortcuts

Asciidoctor recognizes a macro for creating keyboard shortcuts using the syntax kbd:[key(+key)*].

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
|===
Result: Keyboard macros displaying common browser keyboard shortcuts
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

You no longer have to struggle to explain to users what keys they are supposed to press.

Trying to explain to someone how to select a menu item can be a pain. With the menu macro, the symbols do the work.

Menu macro syntax
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

The instructions in the example above appear below.

Result: Menu macros displaying menu selections

To save the file, select File  Save.

Select View  Zoom  Reset to reset the zoom level to the default setting.

44.3. UI buttons

It can be equally difficult to communicate to the reader that they need to press a button. They can’t tell if you are saying “OK” or they are supposed to look for a button labeled OK. It’s all about getting the semantics right. The btn macro to the rescue!

Button macro syntax
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].
Result: Button macros displaying UI buttons

Press the OK button when you are finished.

Select a file in the file navigator and click Open.