Bypass nav sub-menus for single-child top-level links on mobile viewports

[s1monj]

Use case: we want a "Contact Us" tab/link that displays a simple single-section contact page with no additional nav or toc for all viewports

For viewports above 1220px, this can be achieved by:

theme:
  features:
    - navigation.tabs

nav:
  - Home: index.md
...
  - Contact Us:
    - contact.md

and then including the front matter hide: - navigation - toc in contact.md

(we can not use - Contact Us: contact.md under nav because it will be grouped under Home and not displayed as a tab)

However in smaller viewports, when the top hamburger button is clicked, this will render a top level menu:

Nav Menu
Home
Contact Us >

And when Contact Us is clicked, a sub menu is rendered with another Contact Us link to the page:

Contact Us
Contact Us

Feature request: Clicking twice for a single-child nav is confusing to the user who just wants to see the Contact Us page. Include a flag that allows sub-menus to be bypassed for single child top-level links on mobile viewports, so that the first "Contact Us" link takes the user directly to contact.md. Or alternatively, include a flag that allows top-level direct links ie - Contact Us: contact.md to have their own tab.

[squidfunk]

Thanks for your suggestion. I understand that tabs navigation between mobile/desktop may be unintuitive at times. Unfortunately, the content of the navigation sidebar/drawer is site-wide and cannot be adjusted with front-matter, which is page-specific. I'll check if we can add a flag, but I'm unsure whether this is generalizable to collapsing every single-page item for tabs navigation into a single link. In the end, we might have to circumvent the "grouping below home" behavior, which would be a breaking change.

It might be easier to add your link to nav so that it is correctly shown in the sidebar and manually add the link manually to the tabs.html partial through theme extension.

[squidfunk]

... another idea would be to add an option to config.extra similar to social links, which will always add links to the end of the tab navigation and sidebar on mobile. Would something like this work for you?

[s1monj]

Right, agreed the former sounds like a site-wide change so the latter of allowing top-level childless links to the tab may be the way to go.

I noticed issue "External link is not shown in the tab nav" #1884

I think it works in the nav-item.html because it renders items that have no child elements.
Where as tab-item.html only renders items that have children or are the main page.

Is there a design reason why tab-item.html does not render direct links that don't have child elements? Would it be possible to add a switch for this in mkdocs.yml?

I think the tabs.html partial workaround sounds like my best option at the moment, the config.extra is a bit messy as in practice I have a few of these simple, top-level pages

[squidfunk]

I agree that extra options are probably not a good way to go, as we'd break out of the navigation definition and could only add to the front or back, so let's scrap that.

The grouping behavior does mainly exist for historical/legacy reasons. However, changing that would definitely be a breaking change, at least in behavior. Adding more options would make it more complicated. I think we could tackle this together with #2060 as part of another refactoring of navigation. We can evaluate it when the next funding goal is reached, and all navigation improvements have been merged into master. It would actually make the theme lose some weight, which is a good thing. This would also mean we could remove the extra logic introduced in #1885.

[s1monj]

Nav refactoring sounds good, I can work-around until then no probs

In case others are interested, this is my first attempt - I'm sure it can be done a lot better but tried not to interfere with the original logic too much and seems to work for now

overrides/partials/tabs-item.html

{% if nav_item.url == "index.html" %}
    <li class="md-tabs__item">
        {% set class = "md-tabs__link" %}
        {% if not page.ancestors | length and nav | selectattr("url", page.url) %}
        {% set class = "md-tabs__link md-tabs__link--active" %}
        {% endif %}
        <a href="{{ nav_item.url | url }}" class="{{ class }}">
        {{ nav_item.title }}
        </a>
    </li>
{% elif nav_item.url and nav_item.url.startswith("http") %}
    <li class="md-tabs__item">
        <a href="{{ nav_item.url | url }}" class="md-tabs__link">
        {{ nav_item.title }}
        </a>
    </li>
{% else %}
    {% set title = title | default(nav_item.title) %}
    {% if nav_item.children and nav_item.children | length > 0 %}
        {% set nav_item_url = (nav_item.children | first).url %}
        {% if (nav_item.children | first).children %}
            {% set nav_item = nav_item.children | first %}
            {% include "partials/tabs-item.html" %}
        {% endif %}
    {% else %}
        {% set nav_item_url = nav_item.url %}
    {% endif %}
    <li class="md-tabs__item">
        {% set class = "md-tabs__link" %}
        {% if nav_item.active %}
            {% set class = "md-tabs__link md-tabs__link--active" %}
        {% endif %}
        <a href="{{ nav_item_url | url }}" class="{{ class }}">
            {{ title }}
        </a>
    </li>
{% endif %}

[squidfunk]

Thanks for sharing!

[squidfunk]

I refactored navigation tabs to be much more predictable in the latest version of Insiders, which resolves this issue - all first level items are now rendered as-is as part of the tabs, including external links and top-level pages:

When a top-level page is rendered, the navigation is rendered empty and can be hidden (if desired). The tabs navigation now effectively mirrors the first level of mobile navigation. Before, I tried to be too clever by transparently moving all top-level pages into the first tab which received the title of the first page. Over the years, I realized that this leads to confusion among users. I decided to simplify the current implementation. Navigation tabs should now be much simpler to use.

While this is more or less unintended behavior (i.e. a bug), it's not feasible to fix this as part of the community edition, as backporting it would require significant effort. However, if growth continues at this rate, the next funding goal should be reached at the end of this month and all new navigation options will be generally available as they're merged back into the community edition 😊

[squidfunk]

The funding goal has been reached and the respective features and fixes have just been merged from Insiders. The master is already up to date - watch out for a release.

[squidfunk]

6.2.1 was just released, which includes the fixes.