10  Создание книг

Возможности Quarto позволяют создавать книги в различных форматах, сочетая открытый код, доступ к данным и интерактивные элементы в онлайн-версиях. Примеры таких книг можно найти в Галерее примеров книг Quarto. В Quarto возможны следующие варианты для форматов книг: HTML, MS Word, EPUB, AsciiDoc, а начиная с версии 1.9 в Quarto возможно создавать книги в Typst-формате с последующим выводом в PDF.

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

10.1 Создание книги на основе шаблона

Для создания книг можно использовать, аналогично проектам веб-страниц и блогам, те же инструменты: Visual Studio Code (или Positron), RStudio и командную строку.

VS Code

Книгу на основе шаблона в Visual Studio Code (соответственно, Positron) можно создать, выбрав в меню File : New File… : Quarto Project и далее указать Book Project.

Рисунок 10.1: Пример создания книги в Quarto в Visual Studio Code / Positron

RStudio

Для того, чтобы создать книгу в Quarto в RStudio, необходимо выбрать в меню File : New Project… : New Directory : Quarto Book как на рисунке.

Рисунок 10.2: Пример создания книги в Quarto в RStudio

Терминал

Основу для будущей книги можно легко создать с помощью команд в терминале. Для этого необходимо открыть терминал в директории, где необходимо создать книгу, и далее следовать указаниям, набрав команду quarto create project либо quarto create-project --type book, если проект книги создается в текущей директории.

Terminal

quarto create project

Рисунок 10.3: Пример создания книги в Quarto в терминале

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

Рисунок 10.4: Процесс создания книги в Quarto в терминале

Для предварительного просмотра необходимо набрать команду quarto preview, а для полного рендеринга проекта — команду quarto render.

Рисунок 10.5: Пример книги в Quarto на основе базового шаблона

Шаблон созданной на основе шаблона книги как проекта будет содержать следующие файлы в новой директории:

book_directory/my_book
1├── _quarto.yml
2├── index.qmd
3├── intro.qmd
4├── summary.qmd
5├── references.qmd
6├── references.bib
7└── cover.png

1

Файл с метаданными проекта Quarto-книги (_quarto.yml).

2

Основной файл книги (index.qmd).

3

Глава: Введение (intro.qmd).

4

Глава: Заключение (summary.qmd).

5

Глава: Библиография (references.qmd).

6

BibTeX-файл с метаданными для формирования библиографии (references.bib).

7

Обложка книги (cover.png).

В результате рендеринга проекта будет создан каталог _book, содержащий все возможные определенные форматы книги, например, если основной формат HTML, то обязательно сформируется файл index.html.

10.2 Структура книги

10.2.1 Навигация

Структура книги определяется файлом _quarto.yml. Ниже представлен пример простого YAML-файла, задающего структуру книги.

_quarto.yml

project:
  type: book

book:
  # заголовок
  title: "Философия науки"
  # подзаголовок
  subtitle: "исторический обзор и современные проблемы"
  # автор
  author: "А.А. Автор"
  # аннотация
  abstract: "В книге рассмотрены современные подходы к практическим задачам."
  # текущая дата
  date: today
  # главы
  chapters:
    - index.qmd
    - introduction.qmd
    - text: "Содержание"
      href: Guide/index.qmd
    - text: "Основной текст"
      href: Main/index.qmd
    - exercises.qmd 
    # библиография
    - references.qmd
  # приложения
  appendices:
    - Appendicies/first.qmd
    - Appendicies/second.qmd 

# метаданные библиографии
bibliography: references.bib

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

Названия глав указываются как заголовки первого уровня:

introduction.qmd

# Введение {#introduction}

Текст главы...

Совет

