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.

Many setup procedures branch. Install on macOS or Windows. Configure for the cloud or on-premise version. Authenticate with an API key or OAuth. Throughout your documentation, you’ll need to describe how to handle these branching procedures. Help your users find the right information and avoid content that doesn’t apply to them.

​
Three approaches to branching procedures

​
Tabs inside a step

When the differences are short—a few lines each or a single code block—and part of a procedure, put the options inside a tab within the step that diverges. 
<Steps>
  <Step title="Install the package">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash
        brew install mintlify
        ```
      </Tab>
      <Tab title="Windows">
        ```bash
        winget install mintlify
        ```
      </Tab>
    </Tabs>
  </Step>
  <Step title="Verify the installation">
    Run `mintlify --version` to confirm the installation succeeded.
  </Step>
</Steps>
This keeps the procedure together and makes it clear the variation applies specifically to that one step. The steps before and after are the same for everyone. Be aware that not every reader notices tabs. So be cautious about what information goes into tabs. If anything is applicable to both paths, make sure it is not hidden in only one tab. Use tabs inside steps when:
  • Only one or two steps in the procedure vary by platform.
  • Each variation is short and fits within a single step, not an entirely separate procedure.
  • The reader doesn’t need to make a meaningful decision about which path to take or the selection criteria are obvious like picking their operating system.

​
Separate how-to guides

When the differences between branching procedures are more in depth, or the choice affects more than just a few steps, write separate guides and link to them from a decision point. 
Choose the authentication method that fits your setup:

<Columns>
  <Card title="API key authentication" href="/guides/auth-api-key" icon="key">
    Best for server-to-server requests and scripts. Simpler to set up.
  </Card>
  <Card title="OAuth 2.0" href="/guides/auth-oauth" icon="lock">
    Required for accessing user data. More setup, but more control.
  </Card>
</Columns>
This approach is easier to read and easier to maintain when the procedures diverge significantly. Readers self-select into their path and follow that guide from start to finish. Make sure people are finding the right guide for their path. Review feedback and search results related to the guides to identify gaps and areas for improvement. Use separate guides when:
  • The differences between procedures involve more than 3-4 steps each.
  • The procedures require different prerequisites.
  • A user who takes one path will never need the other.

​
A prerequisite step that routes the reader

For longer procedures where the initial steps are identical but the later steps diverge, make the branching point clear before the user begins the shared steps. This avoids frustration from having readers discover halfway through that they need to take a different path. 
Before you begin, decide which path applies to you:

- **If you're deploying to the cloud**, follow steps 1-4 and then continue to the "Cloud deployment steps" section.
- **If you're self-hosting**, start at step 5 and then follow the rest of the steps.
This way, readers know up front how the procedure branches out, and can follow the correct path without having to backtrack. This is a lightweight version of the separate-guides approach. It’s appropriate when the branching is modest—one path has a few different steps but most of the procedure is the same—and you don’t want to maintain two parallel guides.

​
What to avoid

A common mistake is embedding a branch mid-procedure without clearly signaling it.
Example of an unclear branching point
<Step title="Configure authentication">
  Add your key to the config file if you're using API key auth. For OAuth, you'll need to register a client application first.
This forces every reader to understand both paths to figure out which applies. Even users who know exactly which auth method they’re using have to read carefully to make sure they’re not missing something. The fix is to make the decision explicit before the step begins, or use tabs so the paths are visually separated.
Next up: When a procedure outgrows a page — How to recognize when a procedure is too long for one page, and how to restructure it.