Quarto. Структура для книги

2025-03-27 · 6 мин. для прочтения

Quarto. Структура для книги.

Содержание

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

1.1 Общая информация

  • Quarto Books — это комбинации нескольких документов (глав) в одну рукопись.
  • Книги могут быть созданы в различных форматах:
    • HTML
    • PDF
    • MS Word
    • EPUB
    • AsciiDoc

1.2 Создание структуры книги

  • Чтобы создать новый проект книги из терминала, используйте команду quarto create project:
    quarto create project book mybook
  • Это создаст основу для простой книги в каталоге mybook.
  • Используйте quarto preview команда для рендеринга и предварительного просмотра книги:
    quarto preview mybook
  • Предварительный просмотр книги откроется в веб-броузере.

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

Выше мы продемонстрировали, как создать и отредактировать простую книгу с главами, содержащимися в файлах. index.qmd, intro.qmd, summary.qmd . Здесь мы более подробно рассмотрим дополнительные аспекты процесса работы с книгами.

1.4 Файл конфигурации

  • Файл проекта Quarto ( _quarto.yml ) содержится в каталоге проекта книги.
  • Этот файл содержит начальную конфигурацию книги:
    project:
  type: book

book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
​    - index.qmd
​    - intro.qmd
​    - summary.qmd
​    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

1.4.1 Компиляция

  • Используйте команду render для рендеринга всех форматов вывода:
    quarto render
  • Если не передавать аргументы quarto render, будут созданы все форматы.
  • Можно отображать отдельные форматы через аргумент --to:
    quarto render           # render all formats
quarto render --to pdf  # render PDF format only
  • Результат компиляции книги будет записан в подкаталог _book:
    mybook/
  _book/
    index.html # and other book files
    mybook.pdf
    mybook.epub

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

2.1 Общая информация

  • Главы и разделы книги Quarto автоматически нумеруются (для перекрестных ссылок).

  • Можно указать, что некоторые части книги должны оставаться ненумерованными.

  • Свойства книги, такие как название, автор и структура главы, перечислены под book:

    book:
  title: "mybook"
  author: "Jane Doe"
  date: "5/9/2021"
  chapters:
​    - index.qmd
​    - intro.qmd
​    - summary.qmd
​    - references.qmd
    Распечатка 1: _quarto.yml
    • Файл index.qmd обязателен (потому что Quarto books также создают веб-сайт в формате HTML).
      • Эта страница должна включать предисловие, благодарности и т. д. HTML-версия книги будет использовать index.qmd как домашняя страница и, если предусмотрено, разместит cover-image на этой странице.
    • Остаток chapters включает в себя одну или несколько глав книги.
    • Файл references.qmd будет включать сгенерированную библиографию.

  • Параметры рендеринга, которые должны применяться ко всем главам и всем форматам, перечислены на верхнем уровне _quarto.yml (т.е. не вложенном в book):

    bibliography: references.bib
    Распечатка 2: _quarto.yml

  • Параметры рендеринга, которые должны применяться ко всем главам для определённых форматов, перечислены в секции format:

    format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    Распечатка 3: _quarto.yml

2.2 Названия

  • Название задаётся в title:
    ---
title: "Introduction"
---

2.3 Номера глав

  • Все главы пронумерованы по умолчанию.
  • Если вы хотите, чтобы глава была ненумерованной, просто добавьте класс .unnumbered к его основному заголовку:
    # Preface {.unnumbered}
  • Можно смешивать пронумерованные и ненумерованные главы.
  • Хотя вы можете ссылаться на ненумерованные главы, вы не можете ссылаться на рисунки, таблицы и т. д. внутри них.

2.4 Номера разделов

  • Вы можете задать глубину нумерации через number-depth.

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

    number-depth: 1
    Распечатка 4: _quarto.yml

  • Если необходимо, чтобы number-depth применялась только к определённому формату, вложите его в format :

    format:
  pdf:
    number-depth: 1
    Распечатка 5: _quarto.yml

  • Опция toc-depth не зависит от number-depth.

2.5 Библиография

  • Следует включить div с идентификатором #refs в том месте книге, где должна быть создана библиография:
    # References {.unnumbered}

