Add Button directive

docs/_docset.yml

@@ -1,3 +1,3 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
@@ -88,6 +88,7 @@
       - file: applies.md
       - file: applies-switch.md
       - file: automated_settings.md
+      - file: buttons.md
       - file: code.md
       - file: comments.md
       - file: conditionals.md

docs/syntax/buttons.md

@@ -0,0 +1,232 @@
+# Buttons
+
+Buttons provide styled link elements for calls to action in documentation. Use buttons to highlight important navigation points, downloads, or external resources.
+
+:::{button}
+[Getting Started](docs-content://get-started/introduction.md)
+:::
+
+## Basic button
+
+A button wraps a standard Markdown link with button styling:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+:::{button}
+[Syntax Guide](index.md)
+:::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+:::{button}
+[Get Started](/get-started)
+:::
+```
+::::::
+:::::::
+
+## Button types
+
+Two button variants are available:
+
+- **Primary** (default): Filled blue background with white text, used for main calls to action.
+- **Secondary**: Blue border with transparent background, used for secondary actions.
+
+:::::::{tab-set}
+::::::{tab-item} Output
+::::{button-group}
+:::{button}
+[Quick Reference](quick-ref.md)
+:::
+:::{button}
+:type: secondary
+[Syntax Guide](index.md)
+:::
+::::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+::::{button-group}
+:::{button}
+[Primary Action](/primary)
+:::
+:::{button}
+:type: secondary
+[Secondary Action](/secondary)
+:::
+::::
+```
+::::::
+:::::::
+
+## Button groups
+
+Use the `{button-group}` directive to display multiple buttons in a row:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+::::{button-group}
+:::{button}
+[Admonitions](admonitions.md)
+:::
+:::{button}
+:type: secondary
+[Dropdowns](dropdowns.md)
+:::
+::::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+::::{button-group}
+:::{button}
+[Elastic Fundamentals](/get-started)
+:::
+:::{button}
+:type: secondary
+[Upgrade Versions](/deploy-manage/upgrade)
+:::
+::::
+```
+::::::
+:::::::
+
+## Alignment
+
+### Single button alignment
+
+Control the horizontal alignment of standalone buttons with the `:align:` property:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+:::{button}
+:align: left
+[Links](links.md)
+:::
+
+:::{button}
+:align: center
+[Images](images.md)
+:::
+
+:::{button}
+:align: right
+[Tables](tables.md)
+:::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+:::{button}
+:align: left
+[Left (default)](/example)
+:::
+
+:::{button}
+:align: center
+[Center](/example)
+:::
+
+:::{button}
+:align: right
+[Right](/example)
+:::
+```
+::::::
+:::::::
+
+### Button group alignment
+
+Button groups also support the `:align:` property:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+::::{button-group}
+:align: center
+:::{button}
+[Code Blocks](code.md)
+:::
+:::{button}
+:type: secondary
+[Tabs](tabs.md)
+:::
+::::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+::::{button-group}
+:align: center
+:::{button}
+[Centered Group](/example)
+:::
+:::{button}
+:type: secondary
+[Second Button](/example)
+:::
+::::
+```
+::::::
+:::::::
+
+## External links
+
+External links (URLs outside elastic.co) automatically open in a new tab, just like regular links:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+:::{button}
+[Visit GitHub](https://github.com/elastic)
+:::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+:::{button}
+[Visit GitHub](https://github.com/elastic)
+:::
+```
+::::::
+:::::::
+
+External links include `target="_blank"` and `rel="noopener noreferrer"` attributes for security.
+
+## Cross-repository links
+
+Buttons support [cross-repository links](links.md#cross-repository-links) using the `scheme://path` syntax:
+
+:::::::{tab-set}
+::::::{tab-item} Output
+:::{button}
+[Getting Started Guide](docs-content://get-started/introduction.md)
+:::
+::::::
+
+::::::{tab-item} Markdown
+```markdown
+:::{button}
+[Getting Started Guide](docs-content://get-started/introduction.md)
+:::
+```
+::::::
+:::::::
+
+Cross-links are resolved at build time to their target URLs in the documentation site.
+
+## Properties reference
+
+### Button properties
+
+| Property | Required | Default | Description |
+|----------|----------|---------|-------------|
+| (content) | Yes | - | A Markdown link `[text](url)` that becomes the button. |
+| `:type:` | No | `primary` | Button variant: `primary` (filled) or `secondary` (outlined). |
+| `:align:` | No | `left` | Horizontal alignment for standalone buttons: `left`, `center`, or `right`. |
+
+### Button group properties
+
+| Property | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `:align:` | No | `left` | Horizontal alignment of the button group: `left`, `center`, or `right`. |

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

@@ -0,0 +1,75 @@
+/* Button directive styles */
+
+/* Button wrapper for standalone buttons */
+.doc-button-wrapper {
+	display: flex;
+	margin-block: 1rem;
+}
+
+.doc-button-wrapper.doc-button-left {
+	justify-content: flex-start;
+}
+
+.doc-button-wrapper.doc-button-center {
+	justify-content: center;
+}
+
+.doc-button-wrapper.doc-button-right {
+	justify-content: flex-end;
+}
+
+/* Button group container */
+.doc-button-group {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.75rem;
+	margin-block: 1rem;
+}
+
+.doc-button-group.doc-button-group-left {
+	justify-content: flex-start;
+}
+
+.doc-button-group.doc-button-group-center {
+	justify-content: center;
+}
+
+.doc-button-group.doc-button-group-right {
+	justify-content: flex-end;
+}
+
+/* Button item wrapper for buttons inside groups */
+.doc-button-item {
+	display: inline-flex;
+}
+
+/* Primary button - exact same Tailwind classes as _LandingPage.cshtml */
+.doc-button-primary a {
+	@apply bg-blue-elastic hover:bg-blue-elastic-110 focus:ring-blue-elastic-50 flex h-10 cursor-pointer items-center justify-center rounded-sm px-6 py-2 font-sans text-base font-semibold text-nowrap text-white no-underline select-none hover:text-white focus:ring-4 focus:outline-none;
+}
+
+/* Secondary button - exact same Tailwind classes as _LandingPage.cshtml */
+.doc-button-secondary a {
+	@apply text-blue-elastic hover:text-blue-elastic-100 border-blue-elastic hover:border-blue-elastic-100 focus:ring-blue-elastic-50 flex h-10 cursor-pointer items-center justify-center rounded-sm border-2 px-6 py-2 text-center font-sans text-base font-semibold text-nowrap no-underline focus:ring-4 focus:outline-none;
+}
+
+/* Remove external link icon from buttons */
+.doc-button-wrapper a[target='_blank']::after,
+.doc-button-item a[target='_blank']::after {
+	content: none !important;
+}
+
+/* Responsive adjustments */
+@media (max-width: 640px) {
+	.doc-button-group {
+		flex-direction: column;
+	}
+
+	.doc-button-item {
+		width: 100%;
+	}
+
+	.doc-button-item a {
+		width: 100%;
+	}
+}

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

@@ -24,6 +24,7 @@
 @import './modal.css';
 @import './archive.css';
 @import './markdown/stepper.css';
+@import './markdown/button.css';
 @import './api-docs.css';
 @import 'tippy.js/dist/tippy.css';