Hub pages 3/4: {get-started}

docs/_docset.yml

@@ -1,3 +1,3 @@
 project: 'doc-builder'
 max_toc_depth: 2
 dev_docs: true
@@ -122,6 +122,7 @@
       - file: file_inclusion.md
       - file: footnotes.md
       - file: frontmatter.md
+      - file: get-started.md
       - file: hero.md
       - file: hub-pages.md
       - file: icons.md

docs/examples/products/docs-builder.md

@@ -12,6 +12,28 @@ description: docs-builder documentation. Build, validate, and publish Elastic do
 :tertiary-action: [Explore docs-builder](#explore)
 :::
 
+:::{get-started}
+title: Get started in 3 steps
+intro: Install docs-builder, write your first page, then preview and publish it.
+steps:
+  - title: Install docs-builder
+    options:
+      - label: Build from source
+        description: Clone the repository and build the CLI yourself.
+        code: dotnet build
+        language: sh
+      - label: Run in a container
+        description: No local install needed.
+        url: /getting-started/installation.md
+        url-label: Container setup
+  - title: Write your first page
+    description: Author Markdown, add links, and use the directive set.
+    link: /getting-started/writing-content.md
+    link-label: Start writing
+  - title: Preview and publish
+    description: Serve the site locally with live reload, then publish it.
+:::
+
 ::::{card-group}
 :title: Get hands-on
 :id: hands-on

docs/syntax/get-started.md

@@ -0,0 +1,95 @@
+# Get started
+
+The onboarding section of a [hub page](hub-pages.md). It gives a new reader one opinionated path to a first success, before they face the full link list.
+
+The section is optional. Skip it when the hero already says what to do next.
+
+See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered section.
+
+## Basic
+
+A hub's onboarding section is three steps. The first offers two equally weighted ways to start, and the rest are single links.
+
+```markdown
+:::{get-started}
+title: Get started in 3 steps
+intro: Install docs-builder, write your first page, then preview and publish it.
+steps:
+  - title: Install docs-builder
+    options:
+      - label: Install locally
+        description: Install the CLI on your machine.
+        code: curl -sSL https://ela.st/docs-builder-install | sh
+        language: sh
+      - label: Run in a container
+        description: No local install needed.
+        url: /getting-started/installation.md
+        url-label: Container setup
+  - title: Write your first page
+    description: Author Markdown, add links, and use the directive set.
+    link: /getting-started/writing-content.md
+    link-label: Start writing
+  - title: Preview and publish
+    description: Serve the site locally with live reload, then publish it.
+    link: /getting-started/serve.md
+    link-label: Serve locally
+:::
+```
+
+The body is YAML, not markdown, like [`{link-card}`](link-card.md).
+
+## Schema
+
+| Field | Notes |
+|---|---|
+| `title` | **Required.** H2 heading. |
+| `intro` | One-line lead below the heading. |
+| `steps` | The numbered steps. |
+
+Everything the section offers lives inside a step. An install command belongs in `steps[0].options[]`, which keeps the whole path inside the numbered sequence.
+
+A command in a step option goes through the standard code block, so it gets syntax highlighting and a copy button like every other code block on the site.
+
+Every field except `title` is optional. The [example hub](../examples/products/docs-builder.md) uses each one once, and shows all three step shapes, so you can start from it and delete what you do not need.
+
+
+## Step shapes
+
+A step takes one of three shapes.
+
+**Plain.** A `title` and a `description`. Nothing is clickable.
+
+```yaml
+- title: Preview and publish
+  description: Serve the site locally, then publish it.
+```
+
+**Link.** Add `link` and `link-label`, and the whole step card becomes clickable.
+
+```yaml
+- title: Write your first page
+  description: Author markdown, add links, and use the directive set.
+  link: /getting-started/writing-content.md
+  link-label: Start writing
+```
+
+**Options.** Add `options` for two or more equally weighted paths, shown side by side. Each option takes a `label`, a `description`, and either a copyable `code` snippet with its `language`, or a `url` with a `url-label`.
+
+```yaml
+- title: Preview and publish
+  options:
+    - label: Preview locally
+      description: Serve the site with live reload while you write.
+      code: docs-builder serve
+      language: sh
+    - label: Publish
+      description: Build the site and publish it.
+      url: /getting-started/publish.md
+      url-label: How to publish
+```
+
+Steps are numbered automatically, in source order. The number sits before the title, because the section describes a sequence and the number is what carries that.
+
+## Links
+
+Every `steps[].link` and `options[].url` validates at build time, using the same forms as [`{link-card}`](link-card.md#links).

docs/syntax/hub-pages.md

@@ -56,6 +56,7 @@ Write both deliberately. The search body indexes the hero title and description
 | [`{hero}`](hero.md) | Identity band. Carries the product icon, the page title, a description, and up to three actions. |
 | [`{card-group}`](card-group.md) | Section heading and card grid. Renders as an accordion inside `{explore}`. |
 | [`{link-card}`](link-card.md) | One card: title, description, link list, optional aside. Renders as a link column inside `{explore}`. |
+| [`{get-started}`](get-started.md) | Onboarding funnel. An install command, a tutorial link, and numbered steps. |
 | [`{explore}`](explore.md) | The browse-everything section. A stack of collapsible accordions. |
 
 ## Page skeleton

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

@@ -138,6 +138,207 @@
 		flex-shrink: 0;
 	}
 
+	/* Get started ------------------------------------------------------ */
+	.hub-get-started {
+		@apply mx-auto w-full max-w-5xl;
+		margin-bottom: 56px;
+		scroll-margin-top: 96px;
+	}
+	.hub-get-started .hub-get-started-title {
+		margin: 0 0 8px;
+		font-size: var(--text-xl);
+		font-weight: 700;
+		color: var(--color-ink);
+	}
+	.hub-get-started .hub-get-started-intro {
+		margin: 0 0 20px;
+		font-size: var(--text-base);
+		color: var(--color-ink-light, #4c4c4c);
+		line-height: 1.5;
+	}
+	.hub-get-started .hub-get-started-install {
+		position: relative;
+		flex: 1 1 380px;
+		min-width: 0;
+		margin: 0;
+	}
+	.hub-get-started .hub-get-started-install pre {
+		margin: 0;
+		padding: 12px 16px;
+		overflow-x: auto;
+		background: var(--color-ink-navy);
+		border-radius: 10px;
+	}
+	.hub-get-started .hub-get-started-install code {
+		font-family: var(--font-mono, monospace);
+		font-size: var(--text-sm);
+		color: var(--color-white);
+		background: transparent;
+	}
+
+	.hub-get-started .hub-get-started-steps {
+		@apply grid gap-4;
+		grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+	.hub-get-started .hub-get-started-step {
+		@apply relative flex flex-col;
+		padding: 20px;
+		background: var(--color-white);
+		border: 1px solid var(--color-grey-20);
+		border-radius: 14px;
+	}
+	.hub-get-started .hub-get-started-step-head {
+		@apply flex items-center;
+		gap: 12px;
+		margin-bottom: 10px;
+		padding-right: 34px;
+	}
+	.hub-get-started .hub-get-started-step-num {
+		position: absolute;
+		top: 20px;
+		right: 20px;
+		font-size: var(--text-sm);
+		font-weight: 600;
+		/* grey-70 reads at 3.31:1 on white, short of the 4.5:1 minimum. ink-light
+		   carries the same quiet weight at 7.03:1 and is what other secondary text
+		   on the page already uses. */
+		color: var(--color-ink-light);
+		letter-spacing: 0.06em;
+	}
+	.hub-get-started .hub-get-started-step-title {
+		margin: 0;
+		font-size: var(--text-base);
+		font-weight: 700;
+		color: var(--color-ink-dark);
+	}
+	.hub-get-started .hub-get-started-step-desc {
+		margin: 0;
+		font-size: var(--text-sm);
+		color: var(--color-ink-light, #4c4c4c);
+		line-height: 1.45;
+	}
+
+	/* Step 01 with two equal start options spans the full row. */
+	.hub-get-started .hub-get-started-steps:has(.hub-get-started-step-wide) {
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+	}
+	.hub-get-started .hub-get-started-step-wide {
+		grid-column: 1 / -1;
+		container-type: inline-size;
+	}
+	.hub-get-started .hub-get-started-options {
+		display: grid;
+		grid-template-columns: 1fr 1fr;
+		margin-top: 16px;
+		padding-top: 16px;
+		border-top: 1px solid var(--color-grey-20);
+	}
+	.hub-get-started .hub-get-started-option {
+		@apply flex flex-col;
+		gap: 10px;
+		padding-right: 28px;
+	}
+	.hub-get-started .hub-get-started-option + .hub-get-started-option {
+		padding-right: 0;
+		padding-left: 28px;
+		border-left: 1px solid var(--color-grey-20);
+	}
+	.hub-get-started .hub-get-started-option-label {
+		font-size: var(--text-sm);
+		font-weight: 700;
+		color: var(--color-ink-dark);
+	}
+	.hub-get-started .hub-get-started-option-desc {
+		margin: 0;
+		font-size: var(--text-sm);
+		color: var(--color-ink-light, #4c4c4c);
+		line-height: 1.45;
+	}
+	.hub-get-started .hub-get-started-option .hub-get-started-install {
+		flex: none;
+		width: 100%;
+		margin-top: auto;
+	}
+	.hub-get-started .hub-get-started-option-btn {
+		@apply inline-flex items-center justify-center;
+		gap: 8px;
+		width: 100%;
+		min-height: 48px;
+		margin-top: auto;
+		padding: 0 18px;
+		font-size: var(--text-sm);
+		font-weight: 600;
+		color: var(--color-ink-dark);
+		background: var(--color-white);
+		border: 1px solid var(--color-ink-dark);
+		border-radius: 8px;
+		transition:
+			background 0.15s ease,
+			border-color 0.15s ease;
+	}
+	.hub-get-started .hub-get-started-option-btn:hover,
+	.hub-get-started .hub-get-started-option-btn:focus-visible {
+		background: var(--color-grey-10);
+		border-color: var(--color-ink-dark);
+		color: var(--color-ink-dark);
+	}
+	.hub-get-started .hub-get-started-option-link {
+		@apply inline-flex items-center gap-1;
+		align-self: flex-start;
+		font-size: var(--text-sm);
+		font-weight: 600;
+		color: var(--color-blue-elastic-100, #0b64dd);
+	}
+	.hub-get-started .hub-get-started-option-link:hover,
+	.hub-get-started .hub-get-started-option-link:focus-visible {
+		text-decoration: underline;
+	}
+	@container (max-width: 560px) {
+		.hub-get-started .hub-get-started-options {
+			grid-template-columns: 1fr;
+		}
+		.hub-get-started .hub-get-started-option {
+			padding-right: 0;
+		}
+		.hub-get-started .hub-get-started-option + .hub-get-started-option {
+			padding-left: 0;
+			padding-top: 16px;
+			margin-top: 4px;
+			border-left: 0;
+			border-top: 1px solid var(--color-grey-20);
+		}
+	}
+
+	/* Steps 02/03 are clickable link cards. */
+	.hub-get-started .hub-get-started-step-link {
+		padding: 0;
+		transition:
+			box-shadow 0.15s,
+			border-color 0.15s;
+	}
+	.hub-get-started .hub-get-started-step-link:hover,
+	.hub-get-started .hub-get-started-step-link:focus-visible {
+		border-color: var(--color-blue-elastic);
+		box-shadow: 0 1px 4px rgb(0 0 0 / 0.07);
+	}
+	.hub-get-started .hub-get-started-step-anchor {
+		@apply flex h-full flex-col;
+		padding: 20px;
+		color: inherit;
+		text-decoration: none;
+	}
+	.hub-get-started .hub-get-started-step-arrow {
+		@apply inline-flex items-center gap-1;
+		margin-top: auto;
+		padding-top: 14px;
+		font-size: var(--text-sm);
+		font-weight: 600;
+		color: var(--color-blue-elastic-100, #0b64dd);
+	}
+
 	/* Zone (section heading) ------------------------------------------ */
 	.hub-zone {
 		@apply mx-auto w-full max-w-5xl;

src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs

@@ -149,6 +149,9 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 		if (info.IndexOf("{link-card}") > 0)
 			return new LinkCardBlock(this, context);
 
+		if (info.IndexOf("{get-started}") > 0)
+			return new GetStartedBlock(this, context);
+
 		if (info.IndexOf("{agent-skill}") > 0)
 			return new AgentSkillBlock(this, context);