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), ready to render.

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

💡 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
Figure: Dynamic header navigation bar

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.

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
Figure: Dynamic sidebar navigation

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

ℹ️ 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.

Fragments of API specifications can be placed inline on a Markdown page using Inlined API & Schema Reference 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

ℹ️ 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

Does a top-level navbar link also control access to the pages beneath it?

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.

What happens if I get a `sidebars.yaml` entry wrong?

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 above.