Что я могу контролировать с помощью параметров заголовка YAML в pandoc?

Только случайно я увидел примерный документ с использованием строки toc: true в своих опциях заголовка YAML в файле Markdown, который будет обрабатываться Pandoc. И Pandoc docs не упоминал эту опцию для управления оглавлением с использованием заголовка YAML. Кроме того, я вижу несколько произвольных строк в примерах документов на том же сайте Pandoc readme.

Основной вопрос:

Какие параметры Pandoc доступны с помощью заголовка YAML?

мета-вопрос:

Что определяет доступные параметры Pandoc, которые можно установить с помощью заголовка YAML?

Примечание: мой рабочий процесс - использовать файлы Markdown (.md) и обрабатывать их через Pandoc для получения файлов PDF. Он имеет иерархически организованное рукописное письмо с математикой. Например:

pandoc --standalone --smart \
    --from=markdown+yaml_metadata_block \
    --filter pandoc-citeproc \
    my_markdown_file.md \
    -o my_pdf_file.pdf

Ответ 1

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

Шаблоны Pandoc могут содержать переменные. Например, в своем HTML-шаблоне вы можете написать:

<title>$title$</title>

Эти переменные шаблона могут быть установлены с помощью опции --variable KEY[=VAL].

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

опция --metadata KEY[=VAL],
блок метаданных YAML или
опция --metadata-file.

Опции --variable дословно вставляют строки в шаблон, а --metadata экранирует строки. Строки в метаданных YAML (также при использовании --metadata-file) интерпретируются как уценка, которую можно обойти, используя уценку pandoc универсальные необработанные атрибуты. Например, для вывода HTML:

'<script>alert()</script>'{=html}

См. эту таблицу для схемы:

|                        | --variable        | --metadata        | YAML metadata and --metadata-file |
|------------------------|-------------------|-------------------|-----------------------------------|
| values can be…         | strings and bools | strings and bools | also YAML objects and lists       |
| strings are…           | inserted verbatim | escaped           | interpreted as markdown           |
| accessible by filters: | no                | yes               | yes                               |

Чтобы ответить на ваш вопрос: шаблон определяет, какие поля в блоке метаданных YAML оказывают влияние. Например, для просмотра латексного шаблона по умолчанию используйте:

$ pandoc -D latex

Чтобы увидеть некоторые переменные, которые автоматически устанавливаются pandoc, см. руководство. Наконец, другие варианты поведения pandoc (такие как расширения уценки и т.д.) Могут быть заданы только в качестве параметров командной строки (кроме случаев использования сценария оболочки).

Ответ 2

Это довольно длинный список, который вы можете просмотреть, запустив man pandoc в командной строке и перейдя в раздел "Переменные, заданные pandoc" в разделе "ШАБЛОНЫ".

В верхней части списка перечислены следующие параметры:

Variables set by pandoc
   Some variables are set automatically by pandoc.  These vary somewhat depending  on  the
   output format, but include metadata fields as well as the following:

   title, author, date
          allow identification of basic aspects of the document.  Included in PDF metadata
          through LaTeX and ConTeXt.  These can be set through a pandoc title block, which
          allows for multiple authors, or through a YAML metadata block:

                 ---
                 author:
                 - Aristotle
                 - Peter Abelard
                 ...

   subtitle
          document subtitle; also used as subject in PDF metadata

   abstract
          document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx

   keywords
          list  of  keywords  to  be  included in HTML, PDF, and AsciiDoc metadata; may be
          repeated as for author, above

   header-includes
          contents specified by -H/--include-in-header (may have multiple values)

   toc    non-null value if --toc/--table-of-contents was specified

   toc-title
          title of table of contents (works only with EPUB and docx)

   include-before
          contents specified by -B/--include-before-body (may have multiple values)

   include-after
          contents specified by -A/--include-after-body (may have multiple values)

   body   body of document

`` `

Ответ 3

Вы можете увидеть документацию pandoc для подсказки: http://pandoc.org/getting-started.html

Но чтобы точно знать, где он будет использоваться, вы можете искать шаблоны источников pandoc: https://github.com/jgm/pandoc-templates

Например, для вывода html5 файл: https://github.com/jgm/pandoc-templates/blob/master/default.html5

Здесь раздел кода:

<title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>

Как видите, он имеет title-prefix и pagetitle.

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