From 492994585a35e029117d75fcecda1a7632fc71df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Thu, 28 May 2026 23:02:18 +0200
Subject: [PATCH 1/5] feat: bump to v1.5.0 with review fixes and new options

Address the v1.4.0 monorepo review findings and ship the requested
enhancements as a single v1.5.0 release.

Bug fixes
- JavaScript-escape anchor IDs and audio paths via a new
  escape_js_string helper so values containing backslashes, quotes,
  newlines, or </ cannot break out of the inline <script> tag.
- Warn (once per render) when the bundled default ding.mp3 cannot be
  located alongside the extension.
- HTML-escape the button text so markup in the text argument is
  rendered as plain text.

New features
- volume attribute clamped to [0.0, 1.0] with a warning on
  out-of-range or non-numeric input.
- loop-audio attribute that genuinely disables looping by wrapping
  window.Audio around Elevator.js construction.
- Built-in named sounds: audio=ding and end=ding resolve to the
  bundled ding.mp3.
- shortcut attribute binding a single KeyboardEvent.key value,
  ignored inside form fields and contenteditable elements.
- Document-level disable via elevator: false (or
  elevator: { enabled: false }) in YAML metadata.

Docs and scaffolding
- Document the new attributes, named sounds, and global disable in
  README.md, example.qmd, _schema.yml, and _snippets.json.
- Fix the BossaBossa.mp3 link in README.md (file ships at repo root).
- Ship _modules/logging.lua and sync module headers with the
  canonical style.
---
 CHANGELOG.md                              |  25 ++
 README.md                                 |  68 +++-
 _extensions/elevator/_extension.yml       |   2 +-
 _extensions/elevator/_modules/html.lua    |   2 +-
 _extensions/elevator/_modules/logging.lua |  62 ++++
 _extensions/elevator/_modules/string.lua  |  23 +-
 _extensions/elevator/_schema.yml          |  26 +-
 _extensions/elevator/_snippets.json       |  15 +
 _extensions/elevator/elevator.lua         | 418 ++++++++++++++++++----
 example.qmd                               |  28 +-
 10 files changed, 575 insertions(+), 94 deletions(-)
 create mode 100644 _extensions/elevator/_modules/logging.lua

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1580c4..7e36bf6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 1.5.0 (2026-05-28)
+
+### Bug Fixes
+
+- fix: JavaScript-escape anchor IDs and audio paths so values containing `"`, `\`, `<`, or newlines no longer break the generated init script.
+- fix: Warn (once per render) when the bundled default `ding.mp3` cannot be located alongside the extension.
+- fix: HTML-escape the button text so markup in the `text` argument is rendered as plain text rather than dropped or interpreted.
+
+### New Features
+
+- feat: Add `volume` attribute that clamps to the range [0.0, 1.0] and warns on out-of-range or non-numeric input.
+- feat: Add `loop-audio` attribute that genuinely disables looping (works around Elevator.js's `setAttribute('loop', 'false')` no-op).
+- feat: Add built-in named sounds. `audio=ding` and `end=ding` resolve to the bundled `ding.mp3`.
+- feat: Add `shortcut` attribute to trigger the elevator from anywhere outside form fields via a keyboard key.
+- feat: Add document-level disable via `elevator: false` (or `elevator: { enabled: false }`) in YAML metadata.
+
+### Documentation
+
+- docs: Document new attributes (`volume`, `loop-audio`, `shortcut`), built-in sounds, and global disable in `README.md`, `example.qmd`, `_schema.yml`, and `_snippets.json`.
+
+### Refactoring
+
+- refactor: Add `escape_js_string` helper to the shared `_modules/string.lua` module.
+- refactor: Sync `_modules/` doc-style metadata with the canonical module headers and ship `_modules/logging.lua` alongside `string.lua` and `html.lua`.
+
 ## 1.4.0 (2026-03-23)
 
 ### Refactoring
diff --git a/README.md b/README.md
index 9f85ecb..2d437c0 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Animation is only available for HTML-based documents.
 ## Installation
 
 ```sh
