Skip to content

Commit ea0d057

Browse files
reakaleekreakaleek
committed
Add kbd
1 parent ad81fa4 commit ea0d057

File tree

9 files changed

+199
-3
lines changed

9 files changed

+199
-3
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: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
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.
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+
## Keyboard combinations
24+
25+
You can represent keyboard combinations by joining multiple `{kbd}` roles with a plus sign (+).
26+
27+
::::{tab-set}
28+
29+
:::{tab-item} Output
30+
{kbd}`ctrl` + {kbd}`C` to copy text.
31+
32+
{kbd}`Shift` + {kbd}`Alt` + {kbd}`F` to format the document.
33+
:::
34+
35+
:::{tab-item} Markdown
36+
```markdown
37+
{kbd}`Ctrl` + {kbd}`C` to copy text.
38+
39+
{kbd}`Shift` + {kbd}`Alt` + {kbd}`F` to format the document.
40+
```
41+
:::
42+
43+
::::
44+
45+
## Common shortcuts by platform
46+
47+
Here are some common keyboard shortcuts across different platforms:
48+
49+
::::{tab-set}
50+
51+
:::{tab-item} Output
52+
| Mac | Windows/Linux | Description |
53+
|-------------------------|----------------------------|-----------------------------|
54+
| {kbd}`⌘` + {kbd}`C` | {kbd}`Ctrl` + {kbd}`C` | Copy |
55+
| {kbd}`⌘` + {kbd}`V` | {kbd}`Ctrl` + {kbd}`V` | Paste |
56+
| {kbd}`⌘` + {kbd}`Z` | {kbd}`Ctrl` + {kbd}`Z` | Undo |
57+
| {kbd}`⌘` + {kbd}`Enter` | {kbd}`Ctrl` + {kbd}`Enter` | Run a query |
58+
| {kbd}`⌘` + {kbd}`/` | {kbd}`Ctrl` + {kbd}`/` | Comment or uncomment a line |
59+
:::
60+
61+
:::{tab-item} Markdown
62+
```markdown
63+
| Mac | Windows/Linux | Description |
64+
|-------------------------|----------------------------|-----------------------------|
65+
| {kbd}`⌘` + {kbd}`C` | {kbd}`Ctrl` + {kbd}`C` | Copy |
66+
| {kbd}`⌘` + {kbd}`V` | {kbd}`Ctrl` + {kbd}`V` | Paste |
67+
| {kbd}`⌘` + {kbd}`Z` | {kbd}`Ctrl` + {kbd}`Z` | Undo |
68+
| {kbd}`⌘` + {kbd}`Enter` | {kbd}`Ctrl` + {kbd}`Enter` | Run a query |
69+
| {kbd}`⌘` + {kbd}`/` | {kbd}`Ctrl` + {kbd}`/` | Comment or uncomment a line |
70+
```
71+
:::
72+
73+
::::
74+
75+
## Special keys
76+
77+
Some commonly used special keys:
78+
79+
::::{tab-set}
80+
81+
:::{tab-item} Output
82+
| Symbol | Key Description |
83+
|-----------|------------------|
84+
| {kbd}`⌘` | Command (Mac) |
85+
| {kbd}`⌥` | Option/Alt (Mac) |
86+
| {kbd}`⇧` | Shift |
87+
| {kbd}`⌃` | Control |
88+
| {kbd}`↩` | Return/Enter |
89+
| {kbd}`⌫` | Delete/Backspace |
90+
| {kbd}`⇥` | Tab |
91+
| {kbd}`↑` | Up Arrow |
92+
| {kbd}`↓` | Down Arrow |
93+
| {kbd}`←` | Left Arrow |
94+
| {kbd}`→` | Right Arrow |
95+
| {kbd}`⎋` | Escape |
96+
:::
97+
98+
:::{tab-item} Markdown
99+
```markdown
100+
| Symbol | Key Description |
101+
|-----------|------------------|
102+
| {kbd}`⌘` | Command (Mac) |
103+
| {kbd}`⌥` | Option/Alt (Mac) |
104+
| {kbd}`⇧` | Shift |
105+
| {kbd}`⌃` | Control |
106+
| {kbd}`↩` | Return/Enter |
107+
| {kbd}`⌫` | Delete/Backspace |
108+
| {kbd}`⇥` | Tab |
109+
| {kbd}`↑` | Up Arrow |
110+
| {kbd}`↓` | Down Arrow |
111+
| {kbd}`←` | Left Arrow |
112+
| {kbd}`→` | Right Arrow |
113+
| {kbd}`⎋` | Escape |
114+
```
115+
:::
116+
117+
::::

