Pandoc. Фильтры. Включение файлов

Включение файлов в другие файлы.

1 Включения других файлов в документ

• Основные варианты:
  • рекурсивное включение;
  • абсолютное включение.
• Рекурсивное включение:
  • Пусть файл a/b.md подключается из основного документа.
  • Файл a/b.md в свою очередь подключает файл a/b/c.md.
  • В этом случае используется относительный путь b/c.md.
  • То же самое касается путей к изображениям и путей к файлам кодовых блоков с использованием фильтра include-code-files.
• Абсолютное включение:
  • Как в LaTeX.

1.1 include-files

• Репозиторий: https://github.com/pandoc/lua-filters.
• Язык реализации: Lua.
• Рекурсивное включение.

1.1.1 Особенности

• Не запускайте другие фильтры перед выполнением include-files.
• Выполнение большинства фильтров без предварительного использования include-files приведёт к тому, что другой фильтр увидит пустой блок кода.

1.1.2 Применение

• Используйте include для включения файлов того же формата, что и входные данные.
• Использование оформляется в виде директивы класса.
• Каждая строка кода обрабатывается как имя файла, анализируется, и результат добавляется в документ.
• Метаданные из включенных файлов отбрасываются.
• Строки комментариев начинаются с символов //.

1.1.3 Смена заголовков

• По умолчанию вложенные документы включаются без изменений.
• Иногда удобно изменить уровень заголовков.
• Ручное переключение: используйте атрибут shift-heading-level-by для управления сдвигом заголовка.
• Автоматическое переключение: добавьте метаданные -M include-auto, чтобы включить автоматическое смещение. Не указывайте shift-heading-level-by.
• Пример:

   1# Title f
   2
   3This is `file-f.md`.
   4
   5## Subtitle f
   6
   7```{.include} >> equivalent to {.include shift-heading-level-by=2}
   8file-a.md
   9```
  10
  11```{.include shift-heading-level-by=1} >> force shift to be 1
  12file-a.md
  13```
  

1.1.4 Форматы

• По умолчанию предполагается, что файлы написаны в формате Markdown.
• При необходимости включить файлы, написанные в другом формате, альтернативный формат может быть указан через атрибут format.
• Принимаются только текстовые форматы.

1.1.5 Пример

• Предположим, мы пишем длинный документ, например диссертацию.
• Каждая глава и раздел приложения находятся в отдельном файле.
• Основной файл — main.md:

   1---
   2author: me
   3title: Thesis
   4---
   5
   6# Frontmatter
   7
   8Thanks everyone!
   9
  10<!-- actual chapters start here -->
  11
  12``` {.include}
  13chapters/introduction.md
  14chapters/methods.md
  15chapters/results.md
  16chapters/discussion.md
  17```
  18
  19# Appendix
  20
  21More info goes here.
  22
  23``` {.include shift-heading-level-by=1}
  24// headings in included documents are shifted down a level,
  25// a level 1 heading becomes level 2.
  26appendix/questionaire.md
  27```
  

• Например, html можно создать с помощью этой команды:

  1pandoc --lua-filter=include-files.lua main.md --output result.html
  

1.2 panda

• Репозиторий: https://github.com/CDSoft/panda.
• Документация: http://christophe.delord.free.fr/panda/.
• Язык реализации: Lua.
• Абсолютное включение.

1.2.1 Особенности

• Включение как блок div.
• Включаемый файл может быть в другом формате.
• Если блок задаёт входной формат как класс, файл анализируется в соответствии с этим форматом.

1.2.2 Смена заголовков

• По умолчанию вложенные документы включаются без изменений.
• Иногда удобно изменить уровень заголовков.
• Ручное переключение: используйте атрибут shift=n для управления сдвигом заголовка.
• По умолчанию n = 0.

1.2.3 Пример

• Содержимое файла анализируется в соответствии с его форматом и заменяет содержимое блока div:

  1:::{include=file.md shift=n}
  2This text is optional and will be replaced by the content of file.md.
  3Section title levels are shifted by n (0 if not specified).
  4:::