How to exclude some top-level navigation items when using navigation.tabs

[ben519]

I'm using Material to build a platform that hosts courses. The plan is to have dozens of courses or more, and I'm trying to figure out how to structure this large volume of content.

At the moment, I'm using navigation tabs. Functionally, this works great, but it looks bad having so many items in the header. For example, this..

theme:
  name: material
  features:
    - toc.integrate
    - navigation.tabs 

nav:
  - Home: index.md
  - Contributors: contributors.md
  - Super Awesome Course 1:
    - courses/course1/index.md
    - Section 1:
      - courses/course1/section1/example1.md
    - Section 2:
      - courses/course1/section1/example2.md
      - courses/course1/section1/example3.md
  - Super Awesome Course 2: course2.md
  - Super Awesome Course 3: course3.md
  - Super Awesome Course 4: course4.md
  - Super Awesome Course 5: course5.md
  - Super Awesome Course 6: course6.md

looks like this

Is there a way I can exclude these course links from the header?

What I've tried

1. You might be thinking, why don't I just create a top-level Courses section and list all courses beneath it. The problem is, when you view for example Course 1, the table of contents shows everything - not just the material related to course 1 - which is quite busy. Here's what that looks like..

theme:
  name: material
  features:
    - toc.integrate
    - navigation.tabs 
   
nav:
  - Home: index.md
  - Contributors: contributors.md
  - Courses:
    - Super Awesome Course 1:
      - courses/course1/index.md
      - Section 1:
        - courses/course1/section1/example1.md
      - Section 2:
        - courses/course1/section1/example2.md
        - courses/course1/section1/example3.md
    - Super Awesome Course 2: course2.md
    - Super Awesome Course 3: course3.md
    - Super Awesome Course 4: course4.md
    - Super Awesome Course 5: course5.md
    - Super Awesome Course 6: course6.md

Notice how different the TOC looks for the same course (from my first attempt above).

2. I could exclude courses/course1/index.md from the nav altogether and the page is still accessible via a direct link to /courses/course1, but in this case it excludes the lower-level sections and content. (i.e. I just get that one page).

I suspect the best approach to solving this is to override whichever template renders the header. Any advice here would be appreciated. (P.S. Loving Material for MkDocs so far!)

[squidfunk]

Great question. I agree that it's sometimes hard to find a structure that just feels right and you need to go back and forth until settling for something that works well. So as I understand – you want to structure content with tabs, but you want to omit the links from the tab bar. A problem that comes to mind is… how does the user navigate? How does he get back to the home page or switch between courses? Nonetheless, in order to hide all tabs you could just add a few lines of extra CSS:

.md-tabs {
  display: none;
}

If you want to hide a specific tab, you could just use nth-child to select the specific course (easy solution) or extend the tabs.html template to somehow check whether to skip a page or render it (more sweat required). For the CSS-only solution:

.md-tabs__item:nth-child(1), /* 1st tab */
.md-tabs__item:nth-child(2), /* 2nd tab, and so on ... */
.md-tabs__item:nth-child(3) { 
  display: none;
}

... or add a check here before the template inclusion:

mkdocs-material/src/partials/tabs.html

Lines 34 to 36 in 7d8165c

	{% for nav_item in nav %}
	{% include "partials/tabs-item.html" %}
	{% endfor %}

Theme extension is described here – it should be pretty straight-forward. Note that since you're probably using Insiders, you should copy tabs.html from from the Insiders repository as the source might be a little different due to additional features.

[ben519]

how does the user navigate

1. I don't want to hide everything in the header. I want to include links for things like the home page, contributors, contact, etc.
2. I plan on building a custom home page with sections like "featured courses" or "new courses", etc. I'll use direct links from there to get to a specific course page.

I think overriding tabs.html is the way to go (I was just looking at this). Appreciate your guidance.

