Quarto qmd转pdf：scrartcl文档首页页眉Logo设置报错求助

问题场景 #

使用scrartcl文档类时，想要实现首页页眉显示带width尺寸参数的图片Logo，从第二页开始更换为文字页眉。尝试用scrlayer-scrpage包的\cohead命令实现时，只要给\includegraphics加上width=5cm参数就会触发LaTeX Error: Missing \begin{document}错误；但把Logo换成文字、或者去掉width参数时，编译完全正常。

错误原因 #

问题出在Pandoc的YAML配置解析上：include-in-header的text字段是多行YAML文本，其中\includegraphics[width=5cm]里的方括号会被YAML误识别为自身的语法结构（比如数组或引用），导致生成的LaTeX代码被意外截断，最终触发文档环境未开始的错误。

解决方案 #

方案1：用自定义LaTeX命令封装图片调用 #

把带尺寸参数的图片调用封装成一个自定义命令，避免YAML直接解析带方括号的参数：

---
title: "Logo in Header"
documentclass: scrartcl
format: 
   pdf: 
      include-in-header: 
         text: |
            \usepackage{scrlayer-scrpage}
            \usepackage{graphicx}
            \clearpairofpagestyles
            % 封装带尺寸的Logo命令
            \newcommand{\headerlogo}{\includegraphics[width=5cm]{my_logo.png}}
            \cohead[\headerlogo]{Header from page 2 onward}
---

Page 1

\newpage

Page 2

方案2：将页眉配置单独存为LaTeX文件 #

把所有页眉相关的LaTeX代码写入独立的.tex文件，通过include-in-header的文件引用方式引入，彻底绕开YAML的解析冲突：

1. 创建header-config.tex文件，内容如下：

\usepackage{scrlayer-scrpage}
\usepackage{graphicx}
\clearpairofpagestyles
\cohead[\includegraphics[width=5cm]{my_logo.png}]{Header from page 2 onward}

2. 主文档的YAML配置修改为：

---
title: "Logo in Header"
documentclass: scrartcl
format: 
   pdf: 
      include-in-header: header-config.tex
---

Page 1

\newpage

Page 2

说明 #

两种方案都能解决编译错误，其中方案2的代码分离方式更便于维护，尤其当页眉配置复杂时更推荐使用。

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