add support for kbd shortcode. Closes #3384 (#3395)

See https://quarto.org/docs/prerelease/1.3.html for documentation.

Author: cscheid

news/changelog-1.3.md

@@ -66,3 +66,4 @@
 - Add optional `rel` attribute to navigation links ([#3212](https://github.com/quarto-dev/quarto-cli/issues/3212))
 - Use the right port when CRI is initialized multiple times ([#3066](https://github.com/quarto-dev/quarto-cli/issues/3066))
 - Allow custom themes for giscus ([#3105](https://github.com/quarto-dev/quarto-cli/issues/3105))
+- new `kbd` shortcode, to describe keyboard keys ([#3384](https://github.com/quarto-dev/quarto-cli/issues/3384)). See the [pre-release documentation](https://quarto.org/docs/prerelease/1.3.html) for details.

src/resources/extensions/quarto/kbd/_extension.yml

@@ -0,0 +1,6 @@
+title: Kbd
+author: Posit, PBC
+organization: quarto
+contributes:
+  shortcodes:
+    - kbd.lua

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

@@ -0,0 +1,79 @@
+-- todo: i18n :(
+return {
+  ['kbd'] = function(args, kwargs, meta)
+    local function osname(v)
+      if v == "win" then return "Windows" end
+      if v == "mac" then return "Mac" end
+      if v == "linux" then return "Linux" 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' }
+      })
+      local kwargs_strs = {}
+      for k, v in pairs(kwargs) do
+        table.insert(kwargs_strs, string.format('data-%s="%s"', osname(k), pandoc.utils.stringify(v)))
+      end
+      local kwargs_str = table.concat(kwargs_strs)
+
+      local default_arg_str
+      if #args == 0 then
+        for k, v in pairs(kwargs) do
+          default_arg_str = pandoc.utils.stringify(v)
+          break
+        end
+
+        default_arg_str = ""
+      else
+        default_arg_str = pandoc.utils.stringify(args[1])
+      end
+
+      return pandoc.RawInline('html', '<kbd ' .. kwargs_str .. '>' .. default_arg_str .. '</kbd>')
+    else
+      -- example shortcodes
+      -- {{< 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 >}}
+      local result = {};
+      local n_kwargs = 0
+      for k, v in pairs(kwargs) do
+        n_kwargs = n_kwargs + 1
+      end
+      if #args == 1 then
+        table.insert(result, pandoc.Code(pandoc.utils.stringify(args[1])))
+        if n_kwargs > 0 then
+          table.insert(result, pandoc.Str(' ('))
+          for k, v in pairs(kwargs) do
+            table.insert(result, pandoc.Str(osname(k)))
+            table.insert(result, pandoc.Str(': '))
+            table.insert(result, pandoc.Code(pandoc.utils.stringify(v)))
+            n_kwargs = n_kwargs - 1
+            if n_kwargs > 0 then
+              table.insert(result, pandoc.Str('; '))
+            end
+          end
+          table.insert(result, pandoc.Str(')'))
+        end
+      else
+        -- all kwargs
+        if n_kwargs == 0 then
+          error("kbd requires at least one argument")
+        else
+          for k, v in pairs(kwargs) do
+            table.insert(result, pandoc.Code(pandoc.utils.stringify(v)))
+            table.insert(result, pandoc.Str(' ('))
+            table.insert(result, pandoc.Str(osname(k)))
+            table.insert(result, pandoc.Str(')'))
+            n_kwargs = n_kwargs - 1
+            if n_kwargs > 0 then
+              table.insert(result, pandoc.Str(', '))
+            end
+          end
+        end
+      end
+      return result
+    end
+  end
+}

src/resources/extensions/quarto/kbd/resources/kbd.css

@@ -0,0 +1,2 @@
+kbd.kbd {
+}

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

@@ -0,0 +1,38 @@
+(() => {
+  function guessOS() {
+    const userAgent = window.navigator.userAgent;
+    if (userAgent.includes("Mac OS")) {
+      return {
+        name: "mac",
+      };
+    } else if (userAgent.includes("Windows")) {
+      return {
+        name: "win",
+      };
+    } else {
+      return {
+        name: "linux",
+      };
+    }
+  }
+  const os = guessOS();
+
+  // deno-lint-ignore no-window-prefix
+  window.addEventListener("DOMContentLoaded", (_) => {
+    for (const el of Array.from(document.querySelectorAll("kbd"))) {
+      el.classList.add("kbd");
+      if (el.dataset[os.name] !== undefined) {
+        el.innerText = el.dataset[os.name];
+      }
+      if (os.name === "mac") {
+        el.innerText = el.innerText
+          .replaceAll(/command-?/gi, "⌘")
+          .replaceAll(/cmd-?/gi, "⌘")
+          .replaceAll(/shift-?/gi, "⇧")
+          .replaceAll(/ctrl-?/gi, "⌃")
+          .replaceAll(/control-?/gi, "⌃")
+          .replaceAll(/option-?/gi, "⌥");
+      }
+    }
+  });
+})();

tests/docs/smoke-all/2022/11/19/kbd-test.qmd

@@ -0,0 +1,10 @@
+---
+title: test
+format: 
+  html: default
+  pdf: default
+---
+
+To foo, press {{< kbd Shift-Ctrl-P >}}. To bar, press {{< kbd Shift-Ctrl-P mac=Shift-Command-P >}}. To baz, press {{< kbd mac=Shift-Command-P win=Shift-Control-S linux=Shift-Ctrl-S >}}.
+
+To foo, press {{< kbd win=Shift-Ctrl-P >}}.