Quarto渲染PDF时LaTeX命令失效，如何实现表格表头换行？

问题背景 #

使用Quarto 1.5.53结合Python渲染PDF文档时，需要实现表格表头的换行效果，但尝试多种方法后LaTeX命令均未被正确解析。

已尝试的无效方法 #

方法一：利用pandas.to_latex替换换行符 #

import pandas as pd
from IPython.display import Latex

# 创建DataFrame
data = {
    'Column 1\nLine 2': [1, 2, 3],
    'Column 2\nLine 2': [4, 5, 6]
}
df = pd.DataFrame(data)

# 转换为LaTeX表格并替换换行符
latex_table = df.to_latex(escape=False).replace('\\n', '\\\\')

display(Latex(df.to_latex(index=False)))

结果：表头仅显示反斜杠，无换行效果。

方法二：使用tabulate生成LaTeX表格 #

import pandas as pd
from tabulate import tabulate
from IPython.display import Latex

data = {
    'Column 1\nLine 2': [99, 2, 3],
    'Column 2\nLine 2': [4, 5, 6]
}
df = pd.DataFrame(data)

# 转换为LaTeX格式表格
table_latex = tabulate(df, headers='keys', tablefmt='latex')

display(Latex(table_latex))

结果：表头为单行，换行标识完全消失。

方法三：尝试makecell包 #

---
title: "wow"
format:
    pdf:
        documentclass: article
        keep-tex: false
        include-in-header:
            text: |
                \usepackage{makecell}
---

import pandas as pd
from tabulate import tabulate
from IPython.display import Latex

data = {
    '\makecell{Column 1 \\ Line 2}': [88, 2, 3],
    '\makecell{Column 1 \n Line 2}': [4, 5, 6]
}
df = pd.DataFrame(data)

table_latex = tabulate(df, headers='keys', tablefmt='latex')

display(Latex(table_latex))

结果：表头直接显示\makecell{Column 1 \\ Line 2}文本，未触发LaTeX命令解析。

有效解决方案 #

方案1：结合pandas与makecell，禁用转义并手动构造表头 #

1. 在Quarto的YAML头部引入makecell包：

---
title: "Table Header Line Break"
format:
  pdf:
    include-in-header:
      text: |
        \usepackage{makecell}
---

2. 在Python代码中直接构造包含makecell命令的表头，同时确保to_latex禁用转义：

import pandas as pd
from IPython.display import Latex

# 构造数据
data = {
    'Col1': [1,2,3],
    'Col2': [4,5,6]
}
df = pd.DataFrame(data)

# 手动指定带换行的表头
custom_headers = [
    r'\makecell{Column 1 \\ Line 2}',
    r'\makecell{Column 2 \\ Line 2}'
]

# 生成LaTeX表格，禁用转义并替换默认表头
latex_table = df.to_latex(
    index=False,
    escape=False,
    header=custom_headers
)

display(Latex(latex_table))

原理：通过header参数直接传入LaTeX原生命令，escape=False确保Quarto不会转义这些命令，makecell包负责处理表头内的换行逻辑。

方案2：使用Quarto原生Markdown表格（推荐） #

若无需完全用Python生成表格，可直接用Quarto的Markdown表格语法结合LaTeX命令：

---
title: "Table Header Line Break"
format:
  pdf:
    include-in-header:
      text: |
        \usepackage{makecell}
---

| \makecell{Column 1 \\ Line 2} | \makecell{Column 2 \\ Line 2} |
|-------------------------------|-------------------------------|
| 1                             | 4                             |
| 2                             | 5                             |
| 3                             | 6                             |

如果需要动态生成，可让Python输出上述Markdown代码，再由Quarto渲染。

方案3：调整tabulate参数实现 #

使用tabulate时，必须设置escape=False，同时正确传入带makecell的表头：

import pandas as pd
from tabulate import tabulate
from IPython.display import Latex

data = {
    'Col1': [1,2,3],
    'Col2': [4,5,6]
}
df = pd.DataFrame(data)

# 自定义带换行的表头
custom_headers = [
    r'\makecell{Column 1 \\ Line 2}',
    r'\makecell{Column 2 \\ Line 2}'
]

# 生成LaTeX表格，禁用转义
table_latex = tabulate(
    df,
    headers=custom_headers,
    tablefmt='latex',
    escape=False
)

display(Latex(table_latex))

关键：escape=False是核心，否则tabulate会自动转义LaTeX命令，导致命令失效。

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