WIP: enable section indexes by default, allow deeper nesting in sidenav

documentation/docs/configuration/extensions/python-markdown.md

@@ -28,7 +28,7 @@ No configuration options are available. See reference for usage:
   [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
   [Adding buttons]: ../../elements/buttons.md#default
   [Adding tooltips]: ../../elements/tooltips.md#example
-  [Adding link target]: ../../elements/links.md#enhanced-example
+  [Adding link target]: ../../elements/links.md#example
 
 ## Definition Lists
 

documentation/mkdocs.yml

@@ -19,14 +19,11 @@ nav:
         - Sans Dark: 'configuration/palettes/sans-dark.md'
       - Features: 'configuration/features.md'
       - Blocks: 'configuration/blocks.md'
-      - Plugins: 'configuration/plugins/index.md'
-      - '___Git Revision': 'configuration/plugins/git-revision.md'
-      - '___Macros': 'configuration/plugins/macros.md'
-      - '___Search': 'configuration/plugins/search.md'      
-      - Extensions: 'configuration/extensions/index.md'
-      - Markdown Extensions: 'configuration/extensions/python-markdown.md'
-      - PyMdown Extensions: 'configuration/extensions/pymdown-extensions.md'
-      - '___Snippets': 'configuration/extensions/snippets.md'
+      - Plugins: 
+        - Index: 'configuration/plugins/index.md'
+        - Git Revision: 'configuration/plugins/git-revision.md'
+        - Macros: 'configuration/plugins/macros.md'
+        - Search: 'configuration/plugins/search.md'      
     - Navigation:
         - Section Indexes: 'navigation/section-indexes.md'
         - Table of Contents: 'navigation/toc.md'
@@ -51,6 +48,12 @@ nav:
       - Tables: 'elements/table.md'
       - Tooltips: 'elements/tooltips.md'
       - Typography: 'elements/typography.md'
+    - Extensions: 
+      - Index: 'configuration/extensions/index.md'
+      - Markdown Extensions: 'configuration/extensions/python-markdown.md'
+      - PyMdown Extensions: 
+        - Index: 'configuration/extensions/pymdown-extensions.md'
+        - Snippets: 'configuration/extensions/snippets.md'      
     - Install: 'install.md'
     - Releases: 'releases.md'
 
@@ -109,4 +112,7 @@ theme:
     - about/coverage-report/index.html
 
 extra_css:
-  - overrides/extra.css
+  - overrides/extra.css
+
+extra:
+  MAX_SIDE_NAV_SECTION_NESTING: 4

package.json

@@ -1,6 +1,6 @@
 {
     "name": "mkdocs-terminal",
-    "version": "4.4.0",
+    "version": "5.0.0",
     "description": "Terminal.css theme for MkDocs",
     "keywords": [
         "mkdocs",
@@ -25,4 +25,4 @@
     "engines": {
         "node": ">= 16"
     }
-}
+}

terminal/macros/side-nav/side-nav-item.j2

@@ -1,23 +1,33 @@
-{% macro index_item( nav_item, class ) -%}
-    {% if nav_item.active %}
-        <span {% if class %}class="{{ class }}"{% endif %}>{{ nav_item.parent.title }}</span>
-    {% else %}
-        <a {% if class %}class="{{ class }}"{% endif %} href="{{ nav_item.url|url }}">{{ nav_item.parent.title }}</a>
-    {% endif %}
-{%- endmacro -%}
+{% import 'macros/side-nav/side-nav-utils.j2' as side_nav_utils with context %}
 
+{% macro side_nav_item( nav_item, nesting_level) -%}
+    {% if nesting_level <= side_nav_utils.get_max_nesting()|int %}
+        {% if nav_item.children %}
+            <li>
+            {# if the section has an index page, use the index page's URL for the href link #}
+            {% if side_nav_utils.has_index_page(nav_item) %}
+                <a href="{{ side_nav_utils.get_section_url(nav_item) | url }}"><span {{ side_nav_utils.get_class_attr_snippet( nav_item ) }}>{{ nav_item.title }}</span></a>
 
+            {# if the section does not have an index, just display the section title #}
+            {% else %}
+                <span {{ side_nav_utils.get_class_attr_snippet( nav_item ) }}>{{ nav_item.title }}</span>
+            {% endif %}
 
-{% macro non_index_item( nav_item, class ) -%}
-    {% if nav_item.active %}
-        <span {% if class %}class="{{ class }}"{% endif %}>{{ nav_item.title }}</span>
-    {% else %}
-        {% if nav_item.is_section %}
-            {# nav_item.is_section covers MkDocs Section objects #}
-            {# MkDocs Section objects do not have a URL to use as a link #}
-            <span {% if class %}class="{{ class }}"{% endif %}>{{ nav_item.title }}</span>
+            {# if the section has children, recurse #}
+            {% for child in nav_item.children %}
+                <ul>
+                    {{ side_nav_item(child, nesting_level+1) }}
+                </ul>
+            {% endfor %}
+            </li>
         {% else %}
-            <a {% if class %}class="{{ class }}"{% endif %} href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
-        {% endif %}
-    {% endif %}
+            {# don't render section index pages as sub pages (this would be redundant) #}
+            {% if nav_item.is_page and ( nav_item.title != side_nav_utils.get_section_index_title_indicator()) %}
+                <li>
+                    {# if the item is a page then use its link #}
+                    <a href="{{ nav_item.url | url }}"><span {{ side_nav_utils.get_class_attr_snippet( nav_item ) }}>{{ nav_item.title }}</span></a>
+                </li>
+            {% endif %}
+        {%endif%}
+    {%endif%}
 {%- endmacro -%}

terminal/macros/side-nav/side-nav-utils.j2

@@ -0,0 +1,71 @@
+{# returns the default title "Index" if 'config.extra.SECTION_INDEX_PAGE_TITLE' is undefined #}
+{# returns the user's 'config.extra.SECTION_INDEX_PAGE_TITLE' value otherwise #}
+{% macro get_section_index_title_indicator() -%}
+{% if config.extra.SECTION_INDEX_PAGE_TITLE %}{{ config.extra.SECTION_INDEX_PAGE_TITLE }}{% else %}Index{% endif %}
+{%- endmacro -%}
+
+{# returns the default maximum side navigation depth "2" if 'config.extra.MAX_SIDE_NAV_SECTION_NESTING' #}
+{% macro get_max_nesting() -%}
+{% if config.extra.MAX_SIDE_NAV_SECTION_NESTING %}{{ config.extra.MAX_SIDE_NAV_SECTION_NESTING }}{% else %}2{% endif %}
+{%- endmacro -%}
+
+{# returns "True" if nav_item has children and one of the children has a 'title' attribute == 'Index'#}
+{# returns "" otherwise #}
+{% macro has_index_page( nav_item ) -%}
+{% if nav_item.children|selectattr("title", "eq", get_section_index_title_indicator() )|list|length == 0 %}{% else %}True{% endif %}
+{%- endmacro -%}
+
+{# if nav_item has one index page, return the index page's URL #}
+{# returns "" otherwise #}
+{% macro get_section_url(nav_item) -%}
+{% if nav_item.children|selectattr("title", "eq", get_section_index_title_indicator() )|list|length == 1 %}
+{%- set section_index_page = nav_item.children|selectattr("title", "eq", get_section_index_title_indicator() )|first %}{{ section_index_page.url }}{% else %}{% endif %}
+{%- endmacro -%}
+
+
+{% macro get_base_class( nav_item ) -%}
+    {% set ns = namespace(class="terminal-mkdocs-side-nav-item", is_active_index=false) %}
+    {% if nav_item.active %}
+        {%- set ns.class = ns.class ~ "--active" -%}
+    {% endif %}
+
+    {% if "navigation.side.indexes" in features and nav_item.title == get_section_index_title_indicator() %}
+        {# if nav_item is a index page, check to see if any of its' siblings are active) #}
+        {% for index_sibling in nav_item.parent.children %}
+            {% if index_sibling.active %}
+                {% set ns.is_active_index = true %}
+            {% endif %}
+        {% endfor %}
+        {% if ns.is_active_index %}
+            {%- set ns.class = ns.class ~ "--active" -%}
+        {% endif %}
+    {% endif %}
+
+    {{ ns.class|trim }}
+{%- endmacro -%}
+
+
+{# 'terminal-mkdocs-side-nav-section-no-index' css class used to indicate a non-clickable folder #}
+{% macro get_class( nav_item ) -%}
+    {% set ns = namespace(class="") %}
+    {%- set ns.class = get_base_class( nav_item ) -%}
+
+    {% if nav_item.children %}
+        {% if "navigation.side.indexes" not in features %}
+            {%- set ns.class = ns.class ~ " terminal-mkdocs-side-nav-section-no-index" -%}
+        {% else %}
+            {% if nav_item.children|selectattr("title", "eq", get_section_index_title_indicator() )|list|length == 0 %}
+                {%- set ns.class = ns.class ~ " terminal-mkdocs-side-nav-section-no-index" -%}           
+            {% endif %}
+        {% endif %}
+    {% endif %}
+
+    {{ ns.class|trim }}
+{%- endmacro -%}
+
+{# returns HTML class attribute snippet#}
+{% macro get_class_attr_snippet( nav_item ) -%}
+    {% set macro_ns = namespace(class="") -%}
+    {% set macro_ns.class = get_class( nav_item ) -%}
+    {% if macro_ns.class %}class="{{ macro_ns.class }}"{% endif %}
+{%- endmacro -%}

terminal/partials/html-title.html

@@ -1,6 +1,6 @@
-{% import 'macros/side-nav/section-index-page-title.j2' as index_helper with context %}
+{% import 'macros/side-nav/side-nav-utils.j2' as side_nav_utils with context %}
 
-{% if "navigation.side.indexes" in features and page and page.title and page.title == index_helper.get_section_index_page_title() and page.parent and page.parent.title %}
+{% if "navigation.side.indexes" in features and page and page.title and page.title == side_nav_utils.get_section_index_title_indicator() and page.parent and page.parent.title %}
     {% set tab_title = page.parent.title %}
 {% else %}
     {% set tab_title = page.title %}

terminal/partials/side-nav/side-nav.html

@@ -1,9 +1,10 @@
+{% import 'macros/side-nav/side-nav-item.j2' as side_nav_utils with context %}
+
 <nav>
-  {% if nav|length>1 %}
-    <ul class="terminal-mkdocs-side-nav-items">
-        {% for nav_item in nav %}
-          {% include "partials/side-nav/side-nav-item.html" %}
-        {% endfor %}
-    </ul>
-  {% endif %}
-</nav>
+  <ul>
+    {% for nav_item in nav %}
+    {{ side_nav_utils.side_nav_item(nav_item, 1) }}
+    {% endfor %}  
+  </ul>
+</nav>
+

terminal/theme_version.html

@@ -1 +1 @@
-<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-4.4.0">
+<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-5.0.0">