使用 mkdocs-with-pdf 生成 pdf 文档时，admonition（如 warning、note 等）的图标常出现在标题右侧或位置偏移，而 html 中显示正常；本文提供经验证的 css 修复方案，精准调整图标定位，无需修改 markdown 源码。
使用 mkdocs-with-pdf 生成 pdf 文档时，admonition（如 warning、note 等）的图标常出现在标题右侧或位置偏移，而 html 中显示正常；本文提供经验证的 css 修复方案，精准调整图标定位，无需修改 markdown 源码。
在 MkDocs 项目中，mkdocs-with-pdf 插件通过将 HTML 渲染为 PDF（底层基于 WeasyPrint），但其对 CSS 的支持与浏览器存在差异——尤其是伪元素 ::before 的绝对定位行为。HTML 中 Material 主题默认使用 position: absolute 定位 admonition 图标，而 WeasyPrint 对 top/left 在非相对定位上下文中的解析不一致，导致图标“漂移”。
你尝试的 .admonition-icon { float: left; } 未生效，是因为 MkDocs Material 实际并未使用独立的 .admonition-icon 元素，而是通过 ::before 伪元素在 .admonition-title 上渲染 SVG 图标（例如
✅ 正确解法是精准覆盖伪元素定位规则。将以下 CSS 添加至你的 docs/assets/css/extra.css（并确保 mkdocs.yml 中已正确配置 extra_css）：
/* 修复 PDF 中 admonition 图标位置（WeasyPrint 兼容） */
.md-typeset .admonition-title::before {
left: 0.5rem !important;
top: 0.7rem !important;
position: absolute !important;
}
⚠️ 注意事项：
- 必须添加 !important —— WeasyPrint 渲染时会继承部分内联样式，普通优先级易被覆盖；
- position: absolute 显式声明不可或缺，否则 top/left 在 PDF 渲染中无效；
- .md-typeset 是 Material 主题内容区域的根类，确保选择器作用域准确；
- 数值 0.5rem 和 0.7rem 可根据字体大小微调（推荐先用默认值测试，再按需增减 ±0.1rem）。
? 补充建议：若需统一所有 admonition 类型（note/warning/danger等）图标对齐，该规则已天然覆盖，因所有类型均共享 .admonition-title::before 结构。无需额外为每种类型单独写样式。
最后，执行 mkdocs build 重新生成 PDF，图标将稳定锚定在标题左侧起始处，与 HTML 版本视觉一致。此方案轻量、无侵入性，且兼容 MkDocs Material v9+ 与 mkdocs-with-pdf 最新版。
