- Settings
- Navigation
Settings
Navigation
Design information architecture that aligns with user needs.
The navigation property in layout.json controls the structure and information hierarchy of your documentation.
With proper navigation configuration, you can organize your content so that users can find exactly what they’re looking for.
Tabs
Split large documentation areas into top-level header tabs.
Dropdowns
Add compact sidebar selectors for secondary documentation lanes.
Languages
Add a language selector for translated documentation.
​Pages
Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository.
In the navigation array, each group contains a pages array where each entry must reference the path to a page file. You don’t need to include .mdx in page names.
{
"navigation": [
{
"group": "Getting Started",
"pages": [
"quickstart",
"installation",
"configuration"
]
}
]
}
​Groups
Use groups to organize your sidebar navigation into sections. Groups can be nested within each other and styled with icons.
In the navigation array, each entry is an object that requires a group field and a pages field.
"navigation": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
​Example with nested groups
{
"navigation": [
{
"group": "Getting started",
"pages": [
"quickstart",
{
"group": "Editing",
"pages": [
"installation",
"editor"
]
}
]
},
{
"group": "Writing content",
"pages": [
"writing-content/page",
"writing-content/text"
]
}
]
}
​Tabs
Use tabs to split your documentation into major top-level areas in the header, such as Home, Guides, API Reference, or SDKs. Tabs are configured with the top-level tabs array in layout.json.
When you add tabs, Docsalot also shows a default documentation tab first. You can rename and restyle that default tab with topAnchor.
{
"topAnchor": {
"name": "Home",
"icon": "house",
"iconType": "solid"
},
"tabs": [
{
"name": "API Reference",
"url": "api-reference",
"icon": "square-terminal",
"iconType": "regular"
}
],
"navigation": [
{
"group": "Getting Started",
"pages": ["quickstart", "installation"]
},
{
"group": "API Reference",
"pages": ["api-reference/index", "api-reference/authentication"]
},
{
"group": "Users",
"pages": ["api-reference/users/list-users", "api-reference/users/create-user"]
}
]
}
With this configuration, Home shows the regular documentation groups. API Reference shows groups whose pages live under /api-reference/*.
​Multiple tabs
Add one tab for each major content area. The url should match the route prefix for the pages that belong to that tab.
{
"topAnchor": {
"name": "Home",
"icon": "none"
},
"tabs": [
{
"name": "Guides",
"url": "guides",
"icon": "book-open",
"iconType": "regular"
},
{
"name": "API",
"url": "api-reference",
"icon": "cloud",
"iconType": "regular"
},
{
"name": "SDKs",
"url": "sdks",
"icon": "code",
"iconType": "solid"
}
],
"navigation": [
{
"group": "Getting Started",
"pages": ["quickstart"]
},
{
"group": "Guides",
"pages": ["guides/installation", "guides/configuration"]
},
{
"group": "API Reference",
"pages": ["api-reference/index", "api-reference/authentication"]
},
{
"group": "SDKs",
"pages": ["sdks/javascript", "sdks/python"]
}
]
}
​Tab properties
The tab label shown in the header.
The internal route prefix for the tab, such as "api-reference", or a full external URL.
The icon shown next to the tab name. Use a Font Awesome icon name such as "book-open", "cloud", or "square-terminal". Set "icon": "none" when you want text only.
The Font Awesome style for the icon. Common tab values are regular, solid, duotone, and brands. For topAnchor, use one of brands, duotone, light, sharp-solid, solid, or thin.
Keep tab URL prefixes distinct. If you use both "api" and "api-reference", pages under /api-reference/* may match the broader "api" prefix first.
​Folders
Simply put your MDX files in folders and update the paths in layout.json.
For example, to have a page at https://yoursite.com/your-folder/your-page you would make a folder called your-folder containing an MDX file called your-page.mdx.
You cannot use api for the name of a folder unless you nest it inside another folder. Docsalot uses Next.js which reserves the top-level api folder for internal server calls.
"navigation": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
​Anchors
Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action.
In layout.json, anchors is an array where each entry is an object that requires a name field and a url field. The icon, iconType, and color fields are optional.
{
"anchors": [
{
"name": "Documentation",
"icon": "book-open",
"url": "docs"
},
{
"name": "API reference",
"icon": "square-terminal",
"url": "api-reference"
},
{
"name": "Blog",
"icon": "newspaper",
"url": "https://external-link.com/blog"
}
]
}
​Anchor properties
The display name of the anchor shown in the sidebar.
The URL path or external link. Internal paths should not include a leading slash.
The icon to display next to the anchor name. Uses Font Awesome icon names.
The style of the icon. Options: brands, duotone, light, regular, sharp-solid, solid, thin.
The color of the anchor. Can be a hex string or a gradient object with from and to properties.
​Hidden Pages
MDX files not included in layout.json will not show up in the sidebar but are accessible through the search bar and by linking directly to them.