::: {#refs}
:::
    Распечатка 6: _quarto.yml

2.6 Создание индекса

  • Для вывода PDF вы можете создать индекс, используя пакет LaTeX makeidx вместе с командой \index.
  • Команда \index для выходных данных в формате, отличном от pdf, игнорируются.
  • Чтобы добавить индекс в PDF-файл книги, добавьте эти записи include-in-header и include-after-body в конфигурацию формата pdf в _quarto.yml:
    format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header:
      text: |
        \usepackage{makeidx}
        \makeindex
    include-after-body:
      text: |
        \printindex
    Распечатка 7: _quarto.yml
  • Затем добавьте команды \index{entry} везде, где вам нужна запись индекса:
    Markdown\index{Markdown} allows you to write using an easy-to-read, easy-to-write plain text format.
  • Также можете использовать пакет imakeidx:
    format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header:
      text: |
        \usepackage{imakeidx}
        \makeindex[intoc=true, columns=3, columnseprule=true, options=-s latex/indexstyles.ist]
    include-after-body:
      text: |
        \printindex
    Распечатка 8: _quarto.yml
  • Этот пакет предлагает дополнительные возможности для форматирования индекса.
  • В приведенном выше примере:
    • intoc=true включит запись для индекса в оглавление;
    • columns=3 отформатирует индекс в три столбца;
    • columnseprule=true отобразит линию между столбцами индекса;
    • options=-s latex/indexstyles.ist будут использоваться дополнительные параметры форматирования из файла индексного стиля, расположенного по адресу latex/indexstyles.ist.

2.7 Части

  • Форматы EPUB и Word (Docx) в настоящее время не поддерживают организацию книг в части.
  • При рендеринге книги с частями в эти форматы части будут проигнорированы.
  • Вы можете разделить свою книгу на части, используя part в иерархии chapters:
    book:
  chapters:
​    - index.qmd
​    - preface.qmd
​    - part: dice.qmd
      chapters:
​        - basics.qmd
​        - packages.qmd
​    - part: cards.qmd
      chapters:
​        - objects.qmd
​        - notation.qmd
​        - modifying.qmd
​        - environments.qmd
    Распечатка 9: _quarto.yml
  • Тут файлы разметки dice.qmd и cards.qmd содержат заголовок части (как заголовок первого уровня), а также некоторое вводное содержание для части.
  • Если нужен только заголовок части, то вы можете использовать этот синтаксис:
    book:
  chapters:
​    - index.qmd
​    - preface.qmd
​    - part: "Dice"
      chapters:
​        - basics.qmd
​        - packages.qmd
    Распечатка 10: _quarto.yml
  • В выводе LaTeX для частей используется команда \part.

2.8 Приложения

  • Можно включить приложения, добавив ключ appendices:
    book:
  chapters:
​    - index.qmd
​    - intro.qmd
​    - summary.qmd
​    - references.qmd
  appendices:
​    - tools.qmd
​    - resources.qmd
    Распечатка 11: _quarto.yml
  • Приложения нумеруются с использованием заглавных букв и имеют префикс, вставленный в их заголовок, чтобы указать, что они являются приложением (например, «Приложение A — Дополнительные ресурсы»).
  • Можно настроить префикс и разделитель:
    crossref:
  appendix-title: "App."
  appendix-delim: ":"
    Распечатка 12: _quarto.yml

2.9 Навигация по странице

  • Если у вас есть книга с несколькими страницами в разделе или подразделе, часто бывает удобно предложить пользователю возможность перейти на следующую страницу (или предыдущую страницу) в нижней части страницы, которую он только что закончил читать.
  • Это можно включить это с помощью:
    book:
  page-navigation: true
    Распечатка 13: _quarto.yml
  • При включении навигация по страницам будет отображаться внизу страницы, когда есть следующая или предыдущая страница (включая следующий или предыдущий раздел).
  • Эта опция включена по умолчанию для книг, но не для веб-сайтов.

2.10 Нижний колонтитул страницы

  • Используйте page-footer чтобы предоставить общий нижний колонтитул для всех страниц книги.

  • Самый простой нижний колонтитул просто предоставляет текст, который будет отцентрирован и отображен более светлым шрифтом:

    book:
  page-footer: "Copyright 2021, Norah Jones"
    Распечатка 14: _quarto.yml

  • Можно выделить области нижнего колонтитула по отдельности (left, right, и center):

    book:
  page-footer:
    left: "Copyright 2021, Norah Jones"
    right:
​      - icon: github
        href: https://github.com/
​      - icon: twitter
        href: https://twitter.com/
    Распечатка 15: _quarto.yml

  • Можно использовать параметры background, foreground, border для дальнейшего управления внешним видом нижнего колонтитула.

  • По умолчанию нижний колонтитул не имеет фонового цвета и верхней границы.

  • Чтобы убрать границу, сделайте следующее:

    book:
  page-footer:
    border: false
    Распечатка 16: _quarto.yml

  • Использовать светлый фон (например, чтобы он соответствовал панели навигации):

    book:
  page-footer:
    background: light
    Распечатка 17: _quarto.yml
Science-Writing Markdown
Дмитрий Сергеевич Кулябов
Authors
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности
Мои научные интересы включают физику, администрирование Unix и сетей.