Steps
{.steps} to an ordered list for a numbered procedure. Use the steps shortcode when each step needs a table-of-contents heading.Steps display an ordered list with numbered dots and a connecting line. Add a {.steps} marker line to an ordered list.
CSS draws the dots and line. No script loads. Use steps for ordered procedures.
Use plain lists or cards for unordered items.
There are two forms. Use an ordered list with {.steps} by default.
Use {{% steps %}} when each step needs a heading in the table of contents.
Optional presentation
Use {.steps .td-steps-compact} for a short procedure, or steps variant="compact" for the heading form. OINK 1.4.0 supports these opt-in variants; compare the examples. Numbering, nesting, and heading anchors retain their existing meaning.
Shortest form
Write 1. for each item so Markdown counts automatically.
Then you can add, remove, or reorder steps without renumbering. Content always uses three spaces of indentation.
- Install Hugo Extended
- Clone OINK Starter
- Start the local preview
{.steps} must immediately follow the last list line. A blank line makes it display as text with braces.
What goes in a step
List items accept block content: paragraphs, fenced code, callouts, tables, nested lists, and images. Align content with the item’s content column, using three spaces.
-
Clone OINK Starter; it is the small project template for the theme.
-
Start the local server.
NoteThe first build fetches the theme through the Go module proxy, which needs Go on the machine.
-
Replace three things and it is your site.
Where Replace with titleinhugo.ymlyour site name baseURLinhugo.ymlyour domain content/your content
Shortcodes in {{< … >}} form, such as tabs, cards, and badges, also work inside list items.
The {{% … %}} form does not. See Limits.
Splitting one step per platform
If a step differs by platform, put adjacent {tab=} fences inside that list item. They still form a tab set.
-
Install Hugo Extended.
-
Install the dependencies:
EL / RHELDebian / Ubuntu -
Run
hugo serverto preview.
Continuing the numbering
If prose interrupts a procedure, start the next group with its actual step number.
Markdown emits start and continues numbering from that value, up to 40.
- Configure
baseURLand the deployment workflow. - Push to
mainand wait for GitHub Actions to finish.
Steps with headings
For long procedures with linked headings in the table of contents, use {{% steps %}}.
The body uses page-level Markdown without indentation. Each direct child heading is one step.
The three headings below appear in this page’s table of contents.
Install the toolchain
You need Hugo Extended ≥ 0.168.0 and Go.
Run the server
brew install hugo go
sudo apt install hugo golang-go
Publish
Push to main; the workflow the repository ships builds and publishes.
This is the theme’s only {{% … %}} shortcode. The percent form gives its body to Goldmark as page-level Markdown.
This allows headings in the table of contents and container shortcodes such as tabs, cards, and fields inside steps.
It cannot nest inside list items or other percent containers.
Use the same heading level for every step in a procedure. Never nest steps inside another steps container.
Which form to use
| Situation | Use |
|---|---|
| A step is a sentence or two plus a command | ordered list + {.steps} |
| Each step needs a heading, a link and a place in the TOC | {{% steps %}} |
A step must contain a tabs, cards or fields container |
{{% steps %}} |
| The procedure itself has to nest inside another list item | ordered list + {.steps} |
Output
| Output | Shape |
|---|---|
| HTML | The native form is <ol class="steps"> with numbers and rule drawn in CSS; the shortcode form is <div class="td-steps"> plus headings |
| Numbers and content unchanged, the rule stays | |
| Markdown | The source as written: an ordered list plus {.steps}, or headings plus bodies |
| RSS | A static list or titled sections |
Steps load no script. Disabling JavaScript does not change the result.
Parameter reference
OINK 1.4.0 supports the optional variant="compact" on the full form. Follow these conventions:
Limits
- Do not put
{{% … %}}inside list items. A percent shortcode’s multiline output truncates the list. To put a container in a step, use the shortcode form for the whole procedure. {{% steps %}}cannot be inside list items or other percent containers.- Put the marker immediately after the list, with no blank line before
{.steps}. With formatters such as Prettier, wrap it in<!-- prettier-ignore-start -->/<!-- prettier-ignore-end -->. {.steps}applies only to ordered lists. A-list has no numbers.- Steps do not collapse, expand, or track progress. There is no “done” state.
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