Local docs build failing due to undefined nav items

[linkvt]

Hi,

I encountered an error while building/serving the docs locally with the mkdocs CLI and the container started via ./hack/docker/run.sh, which does not seem to be the case in CI or for other people considering the missing issues?

The problem is in the following two files, I'm able to build the docs locally with the following patch: linkvt@730411d

diff --git a/overrides/partials/nav.html b/overrides/partials/nav.html
index f1e1b833..e8ededad 100644
--- a/overrides/partials/nav.html
+++ b/overrides/partials/nav.html
@@ -69,10 +69,12 @@
 
   <ul class="md-nav__list" data-md-scrollfix>
     <!-- All NAVS: {{ nav.children }} -->
-    {% for nav_item in nav.children %}
-      <!-- nav item: {{ nav_item }} -->
-      {% set path = "__nav_" ~ loop.index %}
-      {{ item.render(nav_item, path, 1) }}
-    {% endfor %}
+    {% if nav.children %}
+      {% for nav_item in nav.children %}
+        <!-- nav item: {{ nav_item }} -->
+        {% set path = "__nav_" ~ loop.index %}
+        {{ item.render(nav_item, path, 1) }}
+      {% endfor %}
+    {% endif %}
   </ul>
 </nav>
diff --git a/overrides/partials/tabs.html b/overrides/partials/tabs.html
index e2c67ac0..8d137671 100644
--- a/overrides/partials/tabs.html
+++ b/overrides/partials/tabs.html
@@ -35,7 +35,7 @@
     {% set nav = section.children %}
   {% endif %}
 
-  {% if nav | length > 1 %}
+  {% if nav and nav | length > 1 %}
     <div class="md-grid">
       <ul class="md-tabs__list" id="sub-nav">
         {% for nav_item in nav %}
@@ -44,4 +44,4 @@
       </ul>
     </div>
   {% endif %}
-</nav>
\ No newline at end of file
+</nav>
 

Without this I get the following error:

Error in nav.html

❯ git clean -xfd 
Removing .cache/
Removing .venv/
Removing hack/__pycache__/
Removing site/
❯ ./hack/docker/run.sh
+ docker pull ghcr.io/knative/knative-docs:latest --platform linux/amd64
Trying to pull ghcr.io/knative/knative-docs:latest...
...
Writing manifest to image destination
27da22723a9da0e919248a3618c1424c0de5c46cd372880d8d92507d9335cda3
+ docker run --rm -p 8000:8000 -v /Users/vlink/repos/knative/docs/hack/docker/../../:/site ghcr.io/knative/knative-docs:latest serve --dirtyreload --dev-addr=0.0.0.0:8000
WARNING: image platform (linux/amd64) does not match the expected platform (linux/arm64)
INFO    -  Building documentation...
...
ERROR   -  Error building page 'index.md': 'NoneType' object is not iterable
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 7, in <module>
    sys.exit(cli())
             ^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1462, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1383, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1850, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1246, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 814, in invoke
    return callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/__main__.py", line 272, in serve_command
    serve.serve(**kwargs)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 85, in serve
    builder(config)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, serve_url=None if is_clean else serve_url, dirty=is_dirty)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 337, in build
    _build_page(
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 223, in _build_page
    output = template.render(context)
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 1295, in render
    self.environment.handle_exception()
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 942, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/site/overrides/home.html", line 1, in top-level template code
    {% extends "main.html" %} {% block content %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/site/overrides/main.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "/usr/local/lib/python3.11/site-packages/material/templates/base.html", line 154, in top-level template code
    {% block site_nav %}
^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/material/templates/base.html", line 162, in block 'site_nav'
    {% include "partials/nav.html" %}
^^^^^^^^^
  File "/site/overrides/partials/nav.html", line 72, in top-level template code
    {% for nav_item in nav.children %}
^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/runtime.py", line 424, in __init__
    self._iterator = self._to_iterator(iterable)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/runtime.py", line 432, in _to_iterator
    return iter(iterable)
           ^^^^^^^^^^^^^^
TypeError: 'NoneType' object is not iterable

Error in tabs.html

ERROR   -  Error building page 'about-analytics-cookies.md': object of type 'NoneType' has no len()
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 7, in <module>
    sys.exit(cli())
             ^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1462, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1383, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1850, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1246, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 814, in invoke
    return callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/__main__.py", line 272, in serve_command
    serve.serve(**kwargs)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 85, in serve
    builder(config)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, serve_url=None if is_clean else serve_url, dirty=is_dirty)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 337, in build
    _build_page(
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 223, in _build_page
    output = template.render(context)
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 1295, in render
    self.environment.handle_exception()
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 942, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/site/overrides/main.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "/usr/local/lib/python3.11/site-packages/material/templates/base.html", line 140, in top-level template code
    {% block header %}
^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/material/templates/base.html", line 141, in block 'header'
    {% include "partials/header.html" %}
^^^^^^^^^^^^^^^^^^^^^^^
  File "/site/overrides/partials/header.html", line 149, in top-level template code
    {% include "partials/tabs.html" %}
^^^^^^^^^^^^^^^^^^^^^
  File "/site/overrides/partials/tabs.html", line 38, in top-level template code
    {% if nav | length > 1 %}
TypeError: object of type 'NoneType' has no len()

While that is a solution for me there are surely multiple ways to fix it, not sure about the best approach as I'm not familiar with mkdocs-awesome-nav which does seem to set nav IIRC.

fyi @evankanderson , I saw that you worked on the navigation just recently.

Thanks, Vincent

[evankanderson]

Hi Vincent!

Interesting! I've been using the locally-installed tools with uv, so I haven't looked at the difference with the docker-ized container.

I'm happy to review a PR from you, or I have a plan to replace some of the custom overrides with a simpler navigation setup (famous last words!) in the next few weeks.