Научно-издательская
система Quarto

обзор и начало работы

Е.Н. Матеров

4 марта 2023 г.

quarto-meetup-begin.netlify.app

Название “Quarto”

Quarto (от латинского quārtō)¹ — это книга или брошюра, изготовленная из полных листов, напечатанных с восемью страницами текста, по четыре на одну сторону, а затем сложенных дважды, чтобы получить четыре листа.

Слева показан пример кварто-книги.

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Quarto

Quarto® — это научно-техническая издательская система с открытым исходным кодом, построенная на основе Pandoc и использующая Markdown для разметки.

Pandoc — универсальный конвертер для работы с текстовыми документами для форматирования научных и технических текстов, поддерживающий более 40 различных форматов.

Quarto CLI — это интерфейс командной строки, который преобразует обычные различные форматы (.md, .rmd, .qmd или .ipynb / Jupyter notebook) в статические отчеты PDF / Word / HTML, интерактивные книги, веб-сайты, блоги, презентации и многое другое.

Quarto позволяет создавать динамический контент с помощью Python, R, Julia и Observable JavaScript.

Авторы: Carlos Scheidegger (@cscheid), Charles Teague (@dragonstyle), Christophe Dervieux (@cderv), J.J. Allaire (@jjallaire), Yihui Xie (@yihui).

Введение в Quarto

обзор научно-издательской системы Quarto

Статьи

Веб-страницы

Книги

Презентации

Больше примеров разработок в Quarto

https://quarto.org/docs/gallery/

Пример страницы в Quarto

https://materov.github.io/R-sources/

Пример блога в Quarto

https://data-visualization-blog.netlify.app/

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Начало работы с Quarto

https://quarto.org/

Quarto в RStudio

Quarto в Visual Studio Code

Quarto в Jupyter

Создание документов в Rstudio

Создание документов в Visual Studio Code

Возможности для рендеринга

Используйте кнопку Render в RStudio IDE для рендеринга файла и предварительного просмотра выходных данных.

Также, можно использовать Render в Visual Studio Code.

Quarto как R-библиотека:

quarto::quarto_render(input = ___, output_format = ___)

Quarto в командной строке:
```
quarto render <input> --to <format>
```

Единый источник документа

Документ может быть преобразован в различные выходные форматы через Pandoc:

$ quarto render hello.qmd --to html
$ quarto render hello.qmd --to pdf
$ quarto render hello.qmd --to docx
$ quarto render hello.qmd --to epub
$ quarto render hello.qmd --to pptx
$ quarto render hello.qmd --to revealjs

Возможность вывода в нескольких форматах одновременно

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Составляющие `.qmd`-документа

---
title: "Заголовок документа"
format:
  html:
    code-fold: true
---
Текст: пример рисунка, см. @fig-ggplot.

```{r}
#| label: fig-ggplot
#| fig-cap: "Демонстрация `ggplot`"
library(hrbrthemes)
library(tidyverse)

ggplot(mtcars, aes(mpg, wt)) +
  geom_point(color = ft_cols$yellow) +
  geom_smooth() +
  labs(x = "Экономия топлива (mpg)", 
       y = "Вес (т)",
       title = "Пример диаграммы рассеяния",
       caption = "Источник: hrbrthemes") + 
  theme_ft_rc()
```

Метаданные (YAML).
Текст документа.
Ячейки с исполняемым кодом.

Текст: пример рисунка, см. Рисунок 1.

Рисунок 1: Демонстрация ggplot

Метаданные (YAML-часть документа)

Метаданные могут быть включены в Quarto-документ с помощью YAML либо в преамбуле в начале файла, либо отдельным _quarto.yml-файлом.

С помощью YAML мы задаем, например, название документу, дату, автора, устанавливаем те параметры, которые необходимы при рендеринге документа, чтобы не писать их в командной строке и т.д.

Markdown (форматирование текста)

Markdown	Вывод
`курсив и полужирный`	курсив и полужирный
`надстрочный^2^ / подстрочный~2~`	надстрочный² / подстрочный₂
`~~зачеркнутый~~`	~~зачеркнутый~~
`verbatim code`	`verbatim code`

Markdown (заголовки)

Markdown	Вывод
`# Заголовок 1`	Заголовок 1
`## Заголовок 2`	Заголовок 2
`### Заголовок 3`	Заголовок 3
`#### Заголовок 4`	Заголовок 4

Markdown (ссылки и рисунки)

Markdown	Вывод
`<https://http://sibpsa.ru/>`	http://sibpsa.ru/
`[СПСА](http://sibpsa.ru/)`	СПСА
`![Caption](logo.png)`
`[![Caption](logo.png)](http://sibpsa.ru/)`
`[![Caption](logo.png)](http://sibpsa.ru/ "СПСА")`
`[![](logo.png){fig-alt="Текст"}](https://quarto.org)`

