Best way to show an arbitrary nav tree on the homepage?

[toomanybrians]

Hi Everyone!

I would like my homepage to display the standard left-column navigation tree with a sub-section of my site nav. The challenge is my home page is not part of the tree itself. For example:

nav:
  - My guide:
    - 1. Intro: intro/index.md
    - 2. Overview: overview/index.md
    - 3. Start: start/index.md

By default, the left hand nav on the homepage is blank, since the home page is not in the nav. No prob. But I want to show the nav at the "My Guide" level on my homepage. I'm wondering if someone can point me in the right direction as a starting point?

For example, should I make an index.html override and then add some logic in there to force it to show? Or should I override nav.html and put the logic in there?

I'm confident I can figure out how to actually make it happen, but it seems like there are several ways to approach this, so I wonder if someone has an opinion on what's the cleanest or most elegant way to approach this? (Worst case I just manually add it to the template, which would work but then I'd have to maintain the TOC in two places.)

Thanks!

[kamilkrzyskow]

Hello @toomanybrians,
the navigation on the left hand side should be visible even though the index.md isn't included 🤔
Perhaps you're using navigation.tabs which changes the rendering of navigation and sort of detaches it.

Firstly, I would abstain from modifying the nav either in the mkdocs.yml or via hooks to duplicate entries, as this would lead to bugs.

The quickest option to get it sorted would be to use a custom home.html template with a static HTML structure written in the site_nav block.

• https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-template
• https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks

• mkdocs-material/src/templates/base.html

  Lines 294 to 334 in 0c54a88

  	<!-- Sidebars -->
  	{% block site_nav %}
  	<!-- Navigation -->
  	{% if nav %}
  	{% if page.meta and page.meta.hide %}
  	{% set hidden = "hidden" if "navigation" in page.meta.hide %}
  	{% endif %}
  	<div
  	class="md-sidebar md-sidebar--primary"
  	data-md-component="sidebar"
  	data-md-type="navigation"
  	{{ hidden }}
  	>
  	<div class="md-sidebar__scrollwrap">
  	<div class="md-sidebar__inner">
  	{% include "partials/nav.html" %}
  	</div>
  	</div>
  	</div>
  	{% endif %}
  	<!-- Table of contents -->
  	{% if "toc.integrate" not in features %}
  	{% if page.meta and page.meta.hide %}
  	{% set hidden = "hidden" if "toc" in page.meta.hide %}
  	{% endif %}
  	<div
  	class="md-sidebar md-sidebar--secondary"
  	data-md-component="sidebar"
  	data-md-type="toc"
  	{{ hidden }}
  	>
  	<div class="md-sidebar__scrollwrap">
  	<div class="md-sidebar__inner">
  	{% include "partials/toc.html" %}
  	</div>
  	</div>
  	</div>
  	{% endif %}
  	{% endblock %}

If you're using the navigation.tabs setting another option would be to override nav-item.html and maybe nav.html as well to change the behaviour on the index.md page. It might be worth it to just create a custom file structure home.html -> partials/home_nav.html -> partials/home_nav-item.html, which could allow you to separate your changes from the rest of the site.

[toomanybrians]

Ah yes, I am using the navigation.tabs setting, sorry for not mentioning that! I'm familiar with partials and overrides, and the options you propose here are perfect and give me enough ideas to go down a working path.

Again, thanks!

[toomanybrians]

I have a follow up question for this.

I'm taking the route of a nav.html override for the home page so I can have my own custom left-sidebar structure. I'm just doing it manually in HTML. All good.

I can't figure out the CSS though. If I just copy the exact HTML code that's usually generated, my sidebar works fine, but then on mobile devices the hambuger menu shows my custom content sidebar content, rather than the "real" site nav from the header. I tried lots of different options with CSS classes and structure, but it looks like I'm missing something. I see that the top header site nav and sidebar site nav are sort of mingled together in the HTML, with ceratin "active" class names which trigger what's actually showing.

So I think I'm on the right path but can't completely figure it out. I wonder if someone who knows more about the way the menu and CSS works could give me some hints?

Thanks!
Brian

[kamilkrzyskow]

The tabs on top of the page are a separate HTML section that gets hidden given the correct media query.

@media screen and (max-width: 76.2344em) {
  .md-tabs {
    display: none;
  }
}

---

So the left navigation needs to include the top level elements and they're hidden based on a mix of CSS classes.

mkdocs-material/src/templates/partials/nav.html

Lines 26 to 30 in f4adebd

	{% set class = "md-nav md-nav--primary" %}
	{% if "navigation.tabs" in features %}
	{% set class = class ~ " md-nav--lifted" %}
	{% endif %}
	{% if "toc.integrate" in features %}

The navigation.tabs feature applies the --lifted class to the navigation, which hides the elements by default.

@media screen and (min-width: 76.25em) {
  .md-nav--lifted > .md-nav__list > .md-nav__item, .md-nav--lifted > .md-nav__title {
    display: none;
  }
}

but the --active navigation which is the current section of the page nullifies it:

@media screen and (min-width: 76.25em) {
  .md-nav--lifted > .md-nav__list > .md-nav__item--active {
    display: block;
  }
}

Warning

All of the max-min-width em values are calculated in the SCSS compilation process, and given that they're float numbers they can change between rebuilds.

---

As for which "layer" of the navigation tree is visible in the navigation drawer on the left on mobile view is decided by the "checked" status of the invisible toggles. Unfortunately both Firefox and Chrome dev tools do a bad job of showing the changes in the DOM, but if you'd check the state of the elements via JS the checked status would change from true to false.

@media screen and (max-width: 76.2344em) {
  .md-nav__toggle:checked ~ .md-nav {
    opacity: 1;
    transform: translateX(0);
    transition: transform .25s cubic-bezier(.4,0,.2,1),opacity 125ms 125ms;
    transition-property: transform, opacity;
    transition-duration: 0.25s, 125ms;
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1), ease;
    transition-delay: 0s, 125ms;
  }
}

I guess some rule applies here that elements lower in the DOM by default have a higher z-index value, so the navigation sections stack on top of each other.

All changes work with pure CSS without JavaScript, so all of the CSS classes are set in HTML already from the templates.

[toomanybrians]

Wow, amazing! Literally all I had to do was search the HTML nav menu code for checked and delete it and I'm all set.

Again, thanks!