Quarto: инструмент публикации ресурсов из markdown документов

инструментарий

markdown

сделай сам

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

Дата публикации

29 апреля 2025 г.

С её помощью один или несколько markdown-документов могут превратиться в отдельную веб-страницу, целый сайт, презентацию, pdf-, docx-, pptx-документ или html-презентацию. В этой заметке расскажу, как я использую эту утилиту в своей работе.

Название Quatro разработчики утилиты взяли от полиграфического термина Ин-кварто - размер страницы в одну четверть типографского листа. На одном листе помещается 4 листа или 8 страниц книги. Первые книги Иоганна Гутенберга печатались в таком формате¹. По этому на вступительном изображении к заметке находится гравюра печатного пресса².

Основы

Утилита Quarto преобразует markdown-разметку в указанный формат. Кроме стандартной разметки, разработчики Quarto добавили ряд элементов с помощью которых в документе появляются интерактивные элементы. Пример интерактивности - подсказки к исходному коду программ:

from machine import Pin

button = Pin(14, Pin.IN, Pin.PULL_DOWN)
led = Pin(12, Pin.OUT)

while True:
    isPressed = button.value()
    if isPressed:
        led.on()
    else:
        led.off()

1: Импортируем из модуля machine объект Pin.
2: Переменная button ссылается на объект Pin. Кнопка подключена к 12 пину. К этому пину подключён один из выводов тактовой кнопки. Пин настраиваем на вход указав вторым параметром значение Pin.IN.
3: Переменная led ссылается на объект Pin. Анод светодиода подключен к 14 пину. Пин настраиваем на выход указав вторым параметром значение Pin.OUT.
4: Запускаем бесконечный цикл while. Весь код внутри цикла будет повторяться до тех пор, пока подаётся питание на микроконтроллер.
5: Переменная isPressed хранит текущее значение на пине 12. Состояние кнопки считываем с помощью метода value().
6: С помощью инструкции if решаем, нужно ли включить или выключить светодиод. Метод on() объекта led включит светодиод, метод off() выключит светодиод.

Подведя курсор к цифре в одной из строк кода, можно увидеть текст подсказки.

У инструкции в html-форме есть свои преимущества. Создаваемая веб-страница использует адаптивные стили и её элементы подстраиваются под расширение экрана. Такую инструкцию можно открыть и на телефоне. Некоторые студенты так и поступают.

Quarto поддерживает диаграммы в формате MermaidJS. Их плюс в том, что изображение генерируется на основе разметки. Если нужно исправить элемент диаграммы, не нужно редактировать изображение, а лишь текст разметки :

graph TD
    folder["<i class="fa-solid fa-folder-open"></i> Скрипты<br>(текущий рабочий каталог)"]
    script([<i class="fa-regular fa-file-code"></i> script.py])
    file(["<i class="fa-regular fa-file-lines"></i> verse.txt"])

    folder-->script
    folder-->file

Рисунок 1

Эта структура каталогов создана на основе следующей разметки:

%%| label: fig-folder-tree
graph TD
    folder["Скрипты<br>(текущий рабочий каталог)"]
    script([script.py])
    file(["verse.txt"])
    folder-->script
    folder-->file

Если понадобится изменить имена файлов на диаграмме или добавить ещё один, это легко сделать, исправив текстовую разметку.

С помощью Quarto можно делать перекрёстные ссылки на изображения, формулы, таблицы и листинги программ. Например, чтобы сослаться на предыдущую диаграмму, нужно написать @fig-folder-tree. В итоге получим такую ссылку: Рисунок 1. Подводим курсор и получаем предпросмотр изображение, кликаем - и переходим к самому изображению.

По началу обилие настроек а также инструментов разметки может сбить с толку. Через некоторое время

Веб-сайт

Когда у меня накопилась критическая масса инструкций к лабораторных работам, захотелось объединить их в один ресурс и разместить в интернете. В начале я использовал похожую на Quarto систему - mkdocs. Возникли трудности с настройкой блога. После долгих попыток настроить mkdocs, я перешёл на Quarto.

Этот сайт состоит из набора каталогов с markdown-документами и файлов конфигурации. После настройки, оглавление сайта создаётся автоматически. Хотя сайт статичный, но есть функция поиска.

Презентации

Большим открытием для меня стала возможность преобразовать md-разметку в презентацию. Quarto поддерживает создание RevealJS презентаций.

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

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

Любопытно, что в RevealJS презентации структура слайдов - двумерна. Заголовки первого уровня образуют горизонтальную структуру. Заголовки второго уровня образуют вертикальную структуру, позволяя углубиться в тему.

Лично для меня важными оказались две функции - анимация подсветки кода и анимация добавления кода.

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

Документы для печати

В некоторых ситуациях нужен печатный вариант документов. Quarto поддерживает создание docx и pdf-документов. Добавив несколько конфигурации в начале md-файла получаем на выходе файлы нужных форматов:

