Шаблоны и переменные Pandoc

Все примеры расположены в репозитории.

При генерации целого документа (параметр -s) Pandoc выводит данные в шаблон. Для каждого выходного формата шаблоны разные. Чтобы посмотреть шаблон используйте команду

Например

Читать далее Шаблоны и переменные Pandoc

Способы добавления метаданных в документ Pandoc

Pandoc позволяет добавить метеоданные к документу несколькими способами. Рассмотрим три из них:

  1. Параметры;
  2. YAML блок;
  3. Файл с метаданными.

Эти три способа могут применяться одновременно. В этом случае параметры будут перетирать друг друга. Начнем с самого низко-приоритетного файла с метаданными. Все примеры зафиксированы в репозитории.

Файл с метаданными

Файл с метаданными, это обычный yaml файл, такой как metadata.yaml:

При запуске имя файла передаётся в параметре --metadata-file:

Читать далее Способы добавления метаданных в документ Pandoc

Опции Pandoc: file-scope, preserve-tabs, tab-stop

Рассмотрим несколько параметров Pandoc. Все примеры зафиксированы в репозитории.

file-scope

Существует два способа конвертации одного документа из нескольких файлов:

  • сначала соединить все файлы в один, а потом конвертировать
  • конвертировать все файлы по отдельности, а потом соединить.

По умолчанию Pandoc использует первый вариант.

Например, если отдельные файлы будут содержать дублирующиеся номера примечаний то Pandoc выдаст предупреждение.

Читать далее Опции Pandoc: file-scope, preserve-tabs, tab-stop

Объединение ячеек в таблицах VuePress

Стандартные MD-таблицы в VuePress не поддерживают объединение ячеек. Эту функцию можно добавить плагином markdown-it-multimd-table, он соедержит следующие возможности:

  • Объединение ячеек по горизонтали;
  • Объединение ячеек по вертикали;
  • Разделение ячеек;
  • Сложные заголовки у таблиц;
  • Пропуск заголовка у таблиц;
  • Блочный контент внутри ячеек, такой как списки, код и др.

Рассмотрим установку и работу этого плагина. За основу возьмем HelloWorld проект. Полная версия примера размещена в этом репозитории.

Сначала, включим плагин в скрипт установки 01_CreateProject.bat:

Читать далее Объединение ячеек в таблицах VuePress

Плагин VuePress для отображения формул vuepress-plugin-katex

Плагин vuepress-plugin-katex основан на плагине markdown-it-texmath который использует для рендера формул KaTeX (Аналог MathJax).

Рассмотрим установку и работу этого плагина. За основу возьмем HelloWorld проект. Полная версия примера размещена в этом репозитории.

Сначала, включим плагин в скрипт установки 01_CreateProject.bat:

Читать далее Плагин VuePress для отображения формул vuepress-plugin-katex

Добавляем favicon в VuePress

Будем использовать рекомендации из этой статьи по добавлению favicon в современных форматах.

За основу возьмем HelloWorld проект. Полная версия примера размещена в этом репозитории.

При генерации сайта VuePress берет файлы из каталога docs\.vuepress\public. Там мы и будем размещать файлы иконок. Нам нужно 4 файла, разместим их следующим образом:

  • Прямо в каталоге public поместим favicon.ico размером 32x32.
  • В каталоге public\assets\favicons разместим

Читать далее Добавляем favicon в VuePress

Плагины VuePress back-to-top и reading-progress

Рассмотрим установку и работу плагинов plugin-back-to-top и plugin-reading-progress.

За основу возьмем HelloWorld проект. Полная версия примера размещена в этом репозитории.

back-to-top

Плагин добавляет кнопку которая скролит страницу наверх. Кнопка появляется только если страницы прокручена по вертикали.

Для установки добавляем команду в скрипт создания проекта 01_CreateProject.bat:

Читать далее Плагины VuePress back-to-top и reading-progress

Отладка ошибок конвертации в Pandoc

Рассмотрим способы получения информации об ошибка при конвертации файлов через Pandoc. Все примеры расположены в репозитории.

Попробуем конвертировать md-файл в html:

Появляется предупреждение:

Файл всё равно будет конвертирован. Причем pandoc завершит работу без кода ошибки. Если нужно чтобы в случае предупреждения код ошибки был не равен 0, то используйте команду --fail-if-warnings:

Результатом будет:

Код ошибки 3 — специальный код ошибки для предупреждений.

Читать далее Отладка ошибок конвертации в Pandoc