使用MkDocs Material生成PDF时SVG CSS渲染失效问题求助

问题背景 #

使用MkDocs Material搭配with-pdf插件生成PDF文档时，网页端的SVG元素可正常渲染CSS样式，但生成的PDF中SVG的CSS样式完全丢失。当前插件配置如下：

plugins:
  - with-pdf:
      cover_subtitle: test     
      cover: true
      back_cover: true
      copyright: Copyright © Abby.huang -  All rights reserved.
      output_path: pdf/abby.pdf

已知with-pdf插件基于WeasyPrint生成PDF，问题源于WeasyPrint对非可信来源的CSS/HTML资源加载限制。

解决方案 #

1. 配置WeasyPrint可信来源权限 #

在with-pdf插件配置中添加weasyprint_options，开启本地文件访问权限或指定资源基准URL，让WeasyPrint能正常加载本地CSS和SVG资源：

plugins:
  - with-pdf:
      cover_subtitle: test     
      cover: true
      back_cover: true
      copyright: Copyright © Abby.huang -  All rights reserved.
      output_path: pdf/abby.pdf
      weasyprint_options:
        enable_local_file_access: true
        base_url: "file:///绝对路径/到你的docs/site目录/"  # 替换为实际site目录路径

• enable_local_file_access：允许WeasyPrint加载本地文件系统中的资源
• base_url：指定资源加载的基准路径，确保相对路径的资源能被正确解析

2. 内联SVG的CSS样式 #

将SVG依赖的CSS样式直接内联到SVG文件内部，避免WeasyPrint因外部资源限制无法读取样式：

<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200">
  <style type="text/css">
    .custom-fill { fill: #2196F3; }
    .custom-stroke { stroke: #FFC107; stroke-width: 3; }
  </style>
  <circle class="custom-fill custom-stroke" cx="100" cy="100" r="80" />
</svg>

3. 检查CSS兼容性 #

WeasyPrint的CSS支持与浏览器存在差异，需确保SVG使用的CSS属性在WeasyPrint支持范围内：

• 避免使用浏览器特有的CSS属性、伪类或选择器
• 改用WeasyPrint支持的基础CSS语法，比如用fill、stroke等直接属性代替复杂的继承样式

4. 修正资源引用路径 #

确保SVG和CSS文件使用相对路径引用，且资源文件位于MkDocs的可访问目录下：

• 避免使用绝对URL或外部CDN链接引用资源
• 将SVG和CSS文件放在docs目录下，使用./或../形式的相对路径调用

内容的提问来源于stack exchange，提问作者黄凤仙