Stepper

Steppers provide a visual representation of sequential steps, commonly used in tutorials or guides to break down processes into manageable stages. For example, you can usee steppers instead of numbered section headings when documenting a supertask or a complex procedure. An example is the Observability Get Started.

By default every step title is a link with a generated anchor. You can override the default anchor by adding the :anchor: option to the step.

:::::{stepper}

::::{step} Install
First install the dependencies.
```shell
npm install
```
::::

::::{step} Build
Then build the project.
```shell
npm run build
```
::::

::::{step} Test
Finally run the tests.
```shell
npm run test
```
::::

::::{step} Done
::::

:::::
		

:::::{stepper}

::::{step} Create an index

Create a new index named `books`:

```console
PUT /books
```

The following response indicates the index was created successfully.

:::{dropdown} Example response
```console-result
{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "books"
}
```
:::

::::

::::{step} Add data to your index
:anchor: add-data

:::{tip}
This tutorial uses Elasticsearch APIs, but there are many other ways to [add data to Elasticsearch](#).
:::

You add data to Elasticsearch as JSON objects called documents. Elasticsearch stores these documents in searchable indices.
::::

::::{step} Define mappings and data types

When using dynamic mapping, Elasticsearch automatically creates mappings for new fields by default.
The documents we’ve added so far have used dynamic mapping, because we didn’t specify a mapping when creating the index.

To see how dynamic mapping works, add a new document to the `books` index with a field that doesn’t appear in the existing documents.

   ```console
   POST /books/_doc
   {
     "name": "The Great Gatsby",
     "author": "F. Scott Fitzgerald",
     "release_date": "1925-04-10",
     "page_count": 180,
     "language": "EN" <1>
   }
   ```
1. The new field.
   ::::

:::::
		

Stepper step titles automatically appear in the page's "On this page" table of contents (ToC) sidebar, making it easier for users to navigate directly to specific steps.

To keep those titles in the procedure and out of the table of contents, set :toc: false. See Omit steps from the table of contents.

Set :toc: false on {stepper} when step titles should not be headings. A title is still one level deeper than the heading above the stepper, the same rule as a normal step. Under an ## heading, the title uses the size and weight of an h3. The title is a div with that styling, so it does not appear in On this page. Assistive technologies still treat it as a heading at that level. Each step still has an anchor, so you can link to it.

The default is to include step titles in the table of contents.

This stepper is rendered on the page. Its titles are not listed in On this page. Prepare the project still opens the first step:

:::::{stepper}
:toc: false

::::{step} Prepare the project
Install the dependencies before you build.
::::

::::{step} Build the project
Run the production build.
::::

:::::
		

When steppers are nested inside other directive components (like {tab-set}, {dropdown}, or other containers), their step titles are not included in the ToC to avoid duplicate or competing headings across multiple tabs or links to content that might be collapsed or hidden.

Example of excluded stepper:

::::{tab-set}
:::{tab-item} Tab 1
::{stepper}
:{step} This step won't appear in ToC
Content here...
:
::
:::
::::
		

Stepper step titles automatically adjust their heading level based on the preceding heading in the document, ensuring proper document hierarchy and semantic structure.

For example, a stepper that follows an ## heading renders each step title as ###.

You can add sub-headings inside a step to organise longer content. When the step title is a heading, each heading inside the step must be at least one level deeper than that title. If you write a heading at the same level as the step, or higher, the build adjusts it and emits a hint on that line.

With :toc: false, a heading inside the step must be deeper than the heading above the stepper. A stepper under an ## heading has titles that use the size of an h3. A ### heading inside a step is valid, because the title is not in the outline. A heading at the same level as the heading above the stepper, or higher, is adjusted and a hint is emitted.

The following example intentionally uses the wrong heading level to demonstrate the auto-correction. This stepper follows a ### heading, so its steps render as ####. The #### sub-heading inside the step is at the same level as the step itself — it is auto-adjusted to ##### and a hint is emitted:

HINT: Heading level h4 inside a step renders at the same or higher level as the step itself (h4).
      It has been adjusted to h5 — write it as '#####' to avoid this hint.
		

:::::{stepper}

::::{step} Configure
#### Advanced options

These options override the defaults.
::::

:::::
		

To suppress the hint, write the heading at the correct level from the start:

::::{step} Configure
##### Advanced options

These options override the defaults.
::::