‎docs/testing/req.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,12 @@ stack: preview 9.0, ga 9.1
1515

1616
{applies_to}`stack: preview 9.0` This tutorial is based on Elasticsearch 9.0.
1717
This tutorial is based on Elasticsearch 9.0. This tutorial is based on Elasticsearch 9.0.
18-
This tutorial is based on Elasticsearch 9.0.
19-
20-
what
18+
This tutorial is {kbd}`⌘` + {kbd}`/` based on Elasticsearch 9.0.
2119

20+
| Mac | Windows/Linux | Description |
21+
|-------------------------|----------------------------|-----------------------------|
22+
| {kbd}`⌘` + {kbd}`Enter` | {kbd}`Ctrl` + {kbd}`Enter` | Run a query |
23+
| {kbd}`⌘` + {kbd}`/` | {kbd}`Ctrl` + {kbd}`/` | Comment or uncomment a line |
2224

2325
To follow this tutorial you will need to install the following components:
2426

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
@layer components {
2+
kbd {
3+
@apply bg-grey-20 text-grey-100 border-grey-60 shadow-grey-60 relative top-[-2px] cursor-default rounded-sm border px-1 py-0.5 text-center font-mono text-xs leading-none capitalize shadow-[0_2px_0_1px];
4+
}
5+
}

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

Lines changed: 1 addition & 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';

‎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()

‎src/Elastic.Markdown/Myst/Roles/Kbd/KbdParser.cs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Licensed to Elasticsearch B.V under one or more agreements.
2+
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
3+
// See the LICENSE file in the project root for more information
4+
5+
using System;
6+
using Markdig.Parsers;
7+
8+
namespace Elastic.Markdown.Myst.Roles.Kbd;
9+
10+
public class KbdParser : RoleParser<KbdRole>
11+
{
12+
13+
protected override KbdRole CreateRole(string role, string content, InlineProcessor parserContext) =>
14+
new(role, content);
15+
16+
protected override bool Matches(ReadOnlySpan<char> role) => role is "{kbd}";
17+
}

‎src/Elastic.Markdown/Myst/Roles/Kbd/KbdRole.cs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Licensed to Elasticsearch B.V under one or more agreements.
2+
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
3+
// See the LICENSE file in the project root for more information
4+
5+
using System.Diagnostics;
6+
7+
namespace Elastic.Markdown.Myst.Roles.Kbd;
8+
9+
[DebuggerDisplay("{GetType().Name} Line: {Line}, Role: {Role}, Content: {Content}")]
10+
public class KbdRole(string role, string content) : RoleLeaf(role, content)
11+
{
12+
public string KeyboardText { get; } = content;
13+
}

‎src/Elastic.Markdown/Myst/Roles/Kbd/KbdRoleRenderer.cs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Licensed to Elasticsearch B.V under one or more agreements.
2+
// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
3+
// See the LICENSE file in the project root for more information
4+
5+
using Markdig;
6+
using Markdig.Parsers.Inlines;
7+
using Markdig.Renderers;
8+
using Markdig.Renderers.Html;
9+
using Markdig.Renderers.Html.Inlines;
10+
11+
namespace Elastic.Markdown.Myst.Roles.Kbd;
12+
13+
public class KbdRoleHtmlRenderer : HtmlObjectRenderer<KbdRole>
14+
{
15+
protected override void Write(HtmlRenderer renderer, KbdRole role)
16+
{
17+
_ = renderer.Write("<kbd>");
18+
_ = renderer.Write(role.KeyboardText);
19+
_ = renderer.Write("</kbd>");
20+
}
21+
}
22+
23+
public static class InlineKbdExtensions
24+
{
25+
public static MarkdownPipelineBuilder UseInlineKbd(this MarkdownPipelineBuilder pipeline)
26+
{
27+
pipeline.Extensions.AddIfNotAlready<InlineKbdExtension>();
28+
return pipeline;
29+
}
30+
}
31+
32+
public class InlineKbdExtension : IMarkdownExtension
33+
{
34+
public void Setup(MarkdownPipelineBuilder pipeline) => _ = pipeline.InlineParsers.InsertBefore<CodeInlineParser>(new KbdParser());
35+
36+
public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) =>
37+
renderer.ObjectRenderers.InsertBefore<CodeInlineRenderer>(new KbdRoleHtmlRenderer());
38+
}

0 commit comments

Comments
 (0)