Material for MkDocs自定义首页后折叠导航栏失效问题求助

问题根源 #

1. 脚本覆盖导致原生功能失效：{% block scripts %}中仅引入Bootstrap脚本，未调用{{ super() }}，覆盖了Material for MkDocs自带的导航栏交互脚本，折叠导航的逻辑无法运行。
2. 样式块嵌套错误：{% block styles %}被嵌套在{% block tabs %}内部，违反模板结构规则，导致样式加载顺序混乱。
3. 核心容器隐藏破坏交互依赖：直接隐藏.md-main容器，破坏了导航栏交互所需的DOM结构和事件绑定逻辑，引发暗屏问题。

修复后的home.html代码 #

{% extends "main.html" %}

<!-- 正确引入样式块，放在模板外层 -->
{% block styles %}
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet"
    integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.3/font/bootstrap-icons.css">
  {{ super() }} <!-- 继承Material for MkDocs原生样式 -->
{% endblock %}

<!-- 正确引入脚本块，先加载原生脚本 -->
{% block scripts %}
  {{ super() }} <!-- 保留原生导航交互脚本 -->
  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js"
    integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4"
    crossorigin="anonymous"></script>
{% endblock %}

{% block tabs %}
  {{ super() }}

  <!-- 首页专属样式覆盖 -->
  <style>
    /* 保持导航栏在顶部 */
    header.md-header {
      position: initial;
    }
    /* 隐藏内容而非核心容器，保留交互依赖 */
    .md-main__inner {
      display: none;
    }
  </style>

  <div class="header">
    <!-- 自定义首页内容 -->
  </div>
{% endblock %}

{% block content %}{% endblock %}
{% block footer %}{{ super() }}{% endblock %}

关键修复说明 #

• 保留原生脚本：通过{{ super() }}加载Material for MkDocs的原生交互脚本，确保折叠导航的逻辑正常运行。
• 调整样式块位置：将样式块移到模板外层，遵循Material for MkDocs的模板结构，保证样式加载顺序正确。
• 优化内容隐藏方式：隐藏.md-main__inner而非.md-main容器，保留导航交互所需的DOM结构，避免暗屏问题。

内容的提问来源于stack exchange，提问作者chillingfox