Add mode=plain to kbd shortcode (#13489) (#14079)

* Add `mode=plain` to `kbd` shortcode (#13489)

Allow rendering keyboard shortcuts as literal text without OS-specific
symbol translation, for teaching/slideshow contexts where shortcuts for
multiple OSes need to be shown simultaneously.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Fix kbd shortcode handling empty mode kwarg and test format

Quarto's shortcode system populates kwargs with empty values for
unspecified keys, so check for empty string before validating mode.
Also fix test to use correct ensureFileRegexMatches format (single
array of match patterns).

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: cscheid

news/changelog-1.9.md

@@ -3,6 +3,7 @@ All changes included in 1.9:
 ## Shortcodes
 
 - ([#13342](https://github.com/quarto-dev/quarto-cli/issues/13342)): Ensure that the `contents` shortcode works inside metadata.
+- ([#13489](https://github.com/quarto-dev/quarto-cli/issues/13489)): Add `mode=plain` option to the `kbd` shortcode to render keyboard shortcuts exactly as written, without OS-specific symbol translation.
 - ([#14061](https://github.com/quarto-dev/quarto-cli/issues/14061)): Fix `meta` shortcode not preserving line breaks in values. The shortcode now respects its usage context (block, inline, or text) and preserves paragraph breaks in block and code block contexts.
 
 ## Regression fixes

src/resources/extensions/quarto/kbd/kbd.lua

@@ -4,14 +4,40 @@ return {
     local function get_osname(v)
       if v == "win" then return "windows" end
       if v == "mac" then return "mac" end
-      if v == "linux" then return "linux" end       
+      if v == "linux" then return "linux" end
     end
+
+    -- Extract and validate mode kwarg
+    local mode = kwargs["mode"]
+    if mode ~= nil then
+      mode = pandoc.utils.stringify(mode)
+      kwargs["mode"] = nil
+      if mode == "" then
+        mode = nil
+      elseif mode ~= "plain" then
+        return quarto.shortcode.error_output("kbd", "unknown mode: " .. mode .. ", supported modes are: plain", "inline")
+      else
+        -- plain mode requires a positional argument
+        if #args == 0 then
+          return quarto.shortcode.error_output("kbd", "plain mode requires a positional argument", "inline")
+        end
+        -- plain mode doesn't accept OS kwargs
+        for k, _ in pairs(kwargs) do
+          return quarto.shortcode.error_output("kbd", "plain mode does not accept OS-specific arguments", "inline")
+        end
+      end
+    end
+
     if quarto.doc.is_format("html:js") then
       quarto.doc.add_html_dependency({
         name = 'kbd',
         scripts = { 'resources/kbd.js' },
         stylesheets = { 'resources/kbd.css' }
       })
+      if mode == "plain" then
+        local text = pandoc.utils.stringify(args[1])
+        return pandoc.RawInline('html', '<kbd data-mode="plain" class="kbd">' .. text .. '</kbd>')
+      end
       local kwargs_strs = {}
       local title_strs = {}
       for k, v in pairs(kwargs) do
@@ -73,6 +99,9 @@ return {
       -- {{< kbd Shift-Ctrl-P >}}
       -- {{< kbd Shift-Ctrl-P mac=Shift-Command-P >}}
       -- {{< kbd mac=Shift-Command-P win=Shift-Control-S linux=Shift-Ctrl-S >}}
+      if mode == "plain" then
+        return pandoc.Code(pandoc.utils.stringify(args[1]))
+      end
       local result = {};
       local n_kwargs = 0
       for k, v in pairs(kwargs) do

src/resources/extensions/quarto/kbd/resources/kbd.js

@@ -45,6 +45,9 @@
   window.addEventListener("DOMContentLoaded", (_) => {
     for (const el of Array.from(document.querySelectorAll("kbd"))) {
       el.classList.add("kbd");
+      if (el.dataset.mode === "plain") {
+        continue;
+      }
       if (el.dataset[os.name] !== undefined) {
         el.innerText = el.dataset[os.name];
       }

tests/docs/smoke-all/shortcodes/kbd-plain.qmd

@@ -0,0 +1,14 @@
+---
+title: kbd plain mode test
+format: html
+_quarto:
+  tests:
+    html:
+      ensureFileRegexMatches:
+        - ['data-mode="plain"', 'Shift-Ctrl-K', 'Command-Shift-K']
+        - []
+---
+
+{{< kbd Shift-Ctrl-K mode=plain >}}
+
+{{< kbd Command-Shift-K mode=plain >}}