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

Лекция 5. Начало работы с Quarto и структура документов

Большие данные и аналитика
Бизнес-информатика 38.03.05 (бакалавриат)

Обзор Quarto

Quarto

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

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

В Quarto можно публиковать…

…статьи

…веб-страницы

…курсы

…книги

…презентации

…дэшборды

…постеры

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

Установка Quarto

  • Устанавливаем интерфейс командной строки Quarto CLI

  • Устанавливаем Quarto Extension для IDE (в нашем случае это VS Code)

Quarto в Visual Studio Code

Quarto как CLI

Пример создания проекта в командной строке

Пример создания проекта в командной строке

Предосмотр проекта

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

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

$ 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

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

 

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

1. Метаданные

Метаданные

Метаданные в Quarto реализованы на основе YAML и могут быть включены в Quarto-документ в преамбуле в начале файла и/или в отдельном _quarto.yml-файле (либо ином *.yml-файле, скажем, _extension.yml, _metadata.yml).

YAML
---
# пример YAML-метаданных: 
# заголовок, дата, формат документа, режим редактора
title: "Заголовок документа"
date: today
format: html
editor: visual
---

Пример метаданных

_quarto.yml
project:
  type: website

author: Автор Фамилия

format:
  html:
    toc: true

Пример _quarto.yml

_quarto.yml
# параметры уровня проекта
project:
  # тип проекта
  # возможные типы: default, website, book и manuscript
  type: website
  # папка для выходных HTML-данных
  output-dir: docs

website:
  title: "Название веб-сайта"

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

2. Markdown

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


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

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


Markdown Вывод 
# Заголовок 1

Заголовок 1

 
## Заголовок 2

Заголовок 2

 
### Заголовок 3

Заголовок 3

 
#### Заголовок 4

Заголовок 4

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

Markdown Вывод 
<https://itmo.ru/>
 https://itmo.ru/ 
[ИТМО](https://itmo.ru/)
 ИТМО 
![Заголовок](logo.png)
 Определяющий текст 
[![Заголовок](ITMO-logo.png)](https://itmo.ru/)
 Заголовок 
[![Заголовок](ITMO-logo.png)](https://itmo.ru/ "ИТМО")
 ИТМО 
[![](ITMO-logo.png){fig-alt="Текст"}](https://itmo.ru/)
 Текст.

Markdown (таблицы)


Markdown

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

Markdown (таблицы)


Вывод

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

3. Ячейки с кодом

Ячейки с кодом

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

Блоки кода должны начинаться с ```{language} и завершаться ```, где {language}, в зависимости от языка:

{language} Язык программирования
{r} R
{python} Python
{julia} Julia
{ojs} Observable JS

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

Пример ячейки с кодом

Пример оформления кода в Quarto

Результат исполнения кода

Встроенные вычисления

Помимо вычислений в ячейках, код можно вставлять в в рамках Markdown-разметки. Формат вставки имеет вид `{language} code`.


Quarto
В наборе данных `mtcars` содержатся данные по `r ncol(mtcars)` автомобилям.


В наборе данных mtcars содержатся данные по 11 автомобилям.

Дополнительные элементы

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

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

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

Диаграммы

Использование Mermaid и Graphviz диаграмм позволяет создавать блок-схемы, диаграммы последовательностей, диаграммы состояний, диаграммы Ганта и многое другое, используя синтаксис, вдохновленный Markdown.

Формулы в Quarto

Математические формулы в Quarto используют синтаксис на основе \(\LaTeX\).

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

Заметка

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

Замечание

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

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

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

Совет

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

Пример блока

Это пример блока.

Что можно добавлять в Quarto?

  • Элементы HTML и CSS + Sass
  • Интерактивные элементы на основе R, Python, Observable JS
  • Интерактивные Wasm-элементы на основе WebR и Pyodide (например, Quarto Live позволяет исполнять R непосредственно в браузере, Shinylive — это новый способ полностью запустить Shiny в браузере, см. Пример ShinyLive)
  • JavaScript код (например, в reactable для интерактивных таблиц)
  • R и Python Shiny интерактив

Проекты в Quarto

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

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

myblog/
├── index.qmd (основной файл, рендерится)
├── _quarto.yml (содержит глобальные метаданные)
├── about.qmd
├── style.scss (стили, влияет только на index.qmd)
├── _site (создаваемая папка, публикуется)
└── posts/ (посты)
    └── metadata.yml
    └── welcome/
        └── index.qmd
    └── post-with-code
        └── index.qmd

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

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.

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

Также, актуальные расширения можно посмотреть на странице Quarto Extensions, автор Mickaël Canouil.

Что мы изучили?

Рассмотренные вопросы

  • Обзор Quarto
  • Установка Quarto
  • Начало работы с Quarto
  • Структура документов Quarto
  • Дополнительные элементы
  • Проекты в Quarto

Спасибо за внимание!