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 <noreply@anthropic.com>

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.
 
 ## Regression fixes
 

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

@@ -4,14 +4,37 @@ 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 ~= "plain" then
+        return quarto.shortcode.error_output("kbd", "unknown mode: " .. mode .. ", supported modes are: plain", "inline")
+      end
+      -- 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
+
     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 +96,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,15 @@
+---
+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 >}}