Skip to content

Commit 6684cf2

Browse files
reakaleekreakaleek
authored
Add kbd element (#1537)
* Add kbd * Styling adjustments * Revert req.md * Add test * Use keywords for special keys and allow combined keys * Fix formatting * Emit error when parsing fails * Use unknown key on error * Add aria-label * Fix heading casing * Add ability to show alternate keys with '|' * Adjust tests * Run prettier
1 parent a441454 commit 6684cf2

File tree

11 files changed

+755
-0
lines changed

11 files changed

+755
-0
lines changed

‎docs/_docset.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ toc:
9393
- file: frontmatter.md
9494
- file: icons.md
9595
- file: images.md
96+
- file: kbd.md
9697
- file: lists.md
9798
- file: line_breaks.md
9899
- file: links.md

‎docs/syntax/kbd.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Keyboard shortcuts
2+
3+
You can represent keyboard keys and shortcuts in your documentation using the `{kbd}` role. This is useful for showing keyboard commands and shortcuts in a visually consistent way. See the full list of [available keys](#available-keys).
4+
5+
## Basic usage
6+
7+
To display a keyboard key, use the syntax `` {kbd}`key-name` ``. For example, writing `` {kbd}`enter` `` will render as a styled keyboard key.
8+
9+
::::{tab-set}
10+
11+
:::{tab-item} Output
12+
Press {kbd}`enter` to submit.
13+
:::
14+
15+
:::{tab-item} Markdown
16+
```markdown
17+
Press {kbd}`enter` to submit.
18+
```
19+
:::
20+
21+
::::
22+
23+
## Combining keys
24+
25+
For keyboard shortcuts involving multiple keys, you can combine them within a single `{kbd}` role by separating the key names with a `+`. Keys are always visually separated, even when using the combined syntax.
26+
27+
::::{tab-set}
28+
29+
:::{tab-item} Output
30+
Use {kbd}`cmd+shift+enter` to execute the command.
31+
:::
32+
33+
:::{tab-item} Markdown
34+
```markdown
35+
Use {kbd}`cmd+shift+enter` to execute the command.
36+
```
37+
:::
38+
39+
::::
40+
41+
## Alternative keys
42+
43+
To display alternative keys for a shortcut, use `|` to separate the alternate keys within the same `{kbd}` role. This is useful for showing platform-specific shortcuts, such as `ctrl` on Windows and `cmd` on macOS.
44+
45+
::::{tab-set}
46+
47+
:::{tab-item} Output
48+
Use {kbd}`ctrl|cmd + c` to copy text.
49+
:::
50+
51+
:::{tab-item} Markdown
52+
```markdown
53+
Use {kbd}`ctrl|cmd + c` to copy text.
54+
```
55+
:::
56+
57+
::::
58+
59+
## Reserved characters
60+
61+
The `+` and `|` characters have special meaning for combining keys and specifying alternatives. To render them as literal keys, you must use their keyword equivalents.
62+
63+
- To display the {kbd}`plus` key, use `` `{kbd}`plus` ``.
64+
- To display the {kbd}`pipe` key, use `` `{kbd}`pipe` ``.
65+
66+
## Common shortcuts by platform
67+
68+
The platform-specific examples below demonstrate how to combine special keys and regular characters.
69+
70+
::::{tab-set}
71+
72+
:::{tab-item} Output
73+
74+
| Mac | Windows/Linux | Description |
75+
|------------------|-------------------|-----------------------------|
76+
| {kbd}`cmd+c` | {kbd}`ctrl+c` | Copy |
77+
| {kbd}`cmd+v` | {kbd}`ctrl+v` | Paste |
78+
| {kbd}`cmd+z` | {kbd}`ctrl+z` | Undo |
79+
| {kbd}`cmd+enter` | {kbd}`ctrl+enter` | Run a query |
80+
| {kbd}`cmd+/` | {kbd}`ctrl+/` | Comment or uncomment a line |
81+
82+
:::
83+
84+
:::{tab-item} Markdown
85+
```markdown
86+
| Mac | Windows/Linux | Description |
87+
|------------------|-------------------|-----------------------------|
88+
| {kbd}`cmd+c` | {kbd}`ctrl+c` | Copy |
89+
| {kbd}`cmd+v` | {kbd}`ctrl+v` | Paste |
90+
| {kbd}`cmd+z` | {kbd}`ctrl+z` | Undo |
91+
| {kbd}`cmd+enter` | {kbd}`ctrl+enter` | Run a query |
92+
| {kbd}`cmd+/` | {kbd}`ctrl+/` | Comment or uncomment a line |
93+
```
94+
:::
95+
96+
::::
97+
98+
## Available keys
99+
100+
The `{kbd}` role recognizes a set of special keywords for modifier, navigation, and function keys. Any other text will be rendered as a literal key.
101+
102+
Here is the full list of available keywords:
103+
104+
| Syntax | Rendered Output |
105+
|-------------------------|------------------|
106+
| `` {kbd}`shift` `` | {kbd}`shift` |
107+
| `` {kbd}`ctrl` `` | {kbd}`ctrl` |
108+
| `` {kbd}`alt` `` | {kbd}`alt` |
109+
| `` {kbd}`option` `` | {kbd}`option` |
110+
| `` {kbd}`cmd` `` | {kbd}`cmd` |
111+
| `` {kbd}`win` `` | {kbd}`win` |
112+
| `` {kbd}`up` `` | {kbd}`up` |
113+
| `` {kbd}`down` `` | {kbd}`down` |
114+
| `` {kbd}`left` `` | {kbd}`left` |
115+
| `` {kbd}`right` `` | {kbd}`right` |
116+
| `` {kbd}`space` `` | {kbd}`space` |
117+
| `` {kbd}`tab` `` | {kbd}`tab` |
118+
| `` {kbd}`enter` `` | {kbd}`enter` |
119+
| `` {kbd}`esc` `` | {kbd}`esc` |
120+
| `` {kbd}`backspace` `` | {kbd}`backspace` |
121+
| `` {kbd}`del` `` | {kbd}`delete` |
122+
| `` {kbd}`ins` `` | {kbd}`insert` |
123+
| `` {kbd}`pageup` `` | {kbd}`pageup` |
124+
| `` {kbd}`pagedown` `` | {kbd}`pagedown` |
125+
| `` {kbd}`home` `` | {kbd}`home` |
126+
| `` {kbd}`end` `` | {kbd}`end` |
127+
| `` {kbd}`f1` `` | {kbd}`f1` |
128+
| `` {kbd}`f2` `` | {kbd}`f2` |
129+
| `` {kbd}`f3` `` | {kbd}`f3` |
130+
| `` {kbd}`f4` `` | {kbd}`f4` |
131+
| `` {kbd}`f5` `` | {kbd}`f5` |
132+
| `` {kbd}`f6` `` | {kbd}`f6` |
133+
| `` {kbd}`f7` `` | {kbd}`f7` |
134+
| `` {kbd}`f8` `` | {kbd}`f8` |
135+
| `` {kbd}`f9` `` | {kbd}`f9` |
136+
| `` {kbd}`f10` `` | {kbd}`f10` |
137+
| `` {kbd}`f11` `` | {kbd}`f11` |
138+
| `` {kbd}`f12` `` | {kbd}`f12` |
139+
| `` {kbd}`plus` `` | {kbd}`plus` |
140+
| `` {kbd}`fn` `` | {kbd}`fn` |
141+
| `` {kbd}`pipe` `` | {kbd}`pipe` |

‎src/Elastic.Documentation.Site/Assets/markdown/kbd.css

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
@layer components {
2+
.markdown-content {
3+
kbd.kbd {
4+
@apply bg-grey-20 text-grey-100 border-grey-50 shadow-grey-50 relative top-[-2px] inline-flex min-w-[18px] cursor-default items-center gap-1.5 rounded-sm border px-1.5 pt-[3px] pb-[2px] text-center align-middle font-mono text-sm leading-none capitalize shadow-[0_2px_0_1px];
5+
}
6+
7+
kbd.kbd .kbd-separator {
8+
@apply bg-grey-100 mx-1 inline-block self-stretch;
9+
width: 1px;
10+
/*height: .8em;*/
11+
transform: translateY(-1px) rotate(30deg);
12+
}
13+
14+
kbd.kbd .kbd-space {
15+
@apply w-0;
16+
}
17+
}
18+
}

‎src/Elastic.Documentation.Site/Assets/styles.css

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
@import './markdown/tabs.css';
1010
@import './markdown/code.css';
1111
@import './markdown/icons.css';
12+
@import './markdown/kbd.css';
1213
@import './copybutton.css';
1314
@import './markdown/admonition.css';
1415
@import './markdown/dropdown.css';
@@ -227,3 +228,9 @@ body {
227228
.tippy-content {
228229
white-space: pre-line;
229230
}
231+
232+
.icon,
233+
.icon > * {
234+
user-select: none;
235+
pointer-events: none;
236+
}

‎src/Elastic.Markdown/Myst/MarkdownParser.cs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
using Elastic.Markdown.Myst.Renderers;
1616
using Elastic.Markdown.Myst.Roles.AppliesTo;
1717
using Elastic.Markdown.Myst.Roles.Icons;
18+
using Elastic.Markdown.Myst.Roles.Kbd;
1819
using Markdig;
1920
using Markdig.Extensions.EmphasisExtras;
2021
using Markdig.Parsers;
@@ -147,6 +148,7 @@ public static MarkdownPipeline Pipeline
147148
.UseEmphasisExtras(EmphasisExtraOptions.Default)
148149
.UseInlineAppliesTo()
149150
.UseInlineIcons()
151+
.UseInlineKbd()
150152
.UseSubstitution()
151153
.UseComments()
152154
.UseYamlFrontMatter()

0 commit comments

Comments
 (0)