Navigation menu issues when nesting pages

[NathanD-GDS]

What should change

There are a couple of issues that are related:

1. Nested pages display every heading on every nested page in the navigation bar
2. If a page has nested pages beneath/within it, the headings for the top-level page do not appear in the navigation bar

1. Nested pages display every heading on every nested page in the navigation bar

At the moment, if you nest pages with multiple headings in the tech docs template, every heading for every page in the nest is visible from the navigation bar.

In this example, the API reference page has 10 pages nested beneath it. You can see two of these nested pages in the screenshot - Create a payment API reference and Get information about a single payment API reference:

This is a problem because, when you load one of the nested pages, the navigation bar jumps right to the bottom. If you're viewing one of the

It would be useful if it were possible to have a global (or per-page) setting to only display the headings for the current page. So the example above would instead look like this:

2. If a page has nested pages beneath/within it, the headings for the top-level page do not appear in the navigation bar

In this example, the top-level page API reference has headings that should be visible in the navigation bar, such as Endpoint. Instead, the navigation bars is only displaying the nested pages and the headings from the nested pages:

User need

As it stands, I haven't done any testing with users beyond the GOV.UK Pay team. Within the Pay team, however, everyone that went to use the API reference commented on the navigation bar and its impact on their use.

EDIT: As of May 2023, a round of user research identified the navigation as pain point.

Issue 2 prevented them from easily jumping to the headings they needed on the top-level page.

Issue 1 caused general navigation issues, where the user would select, for example, nested page 1 but the navigation menu would jump to the bottom. The user needed to then scroll past 9 nested pages (and their headings) to re-orient themselves.

[SoumayaMauthoorMOJ]

Yes please! This would make our documentation more readable e.g. https://user-guidance.services.alpha.mojanalytics.xyz/data-engineering-tools/