---
seo:
    title: "Portal Navigation"
    description: "Configure portal navigation and sidebars using configuration."
llm_context: "Reference for the navigation configuration options supported by the portal. Global (header) navigation using portal.yaml, and per-section sidebars.yaml files to control sidebar structure."
category: "reference"
related:
    - "/portal/guides/organisation"
    - "/portal/reference/formatting"
---

## Header & Sidebar Navigation

Portal content is designed to be completely flexible and user-controlled. Markdown files are organised in folders under the `docs/` folder (see [File Organisation](/portal/guides/organisation#file-folder-organisation)), ready to render.

But how should you group those files into a cohesive user experience? That's what navigation is for.

:::tip Need Help?
Organising content and navigation well is a real design exercise, especially if you're coming from a world of siloed PDF documents where structure was never a first-class concern. Getting it right usually means stepping back, seeing the bigger picture, and being open to new ways of grouping things — it's something we spend time thinking through with customers as we build their first launch version.
:::

### Header Navigation

Along the top of every page is a consistent header bar, containing a series of links to the top-level sections of the portal.

![Figure: Dynamic header navigation bar](https://docs.fixspec.com/api/docs/image/portal_header_nav.png)

This set of top-level links can be dynamically set in the `portal.yaml` configuration file in the `docs/` folder root.

```yaml
navbar:
    items:
        - link: platform/concepts/architecture.md
          label: API Conformance Platform
        - link: portal/index.md
          label: White-Labelled Portal
        - link: finspec/index.md
          label: FinSpec Schema
        - link: apis/index.md
          label: Platform API
```

Note that access to these top-level navigation items can be controlled based on the authentication status of the user. See [Page-Level Authentication Control](/portal/reference/access#page-level-control).

```jsonSchema protocol=config version=portal-yaml-schema def=navbar
{
    "type": "object",
    "additionalProperties": false,
    "description": "Header navigation bar configuration.",
    "properties": {
        "items": {
            "type": "array",
            "description": "Navigation items in the header",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "label",
                    "link"
                ],
                "properties": {
                    "link": {
                        "type": "string",
                        "description": "Markdown path relative to `/docs` folder."
                    },
                    "label": {
                        "type": "string",
                        "description": "Display label."
                    },
                    "guestVisibility": {
                        "type": "string",
                        "enum": [
                            "invite",
                            "hide",
                            "show"
                        ],
                        "description": "Controls visibility of the item for guest users. `invite` shows a padlock and login link. Defaults to `show`.",
                        "$refName": "guestVisibility",
                        "$refResolved": true
                    },
                    "authenticatedVisibility": {
                        "type": "string",
                        "enum": [
                            "hide",
                            "show"
                        ],
                        "description": "Controls visibility of the item for authenticated users. Defaults to `show`.",
                        "$refName": "authenticatedVisibility",
                        "$refResolved": true
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Limits visibility to users belonging to entities with one of the specified roles.",
                        "$refName": "roles",
                        "$refResolved": true
                    }
                },
                "$refName": "navbarItem",
                "$refResolved": true
            }
        }
    }
}
```

### Section Sidebars

Within each section, there is a sidebar navigation item featuring collapsible groups and links to content within that section.

![Figure: Dynamic sidebar navigation](https://docs.fixspec.com/api/docs/image/portal_sidebar.png)

While we recommend keeping the underlying folder structure consistent with the sidebar, it doesn't have to be that way. The sidebar is configured by a (mandatory) `sidebars.yaml` file in the section's folder.

```yaml
items:
    - link: index.md
      label: Introduction
    - label: Quick Start Guides
      link: guides/index.md
      items:
          - link: guides/organisation.md
            label: File Organisation
          - link: guides/pushing.md
            label: Pushing Content (Git)
          - link: guides/rendering_schemas.md
            label: Rendering Schemas
```

```jsonSchema protocol=config version=sidebars-yaml-schema def=sidebarItem
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "link",
        "label"
    ],
    "properties": {
        "link": {
            "type": "string",
            "description": "The path to the Markdown file (or API spec) **relative to the section folder**. This is the only required attribute for a sidebar entry."
        },
        "label": {
            "type": "string",
            "description": "Display label."
        },
        "items": {
            "type": "array",
            "description": "Array of nested child items. If present, the entry is rendered as a collapsible group rather than a plain page. Groups can be nested.",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "link",
                    "label"
                ],
                "properties": {
                    "link": {
                        "type": "string",
                        "description": "The path to the Markdown file (or API spec) **relative to the section folder**. This is the only required attribute for a sidebar entry."
                    },
                    "label": {
                        "type": "string",
                        "description": "Display label."
                    },
                    "items": {
                        "type": "array",
                        "description": "Array of nested child items. If present, the entry is rendered as a collapsible group rather than a plain page. Groups can be nested.",
                        "items": {
                            "$refName": "sidebarItem",
                            "$refResolved": false
                        }
                    },
                    "guestVisibility": {
                        "type": "string",
                        "enum": [
                            "invite",
                            "hide",
                            "show"
                        ],
                        "description": "Controls visibility of the item for guest users. `invite` shows a padlock and login link. Defaults to `show`."
                    },
                    "authenticatedVisibility": {
                        "type": "string",
                        "enum": [
                            "hide",
                            "show"
                        ],
                        "description": "Controls visibility of the item for authenticated users. Defaults to `show`."
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Limits visibility to users belonging to entities with one of the specified roles."
                    }
                },
                "$refName": "sidebarItem",
                "$refResolved": true
            }
        },
        "guestVisibility": {
            "type": "string",
            "enum": [
                "invite",
                "hide",
                "show"
            ],
            "description": "Controls visibility of the item for guest users. `invite` shows a padlock and login link. Defaults to `show`."
        },
        "authenticatedVisibility": {
            "type": "string",
            "enum": [
                "hide",
                "show"
            ],
            "description": "Controls visibility of the item for authenticated users. Defaults to `show`."
        },
        "roles": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Limits visibility to users belonging to entities with one of the specified roles."
        }
    }
}
```

:::info Use Of Relative Paths
Each `sidebars.yaml` file lives within a folder, and `link` elements are to files within that folder **unless they are API references**. For links to Markdown pages, avoid traversing outside the current section folder using `../` path notation or fully-qualified paths.
:::

Note that a single page that appears at the _root_ of a `sidebars.yaml` file is styled the same as a group element for consistency. The only difference is the collapse caret.

### Links to API Specs

Fragments of API specifications can be placed inline on a Markdown page using [Inlined API & Schema Reference](/portal/reference/endpoints_schemas#inlined-api-schema-references) notation.

Alternatively, you can render the whole API specification on a single page in much the same way that SwaggerUI or Redocly do. To create such a link, simply indicate the spec path relative to the `/docs/apis` folder. The portal will automatically detect the API type (OpenAPI or FinSpec), and render the full specification accordingly.

```yaml
# This generate a sidebar link labelled "FixSpec API" and points to the OpenAPI file /docs/apis/openapi/fixspec/v5.yaml
- link: openapi/fixspec/v5.yaml
  label: FixSpec API
```

:::info Auto-Generating Sidebars Within Specs
When rendering a full API specification, the portal uses a different layout which automatically generates the left-hand navigation. This can not be edited manually.
:::

### Error Handling

Any `sidebars.yaml` entry the portal can't make sense of — a malformed spec path, an
entry with neither `page` nor `group`, or a non-mapping list entry — is **dropped from
the rendered sidebar rather than causing the page to fail to load**, so a bad entry
never takes down the whole sidebar.

### Frequently Asked Questions

:::faqs
::faq[Does a top-level navbar link also control access to the pages beneath it?]{#faq_portal_navigation_navbar_scope}
No. A `navbar` entry in `portal.yaml` only controls the first page of a section — it has no visibility into the sidebar hierarchy underneath. To control access to the rest of a section's pages, set `guestVisibility`, `authenticatedVisibility` or `roles` in that section's `sidebars.yaml`.
::
::faq[What happens if I get a `sidebars.yaml` entry wrong?]{#faq_portal_navigation_invalid_entry}
The portal drops the malformed entry from the rendered sidebar rather than failing the whole page, so one bad entry won't take your entire section offline. See [Error Handling](#error-handling) above.
::
:::
