Python中如何实现Mkdocs目录折叠功能

在MkDocs中实现目录折叠功能，通常需要借助特定的主题插件。最直接和推荐的方法是使用 mkdocs-material 主题，它内置了强大的目录导航功能，包括可折叠的目录树。

首先，确保你安装了 mkdocs-material：

pip install mkdocs-material

然后，在你的 mkdocs.yml 配置文件中启用它，并进行相关设置：

site_name: My Docs
theme:
  name: material
  features:
    - navigation.expand # 默认展开当前活动的目录分支
    # - navigation.sections # 此功能在较新版本中可启用章节式折叠侧边栏
    - navigation.instant # 无刷新即时跳转
    - navigation.tracking # 高亮当前阅读位置
    - navigation.top # 返回顶部按钮
    # 更精细的折叠控制通常通过`navigation.indexes`或`navigation.instant`等特性组合实现

mkdocs-material 的侧边栏导航默认就是可折叠的。当你有一个嵌套的文档结构时，父级目录旁边会出现一个可点击的三角图标，点击即可展开或折叠其下的所有子页面。

如果你的目录结构没有自动折叠/展开，请检查你的文档组织结构。一个典型的、能正确触发折叠功能的 nav 配置如下：

nav:
  - Home: index.md
  - User Guide:
    - Introduction: user-guide/intro.md
    - Installation: user-guide/install.md
    - Configuration:
      - Basic: user-guide/config/basic.md
      - Advanced: user-guide/config/advanced.md
  - API Reference:
    - Overview: api/overview.md
    - Functions: api/functions.md

在这个结构中，“User Guide”和其下的“Configuration”都是可折叠的章节。

核心要点：使用 mkdocs-material 主题并正确组织 nav 配置是实现目录折叠最标准的方法。无需自己写JavaScript或CSS。

如果因为某些原因不能使用 mkdocs-material，而必须使用其他主题（如 readthedocs），那么实现折叠会非常麻烦，通常需要自己编写并注入JavaScript代码来操作DOM，这超出了MkDocs的标准支持范围，也不建议这么做。

总结：用 mkdocs-material 主题。