-quarto add mcanouil/quarto-elevator@1.4.0
+quarto add mcanouil/quarto-elevator@1.5.0
 ```
 
 This will install the extension under the `_extensions` subdirectory.
@@ -16,19 +16,65 @@ If you're using version control, you will want to check in this directory.
 
 ## Usage
 
-To add an elevator button, use the `{{< elevator >}}` shortcode. For example:
+To add an elevator button, use the `{{< elevator >}}` shortcode.
 
-- Mandatory:
+### Minimal
 
-  ```markdown
-  {{< elevator >}}
-  ```
+```markdown
+{{< elevator >}}
+```
+
+### Custom text and scroll target
+
+The first positional argument is the button label and the second is the id of an element to scroll to instead of the top of the page.
+
+```markdown
+{{< elevator "Back to header" my-header >}}
+```
+
+### Audio
+
+`audio` is the looping music played during the scroll and `end` is the sound played once the scroll finishes.
+
+```markdown
+{{< elevator audio=music.mp3 end=ding.mp3 >}}
+```
+
+The built-in name `ding` resolves to the bundled `ding.mp3`, so `audio=ding` or `end=ding` works without copying the file into your project.
+
+### Volume
+
+`volume` accepts a number in the range [0.0, 1.0]. Out-of-range or non-numeric values are clamped and a warning is emitted at render time.
+
+```markdown
+{{< elevator audio=music.mp3 volume=0.5 >}}
+```
+
+### Loop control
 
-- Optional `<text-button>`, `<anchor-target>`, and `<audio=audio.mp3>`:
+`loop-audio` defaults to `true` (Elevator.js's own default). Set it to `false` to play the main audio just once. The extension overrides Elevator.js's internal `setAttribute('loop', 'false')` no-op so this option actually disables looping.
+
+```markdown
+{{< elevator audio=music.mp3 loop-audio=false >}}
+```
 
-  ```markdown
-  {{< elevator <text-button> <anchor-target> <audio=audio.mp3> >}}
-  ```
+### Keyboard shortcut
+
+`shortcut` binds a single key (matched against `KeyboardEvent.key`) that triggers the elevator from anywhere on the page, except when the focus is inside an `<input>`, `<textarea>`, `<select>`, or any `contenteditable` element.
+
+```markdown
+{{< elevator audio=music.mp3 shortcut="t" >}}
+```
+
+### Global disable
+
+Set `elevator: false` (or `elevator: { enabled: false }`) in the document YAML to suppress every `{{< elevator >}}` shortcode in that document.
+
+```yaml
+---
+elevator: false
+---
+```
 
 ## Example
 
@@ -40,7 +86,7 @@ Output of `example.qmd`:
 
 ---
 
-[BossaBossa](_extensions/elevator/BossaBossa.mp3) by Kevin MacLeod | <https://incompetech.com/>.  
+[BossaBossa](BossaBossa.mp3) by Kevin MacLeod | <https://incompetech.com/>.
 Music promoted by <https://www.chosic.com/free-music/all/>.
 Creative Commons Creative Commons: By Attribution 3.0 License (<http://creativecommons.org/licenses/by/3.0/>).
 
diff --git a/_extensions/elevator/_extension.yml b/_extensions/elevator/_extension.yml
index fb12943..2570026 100644
--- a/_extensions/elevator/_extension.yml
+++ b/_extensions/elevator/_extension.yml
@@ -1,6 +1,6 @@
 title: Elevator.js
 author: Mickaël Canouil
-version: 1.4.0
+version: 1.5.0
 quarto-required: ">=1.2.280"
 contributes:
   shortcodes:
diff --git a/_extensions/elevator/_modules/html.lua b/_extensions/elevator/_modules/html.lua
index e022cef..8212cc5 100644
--- a/_extensions/elevator/_modules/html.lua
+++ b/_extensions/elevator/_modules/html.lua
@@ -1,5 +1,5 @@
 --- MC HTML - HTML generation and dependency management for Quarto Lua filters and shortcodes
---- @module html
+--- @module "html"
 --- @license MIT
 --- @copyright 2026 Mickaël Canouil
 --- @author Mickaël Canouil
diff --git a/_extensions/elevator/_modules/logging.lua b/_extensions/elevator/_modules/logging.lua
new file mode 100644
index 0000000..a538809
--- /dev/null
+++ b/_extensions/elevator/_modules/logging.lua
@@ -0,0 +1,62 @@
+--- MC Logging - Formatted log output for Quarto Lua filters and shortcodes
+--- @module "logging"
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+-- ============================================================================
+-- LOGGING UTILITIES
+-- ============================================================================
+
+--- Format and log an error message with extension prefix.
+--- Provides standardised error messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "external", "lua-env")
+--- @param message string The error message to display
+--- @usage M.log_error("external", "Could not open file 'example.md'.")
+function M.log_error(extension_name, message)
+  quarto.log.error('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log a warning message with extension prefix.
+--- Provides standardised warning messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "external", "lua-env")
+--- @param message string The warning message to display
+--- @usage M.log_warning("lua-env", "No variable name provided.")
+function M.log_warning(extension_name, message)
+  quarto.log.warning('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log an output message with extension prefix.
+--- Provides standardised informational messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "lua-env")
+--- @param message string The informational message to display
+--- @usage M.log_output("lua-env", "Exported metadata to: output.json")
+function M.log_output(extension_name, message)
+  quarto.log.output('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log a debug message with extension prefix.
+--- Provides standardised debug messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "lua-env")
+--- @param message string The debug message to display
+--- @usage M.log_debug("lua-env", "Variable 'x' has value: 42")
+function M.log_debug(extension_name, message)
+  quarto.log.debug('[' .. extension_name .. '] ' .. message)
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M
diff --git a/_extensions/elevator/_modules/string.lua b/_extensions/elevator/_modules/string.lua
index e711a00..b1f8d91 100644
--- a/_extensions/elevator/_modules/string.lua
+++ b/_extensions/elevator/_modules/string.lua
@@ -1,5 +1,5 @@
 --- MC String - String manipulation and escaping for Quarto Lua filters and shortcodes
---- @module string
+--- @module "string"
 --- @license MIT
 --- @copyright 2026 Mickaël Canouil
 --- @author Mickaël Canouil
@@ -112,6 +112,27 @@ function M.escape_typst_string(text)
   return text:gsub('\\', '\\\\'):gsub('"', '\\"')
 end
 
+--- Escape characters for JavaScript string literals (inside `"..."` or `'...'`).
+--- Handles backslash, both quote styles, newlines, carriage returns, tabs,
+--- form feeds, and the `</` sequence so payloads cannot break out of a
+--- surrounding inline `<script>` block.
+--- @param text string|nil The text to escape
+--- @return string The escaped text safe for JavaScript string literals
+--- @usage local safe = M.escape_js_string([[a "b" </script>]])
+function M.escape_js_string(text)
+  if text == nil then return '' end
+  if type(text) ~= 'string' then text = tostring(text) end
+  return text
+      :gsub('\\', '\\\\')
+      :gsub('"', '\\"')
+      :gsub("'", "\\'")
+      :gsub('\n', '\\n')
+      :gsub('\r', '\\r')
+      :gsub('\t', '\\t')
+      :gsub('\f', '\\f')
+      :gsub('</', '<\\/')
+end
+
 --- Escape special Lua pattern characters for use in string.gsub.
 --- @param text string The text containing characters to escape
 --- @return string The escaped text safe for Lua patterns
diff --git a/_extensions/elevator/_schema.yml b/_extensions/elevator/_schema.yml
index 0cb1092..218b1e4 100644
--- a/_extensions/elevator/_schema.yml
+++ b/_extensions/elevator/_schema.yml
@@ -20,7 +20,7 @@ shortcodes:
     attributes:
       audio:
         type: string
-        description: "Path to the main audio file played during the scroll animation."
+        description: "Path to the main audio file played during the scroll animation. The built-in name 'ding' resolves to the bundled ding.mp3."
         completion:
           type: file
           extensions:
@@ -30,10 +30,32 @@ shortcodes:
       end:
         type: string
         default: "ding.mp3"
-        description: "Path to the audio file played when the scroll completes."
+        description: "Path to the audio file played when the scroll completes. The built-in name 'ding' resolves to the bundled ding.mp3."
         completion:
           type: file
           extensions:
             - .mp3
             - .ogg
             - .wav
+      volume:
+        type: number
+        description: "Playback volume in the range [0.0, 1.0]. Values outside the range are clamped and a warning is emitted."
+        minimum: 0.0
+        maximum: 1.0
+      loop-audio:
+        type: boolean
+        default: true
+        description: "Whether the main audio loops while scrolling. Set to false to play the audio only once."
+      shortcut:
+        type: string
+        description: "Optional keyboard key (matched against KeyboardEvent.key) that triggers the elevator from anywhere outside form fields. Examples: 't', 'Escape'."
+
+metadata:
+  elevator:
+    type: ["boolean", "object"]
+    description: "Set to false to disable every {{< elevator >}} shortcode in the document. Accepts an object with an 'enabled' boolean as an alternative."
+    properties:
+      enabled:
+        type: boolean
+        default: true
+        description: "Whether {{< elevator >}} shortcodes render anything. Defaults to true."
diff --git a/_extensions/elevator/_snippets.json b/_extensions/elevator/_snippets.json
index 0fafd40..2b7da08 100644
--- a/_extensions/elevator/_snippets.json
+++ b/_extensions/elevator/_snippets.json
@@ -3,5 +3,20 @@
 		"prefix": "elevator",
 		"body": "{{< elevator \"${1:Back to top}\" >}}",
 		"description": "Insert an elevator (back to top) shortcode"
+	},
+	"Elevator shortcode with audio": {
+		"prefix": "elevator-audio",
+		"body": "{{< elevator \"${1:Back to top}\" audio=\"${2:music.mp3}\" >}}",
+		"description": "Insert an elevator shortcode with main audio"
+	},
+	"Elevator shortcode with target": {
+		"prefix": "elevator-target",
+		"body": "{{< elevator \"${1:Go up}\" \"${2:target-id}\" >}}",
+		"description": "Insert an elevator shortcode scrolling to a target id"
+	},
+	"Elevator shortcode with volume and shortcut": {
+		"prefix": "elevator-full",
+		"body": "{{< elevator \"${1:Back to top}\" audio=\"${2:music.mp3}\" volume=${3:0.5} loop-audio=${4:true} shortcut=\"${5:t}\" >}}",
+		"description": "Insert an elevator shortcode with volume, loop, and keyboard shortcut"
 	}
 }
diff --git a/_extensions/elevator/elevator.lua b/_extensions/elevator/elevator.lua
index 674c243..ba2dc19 100644
--- a/_extensions/elevator/elevator.lua
+++ b/_extensions/elevator/elevator.lua
@@ -1,4 +1,4 @@
---- @module elevator
+--- @module "elevator"
 --- @license MIT
 --- @copyright 2026 Mickaël Canouil
 --- @author Mickaël Canouil
@@ -6,92 +6,360 @@
 --- Load modules
 local str = require(quarto.utils.resolve_path('_modules/string.lua'):gsub('%.lua$', ''))
 local html_mod = require(quarto.utils.resolve_path('_modules/html.lua'):gsub('%.lua$', ''))
+local log = require(quarto.utils.resolve_path('_modules/logging.lua'):gsub('%.lua$', ''))
+
+--- Extension name used as a prefix for log messages.
+--- @type string
+local EXTENSION = 'elevator'
+
+--- Default end-of-scroll audio file shipped with the extension.
+--- @type string
+local DEFAULT_END_AUDIO = 'ding.mp3'
+
+--- Built-in named sound aliases mapped to their bundled audio paths.
+--- Keys are user-facing names; values are filenames bundled with the extension.
+--- @type table<string, string>
+local NAMED_SOUNDS = {
+  ding = 'ding.mp3',
+}
+
+--- Module-level guard preventing the default audio resource from being added
+--- more than once per Quarto render (one process can host several shortcodes).
+--- @type boolean
+local default_audio_registered = false
+
+--- Module-level guard ensuring the missing-default warning fires at most once
+--- per Quarto render to avoid log spam when the shortcode is used repeatedly.
+--- @type boolean
+local missing_default_warned = false
+
+--- Module-level cache for the document-level `elevator: false` opt-out.
+--- `nil` means "not yet inspected"; `true`/`false` mean the metadata has been
+--- read and the result is recorded.
+--- @type boolean|nil
+local globally_disabled = nil
+
+--- Parse a value into a boolean.
+--- Accepts native booleans plus the case-insensitive strings `true`, `yes`,
+--- `1`, `on` (truthy) and `false`, `no`, `0`, `off` (falsy).
+--- @param value any The value to parse
+--- @param default boolean Fallback when the value is missing or unrecognised
+--- @return boolean
+local function parse_boolean(value, default)
+  if value == nil then return default end
+  if type(value) == 'boolean' then return value end
+  local text = str.stringify(value)
+  if str.is_empty(text) then return default end
+  text = text:lower()
+  if text == 'true' or text == 'yes' or text == '1' or text == 'on' then
+    return true
+  end
+  if text == 'false' or text == 'no' or text == '0' or text == 'off' then
+    return false
+  end
+  return default
+end
+
+--- Resolve an audio reference, expanding built-in named sounds to their
+--- bundled filenames. Empty input returns an empty string.
+--- @param reference string The raw audio value supplied by the user
+--- @return string Resolved audio path (possibly the original value)
+local function resolve_audio(reference)
+  if str.is_empty(reference) then return '' end
+  local key = reference:lower()
+  local bundled = NAMED_SOUNDS[key]
+  if bundled then
+    quarto.doc.add_format_resource(bundled)
+    return bundled
+  end
+  return reference
+end
+
+--- Validate and clamp a volume value to the range supported by HTMLAudioElement.
+--- Emits a warning when the input is non-numeric or out of bounds.
+--- @param raw_value string The raw user input
+--- @return number|nil Clamped volume in [0.0, 1.0] or nil when not supplied
+local function parse_volume(raw_value)
+  if str.is_empty(raw_value) then return nil end
+  local number = tonumber(raw_value)
+  if not number then
+    log.log_warning(EXTENSION, "Ignoring non-numeric volume '" .. raw_value .. "'.")
+    return nil
+  end
+  if number < 0 or number > 1 then
+    log.log_warning(
+      EXTENSION,
+      "Volume '" .. raw_value .. "' out of range [0.0, 1.0]; clamping."
+    )
+    if number < 0 then number = 0 end
+    if number > 1 then number = 1 end
+  end
+  return number
+end
+
+--- Determine whether the document opts out of the elevator entirely via the
+--- top-level `elevator: false` metadata flag. The result is cached per
+--- document; pass the `meta` table supplied to the shortcode handler.
+--- @param meta table|nil The document metadata passed by Quarto
+--- @return boolean True when the shortcode should render nothing
+local function is_globally_disabled(meta)
+  if globally_disabled ~= nil then return globally_disabled end
+  if meta and meta.elevator ~= nil then
+    -- Accept both `elevator: false` and `elevator: { enabled: false }`.
+    if type(meta.elevator) == 'table' and meta.elevator.enabled ~= nil then
+      globally_disabled = not parse_boolean(meta.elevator.enabled, true)
+    else
+      globally_disabled = not parse_boolean(meta.elevator, true)
+    end
+  else
+    globally_disabled = false
+  end
+  return globally_disabled
+end
+
+--- Warn (once per render) when the default `ding.mp3` resource cannot be
+--- located alongside this Lua filter. Returns the resolved path on success.
+--- @return string|nil The resolved path to the default audio, or nil when missing
+local function ensure_default_audio()
+  local resolved = quarto.utils.resolve_path(DEFAULT_END_AUDIO)
+  -- `resolve_path` returns a path even when the file does not exist, so probe
+  -- the filesystem to confirm the resource ships with the extension.
+  local handle = io.open(resolved, 'rb')
+  if handle then
+    handle:close()
+    return resolved
+  end
+  if not missing_default_warned then
+    log.log_warning(
+      EXTENSION,
+      "Default audio '" .. DEFAULT_END_AUDIO ..
+      "' was not found alongside the extension; no end-of-scroll sound will play."
+    )
+    missing_default_warned = true
+  end
+  return nil
+end
+
+--- Build the JavaScript snippet wiring one DOM selector to an Elevator
+--- instance. All option fragments are passed pre-serialised so the caller
+--- controls escaping; this helper only stitches the pieces together. Each
+--- block is wrapped in its own IIFE so the local `instance` variable does
+--- not collide with sibling blocks (`var` is function-scoped in JS).
+--- @param selector_js string JavaScript expression returning the element
+--- @param target_js string `targetElement: ...,` snippet (may be empty)
+--- @param main_audio_js string `mainAudio: "...",` snippet (may be empty)
+--- @param end_audio_js string `endAudio: "...",` snippet (may be empty)
+--- @param loop_audio_js string `loopAudio: true|false,` snippet (may be empty)
+--- @param volume_pre_js string `window.Audio` wrap installed before construction
+--- @param volume_post_js string `window.Audio` restore installed after construction
+--- @param shortcut_js string Keyboard-shortcut wiring (may be empty)
+--- @param missing_label string Human-readable label used in `not found` logs
+--- @return string A JavaScript block ready to embed inside a `<script>` tag
+local function build_wiring(
+  selector_js,
+  target_js,
+  main_audio_js,
+  end_audio_js,
+  loop_audio_js,
+  volume_pre_js,
+  volume_post_js,
+  shortcut_js,
+  missing_label
+)
+  return
+    '(function () {' ..
+    '  var el = ' .. selector_js .. ';' ..
+    '  if (el) {' ..
+    volume_pre_js ..
+    '    var instance = new Elevator({' ..
+    '      element: el,' ..
+    target_js ..
+    main_audio_js ..
+    end_audio_js ..
+    loop_audio_js ..
+    '    });' ..
+    volume_post_js ..
+    shortcut_js ..
+    '  } else {' ..
+    '    console.log("Elevator: ' .. missing_label .. ' not found");' ..
+    '  }' ..
+    '})();'
+end
 
 --- Elevator shortcode handler.
---- Creates a button that scrolls smoothly to the top of the page (or a target element)
---- with optional elevator music sound effects.
---- Also enhances Quarto's back-to-top button (when enabled via back-to-top-navigation: true).
+--- Creates a button that scrolls smoothly to the top of the page (or a target
+--- element) with optional elevator music sound effects. Also enhances Quarto's
+--- back-to-top button when `back-to-top-navigation: true` is set.
 ---
---- @param args table Array of positional arguments (button text, optional target element ID)
---- @param kwargs table Named arguments (audio: main audio file, end: end audio file)
---- @return pandoc.RawInline|pandoc.Null HTML button with elevator functionality or Null for non-HTML formats
+--- @param args table Positional arguments (button text, optional target id)
+--- @param kwargs table Named arguments
+--- @param meta table Document metadata (used for the global disable flag)
+--- @return pandoc.RawInline|pandoc.Null HTML button or Null for non-HTML formats
 --- @usage {{< elevator >}}
 --- @usage {{< elevator "Back to top" >}}
---- @usage {{< elevator "Go up" "header" audio="music.mp3" end="ding.mp3" >}}
-local function elevator(args, kwargs)
-  if quarto.doc.is_format('html:js') then
-    -- Use utils module to ensure HTML dependencies
-    html_mod.ensure_html_dependency({
-      name = 'elevatorjs',
-      version = '1.0.0',
-      scripts = { 'elevator.min.js' }
-    })
-
-    --- @type string Text to display on the button
-    local textButton = 'Return to the top!'
-    --- @type string JavaScript code for target element (if specified)
-    local targetAnchor = ''
-    if #args > 0 then
-      textButton = str.stringify(args[1])
-      if #args > 1 then
-        targetAnchor = 'targetElement: document.querySelector("#' .. str.stringify(args[2]) .. '"), '
-      end
+--- @usage {{< elevator "Go up" "header" audio="music.mp3" end="ding.mp3" volume=0.5 loop-audio=false shortcut="t" >}}
+local function elevator(args, kwargs, meta)
+  if not quarto.doc.is_format('html:js') then
+    return pandoc.Null()
+  end
+
+  if is_globally_disabled(meta) then
+    return pandoc.Null()
+  end
+
+  html_mod.ensure_html_dependency({
+    name = 'elevatorjs',
+    version = '1.0.0',
+    scripts = { 'elevator.min.js' }
+  })
+
+  --- @type string Text to display on the button
+  local text_button = 'Return to the top!'
+  --- @type string JavaScript snippet selecting the target element (if any)
+  local target_anchor_js = ''
+  if #args > 0 then
+    text_button = str.stringify(args[1])
+    if #args > 1 then
+      local target_id = str.stringify(args[2])
+      target_anchor_js =
+        '      targetElement: document.querySelector("#' ..
+        str.escape_js_string(target_id) .. '"),'
     end
+  end
+
+  --- @type string Resolved path to the main audio file (played while scrolling)
+  local main_audio = resolve_audio(str.stringify(kwargs['audio']))
 
-    --- @type string Path to main audio file (played during scroll)
-    local mainAudio = str.stringify(kwargs['audio'])
-    if str.is_empty(mainAudio) then
-      mainAudio = ''
+  --- @type string Resolved path to the end audio file (played at completion)
+  local end_audio_raw = str.stringify(kwargs['end'])
+  local end_audio
+  if str.is_empty(end_audio_raw) then
+    end_audio = DEFAULT_END_AUDIO
+    if not default_audio_registered then
+      ensure_default_audio()
+      quarto.doc.add_format_resource(end_audio)
+      default_audio_registered = true
     end
+  else
+    end_audio = resolve_audio(end_audio_raw)
+  end
+
+  --- @type number|nil Audio playback volume in [0.0, 1.0]
+  local volume = parse_volume(str.stringify(kwargs['volume']))
+
+  --- @type boolean Whether the main audio loops while scrolling
+  local loop_audio = parse_boolean(kwargs['loop-audio'], true)
+
+  --- @type string Optional keyboard key that triggers the elevator
+  local shortcut = str.stringify(kwargs['shortcut'])
 
-    --- @type string Path to end audio file (played when scroll completes)
-    local endAudio = str.stringify(kwargs['end'])
-    if str.is_empty(endAudio) then
-      endAudio = 'ding.mp3'
-      quarto.doc.add_format_resource(endAudio)
+  local main_audio_js = ''
+  if not str.is_empty(main_audio) then
+    main_audio_js = '      mainAudio: "' .. str.escape_js_string(main_audio) .. '",'
+  end
+
+  local end_audio_js = ''
+  if not str.is_empty(end_audio) then
+    end_audio_js = '      endAudio: "' .. str.escape_js_string(end_audio) .. '",'
+  end
+
+  local loop_audio_js = '      loopAudio: ' .. tostring(loop_audio) .. ','
+
+  -- Elevator.js holds its `Audio` instances in private closure variables and
+  -- internally calls `audio.setAttribute('loop', loopAudio)`. Because `loop`
+  -- is a boolean HTML attribute, setting it to the literal string `"false"`
+  -- still enables looping; volume cannot be tweaked from outside either.
+  -- The wrappers below temporarily replace `window.Audio` so each newly built
+  -- instance gets the requested `volume` and a real `loop = false` when
+  -- needed, then restore the original constructor straight after `new
+  -- Elevator`. The saved-original handle lives on `window` so the
+  -- custom-button and back-to-top blocks can share one restore step.
+  local needs_audio_wrap = volume ~= nil or loop_audio == false
+  local volume_pre_js = ''
+  local volume_post_js = ''
+  if needs_audio_wrap then
+    local body = '      var a = new window.__elevatorOrigAudio(src);'
+    if volume ~= nil then
+      body = body .. '      a.volume = ' .. tostring(volume) .. ';'
+    end
+    if loop_audio == false then
+      body = body ..
+        '      var origSetAttribute = a.setAttribute.bind(a);' ..
+        '      a.setAttribute = function(name, value) {' ..
+        '        if (name === "loop") { a.loop = (value === true || value === "true"); return; }' ..
+        '        origSetAttribute(name, value);' ..
+        '      };'
     end
+    body = body .. '      return a;'
+    volume_pre_js =
+      '    window.__elevatorOrigAudio = window.__elevatorOrigAudio || window.Audio;' ..
+      '    window.Audio = function(src) {' ..
+      body ..
+      '    };'
+    volume_post_js = '    window.Audio = window.__elevatorOrigAudio;'
+  end
 
-    -- Create the initialization script that will run after page load
-    local initScript =
-      'window.addEventListener("load", function() {' ..
-      '  console.log("Elevator: Initializing...");' ..
-      '  var elevatorButton = document.querySelector(".elevator-button");' ..
-      '  if (elevatorButton) {' ..
-      '    console.log("Elevator: Found custom button");' ..
-      '    var customElevator = new Elevator({' ..
-      '      element: elevatorButton,' ..
-      targetAnchor ..
-      '      mainAudio: "' .. mainAudio .. '",' ..
-      '      endAudio: "' .. endAudio .. '"' ..
-      '    });' ..
-      '  } else {' ..
-      '    console.log("Elevator: Custom button not found");' ..
-      '  }' ..
-      '  var quartoBackToTop = document.querySelector("#quarto-back-to-top");' ..
-      '  if (quartoBackToTop) {' ..
-      '    console.log("Elevator: Found Quarto back-to-top button");' ..
-      '    quartoBackToTop.removeAttribute("onclick");' ..
-      '    quartoBackToTop.onclick = null;' ..
-      '    var quartoElevator = new Elevator({' ..
-      '      element: quartoBackToTop,' ..
-      targetAnchor ..
-      '      mainAudio: "' .. mainAudio .. '",' ..
-      '      endAudio: "' .. endAudio .. '"' ..
-      '    });' ..
-      '  } else {' ..
-      '    console.log("Elevator: Quarto back-to-top button not found");' ..
-      '  }' ..
-      '});'
-
-    quarto.doc.include_text('after-body', '<script>' .. initScript .. '</script>')
-
-    return pandoc.RawInline(
-      'html',
-      '<button class="btn btn-outline-primary elevator-button" type="submit">' .. textButton .. '</button>'
-    )
-  else
-    return pandoc.Null()
+  local shortcut_js = ''
+  if not str.is_empty(shortcut) then
+    local shortcut_key = str.escape_js_string(shortcut)
+    shortcut_js =
+      '    document.addEventListener("keydown", function(ev) {' ..
+      '      var target = ev.target;' ..
+      '      var tag = target && target.tagName ? target.tagName.toUpperCase() : "";' ..
+      '      var editable = target && target.isContentEditable;' ..
+      '      if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || editable) { return; }' ..
+      '      if (ev.key === "' .. shortcut_key .. '") {' ..
+      '        ev.preventDefault();' ..
+      '        instance.elevate();' ..
+      '      }' ..
+      '    });'
   end
+
+  local custom_wiring = build_wiring(
+    'document.querySelector(".elevator-button")',
+    target_anchor_js,
+    main_audio_js,
+    end_audio_js,
+    loop_audio_js,
+    volume_pre_js,
+    volume_post_js,
+    shortcut_js,
+    'Custom button'
+  )
+
+  local quarto_wiring =
+    '(function () {' ..
+    '  var qbtt = document.querySelector("#quarto-back-to-top");' ..
+    '  if (qbtt) {' ..
+    '    qbtt.removeAttribute("onclick");' ..
+    '    qbtt.onclick = null;' ..
+    volume_pre_js ..
+    '    var instance = new Elevator({' ..
+    '      element: qbtt,' ..
+    target_anchor_js ..
+    main_audio_js ..
+    end_audio_js ..
+    loop_audio_js ..
+    '    });' ..
+    volume_post_js ..
+    shortcut_js ..
+    '  }' ..
+    '})();'
+
+  local init_script =
+    'window.addEventListener("load", function() {' ..
+    custom_wiring ..
+    quarto_wiring ..
+    '});'
+
+  quarto.doc.include_text('after-body', '<script>' .. init_script .. '</script>')
+
+  return pandoc.RawInline(
+    'html',
+    '<button class="btn btn-outline-primary elevator-button" type="submit">' ..
+    str.escape_html(text_button) ..
+    '</button>'
+  )
 end
 
 --- Module export table.
diff --git a/example.qmd b/example.qmd
index b8a91a1..17e7b9c 100644
--- a/example.qmd
+++ b/example.qmd
@@ -18,7 +18,7 @@ Animation is only available for HTML-based documents.
 ## Installation
 
 ```bash
