如何自定义MkDocs Material主题CSS？extra.css配置未生效求助

• 确认extra.css路径与配置正确
  必须将extra.css放在docs/css/目录下，同时在mkdocs.yml中正确配置：

  extra_css:
    - css/extra.css
  

  本地运行前检查文件位置，部署到GitHub Pages时确保该文件被同步到仓库。

• 提升CSS选择器优先级
  Material主题自带的样式选择器优先级可能更高，导致你的自定义样式被覆盖。可以使用更具体的选择器，比如：

  .md-content__inner > h1 {
    color: #ff0000;
  }
  

  临时测试也可以添加!important（不推荐长期使用，避免样式冲突）：

  h1 {
    color: #ff0000 !important;
  }
  

• 直接覆盖主题CSS变量（推荐）
  Material主题核心样式依赖CSS变量，你可以在extra.css中重新定义这些变量来实现自定义，这是官方推荐的方式，不会轻易被主题更新覆盖：

  :root {
    --md-primary-fg-color: #2196f3;
    --md-accent-fg-color: #ff5722;
    --md-default-bg-color: #f5f5f5;
  }
  

• 清除缓存
  本地测试时清空浏览器缓存或使用隐私模式打开页面；GitHub Pages部署后可能存在CDN缓存，等待数分钟后强制刷新（Ctrl+F5）查看效果。

• 验证构建结果
  运行mkdocs build命令，检查生成的site/css/目录下是否包含extra.css的内容，确认构建过程中文件被正确打包。

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