MkDocs-with-pdf插件PDF中警告框图标位置异常求助

方案1：使用原生Admonition语法替代自定义HTML #

不要在Markdown里写纯HTML的警告框，改用MkDocs Material原生的Admonition语法，插件对原生元素的渲染支持更完善，能避免自定义结构导致的PDF渲染异常：

!!! warning "Caution"
    Insert text here

方案2：针对PDF渲染优化CSS #

mkdocs-with-pdf依赖WeasyPrint生成PDF，它对CSS的处理和浏览器存在差异，浮动布局可能失效。修改extra.css，用媒体查询针对打印场景调整，同时改用更稳定的Flex布局：

/* 针对PDF打印场景的样式 */
@media print {
  .admonition-title {
    display: flex;
    align-items: center;
    gap: 8px; /* 控制图标和标题文字的间距 */
  }
  .admonition-icon {
    flex-shrink: 0; /* 防止图标被压缩 */
  }
}

如果必须用浮动，可增加!important强制覆盖默认样式，同时确保图标是行内块元素：

@media print {
  .admonition-icon {
    float: left !important;
    margin-right: 3px;
    display: inline-block;
  }
}

方案3：提高CSS选择器优先级 #

插件自带的样式可能覆盖了你的自定义CSS，使用更具体的选择器确保样式生效：

/* 针对warning类型的警告框图标 */
div.admonition.warning .admonition-icon {
  float: left;
  margin-right: 3px;
}

方案4：确认CSS文件配置正确 #

检查mkdocs.yml中是否正确引入了extra.css，路径要和文件实际位置一致：

extra_css:
  - extra.css

如果extra.css放在docs/css目录下，路径要改为css/extra.css。

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