-quarto add mcanouil/quarto-elevator@1.4.0
+quarto add mcanouil/quarto-elevator@1.5.0
 ```
 
 This will install the extension under the `_extensions` subdirectory.
@@ -41,6 +41,26 @@ To add an elevator button, use the `{{{< elevator >}}}` shortcode:
   {{{< elevator <text-button> <anchor-target> <audio=audio.mp3> >}}}
   ```
 
+- Volume, loop, and keyboard shortcut:
+
+  ```markdown
+  {{{< elevator "Back" audio=music.mp3 volume=0.5 loop-audio=false shortcut="t" >}}}
+  ```
+
+- Built-in named sound (`ding` resolves to the bundled `ding.mp3`):
+
+  ```markdown
+  {{{< elevator "Back" end=ding >}}}
+  ```
+
+- Global disable via document metadata:
+
+  ```yaml
+  ---
+  elevator: false
+  ---
+  ```
+
 :::: {style='text-align: center;'}
 
 ```{=html}
@@ -85,14 +105,16 @@ I call "back to top" buttons elevators...
 `<div class="down-arrow">&#9660;</div>`{=html}
 Ok, here we are... click that elevator!
 
-{{< elevator audio=BossaBossa.mp3 >}}
+{{< elevator audio=BossaBossa.mp3 volume=0.5 loop-audio=false shortcut="t" >}}
 
 Or `{{{< elevator "Return to 'Wow, all this scrolling.'" wow-all-this-scrolling audio=BossaBossa.mp3 >}}}` to scroll up to `## Wow, all this scrolling`.
 
