The nav.json Reference

Every folder under content/ can contain a nav.json file. It tells APIMatic how to label that folder in the sidebar and in what order to show the pages and subfolders inside it. The nav.json at the root of content/ can also define which folders appear as tabs across the top of your portal.

Here's a sample structure of your source folder:

src/
  apimatic.json
  content/
    nav.json                 # root: page order + tabs
    index.md
    guides/
      nav.json               # folder: title + page order
      authentication.md
      pagination.md
  spec/
    openapi.yaml

How it worksCopy Anchor Link

When APIMatic builds your portal, it reads content/ folder by folder:

1. Each .md or .mdx file becomes a page. Its sidebar label comes from the title in the page's frontmatter.
2. Each folder becomes a sidebar section. If the folder has a nav.json, its title is used as the section label and its pages array sets the order of items in that section.
3. The "..." entry in pages stands for every item in the folder that isn't listed by name, so new pages show up without editing nav.json.
4. The root nav.json can list items in tabs. Each of those becomes its own tab. Everything not listed in tabs is placed in the Home tab.

Sample root nav.jsonCopy Anchor Link

{
  "tabs": ["apimatic:sdks", "apimatic:plugin", "apimatic:api"],
  "pages": ["index", "..."]
}

This is the default root nav.json of a new portal. It shows SDKs, Context Plugins, and API Reference as tabs. In the Home tab, index is shown first, followed by every other top-level page and folder.

Properties in nav.json fileCopy Anchor Link

TitleCopy Anchor Link

The display name of the folder. Use it to give a folder a readable label without renaming the folder on disk.

{
  "title": "Guides"
}

PagesCopy Anchor Link

An ordered list of the items in the folder. Each entry is the file name without the .md or .mdx extension, the name of a subfolder, or "...".

A subfolder starts with this default nav.json:

{
  "pages": ["..."]
}

The root content/nav.json also includes the default tabs (see Sample root nav.json).

"..." adds all pages and subfolders in the folder. Replace "..." with names to set an exact order, or keep it at the end to list a few items first and let the rest follow:

{
  "title": "Guides",
  "pages": ["authentication", "..."]
}

To fully control the order, list every item:

{
  "title": "Guides",
  "pages": ["authentication", "pagination", "errors"]
}

This renders the Guides section as:

Guides
  Authentication
  Pagination
  Errors

Notes:

• Entries are names relative to the folder that contains the nav.json, not paths. Use "authentication", not "guides/authentication" or "authentication.md".
• A subfolder is listed by its folder name. Its own nav.json controls what's inside it.

TabsCopy Anchor Link

tabs is only read from the root content/nav.json. Each entry is the name of a top-level folder in content/, and each one is shown as a separate tab at the top of the portal.

• A folder listed in tabs becomes a tab. The tab's label is the folder's title from its own nav.json, and the tab's sidebar shows that folder's contents.
• Tabs appear in the order you list them, after the Home tab.
• Any folder not listed in tabs is added to the Home tab by default.
• New portals start with three built-in tabs: SDKs, Context Plugins, and API Reference.
• If you remove tabs entirely, there's no tab bar, and SDKs, Context Plugins, and API Reference appear in the Home sidebar.

{
  "title": "Home",
  "tabs": ["guides", "apimatic:sdks", "apimatic:plugin", "apimatic:api"],
  "pages": ["index", "..."]
}

This produces five tabs:

The title in the root nav.json sets the label of the Home tab.

Built-in tabsCopy Anchor Link

SDKs, Context Plugins, and API Reference are listed in tabs by these built-in names:

They're included in tabs by default. To show your own folders next to them, add the folder names to the same list. If you remove one of these names, that section moves into the Home sidebar.

Update your nav.jsonCopy Anchor Link

To change how your portal is organized, edit the nav.json files in content/:

1. Reorder a section: open that folder's nav.json and list the pages in the order you want in pages. Keep "..." at the end if you want any other pages to follow automatically.
2. Rename a section: set title in that folder's nav.json.
3. Add tabs: open the root content/nav.json and add the names of your top-level folders to the existing tabs array. Tabs appear in the order you list them, after the Home tab. Keep the apimatic: entries referred in tabs, or else they will all move into the Home sidebar (see built-in tabs).

{
  "title": "Home",
  "tabs": ["guides", "apimatic:sdks", "apimatic:plugin", "apimatic:api"],
  "pages": ["index", "..."]
}

4. Rebuild your portal to see the changes.

ExamplesCopy Anchor Link

Default portalCopy Anchor Link

A new portal starts with this root nav.json. It shows SDKs, Context Plugins, and API Reference as tabs, and everything else in Home.

{
  "tabs": ["apimatic:sdks", "apimatic:plugin", "apimatic:api"],
  "pages": ["index", "..."]
}

Nested foldersCopy Anchor Link

Each folder controls its own order. Here, guides contains a subfolder advanced with its own nav.json.

content/
  guides/
    nav.json
    authentication.md
    advanced/
      nav.json
      webhooks.md
      rate-limits.md

{
  "title": "Guides",
  "pages": ["authentication", "advanced"]
}

Inside the nested advanced folder, nav.json looks something like this:

{
  "title": "Advanced",
  "pages": ["webhooks", "rate-limits"]
}