Keyboard Keys

Documentation often needs to show keyboard shortcuts: “press Ctrl+S to save” or “hit Esc to close the dialog”. The {{< keys >}} shortcode renders these as styled key caps with a subtle 3D border effect, monospace font, and automatic dark-mode support.

It handles single keys, multi-key combos, and platform-aware rendering so that macOS readers see ⌘ while Windows readers see Ctrl.

Quick Start

Wrap a key name in the shortcode to render a styled key cap:

Press {{< keys "Esc" >}} to close.

Press Esc to close.

For a multi-key shortcut, use the shortcut parameter. Keys are split on + automatically:

{{< keys shortcut="Ctrl+Shift+P" >}}

Ctrl+Shift+P

Single Keys

The simplest usage is a single key name passed as a positional argument. This works for any key you might find on a keyboard: letters, numbers, function keys, navigation keys, and modifiers.

{{< keys "Enter" >}}
{{< keys "Tab" >}}
{{< keys "Space" >}}
{{< keys "F5" >}}
{{< keys "A" >}}

Enter Tab Space F5 A

Modifier keys render just like regular keys:

Ctrl Shift Alt

All keys share the same visual style: a rounded border, subtle shadow, and monospace font that mimics the appearance of physical key caps.

Shortcut Combos

Most keyboard shortcuts involve pressing multiple keys together. The shortcut parameter accepts a string like "Ctrl+Shift+P", splits it on +, and renders each key with a + separator between them:

{{< keys shortcut="Ctrl+C" >}}
{{< keys shortcut="Ctrl+Shift+P" >}}
{{< keys shortcut="Alt+F4" >}}

Ctrl+C

Ctrl+Shift+P

Alt+F4

Action Shortcut
Copy

Ctrl+C
Paste

Ctrl+V
Undo

Ctrl+Z
Save

Ctrl+S
Find

Ctrl+F
Command palette

Ctrl+Shift+P

You can also build combos manually by placing individual keys next to each other:

{{< keys "Ctrl" >}}+{{< keys "Shift" >}}+{{< keys "P" >}}

Ctrl+Shift+P

Both approaches are valid. Use shortcut= for convenience, or manual placement when you want different separators or spacing between keys.

Platform-Aware Rendering

Different operating systems use different key names. macOS has Command (⌘) and Option (⌥), while Windows uses Ctrl and Alt. The platform parameter translates key names so you can write platform-specific documentation without hard-coding symbols.

macOS

With platform="mac", standard modifier names are replaced with their macOS symbol equivalents. This is useful when writing documentation targeted at macOS users:

Key name macOS symbol
Ctrl ⌃ (⌃)
Cmd / Command ⌘ (⌘)
Alt / Option ⌥ (⌥)
Shift ⇧ (⇧)
Up / Down / Left / Right ▲ ▼ ◀ ▶ (▲▼◀▶)

A full shortcut with macOS rendering:

{{< keys shortcut="Cmd+Shift+P" platform="mac" >}}

⌘+⇧+P

The symbols are compact and universally recognized by macOS users, making them ideal for application-specific documentation.

Windows

With platform="win", macOS-specific key names are translated to their Windows equivalents. This lets you write a single shortcode and render it appropriately for Windows readers:

macOS key Windows key
Cmd Ctrl (Ctrl)
Option Alt (Alt) 
{{< keys shortcut="Cmd+S" platform="win" >}}

Ctrl+S

Keys that have no platform-specific equivalent (like letter keys and function keys) pass through unchanged.

Default (No Platform)

Without a platform parameter, key names are rendered exactly as written. This is the right choice when your audience uses multiple platforms or when the shortcut is platform-neutral:

Ctrl+Shift+P

For most documentation, leaving platform unset is the simplest and most portable option.

In Context

Keyboard keys work naturally in all common documentation contexts. The examples below show how {{< keys >}} integrates with prose, lists, callouts, and blockquotes.

Inline Prose

Keys blend seamlessly into running text without disrupting the reading flow:

To save your work, press Ctrl+S. If you need to undo, reach for Ctrl+Z. For more advanced operations, open the command palette with Ctrl+Shift+P.

This pattern works well in tutorials where you walk readers through a series of actions.

Lists

Shortcuts pair naturally with list items. Place the key combo first, followed by a description:

  • Ctrl+C Copy
  • Ctrl+V Paste
  • Ctrl+Z Undo
  • Ctrl+Y Redo
  • Ctrl+F Find

This layout makes it easy to scan a list of shortcuts at a glance.

Callouts

Callouts are a great way to highlight important shortcuts that readers should remember:

TipQuick Navigation

Press Ctrl+P to quickly open any file by name, or Ctrl+Shift+P to access the full command palette.

The styled key caps remain legible inside colored callout backgrounds.

Blockquotes

Keys also render correctly inside blockquotes:

Press Esc to close any dialog or cancel the current operation.

This is useful for quoting interface instructions or reproducing help text from an application.

Parameter Reference

The table below summarizes all available parameters for the {{< keys >}} shortcode.

Parameter Values Default Description
(positional) Any key name (none) Single key to render
shortcut Key combo string (none) Multi-key shortcut, split on +
platform mac, win (none) Translate keys for a specific OS

Either the positional argument or shortcut is required. The platform parameter is always optional.

Function Keys

Function keys (F1 through F20) receive a compact typographic treatment inspired by macOS menu glyphs. The text is rendered at x-height scale with slightly bolder weight, giving them a distinct look that sets them apart from regular keys:

F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12

Function keys work in combos too:

Ctrl+F5

Alt+F4

⌘+⇧+F12

The compact styling is applied automatically and is not platform-specific.

Dark Mode

Key caps automatically adapt in dark mode. The background shifts to a dark gradient, borders become more subtle, and text brightens for readability. No extra configuration is needed; the shortcode works identically in both light and dark themes.

Copy/Paste Friendly

Rendered shortcuts are plain text under the hood, so copying them from the page preserves the readable key names and separators. For example, copying a macOS shortcut like ⌘+⇧+P produces ⌘+⇧+P in the clipboard. This makes it easy for readers to paste shortcuts into notes, chat messages, or other documents without losing meaning.

Symbol Tooltips

When platform-aware rendering produces macOS symbols, each key cap includes a title attribute with the full key name. Hovering over ⌘ shows “Command”, ⌥ shows “Option”, and so on. This helps readers who may not recognize every symbol at a glance.

Comparison with Quarto’s Built-In kbd

Quarto ships with its own {{< kbd >}} shortcode (documentation) that renders keyboard shortcuts as plain text. It supports per-OS keyword arguments (mac=, win=, linux=) and auto-detects the reader’s operating system in HTML output:

{{< kbd Shift-Ctrl-P >}}
{{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}

The Great Docs {{< keys >}} shortcode differs in three ways:

  1. Visual styling. Keys render as styled caps with a 3D border, gradient background, and monospace font rather than plain text.
  2. Symbol translation. With platform="mac", modifier names are replaced by their macOS symbols (⌘, ⌥, ⇧, ⌃) rather than spelled out.
  3. Separator rendering. Combo keys are joined by a styled + separator element.

Choose {{< kbd >}} when you want minimal, format-agnostic output that works in PDF, DOCX, and other non-HTML targets. Choose {{< keys >}} when you are authoring HTML documentation and want visually distinct key-cap styling that matches the Great Docs design system.

Next Steps

The keyboard keys shortcode renders key combinations as styled caps that match the Great Docs design system. Use it in tutorials, shortcut references, or anywhere you describe keyboard interactions.