Add kbd element

docs/_docset.yml

@@ -93,6 +93,7 @@ toc:
       - file: frontmatter.md
       - file: icons.md
       - file: images.md
+      - file: kbd.md
       - file: lists.md
       - file: line_breaks.md
       - file: links.md

docs/syntax/kbd.md

@@ -0,0 +1,117 @@
+# Keyboard shortcuts
+
+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.
+
+## Basic usage
+
+To display a keyboard key, use the syntax `` {kbd}`key-name` ``. For example, writing `` {kbd}`Enter` `` will render as a styled keyboard key.
+
+::::{tab-set}
+
+:::{tab-item} Output
+Press {kbd}`Enter` to submit.
+:::
+
+:::{tab-item} Markdown
+```markdown
+Press {kbd}`Enter` to submit.
+```
+:::
+
+::::
+
+## Keyboard combinations
+
+You can represent keyboard combinations by joining multiple `{kbd}` roles with a plus sign (+).
+
+::::{tab-set}
+
+:::{tab-item} Output
+{kbd}`ctrl` + {kbd}`C` to copy text.
+
+{kbd}`Shift` + {kbd}`Alt` + {kbd}`F` to format the document.
+:::
+
+:::{tab-item} Markdown
+```markdown
+{kbd}`Ctrl` + {kbd}`C` to copy text.
+
+{kbd}`Shift` + {kbd}`Alt` + {kbd}`F` to format the document.
+```
+:::
+
+::::
+
+## Common shortcuts by platform
+
+Here are some common keyboard shortcuts across different platforms:
+
+::::{tab-set}
+
+:::{tab-item} Output
+| Mac                     | Windows/Linux              | Description                 |
+|-------------------------|----------------------------|-----------------------------|
+| {kbd}`⌘` + {kbd}`C`     | {kbd}`Ctrl` + {kbd}`C`     | Copy                        |
+| {kbd}`⌘` + {kbd}`V`     | {kbd}`Ctrl` + {kbd}`V`     | Paste                       |
+| {kbd}`⌘` + {kbd}`Z`     | {kbd}`Ctrl` + {kbd}`Z`     | Undo                        |
+| {kbd}`⌘` + {kbd}`Enter` | {kbd}`Ctrl` + {kbd}`Enter` | Run a query                 |
+| {kbd}`⌘` + {kbd}`/`     | {kbd}`Ctrl` + {kbd}`/`     | Comment or uncomment a line |
+:::
+
+:::{tab-item} Markdown
+```markdown
+| Mac                     | Windows/Linux              | Description                 |
+|-------------------------|----------------------------|-----------------------------|
+| {kbd}`⌘` + {kbd}`C`     | {kbd}`Ctrl` + {kbd}`C`     | Copy                        |
+| {kbd}`⌘` + {kbd}`V`     | {kbd}`Ctrl` + {kbd}`V`     | Paste                       |
+| {kbd}`⌘` + {kbd}`Z`     | {kbd}`Ctrl` + {kbd}`Z`     | Undo                        |
+| {kbd}`⌘` + {kbd}`Enter` | {kbd}`Ctrl` + {kbd}`Enter` | Run a query                 |
+| {kbd}`⌘` + {kbd}`/`     | {kbd}`Ctrl` + {kbd}`/`     | Comment or uncomment a line |
+```
+:::
+
+::::
+
+## Special keys
+
+Some commonly used special keys:
+
+::::{tab-set}
+
+:::{tab-item} Output
+| Symbol    | Key Description  |
+|-----------|------------------|
+| {kbd}`⌘`  | Command (Mac)    |
+| {kbd}`⌥`  | Option/Alt (Mac) |
+| {kbd}`⇧`  | Shift            |
+| {kbd}`⌃`  | Control          |
+| {kbd}`↩`  | Return/Enter     |
+| {kbd}`⌫`  | Delete/Backspace |
+| {kbd}`⇥`  | Tab              |
+| {kbd}`↑`  | Up Arrow         |
+| {kbd}`↓`  | Down Arrow       |
+| {kbd}`←`  | Left Arrow       |
+| {kbd}`→`  | Right Arrow      |
+| {kbd}`⎋`  | Escape           |
+:::
+
+:::{tab-item} Markdown
+```markdown
+| Symbol    | Key Description  |
+|-----------|------------------|
+| {kbd}`⌘`  | Command (Mac)    |
+| {kbd}`⌥`  | Option/Alt (Mac) |
+| {kbd}`⇧`  | Shift            |
+| {kbd}`⌃`  | Control          |
+| {kbd}`↩`  | Return/Enter     |
+| {kbd}`⌫`  | Delete/Backspace |
+| {kbd}`⇥`  | Tab              |
+| {kbd}`↑`  | Up Arrow         |
+| {kbd}`↓`  | Down Arrow       |
+| {kbd}`←`  | Left Arrow       |
+| {kbd}`→`  | Right Arrow      |
+| {kbd}`⎋`  | Escape           |
+```
+:::
+
+::::

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

