MkDocs Material主题extra.css自定义样式移动端不生效问题

问题表现 #

使用搭载Material主题的MkDocs搭建产品文档站点，通过extra.css自定义原生主题样式，桌面端浏览器访问时自定义样式正常加载：

移动设备访问时extra.css样式无法正常生效，渲染异常：

其中左侧为打开侧边菜单的显示效果，右侧为点击菜单内链接后的显示效果。

故障根因 #

1. CSS存在语法错误：原代码中.md-nav__item--nested>.md-nav__link的>是HTML转义后的大于号，不属于CSS合法语法，会导致CSS解析器中断该位置之后的规则解析。桌面端侧边导航DOM结构和移动端不同，未触发解析阻断，移动端抽屉式导航渲染时命中该错误规则，直接导致后续导航相关样式全部失效。
2. 固定定位样式未做响应式适配：原代码.md-float-right类写死了margin: 430px 0 0 650px的边距，该值仅适配桌面端大分辨率，移动端视口宽度普遍在320-480px区间，650px的左边距会直接将元素推出视口，同时撑破页面容器导致横向溢出。
3. 导航样式未区分响应式场景：Material主题移动端侧边栏为全屏抽屉结构，直接套用桌面端的圆角、内边距规则会出现渲染错位。

修复方案 #

直接将原有extra.css内容替换为以下修正后的代码即可：

.md-header__button.md-logo :-webkit-any(img,svg) {
    display: block;
    width: auto;
    height: 2rem;
    fill: currentColor;
}
.md-header {
    background-color: #0000cc;
}

input.md-search__input {
    width: 100%;
    height: 1.8rem;
    padding-left: 2.2rem;
    font-size: .8rem;
    opacity: 1;
    background-color: rgba(0,0,0,1);
    border-radius: 16px;
    text-align: left;
    letter-spacing: 0px;
    color: #ffffff;
}

.md-search__input:hover {
    background-color: rgba(0,0,0,1);
}
.md-search-result__teaser {
    display: -webkit-box;
    max-height: 2rem;
    color: #00348b;
    margin: .5em 0;
    overflow: hidden;
    font-size: .64rem;
    line-height: 1.6;
    text-overflow: ellipsis;
    -webkit-box-orient: vertical;
    -webkit-line-clamp: 2;
}

[data-md-toggle=search]:checked~.md-header .md-search__input {
    text-overflow: clip;
    background-color: var(--md-default-bg-color);
    border-radius: .1rem .1rem 0 0;
    color: #00348b;
}
.md-search-result__meta {
    padding: 0 .8rem;
    color: #00348b;
    font-size: .64rem;
    line-height: 1.8rem;
    scroll-snap-align: start;
}

/* 桌面端导航专属样式 */
@media screen and (min-width: 76.25em) {
  .md-nav--primary, .md-nav--secondary {
      font-size: .75rem;
      line-height: 1.5;
      background-color: #eee;
      border-radius: 8px;
      padding-top: .6rem;
      padding-bottom: .6rem;
      background: #00348B 0% 0% no-repeat padding-box;
  }
}
/* 移动端导航专属适配 */
@media screen and (max-width: 76.1875em) {
  .md-nav--primary, .md-nav--secondary {
      font-size: .75rem;
      line-height: 1.5;
      background: #00348B 0% 0% no-repeat padding-box;
      border-radius: 0;
      padding: .6rem 0;
  }
  .md-float-right {
      margin: 0;
      right: 1rem;
      bottom: 1rem;
      left: auto;
      top: auto;
  }
}
.md-nav__title {
    display: block;
    padding: 0 .6rem;
    overflow: hidden;
    font-weight: 700;
    text-overflow: ellipsis;
    color: #ffffff;
}
.md-nav__item .md-nav__link--active {
    text-align: left;
    font: normal normal normal 14px/18px Open Sans;
    letter-spacing: 0.35px;
    color: #FFFFFF;
    opacity: 1;
}
/* 修复转义字符错误，使用原生CSS子选择器 */
.md-nav__item--nested > .md-nav__link {
    color: #FFFFFF;
}
.md-nav__link {
    display: block;
    margin-top: .625em;
    padding: 0 .6rem;
    overflow: hidden;
    text-overflow: ellipsis;
    cursor: pointer;
    transition: color 125ms;
    scroll-snap-align: start;
    text-align: left;
    letter-spacing: 0.33px;
    color: #FFFFFF;
    opacity: 1;
}
.md-nav__link[data-md-state=blur] {
    color: #d5d5d5;
}
.md-footer {
    color: #FFFFFF;
    background : #00348B 0% 0% no-repeat padding-box;
}
.md-float-right {
    height: 100%;
    display: flex;
    align-items: flex-end;
    position: fixed;
}

p {
    display: block;
    margin-block-start: 1em;
    margin-block-end: 1em;
    margin-inline-start: 0px;
    margin-inline-end: 0px;
    text-align: justify;
}

验证注意事项 #

• 替换文件后需强制清除浏览器缓存：桌面端按Ctrl+F5强制刷新，移动端在浏览器设置中清除对应站点的缓存数据，避免旧CSS缓存影响效果
• 后续编写自定义CSS时不要直接复制富文本/HTML渲染后的代码，避免引入>这类HTML转义字符，此类非法语法会直接导致CSS解析中断

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