MkDocs生成的Read-The-Docs站点内容宽度与表格滚动问题咨询

问题说明 #

用户使用MkDocs生成的Read-The-Docs风格站点存在以下问题：

• 内容无法填满浏览器宽度，右侧存在无内容的灰色区域，希望让内容尽可能占满屏幕（Chrome、Edge均出现此问题）
• 表格因内容区域过窄需要横向滚动，想改为自动换行或控制滚动行为

站点截图：

一、内容宽度控制（填满屏幕） #

这是RTD主题的默认设计——限制主内容最大宽度来提升大屏幕可读性，完全可以自定义修改，两种常用方法：

1. 主题配置直接调整 #

在项目的mkdocs.yml中添加配置，直接设置内容最大宽度：

theme:
  name: readthedocs
  options:
    max_width: 1200px  # 按需调整数值，设为none则取消宽度限制，完全占满

2. 自定义CSS彻底修改 #

如果配置项不够灵活，用自定义CSS覆盖默认样式：

1. 在docs目录下创建css/custom.css文件
2. 写入以下样式：

.wy-nav-content {
    max-width: none !important;  /* 取消内容最大宽度限制 */
    width: 95%;  /* 可选，设置内容占屏幕的比例，避免贴边太近 */
}

3. 在mkdocs.yml中引入这个自定义CSS：

extra_css:
  - css/custom.css

二、表格滚动/换行控制 #

和Sphinx一样，MkDocs也可以通过修改CSS来调整表格行为，两种方向：

1. 强制表格内容自动换行 #

把默认的横向滚动改成内容换行，添加到custom.css中：

.wy-table-responsive table td, .wy-table-responsive table th {
    white-space: normal !important;  /* 取消强制不换行 */
    word-wrap: break-word;  /* 长单词或长内容自动换行 */
}
.wy-table-responsive {
    overflow-x: visible !important;  /* 移除横向滚动条 */
}

2. 保留滚动但扩大表格容器 #

如果不想换行，只想让表格能利用更多宽度，可单独调整表格容器：

.wy-table-responsive {
    max-width: 100% !important;
}

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