Указывайте в заголовках ключи для перекрестных ссылок (например, как выше {#introduction}), это поможет ориентироваться в тексте или в дальнейшем ссылаться на части книги.

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

_quarto.yml

book:
  chapters:
    - text: "Основной текст"
      href: Main/index.qmd

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

index.qmd

# Введение {.unnumbered}

Текст главы...

Библиография будет сгененрирована автоматически при рендеринге проекта, в который включен файл references.bib, а также файл references.qmd вида:

# Список литературы {.unnumbered}

::: {#refs}
:::

Рисунок 10.6: Содержание файла references.qmd

10.2.2 Части книги

Если структура книги достаточно сложная, можно разделить такую книгу на части, используя параметр part:

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "Название части"
      chapters: 
        - basics.qmd
        - experiments.qmd
    - part: new_part.qmd
      chapters:
        - objects.qmd
        - notation.qmd
        - environments.qmd

Рисунок 10.7: Пример частей книги в Quarto

УведомлениеЗамечание

Форматы HTML, PDF и Typst полностью поддерживают части книги и приложения, в отличие от форматов EPUB и MS Word (Docx), которые будут игнорировать эти структуры при рендеринге.

10.2.3 Приложения

Для добавления приложений необходимо добавить соответствующие части в _quarto.yml.

book:
  chapters:
    - index.qmd
    - preface.qmd
    - references.qmd
  # приложения:
  appendices:
    - appendix_1.qmd
    - appendix_2.qmd

# заголовок для приложений:
crossref:
  appendix-title: "Приложение"
  appendix-delim: ":"
crossref-apx-prefix: "Приложение"

Рисунок 10.8: Пример приложений в Quarto-книге

10.2.4 Изображение обложки

Для книг в форматах HTML и EPUB можно установить изображение в качестве обложки книги, указав это в YAML.

book:
  cover-image: cover-image.png

Рисунок 10.9: Пример HTML-книги с обложкой

Также возможно установить обложки для каждого из указанных форматов:

format:
   html: 
     cover-image: cover-HTML.png
   epub:
     cover-image: cover-EPUB.png

Рисунок 10.10: Пример EPUB-книги с обложкой

Отметим, что использование CSS/SCSS позволяет привнести дополнительные эффекты, например, сделать тень для обложки или преобразование-переход при наведении курсора на обложку.

book-theme.scss

img.quarto-cover-image {
  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
  border-radius: 4px;
  transition: transform 0.3s, box-shadow 0.3s;
}

img.quarto-cover-image:hover {
  transform: translateY(-5px);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
}

10.3 Дополнительные замечания по созданию книг

10.3.1 Использование скриптов для настроек

Mine Çetinkaya-Rundel в своем докладе Reproducible, dynamic, and elegant books with Quarto привела множество замечательных советов по созданию книг в Quarto. Вот один них.

Рутинные настройки книги удобно оформлять как скрипт и затем отдельно подгружать, например, в начале каждой главы, указывая ссылку на R-файл, обязательно указывая префикс нижнего подчеркивания в начале файла, чтобы исключить рендер:

R

#| echo: false
source("_common.R")
status("drafting")

В свою очередь, _common.R может содержать установки для отображения рисунков, базовую тему для {ggplot2}-изображений, сообщения по статусу текущего издания, функциональные скрипты, позволяющие отображать текущий статус и многое другое. Полный пример такого файла можно найти в коде книги R for Data Science (2e), приведем его адаптированный вариант ниже.

Пример скрипта

_common.R

set.seed(1014)

knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  fig.retina = 2,
  fig.width = 6,
  fig.asp = 2 / 3,
  fig.show = "hold"
)

options(
  dplyr.print_min = 6,
  dplyr.print_max = 6,
  pillar.max_footer_lines = 2,
  pillar.min_chars = 15,
  stringr.view_n = 6,
  cli.num_colors = 0,
  cli.hyperlink = FALSE,
  pillar.bold = TRUE,
  width = 77 # 80 - 3 для #> комментария
)

ggplot2::theme_set(ggplot2::theme_gray(12))

status <- function(type) {
  status <- switch(
    type,
    polishing = "должно быть читабельным, но в настоящее время проходит окончательную доработку",
    restructuring = "находится в стадии интенсивной реструктуризации и может быть запутанным или неполным",
    drafting = "в настоящее время это свалка идей, и мы не рекомендуем ее читать",
    complete = "в значительной степени завершено и просто нуждается в окончательной корректуре",
    stop("Invalid `type`", call. = FALSE)
  )

  class <- switch(
    type,
    polishing = "note",
    restructuring = "important",
    drafting = "important",
    complete = "note"
  )

  cat(paste0(
    "\n",
    ":::: status\n",
    "::: callout-",
    class,
    " \n",
    "Вы читаете находящееся в стадии разработки второе издание книги R for Data Science. ",
    "Эта глава ",
    status,
    ". ",
    "Вы можете ознакомиться с полным первым изданием по адресу <https://r4ds.had.co.nz>.\n",
    ":::\n",
    "::::\n"
  ))
}

10.3.2 Книги в Typst

В Quarto возможно создавать книги на основе Typst, выходным форматом которых будет PDF. Для этого сначала необходимо установить расширение Orange Book Format.

Terminal

quarto add quarto-ext/orange-book

Теперь достаточно в _quarto.yml указать

project:
  type: book

format: orange-book-typst

или более развернуто:

_quarto.yml

project:
  type: book

book:
  title: "Моя первая книга"
  author: "А.А. Автор"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    # - references.qmd <-- не нужно заводить отдельную главу, 
    # библиография формируется автоматически

bibliography: references.bib

format:
  orange-book-typst:
    theme:
      - cosmo
      - brand

lang: ru

Макеты таких книг поддерживают брендирование с помощью _brand.yml, части и главы, приложения, перекрестные ссылки, нумерацию глав, оглавление и список литературы. Ниже показан пример элементов PDF-книги, сделанной с помощью расширения Orange Book.

Титульный лист книги

Содержание

Пример главы

10.3.3 Создание индексов и глоссариев

Еще одно наблюдение, которое мы здесь подробно не рассматриваем — это возможность создания книжных указателей (индексов) в Quarto. Дело в том, что и для HTML и для PDF в Quarto используется единый источник, но для вывода в HTML нет логического эквивалента индекса, поскольку в нем нет «страниц», на которые можно было бы ссылаться. Вместо этого, для книжных проектов Quarto предоставляет функцию поиска; она полезна, но не так действенна, как хорошо составленный индекс. Например, можно было указать

::: {.content-visible when-format="pdf"}
\index{термин}
:::

но это не очень эффективно.

Michael Friendly для написания своей книги Visualizing Multivariate Data and Models in R использовал в качестве решения набор вспомогательных функций R, которые форматируют имя библиотеки и генерируют индексные записи только для PDF через вызовы специальных LaTeX-макросов. Подробнее можно прочесть об этом в статье Creating Book Indexes in Quarto.

Для создания глоссария книги можно воспользоваться расширением quarto-glossary, установить которое можно с помощью команды

Terminal

quarto install extension debruine/quarto-glossary

Далее в YAML необходимо добавить

_quarto.yml

glossary:
  path: glossary.yml
  popup: click  # опции: click, hover или none 
  show: true

определить понятия в glossary.yml:

glossary.yml

p-value: |
  вероятность появления наблюдаемых данных...

и указать в тексте понятие, следующее за словом glossary

{{< glossary p-value >}}

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

Заключение

В этой главе мы рассмотрели различные варианты создания книг на основе шаблонов. Также в тексте было отмечено, как выглядит структура книги, включая навигацию, части книги, главы, параграфы. В заключении были рассмотрены дополнительные вопросы создания книг, такие как использование скриптов для настроек и создание книг на основе Typst. Очень хорошее представление по использованию Quarto как системы публикации для написания книг можно почерпнуть из статьи Using Quarto to Write a Book, автор которой Kieran Healy.