Skip to main content
Documentation often mirrors the product: features become sections, and the internal architecture becomes the docs hierarchy. That feels logical because it matches the team’s mental model. It rarely works well for users. Users don’t navigate docs by feature. They navigate by goal. They arrive asking “how do I do X?” If your navigation requires them to first understand your product’s architecture to know where to look, you’ve already made their job harder.

​
Feature-based vs. goal-based navigation

Here’s a concrete example. A company that builds a data pipeline tool might organize their docs like this:
Feature-based navigation
This mirrors the product’s architecture. But a user who wants to “get data from Postgres into our data warehouse” has to infer which sections are relevant before they can even start reading. A goal-based alternative:
Goal-based navigation
The underlying content is often identical. The organization reflects what users are trying to accomplish, not how the product is built.

​
The AI navigation trap

AI tools are particularly prone to generating feature-based navigation. Ask an AI to “suggest a navigation structure for our documentation” and it will usually mirror your product, because the most obvious input you give it is a list of features. If you’re using AI to help structure your Mintlify docs, be explicit about organizing by user goal:
“Suggest a navigation structure for our documentation organized around what users are trying to accomplish, not our product’s feature list. Our users are typically trying to: [list 3–5 key jobs to be done].”
That extra context usually produces a more useful structure.

​
Mintlify’s navigation primitives

Mintlify gives you several ways to organize navigation. Each one fits a different structural need. Pick one primary pattern for the top level of your site, then nest the others inside it.

​
Groups

Groups are the basic building block: a labeled section with pages inside. Use them when the pages inside share a clear purpose and a user who wants one is likely to want the others.
docs.json
Keep group names short and goal-oriented. “Get started” works. “Introduction to the product” is too long and too vague.

​
Tabs

Tabs create distinct sections of your site with separate URL paths, shown as a navigation bar across the top. Use them for parallel sections that serve the same audience in different modes. Completing a single task should only require content from a single tab. The most common good use of tabs is separating guides from API reference for one product. The same developer reads both, but they’re doing different things: following steps in one, looking up parameters in the other. A common misuse of tabs is creating a tab for every product area because the sidebar is getting long. A long sidebar usually means your groups are poorly defined, not that you need more tabs. Dropdowns do the same job as tabs, but as a menu at the top of the sidebar instead of a bar across the page. Choose them when you have more sections than fit comfortably in a tab bar, or when you want the top of the page to stay clean.

​
Products

Products are for separate products that each need their own full documentation site under one project. If a user who works with Product A rarely needs Product B’s documentation, products make sense. If users regularly move between sections, tabs or groups will serve them better.

​
Anchors

Anchors add persistent items to the top of your sidebar. They can section your content like tabs, but they’re most useful as global anchors: links that appear on every page, regardless of section. Use global anchors for resources readers need from anywhere, like a changelog, a status page, or a community forum. Don’t use anchors to promote content that’s already easy to reach through your main navigation.

​
Patterns that hold up

Make the quickstart easy to reach. The most important page on most documentation sites is the one that gets a new user to a working state as fast as possible. Put it at or near the top of your primary navigation, and link to it from your introduction page so new users don’t have to read through an overview to find it. Separate doing from looking up. Tutorials and how-to guides are about doing. Reference material is about looking up. Users move between these modes constantly, and they’re easier to navigate when they live in distinct areas of your Mintlify site. Name sections for what users will accomplish, not what the section contains. “Webhooks” describes what’s inside. “Receive real-time events” describes why a user would go there. The second version attracts the right reader without requiring them to already know what webhooks are.

​
Check your section names

Look at each section name without reading the content. Can a new user tell from the name alone whether the section will help with their task? If the answer is often no, the problem is usually one of two things: section names that are too product-centric, or sections that are too broad and need to be broken up. The next lesson covers how to test navigation with real readers and real data.

​
Inventory content before reorganizing it

Before changing a large navigation tree, list the existing pages with their purpose, audience, content type, traffic, and owner. If you audited content types in the content types lesson, start from that list. Mark duplicates, gaps, and pages that no longer deserve a place in the new structure. Designing from an inventory prevents two common mistakes: preserving every old page because it already exists, and moving pages without noticing that several cover the same task. When you rename or move a published page, add a redirect from the old URL to the new one. Existing bookmarks, search results, support messages, and agent citations may continue using the old address long after the navigation changes. Next up: Measure and improve findability—use behavior and feedback to test whether the structure works.