UI Macros and Icons

Displaying Keyboard Shortcuts

For software documentation, AsciiDoc offers special macros to display user interface elements consistently.

The keyboard macro displays keyboard shortcuts:

Save with kbd:[⌘+S] or kbd:[Ctrl+S].
Press kbd:[Enter] to confirm.

Result: Save with ⌘+S or Ctrl+S. Press Enter to confirm.

Multiple keys are connected with +:

kbd:[Ctrl+Alt+Delete]
kbd:[⌘+Shift+P]

Buttons and Menus

The button macro displays buttons:

Click btn:[OK] to continue.
Select btn:[Cancel] to abort the process.

Result: Click OK to continue.

The menu macro displays menu paths:

Select menu:File[Save As...].
Open menu:Edit[Preferences > General].

Result: Select File  Save As…​.

Submenus are separated with > within the square brackets.

Inserting Icons

With the icon macro, you insert icons into your text:

icon:heart[] Like
icon:check[] Done
icon:warning[] Attention

For icons to be displayed, :icons: font must be in the document header.

Icons can also be customized:

icon:heart[size=2x]           // Double size
icon:spinner[spin]            // Animated
icon:arrow-right[rotate=90]   // Rotated
adoc Studio uses Font Awesome Icons by default. With set=, you can also switch between SF Symbols and Font Awesome within a document.

Icon Sets: SF Symbols and Font Awesome

In addition to Font Awesome, you can also use Apple’s SF Symbols – the collection of all symbols from Apple operating systems with over 6,000 icons.

Activate SF Symbols with these attributes in the document header:

:icons: font
:icon-set: apple

Insert icons with the macro . The adoc Coach suggests suitable icons while you type.

Available parameters for SF Symbols:

icon:rainbow[palette=multicolor]
icon:arrow.right.circle.fill[palette=hierarchical, role=green]
icon:cloud.drizzle.fill[flip=vertical]
icon:view.2d[rotate=90, role=red]
icon:01.circle[weight=ultralight]
icon:01.circle[weight=black]

The most important parameters at a glance:

  • flip=horizontal or flip=vertical – Mirror the icon

  • palette=monochrome|hierarchical|multicolor – Color variants

  • role=blue – Color adjustment

  • rotate=90|180|270 – Rotation

  • size=1x|…​|7x or simply [2x] – Size

  • weight=ultralight|…​|black – Stroke weight

  • set=apple|far|fab|fas – Switch between icon sets

UI macros make your documentation more consistent and easier to understand – especially for guides and tutorials.