Supplementing generated navigation

[stevegroom]

I have a large document with generated navigation. I wanted to add to the side bar a few manual links - specifically to external addresses. Creating Nav elements in mkdocs.yml works, but requires that all navigation links are created manually there and I am not happy with the risk of missing changes to the navigation elements over time.

To address this, I used the overrides feature to insert external navigation links before or after the generated links.

Create docs/overrides/partials/nav.html copied from https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav.html

I then added two blocks of code - look for 4 x override below:

...
<!-- Repository information -->
  {% if config.repo_url %}
    <div class="md-nav__source">
      {% include "partials/source.html" %}
    </div>
  {% endif %}

  <!-- Override add external links before the generated navigation items -->
  {% if config.extra.nav_items_pre is defined %}
    {% for nav_item in config.extra.nav_items_pre %}
      {% set path = "nav-" + loop.index | string %}
      {% set level = 1 %}
      {% include "partials/nav-item.html" %}
    {% endfor %}
  {% endif %}
  <!-- /Override add external links before the generated navigation items -->
  
  <!-- Render item list -->
  <ul class="md-nav__list" data-md-scrollfix>
    {% for nav_item in nav %}
    {% set path = "__nav_" ~ loop.index %}
    {% set level = 1 %}
    {% include "partials/nav-item.html" %}
    {% endfor %}
  </ul>

    <!-- Override add external links after the generated navigation items -->
    {% if config.extra.nav_items_post is defined %}
      {% for nav_item in config.extra.nav_items_post %}
        {% set path = "nav-" + loop.index | string %}
        {% set level = 1 %}
        {% include "partials/nav-item.html" %}
      {% endfor %}
    {% endif %}
<!-- /Override add external links after the generated navigation items -->

</nav>

These blocks then loop over any override made in mkdocs.yml in the extra section:

...
extra:
  generator: false
  nav_items_pre:
    - FAQ:
      title: 'FAQ'
      url: 'https://example.com/faq'
  nav_items_post:
    - FAQ:
      title: 'FAQ'
      url: 'https://example.com/faq'
    - '(C)':
      title: 'SRO'
      url: 'https://example.com/'
...

This seems to work for me, but I don't understand what is going on behind the scenes so might be mistaken.

Do you consider this to be the right approach?

Do you have any tips on how best to be aware when the original nav.html that file I copied is maintained so that I might update my override version in a timely manner?

Steve

[stevegroom]

I did find a cosmetic issue - the new link has a bullet point and line break when rendered in Chrome and appears without bullet on FireFox.

Considering that it is a difference between browsers, is this a mkdocs, material or my own bug ?

Steve

[squidfunk]

It's definitely not a bug on our side, as you're in customization land, where you're always on your own 😉