How do I add the Steps block to a Hugo site?

Add a "block: steps" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Is the Steps block free to use?

Yes. Every HugoBlox block is free and open-source under the MIT license — use it in personal and commercial projects, with no attribution required.

Can I customize the Steps block?

Yes. It exposes 13 content options, plus 4 design options, and inherits the shared block settings for background, spacing, and colors. You can also describe the changes you want to Hugo Chat AI and it will edit the config for you.

Does the Steps block work with any Hugo theme?

The block ships in the open-source HugoBlox kit. Add the kit to any Hugo site and the block becomes available in your page sections — there is no theme lock-in.

hugoblox.com/blocks/steps

FeaturesFree · MITPreact · interactive

Steps block

Numbered process steps in vertical, horizontal, or timeline layouts — for 'how it works' and onboarding.

Customize with AI View source

Add it to any Hugo page's sections list — no build step.

v1.0.0Version

13Options

MITLicense

Quick start

Add the Steps block

Drop this into your page's front matter, under the sections list. Edit the values, and HugoBlox renders the block — no build step.

Add to your page's sections

- block: steps
  content:
    title: Get started in minutes
    text: No credit card required. Deploy to GitHub Pages in one click.
    items:
      - title: Choose a template
        text: Pick from our library of production-ready Hugo templates — academic CV, startup landing page, research lab, and more.
        icon: rectangle-stack
      - title: Customise your content
        text: Edit in simple YAML and Markdown. No coding required — everything is configured through readable parameters.
        icon: pencil-square
      - title: Deploy everywhere
        text: Push to GitHub and your site deploys automatically. Free hosting on GitHub Pages, Netlify, or Vercel.
        icon: rocket-launch
  design:
    layout: horizontal
    marker_style: icon
    connector: line

Flexibility

Layouts & variants

Switch the block's design with these presets — no custom CSS.

layoutLayout mode. 'vertical': stacked numbered steps with a connecting line running down the left — best for tutorials, install guides, docs, and long-form process explanations (2–8 steps). 'horizontal': markers in a row with a connecting line above content — best for 'how it works' and onboarding sections where steps are brief (3–5 steps). 'timeline': alternating left/right cards on a centre vertical line — best for roadmaps, company history, career timelines, and project milestones (4–8 items).

verticaldefaulthorizontaltimeline

marker_styleShape of the step indicator. 'number': auto-numbered circle (1, 2, 3…) — clear sequence, best when order matters. 'icon': icon from the icon pack in a circle — visual, best when each step has a distinct concept. 'dot': small plain dot — minimal, best for dense timelines. When using 'icon', set an icon on each step item.

numberdefaulticondot

numberingNumbering style when marker_style is 'number'. 'decimal': 1, 2, 3 — standard. 'padded': 01, 02, 03 — zero-padded, preferred on developer/devrel sites (Stripe, Linear, Vercel aesthetic). 'roman': I, II, III — formal, premium feel. 'alpha': A, B, C — phases or independent options.

decimaldefaultpaddedromanalpha

connectorLine connecting step markers. 'line': solid gray line — implies a definite sequence. 'dashed': dashed line — implies a more casual or flexible sequence. 'none': no connector — steps read as independent items.

linedefaultdashednone

Reference

Configuration

Every option the Steps block accepts, generated from its schema.

Content options

Properties set under the block's content key.

Property	Type	Default	Description
`title`	`string`	—	Section heading. Frames the purpose of the steps. E.g. 'How it works', 'Get started in minutes', 'Our process'.
`subtitle`	`string`	—	Optional eyebrow label rendered in small caps above the title. E.g. 'Getting started', 'Our process', 'How we work'.
`text`	`string`	—	Optional section subtitle beneath the title — sets context before the steps begin.
`items`required	`object[]`	—	The steps. Use 3–6 items for best results; horizontal layout is optimal at 3–5. Vertical handles 2–8 comfortably. Timeline works best with 4–8.
`items[].title`required	`string`	—	Step heading. Should be an action phrase or outcome. E.g. 'Sign up', 'Connect your data', 'Go live'.
`items[].text`	`string`	—	Step body text. Explains what happens in this step, or its benefit. Supports bold and italic Markdown.
`items[].icon`	`string`	—	Icon for this step. Only used when design.marker_style is 'icon'. Uses the standard icon packs: hero/ (Heroicons — default), brands/ (brand logos), devicon/ (dev tool icons). E.g. 'rocket-launch', 'hero/user-plus', 'brands/github'. See hugoblox.com/icons for the full catalogue.
`items[].date`	`string`	—	Optional date or period label shown above the step title. Most useful in the timeline layout for roadmaps or company history. E.g. '2021 Q3', 'March 2024', 'Week 1'.
`items[].badge`	`string`	—	Optional pill badge rendered next to the date/above the title. E.g. 'New', 'Beta', 'Free', 'Completed'. Highlights notable steps.
`items[].image`	`string`	—	Optional illustration or screenshot shown below the step text. Filename in assets/media/ or a URL. Best for vertical or timeline layouts; skip for horizontal.
`items[].cta`	`object`	—	Optional inline text link at the bottom of the step. E.g. 'Learn more →', 'See docs →'. Subtle; use for one or two key steps only.
`items[].cta.text`required	`string`	—	Link label
`items[].cta.url`required	`string`	—	Destination URL (relative or absolute)

Design options

Properties set under the block's design key — shared background, spacing, and color settings apply on top.

Property	Type	Default	Description
`layout`	`vertical \| horizontal \| timeline`	vertical	Layout mode. 'vertical': stacked numbered steps with a connecting line running down the left — best for tutorials, install guides, docs, and long-form process explanations (2–8 steps). 'horizontal': markers in a row with a connecting line above content — best for 'how it works' and onboarding sections where steps are brief (3–5 steps). 'timeline': alternating left/right cards on a centre vertical line — best for roadmaps, company history, career timelines, and project milestones (4–8 items).
`marker_style`	`number \| icon \| dot`	number	Shape of the step indicator. 'number': auto-numbered circle (1, 2, 3…) — clear sequence, best when order matters. 'icon': icon from the icon pack in a circle — visual, best when each step has a distinct concept. 'dot': small plain dot — minimal, best for dense timelines. When using 'icon', set an icon on each step item.
`numbering`	`decimal \| padded \| roman \| alpha`	decimal	Numbering style when marker_style is 'number'. 'decimal': 1, 2, 3 — standard. 'padded': 01, 02, 03 — zero-padded, preferred on developer/devrel sites (Stripe, Linear, Vercel aesthetic). 'roman': I, II, III — formal, premium feel. 'alpha': A, B, C — phases or independent options.
`connector`	`line \| dashed \| none`	line	Line connecting step markers. 'line': solid gray line — implies a definite sequence. 'dashed': dashed line — implies a more casual or flexible sequence. 'none': no connector — steps read as independent items.

Compose

Works well with

Blocks that pair naturally with Steps on the same page.

CTA Card Features Hero

Frequently asked

Steps block FAQ

Add a "block: steps" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Ready to build with the Steps block?

Customize with AI View source