Как рендерить R Markdown в PDF на кириллице

Так получилось, что за всё время, что я использую в работе R, мне не доводилось рендерить markdown-файлы в формат PDF. Иногда я хранил наработки просто в фалах .R, а исследования оформлял в Google Docs, накидывая туда скринов из viewer-а. Иногда это был рендер в .html, с интерактивной графикой, или проекты Shiny в облаке Posit. Да мало ли вариантов.

Но в связи с некоторыми изменениями в форматах хранения аналитических артефактов, судьба привела меня к PDF.

“Дело-то не хитрое, просто меняем формат вывода в markdown” — подумал я. Однако всё оказалось не так просто: и тексты и ggplot не видят кириллицу, движок xelatex не находит кастомные шрифты, LaTeX вообще бесится на всё.

Каждая проблема отдельно худо-бедно гуглится или решается через chatGPT, но в интернетах намного больше информации как посадить markdown-PDF на китайский, чем на кириллицу.

Рассмотрим на примере классического markdown, а в конце реализация для Quarto.

В общем, по порядку.

В качестве IDE я использую RStudio.

Для рендера в PDF, в первую очередь нужно поставить LaTeX, я не изучал там нюансы движков, а выбрал наиболее цитируемый TinyTex. Устанавливается через CRAN или через Git, кому как нравится:

install.packages('tinytex')  tinytex::install_tinytex()  #после этой команды нужно полностью перезапустить ваш R-клиент

За основу возьмём вот такой файл .Rmd, с базовым набором элементов: заголовок, текст, код и график.

--- title: "Cyrillic markdown" date: "`r Sys.Date()`" output: pdf_document ---  ```{r include = F} library(tidyverse) ```  ```{r include = F} # Создаём датасет dates <- rep(seq(as.Date("2023-01-01"), length.out = 7, by = "days"), each = 2) values <- sample(100:130, 14, replace = TRUE) categories <- rep(c("Cat_A", "Cat_B"), 7)  df <- data.frame(date = dates,                   value = values,                   category = categories) ```  ## Заголовок  Тут у нас кириллический текст с некоторыми вставками english words.  ```{r} head(df) ```  Ну и график прилагается:  ```{r} # plot 1 ggplot(df, aes(x = date,                y = value,                col = category)) +    geom_line() +   labs(title = "График",        x = "Дата",        y = "Метрика") +   theme_minimal() ```

При попытке рендера, если у вас локаль RU, консоль выкатит первую ошибку (или отрендерит без кириллического текста и с кучей warning-ов):

! LaTeX Error: Unicode character З (U+0417)                not set up for use with LaTeX.

Решается она, например, таким способом:

1. В YAML-заголовке указываем движок и включаем дополнения в виде файла header.tex:

--- title: "Cyrillic markdown" date: "`r Sys.Date()`" output:   pdf_document:     latex_engine: xelatex     includes:       in_header: header.tex --- 

2. Сам файл header.tex лежит в папке с нашим markdown-файлом и выглядит примерно так:

\usepackage{fontspec} \setmainfont{Segoe UI} \setsansfont{Segoe UI} \setmonofont{Segoe UI} \usepackage{polyglossia} \setmainlanguage{russian} \setotherlanguage{english}

Теперь LaTeX перестанет ругаться и кое-как, но PDF-ку соберёт.

Кириллица в тексте обрабатывается, а вот ggplot форматирует даты в текст и ломается.

Если вы не любитель описывать labs в графиках, а уж тем более кириллицей, то тут можно ограничиться сменой локали прям в markdown-файле, добавив куда-нибудь в начало такую строку:

Sys.setlocale("LC_TIME", "en_US.UTF-8")

Второй вариант — использовать библиотеку showtext:

install.packages("showtext") library(showtext)  # после загрузки библиотеки, отдаём распознавание на откуп движку showtext_auto()

Предупреждения ушли, график видит кириллицу как в лабсах, так и в датах:

В целом готово. Но мне вообще не нравится как выглядят блоки с кодом. Я люблю для этого использовать шрифты Cascadia Mono PL Light или Cascadia Code Light. Но если шрифт кастомный, просто переписать header.tex не поможет. Я перепробовал разные варианты, и переустановить шрифты, и прописать полное название, и скормить ему весь путь к файлу шрифта — безрезультатно.

В итоге помогла смена движка на lualatex, который тоже поддерживает fontscpec.

--- title: "Cyrillic markdown" date: "`r Sys.Date()`" output:   pdf_document:     latex_engine: lualatex     includes:       in_header: header.tex ---

Ну другое дело же)

На этом, пожалуй, и все нюансы рендера markdown в PDF.

Я потратил на это пару вечеров (а мог пить пиво), надеюсь кому-нибудь поможет сэкономить время.

Quarto

Тут намного всё проще, никаких костылей с header.tex не нужно, шрифты прописываются прям в YAML, кириллица на графике лечится тем же showtext:

--- title: "Cyrillic markdown" format: pdf pdf-engine: lualatex mainfont: Segoe UI sansfont: Segoe UI monofont: Cascadia Mono PL Light editor: visual ---  ```{r include = F} library(showtext) showtext_auto() ```

По традиции, приглашаю вас в свой ТГ-канал. Там я пишу о продуктовой аналитке, в основном для ребят, которые уже работают, но только начинают свой карьерный путь.