@@ -0,0 +1,5 @@
+@layer components {
+	kbd {
+		@apply bg-grey-20 text-grey-100 border-grey-50 shadow-grey-50 relative top-[-2px] inline-block min-w-[18px] cursor-default rounded-sm border px-1 pt-[3px] pb-[2px] text-center align-middle font-mono text-sm leading-none capitalize shadow-[0_2px_0_1px];
+	}
+}

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

@@ -9,6 +9,7 @@
 @import './markdown/tabs.css';
 @import './markdown/code.css';
 @import './markdown/icons.css';
+@import './markdown/kbd.css';
 @import './copybutton.css';
 @import './markdown/admonition.css';
 @import './markdown/dropdown.css';
@@ -227,3 +228,9 @@ body {
 .tippy-content {
 	white-space: pre-line;
 }
+
+.icon,
+.icon > * {
+	user-select: none;
+	pointer-events: none;
+}

src/Elastic.Markdown/Myst/MarkdownParser.cs

@@ -15,6 +15,7 @@
 using Elastic.Markdown.Myst.Renderers;
 using Elastic.Markdown.Myst.Roles.AppliesTo;
 using Elastic.Markdown.Myst.Roles.Icons;
+using Elastic.Markdown.Myst.Roles.Kbd;
 using Markdig;
 using Markdig.Extensions.EmphasisExtras;
 using Markdig.Parsers;
@@ -147,6 +148,7 @@ public static MarkdownPipeline Pipeline
 				.UseEmphasisExtras(EmphasisExtraOptions.Default)
 				.UseInlineAppliesTo()
 				.UseInlineIcons()
+				.UseInlineKbd()
 				.UseSubstitution()
 				.UseComments()
 				.UseYamlFrontMatter()

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

@@ -0,0 +1,17 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System;
+using Markdig.Parsers;
+
+namespace Elastic.Markdown.Myst.Roles.Kbd;
+
+public class KbdParser : RoleParser<KbdRole>
+{
+
+	protected override KbdRole CreateRole(string role, string content, InlineProcessor parserContext) =>
+		new(role, content);
+
+	protected override bool Matches(ReadOnlySpan<char> role) => role is "{kbd}";
+}

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

@@ -0,0 +1,13 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Diagnostics;
+
+namespace Elastic.Markdown.Myst.Roles.Kbd;
+
+[DebuggerDisplay("{GetType().Name} Line: {Line}, Role: {Role}, Content: {Content}")]
+public class KbdRole(string role, string content) : RoleLeaf(role, content)
+{
+	public string KeyboardText { get; } = content;
+}

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

@@ -0,0 +1,38 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using Markdig;
+using Markdig.Parsers.Inlines;
+using Markdig.Renderers;
+using Markdig.Renderers.Html;
+using Markdig.Renderers.Html.Inlines;
+
+namespace Elastic.Markdown.Myst.Roles.Kbd;
+
+public class KbdRoleHtmlRenderer : HtmlObjectRenderer<KbdRole>
+{
+	protected override void Write(HtmlRenderer renderer, KbdRole role)
+	{
+		_ = renderer.Write("<kbd>");
+		_ = renderer.Write(role.KeyboardText);
+		_ = renderer.Write("</kbd>");
+	}
+}
+
+public static class InlineKbdExtensions
+{
+	public static MarkdownPipelineBuilder UseInlineKbd(this MarkdownPipelineBuilder pipeline)
+	{
+		pipeline.Extensions.AddIfNotAlready<InlineKbdExtension>();
+		return pipeline;
+	}
+}
+
+public class InlineKbdExtension : IMarkdownExtension
+{
+	public void Setup(MarkdownPipelineBuilder pipeline) => _ = pipeline.InlineParsers.InsertBefore<CodeInlineParser>(new KbdParser());
+
+	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) =>
+		renderer.ObjectRenderers.InsertBefore<CodeInlineRenderer>(new KbdRoleHtmlRenderer());
+}