Quarto渲染PDF时标题缺失、指定字体未生效问题求助

一、核对YAML配置格式 #

先确保你的.qmd文档头部YAML配置没有语法错误，以下是标准的正确配置示例：

---
title: "你的文档标题"
format:
  pdf:
    engine: xelatex
    mainfont: Tahoma
    sansfont: Tahoma
---

• 必须指定engine: xelatex或lualatex，pdfLaTeX不支持直接调用系统字体，这是Tahoma不生效的核心原因之一
• mainfont和sansfont都设为Tahoma，确保标题、正文等所有文本统一使用该字体
• title字段要放在YAML最外层，不要缩进嵌套在format里

二、确认LaTeX依赖与字体环境 #

1. 如果你用XeLaTeX/LuaLaTeX，需要LaTeX发行版（TeX Live/MikTeX）安装fontspec包：
   • TeX Live用户可执行命令：tlmgr install fontspec
   • MikTeX会自动安装缺失包，若未触发可手动搜索安装
2. 确保系统中已安装Tahoma字体：Windows默认自带，mac/Linux需手动下载安装后重启VSCode

三、验证渲染引擎是否生效 #

查看终端输出的渲染日志，确认实际使用的引擎是你指定的XeLaTeX/LuaLaTeX：

Running xelatex...
如果日志显示pdflatex，说明配置未生效，解决方式：

• 打开VSCode设置，搜索Quarto: Pdf Engine，将默认引擎设为xelatex
• 或者在YAML中明确指定engine: xelatex，它的优先级高于VSCode全局设置

四、排查标题缺失问题 #

1. 检查YAML中是否误写title: false，或自定义模板里关闭了标题输出，暂时注释模板配置用默认模板测试：

format:
  pdf:
    engine: xelatex
    mainfont: Tahoma
    # template: custom-template.tex  # 注释此行测试

2. 若为中文标题，确保YAML编码正确，标题文本需用双引号包裹

五、用极简文档测试排除冲突 #

创建一个最小可复现的.qmd文件，验证基础功能是否正常：

---
title: "测试标题"
format:
  pdf:
    engine: xelatex
    mainfont: Tahoma
---

## 二级标题
这是测试文本，检查字体是否为Tahoma，标题是否显示。

如果这个极简文档能正常渲染，说明原文档存在自定义CSS、LaTeX代码块等冲突，逐步排查删除非必要配置即可

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