diff --git a/.changeset/tasty-ducks-change.md b/.changeset/tasty-ducks-change.md new file mode 100644 index 000000000..33aaa984a --- /dev/null +++ b/.changeset/tasty-ducks-change.md @@ -0,0 +1,5 @@ +--- +"myst-roles": minor +--- + +Add `kbd`/`keyboard` role diff --git a/docs/typography.md b/docs/typography.md index cd94b5179..225008fec 100644 --- a/docs/typography.md +++ b/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 diff --git a/packages/myst-parser/tests/roles/keyboard.yml b/packages/myst-parser/tests/roles/keyboard.yml new file mode 100644 index 000000000..2ce150738 --- /dev/null +++ b/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 diff --git a/packages/myst-roles/src/index.ts b/packages/myst-roles/src/index.ts index f120e42fe..a1de30948 100644 --- a/packages/myst-roles/src/index.ts +++ b/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'; diff --git a/packages/myst-roles/src/keyboard.ts b/packages/myst-roles/src/keyboard.ts new file mode 100644 index 000000000..00ea90435 --- /dev/null +++ b/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]; + }, +};