Quarto — це науково–технічна видавнича система з відкритим кодом, яка ґрунтується на універсальному конверторі документів Pandoc та використовує мову розмітки Markdown. Це універсальний інструмент для тих, хто пише на R, Python, Julia та Observable JavaScript.
За допомогою Quarto можна поєднувати описовий текст і код для створення відформатованих документів, веб–сторінок, постів у блогах, книг тощо.
Розробники Quarto хотіли використати ім’я, яке мало деяке значення в історії видавничої справи. Вибір пав на Quarto (від латинського quārtō, скорочено Qto, 4to або 4º) — це формат книги або брошури в одну четвертину топографічного листа. На кожній стороні листа при цьому поміщається 4 сторінки книги (8 сторінок на один лист).
Найраннішим відомим виданням такого формату була Книга Сивіл (англ. Sibyllenbuch), що була надрукована Йоганном Гутенбергом у 1452–1453 роках.
Quarto являє собою текстовий документ спеціального формату .qmd, який можна скомпілювати у різноманітні документи:
Для роботи з Quarto потрібно: 1. Встановити інтерфейс командного рядка Quarto (CLI) під актуальну операційну систему (Windows, Linux або Mac OS).
Створити Quarto–проект можна декількома шляхами:
terminal
# веб-сайт
quarto create-project mysite --type website
# блог
quarto create-project myblog --type website:blog
# книга
quarto create-project mybook --type book
Спочатку Knitr (для R) або Jupyter (для Python або Julia) виконує всі фрагменти коду .qmd-файлу і створює новий markdown (.md) документ, який включає в себе код і всі його результати. Далі .md–файл оброблюється Pandoc для перетворення у різноманітні формати файлів (HTML, PDF, Word тощо).
terminal
quarto render <input> --to <format>
# Наприклад:
quarto render document.qmd --to docxQuatro документи складаються з трьох базових складових:
YAML–шапка знаходиться нагорі документу і відділена трьома дефісами (---) зверху та знизу. В ній зберігається мета–інформація документу: назва, дата створення, автор, інформація щодо роботи коду, контенту і процесу рендерінгу.
---
title: "Dracula"
author: "Bram Stoker"
date: "May 26, 1897"
format:
html:
toc: true
code-fold: true
---Ця частина документу йде одразу після YAML–шапки і складає основну частину документу.
Markdown — це популярна і зручна мова розмітки. Ви непевно зустрічали її в README.md–файлах репозиторіїв GitHub, а також у Telegram–повідомленнях.
Чанки — це блоки, які відділяються від тексту потрійними зворотніми лапками ``` ( анг. backtick) на початку та в кінці. У фігурних дужках вказується мова програмування на якій необхідно виконати код.
```{python}
print('Fly, you fools!')
```Результат чанку за замовчування виводиться одразу після нього, але все це можна налаштувати.
Метадані документу можуть бути задані у шапці документу або окремим _quarto.yml-файлом.
В цій частині документу зберігається інформація щодо назви документу, дати, автора, налаштування рендерінгу, параметри чанків та інші додаткові налаштування. Всі параметри встановлюються у форматі key: value.
Ключ format: відповідає за тип вихідного файлу.
| Тип | Значення | Опис |
|---|---|---|
| Документи |
|
|
| Презентації |
|
|
| Markdown |
|
|
| Wiki |
|
|
А також цілу низку інших форматів, документацію по котрим можна отримати в розділі Reference документації.
В залежності від типу вихідного документу, ці ключі можуть відрізнятися, але наведу основні:
| Ключ | Значення |
|---|---|
title |
Назва документа |
subtitle |
Підзаголовок документа |
date |
Дата документа |
author |
Автор або автори документа |
Для генерації змісту (анг. table of contents, скорочено toc) необхідно ключу toc задати значення true. В залежності від типу вихідного документу зміст буде згенерований відповідно до заголовків (Розділ 23.5.2).
| Ключ | Значення |
|---|---|
toc |
Додайте автоматично створений зміст у вихідний документ. |
toc-depth |
Кількість рівнів розділу, які потрібно включити у зміст. За замовчуванням 3 |
toc-title |
Заголовок, використаний для змісту. |
Quarto, Pandoc та LaTeX генерують текстові елементи документу, які потребують локалізації. Наприклад: “Рисунок” або “Таблиця” для перехресних посилань, назви виносок тощо.
langПриклад використання польської локалізації документу:
---
title: "Mój dokument"
lang: pl
---Це призведе до використання польського перекладу компонентів документу, а також до застосування інших мовних правил обробки документів.
Наразі доступні повні переклади такими мовами:
en, за замовчуванням)nl)es)it)zh)kr)de)pl)pt)ru)fi)fr)cs)ja)Якщо вас не влаштовує мова за умовчанням, яка використовується для певної частини документа, ви можете вказати альтернативну мову за допомогою ключа language. Наприклад, щоб замінити значення підписів «Author» і «Published», які використовуються в блоках заголовків, ви можете зробити це:
---
title: "Мій документ"
author: "Ігор Мірошниченко"
date: 12/15/2022
language:
title-block-author-single: "Автор"
title-block-published: "Опубліковано"
---Всі ці зміни можна зберегти в окремому .yml-файлі і використовувати власну локалізацію до документу:
---
title: "Мій документ"
author: "Ігор Мірошниченко"
date: 12/15/2022
language: custom.yml
---Я зробив власну українську локалізацію Quarto-документів, яку Ви можете завантажити з мого GitHub-репозиторія: https://github.com/aranaur/quarto-ukrainian.
Ознайомитися з усіма офіційними локалізаціями можна за посиланням: https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/language.
Quarto ґрунтується на Pandoc та використовує різновид markdown в якості базового синтаксису. Pandoc markdown — це розширена та злегка перероблена версія синтаксису markdown.
Markdown — це формат звичайного тексту, який розроблено таким чином, щоб його було легко писати та, що ще важливіше, легко читати.
| Синтаксис markdown | Результат |
|---|---|
|
курсив та жирний |
|
надрядковий2 / підрядковий2 |
|
|
|
дослівний код |
| Синтаксис markdown | Результат |
|---|---|
|
Заголовок 1 |
|
Заголовок 2 |
|
Заголовок 3 |
|
Заголовок 4 |
|
Заголовок 5 |
|
Заголовок 6 |
| Синтаксис 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 |
Формувати такі таблиці вручну досить складно і незручно. В таких випадках на допомогу приходить Markdown Tables Generator.
Markdown() та пакету tabulate:terminal
pip install tabulatefrom IPython.display import Markdown
from tabulate import tabulate
table = [["Bilbo Baggins", "Hobbits", "Male"],
["Beren", "Men", "Male"],
["Nimrodel", "Elves", "Female"],
["Muzgash", "Orc", "Male"]]
Markdown(tabulate(
table,
headers=["Name", "Race", "Sex"]
))| Name | Race | Sex |
|---|---|---|
| Bilbo Baggins | Hobbits | Male |
| Beren | Men | Male |
| Nimrodel | Elves | Female |
| Muzgash | Orc | Male |
print(), у форматі консолі:import pandas as pd
df = pd.DataFrame(data = table,
columns = ["Name", "Race", "Sex"])
print(df) Name Race Sex
0 Bilbo Baggins Hobbits Male
1 Beren Men Male
2 Nimrodel Elves Female
3 Muzgash Orc MaleДля запису рівняння в середині тексту використовується одинарний символ $ та подвійний $$ для запису рівняння з нового рядка:
| Синтаксис markdown | Результат |
|---|---|
|
у середині тексту: \(E=mc^{2}\) |
|
з нового рядка: \[E = mc^{2}\] |
В якості допомоги формування рівнянь рекомендую ресурс Online LaTeX Equation Editor.
Quarto має вбудовану підтримку для створення діаграм Mermaid та Graphviz. Це дає змогу створювати блок–схеми, діаграми послідовності, діаграми станів тощо, використовуючи синтаксис простого тексту.
Приклад створення блок–схеми за допомогою Mermaid:
```{mermaid}
flowchart LR
A[Квадратна форма] --> B(Кругла форма)
B --> C{Рішення}
C --> D[Результат один]
C --> E[Результат два]
```flowchart LR
A[Квадратна форма] --> B(Кругла форма)
B --> C{Рішення}
C --> D[Результат один]
C --> E[Результат два]
Більше інформації у розділі Diagrams.
Вставляти відео у документи можна за допомогою запису {{< video >}}.
Приклад використання відео з Youtube:
{{< video https://www.youtube.com/embed/qOhk7YyxXQ4 >}}Більше інформації у розділі Videos.
Виноски — чудовий спосіб привернути додаткову увагу до певних понять або чіткіше вказати, що певний вміст є додатковим або потребує додаткової уваги.
У Quarto є п’ять різноманітних виносок: - примітка (note) - застереження (warning) - важливо (important) - підказка (tip) - попередження (caution)
Колір і значок відрізнятимуться залежно від обраного типу. Ось як виглядають різні виноски в HTML:
Зауважте, що існує п’ять типів виносок, зокрема: note, tip, warning, caution та important.
Виноски — простий спосіб привернути увагу, наприклад, до цього застереження.
Виноски точно покращать Ваш текст.
Приклад виноски з текстом
Це приклад «згорнутої» виноски з попередженням. Використайте collapse="true" щоб згорнути її за замовчуванням та collapse="false" щоб виноска могла бути згорнута, але була розгорнути за замовчуванням.
Створіть виноски в розмітці за допомогою наступного синтаксису (зверніть увагу, що перший заголовок, використаний у виносці, використовується як заголовок виноски):
::: {.callout-note}
## Примітка
Зауважте, що існує п’ять типів виносок, зокрема:
`note`, `tip`, `warning`, `caution` та `important`.
:::
::: {.callout-tip}
## Підказка
Приклад виноски з текстом
:::
::: {.callout-caution collapse="true"}
## Розгорніть, щоб дізнатися про згортання
Це приклад «згорнутої» виноски з попередженням.
Використайте `collapse="true"` щоб згорнути її за замовчуванням та `collapse="false"` щоб виноска могла бути згорнута, але була розгорнути за замовчуванням.
:::| Синтаксис markdown | Результат |
|---|---|
|
тире: - |
|
коротке (середнє) тире: – |
|
довге тире: — |
Існує широкий спектр доступних параметрів для налаштування виводу виконаного коду. Усі ці параметри можна вказати глобально (у YAML-шапці з ключем execute) або для кожного блоку коду.
---
title: "Мій документ"
author: "Ігор Мірошниченко"
execute:
echo: false
---```{python}
#| echo: true
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
x = np.arange(-4, 4, .012)
y = np.arange(-4, 4, .012)
X, Y = np.meshgrid(x, y)
Z = 1 - np.abs(X) - np.sin(Y**2)
W = 1 + Y - np.cos(X**2)
fig = plt.figure(figsize=(8, 8))
ax = fig.add_subplot(projection='polar')
plt.scatter(Z, W, alpha=.03, s=0.2)
plt.axis('off')
plt.show()
```Параметри налаштування знаходяться у верхній частині блоку під спеціальним коментарем #|.
| Налаштування | Опис |
|---|---|
eval |
Оцініть фрагмент коду (якщо false, просто відтворіть код). |
echo |
Показувати код (якщо false, код не буде виведено на екран). |
warning |
Показувати попередження, які виникають під час виконання коду |
error |
Показувати помилки у документі (це означає, що помилки під час виконання коду не зупинять обробку документа). |
include |
Запобігає виводу коду та його результатів. |
Quarto дозволяє виводити результат коду в середині тексту. Це особливо зручно, якщо необхідно щоб документ використовував найсвіжіші розрахунки. Проте синтаксис виводу залежить від рушія (анг. engine) Quarto: Jupyter, Knitr або OJS.
Щоб включити збережену змінну, використовуєте IPython.display.Markdown.
Наприклад, виведемо площу кола за заданим радіусом (radius):
```{python}
#| echo: false
from IPython.display import Markdown
import math
radius = 10
circle_area = math.pi * pow(radius, 2)
Markdown((f"""
Площа кола з радіусом {radius} дорівнює {round(circle_area, 2)}.
"""
))
```Зауважте, що ми використовуємо опцію echo: false, щоб не виводити код у фінальний документ, а тільки результат.
Існує низка способів публікації документів, презентацій і веб-документів, створених за допомогою Quarto. Оскільки вміст, відтворений за допомогою Quarto, використовує стандартні формати (HTML, PDF, MS Word тощо), його можна опублікувати будь-де. Крім того, доступна команда quarto publish для легкої публікації в різних популярних службах (GitHub, Netlify, RStudio Connect тощо), а також різні інструменти, які полегшують публікацію з системи Неперервної інтеграції (анг. Continuous integration).
Сервіси для публікації:
| Сервіс | Опис |
|---|---|
| Quarto Pub | Публікація документів, веб-сайтів і книг Quarto. |
| GitHub Pages | Публікація документів за допомогою репозиторію GitHub |
| RStudio Connect | Платформа для безпечного обміну даними в межах організації. |
| Netlify | Професійна платформа веб-публікації. |
| Інші сервіси | Скористайтеся цими сервісами, якщо один із наведених вище методів не відповідає вашим вимогам. |
YAML це рекурсивний акронім YAML Ain’t Markup Language («YAML — не мова розмітки»). У назві відображена історія розвитку: на ранніх етапах мова називалася Yet Another Markup Language («Ще одна мова розмітки») і навіть розглядалася як конкурент XML, але пізніше була перейменована з метою акцентувати увагу на даних, а не на розбивці документів.↩︎