Markdown (списки)

Markdown (таблицы)

Markdown

| Справа | Слева | По умолчанию | По центру |
|-------:|:------|--------------|:---------:|
|     12 | 12    | 12           |    12     |
|    123 | 123   | 123          |    123    |
|      1 | 1     | 1            |     1     |

Вывод

Справа	Слева	По умолчанию	По центру
12	12	12	12
123	123	123	123
1	1	1	1

Формулы в Quarto

Математические формулы в Quarto используют разделители $ для встроенных математических элементов текста и разделители $$ для выносной математики на основе LaTeX-синтаксиса.

Выносные блоки

Заметка

Этот элемент будет использоваться для заметок.

Замечание

Этот элемент будет использоваться для важных замечаний.

Важно

Этот элемент будет использоваться для предупреждений.

Предостережение

Этот элемент будет использоваться для предостережений.

Совет

Этот элемент будет использоваться для рекомендаций и советов.

Выносные блоки

:::{.callout-note}
## Заметка 

Этот элемент будет использоваться для заметок.
:::

:::{.callout-caution appearance="simple"}
## Важно

Этот элемент будет использоваться для предупреждений.
:::

:::{.callout-warning icon=false}
## Предостережение

Этот элемент будет использоваться для предостережений.
:::

Расширенные макеты

В случае, если содержимое выходит за пределы области основного текста, его можно продолжить, используя правую и левую версии столбцов основного текста, страницы и экрана для компоновки содержимого. Например, как ниже:

Примеры параметров для определения содержимого, выходящего за фиксированную ширину справа:

Диаграммы

Вставка диаграмм – еще одно ноу-хау в Quarto, имеющее встроенную поддержку Mermaid и Graphviz диаграмм. Это позволяет создавать блок-схемы, диаграммы последовательностей, диаграммы состояний, диаграммы Ганта и многое другое, используя синтаксис обычного текста, вдохновленный markdown.

Ячейки с исполняемым кодом

Исполняемый код записывается в специальные блоки (ячейки), в начале которых указывается язык программирования для выделения.

Если мы хотим сделать код неисполняемым – нужно поставить точку перед указанием языка программирования.

Подсветка кода

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'}) 
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()

Параметры ячейки

Внутри ячейки в комментариях в верхней части блока можно указывать параметры. Параметры ячейки влияют на выполнение и вывод блоков исполняемого кода.

Например:

Структура проекта блога

Это стандартное содержание проекта-блога в Quarto.

myblog/

├── index.qmd (основной файл, рендерится)

├── _quarto.yml (содержит глобальные метаданные)

├── about.qmd

├── style.scss (стили, влияет только на index.qmd)

├── _site (создаваемая папка, публикуется)

└── posts/ (посты)

    └── metadata.yml

    └── welcome/

        └── index.qmd

    └── post-with-code

        └── index.qmd

Структура проекта книги

Это стандартное содержание проекта-книги в Quarto.

mybook/

├── index.qmd (основной файл, рендерится)

├── _quarto.yml (содержит глобальные метаданные)

├── style.scss (стили, влияет только на index.qmd)

├── favicon.png (фавикон)

├── title.png (титульная страница)

├── sidebar logo.png (логотип сайдбара)

├── reference.bib (метаданные BibTeX со ссылками)

├── reference.qmd (Глава для ссылок)

├── 404.qmd (Страница не найдена)

├── _book (создаваемая папка, публикуется)

└── Chapter 1/ (Глава 1)

    └── file 1.qmd

├── Chapter 2/ (Глава 2)

├── …

├── Chapter n/ (Глава n)

└── Appendicies/ (Приложения)

Расширения Quarto

Расширения – это мощный способ изменять и расширять поведение Quarto.

С помощью расширений можно создавать шаблоны для публикаций, темы презентаций, вставлять видео, твиты, значки и т.д.

Также, актуальные расширения можно посмотреть на странице Awesome Quarto.

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Основные сервисы для веб-публикации

Вы можете опубликовать Quarto документы в самых различных местах, включая популярные издательские сервисы:

Сервис	Описание
Netlify	Используйте Netlify, если вам нужна поддержка пользовательских доменов, аутентификации, предварительного просмотра ветвей и других более продвинутых возможностей.
GitHub Pages	Публикуйте контент на основе исходного кода, управляемого в репозитории GitHub. Используйте страницы GitHub, когда исходный код вашего документа или сайта размещен на GitHub.
Quarto Pub	Служба публикации документов, веб-сайтов и книг Quarto. Используйте Quarto Pub, если вам нужен бесплатный, простой в использовании сервис для общедоступного контента.
другие сервисы	Контент, отображаемый с помощью Quarto, использует стандартные форматы (HTML, Pdf, MS Word и т.д.), которые могут быть опубликованы где угодно. Используйте это, если один из описанных выше методов не соответствует вашим требованиям.