format:
  html: default
  typst:
      papersize: a4
      margin:
          x: 1cm
          y: 1cm
      columns: 1
      mainfont: "Lato"
      fontsize: 10pt

Эта разметка скажет Quarto, что документ нужно сохранить как веб-страницу и pdf-файл. Мне не нужно вручную настраивать поля страницы, количество колонок, размер шрифта. Это на себя берёт утилита. При экспорте в docx-файл можно указать шаблон со стилями, которые будут использоваться в экспортированном документе.

Пример генерации pdf-документа можно найти на этой странице в разделе Другие форматы под оглавлением.

Расширения

Через некоторое время использования Quarto, мне стало не хватать некоторых функций. Например быстрой вставки и оформления текста с клавиатурными комбинациями. Хотелось чтобы элементы с клавишами выделялись на страницах сайта. Не найдя готового решения, я нашёл в документации страницу о разработке собственных плагинов. Разрабатывать расширения можно или на JavaScript или на Lua. Последний язык, со слов документации, предпочтительнее, но я его совсем не знал. Разработку расширения я отложил на долгий срок не до конца понимая, как устроены расширения. В итоге помогло чтение исходного кода готовых расширений. К счастью исходники можно найти на GitHub. Так появилось расширение KbDisplay. Оно пока не опубликовано.

Расширение особенно пригодилось для раздела по моделированию в TinkerCad. Многие действия в программе выполняются либо мышью, либо клавиатурными комбинациями. Расширение форматирует разметку и, к примеру, превращает текст ++ctrl+shift+c++ в ⌃Ctrl + ⇧Shift + C .

Следующий крупный шаг в разработке расширений для Quarto - Shortiquiz. Долгое время инструкциям для лабораторных и практических на сайте не хватало инструментов оценивания. Готовые плагины снова не подошли и летом началась разработка расширения. Источником мотивации была возможность внедрить в работу обновлённый курс по Python, в котором просто напрашивались тестовые вопросы для самопроверки.

В первую очередь появились строчные вопросы, находящиеся прямо в тексте. Идею подсмотрел у сервиса Mathigon. Теперь в инструкциях можно встретить вопросы, встроенные к текст. После x правильного ответа, блок с вопросом меняется на обычный текст. Хотелось сделать учащихся активными читателями, которые не просто пропускают текст теории или инструкции а вынуждены осмыслить прочитанное и подтвердить правильность понимания текста. В первую очередь для самих себя.

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

Примерно в это время нашёл расширение Pyodide с помощью которого Python-код на странице становится интерактивным. Его можно редактировать и запускать. К сожалению в реализации расширения не было поддержки модуля turtle, который был мне нужен. По этому было написано расширение SkPython. Следующий код можно редактировать и запускать прямо в браузере:

from turtle import *

speed(1)

n = 5
for i in range(n):
    forward(75)
    left(360 // n)

done()

from turtle import *

speed(1)

n = 5
for i in range(n):
    forward(75)
    left(360 // n)

done()

Это расширение было самым сложным компонентом сайта. Разработка и отладка заняли много времени, но оно того стоило. Ведь на страницах лабораторных по Python появились интерактивные элементы. И теперь теорию сопровождает живая демонстрация.

Следующая проблема которую я стал решать с помощью расширений - концентрация внимания на важных шагах инструкции. Веб-страница непрерывна в отличие от pdf-документа. Студенты могут потеряться в тексте, им может быть тяжело найти шаги которые уже выполнены, а какие ещё предстоит сделать. Я вспомнил о ресурсе под названием Code Club. Инструкции к проектам на этом сайте чётко разделены на шаги. Каждый шаг позволяет ученику поставить галочку о выполнении. Так появилось расширение StepByStep.

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

Между шагами можно разместить дополнительную теорию или пояснения.

Но основные действия теперь чётко выделяются на фоне поясняющего текста.

Разметка для каждого шага очень простая - нужно поместить действия между следующими элементами:

:::{.sbsaction}

:::

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

Такой блок тоже чётко выделяется на фоне остальной инструкции.

Выше в заметке я упомянул функцию Quarto, с помощью которой добавляются всплывающие подсказки для кода программ. В моих занятиях часто встречаются визуализированные языки программирования, иллюстрации со схемами для сборки. Нужна была функциональность для подсветки элементов изображения. Эта функция была добавлена следующей. При оформлении некоторых элементов я вдохновлялся инструкциями на сайте lastminuteengineers.com.

На рисунке показана схема для сборки. С помощью шорткодов на рисунке подсвечивается светодиод и пин 12 к которому подключён его анод. Если подвести курсор к подсвеченным в тексте элементам, то появится стрелка, связывающая текст с изображением. Так можно показать где на схеме находится резистор и тактовая кнопка, пин Vin и 14.

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

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

Ещё много задумок по улучшению сайта можно реализовать в будущем. Главное не останавливаться на достигнутом и не требовать от себя слишком многого.

Основы

Веб-сайт

Презентации

Документы для печати

Расширения

Сноски