Reference

Every option the elevator extension accepts.

The complete elevator configuration: shortcode arguments, audio and keyboard attributes, the global switch, and what happens to Quarto’s own back-to-top button.

Shortcode

{{< elevator >}}
{{< elevator "<text>" <target> audio=... end=... volume=... loop-audio=... shortcut=... >}}

Positional arguments of the `elevator` shortcode.
Argument	Type	Required	Default	Description
`text`	string	No	`Return to the top!`	The button label.
`target`	string	No		The `id` of an element to ride to, instead of the top of the page. Written without the leading `#`.

The second argument is only read when the first is given, so a target needs an explicit label in front of it.

Attributes

Attributes of the `elevator` shortcode.
Attribute	Type	Default	Description
`audio`	path or name		Music played for the length of the ride.
`end`	path or name	`ding.mp3`	Sound played on arrival.
`volume`	number		Playback volume, from `0.0` to `1.0`. Applies to both sounds.
`loop-audio`	boolean	`true`	Whether `audio` repeats until the ride finishes.
`shortcut`	string		A single key that calls the elevator from anywhere on the page.

audio and end take a path relative to your document, or the built-in name ding, which resolves to the sound bundled with the extension.

A project has to copy the sound into its output itself. List it under resources in _quarto.yml, and put it in place before the render, or the page asks for a file the output does not carry. The bundled sound is registered while a page renders, which is after Quarto has resolved the project resources, so a resources entry alone finds nothing on a clean project. This site copies it in from a pre-render script. See Getting the sounds into the output.

The extension reads true, yes, 1, and on as true, and false, no, 0, and off as false. The schema accepts the words true and false in any case, so TRUE passes unreported, and the six other spellings are reported even though the extension honours them. Write true or false to keep the render quiet.

shortcut is matched against the browser’s KeyboardEvent.key, so t is a letter and Escape is a name. It is ignored while the focus is inside an input, textarea, or select, or any element with contenteditable, so it will not fire mid-sentence in a search box.

Configuration

extensions:
  elevator:
    enabled: false

Document and project options.
Option	Type	Default	Description
`enabled`	boolean	`true`	When `false`, every `elevator` shortcode in the document renders nothing.

Quarto’s own back-to-top button

Quarto draws its own back-to-top control when back-to-top-navigation is set. Where one is present, the extension takes it over as well: it removes the built-in click handler and wires the same elevator behaviour, audio included.

One shortcode is still needed on the page to load the script, but the button it produces can be left wherever it suits you.

Validation

Validation rules and what happens when a value fails them.
Rule	What is accepted	On failure
`volume`	A number from `0.0` to `1.0`.	A non-numeric value warns and is ignored. A number outside the range warns and is clamped.
`loop-audio`	The boolean spellings above.	A spelling the schema does not accept, such as `no`, is reported by the schema check and still honoured by the extension. A value neither knows falls back to `true`.
`audio`, `end`	Any path, or the name `ding`.	A path that does not resolve in the browser fails at playback, not at render.

Limitations

Caution

One button per page. Each shortcode emits a button carrying the same elevator-button class, and each script block wires the first one it finds. Two shortcodes on a page therefore give the first button two elevators and the second button none.

HTML formats carrying JavaScript only. Everywhere else the shortcode renders nothing.
Browsers block audio that starts without a user gesture, so the music depends on the ride beginning with a click. A ride triggered by shortcut alone, before any click on the page, may arrive in silence.
shortcut is bound once for each control on the page. Where Quarto’s own back-to-top pill is present, the key is bound twice, so one press starts two rides and plays the sounds twice.
Elevator.js keeps its audio in private variables, so volume and loop-audio are applied by wrapping the browser’s Audio constructor for the moment the elevator is built, then restoring it. This is why loop-audio=false works at all: the library’s own handling sets the loop attribute to the string "false", which a browser reads as true.