如何为Sphinx的Read the Docs主题设置移动端布局的切换触发宽度？

核心调整逻辑 #

需要修改的本质是主题样式表中定义的媒体查询断点值，将原本触发移动端单栏布局的最大视口宽度，从默认值往上调高数百像素即可，无需修改复杂的页面交互逻辑。

无侵入式调整步骤（不修改原生主题源码，避免被升级覆盖） #

• 在项目的文档重写目录下新建自定义样式文件，常规存储路径为docs/overrides/assets/stylesheets/custom.css
• 在自定义CSS文件内，统一将移动端布局关联的媒体查询断点值替换为目标宽度：
  • 主题默认的侧边栏折叠、单栏布局触发规则为@media screen and (max-width: 768px)
  • 若要将触发宽度提高500像素，直接将值调整为1268px，对应规则写为@media screen and (max-width: 1268px)
• 在项目根目录的mkdocs.yml配置文件中，关联刚编写的自定义CSS，配置项格式为extra_css: - assets/stylesheets/custom.css

调试注意事项 #

• 不要漏改三类关联断点：侧栏导航收缩、顶栏菜单折叠为汉堡按钮、正文双栏变单栏，三类断点要统一设置为相同数值，否则会出现布局错位
• 禁止直接修改虚拟环境内主题自带的原生CSS文件，后续主题版本升级时所有改动会被直接覆盖
• 本地调试时使用强制刷新快捷键Ctrl+Shift+R清除浏览器本地CSS缓存，避免因缓存导致看不到调整后的实际效果
• 断点数值不宜设置过高，建议最高不超过1300px，否则桌面端宽屏场景会被强制切换为移动端窄布局，影响正常阅读

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