Add ability to disable OS detection in kbd shortcode?

[andrewheiss]

Description

The kbd shortcode is really helpful for formatting keyboard shortcuts across operating systems.

In Javascript-enabled outputs, it uses some fancy logic to replace keys with their macOS equivalents, so that Command becomes ⌘, and so on.

This is great for documents that can adapt to the reader's OS. For teaching with slideshows, though, it's a little trickier because the Javascript OS-detection can't be disabled.

For instance, suppose I have this revealjs slidehow:

---
title: "Cross-platform kbd"
format: revealjs
---

## Rendering

To render:

- macOS: {{< kbd Command-Shift-K >}}
- Windows: {{< kbd Ctrl-Shift-K >}}

If I'm showing the slides in a classroom setting using a computer running macOS, the Windows shortcut displays as ^⇧K

Similarly, if I'm showing the slides from a computer with Windows, the macOS shortcut displays as Command-Shift-K

As far as I can tell, there's no way to use the kbd shortcode to get output like this:

It might be helpful for teaching purposes to have a setting/option for the kbd shortcode to disable to OS detection

[mcanouil]

I faced the issue as well.
A quick proof of concept to display the value if and only if only one OS is explicitly set:

---
format: html
---

{{< kbd win=Ctrl-Shift-P >}} or {{< kbd mac=Cmd-Shift-P >}}

Replace index_files/libs/quarto-contrib/kbd/kbd.js with the code below:

Code without diff markers

(() => {
  function guessOS() {
    const userAgent = window.navigator.userAgent;
    if (userAgent.includes("Mac OS")) {
      return {
        name: "mac",
      };
    } else if (userAgent.includes("Windows")) {
      return {
        name: "windows",
      };
    } else {
      return {
        name: "linux",
      };
    }
  }
  const os = guessOS();

  const macosModifiers = {
    "command": "⌘",
    "cmd": "⌘",
    "shift": "⇧",
    "ctrl": "⌃",
    "control": "⌃",
    "option": "⌥",
  };
  const keyRegex = /^[^\s]+$/;
  // use a non-capturing group to avoid capturing the key names

  const macosModifiersRegex = new RegExp(
    // use a non-capturing group to avoid capturing the key names
    `^(?:${Object.keys(macosModifiers).join("|")})-`,
    "gi"
  );
  const shortcutParses = (text) => {
    text = text.toLocaleLowerCase();
    while (text.match(macosModifiersRegex)) {
      text = text.replace(macosModifiersRegex, "");
    }
    return text.match(keyRegex) !== null;
  }

  // deno-lint-ignore no-window-prefix
  window.addEventListener("DOMContentLoaded", (_) => {
    for (const el of Array.from(document.querySelectorAll("kbd"))) {
      el.classList.add("kbd");
      // Always check for OS-specific dataset keys
      const osKeys = ["windows", "linux", "mac"];
      const presentKeys = osKeys.filter(key => el.dataset[key] !== undefined);
      if (presentKeys.length === 1) {
        el.innerText = el.dataset[presentKeys[0]];
      } else if (el.dataset[os.name] !== undefined) {
        el.innerText = el.dataset[os.name];
      }
      // Only apply macosModifiers if the value comes from data-mac
      let valueSource = null;
      if (presentKeys.length === 1) {
        valueSource = presentKeys[0];
      } else if (el.dataset[os.name] !== undefined) {
        valueSource = os.name;
      }
      if (valueSource === "mac" && shortcutParses(el.innerText)) {
        el.classList.add("mac");
        for (const [key, value] of Object.entries(macosModifiers)) {
          el.innerText = el.innerText.replaceAll(new RegExp(`${key}-`, "gi"), value);
        }
        el.innerText = el.innerText.toLocaleUpperCase();
      }
    }
  });
})();

(() => {
  function guessOS() {
    const userAgent = window.navigator.userAgent;
    if (userAgent.includes("Mac OS")) {
      return {
        name: "mac",
      };
    } else if (userAgent.includes("Windows")) {
      return {
        name: "windows",
      };
    } else {
      return {
        name: "linux",
      };
    }
  }
  const os = guessOS();

  const macosModifiers = {
    "command": "⌘",
    "cmd": "⌘",
    "shift": "⇧",
    "ctrl": "⌃",
    "control": "⌃",
    "option": "⌥",
  };
  const keyRegex = /^[^\s]+$/;
  // use a non-capturing group to avoid capturing the key names

  const macosModifiersRegex = new RegExp(
    // use a non-capturing group to avoid capturing the key names
    `^(?:${Object.keys(macosModifiers).join("|")})-`,
    "gi"
  );
  const shortcutParses = (text) => {
    text = text.toLocaleLowerCase();
    while (text.match(macosModifiersRegex)) {
      text = text.replace(macosModifiersRegex, "");
    }
    return text.match(keyRegex) !== null;
  }

  // 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) {
+     // Always check for OS-specific dataset keys
+     const osKeys = ["windows", "linux", "mac"];
+      const presentKeys = osKeys.filter(key => el.dataset[key] !== undefined);
+     if (presentKeys.length === 1) {
+       el.innerText = el.dataset[presentKeys[0]];
+     } else if (el.dataset[os.name] !== undefined) {
        el.innerText = el.dataset[os.name];
      }
+     // Only apply macosModifiers if the value comes from data-mac
+     let valueSource = null;
+     if (presentKeys.length === 1) {
+       valueSource = presentKeys[0];
+     } else if (el.dataset[os.name] !== undefined) {
+       valueSource = os.name;
+     }
+     if (valueSource === "mac" && shortcutParses(el.innerText)) {
-     if (os.name === "mac" && shortcutParses(el.innerText)) {
        el.classList.add("mac");
        for (const [key, value] of Object.entries(macosModifiers)) {
          el.innerText = el.innerText.replaceAll(new RegExp(`${key}-`, "gi"), value);
        }
        el.innerText = el.innerText.toLocaleUpperCase();
      }
    }
  });
})();

I'll eventually make a PR with this if deemed suitable (no JS expert at all).

[mcanouil]

Note that the "title", used as tooltip, displays all shortcuts (when defined).

[cscheid]

Tracking here.