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.

A procedure with fifteen steps is harder to follow than one with five because users lose their place. They have to remember how far through they are or how much is left, which becomes challenging if they’re moving between your product in another tab or window and your documentation. If they have to stop and come back, finding their position might require rereading content or starting over. Some procedures are too long for a single page.

​
Signs a procedure has outgrown its page

The scroll is significant. If users need to scroll multiple screens to see all the steps, the procedure is likely too long for a single page. Steps depend on decisions made far earlier. If step 12 says “based on the option you chose in step 3,” you’re probably combining too many procedures into one. Some users don’t need all the steps. If steps 8-12 only apply to users with enterprise plans, those users have to read through steps 1-7 before finding out which path they’re on. The page generates support tickets at a specific step. If you can see from your analytics or support queue that users consistently get stuck at step 9 of 14, that step is probably the right place to make a page break.

​
How to structure multi-page procedures

Two approaches work for most documentation.
  • Short, complete pages that link from one to another.
  • Tutorials that describe each step of a complex procedure, but link to specific how-to guides for more information on each step.
Each page should:
  • Have a single, clear goal like “Connect your GitHub repository” or “Set up your deployment settings” (not “Setup, part 2”).
  • Be completable in one sitting.
  • End with a clear indication of what comes next or success criteria to know that the procedure is complete.
Guide users forward at the end of each page.
Example of a card component used for a next step link
You've connected your repository. Next, configure your deployment settings.

<Card title="Configure deployments" href="/guides/configure-deployments" icon="settings">
  Set your build command, output directory, and environment variables.
</Card>
Next steps can be simple. Just let people know what to do next and what they should expect if they follow a link.
Example of a prose next step link
Next: [Configure your deployment settings](/guides/configure-deployments) — Set your build command, output directory, and environment variables.
Users who complete a page shouldn’t have to navigate back to an index to find out what comes next.

​
Update the navigation

When a procedure spans multiple pages, make sure the navigation reflects the sequence. In docs.json, list the pages in order within a group:
Example group
{
  "group": "Set up your account",
  "pages": [
    "guides/create-account",
    "guides/connect-repository",
    "guides/configure-deployments",
    "guides/publish"
  ]
}
The sidebar order communicates the sequence. A user who gets lost can look at the sidebar and see where they are in the overall flow.
Next up: Code block essentials — Write code blocks that help users follow along.