+Press `t` anywhere outside a form field to ride the elevator.
+
 :::
 
 ---
 
-BossaBossa by Kevin MacLeod | <https://incompetech.com/>.  
+BossaBossa by Kevin MacLeod | <https://incompetech.com/>.
 Music promoted by <https://www.chosic.com/free-music/all/>.
 Creative Commons Creative Commons: By Attribution 3.0 License (<http://creativecommons.org/licenses/by/3.0/>).

From 7d4ada1e534971d0a604a614e594f2b24c91832f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Thu, 28 May 2026 23:05:43 +0200
Subject: [PATCH 2/5] chore: simplify after review

- Drop the module-level globally_disabled cache.
  Re-reading meta on each call is cheap, removes a stale-state risk
  across documents in a project, and shrinks the helper to four lines.
- Inline the needs_audio_wrap flag.
  The condition is short and only used once.
- Unify the custom-button and Quarto back-to-top wiring blocks behind
  a single build_wiring helper that takes a config table.
  The back-to-top variant supplies pre_init_js for the onclick reset
  and omits missing_label so the else branch is skipped.
- Replace em dashes with colons in the build_wiring docstring.
---
 _extensions/elevator/elevator.lua | 144 ++++++++++++------------------
 1 file changed, 59 insertions(+), 85 deletions(-)

diff --git a/_extensions/elevator/elevator.lua b/_extensions/elevator/elevator.lua
index ba2dc19..92e7f72 100644
--- a/_extensions/elevator/elevator.lua
+++ b/_extensions/elevator/elevator.lua
@@ -33,12 +33,6 @@ local default_audio_registered = false
 --- @type boolean
 local missing_default_warned = false
 
---- Module-level cache for the document-level `elevator: false` opt-out.
---- `nil` means "not yet inspected"; `true`/`false` mean the metadata has been
---- read and the result is recorded.
---- @type boolean|nil
-local globally_disabled = nil
-
 --- Parse a value into a boolean.
 --- Accepts native booleans plus the case-insensitive strings `true`, `yes`,
 --- `1`, `on` (truthy) and `false`, `no`, `0`, `off` (falsy).
@@ -98,23 +92,16 @@ local function parse_volume(raw_value)
 end
 
 --- Determine whether the document opts out of the elevator entirely via the
---- top-level `elevator: false` metadata flag. The result is cached per
---- document; pass the `meta` table supplied to the shortcode handler.
+--- top-level `elevator: false` metadata flag.
+--- Accepts both `elevator: false` and `elevator: { enabled: false }`.
 --- @param meta table|nil The document metadata passed by Quarto
 --- @return boolean True when the shortcode should render nothing
 local function is_globally_disabled(meta)
-  if globally_disabled ~= nil then return globally_disabled end
-  if meta and meta.elevator ~= nil then
-    -- Accept both `elevator: false` and `elevator: { enabled: false }`.
-    if type(meta.elevator) == 'table' and meta.elevator.enabled ~= nil then
-      globally_disabled = not parse_boolean(meta.elevator.enabled, true)
-    else
-      globally_disabled = not parse_boolean(meta.elevator, true)
-    end
-  else
-    globally_disabled = false
+  if not (meta and meta.elevator ~= nil) then return false end
+  if type(meta.elevator) == 'table' and meta.elevator.enabled ~= nil then
+    return not parse_boolean(meta.elevator.enabled, true)
   end
-  return globally_disabled
+  return not parse_boolean(meta.elevator, true)
 end
 
 --- Warn (once per render) when the default `ding.mp3` resource cannot be
@@ -141,47 +128,46 @@ local function ensure_default_audio()
 end
 
 --- Build the JavaScript snippet wiring one DOM selector to an Elevator
---- instance. All option fragments are passed pre-serialised so the caller
---- controls escaping; this helper only stitches the pieces together. Each
---- block is wrapped in its own IIFE so the local `instance` variable does
+--- instance.
+--- All option fragments are passed pre-serialised so the caller controls
+--- escaping; this helper only stitches the pieces together.
+--- Each block is wrapped in its own IIFE so the local `instance` variable does
 --- not collide with sibling blocks (`var` is function-scoped in JS).
---- @param selector_js string JavaScript expression returning the element
---- @param target_js string `targetElement: ...,` snippet (may be empty)
---- @param main_audio_js string `mainAudio: "...",` snippet (may be empty)
---- @param end_audio_js string `endAudio: "...",` snippet (may be empty)
---- @param loop_audio_js string `loopAudio: true|false,` snippet (may be empty)
---- @param volume_pre_js string `window.Audio` wrap installed before construction
---- @param volume_post_js string `window.Audio` restore installed after construction
---- @param shortcut_js string Keyboard-shortcut wiring (may be empty)
---- @param missing_label string Human-readable label used in `not found` logs
---- @return string A JavaScript block ready to embed inside a `<script>` tag
-local function build_wiring(
-  selector_js,
-  target_js,
-  main_audio_js,
-  end_audio_js,
-  loop_audio_js,
-  volume_pre_js,
-  volume_post_js,
-  shortcut_js,
-  missing_label
-)
+--- @param config table Fields:
+---   selector_js (string): JavaScript expression returning the element.
+---   target_js (string): `targetElement: ...,` snippet (may be empty).
+---   main_audio_js (string): `mainAudio: "...",` snippet (may be empty).
+---   end_audio_js (string): `endAudio: "...",` snippet (may be empty).
+---   loop_audio_js (string): `loopAudio: true|false,` snippet (may be empty).
+---   volume_pre_js (string): `window.Audio` wrap installed before construction.
+---   volume_post_js (string): `window.Audio` restore installed after construction.
+---   shortcut_js (string): Keyboard-shortcut wiring (may be empty).
+---   pre_init_js (string|nil): Extra JS run after the element is found, before construction.
+---   missing_label (string|nil): Label for the `not found` console log; when nil, the else branch is omitted.
+--- @return string A JavaScript block ready to embed inside a `<script>` tag.
+local function build_wiring(config)
+  local else_branch = ''
+  if config.missing_label then
+    else_branch =
+      '  } else {' ..
+      '    console.log("Elevator: ' .. config.missing_label .. ' not found");'
+  end
   return
     '(function () {' ..
-    '  var el = ' .. selector_js .. ';' ..
+    '  var el = ' .. config.selector_js .. ';' ..
     '  if (el) {' ..
-    volume_pre_js ..
+    (config.pre_init_js or '') ..
+    config.volume_pre_js ..
     '    var instance = new Elevator({' ..
     '      element: el,' ..
-    target_js ..
-    main_audio_js ..
-    end_audio_js ..
-    loop_audio_js ..
+    config.target_js ..
+    config.main_audio_js ..
+    config.end_audio_js ..
+    config.loop_audio_js ..
     '    });' ..
-    volume_post_js ..
-    shortcut_js ..
-    '  } else {' ..
-    '    console.log("Elevator: ' .. missing_label .. ' not found");' ..
+    config.volume_post_js ..
+    config.shortcut_js ..
+    else_branch ..
     '  }' ..
     '})();'
 end
@@ -274,10 +260,9 @@ local function elevator(args, kwargs, meta)
   -- needed, then restore the original constructor straight after `new
   -- Elevator`. The saved-original handle lives on `window` so the
   -- custom-button and back-to-top blocks can share one restore step.
-  local needs_audio_wrap = volume ~= nil or loop_audio == false
   local volume_pre_js = ''
   local volume_post_js = ''
-  if needs_audio_wrap then
+  if volume ~= nil or loop_audio == false then
     local body = '      var a = new window.__elevatorOrigAudio(src);'
     if volume ~= nil then
       body = body .. '      a.volume = ' .. tostring(volume) .. ';'
@@ -315,36 +300,25 @@ local function elevator(args, kwargs, meta)
       '    });'
   end
 
-  local custom_wiring = build_wiring(
-    'document.querySelector(".elevator-button")',
-    target_anchor_js,
-    main_audio_js,
-    end_audio_js,
-    loop_audio_js,
-    volume_pre_js,
-    volume_post_js,
-    shortcut_js,
-    'Custom button'
-  )
-
-  local quarto_wiring =
-    '(function () {' ..
-    '  var qbtt = document.querySelector("#quarto-back-to-top");' ..
-    '  if (qbtt) {' ..
-    '    qbtt.removeAttribute("onclick");' ..
-    '    qbtt.onclick = null;' ..
-    volume_pre_js ..
-    '    var instance = new Elevator({' ..
-    '      element: qbtt,' ..
-    target_anchor_js ..
-    main_audio_js ..
-    end_audio_js ..
-    loop_audio_js ..
-    '    });' ..
-    volume_post_js ..
-    shortcut_js ..
-    '  }' ..
-    '})();'
+  local shared_options = {
+    target_js = target_anchor_js,
+    main_audio_js = main_audio_js,
+    end_audio_js = end_audio_js,
+    loop_audio_js = loop_audio_js,
+    volume_pre_js = volume_pre_js,
+    volume_post_js = volume_post_js,
+    shortcut_js = shortcut_js,
+  }
+
+  local custom_wiring = build_wiring(setmetatable({
+    selector_js = 'document.querySelector(".elevator-button")',
+    missing_label = 'Custom button',
+  }, { __index = shared_options }))
+
+  local quarto_wiring = build_wiring(setmetatable({
+    selector_js = 'document.querySelector("#quarto-back-to-top")',
+    pre_init_js = '    el.removeAttribute("onclick");    el.onclick = null;',
+  }, { __index = shared_options }))
 
   local init_script =
     'window.addEventListener("load", function() {' ..

From 6db603328dd8787ed0da1b746413c533cd006777 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Fri, 29 May 2026 23:01:17 +0200
Subject: [PATCH 3/5] revert: version bump (handled by GHA release workflow)

---
 CHANGELOG.md                        | 2 --
 README.md                           | 2 +-
 _extensions/elevator/_extension.yml | 2 +-
 example.qmd                         | 2 +-
 4 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e36bf6..9bbed91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,6 @@
 
 ## Unreleased
 
-## 1.5.0 (2026-05-28)
-
 ### Bug Fixes
 
 - fix: JavaScript-escape anchor IDs and audio paths so values containing `"`, `\`, `<`, or newlines no longer break the generated init script.
diff --git a/README.md b/README.md
index 2d437c0..ea91349 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Animation is only available for HTML-based documents.
 ## Installation
 
 ```sh
-quarto add mcanouil/quarto-elevator@1.5.0
+quarto add mcanouil/quarto-elevator@1.4.0
 ```
 
 This will install the extension under the `_extensions` subdirectory.
diff --git a/_extensions/elevator/_extension.yml b/_extensions/elevator/_extension.yml
index 2570026..fb12943 100644
--- a/_extensions/elevator/_extension.yml
+++ b/_extensions/elevator/_extension.yml
@@ -1,6 +1,6 @@
 title: Elevator.js
 author: Mickaël Canouil
-version: 1.5.0
+version: 1.4.0
 quarto-required: ">=1.2.280"
 contributes:
   shortcodes:
diff --git a/example.qmd b/example.qmd
index 17e7b9c..748f910 100644
--- a/example.qmd
+++ b/example.qmd
@@ -18,7 +18,7 @@ Animation is only available for HTML-based documents.
 ## Installation
 
 ```bash
-quarto add mcanouil/quarto-elevator@1.5.0
+quarto add mcanouil/quarto-elevator@1.4.0
 ```
 
 This will install the extension under the `_extensions` subdirectory.

From 42344d0b6d51d86761a3f8a3631078b46678322b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Sun, 31 May 2026 12:10:31 +0200
Subject: [PATCH 4/5] feat: scope document-level disable under
 extensions.elevator namespace

Read the global disable flag from extensions.elevator.enabled instead of
the top-level elevator key. Top-level keys pollute the document metadata
namespace; nesting under extensions.elevator keeps all extension options
in one place. The previous top-level form is removed entirely, including
the boolean shorthand, so only extensions.elevator.enabled: false disables
the shortcode.
---
 CHANGELOG.md                      |  2 +-
 README.md                         |  6 ++++--
 _extensions/elevator/_schema.yml  | 17 ++++++++++-------
 _extensions/elevator/elevator.lua | 14 ++++++++------
 example.qmd                       |  4 +++-
 5 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9bbed91..7847eb3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,7 @@
 - feat: Add `loop-audio` attribute that genuinely disables looping (works around Elevator.js's `setAttribute('loop', 'false')` no-op).
 - feat: Add built-in named sounds. `audio=ding` and `end=ding` resolve to the bundled `ding.mp3`.
 - feat: Add `shortcut` attribute to trigger the elevator from anywhere outside form fields via a keyboard key.
-- feat: Add document-level disable via `elevator: false` (or `elevator: { enabled: false }`) in YAML metadata.
+- feat: Add document-level disable via `extensions.elevator.enabled: false` in YAML metadata.
 
 ### Documentation
 
diff --git a/README.md b/README.md
index ea91349..15ab9c3 100644
--- a/README.md
+++ b/README.md
@@ -68,11 +68,13 @@ The built-in name `ding` resolves to the bundled `ding.mp3`, so `audio=ding` or
 
 ### Global disable
 
-Set `elevator: false` (or `elevator: { enabled: false }`) in the document YAML to suppress every `{{< elevator >}}` shortcode in that document.
+Set `extensions.elevator.enabled: false` in the document YAML to suppress every `{{< elevator >}}` shortcode in that document.
 
 ```yaml
 ---
-elevator: false
+extensions:
+  elevator:
+    enabled: false
 ---
 ```
 
diff --git a/_extensions/elevator/_schema.yml b/_extensions/elevator/_schema.yml
index 218b1e4..211760d 100644
--- a/_extensions/elevator/_schema.yml
+++ b/_extensions/elevator/_schema.yml
@@ -51,11 +51,14 @@ shortcodes:
         description: "Optional keyboard key (matched against KeyboardEvent.key) that triggers the elevator from anywhere outside form fields. Examples: 't', 'Escape'."
 
 metadata:
-  elevator:
-    type: ["boolean", "object"]
-    description: "Set to false to disable every {{< elevator >}} shortcode in the document. Accepts an object with an 'enabled' boolean as an alternative."
+  extensions:
+    type: object
     properties:
-      enabled:
-        type: boolean
-        default: true
-        description: "Whether {{< elevator >}} shortcodes render anything. Defaults to true."
+      elevator:
+        type: object
+        description: "Configuration for the elevator extension."
+        properties:
+          enabled:
+            type: boolean
+            default: true
+            description: "Set to false to disable every {{< elevator >}} shortcode in the document. Defaults to true."
diff --git a/_extensions/elevator/elevator.lua b/_extensions/elevator/elevator.lua
index 92e7f72..09b6992 100644
--- a/_extensions/elevator/elevator.lua
+++ b/_extensions/elevator/elevator.lua
@@ -92,16 +92,18 @@ local function parse_volume(raw_value)
 end
 
 --- Determine whether the document opts out of the elevator entirely via the
---- top-level `elevator: false` metadata flag.
---- Accepts both `elevator: false` and `elevator: { enabled: false }`.
+--- `extensions.elevator.enabled: false` metadata flag.
 --- @param meta table|nil The document metadata passed by Quarto
 --- @return boolean True when the shortcode should render nothing
 local function is_globally_disabled(meta)
-  if not (meta and meta.elevator ~= nil) then return false end
-  if type(meta.elevator) == 'table' and meta.elevator.enabled ~= nil then
-    return not parse_boolean(meta.elevator.enabled, true)
+  if type(meta) ~= 'table' then return false end
+  local ext = meta.extensions
+  if type(ext) ~= 'table' then return false end
+  local elevator_meta = ext.elevator
+  if type(elevator_meta) ~= 'table' or elevator_meta.enabled == nil then
+    return false
   end
-  return not parse_boolean(meta.elevator, true)
+  return not parse_boolean(elevator_meta.enabled, true)
 end
 
 --- Warn (once per render) when the default `ding.mp3` resource cannot be
diff --git a/example.qmd b/example.qmd
index 748f910..8686513 100644
--- a/example.qmd
+++ b/example.qmd
@@ -57,7 +57,9 @@ To add an elevator button, use the `{{{< elevator >}}}` shortcode:
 
   ```yaml
   ---
-  elevator: false
+  extensions:
+    elevator:
+      enabled: false
   ---
   ```
 

From 665b276484360c5142a99541c0230f9374562f1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micka=C3=ABl=20Canouil?=
 <8896044+mcanouil@users.noreply.github.com>
Date: Sun, 31 May 2026 12:12:17 +0200
Subject: [PATCH 5/5] fix: regenerate _schema.yml against v2 extension schema

Declare the disable flag as a top-level options.enabled entry, which the
Quarto Wizard maps to extensions.elevator.enabled, instead of nesting it
under metadata.extensions.elevator. Upgrade the $schema reference to v2.
---
 _extensions/elevator/_schema.yml | 38 +++++++++++---------------------
 1 file changed, 13 insertions(+), 25 deletions(-)

diff --git a/_extensions/elevator/_schema.yml b/_extensions/elevator/_schema.yml
index 211760d..9d230ea 100644
--- a/_extensions/elevator/_schema.yml
+++ b/_extensions/elevator/_schema.yml
@@ -1,10 +1,11 @@
-# _schema.yml for "elevator" shortcode extension
-# Describes shortcode arguments and attributes for IDE tooling and runtime validation.
+# Schema for the elevator extension
+$schema: https://m.canouil.dev/quarto-wizard/assets/schema/v2/extension-schema.json
 
-# Per-shortcode schemas.
-# Describes positional arguments and named attributes for {{< elevator >}}.
-
-$schema: https://m.canouil.dev/quarto-wizard/assets/schema/v1/extension-schema.json
+options:
+  enabled:
+    type: boolean
+    default: true
+    description: "Whether {{< elevator >}} shortcodes render anything; set to false to disable every shortcode in the document."
 
 shortcodes:
   elevator:
@@ -12,15 +13,15 @@ shortcodes:
     arguments:
       - name: text
         type: string
-        description: "Text to display on the button. Defaults to 'Return to the top!'."
         default: "Return to the top!"
+        description: "Text to display on the button."
       - name: target
         type: string
         description: "Element ID to scroll to instead of the top of the page."
     attributes:
       audio:
         type: string
-        description: "Path to the main audio file played during the scroll animation. The built-in name 'ding' resolves to the bundled ding.mp3."
+        description: "Path to the main audio file played during the scroll animation; the built-in name 'ding' resolves to the bundled ding.mp3."
         completion:
           type: file
           extensions:
@@ -30,7 +31,7 @@ shortcodes:
       end:
         type: string
         default: "ding.mp3"
-        description: "Path to the audio file played when the scroll completes. The built-in name 'ding' resolves to the bundled ding.mp3."
+        description: "Path to the audio file played when the scroll completes; the built-in name 'ding' resolves to the bundled ding.mp3."
         completion:
           type: file
           extensions:
@@ -39,26 +40,13 @@ shortcodes:
             - .wav
       volume:
         type: number
-        description: "Playback volume in the range [0.0, 1.0]. Values outside the range are clamped and a warning is emitted."
         minimum: 0.0
         maximum: 1.0
+        description: "Playback volume in the range [0.0, 1.0]; values outside the range are clamped and a warning is emitted."
       loop-audio:
         type: boolean
         default: true
-        description: "Whether the main audio loops while scrolling. Set to false to play the audio only once."
+        description: "Whether the main audio loops while scrolling; set to false to play the audio only once."
       shortcut:
         type: string
-        description: "Optional keyboard key (matched against KeyboardEvent.key) that triggers the elevator from anywhere outside form fields. Examples: 't', 'Escape'."
-
-metadata:
-  extensions:
-    type: object
-    properties:
-      elevator:
-        type: object
-        description: "Configuration for the elevator extension."
-        properties:
-          enabled:
-            type: boolean
-            default: true
-            description: "Set to false to disable every {{< elevator >}} shortcode in the document. Defaults to true."
+        description: "Optional keyboard key (matched against KeyboardEvent.key) that triggers the elevator from anywhere outside form fields, e.g. 't' or 'Escape'."