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
. - Пример:
# Title f This is `file-f.md`. ## Subtitle f ```{.include} >> equivalent to {.include shift-heading-level-by=2} file-a.md ``` ```{.include shift-heading-level-by=1} >> force shift to be 1 file-a.md ```
1.1.4 Форматы
- По умолчанию предполагается, что файлы написаны в формате Markdown.
- При необходимости включить файлы, написанные в другом формате, альтернативный формат может быть указан через атрибут
format
. - Принимаются только текстовые форматы.
1.1.5 Пример
- Предположим, мы пишем длинный документ, например диссертацию.
- Каждая глава и раздел приложения находятся в отдельном файле.
- Основной файл —
main.md
:--- author: me title: Thesis --- # Frontmatter Thanks everyone! <!-- actual chapters start here --> ``` {.include} chapters/introduction.md chapters/methods.md chapters/results.md chapters/discussion.md ``` # Appendix More info goes here. ``` {.include shift-heading-level-by=1} // headings in included documents are shifted down a level, // a level 1 heading becomes level 2. appendix/questionaire.md ```
- Например, html можно создать с помощью этой команды:
pandoc --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
::::{include=file.md shift=n} This text is optional and will be replaced by the content of file.md. Section title levels are shifted by n (0 if not specified). :::