Skip to main content

从 R Markdown 迁移到 Quarto

软件
Published

April 2, 2024

已经从 R Markdown 迁移到 Quarto 很长一段时间，目前看还是 Quarto 用得更顺手，更像是新一代的排版工具。原来一大堆的 R Markdown 项目，也逐步在迁移到 Quarto，对于迁移工作有一定的心得，在些记录一些经验备查。

Quarto 默认很好地支持了 R Markdown 语法，但是对配置文件需要做一定合并与修改。

在 R Markdown 工程里，可以会有若干个配置文件，比如说 _output.yaml 和 _bookdown.yml 等若干个文件，但是换成 Quarto 后，只有一个 _quarto.yml 文件，这就需要对这些配置合并到 _quarto.yml 里，然后即可正常编译原来的 R Markdown 工程。

最简单的办法，把 _bookdown.yml 改为 _quarto.yml 然后删除 _output.yml 文件。

合并的时候，对一些配置项，需要做一些修改。原来 R Markdown 里类似这种的语法：

bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  toc: TRUE
  toc_depth: 3
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
  number_sections: true
  pandoc_args:
    --top-level-division=chapter
  split_by: chapter

需要改为如下样式：

format:
  pdf:
    documentclass: book
    margin-left: 30mm
    margin-right: 30mm
    include-in-header: 
      - file: preamble.tex

另外，用 Quarto 直接进行 HTML 本地预览，可以直接生成一个 Web 服务器，支持搜索等功能，这一点太方便了！

quarto preview ./

一些注意事项：

  1. 为方便生产pdf和website，建议用 index.qmd 作为最根节点的文档，否则容易提示如下错误：
ERROR: Book contents must include a home page (e.g. index.md)
  1. 如果要生成中文pdf文档，即用latex生成中文书籍的时候，需要使用 ctexbook 选项：
  pdf:
    documentclass: ctexbook

参考文献：

[1] Quarto PDF 配置

[2] FAQ for R Markdown Users