Steps

Steps are an ordered list with numbered dots and a rule running through them: a plain ordered list plus a {.steps} marker line. The dots and the rule are drawn in CSS and no script is loaded. Use it for procedures that have an order. Parallel items with no order belong in a plain list or in cards.

There are two spellings: an ordered list plus {.steps} (the default choice), and the {{% steps %}} shortcode, for when each step needs its own heading and those headings belong in the table of contents.

Shortest form

Write 1. for every item and let Markdown do the counting. Inserting, deleting and reordering steps then needs no renumbering, and the content indent is always three spaces.

1. Install Hugo Extended
1. Clone the documentation site
1. Start the local preview
{.steps}

1. Install Hugo Extended
2. Clone the documentation site
3. Start the local preview

{.steps} must touch the last line of the list; leave a blank line and it turns into a visible line of braces.

What goes in a step

A list item takes any block content: paragraphs, fenced code, callouts, tables, nested lists, images. Indent it to the item’s content column — three spaces.

1. Clone the documentation site; it is itself a complete example of the theme.

   ```bash
   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs
   ```

1. Start the local server.

   ```bash
   hugo server
   ```

   > [!NOTE]
   > The first build fetches the theme through the Go module proxy, which needs
   > Go on the machine.

1. Replace three things and it is your site.

   | Where | Replace with |
   | --- | --- |
   | `title` in `hugo.yml` | your site name |
   | `baseURL` in `hugo.yml` | your domain |
   | `content/` | your content |
{.steps}

1. Clone the documentation site; it is itself a complete example of the theme.

   git clone https://github.com/pgsty/oink.pgsty.com my-docs
   cd my-docs

2. Start the local server.

   hugo server

   Note

   The first build fetches the theme through the Go module proxy, which needs Go on the machine.

3. Replace three things and it is your site.

   Where	Replace with
   title in hugo.yml	your site name
   baseURL in hugo.yml	your domain
   content/	your content

Shortcodes in {{< … >}} form — tabs, cards, badges — work inside a list item too. The {{% … %}} form does not; see Limits.

Splitting one step per platform

When one step differs per platform, write the {tab=} fences side by side inside that list item and they still assemble into a tab set.

1. Install Hugo Extended.

1. Install the dependencies:

   ```bash {tab="EL / RHEL" group="stepdemo" value="rpm"}
   sudo dnf install golang git
   ```
   ```bash {tab="Debian / Ubuntu" value="deb"}
   sudo apt install golang-go git
   ```

1. Run `hugo server` to preview.
{.steps}

1. Install Hugo Extended.

2. Install the dependencies:

   EL / RHEL

   sudo dnf install golang git

   Debian / Ubuntu

   sudo apt install golang-go git

3. Run hugo server to preview.

Continuing the numbering

When prose interrupts a procedure, write the first item of the next group with its real number. Markdown emits start and the numbering continues from there (up to 40).

4. Configure `baseURL` and the deployment workflow.
1. Push to `main` and wait for GitHub Actions to finish.
{.steps}

4. Configure baseURL and the deployment workflow.
5. Push to main and wait for GitHub Actions to finish.

Steps with headings

When the procedure is long and each step deserves a heading that can be linked to and collected by the table of contents, use {{% steps %}}: its body is page-level Markdown, every direct child heading is one step, and the body is not indented. The three headings below appear in this page’s table of contents.

{{% steps %}}

### Install the toolchain {#install-toolchain}

You need Hugo Extended ≥ 0.160.1 and Go.

### Run the server {#run-server}

{{< tabs group="oink-os" default="macos" >}}
{{< tab label="macOS" value="macos" >}}
`brew install hugo go`
{{< /tab >}}
{{< tab label="Debian" value="debian" >}}
`sudo apt install hugo golang-go`
{{< /tab >}}
{{< /tabs >}}

### Publish {#publish}

Push to `main`; the workflow the repository ships builds and publishes.

{{% /steps %}}

This is the theme’s only {{% … %}} shortcode. The percent form hands its body to Goldmark as page-level Markdown, which is the only way its headings can reach the table of contents and the only way container shortcodes such as tabs, cards and fields can live inside it. The price is that it cannot nest inside a list item or inside another percent container.

Keep the headings of one procedure at one level, and never nest one steps inside another.

Which form to use

Output

No script; with JavaScript off nothing changes.

Parameter reference

Neither form takes parameters — only conventions:

Limits

• No {{% … %}} inside a list item: the multi-line output of a percent shortcode truncates the list. To put a container in a step, switch the whole procedure to the shortcode form.
• {{% steps %}} cannot go inside a list item, nor inside another percent container.
• The marker must touch the list: no blank line between the list and {.steps}. Wrap it in <!-- prettier-ignore-start --> / <!-- prettier-ignore-end --> when a formatter like Prettier is in play.
• {.steps} applies to ordered lists only: on a - list there are no numbers.
• Steps do not fold and do not track progress: no “done” state, no expanding or collapsing.

Related

• Tabs — commands split per platform
• Callouts — prerequisites and warnings inside a step
• Code blocks — the commands in a step
• Cards — “what next” once the procedure is done