Quarto书籍PDF渲染报错：LaTeX Error: Not in outer par mode

问题根源 #

这个PDF渲染错误本质是LaTeX的排版规则限制：边栏/边注这类特殊环境属于「非外层段落模式」，无法容纳带浮动属性的元素（比如默认的figure图片块）。由于HTML不遵循LaTeX的排版逻辑，所以HTML渲染完全正常，只有PDF会触发该报错，且正如你排查的，问题大概率出在.column-margin环境中的图片上。

实测有效的解决方案 #

针对.column-margin中的图片，只需取消浮动属性即可解决，以下是三种可靠方法：

方法1：给图片添加fig-pos="H"参数 #

直接在Quarto图片语法中添加该参数，强制LaTeX将图片作为非浮动元素放置：

::: {.column-margin}
![你的图片说明](image-file.png){fig-pos="H" width="100%"}
:::

width="100%"用于让图片适配边栏宽度，可根据需求调整数值。

方法2：直接使用LaTeX原生命令插图 #

如果方法1未生效，可绕过Quarto的图片渲染逻辑，直接用LaTeX代码插入图片：

::: {.column-margin}
\includegraphics[width=\linewidth]{image-file.png}
:::

\linewidth会自动匹配边栏宽度，无需手动调整数值。

方法3：移除多余的浮动包裹 #

如果你的图片被额外套了::: {.figure}这类浮动容器，必须移除该包裹，直接将图片放在.column-margin环境中：

# 错误写法（带浮动容器）
::: {.column-margin}
::: {.figure}
![图片说明](image-file.png)
:::
:::

# 正确写法
::: {.column-margin}
![图片说明](image-file.png){fig-pos="H"}
:::

辅助排查技巧 #

若修改后仍报错，建议开启keep-tex配置查看生成的LaTeX源码，精准定位问题：
在_quarto.yml中添加如下配置：

format:
  pdf:
    keep-tex: true

重新渲染后，找到生成的.tex文件，搜索outer par mode附近的代码，即可定位到触发错误的元素（比如边栏中的表格也可能出现同类问题，给表格添加table-pos="H"参数即可解决）。

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