Get started

The onboarding section of a hub page. 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 for a rendered section.

A hub's onboarding section is a numbered list of steps. Use as many as the path needs. The first step often offers two equally weighted ways to start, and the rest are single links.

:::{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}.

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 uses each one once, and shows all three step shapes, so you can start from it and delete what you do not need.

There is no fixed number. The layout arranges whatever you write:

• The first step always sits in a tinted box. When it has two options, they sit side by side with an "or" between them. This is true on every hub, including a hub with no options.
• The remaining steps sit below in columns, with titles, text and links lined up across them. They use three columns when they divide by three, two when they are even, so the last row is never short.
• Below a narrow width, the steps stack into one column and the first step's options stack with the "or" line between them. Steps in three columns stack sooner than steps in two.

Keep the list short enough to read as one path. Four steps still scan. Ten do not.

A step takes one of three shapes.

Plain. A title and a description. Nothing is clickable.

- title: Preview and publish
  description: Serve the site locally, then publish it.
		

Link. Add link and link-label. The step shows that label as a text link that ends in an arrow.

- 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. Two options are shown side by side with an "or" between them. Each option takes a label, a description, and either a copyable code snippet with its language, or a url with a url-label.

- 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. Each number sits to the left of its title.

Every steps[].link and options[].url validates at build time, using the same forms as {link-card}.