quarto-example/my_website
├── _quarto.yml
├── about.qmd
├── index.qmd
├── index1.qmd
└── styles.css2 Установка и начало работы с Quarto
2.1 Установка Quarto
Для установки Quarto, необходимо зайти на начальную страницу проекта https://quarto.org/ и нажать на кнопку Get Started.
Установка происходит в два этапа.
- Шаг 1. Установка интерфейса командной строки (CLI) для актуальной операционной системы (Windows, Linux или macOS). Рекомендуется устанавливать стабильную версию Current Release со страницы загрузки, а не Pre-Release-версии.
- Шаг 2. Установка плагина для рабочей интегрированной среды разработки (IDE). В зависимости от предпочтений, для определенной среды разработки необходимо установить плагин. Это может быть, например, VS Code, RStudio, Jupyter или иной текстовый редактор. Можно также установить Quarto-плагин, например, для Sublime Text или Emacs.
2.2 IDE-инструменты
2.2.1 RStudio
Если Quarto CLI уже установлен, то RStudio обнаружит это и автоматически включит функции Quarto. В качестве альтернативы существует версия Quarto встроенная в RStudio, которую можно активировать в настройках R Markdown.
Создание нового Quarto-документа в RStudio с расширением *.qmd происходит как File : New File : Quarto document…, что открывает новый документ на основе шаблона.
В открывшемся окне можно выбрать вид документа (статичный, презентация или интерактивный), указать заголовок документа, автора, выбрать каким образом будет рендериться документ, будет ли использован визуальный редактор.
Редактирование документа возможно в двух режимах: source (текст + код) и Visual (визуальный). Переключение кнопок с Source на Visual позволяет перейти в режим визуального редактирования, который близок к WYSIWYG-редактору и может быть особенно полезен, например, для создания таблиц в документах.
Если в визуальном режиме нажать на /, то в появившемся меню можно выбрать элемент для вставки: блок для кода, список и т.д. Более подробно о работе в визуальном режиме можно посмотреть на странице документации.
Для того, чтобы запустить рендеринг проекта в RStudio, достаточно нажать на кнопку Render, которая находится вверху панель инструментов, либо с помощью клавиатурного сочетания Shift+Control+K или Shift+Command+K в зависимости от установленной операционной системы. Для остановки фонового задания (рабочего процесса) необходимо перейти на панель Background Jobs, находящейся рядом с консолью, и нажать значок Stop background job.
Еще одна возможность сделать рендер Quarto-документа в RStudio — это использование Quarto как R-библиотеки, например:
R
quarto_render("document.qmd", output_format = "pdf")Подробно о работе в RStudio можно посмотреть на соотетствующей странице документации.
2.2.2 Visual Studio Code (Positron)
Альтернативно, Visual Studio Code (или VS Code) предлагает возможность редактировать документы как с *.qmd, так и с *.ipynb-ноутбуками. Помимо предварительного просмотра документов, также работает подсветка синтаксиса для встроенных языков, автоматические подсказки, автозавершение для языков программирования, клавиатурные сочетания, сниппеты, предварительный просмотр в реальном времени для LaTeX, а также диаграмм Mermaid и Graphviz.
Преимущество VS Code состоит в большом количестве полезных плагинов.
Удобный проводник, мини-карта, диагностика для опций YAML и обилие расширений (к примеру, возможность проверки орфографии или переключаться между проектами) делает VS Code отличным инструментом для создания больших проектов, например, книг. Работа VS Code в Quarto описана на странице документации.
В 2024 году в Posit представили новый IDE, который называется Positron и во многом основан на VS Code. Помимо привычных настроек VS Code, Positron предоставляет дополнительные возможности для создания документов Quarto, например, встроенные шаблоны.
2.2.3 Jupyter
Для тех, кто программирует на Julia или Python, более привычным инструментом является система Jupyter-ноутбуков.
Для того, чтобы создать Quarto-пример в Jupyter, необходимо в преамбулу *.qmd-документа добавить YAML-вставку и затем отрендерить *.ipynb-ноутбук, перейдя в терминале в корневой каталог проекта и набрав команду подобно тому, как написано ниже.
Terminal
quarto render hello_Python.ipynb --to html
Замечание
Если вместо Python используется Julia, то в преамбуле необходимо в качестве ядра указать актуальную версию, например, jupyter: julia-1.11.
2.3 Работа с проектами
2.3.1 Создание нового проекта с помощью интерфейса командной строки
Проект Quarto включает несколько файлов, расположенных в одной папке. В этой папке обязательно присутствует файл _quarto.yml, который устанавливает общие параметры для всех документов проекта.
Существует несколько вариантов для создания Quarto-проекта: в IDE, например, в RStudio, VS Code и Positron, а также с помощью команд в терминале используя интерфейс командной строки (CLI).
quarto --help в терминале
Если необходимо создать проект в текущей директории, то это можно сделать, указав в командной строке тип проекта <project_type> (например, website, website:blog, book, manuscript и т.д.).
Terminal
quarto create-project --type <project_type>
Для того, чтобы создать Quarto-проект в новой директории, также можно использовать командную строку, указав тип проекта, при этом Quarto выдаст вам интерактивную подсказку с запросом типа проекта, имени каталога и названия проекта.
Terminal
quarto create project <project_type> my_project_folder
Пример структуры созданного проекта веб-сайта в новой директории:
После создания проекта можно использовать команду quarto preview для рендеринга и предварительного просмотра веб-сайта:
Terminal
quarto preview project_name
Предварительный просмотр веб-сайта откроется в новом веб-браузере. При редактировании и сохранении index.qmd (или других файлов, таких как about.qmd) предварительный просмотр автоматически будет обновляться.
2.3.2 Рендеринг документов Quarto
Сначала Knitr (в R) или Jupyter (в Pyhton или Julia) выполняет все фрагменты кода *.qmd-файла и создает новый Markdown-документ с расширением *.md, который включает в себя код и его выходные данные. Отметим, что один и тот же *.qmd-документ может служить источником для различных выходных форматов.
Terminal
quarto render hello.qmd --to html
quarto render hello.qmd --to docx
quarto render hello.qmd --to pdf
quarto render hello.qmd --to epub
quarto render hello.qmd --to pptx
quarto render hello.qmd --to revealjs
Созданный Markdown-файл затем обрабатывается Pandoc для преобразования в различные форматы файлов, включая HTML, PDF, MS Word и другие поддерживаемые форматы. Отметим, что перед публикацией проекта в сети Интернет обязательно нужно предварительно сделать рендеринг проекта.
Замечание
При рендеринге не будут обрабатываться файлы вида: _file_name.*, .file_name.*, а также файлы, соответствующие README.*md.
При работе с проектом мы периодически обращаемся к его предварительному просмотру используя команду ниже с различными параметрами.
Terminal
quarto preview hello.qmd
Замечание
Отличие команд preview и render в том, что для preview Quarto отрендерит ровно столько элементов проекта, сколько нужно для отображения запрошенного документа и открытия предварительного просмотра. Когда вы взаимодействуете с предварительным просмотром, например, переходите по ссылке в одном документе с одной страницы на другую, Quarto отрендерит и отобразит все дополнительные файлы по мере необходимости.
В Quarto также возможно осуществлять рендеринг файлов, содержащих скриптов (*.r, *.py или *.jl), которые форматируются как ноутбуки.
Terminal
quarto render script.r
quarto render script.py
quarto render script.jlСинтаксис ноутбуков зависит от того, используете ли вы движок Jupyter (для скриптов R, Python и Julia) или Knitr (для R). В любом случае скрипт должен начинаться с ячейки разметки, которая включает блок заголовка YAML.
Например, для Jupyter ячейки Markdown разделяются символами # %% [markdown] и могут включать содержимое в виде однострочных комментариев (#) или многострочных строк ("""). Иными словами, синтаксис очень схож с тем, что используется в Jupytext.
script.py
# %% [markdown]
# ---
# title: Привет, пингвины
# author: А.А. Автор
# date: today
# ---
# %%
#| echo: false
import polars as pls
df = pls.read_csv("palmer-penguins.csv")
# %% [markdown]
"""
## Исследование данных
См. рисунок @fig-bill-sizes для определения параметров.
"""
# %%
#| label: fig-bill-sizes
#| fig-cap: Параметры пингвинов
import matplotlib.pyplot as plt
import seaborn as sns
g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5)
g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend()Удобство подобного подхода заключается в том, что мы можем вместо Jupyter *.ipynb использовать скрипт как выше, что позволяет обращаться к ноутбуку как текстовым файлу, это дает возможность работать с ноутбуками в Git.
Аналогичным способом определяется R-скрипт следуя статье по преобразованию R-скрипта в отчет. Скрипты, визуализируемые с помощью Quarto, должны начинаться с заголовка YAML с использованием #'-комментариев. Код R является основным содержимым скрипта R и включен без каких-либо ограничений. Параметры ячеек кода указываются с #|-комментариями и применяются к коду под ними. Содержимое Markdown включается в строки, начинающиеся со специального #|-комментария.
script.r
#' ---
#' title: Привет, пингвины
#' author: А.А. Автор
#' date: today
#' format: html
#' ---
library(tidyverse)
library(palmerpenguins)
#' ## Пример графика
#' См. @fig-bill-sizes для точных данных.
#| label: fig-bill-sizes
#| fig-cap: Пример графика
#| warning: false
penguins |>
na.omit() |>
ggplot(aes(x = bill_length_mm,
y = bill_depth_mm,
fill = species,
size = body_mass_g)) +
geom_point(pch = 21,
color = "white",
alpha = 0.7) +
scale_x_continuous(name = "Длина клюва",
labels = function(x) str_c(x, " мм")) +
scale_y_continuous(name = "Высота клюва",
labels = function(x) str_c(x, " мм"))Более подробно по рендерингу скриптов можно прочитать на странице документации.
Заключение
Здесь мы рассмотрели самые различные вопросы, начиная от установки Quarto, IDE-инструментов, до создания собственных проектов и возможностей рендеринга.