(The only thing I'm still slightly confused about is how to extend some of these partials. I can override tabs.html easily enough, but if you update tabs.html tomorrow, my overridden version will lack your updates. I need to study jinja2 some more I guess..)

[squidfunk]

Yes, that's can always happen. I always try to keep template/partial changes to a minimum, but adding new features sometimes makes them necessary. I thought about whether we can generalize the hiding of tabs, but I don't think that's possible without sacrificing at least some flexibility.

[ben519]

My 2 cents:

I think most people's issues (including my own) could be solved by templating. What's missing (in my opinion) is an official tutorial on how to extend your templates.

I'm figuring out how to do this now. I'll write back how I solved this particular problem because I think it'll be helpful for others.

[squidfunk]

The documentation has guides on how to override partials and template blocks with examples. What else would you wish to appear?

[TiesWestendorp]

Just a heads up, the referenced partial (tabs.html) has since been updated, check the current version here.

I managed to achieve the desired effect by filtering on url by replacing the appropriate part of the partial by:

                {% if nav_item.url not in [ ... ] %}
                    {{ item.render(nav_item) }}
                {% endif%}

[jcyrss]

Mkdocs populates a whole structure tree of project in the nav. That's not good for a large project. Especially when website owner wants to hide some directories from top-level nav tracing.

But we still want those hidden pages be accessible if user get links of them. So how to display nav-tree on left side when those pages are displayed?

In current implementation of Mkdocs-material, it seems impossible to display a page with left side nav independent from main nav.

Yes, many independent navs and a top level nav, that's what I need, that's what Hugo does.

I'm trying to implement that by a hook function on_page_context. Before rendering a page, check the page file path (and maybe some other rules), and pass an independent nav for mkdocs to render that page.

But it seems still need to modify Jinjia template file nav-item.html. I'm new to Jinjia, it would take me some time to do that.

[squidfunk]

Yes, many independent navs and a top level nav, that's what I need, that's what Hugo does.

Sounds like you'd want to enabled navigation.tabs to split your top level navigation as we do it on our documentation. If that's not what you're describing, please elaborate and provide a detailed example so we can better understand your needs.

Besides that, I'm not entirely sure I understand what you're aiming for, but in order to build a page, yet exclude it from the navigation, MkDocs offers the not_in_nav setting where you can configure which pages are deliberately not included in the navigation. Also note that you do not have to let MkDocs populate nav, you can do it yourself and decide what to include and what not. Additionally, there's the awesome-pages plugin which offers even more flexibility.

[squidfunk]

On another note, the projects plugin might also be interesting, as it allows you to build separate projects (with separate navigation) together into one MkDocs site. Note that it is currently reserved to sponsors.

[jcyrss]

please elaborate and provide a detailed example so we can better understand your needs

Please see my reply to @alexvoss below.

[alexvoss]

There are some useful books out there about information architecture that can help avoid having to display too many top-level categories. I am reading Information Architecture by Rosenfeld et al. and while it is at times a little wordy, the stuff in there is really useful. One reason why navigation hierarchies often grow too large is because they mix different kinds of organization schemes - such as topics, tasks and audiences. These can often be dealt with in separate navigation structures instead of cramming them into one.

If you want to have alternative navigation structures, this can be done in a number of ways. Let's assume that the main structure is topic-oriented, like the documentation for Material for MkDocs is. You might want to have a secondary navigation structure that is audience-oriented (say: admins, developers, product owners). Top-level navigation for such an audience-centric structure often sits on top of a search functionality in the header but it might also make sense to have it on the homepage. There are too many variations to make everything configurable, unfortunately, so some customization will be needed.

The way I would approach this is to configure the header block and to include a div for content that sits atop the actual header on the homepage only.

{% block header %}
  {% if page.is_homepage %}
    <div>
      Admins | Developers | Product Owners
    </div>
  {% endif %}
  {% include "partials/header.html" %}
{% endblock %}

Add CSS to your heart's content and, of course, the appropriate links. Task-oriented alternative navigation I would offer on the main page in the content section as tutorials are important entry points for users and deserve a highly visible space. That is, of course, as always, just my 2p.

[jcyrss]

I am not sure why the python part seems to be always included.

That's just an example of display tightly related topics together in side-nav menu.

Without that it would boil down to showing only the current level and one level above?

I wish the side nav-menu is not showed in the way of doc project directory levels. Doc authors could configure which docs belong to which topic menus. Hugo does that in this way. I found it fits my needs pretty well, except I hope the docs menu could be specified in whole-folder way, like in .meta file in directory, instead of in each doc files.

How would the user access other parts of the navigation structure?

Through top level nav menu on header or links on home page. Or links in other related doc pages, like "Please read this(a link) for (a related topic)".

I do wonder if your claim that users are "lost and confused" is empirically true? Is this based on user research?

Sorry for using word hastily. I'm not navtive English speaker. Better to say 'make me confused'.

My project directory tree is a little complex. Displaying all in left side is too much, and that's not the way I want user to view. And I don't want user see all the doc project tree.

Also I found another issue of making side-nav-menu whole doc tree. That is when we make a little modification, like just changing one page title, we need to rebuild the whole project. Because nav menus in every pages were built with previous name.

[squidfunk]

This might be implementable with a hook that extracts metadata from documents to override the navigation structure, but it is definitely out of scope for us. Our focus is to keep things as simple as possible and provide a coherent navigation structure without too much configuration. We already have a lot of options that influence how navigation is rendered and cut, and adding more degrees of freedom is currently not planned because of the complexity it would entail.

It sounds like Hugo is a better choice for you than Material for MkDocs 😉

[jcyrss]

Yes, I'm tring to do that with a hook.

It sounds like Hugo is a better choice for you than Material for MkDocs

Hugo does meet most of my needs now. But comparing to MkDocs, it is not flexiable enough. It has its own shortcodes/hook, but all in HTML template way. Some customizings are hard to implement.

Another big thing is, I have not found a theme of Hugo to me as satisfied as MkDocs Material.

That's why I'm trying to migrate to Mkdocs even it will take me some time.

[alexvoss]

I wish the side nav-menu is not showed in the way of doc project directory levels. Doc authors could configure which docs belong to which topic menus.

This sounds a bit like you are letting the navigation structure be generated rather than defining it in the nav section of your mkdocs.yml?

There is no reason at all why the navigation structure needs to follow the directory structure used to organize your content. Admittedly, it is a bit for work but if you do have external users it is worth it.

IMHO the options described in the setting up navigation should be sufficient for even the largest projects. If the navigation becomes overwhelming then that is a sign that the structure may need to be re-thought. You may be looking for / developing a technical solution for what is a question of information architecture.

[jcyrss]

This sounds a bit like you are letting the navigation structure be generated rather than defining it in the nav section of your mkdocs.yml?

I have tried both auto-gen and manually configuring in mkdocs.yml. Later I realized the point is, in mkdoc, we only have one nav menu for all pages by default, right?

If so, that's the problem troubling me. We have to put every page as a item in that nav menu for every page. It is too large. And one modification on one page title, we have to rebuild whole website.