⌨️ Add keyboard role (#989)

Co-authored-by: Rowan Cockett <rowanc1@gmail.com>

.changeset/tasty-ducks-change.md

@@ -0,0 +1,5 @@
+---
+"myst-roles": minor
+---
+
+Add `kbd`/`keyboard` role

docs/typography.md

@@ -91,6 +91,20 @@ H{sub}`2`O, and 4{sup}`th` of July
 
 % For chemicals you can use the {chem}`H2O`
 
+(keyboard-input)=
+
+## Keyboard Input
+
+To denote textual _user_ input from a keyboard, such as {kbd}`Ctrl` + {kbd}`Space`, you can use the `kbd`[^long-names-kbd] role, e.g.
+
+```{myst}
+{kbd}`Ctrl` + {kbd}`Space`
+```
+
+[^long-names-kbd]: This role is also accessible through `keyboard`.
+
+
+
 (abbr-role)=
 
 ## Abbreviations

packages/myst-parser/tests/roles/keyboard.yml

@@ -0,0 +1,53 @@
+title: keyboard roles
+cases:
+  - title: keyboard role parses
+    markdown: '{keyboard}`Ctrl` + {keyboard}`Space`'
+    mdast:
+      type: root
+      children:
+        - type: paragraph
+          children:
+            - type: mystRole
+              name: keyboard
+              value: Ctrl
+              children:
+                - type: keyboard
+                  children:
+                    - type: text
+                      value: Ctrl
+            - type: text
+              value: ' + '
+            - type: mystRole
+              name: keyboard
+              value: Space
+              children:
+                - type: keyboard
+                  children:
+                    - type: text
+                      value: Space
+
+  - title: kbd role parses
+    markdown: '{kbd}`Ctrl` + {kbd}`Space`'
+    mdast:
+      type: root
+      children:
+        - type: paragraph
+          children:
+            - type: mystRole
+              name: kbd
+              value: Ctrl
+              children:
+                - type: keyboard
+                  children:
+                    - type: text
+                      value: Ctrl
+            - type: text
+              value: ' + '
+            - type: mystRole
+              name: kbd
+              value: Space
+              children:
+                - type: keyboard
+                  children:
+                    - type: text
+                      value: Space

packages/myst-roles/src/index.ts

@@ -13,6 +13,7 @@ import { smallcapsRole } from './smallcaps.js';
 import { subscriptRole } from './subscript.js';
 import { superscriptRole } from './superscript.js';
 import { underlineRole } from './underline.js';
+import { keyboardRole } from './keyboard.js';
 
 export const defaultRoles = [
   abbreviationRole,
@@ -30,6 +31,7 @@ export const defaultRoles = [
   subscriptRole,
   superscriptRole,
   underlineRole,
+  keyboardRole,
 ];
 export { abbreviationRole } from './abbreviation.js';
 export { chemRole } from './chem.js';
@@ -45,3 +47,4 @@ export { smallcapsRole } from './smallcaps.js';
 export { subscriptRole } from './subscript.js';
 export { superscriptRole } from './superscript.js';
 export { underlineRole } from './underline.js';
+export { keyboardRole } from './keyboard.js';

packages/myst-roles/src/keyboard.ts

@@ -0,0 +1,18 @@
+import type { GenericNode, RoleSpec } from 'myst-common';
+
+export const keyboardRole: RoleSpec = {
+  name: 'keyboard',
+  alias: ['kbd'],
+  body: {
+    type: String,
+    required: true,
+  },
+  run(data) {
+    const body = data.body as string;
+    const node: GenericNode = {
+      type: 'keyboard',
+      children: [{ type: 'text', value: body }],
+    };
+    return [node];
+  },
+};