Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

Numbered lists and the <Steps> component both render as numbered sequences. Steps add visual weight with a prominent step number, a title, and a clearly bounded content area for each step. That design is useful when you’re guiding someone through complex tasks where each step requires decisions or complex actions. But for simpler procedures, a plain numbered list is often enough.

​
When to use the steps component

Use <Steps> when:
  • Each step requires substeps, decisions, or significant context that a single list item is insufficient.
  • The steps are sequential. For example, completing step 2 requires completing step 1 first.
Example steps
<Steps>
  <Step title="Create a Mintlify account">
    Go to [mintlify.com](https://mintlify.com) and sign up. You'll need a GitHub account to connect your repository.
  </Step>
  <Step title="Install the CLI">
    ```bash
    npm i -g mintlify
    ```
  </Step>
  <Step title="Start the local preview">
    Run `mint dev` from your docs directory. The preview opens at `localhost:3000`.
  </Step>
</Steps>
The title of each step describes what the user accomplishes. If someone only reads the step titles, and not the content of every step, they should be able to understand the overall procedure. Don’t use vague titles like “Step 2” or “Installation.” And don’t just describe what happens mechanically in a step title, like “Click Enable.”

​
When a numbered list is better

Use a numbered list when:
  • Each item fits in one or two lines.
  • You’re listing things in a logical order, not guiding someone through a task.
  • The content doesn’t need sub-elements like code blocks, images, or multiple lines of context.
Example descriptive numbered list
Your changes are deployed in this order:

1. Mintlify validates the `docs.json` structure.
2. Your MDX files compile.
3. The site publishes to your subdomain.
This is a sequence of things that happen, not a sequence of things the user does. Using a <Steps> component doesn’t help communicate the sequence.
Example procedural numbered list

1. Navigate to your dashboard.
2. Click the **Deploy** button.
This is a simple process that doesn’t require any decisions or complex actions. A numbered list is a good fit.

​
The one-line step problem

A common misuse of the steps component is wrapping content without using the component’s full capabilities. 
{/* Not the best use of steps */}
<Steps>
  <Step title="Open your terminal" />
  <Step title="Run the command" />
  <Step title="Check the output" />
</Steps>
These one-liners mostly just add whitespace. A numbered list would communicate the same thing. If your steps don’t have children-no code blocks, no prose, no callouts—they can probably be list items instead.

​
Step titles matter

Step titles appear in the table of contents on some Mintlify themes and readers scan them to understand the overall procedure. A title like “Configure” is less helpful than “Configure your webhook endpoint.” The latter tells you exactly what the step is about. Generally, start step titles with a verb and end with the specific thing being acted on.
  • “Installation” → “Install project dependencies”
  • “Analaytics script” → “Add the analytics script to your layout”
  • “Test” → “Test the connection”
Next up: Describe branching procedures — How to handle when a procedure forks based on platform, role, preference, or other factors.