Пример: публикация в QuartoPub

Страница, опубликованная в QuartoPub

Рабочий процесс с Git

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Страница Awesome Quarto

https://github.com/mcanouil/awesome-quarto

Советы дня по Quarto

страница с советами

Приступая к работе с Quarto

страница workshop’а + видео

От R Markdown к Quarto

страница workshop’а

Трюки и приемы в Quarto

страница с твитами советов

Советы по Quarto, найденные в Интернете

страница с советами от Sharon Machlis, включающими Observable и Arquero JavaScript

Создание блога в Quarto

страница meetup’а + видео

Hello, Quarto: A World of Possibilities

Содержание

1. Обзор Quarto и примеры

2. Как начать работу в Quarto?

3. Структура документов в Quarto

4. Возможности для интернет-публикации

5. Дополнительные материалы по Quarto

6. Выводы

Почему стоит попробовать Quarto?

Quarto отлично подходит для публикации статей на сайтах, в блогах, а также отчетов в PDF, Word и в других форматах учеными, исследователями данных, студентами, может использоваться в образовательных целях.

Работа с большими проектами (например, книгами), кэширование, freeze.

Простота перехода от одного формата вывода документа к другому.

Возможность включения математических $\LaTeX$-формул в Word-документ, диаграмм.

Организация цитирования (как в визуальном редакторе, так и организация
ссылок через $BibTEX$, CiteDrive и т.д.).

Расширенные макеты для размещения элементов документа на странице.

Почему стоит попробовать Quarto?

Темы на основе Bootstrap 5, использование CSS и Sass для создания стилей документа.

Презентации на основе reveal.js (включающих в себя Режим докладчика,
Reveal Multiplex plugin, множество различных тем).

Возможности локализации.

Встроенная поддержка Observable JS и Shiny.

Встраивание LearningApps-элементов для организации самотестирования
в учебном процессе.

Автоматизация рутинных процедур с помощью проектно-ориентированных рабочих процессов с GitHub Actions и поддержка Quarto внутри контейнера
Docker для обслуживания HTML-документов и проектов.

Что еще кроме Quarto?

R Markdown предлагает большой выбор библиотек для работы с документами, отчетами, презентациями и дэшбордами, например, bookdown и blogdown.
У части библиотек R нет аналогов в Quarto: pagedown, flexdashboard, learnr.
Об эквивалентах библиотек можно почитать на странице сравнения.

Сравнению R Markdown и Quarto посвящена статья Yihui Xie: With Quarto Coming, is R Markdown Going Away? No, см. также статью We don’t talk about Quarto. Until now! от Alison Hill.

Наряду с R Markdown существуют другие средства для создания публикаций и научных отчетов: Jupyter Book, iPyPublish, Org-Mode, Weave.jl.

Quarto развивается, свои предложения можно оставлять в разделе дискуссии на странице GitHub quarto-cli.

Отметим, что предварительные сборки содержат интересные дополнения. Существуют баги и недостатки Quarto, которые, в основном, быстро исправляются.

Научно-издательская система Quarto

обзор и начало работы

Е.Н. Матеров

4 марта 2023 г.

Название “Quarto”

Содержание

Quarto

Введение в Quarto

Статьи

Веб-страницы

Книги

Презентации

Больше примеров разработок в Quarto

Пример страницы в Quarto

Пример блога в Quarto

Содержание

Начало работы с Quarto

Quarto в RStudio

Quarto в Visual Studio Code

Quarto в Jupyter

Создание документов в Rstudio

Создание документов в Visual Studio Code

Возможности для рендеринга

Единый источник документа

Возможность вывода в нескольких форматах одновременно

Содержание

Составляющие .qmd-документа

Метаданные (YAML-часть документа)

Markdown (форматирование текста)

Markdown (заголовки)

Заголовок 1

Заголовок 2

Заголовок 3

Заголовок 4

Markdown (ссылки и рисунки)

Markdown (списки)

Markdown (таблицы)

Markdown

Вывод

Формулы в Quarto

Выносные блоки

Выносные блоки

Расширенные макеты

Диаграммы

Ячейки с исполняемым кодом

Подсветка кода

Параметры ячейки

Структура проекта блога

Структура проекта книги

Расширения Quarto

Содержание

Основные сервисы для веб-публикации

Пример: публикация в QuartoPub

Страница, опубликованная в QuartoPub

Рабочий процесс с Git

Содержание

Страница Awesome Quarto

Советы дня по Quarto

Приступая к работе с Quarto

От R Markdown к Quarto

Трюки и приемы в Quarto

Советы по Quarto, найденные в Интернете

Создание блога в Quarto

Hello, Quarto: A World of Possibilities

Содержание

Почему стоит попробовать Quarto?

Почему стоит попробовать Quarto?

Что еще кроме Quarto?

Научно-издательская
система Quarto

Составляющие `.qmd`-документа